A comprehensive framework that transforms Claude Code instances into Project Manager (PM) that orchestrate work through specialized subagents while maintaining complete documentation, preventing repeated mistakes, and enabling continuous improvement.
This repository provides the complete specification, templates, and automation tools for implementing a PM Orchestration System with Claude Code CLI. It defines how an AI assistant should behave as a project manager—coordinating work, maintaining documentation, and delegating execution to specialized subagents—rather than implementing code directly.
THINK → DOCUMENT → DELEGATE → VERIFY → DOCUMENT → IMPROVE
| Principle | Description |
|---|---|
| Orchestration Only | PM never implements; it coordinates and delegates |
| Documentation First | Nothing happens without being documented |
| Strict Delegation | All implementation goes through specialized subagents |
| Full Autonomy | PM operates independently with minimal user interruption |
| Mistake Prevention | Learn from errors, prevent infinite loops |
| Continuous Improvement | Post-project reviews drive system evolution |
Every project maintains persistent state across sessions:
.pm/
├── MEMORY.md # Project state and architectural context
├── MISTAKES.md # Error patterns and prevention strategies
├── DECISIONS.md # Architecture and design decisions
├── PROGRESS.md # Chronological progress log with metrics
├── IMPROVEMENTS.md # Process improvement ideas from experience
├── SUBAGENT-RULES.md # Rules passed to every subagent delegation
├── CRITICAL.md # Sensitive data (credentials, URLs, commands)
├── INDEX.md # Quick reference and navigation
├── logs/
│ ├── sessions/ # Timestamped session logs with summaries
│ └── agents/ # Per-subagent invocation logs with verification
├── debug/ # Debug session artifacts (organized by issue)
├── tests/ # Test cases, manual reports, automated results
├── reviews/ # Post-milestone and post-project reviews
└── plans/ # Implementation plans and architecture designs
PM delegates all implementation work to specialized agents:
| Agent Type | Model | Use Case |
|---|---|---|
Explore |
haiku | Find files, understand codebase structure |
python-pro |
haiku | Python code implementation |
typescript-pro |
haiku | TypeScript/JavaScript implementation |
backend-architect |
opus | System design, API architecture decisions |
database-architect |
opus | Schema design, data modeling |
security-auditor |
opus | Security review, vulnerability analysis |
debugger |
opus | Bug investigation, root cause analysis |
qa-expert |
opus | Test planning, manual UI testing |
test-automator |
haiku | Run automated test suites |
Bash |
haiku | Shell commands and terminal operations |
Model Selection Rule: Use haiku for execution tasks (fast, cost-effective), opus for complex reasoning (architecture, security, debugging, planning).
Automatic detection and handling of repeated failures:
Attempt 1: Normal delegation with context
Attempt 2: Include MISTAKES.md patterns, add explicit warnings
Attempt 3: MANDATORY update to MISTAKES.md, analyze root cause
Attempt 4+: STOP all work, document analysis, escalate to user
Python scripts for automating common PM operations:
| Tool | Purpose | When to Use |
|---|---|---|
pm-init |
Session initialization, context loading | Every session start |
pm-end |
Session finalization, validation | Every session end |
pm-check |
Health check, detect issues | Before deployment, after errors |
pm-context |
Quick context file loader | Mid-session context refresh |
pm-export-context |
Pre-compaction context export | Auto via PreCompact hook |
pm-recover-context |
Post-compaction recovery | Auto via SessionStart hook |
pm-audit |
PM work quality audit | Auto via pm-end, on demand |
pm-agent-export |
Subagent transcript export | Auto via SubagentStop hook |
pm-classify |
Manage sensitive information | Organize credentials, commands |
Claude-Code-Project-Manager/
├── README.md # This file
├── templates/
│ ├── CLAUDE.md # PM rules → install to ~/.claude/CLAUDE.md
│ ├── .pm/ # Templates for project .pm/ folders
│ │ ├── *.md # Core documentation templates
│ │ ├── logs/ # Log templates (sessions, agents)
│ │ ├── debug/ # Debug artifacts README
│ │ ├── tests/ # Test artifacts README
│ │ └── reviews/ # Review templates
│ └── pm-tools/ # Automation scripts
│ ├── pm-init # Session initialization
│ ├── pm-end # Session finalization
│ ├── pm-check # Health check
│ ├── pm-context # Context loader
│ ├── pm-export-context # Context export (pre-compact)
│ ├── pm-recover-context # Context recovery (post-compact)
│ ├── pm-audit # Quality audit
│ ├── pm-agent-export # Agent transcript export
│ ├── pm-classify # Sensitive data manager
│ └── lib/ # Shared Python libraries
├── docs/
│ ├── PM-ORCHESTRATION-SYSTEM.md # Complete system specification
│ ├── PM-SYSTEM-REPORT.md # System overview and workflow
│ ├── PM-AGENT-CATALOG.md # Complete agent reference guide
│ ├── CLAUDE-CODE-AGENTS-RESEARCH.md # Agent architecture research
│ ├── SKILLS-PLUGINS-AGENTS-GUIDE.md # Skills and plugins documentation
│ ├── IMPLEMENTATION-GUIDE.md # Implementation instructions
│ └── RULES-INTEGRATION-ANALYSIS.md # Rules system analysis
└── .claude/
└── agents/ # Custom PM coordination agents
├── pm-auditor.md # PM quality auditor
├── context-manager.md # Shared state manager
├── agent-organizer.md # Agent selection coordinator
├── task-distributor.md # Work distribution
├── error-coordinator.md # Error handling
├── knowledge-synthesizer.md # Pattern extraction
├── performance-monitor.md # Metrics tracking
├── research-analyst.md # Information gathering
├── technical-writer.md # Documentation generation
├── backend-architect.md # API design
└── database-architect.md # Data modeling
⚠️ WARNING: This will overwrite your existing~/.claude/CLAUDE.mdfile!Before proceeding:
- If you have an existing
~/.claude/CLAUDE.md, back it up first:cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.backup- Or merge this file with your existing rules instead of overwriting
- Recommended: Review
templates/CLAUDE.mdbefore installing to understand what it does
Copy the CLAUDE.md file to your global Claude configuration:
cp templates/CLAUDE.md ~/.claude/CLAUDE.mdThis file contains all the PM orchestration rules that Claude will follow.
Copy the .pm/ templates for use in new projects:
mkdir -p ~/.claude/templates
cp -r templates/.pm ~/.claude/templates/.pmcp -r templates/pm-tools ~/.claude/pm-tools
chmod +x ~/.claude/pm-tools/pm-*Verify installation:
python3 ~/.claude/pm-tools/pm-init --helpmkdir -p ~/.claude/agents
cp .claude/agents/*.md ~/.claude/agents/Add to ~/.claude/settings.json for automatic context preservation:
{
"hooks": {
"PreCompact": [{
"matcher": "",
"hooks": [{
"type": "command",
"command": "python3 ~/.claude/pm-tools/pm-export-context --trigger auto"
}]
}],
"SessionStart": [{
"matcher": "compact",
"hooks": [{
"type": "command",
"command": "python3 ~/.claude/pm-tools/pm-recover-context"
}]
}],
"SubagentStop": [{
"matcher": "*",
"hooks": [{
"type": "command",
"command": "python3 ~/.claude/pm-tools/pm-agent-export --from-hook"
}]
}]
}
}What these hooks do:
- PreCompact: Exports context before conversation compaction (prevents context loss)
- SessionStart: Automatically recovers context after compaction
- SubagentStop: Auto-exports subagent transcripts for review and optimization
# Navigate to your project directory
cd /path/to/your/project
# Initialize PM session
python3 ~/.claude/pm-tools/pm-initThis will:
- Find or create the
.pm/folder in your project - Load all context files (MEMORY, MISTAKES, DECISIONS, etc.)
- Create a new timestamped session log
- Check for common issues (nested folders, incomplete sessions)
- Display loaded context summary
The PM will:
- Document all work in session logs
- Delegate implementation to appropriate subagents
- Verify all subagent output
- Update
.pm/files at every checkpoint - Prevent repeated mistakes using MISTAKES.md
- Track progress in PROGRESS.md
python3 ~/.claude/pm-tools/pm-endThis validates:
- Session log has a complete summary
- Handoff notes are present
- PROGRESS.md metrics are updated
- Reviews are triggered if needed (milestone, incident, completion)
- All documentation checkpoints were completed
If validation fails, fix the issues before ending the session.
python3 ~/.claude/pm-tools/pm-checkDetects:
- Nested or duplicate
.pm/folders (critical bug source!) - Missing required files
- Incomplete session summaries
- Stale metrics
- Large PROGRESS.md files needing archival
# Load specific context files
python3 ~/.claude/pm-tools/pm-context MEMORY MISTAKES
# Load all context files
python3 ~/.claude/pm-tools/pm-context --all
# JSON output (for parsing)
python3 ~/.claude/pm-tools/pm-context --all --format=json# Add credentials
python3 ~/.claude/pm-tools/pm-classify add credential AWS \
--user "admin@example.com" --pass "secret123" \
--notes "Production account"
# Add environment URL
python3 ~/.claude/pm-tools/pm-classify add environment production \
--url "https://app.example.com" \
--notes "Main production site"
# Add command
python3 ~/.claude/pm-tools/pm-classify add command \
"kubectl get pods -n production" \
--category k8s --purpose "Check production pods"
# List all credentials
python3 ~/.claude/pm-tools/pm-classify list credentials
# Search
python3 ~/.claude/pm-tools/pm-classify search "AWS"Once the PM system is installed, here are practical examples of how to interact with it.
In Claude Code CLI:
Start PM session for this project
or
Initialize PM mode - I need help with [your project description]
What happens: The PM will automatically run pm-init, load all context files, and be ready to coordinate work.
I need to implement a user authentication system with JWT tokens.
Requirements:
- Login/logout endpoints
- Token refresh mechanism
- Password hashing with bcrypt
- Protected route middleware
What the PM does:
- Checks MISTAKES.md for auth-related patterns
- Plans the implementation (database schema, API design, middleware)
- Delegates to appropriate subagents (backend-architect, python-pro, security-auditor)
- Creates test plan and delegates to qa-expert
- Documents decisions in DECISIONS.md
- Updates PROGRESS.md after each step
There's a bug where users can't login after password reset. Help me debug this.
Symptoms:
- Password reset email works fine
- New password is saved to database
- Login fails with "Invalid credentials"
- No errors in server logs
What the PM does:
- Delegates to
debuggeragent (opus) for root cause analysis - Documents findings in debug folder:
.pm/debug/YYYY-MM-DD-password-reset-bug/ - Delegates fix to appropriate implementation agent
- Updates MISTAKES.md with the pattern to prevent recurrence
- Delegates test verification to qa-expert
Review the changes in src/api/payments.py for security issues before I deploy
What the PM does:
- Delegates to
security-auditoragent (opus) - Checks for OWASP Top 10 vulnerabilities
- Reviews authentication/authorization logic
- Checks for secrets in code
- Provides detailed security report
- Documents any issues in MISTAKES.md
The UserService class has grown to 800 lines. Help me refactor it into smaller, focused classes.
What the PM does:
- Delegates to
backend-architect(opus) for refactoring plan - Reviews current code structure
- Proposes separation of concerns
- Documents architecture decisions in DECISIONS.md
- Delegates implementation to code agents
- Ensures tests still pass
Run a health check on this project
What the PM does:
- Runs
pm-checkto detect issues - Reports nested .pm/ folders (critical!)
- Checks for incomplete sessions
- Validates file structure
What do we know about this project? Show me the current context.
What the PM does:
- Loads and summarizes MEMORY.md (architecture, key files)
- Shows recent PROGRESS.md entries
- Lists patterns from MISTAKES.md
- Shows open decisions from DECISIONS.md
Before I implement pagination, check if we've had issues with this before
What the PM does:
- Searches MISTAKES.md for pagination-related patterns
- Warns about previous failures
- Provides prevention strategies
- Includes warnings in delegation prompts
Document this decision: We're using Redis for session storage instead of database sessions
Reasoning:
- Better performance for high-traffic scenarios
- Built-in TTL for automatic expiration
- Reduces database load
Trade-offs:
- Additional infrastructure dependency
- Need to handle Redis failures gracefully
What the PM does:
- Adds entry to DECISIONS.md with timestamp
- Documents reasoning and trade-offs
- Notes in MEMORY.md for future reference
Run the full test suite before I deploy to production
What the PM does:
- Delegates to
test-automator(haiku) to run pytest/jest - Reviews test results
- Reports failures with details
- Blocks deployment if critical tests fail
- Updates PROGRESS.md with test results
Test the checkout flow on staging before we deploy to production
URL: https://staging.example.com
Credentials: [from CRITICAL.md]
Test:
- Add items to cart
- Apply discount code
- Complete payment
- Verify order confirmation email
What the PM does:
- Delegates to
qa-expert(opus) with chrome-devtools MCP - Executes test steps using browser automation
- Takes screenshots at each stage
- Reports any issues found
- Saves report to
.pm/tests/YYYY-MM-DD-checkout-test.md
Deploy the current branch to production
Important: Watch for errors and fix any issues immediately
What the PM does:
- Updates all .pm/ files (checkpoint before deployment)
- Delegates deployment to
devops-engineeragent - Monitors for errors
- For each issue found: Documents fix, syncs to local code immediately
- Only marks deployment complete after local matches production
Create API documentation for the new endpoints I just added
What the PM does:
- Delegates to
technical-writeragent - Reviews code and comments
- Generates markdown documentation
- Includes example requests/responses
- Saves to project docs/ folder
We just finished the user authentication feature. Create a milestone review.
What the PM does:
- Creates
.pm/reviews/YYYY-MM-DD-auth-milestone.md - Documents what went well
- Identifies improvements for IMPROVEMENTS.md
- Extracts patterns for MISTAKES.md
- Updates MEMORY.md with architecture learnings
- Records metrics (time spent, tasks completed)
This project is complete. Create a final project review.
What the PM does:
- Creates
.pm/reviews/YYYY-MM-DD-project-complete.md - Full retrospective of entire project
- Comprehensive lessons learned
- Subagent effectiveness analysis
- Process improvements discovered
- Archives PROGRESS.md if needed
The conversation was just compacted. Restore my project context.
What the PM does:
- Automatically runs
pm-recover-context(if hook configured) - Loads most recent context export
- Restores full project understanding
- Displays summary of recovered context
Production is down! The new deployment broke the login system.
I need to:
1. Rollback immediately
2. Find the bug
3. Fix it
4. Redeploy
Help me coordinate this fast.
What the PM does:
- Immediate: Documents the incident start time
- Delegates rollback to
devops-engineer(parallel with investigation) - Delegates root cause analysis to
debugger(opus) - Once bug found: Delegates fix to implementation agent
- Delegates testing to
qa-expert(critical path) - Coordinates redeploy only after tests pass
- Creates incident review:
.pm/reviews/YYYY-MM-DD-login-outage-incident.md - Updates MISTAKES.md with prevention strategy
I'm done for today. End the PM session properly.
What the PM does:
- Runs
pm-endfor validation - Checks session log completeness
- Verifies handoff notes exist
- Updates PROGRESS.md metrics
- Triggers reviews if milestone reached
- Reports any validation failures
Give me a quick summary of where we are in this project
What the PM does:
- Shows current phase from PROGRESS.md
- Lists completed tasks today
- Shows remaining tasks
- Notes any blockers
- Quick metrics (sessions, tasks completed)
Audit the PM work quality from the last 3 sessions
What the PM does:
- Runs
pm-auditon recent session logs - Scores work quality (0-100) across 5 dimensions
- Reports on delegation quality
- Checks MISTAKES.md compliance
- Suggests improvements for PM operations
Export the transcripts from the last debugging session so I can review how the agent approached the problem
What the PM does:
- Finds relevant agent logs in
.pm/logs/agents/ - Exports to human-readable format
- Shows: prompts, responses, tool calls, results
- Useful for optimizing future delegations
I need to build a complex distributed system with microservices.
Coordinate multiple specialized agents:
- backend-architect for overall design
- database-architect for data layer
- security-auditor for auth strategy
- devops-engineer for deployment plan
Make them work together to create a cohesive design.
What the PM does:
- Uses
agent-organizerto select optimal agents - Uses
task-distributorto parallelize work - Uses
context-managerto share state between agents - Synthesizes all outputs into unified design document
- Resolves any conflicts between agent recommendations
- Initialization: PM runs
pm-initand reads all.pm/files to load context - Task Handling: For each user request:
- Parse and understand the task completely
- Check MISTAKES.md for relevant patterns to avoid
- Plan delegation to appropriate subagents
- Create agent logs before each delegation
- Delegate with full context and success criteria
- Verify subagent output against criteria
- Update documentation immediately after each agent completes
- Documentation Checkpoints: Update
.pm/files at every checkpoint:- After each agent returns
- Before asking user questions
- Before long-running commands
- On any error
- When switching task phases
- Session End: Complete session summary, update metrics, trigger reviews
The PM never:
- Writes or edits code files directly
- Writes or edits config files (except
.pm/folder) - Runs build/test/git commands directly
- Creates files outside
.pm/folder - Skips reading context at session start
- Delegates without checking MISTAKES.md first
- Accepts subagent output without verification
- Continues past 3 failed attempts on same task
- Deletes or overwrites logs (audit trail preservation)
- Leaves debug artifacts in
.pm/root (use subfolders)
The PM always:
- Reads all
.pm/*.mdfiles at session start - Creates session log at session start
- Checks MISTAKES.md before every delegation
- Includes full context and warnings in delegations
- Creates agent log for every subagent invocation
- Verifies subagent output against success criteria
- Updates PROGRESS.md after EACH agent completion (not just task end)
- Updates
.pm/files before AskUserQuestion (potential stop point) - Updates MEMORY.md when project understanding changes
- Updates MISTAKES.md on any failure or rework
- Updates DECISIONS.md on any non-trivial decision
- Writes session summary before session end
- Uses TodoWrite for multi-step task tracking
- Syncs deployment fixes to local code (after ANY deployment fix)
Critical Concept: Subagents spawned via the Task tool do NOT automatically inherit CLAUDE.md rules. The PM must explicitly include essential rules in every delegation prompt:
- No AI attribution in code, comments, commits, or documentation
- Use
python3notpythonfor all Python commands - No symlinks—copy files or use canonical paths
- Only do exactly what is asked—no extra features or refactoring
- Verify output compiles/runs before returning
- Match existing code patterns and conventions
These rules are stored in .pm/SUBAGENT-RULES.md and must be included in every delegation.
Problem Solved: Progress loss when sessions are interrupted, compacted, or ended unexpectedly.
Solution: Update .pm/ files at EVERY checkpoint, not just at task or session end.
Checkpoint Triggers:
- After each subagent returns (even if task incomplete)
- Before asking user questions (user interaction = potential stop)
- Before long-running commands (might hang/fail)
- On any error (errors = learning + state change)
- When switching task phases (phase transitions = progress)
- Before deployment (major checkpoint)
Why This Matters: If it's not in .pm/, it didn't happen. Conversation compaction can occur at any time, and documentation must be up-to-date.
Prevents infinite retry loops by tracking attempts and escalating:
Attempt Count: 0
↓
Attempt 1: Normal delegation with context
↓ (if fails)
Attempt 2: Include MISTAKES.md patterns, add explicit warnings
↓ (if fails)
Attempt 3: MANDATORY—Update MISTAKES.md, analyze root cause
↓ (if fails)
Attempt 4+: STOP—Document full analysis, present to user, wait for direction
Problem Solved: Fixes made during deployment not synced back to local code, causing code drift.
Solution: Deployment is NOT complete until local code matches deployed code.
Phases:
- Pre-Deployment: Update all
.pm/files, document current state - Deployment: Deploy code, monitor for issues
- Issue Resolution: For EACH fix made on server:
- STOP and document the fix immediately
- Delegate agent to apply SAME fix to local code
- Verify local code matches server
- Verification: Confirm local matches deployed, update learnings
Problem Solved: PM should NOT do testing directly.
Solution: All testing delegated to specialized agents:
| Phase | Agent | Model | Output |
|---|---|---|---|
| Test Case Design | qa-expert |
opus | .pm/tests/[feature]-test-cases.md |
| Manual/UI Testing | qa-expert |
opus | .pm/tests/[date]-manual-report.md |
| Automated Testing | test-automator |
haiku | .pm/tests/[date]-automated-report.md |
PM orchestrates testing, verifies reports, and documents results—but never executes tests directly.
| Role | Model | Purpose | Cost Optimization |
|---|---|---|---|
| PM Agent | Opus 4.5 | Orchestration, judgment, verification, decision-making | One PM per session |
| Complex Subagents | Opus | Architecture, security, debugging, test planning | Only when reasoning needed |
| Execution Subagents | Haiku | Code writing, commands, file operations, test execution | Default for implementation |
Cost Strategy: PM uses Opus for high-level coordination, delegates most work to efficient Haiku agents, reserves Opus subagents for complex reasoning tasks only.
| Document | Purpose |
|---|---|
| PM-ORCHESTRATION-SYSTEM.md | Complete system specification with all protocols |
| PM-SYSTEM-REPORT.md | System overview, workflow, and architecture |
| PM-AGENT-CATALOG.md | All available agents, tools, capabilities, when to use |
| CLAUDE-CODE-AGENTS-RESEARCH.md | Deep research on Claude Code agent architecture |
| SKILLS-PLUGINS-AGENTS-GUIDE.md | Guide on skills, plugins, and custom agent creation |
| IMPLEMENTATION-GUIDE.md | Step-by-step implementation instructions |
| templates/CLAUDE.md | The actual PM rules file to install globally |
| templates/pm-tools/README.md | Detailed pm-tools documentation and examples |
- Never repeat the same mistake twice
- Complete project history across sessions
- Zero context loss during conversation compaction
- Systematic approach to complex problems
- Self-documenting projects
- Standardized project documentation
- Knowledge transfer through
.pm/folders - Consistent quality across projects
- Post-project reviews drive team learning
- Audit trail for all decisions
- Training data generation from successful patterns
- Systematic error prevention
- Quality metrics and monitoring
- Process improvement through reviews
- Reproducible development workflows
The hook system automatically preserves context when Claude Code compacts conversations:
- Before compaction:
pm-export-contextsaves full context to JSON and markdown - After compaction:
pm-recover-contextrestores context to new conversation - Result: Zero information loss, seamless continuation
The pm-audit tool scores PM work quality (0-100) across 5 dimensions:
- Session log quality (summary, handoff notes, completeness)
- MISTAKES.md compliance (patterns followed, prevention applied)
- Agent log quality (verification done, lessons extracted)
- Documentation checkpoints (files updated at right times)
- Delegation quality (context provided, criteria clear)
Run automatically by pm-end or manually:
python3 ~/.claude/pm-tools/pm-audit --verboseEvery subagent invocation is logged and can be exported for analysis:
- Auto-exported via
SubagentStophook - Saved to
.pm/logs/agents/[timestamp]-[type]-[id].txt - Includes prompts, responses, tool calls, results
- Useful for optimizing delegation prompts and identifying patterns
For deep review at milestones or on demand:
# Delegate to pm-auditor agent (uses opus model)
# Reviews PM decisions, delegation effectiveness, documentation accuracy
# Identifies patterns for MISTAKES.md and improvements for IMPROVEMENTS.mdThe pm-auditor agent provides independent review of PM work quality, not just automated checks.
This project was developed using its own PM system. To contribute:
- Fork the repository
- Install the PM system (follow Installation above)
- Create a
.pm/folder in your fork for your changes - Use PM mode for all development work
- Include your
.pm/folder in pull requests (shows decision process)
- Claude Code CLI (latest version)
- Python 3.8+ (for pm-tools scripts)
- Unix-like OS (macOS, Linux) or WSL on Windows
This project is documentation and tooling for personal use with Claude Code CLI. Feel free to use, modify, and adapt for your own projects.
Developed through iterative collaboration between human user and Claude Code CLI, demonstrating the PM Orchestration System in practice. The system evolved through multiple sessions, documented in the original .pm/ folder (removed for privacy).
Version: 1.0 Last Updated: 2026-02-11 Status: Production Ready