Managing Claude Code Meta

1. CLAUDE.md is for main agent behaviour CLAUDE.md defines the main agent's role: conversing with users, delegating to sub-agents, and following the promode methodology. It does NOT contain project-specific technical details — those belong in AGENT_ORIENTATION.md.

2. Sub-agents use phase-specific agents Claude Code sub-agents don't inherit CLAUDE.md. Promode provides phase-specific agents (implementer, reviewer, debugger) with the methodology baked in. Main agents handle brainstorming, planning, and orchestration directly, then delegate execution to the appropriate phase agent.

3. AGENT_ORIENTATION.md is the agent knowledge graph Each package/directory can have an AGENT_ORIENTATION.md with compact, token-efficient guidance for agents. This is distinct from README.md (which is for humans). Agents read these just-in-time when working in that area.

4. Tests are the documentation Long-lived markdown should cover architecture and principles only. Detailed behaviour documentation belongs in executable tests. If behaviour isn't tested, it's not guaranteed.

5. CLAUDE.md is standardised The standard CLAUDE.md (standard/MAIN_AGENT_CLAUDE.md) should be copied exactly into projects. It is designed to work universally. All project-specific content belongs in AGENT_ORIENTATION.md.

1. Install — Set up promode in a new project (no existing CLAUDE.md)
2. Update — Update an existing promode installation to the latest version
3. Migrate — Refactor a non-promode CLAUDE.md, moving content to AGENT_ORIENTATION.md
4. Audit — Check if a project follows progressive disclosure principles

Wait for response before proceeding.

Intent-based routing:

• "set up CLAUDE.md", "add agent config", "install promode" → workflows/install.md
• "update promode", "get latest", "upgrade", "update CLAUDE.md" → workflows/update.md
• "CLAUDE.md is too big", "slim down", "refactor existing" → workflows/migrate.md
• "is this right?", "check conformance", "audit" → workflows/audit.md

Key distinction:

• Install = No promode yet, start fresh
• Update = Promode exists, bring to latest version and ensure all components present
• Migrate = Has CLAUDE.md but it's not promode (contains project-specific content)
• Audit = Read-only check, no modifications

After reading the workflow, follow it exactly.

Sub-agents: Main agents delegate execution to phase-specific agents (implementer, reviewer, debugger), which already know the methodology. Brainstorming, planning, and orchestration are done by the main agent.

Promode project structure:

project/
├── CLAUDE.md              # Main agent behaviour (promode methodology)
├── KANBAN_BOARD.md        # Project tracking across sessions
├── AGENT_ORIENTATION.md   # Compact agent guidance (tools, patterns, gotchas)
├── .mcp.json              # MCP server configuration
├── README.md              # Human documentation (optional, for GitHub etc)
└── packages/
    └── {package}/
        └── AGENT_ORIENTATION.md  # Package-specific agent guidance

Required:

• CLAUDE.md — exact copy of standard/MAIN_AGENT_CLAUDE.md
• KANBAN_BOARD.md — project tracking across sessions
• AGENT_ORIENTATION.md — compact agent guidance at project root
• .mcp.json — MCP servers configured (context7, exa, grep_app)

Recommended:

• Package AGENT_ORIENTATION.md files for domain-specific context
• LSP configured for detected languages
• Tests document system behaviour, not markdown files
• README.md exists for humans (GitHub, etc) but is not agent-oriented