# CCPM (Claude Code Project Manager) - Deep Dive

> **TL;DR**: CCPM is a project management system that turns your ideas into GitHub Issues and lets multiple AI agents work on them simultaneously. It solves the "AI forgets everything between sessions" problem and makes AI-assisted development actually scale.

---

## The Problem CCPM Solves

Picture this scenario:

1. You have a great conversation with Claude about building a feature
2. You close your laptop, go to bed
3. Next morning, Claude has *no idea* what you talked about
4. You spend 20 minutes re-explaining everything
5. Repeat forever

**This is the "context problem"** - and it's killing AI-assisted development productivity.

But there's an even bigger issue: **AI development is a silo.** One developer, one AI, working in isolation. Your teammates can't see what the AI is doing. The AI can't coordinate with other AI agents. Everything lives in a single conversation that nobody else can access.

**CCPM's solution**: Use GitHub Issues as the brain that never forgets, and Git worktrees to let multiple agents work in parallel without stepping on each other.

---

## The Core Philosophy: No "Vibe Coding"

CCPM rejects what it calls "vibe coding" - development based on:
- "I think we discussed this last week..."
- "The AI probably remembers..."
- "Let me just quickly add this feature..."

Instead, it enforces **spec-driven development**:

> "Every line of code must trace back to a specification. No shortcuts. No assumptions. No regrets."

This means:
- Every feature starts as a written Product Requirements Document (PRD)
- PRDs become technical Epics with architecture decisions
- Epics break down into Tasks with acceptance criteria
- Tasks become GitHub Issues
- Code commits reference specific Issues
- Everything is traceable end-to-end

---

## How It Works: The Five Phases

```
┌─────────────────────────────────────────────────────────────────────────┐
│                        THE CCPM WORKFLOW                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  📝 BRAINSTORM    →    📋 DOCUMENT    →    🏗️ PLAN                      │
│  /pm:prd-new           (PRD created)       /pm:prd-parse                │
│                                                                          │
│         ↓                                                                │
│                                                                          │
│  📊 DECOMPOSE     →    🔄 SYNC         →    ⚡ EXECUTE                   │
│  /pm:epic-decompose    /pm:epic-sync       /pm:issue-start              │
│                        (GitHub Issues)     (Parallel agents!)           │
│                                                                          │
│         ↓                                                                │
│                                                                          │
│  ✅ MERGE & CLOSE                                                        │
│  /pm:epic-merge                                                          │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
```

### Phase 1: Brainstorm (`/pm:prd-new`)

You describe what you want. CCPM guides you through a structured brainstorming session:

- What's the vision?
- Who are the users?
- What are the success criteria?
- What are the constraints?

**Output**: A Product Requirements Document (PRD) saved in `.claude/prds/`

### Phase 2: Document → Plan (`/pm:prd-parse`)

CCPM transforms your PRD into a technical implementation plan:

- Architectural decisions
- Dependency mapping
- Technology choices
- Risk identification

**Output**: A technical Epic with clear boundaries

### Phase 3: Decompose (`/pm:epic-decompose`)

Break the Epic into concrete, actionable tasks:

- Each task has acceptance criteria
- Effort estimates
- Dependencies identified
- Parallelization opportunities flagged

**Output**: A list of tasks ready to become GitHub Issues

### Phase 4: Sync to GitHub (`/pm:epic-sync` or `/pm:epic-oneshot`)

Push everything to GitHub:

- Epic becomes a parent Issue
- Tasks become linked Issues
- Labels applied automatically
- Relationships preserved

**Output**: Your project is now visible to everyone

### Phase 5: Execute (`/pm:issue-start`)

This is where the magic happens. CCPM launches **specialized agents** to work on tasks:

- Each agent gets its own Git worktree (isolated workspace)
- Agents work in parallel without conflicts
- Progress syncs to GitHub Issues in real-time
- Your main conversation stays clean and strategic

---

## The Parallel Execution Breakthrough

Traditional approach:
```
You → Claude → Work on Task 1 → Finish → Work on Task 2 → Finish → ...
                    (linear, slow)
```

CCPM approach:
```
You (Conductor)
     ↓
     ├── Agent 1 → Task 1 (worktree-1) ──┐
     ├── Agent 2 → Task 2 (worktree-2) ──┼── All happening
     ├── Agent 3 → Task 3 (worktree-3) ──┤   simultaneously!
     └── Agent 4 → Task 4 (worktree-4) ──┘
                    ↓
              /pm:epic-merge
                    ↓
            Clean, unified codebase
```

**Why this matters**: A single issue like "Implement user authentication" isn't one task. It's actually:

| Sub-task | Can Run In Parallel? |
|----------|---------------------|
| Database schema changes | ✅ Yes |
| Service layer logic | ✅ Yes |
| API endpoints | ✅ Yes (after service) |
| UI components | ✅ Yes |
| Test suites | ✅ Yes |

CCPM recognizes this and spawns agents for each parallelizable piece.

---

## The Command System

CCPM provides 40+ slash commands organized by function:

### PRD Commands (Product Planning)
| Command | What It Does |
|---------|--------------|
| `/pm:prd-new` | Start brainstorming a new feature |
| `/pm:prd-parse` | Convert PRD to technical Epic |
| `/pm:prd-list` | Show all PRDs |
| `/pm:prd-edit` | Modify existing PRD |
| `/pm:prd-status` | Check PRD progress |

### Epic Commands (Implementation Planning)
| Command | What It Does |
|---------|--------------|
| `/pm:epic-decompose` | Break Epic into tasks |
| `/pm:epic-sync` | Push to GitHub Issues |
| `/pm:epic-oneshot` | Decompose + sync in one step |
| `/pm:epic-show` | Display Epic details |
| `/pm:epic-close` | Mark Epic complete |

### Issue Commands (Execution)
| Command | What It Does |
|---------|--------------|
| `/pm:issue-start` | Launch agent on a task |
| `/pm:issue-sync` | Push progress updates |
| `/pm:issue-close` | Complete a task |
| `/pm:issue-status` | Check task status |

### Workflow Commands (Coordination)
| Command | What It Does |
|---------|--------------|
| `/pm:next` | Get highest priority task |
| `/pm:status` | Dashboard view of all work |
| `/pm:standup` | Generate standup summary |
| `/pm:blocked` | Show blocked tasks |
| `/pm:in-progress` | Show active work |

### Context Commands (Knowledge Management)
| Command | What It Does |
|---------|--------------|
| `/context:create` | Build project documentation |
| `/context:update` | Refresh after changes |
| `/context:prime` | Load context into session |

---

## The Directory Structure

CCPM organizes everything in your `.claude/` folder:

```
.claude/
├── prds/                    # Product Requirement Documents
│   └── user-auth.md         # Example: authentication feature
├── epics/                   # Local implementation plans (git-ignored)
│   └── user-auth/
│       ├── plan.md          # Technical architecture
│       └── tasks.md         # Decomposed tasks
├── agents/                  # Specialized agent definitions
│   ├── ui-agent.md          # Frontend specialist
│   ├── api-agent.md         # Backend specialist
│   └── test-agent.md        # Testing specialist
├── commands/                # Slash command definitions
│   └── pm/                  # Project management commands
│       ├── prd-new.md
│       ├── epic-sync.md
│       └── ...
└── context/                 # Shared project knowledge
    ├── architecture.md
    ├── dependencies.md
    └── patterns.md
```

**Key insight**: The `epics/` folder is git-ignored. It's your local workspace. GitHub Issues are the source of truth that everyone (humans and AI agents) can see.

---

## Why GitHub Issues?

You might wonder: "Why not use Jira? Or Linear? Or Notion?"

CCPM's answer: **GitHub is where your code already lives.**

Benefits of GitHub as the "database":

| Benefit | How It Helps |
|---------|--------------|
| **True collaboration** | Multiple Claude instances work simultaneously |
| **Real-time visibility** | Humans see AI progress in issue comments |
| **Seamless handoffs** | AI starts work, human finishes (or vice versa) |
| **No new tools** | Teams already use GitHub |
| **Complete history** | Comments provide full audit trail |
| **API access** | Automation can read/write programmatically |

---

## Installation

**Unix/Linux/macOS:**
```bash
# Option 1: One-liner
curl -sSL https://automaze.io/ccpm/install | bash

# Option 2: Manual
bash install/setup.sh
```

**Windows (PowerShell):**
```powershell
.\install\setup.ps1
```

**Requirements:**
- Git (obviously)
- GitHub CLI (`gh`) for issue management
- Claude Code

---

## Your First Feature (5-Minute Quickstart)

```bash
# 1. Start brainstorming
/pm:prd-new user-authentication

# 2. Answer the guided questions about your feature
#    (vision, users, success criteria, etc.)

# 3. Convert to technical plan
/pm:prd-parse user-authentication

# 4. Push to GitHub and start parallel work
/pm:epic-oneshot user-authentication

# 5. Launch an agent on the first task
/pm:issue-start 42

# 6. Check what else can run in parallel
/pm:next

# 7. Launch more agents as needed
/pm:issue-start 43
/pm:issue-start 44

# 8. When all tasks complete, merge everything
/pm:epic-merge user-authentication
```

---

## Key Benefits Summary

| Challenge | Without CCPM | With CCPM |
|-----------|--------------|-----------|
| Context between sessions | Lost, re-explain every time | Persisted in PRDs/Epics/Issues |
| Parallel development | One task at a time | 5-8 concurrent agents |
| Team visibility | AI work is invisible | Real-time GitHub updates |
| Traceability | "Why did we build this?" | PRD → Epic → Task → Commit |
| Code review | Massive PRs, unclear scope | Targeted commits per acceptance criteria |
| Onboarding | Days of explanation | Read the PRD, check the Epic, start working |

---

## Reported Results

Teams using CCPM report:

- **89%** less context-switching friction
- **5-8x** more parallel tasks (vs. 1 at a time)
- **75%** reduction in bug rates
- **3x** faster feature delivery

*(These are claims from the project documentation)*

---

## How CCPM Can Help Us Achieve Our Goals

Looking at what we're building in this repository ("Software Development in the Age of AI"), CCPM aligns perfectly with our mission in several ways:

### 1. **Extends Our Automation Philosophy**

We already have:
- Sync tool to distribute `.claude/` automation
- PR iteration workflows
- Git hooks for protection

CCPM adds:
- Full project management inside Claude Code
- Parallel agent orchestration
- GitHub Issues as persistent memory

**Integration opportunity**: We could sync CCPM alongside our existing automation, giving every project both our knowledge base AND structured PM workflows.

### 2. **Solves the "Multi-Session" Problem We Document**

Our tips and playbooks help developers work *within* a session. CCPM solves working *across* sessions:

| Our Current Focus | What CCPM Adds |
|-------------------|----------------|
| Prompting techniques | Context that persists between prompts |
| Debugging workflows | Issue tracking for bug fixes |
| Feature playbooks | Full PRD → Epic → Task lifecycle |

### 3. **Enables Team-Scale AI Development**

Our repo is great for individual developers. CCPM enables:
- Multiple developers + multiple AI agents
- Visibility into what AI is doing
- Coordination without meetings

This is the **next level** of AI-assisted development.

### 4. **Complements Our Methodologies**

| Our Methodology | How CCPM Enhances It |
|-----------------|----------------------|
| AI pair programming | Becomes AI *team* programming |
| Prompt-driven development | Spec-driven development (more structured) |
| Iterative refinement | PRD versioning and Epic updates |

### 5. **Concrete Implementation Path**

We could:
1. Add CCPM to our sync tool distribution
2. Create playbooks for CCPM workflows
3. Document best practices for parallel agent coordination
4. Build prompts optimized for PRD creation
5. Write model-nuances for multi-agent scenarios

### 6. **Validates Our "Living Knowledge Base" Approach**

CCPM's context system mirrors our philosophy:
- Quick capture over perfection ✓
- Documentation that travels with the code ✓
- Always evolving ✓

We're essentially building the same thing from different angles - us for knowledge, them for project management.

---

## Key Links

| Resource | URL |
|----------|-----|
| GitHub Repository | https://github.com/automazeio/ccpm |
| Commands Reference | https://github.com/automazeio/ccpm/blob/main/COMMANDS.md |
| README | https://github.com/automazeio/ccpm/blob/main/README.md |

---

## Bottom Line

CCPM isn't just another project management tool. It's a **paradigm shift** for AI-assisted development:

- From "one human + one AI" to "team of humans + team of AI agents"
- From "context lost every session" to "everything persisted in GitHub"
- From "hope the AI follows instructions" to "spec-driven accountability"
- From "one task at a time" to "parallel execution swarms"

If you're serious about scaling AI-assisted development beyond toy projects, CCPM is worth understanding deeply. It represents where the industry is heading: AI agents as true team members, coordinated through the same tools (GitHub) that humans already use.

---

*Document created: December 2025*
*Sources: [GitHub - automazeio/ccpm](https://github.com/automazeio/ccpm), [CCPM Commands Reference](https://github.com/automazeio/ccpm/blob/main/COMMANDS.md)*
