managing-claude-code-meta

name

description

MUST be loaded when setting up, installing, migrating, reviewing, auditing, or checking CLAUDE.md files in projects. Covers installing the promode CLAUDE.md into new projects, migrating existing CLAUDE.md content to AGENT_ORIENTATION.md (progressive disclosure), and auditing projects for conformance. Invoke PROACTIVELY when user mentions CLAUDE.md, project setup, agent configuration, or code meta files.

This skill manages projects that adopt the **promode methodology** — a set of principles and workflows for AI agents to develop software. The methodology emphasises TDD, context conservation, progressive disclosure, and clear delegation patterns.

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.

- NEVER modify `standard/MAIN_AGENT_CLAUDE.md` content — it must be copied exactly into projects - NEVER add project-specific content to CLAUDE.md (use AGENT_ORIENTATION.md instead) - NEVER duplicate content between CLAUDE.md and AGENT_ORIENTATION.md — single source of truth - NEVER skip verifying CLAUDE.md matches the standard after installation or migration Stop and ask the user when: - Project is not under git version control or has uncommited changes - Content doesn't fit KEEP/MOVE/DELETE categories during migration - Existing AGENT_ORIENTATION.md conflicts with the suggested structure - You've attempted the same step 3+ times without success - Changes would affect more than 10 files What would you like to do?

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

Wait for response before proceeding.

| Response | Next Action | Workflow | |----------|-------------|----------| | 1, "install", "setup", "new", "create" | Confirm project path | workflows/install.md | | 2, "update", "upgrade", "latest", "refresh" | Check existing installation | workflows/update.md | | 3, "migrate", "refactor", "move", "convert" | Analyze existing CLAUDE.md | workflows/migrate.md | | 4, "audit", "check", "review", "assess" | Scan project structure | workflows/audit.md |

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.

**CLAUDE.md**: Copy `standard/MAIN_AGENT_CLAUDE.md` exactly. Do not modify. This configures the main agent with promode methodology.

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

- `standard/MAIN_AGENT_CLAUDE.md` — The canonical CLAUDE.md (copy exactly into projects) - `references/progressive-disclosure.md` — Why and how to distribute content to AGENT_ORIENTATION.md All in `workflows/`:

Workflow	Purpose
install.md	Install promode into new project
update.md	Update existing promode installation to latest version
migrate.md	Migrate non-promode CLAUDE.md content to AGENT_ORIENTATION.md
audit.md	Audit project for progressive disclosure conformance

A well-configured project has these components:

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

managing-claude-code-meta

Install Skill

SKILL.md