363 lines
22 KiB
Markdown
363 lines
22 KiB
Markdown
# Skill Flow Diagrams
|
||
|
||
Visual maps of how skills chain together across the 7 development phases.
|
||
These show what runs before and after each skill, and what artifacts flow between them.
|
||
|
||
---
|
||
|
||
## Full Pipeline Overview (Zero to Ship)
|
||
|
||
```
|
||
PHASE 1: CONCEPT
|
||
/start ──────────────────────────────────────────────────────► routes to A/B/C/D
|
||
/brainstorm ──────────────────────────────────────────────────► design/gdd/game-concept.md
|
||
/setup-engine ────────────────────────────────────────────────► CLAUDE.md + technical-preferences.md
|
||
/prototype [core-mechanic] ───────────────────────────────────► prototypes/[name]-concept/REPORT.md
|
||
│ PROCEED (validate idea BEFORE writing GDDs)
|
||
▼
|
||
/design-review [game-concept.md] ────────────────────────────► concept validated
|
||
/gate-check ─────────────────────────────────────────────────► PASS → advance to systems-design
|
||
│
|
||
▼
|
||
PHASE 2: SYSTEMS DESIGN
|
||
/map-systems ────────────────────────────────────────────────► design/gdd/systems-index.md
|
||
│
|
||
▼ (for each system, in dependency order)
|
||
/design-system [name] ──────────────────────────────────────► design/gdd/[system].md
|
||
/design-review [system].md ─────────────────────────────────► per-GDD review comments
|
||
│
|
||
▼ (after all MVP GDDs done)
|
||
/review-all-gdds ────────────────────────────────────────────► design/gdd/gdd-cross-review-[date].md
|
||
/gate-check ─────────────────────────────────────────────────► PASS → advance to technical-setup
|
||
│
|
||
▼
|
||
PHASE 3: TECHNICAL SETUP
|
||
/create-architecture ────────────────────────────────────────► docs/architecture/master.md
|
||
/architecture-decision (×N) ─────────────────────────────────► docs/architecture/[adr-nnn].md
|
||
/architecture-review ────────────────────────────────────────► review report + docs/architecture/tr-registry.yaml
|
||
/create-control-manifest ────────────────────────────────────► docs/architecture/control-manifest.md
|
||
/gate-check ─────────────────────────────────────────────────► PASS → advance to pre-production
|
||
│
|
||
▼
|
||
PHASE 4: PRE-PRODUCTION
|
||
[UX — before epics, so specs exist when stories are written]
|
||
/ux-design [screen/hud/patterns] ────────────────────────────► design/ux/*.md
|
||
/ux-review ──────────────────────────────────────────────────► UX specs approved (HARD gate for /team-ui)
|
||
|
||
[Test infrastructure — scaffold before stories reference tests]
|
||
/test-setup ─────────────────────────────────────────────────► test framework + CI/CD pipeline
|
||
/test-helpers ───────────────────────────────────────────────► tests/helpers/[engine-specific].gd
|
||
|
||
[Vertical slice — before epics, validate full game loop]
|
||
/vertical-slice ─────────────────────────────────────────────► prototypes/[name]-vertical-slice/REPORT.md
|
||
/playtest-report ────────────────────────────────────────────► production/playtests/
|
||
|
||
[Stories + sprint plan — only after vertical slice PROCEEDS]
|
||
/create-epics [layer] ───────────────────────────────────────► production/epics/*/EPIC.md
|
||
/create-stories [epic-slug] ─────────────────────────────────► production/epics/*/story-*.md
|
||
/sprint-plan new ────────────────────────────────────────────► production/sprints/sprint-01.md
|
||
/gate-check ─────────────────────────────────────────────────► PASS → advance to production
|
||
│
|
||
▼
|
||
PHASE 5: PRODUCTION (repeating sprint loop)
|
||
/sprint-status ──────────────────────────────────────────────► sprint snapshot
|
||
/story-readiness [story] ────────────────────────────────────► story validated READY
|
||
│
|
||
▼ (pick up and implement)
|
||
/dev-story [story] ──────────────────────────────────────────► routes to correct programmer agent
|
||
│
|
||
▼ (during implementation, as needed)
|
||
/code-review ────────────────────────────────────────────────► code review report
|
||
/scope-check ────────────────────────────────────────────────► scope creep detected / clear
|
||
/content-audit ──────────────────────────────────────────────► GDD content gaps identified
|
||
/bug-report ─────────────────────────────────────────────────► production/qa/bugs/bug-NNN.md
|
||
/bug-triage ─────────────────────────────────────────────────► bugs re-prioritized + assigned
|
||
|
||
[Team skills for feature areas — spawn when working a full feature]
|
||
/team-combat / /team-narrative / /team-ui / /team-level / /team-audio
|
||
|
||
[QA cycle per sprint]
|
||
/qa-plan ────────────────────────────────────────────────────► production/qa/qa-plan-sprint-NN.md
|
||
/smoke-check ────────────────────────────────────────────────► smoke test gate (PASS/FAIL)
|
||
/regression-suite ───────────────────────────────────────────► coverage gaps + missing regression tests
|
||
/test-evidence-review ───────────────────────────────────────► evidence quality report
|
||
/test-flakiness ─────────────────────────────────────────────► flaky test report
|
||
│
|
||
▼
|
||
/story-done [story] ─────────────────────────────────────────► story closed + next surfaced
|
||
/sprint-plan [next] ─────────────────────────────────────────► next sprint
|
||
│
|
||
▼ (after Production milestone)
|
||
/milestone-review ───────────────────────────────────────────► milestone report
|
||
/gate-check ─────────────────────────────────────────────────► PASS → advance to polish
|
||
│
|
||
▼
|
||
PHASE 6: POLISH
|
||
/perf-profile ───────────────────────────────────────────────► perf report + fixes
|
||
/balance-check ──────────────────────────────────────────────► balance report + fixes
|
||
/asset-audit ────────────────────────────────────────────────► asset compliance report
|
||
/tech-debt ──────────────────────────────────────────────────► docs/tech-debt-register.md
|
||
/soak-test ──────────────────────────────────────────────────► soak test protocol + results
|
||
/localize ───────────────────────────────────────────────────► localization readiness report
|
||
/team-polish ────────────────────────────────────────────────► polish sprint orchestrated
|
||
/team-qa ────────────────────────────────────────────────────► full QA cycle sign-off
|
||
/gate-check ─────────────────────────────────────────────────► PASS → advance to release
|
||
│
|
||
▼
|
||
PHASE 7: RELEASE
|
||
/launch-checklist ───────────────────────────────────────────► launch readiness report
|
||
/release-checklist ──────────────────────────────────────────► platform-specific checklist
|
||
/changelog ──────────────────────────────────────────────────► CHANGELOG.md
|
||
/patch-notes ────────────────────────────────────────────────► player-facing notes
|
||
/team-release ───────────────────────────────────────────────► release pipeline orchestrated
|
||
│
|
||
▼ (post-launch, ongoing)
|
||
/hotfix ─────────────────────────────────────────────────────► emergency fix with audit trail
|
||
/team-live-ops ──────────────────────────────────────────────► live-ops content plan
|
||
```
|
||
|
||
---
|
||
|
||
## Skill Chain: /design-system in Detail
|
||
|
||
How a single GDD gets authored, reviewed, and handed to architecture:
|
||
|
||
```
|
||
systems-index.md (input)
|
||
game-concept.md (input)
|
||
upstream GDDs (input, if any)
|
||
│
|
||
▼
|
||
/design-system [name]
|
||
│
|
||
├── Pre-check: feasibility table + engine risk flags
|
||
│
|
||
├── Section cycle × 8:
|
||
│ question → options → decision → draft → approval → WRITE
|
||
│ [each section written to file immediately after approval]
|
||
│
|
||
└── Output: design/gdd/[system].md (complete, all 8 sections)
|
||
│
|
||
▼
|
||
/design-review design/gdd/[system].md
|
||
│
|
||
├── APPROVED → mark DONE in systems-index, proceed to next system
|
||
├── NEEDS REVISION → agent shows specific issues, re-enter section cycle
|
||
└── MAJOR REVISION → significant redesign needed before next system
|
||
│
|
||
▼ (after all MVP GDDs + cross-review)
|
||
/review-all-gdds
|
||
│
|
||
└── Output: gdd-cross-review-[date].md
|
||
```
|
||
|
||
---
|
||
|
||
## Skill Chain: UX / UI Pipeline in Detail
|
||
|
||
UX specs are authored in Phase 4 (Pre-Production), before epics are written, so
|
||
that story acceptance criteria can reference specific UX artifacts.
|
||
|
||
```
|
||
design/gdd/*.md (UI/UX requirements extracted)
|
||
design/player-journey.md (emotional arc, if authored)
|
||
│
|
||
▼
|
||
/ux-design hud → design/ux/hud.md
|
||
/ux-design screen [name] → design/ux/screens/[name].md
|
||
/ux-design patterns → design/ux/interaction-patterns.md
|
||
│
|
||
▼
|
||
/ux-review design/ux/
|
||
│
|
||
├── APPROVED → UX specs ready, proceed to /create-epics
|
||
├── NEEDS REVISION → blocking issues listed → fix → re-run review
|
||
└── MAJOR REVISION → fundamental UX problems → redesign before epics
|
||
│
|
||
▼ (after APPROVED — in Phase 5 when implementing UI features)
|
||
/team-ui
|
||
│
|
||
├── Phase 1: /ux-design (if any specs still missing) + /ux-review
|
||
├── Phase 2: visual design (art-director)
|
||
├── Phase 3: layout implementation (ui-programmer)
|
||
├── Phase 4: accessibility audit (accessibility-specialist)
|
||
└── Phase 5: final review
|
||
|
||
Note: /ux-design and /ux-review belong in Phase 4 (Pre-Production).
|
||
/team-ui belongs in Phase 5 (Production) when a UI feature is being built.
|
||
```
|
||
|
||
---
|
||
|
||
## Skill Chain: Dev Story Flow in Detail
|
||
|
||
How a story moves from backlog to closed:
|
||
|
||
```
|
||
/story-readiness [story]
|
||
│
|
||
├── READY → Status: ready-for-dev → pick up for implementation
|
||
├── NEEDS WORK → agent shows specific gaps → resolve → re-run readiness
|
||
└── BLOCKED → ADR still Proposed, or upstream story incomplete
|
||
│
|
||
▼ (after READY)
|
||
/dev-story [story]
|
||
│
|
||
├── Reads: story file, linked GDD requirement, ADR decisions, control manifest
|
||
├── Routes to: gameplay-programmer / engine-programmer / ui-programmer / etc.
|
||
│
|
||
└── Implementation begins
|
||
│
|
||
▼ (optional, during/after implementation)
|
||
/code-review → architectural review of changeset
|
||
/scope-check → verify no scope creep vs. original story criteria
|
||
/test-evidence-review → validate test files and manual evidence quality
|
||
│
|
||
▼
|
||
/story-done [story]
|
||
│
|
||
├── COMPLETE → Status: Complete, sprint-status.yaml updated, next story surfaced
|
||
├── COMPLETE WITH NOTES → complete but some criteria deferred (logged)
|
||
└── BLOCKED → acceptance criteria cannot be verified → investigate blocker
|
||
```
|
||
|
||
---
|
||
|
||
## Skill Chain: Story Lifecycle (Backlog to Closed)
|
||
|
||
How a story gets from backlog to closed (summary view):
|
||
|
||
```
|
||
/create-epics [layer]
|
||
│
|
||
└── Output: production/epics/[slug]/EPIC.md
|
||
│
|
||
▼
|
||
/create-stories [epic-slug]
|
||
│
|
||
└── Output: production/epics/[slug]/story-NNN-[slug].md
|
||
(Status: Ready or Blocked if ADR is Proposed)
|
||
│
|
||
▼
|
||
/story-readiness [story]
|
||
│
|
||
├── READY → /dev-story → implement → /story-done
|
||
├── NEEDS WORK → resolve gaps → re-run
|
||
└── BLOCKED → fix upstream dependency first
|
||
```
|
||
|
||
---
|
||
|
||
## Skill Chain: QA Pipeline in Detail
|
||
|
||
```
|
||
[Phase 4 — one-time infrastructure setup]
|
||
/test-setup ────────────────────────────────────────────────────► test framework scaffolded + CI/CD wired
|
||
/test-helpers ──────────────────────────────────────────────────► tests/helpers/[engine].gd (GDUnit4, NUnit, etc.)
|
||
|
||
[Phase 5 — per-sprint QA cycle]
|
||
/qa-plan [sprint or feature]
|
||
│
|
||
├── Reads: story files, GDDs, acceptance criteria
|
||
├── Classifies each story by test type:
|
||
│ Logic → automated unit test (BLOCKING)
|
||
│ Integration → integration test or documented playtest (BLOCKING)
|
||
│ Visual/Feel → screenshot + lead sign-off (ADVISORY)
|
||
│ UI → manual walkthrough or interaction test (ADVISORY)
|
||
│ Config/Data → smoke check (ADVISORY)
|
||
└── Output: production/qa/qa-plan-sprint-NN.md
|
||
│
|
||
▼
|
||
/smoke-check
|
||
│
|
||
├── PASS → QA hand-off cleared
|
||
└── FAIL → block sprint close → fix critical paths first
|
||
│
|
||
▼
|
||
/regression-suite
|
||
│
|
||
└── Coverage gaps + list of fixed bugs without regression tests
|
||
│
|
||
▼
|
||
/test-evidence-review
|
||
│
|
||
└── Validates evidence quality, not just existence
|
||
│
|
||
▼ (if CI run history available)
|
||
/test-flakiness
|
||
│
|
||
└── Flaky test report + fix recommendations
|
||
|
||
[Phase 6 — extended stability testing]
|
||
/soak-test ─────────────────────────────────────────────────────► soak test protocol + observed results
|
||
/team-qa ───────────────────────────────────────────────────────► full QA cycle sign-off for release gate
|
||
|
||
[Ongoing — bug management]
|
||
/bug-report ────────────────────────────────────────────────────► production/qa/bugs/bug-NNN.md
|
||
/bug-triage ────────────────────────────────────────────────────► open bugs re-prioritized + assigned
|
||
|
||
[Meta — harness validation]
|
||
/skill-test [lint|spec|catalog] ────────────────────────────────► skill file structural + behavioral check
|
||
```
|
||
|
||
---
|
||
|
||
## Brownfield Onboarding Flow
|
||
|
||
For projects with existing work (use `/start` option D or run directly):
|
||
|
||
```
|
||
/project-stage-detect → stage detection report
|
||
│
|
||
▼
|
||
/adopt
|
||
│
|
||
├── Phase 1: detect what exists
|
||
├── Phase 2: FORMAT audit (not just existence)
|
||
├── Phase 3: classify gaps (BLOCKING / HIGH / MEDIUM / LOW)
|
||
├── Phase 4: ordered migration plan
|
||
├── Phase 5: write docs/adoption-plan-[date].md
|
||
└── Phase 6: fix most urgent gap inline (optional)
|
||
│
|
||
▼
|
||
/design-system retrofit [path] → fills missing GDD sections
|
||
/architecture-decision retrofit [path] → fills missing ADR sections
|
||
/gate-check → where are you in the pipeline?
|
||
```
|
||
|
||
---
|
||
|
||
## How to Read These Diagrams
|
||
|
||
| Symbol | Meaning |
|
||
|--------|---------|
|
||
| `──►` | Produces this artifact |
|
||
| `│ ▼` | Flows into next step |
|
||
| `├──` | Branch (multiple possible outcomes) |
|
||
| `×N` | Runs N times (once per system, story, etc.) |
|
||
| `(input)` | Read by the skill but not produced here |
|
||
| `[optional]` | Not required for the gate to pass |
|
||
| `WRITE` (caps) | File written to disk immediately |
|
||
|
||
---
|
||
|
||
## Common Entry Points
|
||
|
||
| Where you are | Run this |
|
||
|---------------|---------|
|
||
| Brand new, no idea | `/start` → `/brainstorm` |
|
||
| Have a concept, no engine | `/setup-engine` |
|
||
| Have concept + engine | `/map-systems` |
|
||
| Mid-systems design | `/design-system [next system]` or `/map-systems next` |
|
||
| All GDDs done | `/review-all-gdds` → `/gate-check` |
|
||
| In technical setup | `/create-architecture` → `/architecture-decision` |
|
||
| Starting UX design | `/ux-design screen [name]` or `/ux-design hud` |
|
||
| Scaffolding tests | `/test-setup` → `/test-helpers` |
|
||
| Have stories, ready to code | `/story-readiness [story]` → `/dev-story [story]` |
|
||
| Story done | `/story-done [story]` |
|
||
| Running QA for a sprint | `/qa-plan` → `/smoke-check` → `/regression-suite` |
|
||
| Bug backlog needs sorting | `/bug-triage` |
|
||
| Extended stability testing | `/soak-test` |
|
||
| Not sure | `/help` |
|
||
| Existing project | `/adopt` |
|