DOCSEARCHbyAlgolia
Submit Docs

CCPM (The Project Manager Agent)

repository·main·Indexed 27 days ago

https://github.com/automazeio/ccpm

A spec-driven development framework for AI agents that uses GitHub Issues as a single source of truth. CCPM manages requirements via PRDs, technical planning through Epics, and parallel task execution with full traceability. It is available as an Agent Skill for harnesses like Factory, Droid, and Claude Code, utilizing a 5-phase workflow: Brainstorm, Document, Plan, Execute, and Track.

Tokens
10K
Snippets
27
Records
46
Agent score
93%

What's inside CCPM

  1. Use CCPM for spec-driven project management

    main

    CCPM (Claude Code Project Manager) is a workflow for software delivery that moves from PRD → Epic → GitHub Issues → Parallel Agents → Shipped Code.

    Use CCPM for tasks involving the software delivery lifecycle, such as:

    • Writing or scoping PRDs.
    • Parsing PRDs into epics and decomposing epics into tasks.
    • Syncing work to GitHub (pushing tasks as issues, posting progress comments).
    • Starting work on specific GitHub issues using parallel agents.
    • Tracking progress (running standups, checking status, identifying blockers).

    Note: Do NOT use CCPM for debugging code, writing tests, reviewing PRs, or performing raw GitHub operations that lack delivery context.

  2. CCPM Directory Structure

    main

    CCPM uses a specific directory structure within the .claude/ folder to manage product requirements, epics, tasks, and progress tracking. Follow this layout for all file operations:

    • .claude/prds/: Contains Product Requirement Documents (<feature-name>.md).
    • .claude/epics/<feature-name>/: Contains the technical epic (epic.md), task files (<N>.md), analysis files (<N>-analysis.md), and mapping files.
    • .claude/epics/<feature-name>/updates/<issue_N>/: Contains per-agent progress (stream-A.md), overall issue progress (progress.md), and execution state (execution.md).
    • .claude/context/: Project context documentation.
    .claude/
├── prds/
│   └── <feature-name>.md          # Product requirement documents
├── epics/
│   ├── <feature-name>/
│   │   ├── epic.md                # Technical epic
│   │   ├── <N>.md                 # Task files (named by GitHub issue number after sync)
│   │   ├── <N>-analysis.md        # Parallel work stream analysis
│   │   ├── github-mapping.md      # Issue number → URL mapping
│   │   ├── execution-status.md    # Active agents tracker
│   │   └── updates/
│   │       └── <issue_N>/
│   │           ├── stream-A.md    # Per-agent progress
│   │           ├── progress.md    # Overall issue progress
│   │           └── execution.md  # Execution state
│   └── archived/
│       └── <feature-name>/        # Completed epics
└── context/                       # Project context docs (separate system)

  4. Use CCPM via Natural Language Triggers

    main

    CCPM activates automatically when your agent detects Project Management (PM) intent. You do not need special syntax; simply use natural language to drive the workflow phases.

    IntentExample Command
    Brainstorm & PRD"I want to build X" or "let's plan X"
    Epic Planning"parse the X PRD" or "create an epic for X"
    Task Decomposition"break down the X epic"
    GitHub Sync"sync the X epic to GitHub"
    Execution"start working on issue N"
    Tracking/Status"standup", "what's our status", "what's next", or "what's blocked"
    Issue Management"close issue N" or "merge the X epic"

  5. Install CCPM as an Agent Skill

    main

    CCPM is an Agent Skill that can be integrated into various AI coding harnesses. To use it, clone the repository and symlink the skill/ccpm/ directory into your specific harness's skills folder.

    Prerequisites

    • git and gh CLI (must be authenticated via gh auth login)
    • A GitHub repository for your project

    Installation by Harness

    For Factory / Droid: Symlink the skill into your skills directory:

    ln -s /path/to/ccpm/skill/ccpm ~/.factory/skills/ccpm

    For Claude Code: In your project root, create a skills/ directory and symlink the skill:

    ln -s /path/to/ccpm/skill/ccpm .claude/skills/ccpm

    For other Agent Skills–compatible harnesses: Point the harness to the skill/ccpm/ directory.

    git clone https://github.com/automazeio/ccpm.git

  6. Report a bug found during a task

    main

    If a bug is discovered while working on an issue, create a linked bug task to maintain context.

    Workflow:

    1. Gather Context: Use gh issue view <original_N> --json title,body,labels and read the local task file .claude/epics/*/<original_N>.md.
    2. Create Local Bug File: Create a new markdown file in .claude/epics/<epic>/ named bug-<original_N>-<slug>.md.
      • Include bug_for: <original_N> in the frontmatter.
      • Include a Context section referencing the original issue.
    3. Create GitHub Issue: Create a new issue with the label bug and epic:<epic_name>. Ensure the body starts with Fixes / follow-up to #<original_N> to enable GitHub auto-linking.
    4. Link and Rename: Update the local file with the new GitHub issue number and rename the file to <new_N>.md.
    gh issue create \
  --repo "$REPO" \
  --title "Bug: <short description>" \
  --body "$(cat /tmp/bug-body.md)" \
  --label "bug,epic:<epic_name>" \
  --json number -q .number

  7. Decompose an Epic into Tasks

    main

    To convert a technical epic into actionable work, follow the decomposition process to create numbered task files.

    Preflight Checklist

    1. Ensure .claude/epics/<name>/epic.md exists with valid frontmatter.
    2. If existing numbered task files (e.g., 001.md, 002.md) are present in the epic directory, confirm their deletion before recreating them.
    3. If the epic status is already completed, proceed with caution.

    Parallelization Strategy

    Analyze the epic to determine which tasks can run simultaneously based on size:

    • Small (<5 tasks): Create tasks sequentially.
    • Medium (5–10 tasks): Batch into 2–3 groups and spawn parallel Task agents.
    • Large (>10 tasks): Analyze dependencies first, then launch up to 5 concurrent parallel agents. Create dependent tasks only after prerequisites are met.

    Workflow Completion

    After all tasks are created, append a summary to the epic file including:

    • A checklist of created tasks (e.g., 001.md - <Title> (parallel: true/false)).
    • Total task count.
    • Breakdown of parallel vs. sequential tasks.
    • Estimated total effort in hours.

  8. The CCPM 5-Phase Workflow

    main

    CCPM follows a strict spec-driven discipline to ensure every line of code traces back to a requirement:

    1. 🧠 Brainstorm: Guided brainstorming to define problems, users, success criteria, and constraints.
    2. 📝 Document: Creation of a structured Product Requirement Document (PRD) at .claude/prds/<name>.md.
    3. 📐 Plan: Parsing the PRD into a technical epic at .claude/epics/<feature>/epic.md containing architecture decisions and task previews.
    4. ⚡ Execute: Decomposing epics into tasks (with parallel: true metadata where applicable) and syncing to GitHub. Agents then work on issues in parallel streams.
    5. 📊 Track: Using deterministic bash scripts to run standup, status, or search operations for instant progress reporting.

  9. Manage Git Branches and Worktrees for Epics

    main

    Follow these conventions for Git workflow:

    • Branching: Use one branch per epic with the naming pattern epic/<name>.
    • Worktrees: Store worktrees at ../epic-<name>/ (as a sibling to the project root).
    • Workflow: Always start branches from an up-to-date main branch.
    • Commits: Use the format Issue #<N>: <description> inside epics.
    • Restriction: Never use the --force flag in any git operation.
    # Setup a new epic worktree
git checkout main && git pull origin main
git worktree add ../epic-<name> -b epic/<name>

  11. Quick reference for CCPM natural language commands

    main

    You can trigger CCPM workflows using natural language prompts. Common commands include:

    • Planning: "I want to build X" or "create a PRD for X"
    • Parsing: "turn the X PRD into an epic"
    • Decomposing: "break down the X epic into tasks"
    • Syncing: "push the X epic to GitHub"
    • Executing: "start working on issue 42"
    • Tracking: "what's our status", "standup", or "what should I work on next"
    • Closing/Merging: "merge the X epic"
    • Bug Reporting: "found a bug in issue 42" or "testing issue 42 revealed X"

  12. Start work on a specific GitHub issue

    main

    To begin implementation on a GitHub issue using parallel agents, follow these steps:

    Preflight

    1. Verify the issue is open: gh issue view <N> --json state,title,labels,body.
    2. Locate the local task file.
    3. Ensure an analysis file exists at .claude/epics/*/<N>-analysis.md (run analysis first if missing).
    4. Verify the epic worktree exists: git worktree list | grep "epic-<name>".

    Execution Steps

    1. Read Analysis: Identify which streams can start immediately.
    2. Setup Tracking: Create a directory for updates at .claude/epics/<epic>/updates/<N> and create a stream-<X>.md file for each stream to track progress.
    3. Launch Agents: Deploy a general-purpose subagent for each immediate stream. Agents must work only in assigned files, commit frequently using the format Issue #<N>: <specific change>, and update their respective stream-<X>.md files.
    4. Assign on GitHub: Use gh issue edit <N> --add-assignee @me --add-label "in-progress".
    5. Create Execution Status: Initialize .claude/epics/<epic>/updates/<N>/execution.md to track active, queued, and completed streams.

    To monitor progress, check the .claude/epics/<epic>/updates/<N>/ directory. To sync updates, use sync issue <N>.