Project management system for Claude Code using GitHub Issues and Git worktrees for parallel agent execution.

中文文档 (Chinese Documentation)

Stop losing context. Stop blocking on tasks. Stop shipping bugs. This battle-tested system turns PRDs into epics, epics into GitHub issues, and issues into production code – with full traceability at every step.

• Background
• The Workflow
• What Makes This Different?
• Why GitHub Issues?
• Core Principle: No Vibe Coding
• System Architecture
• Workflow Phases
• Command Reference
• The Parallel Execution System
• Key Features & Benefits
• Proven Results
• Example Flow
• Get Started Now
• Local vs Remote
• Technical Notes
• Support This Project

Every team struggles with the same problems:

• Context evaporates between sessions, forcing constant re-discovery
• Parallel work creates conflicts when multiple developers touch the same code
• Requirements drift as verbal decisions override written specs
• Progress becomes invisible until the very end

This system solves all of that.

graph LR
    A[PRD Creation] --> B[Epic Planning]
    B --> C[Task Decomposition]
    C --> D[GitHub Sync]
    D --> E[Parallel Execution]

# Create a comprehensive PRD through guided brainstorming
/pm:prd-new memory-system

# Transform PRD into a technical epic with task breakdown
/pm:prd-parse memory-system

# Push to GitHub and start parallel execution
/pm:epic-oneshot memory-system
/pm:issue-start 1235

Most Claude Code workflows operate in isolation – a single developer working with AI in their local environment. This creates a fundamental problem: AI-assisted development becomes a silo.

By using GitHub Issues as our database, we unlock something powerful:

• Multiple Claude instances can work on the same project simultaneously
• Human developers see AI progress in real-time through issue comments
• Team members can jump in anywhere – the context is always visible
• Managers get transparency without interrupting flow

• AI can start a task, human can finish it (or vice versa)
• Progress updates are visible to everyone, not trapped in chat logs
• Code reviews happen naturally through PR comments
• No "what did the AI do?" meetings

• Add team members without onboarding friction
• Multiple AI agents working in parallel on different issues
• Distributed teams stay synchronized automatically
• Works with existing GitHub workflows and tools

• No separate databases or project management tools
• Issue state is the project state
• Comments are the audit trail
• Labels provide organization

This isn't just a project management system – it's a collaboration protocol that lets humans and AI agents work together at scale, using infrastructure your team already trusts.

Every line of code must trace back to a specification.

We follow a strict 5-phase discipline:

1. 🧠 Brainstorm - Think deeper than comfortable
2. 📝 Document - Write specs that leave nothing to interpretation
3. 📐 Plan - Architect with explicit technical decisions
4. ⚡ Execute - Build exactly what was specified
5. 📊 Track - Maintain transparent progress at every step

No shortcuts. No assumptions. No regrets.

.claude/
├── CLAUDE.md          # Always-on instructions (copy content to your project's CLAUDE.md file)
├── agents/            # Task-oriented agents (for context preservation)
├── commands/          # Command definitions
│   ├── context/       # Create, update, and prime context
│   ├── pm/            # ← Project management commands (this system)
│   └── testing/       # Prime and execute tests (edit this)
├── context/           # Project-wide context files
├── epics/             # ← PM's local workspace (place in .gitignore)
│   └── [epic-name]/   # Epic and related tasks
│       ├── epic.md    # Implementation plan
│       ├── [#].md     # Individual task files
│       └── updates/   # Work-in-progress updates
├── prds/              # ← PM's PRD files
├── rules/             # Place any rule files you'd like to reference here
└── scripts/           # Place any script files you'd like to use here

/pm:prd-new feature-name

Launches comprehensive brainstorming to create a Product Requirements Document capturing vision, user stories, success criteria, and constraints.

Output: .claude/prds/feature-name.md

/pm:prd-parse feature-name

Transforms PRD into a technical implementation plan with architectural decisions, technical approach, and dependency mapping.

Output: .claude/epics/feature-name/epic.md

/pm:epic-decompose feature-name

Breaks epic into concrete, actionable tasks with acceptance criteria, effort estimates, and parallelization flags.

Output: .claude/epics/feature-name/[task].md

/pm:epic-sync feature-name
# Or for confident workflows:
/pm:epic-oneshot feature-name

Pushes epic and tasks to GitHub as issues with appropriate labels and relationships.

/pm:issue-start 1234  # Launch specialized agent
/pm:issue-sync 1234   # Push progress updates
/pm:next             # Get next priority task

Specialized agents implement tasks while maintaining progress updates and an audit trail.

• /pm:init - Install dependencies and configure GitHub

• /pm:prd-new - Launch brainstorming for new product requirement
• /pm:prd-parse - Convert PRD to implementation epic
• /pm:prd-list - List all PRDs
• /pm:prd-edit - Edit existing PRD
• /pm:prd-status - Show PRD implementation status

• /pm:epic-decompose - Break epic into task files
• /pm:epic-sync - Push epic and tasks to GitHub
• /pm:epic-oneshot - Decompose and sync in one command
• /pm:epic-list - List all epics
• /pm:epic-show - Display epic and its tasks
• /pm:epic-close - Mark epic as complete
• /pm:epic-edit - Edit epic details
• /pm:epic-refresh - Update epic progress from tasks

• /pm:issue-show - Display issue and sub-issues
• /pm:issue-status - Check issue status
• /pm:issue-start - Begin work with specialized agent
• /pm:issue-sync - Push updates to GitHub
• /pm:issue-close - Mark issue as complete
• /pm:issue-reopen - Reopen closed issue
• /pm:issue-edit - Edit issue details

• /pm:next - Show next priority issue with epic context
• /pm:status - Overall project dashboard
• /pm:standup - Daily standup report
• /pm:blocked - Show blocked tasks
• /pm:in-progress - List work in progress

• /pm:sync - Full bidirectional sync with GitHub
• /pm:import - Import existing GitHub issues

• /pm:validate - Check system integrity
• /pm:clean - Archive completed work
• /pm:search - Search across all content

Traditional thinking: One issue = One developer = One task

Reality: One issue = Multiple parallel work streams

A single "Implement user authentication" issue isn't one task. It's...

• Agent 1: Database tables and migrations
• Agent 2: Service layer and business logic
• Agent 3: API endpoints and middleware
• Agent 4: UI components and forms
• Agent 5: Test suites and documentation

All running simultaneously in the same worktree.

Traditional Approach:

• Epic with 3 issues
• Sequential execution

This System:

• Same epic with 3 issues
• Each issue splits into ~4 parallel streams
• 12 agents working simultaneously

We're not assigning agents to issues. We're leveraging multiple agents to ship faster.

Traditional single-thread approach:

• Main conversation carries ALL the implementation details
• Context window fills with database schemas, API code, UI components
• Eventually hits context limits and loses coherence

Parallel agent approach:

• Main thread stays clean and strategic
• Each agent handles its own context in isolation
• Implementation details never pollute the main conversation
• Main thread maintains oversight without drowning in code

Your main conversation becomes the conductor, not the orchestra.

What GitHub Sees:

• Clean, simple issues
• Progress updates
• Completion status

What Actually Happens Locally:

• Issue #1234 explodes into 5 parallel agents
• Agents coordinate through Git commits
• Complex orchestration hidden from view

GitHub doesn't need to know HOW the work got done – just that it IS done.

# Analyze what can be parallelized
/pm:issue-analyze 1234

# Launch the swarm
/pm:epic-start memory-system

# Watch the magic
# 12 agents working across 3 issues
# All in: ../epic-memory-system/

# One clean merge when done
/pm:epic-merge memory-system

Never lose project state again. Each epic maintains its own context, agents read from .claude/context/, and updates locally before syncing.

Ship faster with multiple agents working simultaneously. Tasks marked parallel: true enable conflict-free concurrent development.

Works with tools your team already uses. Issues are the source of truth, comments provide history, and there is no dependency on the Projects API.

Right tool for every job. Different agents for UI, API, and database work. Each reads requirements and posts updates automatically.

Every decision is documented. PRD → Epic → Task → Issue → Code → Commit. Complete audit trail from idea to production.

Focus on building, not managing. Intelligent prioritization, automatic context loading, and incremental sync when ready.

Teams using this system report:

• 89% less time lost to context switching – you'll use /compact and /clear a LOT less
• 5-8 parallel tasks vs 1 previously – editing/testing multiple files at the same time
• 75% reduction in bug rates – due to the breaking down features into detailed tasks
• Up to 3x faster feature delivery – based on feature size and complexity

# Start a new feature
/pm:prd-new memory-system

# Review and refine the PRD...

# Create implementation plan
/pm:prd-parse memory-system

# Review the epic...

# Break into tasks and push to GitHub
/pm:epic-oneshot memory-system
# Creates issues: #1234 (epic), #1235, #1236 (tasks)

# Start development on a task
/pm:issue-start 1235
# Agent begins work, maintains local progress

# Sync progress to GitHub
/pm:issue-sync 1235
# Updates posted as issue comments

# Check overall status
/pm:epic-show memory-system

1. Install this repository into your project:

   Unix/Linux/macOS

   cd path/to/your/project/
   curl -sSL https://automaze.io/ccpm/install | bash
   # or: wget -qO- https://automaze.io/ccpm/install | bash

   Windows (PowerShell)

   cd path/to/your/project/
   iwr -useb https://automaze.io/ccpm/install | iex

   ⚠️ IMPORTANT: If you already have a .claude directory, clone this repository to a different directory and copy the contents of the cloned .claude directory to your project's .claude directory.

   See full/other installation options in the installation guide ›

2. Initialize the PM system:

   /pm:init

   This command will:

   • Install GitHub CLI (if needed)
   • Authenticate with GitHub
   • Install gh-sub-issue extension for proper parent-child relationships
   • Create required directories
   • Update .gitignore

3. Create CLAUDE.md with your repository information

   /init include rules from .claude/CLAUDE.md

   If you already have a CLAUDE.md file, run: /re-init to update it with important rules from .claude/CLAUDE.md.

4. Prime the system:

   /context:create

/pm:prd-new your-feature-name

Watch as structured planning transforms into shipped code.

• Uses gh-sub-issue extension for proper parent-child relationships
• Falls back to task lists if extension not installed
• Epic issues track sub-task completion automatically
• Labels provide additional organization (epic:feature, task:feature)

• Tasks start as 001.md, 002.md during decomposition
• After GitHub sync, renamed to {issue-id}.md (e.g., 1234.md)
• Makes it easy to navigate: issue #1234 = file 1234.md

• Intentionally avoids GitHub Projects API complexity
• All commands operate on local files first for speed
• Synchronization with GitHub is explicit and controlled
• Worktrees provide clean git isolation for parallel work
• GitHub Projects can be added separately for visualization

Claude Code PM was developed at Automaze for developers who ship, by developers who ship.

If Claude Code PM helps your team ship better software:

• ⭐ Star this repository to show your support
• 🐦 Follow @aroussi on X for updates and tips