A spec-driven development workflow for AI coding agents with quality gates, risk management, and full traceability.
PRD → Epic → Tasks → Issues → Parallel Agents → Code Review → Shipped Code → Retrospective
SuperPM turns vague feature requests into structured, executable work — managed entirely through markdown files and bash scripts. It works with any AI agent harness that supports the Agent Skills standard.
Most AI agents are great at writing code but terrible at managing work. They lose context between sessions, skip testing, forget dependencies, and have no sense of priority. SuperPM fixes this by giving agents a structured project management methodology:
- Requirements live in files, not chat history — survives context windows and session restarts
- Every task has priority, risk, and effort — agents work on the right things first
- Quality gates block sloppy handoffs — no skipping from "code written" to "done"
- Parallel execution with coordination — multiple agents work simultaneously without conflicts
- Learning loops — retrospectives capture what worked and what didn't
| # | Phase | What Happens |
|---|---|---|
| 1 | Plan | Guided brainstorming → PRD with risk assessment and measurable success criteria |
| 2 | Structure | Epic decomposition → prioritized tasks with dependencies, critical path analysis |
| 3 | Sync | Push to GitHub/GitLab → issues created, labels applied, worktree set up |
| 4 | Execute | Impact analysis → parallel agents launched per work stream, time tracked |
| 5 | Review | PR/MR created → automated checks (tests, lint, types) → quality gate enforcement |
| 6 | Track | 20 bash scripts for status, standup, sprint, burndown, velocity, risk dashboard |
| 7 | Retro | Metrics analysis → estimation calibration → learnings captured for next epic |
Each phase transition has a quality gate — concrete checks that must pass before proceeding.
# Clone the repo
git clone https://github.com/daizhouchen/superpm.git
# Option 1: Symlink into Claude Code skills
mkdir -p ~/.claude/skills
ln -s $(pwd)/superpm ~/.claude/skills/superpm
# Option 2: Copy into your project
cp -r superpm/. your-project/.claude/skills/superpm/# From your project root
bash ~/.claude/skills/superpm/references/scripts/init.shThis creates the directory structure, checks for gh/glab CLI, sets up GitHub labels, and creates a starter CLAUDE.md.
"I want to build user authentication" → Plan phase (writes PRD)
"Turn the user-auth PRD into an epic" → Plan phase (creates epic)
"Break down the user-auth epic" → Structure phase (creates tasks)
"Push the user-auth epic to GitHub" → Sync phase (creates issues)
"Start working on issue 42" → Execute phase (launches agents)
"Review issue 42" → Review phase (creates PR)
"What's our status?" → Track phase (runs scripts)
"Retro for the user-auth epic" → Retro phase (captures learnings)
Auto-detects GitHub (gh) or GitLab (glab) from your git remote. All sync operations work with both platforms.
Every task carries:
- Priority: P0 (critical) → P3 (nice-to-have)
- Risk: low → critical (high/critical tasks require impact analysis before execution)
- Severity: XS → XL (effort sizing for estimation)
Time-boxed delivery with:
- Sprint definition files (
.claude/sprints/sprint-N.md) - Burndown chart (text-based)
- Velocity tracking across sprints
- Committed vs completed hours
Pre-built templates for common patterns:
| Template | Use Case |
|---|---|
api-feature |
REST/GraphQL API endpoint |
ui-feature |
Frontend component or page |
migration |
Database/data migration |
integration |
Third-party service integration |
refactor |
Code refactoring / tech debt |
Usage: "Create a PRD for payment-v2 using the api-feature template"
All tracking operations run as bash scripts — no LLM tokens wasted on deterministic reporting.
| Category | Scripts |
|---|---|
| Overview | status.sh, standup.sh, help.sh |
| Epics | epic-list.sh, epic-show.sh, epic-status.sh |
| PRDs | prd-list.sh, prd-status.sh |
| Workflow | next.sh, in-progress.sh, blocked.sh, search.sh |
| Sprint | sprint-status.sh, burndown.sh, velocity.sh |
| Quality | risk-dashboard.sh, review-status.sh, validate.sh |
| Time | time-tracking.sh |
| Setup | init.sh |
| Transition | Required |
|---|---|
| Plan → Structure | Measurable success criteria, scope boundaries, risk assessment |
| Structure → Sync | Acceptance criteria on all tasks, effort estimates, no circular deps |
| Sync → Execute | Issues synced, worktree created |
| Execute → Review | All streams complete, tests pass locally |
| Review → Close | PR approved, CI passes, no unresolved comments |
| Close → Retro | Epic merged, all issues closed |
.claude/
├── prds/ # Product requirement documents
│ └── <feature>.md
├── epics/
│ └── <feature>/
│ ├── epic.md # Technical epic
│ ├── <N>.md # Task files (by issue number)
│ ├── <N>-analysis.md # Parallel work stream analysis
│ ├── <N>-impact.md # Impact/blast radius analysis
│ ├── time-log.md # Time tracking
│ ├── retro.md # Retrospective
│ └── updates/ # Progress tracking
├── sprints/
│ └── sprint-<N>.md # Sprint definitions
└── templates/ # Reusable patterns
---
name: Implement login flow
status: open | in-progress | review | closed
priority: P0 | P1 | P2 | P3
risk: low | medium | high | critical
severity: XS | S | M | L | XL
estimated_hours: 8
actual_hours: 0
depends_on: [41, 42]
parallel: true
conflicts_with: []
github: https://github.com/org/repo/issues/43
assignee: agent-1
---SuperPM follows the Agent Skills open standard and works with:
- Claude Code
- Any harness supporting
SKILL.md-based skills
╔══════════════════════════════════════════════════════════════╗
║ PROJECT STATUS ║
╚══════════════════════════════════════════════════════════════╝
2026-03-31 20:38
PRDs: 2
── Epics ──────────────────────────────────────────────────────
Total: 2
In-Progress: 1
Backlog: 1
── Tasks ──────────────────────────────────────────────────────
Total: 3 Open: 1 In-Progress: 1 Closed: 1
── Priority Breakdown (open tasks) ──────────────────────────
P0 (Critical): 1
P1 (High): 1
── Risk Items ─────────────────────────────────────────────────
[HIGH] user-auth/#42 - Implement login flow (P0 / in-progress)
── Time Budget ────────────────────────────────────────────────
Estimated: 24h Actual: 8h Usage: 33%
MIT