Skip to content

AGENT_INSTRUCTIONS.md

Latest commit

 

History

History
162 lines (123 loc) · 5.3 KB

AGENT_INSTRUCTIONS.md

File metadata and controls

162 lines (123 loc) · 5.3 KB
Raw

Agent Instructions: Dual-Mode Operation

Overview

The Claude Code Agents system operates in two distinct modes:

  • Demo Mode: Uses .demo folder with mocked data for testing and demonstration
  • Real Mode: Uses root project folders for actual project development

Critical Rules for Agents

1. Always Update Both Worlds

When making changes to the agent system, you MUST update both:

  • Templates (.templates/): Clean template files without data
  • Demo (.demo/): Mocked data versions for demonstration

2. File Location Mapping

Demo Mode (Dashboard demo_mode: true)

  • Agent Prompts: .demo/.claude/agents/
  • Planning Files: .demo/.plan/
  • Test Files: .demo/tests/
  • Orchestrator: .demo/CLAUDE.md

Real Mode (Dashboard demo_mode: false)

  • Agent Prompts: .claude/agents/
  • Planning Files: .plan/
  • Test Files: tests/
  • Orchestrator: CLAUDE.md (root)

3. Dashboard Behavior

The dashboard must:

  • Demo Mode: Watch and write files in .demo/ folder structure
  • Real Mode: Watch and write files in root folder structure
  • Mode Detection: Check demo_mode configuration to determine file paths

4. Template vs Demo vs Real Differences

Templates (.templates/)

  • Clean files with placeholder data
  • Use YYYY-MM-DDTHH:mm:ss.sssZ for timestamps
  • Use example/placeholder values
  • No actual project data

Demo (.demo/)

  • Realistic mocked data for demonstration
  • Actual timestamps and realistic values
  • Sample learnings, tasks, and agent interactions
  • Simulates a working project environment

Real (Root folders)

  • Actual project data
  • Real timestamps and values
  • Actual learnings, tasks, and agent interactions
  • Production environment

5. Agent Development Workflow

When updating agent prompts or system files:

  1. Update Templates: Make changes to .templates/ files first
  2. Update Demo: Copy changes to .demo/ with mocked data
  3. Update Documentation: Reflect changes in README and system docs
  4. Test in Demo: Verify functionality works with demo data
  5. Deploy to Real: System ready for real project deployment

6. File Synchronization Rules

Agent Prompts

  • Source: agents/ (current working versions)
  • Template: .templates/agents/ (clean templates)
  • Demo: .demo/.claude/agents/ (demo versions)
  • Real: .claude/agents/ (deployed versions)

Planning Files

  • Template: .templates/.plan/ (clean templates)
  • Demo: .demo/.plan/ (with mocked data)
  • Real: .plan/ (actual project data)

Orchestrator

  • Template: .templates/CLAUDE.md.template (clean template)
  • Demo: .demo/CLAUDE.md (with demo configuration)
  • Real: CLAUDE.md (actual project orchestrator)

7. Dashboard Configuration

The dashboard must detect mode and adjust file paths:

const getFilePath = (relativePath) => {
  const baseDir = config.demo_mode ? '.demo' : '.';
  return path.join(baseDir, relativePath);
};

// Examples:
// Demo: .demo/.plan/tasks/index.json + .demo/.plan/tasks/<task_id>.json
// Real: .plan/tasks/index.json + .plan/tasks/<task_id>.json

8. Agent Prompt Updates

When Agent-Improver updates agent instructions:

  • Demo Mode: Update .demo/.claude/agents/[agent].md
  • Real Mode: Update .claude/agents/[agent].md
  • Always: Log changes in appropriate agent_changes.json

9. Learning Management

When Learner manages learnings:

  • Demo Mode: Update .demo/.plan/learnings.json
  • Real Mode: Update .plan/learnings.json
  • Always: Maintain proper schema and validation

10. Quality Assurance

Before committing changes:

  • Templates updated with clean structure
  • Demo folder updated with mocked data
  • File paths correctly mapped for both modes
  • Dashboard configuration supports both modes
  • Documentation reflects dual-mode operation
  • No cross-contamination between demo and real data

Implementation Checklist

For System Updates

  • Update .templates/ with clean versions
  • Update .demo/ with mocked data versions
  • Update agent prompts in both locations
  • Update orchestrator in both locations
  • Test dashboard in both modes
  • Verify file path resolution
  • Update documentation

For New Features

  • Design template structure
  • Create demo data examples
  • Update dashboard to handle both modes
  • Add mode-specific file path logic
  • Test feature in both environments
  • Document mode-specific behavior

Error Prevention

Common Mistakes to Avoid

  1. Single Mode Updates: Only updating templates OR demo
  2. Wrong File Paths: Using hardcoded paths instead of mode-aware paths
  3. Data Contamination: Mixing real data in demo or vice versa
  4. Missing Synchronization: Forgetting to update all three locations
  5. Mode Detection Failure: Dashboard not properly detecting mode

Validation Steps

  1. Check both .templates/ and .demo/ are updated
  2. Verify file paths resolve correctly in both modes
  3. Test dashboard functionality in both modes
  4. Confirm no real data in demo files
  5. Ensure templates remain clean and generic

Remember: The goal is seamless operation in both demo (for testing/presentation) and real (for actual projects) environments while maintaining clear separation and proper data handling.