harpreetsingh /flywheel — The Development Flywheel
Render the full development flywheel (or a specific phase) as a visual map. This is the "how does this system work?" answer — for onboarding, sprint preview, or just remembering what comes next.
Usage:
/flywheel ← full flywheel + write FLYWHEEL.md
/flywheel shaping ← zoom into shaping phase
/flywheel planning ← zoom into planning phase
/flywheel sprint ← zoom into sprint execution
/flywheel sprint-close ← zoom into sprint close
/flywheel wave-gate ← zoom into wave gate protocol
Process
Read the actual skill and agent definitions to build the map. Do NOT hardcode — read the source files so the map is always current:
skills/hs-sw-shape/skills/hs-sw-plan-draft/skills/hs-sw-plan-review/skills/hs-sw-beads-create/skills/hs-sw-beads-review/skills/hs-sw-sprint-exec-plan/skills/hs-sw-sprint-go/agents/hs-sw-sprint-director.mdagents/hs-sw-sprint-qa.mdagents/hs-sw-sprint-bug-hunter.mdskills/hs-sw-docs-gen-int/skills/hs-sw-docs-gen-ext/skills/hs-sw-fresh-eyes/skills/hs-sw-test-coverage/skills/hs-sw-ux-polish/skills/hs-sw-land-the-plane/skills/hs-sw-sprint-recover/skills/hs-sw-sprint-close/skills/hs-sw-sprint-retrospective/skills/hs-sw-flywheel-metrics/skills/hs-sw-beads-label/
Find these relative to the claude-workflow-skills repo. Check common locations:
~/.claude/skills/(symlinks)- The repo path from the skill's own location (traverse up from this file)
If
$ARGUMENTSis empty or "full": render the complete flywheel AND writeFLYWHEEL.mdto the project repo root (the working directory, NOT the skills repo). If$ARGUMENTSnames a phase: render just that phase in detail (no file write).Render the map using the formats below.
Write
FLYWHEEL.mdto the project repo root. This is the static, committable version. It should include:- The compact flywheel diagram
- The full expanded flywheel
- The artifact map
- A skill/agent reference table: name, one-line description, inputs, outputs
- Footer: "Generated by
/flywheelon . Run/flywheelfor interactive phase zoom."
The Compact Flywheel
This is the canonical reference diagram. It appears at the top of FLYWHEEL.md and is embedded (with a "You Are Here" marker) in every skill.
┌─ THE FLYWHEEL ──────────────────────────────────────────────────────────┐
│ │
│ SHAPE ──→ PLAN ──→ REVIEW ──→ DECOMPOSE ──→ SPRINT PLAN │
│ /shape /plan-draft /plan-review /beads-create /sprint-exec-plan │
│ ×4-5 /beads-review │
│ │
│ ──→ EXECUTE ──────────────────────────────────────────→ CLOSE │
│ /sprint-go /land-the-plane│
│ ┌──────────────────────────────────────────────┐ │
│ │ Director orchestrates: │ │
│ │ Phase 0 → Wave N [ TDD → QA → Gate → Review │ │
│ │ Flywheel ] → Sprint Close│ │
│ │ Sprint Close: docs-int, docs-ext, │ │
│ │ fresh-eyes, land-the-plane │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ ──→ HUMAN REVIEW ──→ MERGE ──→ (next feature loops back to SHAPE) │
│ PR review, manual QA, bd close │
│ │
│ Sprint failed? ──→ /sprint-recover ──→ re-enter at SPRINT PLAN │
│ │
└─────────────────────────────────────────────────────────────────────────┘
"You Are Here" — For Other Skills
Every skill in the flywheel should include this block near the top of its SKILL.md (after the frontmatter, before the process). This gives each skill awareness of how it fits into the larger system.
The format is a compact one-line flywheel with the current skill highlighted:
┌─ THE FLYWHEEL ──────────────────────────────────────────────────────────┐
│ SHAPE → PLAN → REVIEW×N → DECOMPOSE → SPRINT PLAN → EXECUTE → CLOSE │
│ ▲ │
│ YOU ARE HERE │
│ See FLYWHEEL.md for the full development lifecycle. │
└─────────────────────────────────────────────────────────────────────────┘
When /flywheel generates FLYWHEEL.md, it does NOT rewrite other skills.
The "You Are Here" blocks are added once by a human or by running
/flywheel --embed (future enhancement). Skills reference FLYWHEEL.md for
the full picture.
Full Flywheel (expanded)
╔══════════════════════════════════════════════════════════════════════════╗
║ THE FLYWHEEL ║
╚══════════════════════════════════════════════════════════════════════════╝
┌─────────────────────────────────────────────────────────────────────────┐
│ 1. SHAPING Human + Claude │
│ │
│ /shape #42 │
│ ↓ │
│ 5-round interview: Problem → Appetite → Solution → Rabbit Holes │
│ → No-Gos │
│ ↓ │
│ OUTPUT: docs/projects/features/<slug>/pitch.md │
│ docs/projects/features/<slug>/planning-context/ │
│ │
│ ✓ GitHub Issue updated with pitch link │
│ ✓ Label: ready-to-bet │
└────────────────────────────────────────┬────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ 2. PLANNING Human + Claude │
│ │
│ /plan-draft docs/projects/features/<slug>/ │
│ ↓ │
│ Reads pitch.md + planning-context/ → synthesizes PLAN.md │
│ (architecture, deliverables, CLI commands, diagrams) │
│ ↓ │
│ /plan-review docs/projects/features/<slug>/PLAN.md (repeat 4-5×) │
│ ↓ │
│ Each round: severity-rated proposals → user approves → apply │
│ Converges after 4-5 rounds │
│ ↓ │
│ OUTPUT: docs/projects/features/<slug>/PLAN.md (refined) │
└────────────────────────────────────────┬────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ 3. DECOMPOSITION Human + Claude │
│ │
│ /beads-create docs/projects/features/<slug>/PLAN.md [--labels a,b] │
│ ↓ │
│ PLAN → epics → tasks + TDD test beads (--parent epic) │
│ Each bead carries: ## Files (declared scope), ## Contract (shared │
│ interfaces), ## Steps (Search→Read→Implement→Verify) │
│ Wires dependencies (test beads block impl beads) + CLI beads │
│ ↓ │
│ /beads-review │
│ ↓ │
│ Structural · TDD gaps · domain balance · self-sufficiency · │
│ RIGHT-SIZING (1 bead/1 layer) · CONTRACT consistency · │
│ FILE-OVERLAP graph (collision-free scheduling input) │
│ ↓ │
│ OUTPUT: beads epic, all tickets wired, file-overlap graph │
└────────────────────────────────────────┬────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ 4. SPRINT PLANNING Human + Claude │
│ │
│ /sprint-exec-plan │
│ ↓ │
│ Inventory → TDD pairing → wave analysis → model tiers (opus/sonnet) │
│ → domain balance → team topology → wave diagram │
│ Worker count gated by: escape rate <20% (the scaling gate) AND │
│ true parallel width (largest file-disjoint set per wave) │
│ ↓ │
│ OUTPUT: tmp/sprint-exec-plan.md, sprint-plan.md, tmp/sprint-status.sh│
│ │
│ Optional: /sprint-go --dry-run (preview without launching) │
└────────────────────────────────────────┬────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ 5. SPRINT EXECUTION Autonomous │
│ │
│ /sprint-go │
│ ↓ │
│ Spawns Director (background) → Director creates team │
│ Director spawns: workers (≤5) + QA agent(s) (1-2) │
│ ↓ │
│ ┌─── Phase 0: Ticket Sufficiency Review ───────────────────────────┐ │
│ │ Enrich every bead for self-sufficiency. Create missing TDD │ │
│ │ pairs. No work assigned until Phase 0 completes. │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─── Wave N (repeats per wave) ────────────────────────────────────┐ │
│ │ │ │
│ │ ASSIGN (gate: dep-free → COLLISION-FREE → priority → tier; │ │
│ │ file ledger in sprint-state.md): test beads → Worker A (red) │ │
│ │ ↓ [append assign/qa_pass/… to sprint-log.md per event] │ │
│ │ QA VERIFY: tests fail for right reasons; every ## Step verified │ │
│ │ ↓ │ │
│ │ ASSIGN: impl beads → Worker B (green phase, DIFFERENT worker) │ │
│ │ ↓ │ │
│ │ QA VERIFY: tests pass, ACs met, no mocks, in-scope (## Files) │ │
│ │ ↓ │ │
│ │ ╔═══ WAVE GATE (hard — blocks Wave N+1) ═══════════════════╗ │ │
│ │ ║ 1. All tickets individually QA-passed ║ │ │
│ │ ║ 2. Integration quality gates (ruff + pytest / lint + tsc) ║ │ │
│ │ ║ 3. Review flywheel (CORRECTNESS/SECURITY/COMPACTION/UX), ║ │ │
│ │ ║ SHARDED by diff volume → deduped Review Digest ║ │ │
│ │ ║ 4. QA smoke test ║ │ │
│ │ ║ 5. Snapshot written (sprint-state.md), lifecycle updated ║ │ │
│ │ ║ 6. Human review (Wave 1: BLOCKING / Wave 2+: async) ║ │ │
│ │ ╚══════════════════════════════════════════════════════════╝ │ │
│ │ ↓ │ │
│ └── next wave ─────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─── Sprint Close ────────────────────────────────────────────────┐ │
│ │ 1. Final quality gates + UBS full-project scan │ │
│ │ 2. /test-coverage → verify real coverage (no mocks) │ │
│ │ 3. /docs-gen-int → architecture.md, api.md, cli.md, etc. │ │
│ │ 4. /docs-gen-ext → docs/areas/site/features/, guides/, ref/ │ │
│ │ 5. /fresh-eyes <feature-dir> (code + plan + docs + beads) │ │
│ │ 6. /land-the-plane → commit + push │ │
│ │ 7. /sprint-retrospective → patterns → Phase 0/AGENTS.md fixes │ │
│ │ (+ /flywheel-metrics: escape-rate trend, the 20% gate) │ │
│ │ 8. Lifecycle bead completed, final checkpoint written │ │
│ │ 9. Summary to user → shutdown │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ (post-sprint, human-run: /sprint-close — close beads, log escape │
│ rate, remove status bar, clean tmp) │
│ │
│ OUTPUT: docs/projects/features/<slug>/sprint-state.md (completed) │
│ docs/projects/features/<slug>/architecture.md, api.md, ... │
│ docs/areas/site/features/<slug>/... , guides/, reference/ │
│ All beads labeled qa-passed (human closes after review) │
└────────────────────────────────────────┬────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ 6. HUMAN REVIEW Human │
│ │
│ PR review on GitHub │
│ Manual QA on staging │
│ bd close <id> for each verified bead │
│ Merge feature branch → main → production │
│ │
│ Sprint failed or incomplete? │
│ ↓ │
│ /sprint-recover <feature-dir> — triage, fix beads, re-enter at 4. │
└─────────────────────────────────────────────────────────────────────────┘
Phase Zoom
When the user specifies a phase, render ONLY that phase in expanded detail. Read the relevant skill/agent files and include:
- Every step with its inputs and outputs
- What triggers the next step
- What files are read and written
- What agents are involved
- What quality checks run
- Common failure modes and how they're handled
Available phases:
| Argument | Phase | Key skills/agents |
|---|---|---|
shaping |
Shaping interview | /shape |
planning |
Plan draft + review | /plan-draft, /plan-review |
decomposition |
Beads creation + review | /beads-create, /beads-review (right-sizing, contracts, file-overlap) |
sprint-planning |
Execution plan | /sprint-exec-plan (escape-rate + parallel-width gating) |
sprint |
Full sprint execution | /sprint-go, Director (collision-free assign, event log), QA, workers |
wave-gate |
Wave gate protocol | Director, QA, bug-hunter (sharded lenses → Review Digest) |
sprint-close |
Sprint close sequence | docs-gen-int/ext, fresh-eyes, land-the-plane, /sprint-close |
learning |
Metrics + retrospective | /flywheel-metrics (20% gate), /sprint-retrospective |
review |
Human review | Manual (no skills) |
recovery |
Sprint recovery | /sprint-recover (compaction: replay sprint-log.md) |
Artifact Map
docs/projects/features/<slug>/ ← active work (during feature)
├── pitch.md ← /shape
├── planning-context/ ← /shape (evidence bag)
├── PLAN.md ← /plan-draft → /plan-review ×4-5
├── sprint-plan.md ← /sprint-exec-plan (persistent copy)
├── sprint-state.md ← Director (full snapshot, per wave gate)
├── sprint-log.md ← Director (append-only event log, per ticket event)
├── learnings.md ← /sprint-retrospective (failure patterns + fixes)
├── architecture.md ← /docs-gen-int (sprint close)
├── api.md ← /docs-gen-int
├── cli.md ← /docs-gen-int
├── data-model.md ← /docs-gen-int
├── what-shipped.md ← /docs-gen-int
└── lessons.md ← /docs-gen-int
docs/resources/features/<slug>/ ← after /land-the-plane (feature shipped)
└── (same files, moved by land-the-plane graduation step)
docs/areas/site/
├── features/<slug>/ ← /docs-gen-ext (concept docs)
├── guides/ ← /docs-gen-ext (how-to guides)
├── reference/api/ ← /docs-gen-ext (API reference)
└── reference/cli/ ← /docs-gen-ext (CLI reference)
Beads (bd):
├── Epic: feature epic
├── Sprint Lifecycle bead ← Director (meta-ticket, checklist)
├── Test beads ← /beads-create (red phase)
├── Impl beads ← /beads-create (green phase)
└── Bug/review beads ← bug-hunter (caught:review), Director (caught:manual/pr)
Global (cross-project):
└── ~/.claude/flywheel/sprint-metrics.jsonl ← /sprint-close appends one line/sprint
(escape-rate trend; the 20% scaling gate)
FLYWHEEL.md Generation
When rendering the full flywheel (no phase argument), also write FLYWHEEL.md
to the project repo root (the current working directory). This is the static,
committable version that anyone can read without tooling.
Diagrams in this file are mermaid — it's read on GitHub and in editors, where
mermaid renders. Convert the on-screen ASCII renderings to mermaid when writing them
here (a phase chain becomes a flowchart LR, the artifact map a flowchart TD).
The file should contain:
- A header explaining what the flywheel is and how to use it
- The compact flywheel diagram (mermaid)
- The full expanded flywheel (mermaid)
- The artifact map
- A skill/agent reference table: name, one-line description, inputs, outputs
- Footer:
Generated by /flywheel on <date>. Run /flywheel for interactive phase zoom.
Overwrite any existing FLYWHEEL.md — the generated version is always canonical.
Rules
- Read the actual skill files to build the map. Do not rely on stale descriptions. If a skill has changed since this file was written, the map should reflect the current version.
- Diagrams: mermaid in FLYWHEEL.md, ASCII on screen. The written file is read on GitHub/VS Code, where mermaid renders — use mermaid there. Anything rendered into the conversation (the full map, phase zooms) is ASCII, because the terminal shows a mermaid fence as raw source. No external tools, no images either way.
- Keep the full map under 120 lines. Phase zooms can be longer.
- When zooming into a phase, include enough context to understand it standalone — mention what came before and what comes after.
- If the user asks about a skill that doesn't exist, say so rather than guessing.