Claude Code PM
Claude Code workflow to ship faster better using spec-driven development, GitHub issues, Git worktrees, and mutiple AI agents running in parallel.
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.
Table of Contents
Background
Every team struggles with the same problems:
Context evaporates between sessions, forcing constant re-discovery
between sessions, forcing constant re-discovery Parallel work creates conflicts when multiple developers touch the same code
when multiple developers touch the same code Requirements drift as verbal decisions override written specs
as verbal decisions override written specs Progress becomes invisible until the very end
This system solves all of that.
The Workflow
graph LR A[PRD Creation] --> B[Epic Planning] B --> C[Task Decomposition] C --> D[GitHub Sync] D --> E[Parallel Execution] Loading
See It In Action (60 seconds)
# 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
What Makes This Different?
Traditional Development Claude Code PM System Context lost between sessions Persistent context across all work Serial task execution Parallel agents on independent tasks "Vibe coding" from memory Spec-driven with full traceability Progress hidden in branches Transparent audit trail in GitHub Manual task coordination Intelligent prioritization with /pm:next
Why GitHub Issues?
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:
🤝 True Team Collaboration
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
🔄 Seamless Human-AI Handoffs
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
📈 Scalable Beyond Solo Work
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
🎯 Single Source of Truth
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.
Core Principle: No Vibe Coding
Every line of code must trace back to a specification.
We follow a strict 5-phase discipline:
🧠 Brainstorm - Think deeper than comfortable 📝 Document - Write specs that leave nothing to interpretation 📐 Plan - Architect with explicit technical decisions ⚡ Execute - Build exactly what was specified 📊 Track - Maintain transparent progress at every step
No shortcuts. No assumptions. No regrets.
System Architecture
.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
Workflow Phases
1. Product Planning Phase
/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
2. Implementation Planning Phase
/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
3. Task Decomposition Phase
/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
4. GitHub Synchronization
/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.
5. Execution Phase
/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.
Command Reference
Tip Type /pm:help for a concise command summary
Initial Setup
/pm:init - Install dependencies and configure GitHub
PRD Commands
/pm:prd-new - Launch brainstorming for new product requirement
- Launch brainstorming for new product requirement /pm:prd-parse - Convert PRD to implementation epic
- Convert PRD to implementation epic /pm:prd-list - List all PRDs
- List all PRDs /pm:prd-edit - Edit existing PRD
- Edit existing PRD /pm:prd-status - Show PRD implementation status
Epic Commands
/pm:epic-decompose - Break epic into task files
- Break epic into task files /pm:epic-sync - Push epic and tasks to GitHub
- Push epic and tasks to GitHub /pm:epic-oneshot - Decompose and sync in one command
- Decompose and sync in one command /pm:epic-list - List all epics
- List all epics /pm:epic-show - Display epic and its tasks
- Display epic and its tasks /pm:epic-close - Mark epic as complete
- Mark epic as complete /pm:epic-edit - Edit epic details
- Edit epic details /pm:epic-refresh - Update epic progress from tasks
Issue Commands
/pm:issue-show - Display issue and sub-issues
- Display issue and sub-issues /pm:issue-status - Check issue status
- Check issue status /pm:issue-start - Begin work with specialized agent
- Begin work with specialized agent /pm:issue-sync - Push updates to GitHub
- Push updates to GitHub /pm:issue-close - Mark issue as complete
- Mark issue as complete /pm:issue-reopen - Reopen closed issue
- Reopen closed issue /pm:issue-edit - Edit issue details
Workflow Commands
/pm:next - Show next priority issue with epic context
- Show next priority issue with epic context /pm:status - Overall project dashboard
- Overall project dashboard /pm:standup - Daily standup report
- Daily standup report /pm:blocked - Show blocked tasks
- Show blocked tasks /pm:in-progress - List work in progress
Sync Commands
/pm:sync - Full bidirectional sync with GitHub
- Full bidirectional sync with GitHub /pm:import - Import existing GitHub issues
Maintenance Commands
/pm:validate - Check system integrity
- Check system integrity /pm:clean - Archive completed work
- Archive completed work /pm:search - Search across all content
The Parallel Execution System
Issues Aren't Atomic
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
: Database tables and migrations Agent 2 : Service layer and business logic
: Service layer and business logic Agent 3 : API endpoints and middleware
: API endpoints and middleware Agent 4 : UI components and forms
: UI components and forms Agent 5: Test suites and documentation
All running simultaneously in the same worktree.
The Math of Velocity
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.
Context Optimization
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.
GitHub vs Local: Perfect Separation
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.
The Command Flow
# 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
Key Features & Benefits
🧠 Context Preservation
Never lose project state again. Each epic maintains its own context, agents read from .claude/context/ , and updates locally before syncing.
⚡ Parallel Execution
Ship faster with multiple agents working simultaneously. Tasks marked parallel: true enable conflict-free concurrent development.
🔗 GitHub Native
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.
🤖 Agent Specialization
Right tool for every job. Different agents for UI, API, and database work. Each reads requirements and posts updates automatically.
📊 Full Traceability
Every decision is documented. PRD → Epic → Task → Issue → Code → Commit. Complete audit trail from idea to production.
🚀 Developer Productivity
Focus on building, not managing. Intelligent prioritization, automatic context loading, and incremental sync when ready.
Proven Results
Teams using this system report:
89% less time lost to context switching
lost to context switching 5-8 parallel tasks vs 1 previously
vs 1 previously 75% reduction in bug rates
in bug rates 3x faster feature delivery
Example Flow
# 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
Get Started Now
Quick Setup (2 minutes)
Clone this repository into your project: cd path/to/your/project/ git clone https://github.com/automazeio/ccpm.git . cd ccpm/ 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. 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 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 . Prime the system: /context:create
Start Your First Feature
/pm:prd-new your-feature-name
Watch as structured planning transforms into shipped code.
Local vs Remote
Operation Local GitHub PRD Creation ✅ — Implementation Planning ✅ — Task Breakdown ✅ ✅ (sync) Execution ✅ — Status Updates ✅ ✅ (sync) Final Deliverables — ✅
Technical Notes
GitHub Integration
Uses gh-sub-issue extension for proper parent-child relationships
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 )
File Naming Convention
Tasks start as 001.md , 002.md during decomposition
, during decomposition After GitHub sync, renamed to {issue-id}.md (e.g., 1234.md )
(e.g., ) Makes it easy to navigate: issue #1234 = file 1234.md
Design Decisions
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
Support This Project
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
to show your support 🐦 Follow @aroussi on X for updates and tips