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