# Hs Sw Flywheel

> Render the full development flywheel as a visual map, write FLYWHEEL.md to repo root, zoom into any phase

- Skill: `harpreetsingh/hs-sw-flywheel` (Agent Skill)
- Install (CLI): `npx skillmds@latest add harpreetsingh/hs-sw-flywheel`
- Raw SKILL.md: https://api.skillmd.com/api/skills/harpreetsingh/hs-sw-flywheel/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: harpreetsingh (https://skillmd.com/u/harpreetsingh)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/harpreetsingh/hs-sw-flywheel

---


# /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

1. **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.md`
   - `agents/hs-sw-sprint-qa.md`
   - `agents/hs-sw-sprint-bug-hunter.md`
   - `skills/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)

2. **If `$ARGUMENTS` is empty or "full"**: render the complete flywheel AND
   write `FLYWHEEL.md` to the project repo root (the working directory, NOT the
   skills repo).
   **If `$ARGUMENTS` names a phase**: render just that phase in detail (no file write).

3. **Render the map** using the formats below.

4. **Write `FLYWHEEL.md`** to 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 `/flywheel` on <date>. Run `/flywheel` for 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:
1. A header explaining what the flywheel is and how to use it
2. The compact flywheel diagram (mermaid)
3. The full expanded flywheel (mermaid)
4. The artifact map
5. A skill/agent reference table: name, one-line description, inputs, outputs
6. 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.