diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 50266e3..a851c30 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,7 +12,7 @@ "name": "bmad-game-dev-studio", "source": "./", "description": "A comprehensive game development module with agents and workflows for preproduction, design, architecture, production, and testing across Unity, Unreal, and Godot. Part of the BMad Method ecosystem.", - "version": "0.2.4", + "version": "0.3.0", "author": { "name": "Brian (BMad) Madison" }, @@ -20,8 +20,6 @@ "./src/agents/gds-agent-game-architect", "./src/agents/gds-agent-game-designer", "./src/agents/gds-agent-game-dev", - "./src/agents/gds-agent-game-qa", - "./src/agents/gds-agent-game-scrum-master", "./src/agents/gds-agent-game-solo-dev", "./src/agents/gds-agent-tech-writer", "./src/workflows/1-preproduction/gds-brainstorm-game", @@ -29,7 +27,12 @@ "./src/workflows/1-preproduction/research/gds-domain-research", "./src/workflows/2-design/gds-create-gdd", "./src/workflows/2-design/gds-create-narrative", + "./src/workflows/2-design/gds-create-prd", "./src/workflows/2-design/gds-create-ux-design", + "./src/workflows/2-design/gds-edit-gdd", + "./src/workflows/2-design/gds-edit-prd", + "./src/workflows/2-design/gds-validate-gdd", + "./src/workflows/2-design/gds-validate-prd", "./src/workflows/3-technical/gds-check-implementation-readiness", "./src/workflows/3-technical/gds-create-epics-and-stories", "./src/workflows/3-technical/gds-game-architecture", @@ -49,9 +52,7 @@ "./src/workflows/gametest/gds-test-framework", "./src/workflows/gametest/gds-test-review", "./src/workflows/gds-document-project", - "./src/workflows/gds-quick-flow/gds-quick-dev", - "./src/workflows/gds-quick-flow/gds-quick-dev-new-preview", - "./src/workflows/gds-quick-flow/gds-quick-spec" + "./src/workflows/gds-quick-flow/gds-quick-dev" ] } ] diff --git a/CHANGELOG.md b/CHANGELOG.md index 9446777..cb55181 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,25 @@ # CHANGELOG +## v0.3.0 - Apr 14, 2026 — sync with BMAD-METHOD v6.3.0 + +### Phase 4 agent consolidation + +* Merged `gds-agent-game-qa` (GLaDOS) and `gds-agent-game-scrum-master` (Max) into `gds-agent-game-dev` (Link Freeman). Mirrors upstream BMAD-METHOD's collapse of QA and Scrum Master agents into a single Developer agent (upstream PRs #2179, #2186). Link now owns all scrum-master, development and QA capabilities — 16 roles in one agent. +* `src/gametest/` (17 testing knowledge fragments + `qa-index.csv`) relocated to `src/agents/gds-agent-game-dev/gametest/`. Path references updated from `{module_root}/gametest/` to `{skill_root}/gametest/`. Reason: `_bmad-output/` is being deprecated as a runtime location requirement; QA knowledge lives with the agent that uses it. + +### Quick-dev update + +* Updated `gds-quick-dev` to match improvements from `bmad-quick-dev` : a hardened clarify → plan → implement → review → present flow with a `step-oneshot.md` variant. Adds `compile-epic-context.md` and `sync-sprint-status.md` helpers. + +### PRD + GDD split into 3-skill structures + +* PRD split: consolidated `create-prd/` (with `workflow-create-prd.md`, `workflow-edit-prd.md`, `workflow-validate-prd.md` and shared `steps-c/`, `steps-e/`, `steps-v/`) split into independent skill dirs — `gds-create-prd`, `gds-edit-prd`, `gds-validate-prd`. Each has its own `SKILL.md` and `workflow.md`. Mirrors upstream's 3-skill PRD layout. Note that creating a PRD in GDS is optional - it's included for compatibility with external tools that expect it. +* GDD split: `gds-create-gdd/steps/` renamed to `steps-c/` for parity. New `gds-edit-gdd` and `gds-validate-gdd` skills added as structural placeholders that delegate to their PRD counterparts pending GDD-specific step-body authoring (tracked in `TODO.md`). + +### Phase 4 workflow mirror + +* All seven production-phase skills — `gds-code-review`, `gds-correct-course`, `gds-create-story`, `gds-dev-story`, `gds-retrospective`, `gds-sprint-planning`, `gds-sprint-status` — ported from upstream Phase 4 counterparts. `gds-code-review` adopts upstream's step-file architecture (`steps/step-01..04`). Config paths unified to `{module_config}`; all `bmad-agent-dev` references rewritten to `gds-agent-game-dev`. + ## v0.2.4 - Apr 1, 2026 ### Decouple Skills from \_bmad/ Install Directory diff --git a/README.md b/README.md index ab9e60d..5d84ce0 100644 --- a/README.md +++ b/README.md @@ -113,7 +113,7 @@ BMGD: Great choice! Here's what I recommend... ## Support BMad -BMad is free for everyone and always will be. Star this repo, [buy me a coffee](https://buymeacoffee.com/bmad), or email contact@bmadcode.com for corporate sponsorship. +BMad is free for everyone and always will be. Star this repo, [buy me a coffee](https://buymeacoffee.com/bmad), or email for corporate sponsorship. ## License diff --git a/SYNC-PLAN.md b/SYNC-PLAN.md new file mode 100644 index 0000000..39253a8 --- /dev/null +++ b/SYNC-PLAN.md @@ -0,0 +1,260 @@ +# Game-Dev Studio Sync Plan — 2026-04-14 + +Syncing `bmad-module-game-dev-studio` against `bmad-code-org/BMAD-METHOD@main` (`6b964acd`, post-v6.3.0). + +## Architectural guardrail — DO NOT touch + +Upstream lives under `src/bmm-skills/{1-analysis,2-plan-workflows,3-solutioning,4-implementation}/` plus `src/core-skills/`. Game-dev lives under `src/workflows/{1-preproduction,2-design,3-technical,4-production,gametest,gds-quick-flow,gds-document-project}/` plus `src/agents/` and `src/gametest/`. + +**This sync preserves game-dev's top-level organization.** We port *content and skill-directory shape* within the existing tree; we do not relocate into `src/bmm-skills/`. + +--- + +## Decisions locked in 2026-04-14 + +**Agents (Phase 4 mirror):** Merge `gds-agent-game-qa` and `gds-agent-game-scrum-master` into `gds-agent-game-dev`. Upstream collapsed to a single Developer agent (commits `48c2324b` / `003c979d`) — Phase 4 of game-dev will follow. Phases 1–3 agents (designer, architect, solo-dev, tech-writer) remain distinct. + +**quick-dev:** Delete `gds-quick-dev` and `gds-quick-spec` entirely. Port upstream `bmad-quick-dev` 1:1 as the replacement. No chain, no overlap-preservation. + +**gametest relocation:** Move `src/gametest/` (the knowledge base + `qa-index.csv`) into `src/agents/gds-agent-game-dev/gametest/`. Reason: `_bmad-output/` is being deprecated as a runtime location; knowledge the dev agent uses should live with the dev agent. `src/workflows/gametest/` (the 7 test workflows) stays where it is. + +--- + +## Phase 1 — quick-dev full replacement + quick-flow cleanup + +### Scope + +- **Delete** `src/workflows/gds-quick-flow/gds-quick-dev/` (all current content — divergent enough that no salvage is useful) +- **Delete** `src/workflows/gds-quick-flow/gds-quick-spec/` (redundant once upstream's bmad-quick-dev is ported; upstream absorbs spec generation into `step-02-plan`) +- **Delete** `src/workflows/gds-quick-flow/gds-quick-dev-new-preview/` (already-approved cleanup) +- **Port** upstream `bmad-quick-dev` 1:1 to a new `src/workflows/gds-quick-flow/gds-quick-dev/` + +### Upstream source + +`src/bmm-skills/4-implementation/bmad-quick-dev/` — 11 files, flat layout: +- `SKILL.md`, `workflow.md`, `spec-template.md`, `step-oneshot.md` +- `step-01-clarify-and-route.md`, `step-02-plan.md`, `step-03-implement.md`, `step-04-review.md`, `step-05-present.md` +- `compile-epic-context.md`, `sync-sprint-status.md` + +### Adaptation work during port + +Copy upstream files as-is, then rewrite references for game-dev context: +- `_bmad/bmm/` → `_bmad/gds/` config paths +- `bmad-agent-dev` → `gds-agent-game-dev` +- Any `{module_root}` resolutions to point at game-dev module structure +- Preserve upstream step names, structure, and framing ("hardened, reviewable artifact") + +After port, verify `gds-quick-flow/` only contains the new `gds-quick-dev/`. The flow folder may eventually collapse to just the skill itself — flag in `TODO.md` if it does. + +### Phase 1 verification + +- `npm run lint:md` clean +- `gds-quick-dev` resolves via installer (manual `npx bmad-method install` smoke test) +- Grep confirms zero refs to `gds-quick-spec` or `gds-quick-dev-new-preview` remain in `src/` + +--- + +## Phase 2 — PRD + GDD skill split + +### Upstream shape + +``` +src/bmm-skills/2-plan-workflows/ +├── bmad-create-prd/ (SKILL.md, workflow.md, steps-c/, data/, templates/) +├── bmad-edit-prd/ (SKILL.md, workflow.md, steps-e/, data/prd-purpose.md) ← NEW data file +└── bmad-validate-prd/ (SKILL.md, workflow.md, steps-v/) +``` + +`bmad-edit-prd` just gained new step files (`step-e-01-discovery.md`, `step-e-01b-legacy-conversion.md`, `step-e-02-review.md`, `step-e-03-edit.md`, `step-e-04-complete.md`) and a new `data/prd-purpose.md` reference. Upstream `bmad-create-prd/steps-c/step-08-scoping.md` and `step-11-polish.md` also changed. + +### Game-dev current shape + +**PRD is consolidated** at `src/workflows/2-design/create-prd/`: +``` +create-prd/ +├── bmad-skill-manifest.yaml (no SKILL.md!) +├── data/, templates/ +├── steps-c/, steps-e/, steps-v/ +├── workflow-create-prd.md +├── workflow-edit-prd.md +└── workflow-validate-prd.md +``` + +**GDD is a single skill** at `src/workflows/2-design/gds-create-gdd/` with `steps/` (14 step files) — no edit or validate variant. + +### Plan + +**2a. Split PRD into 3 skill dirs:** + +``` +src/workflows/2-design/ +├── gds-create-prd/ (from workflow-create-prd.md + steps-c/ + shared data/templates) +├── gds-edit-prd/ (from workflow-edit-prd.md + steps-e/; port upstream step-e-* updates + prd-purpose.md) +└── gds-validate-prd/ (from workflow-validate-prd.md + steps-v/) +``` + +Each gets `SKILL.md` + `bmad-skill-manifest.yaml`. Shared `data/` and `templates/` stay deduplicated where possible (symlink or copy-with-note). + +**2b. Mirror the same split for GDD** (user-approved — "GDD is used as PRD by default in gds"): + +``` +src/workflows/2-design/ +├── gds-create-gdd/ (existing, rename steps/ → steps-c/ for consistency) +├── gds-edit-gdd/ (NEW — model on gds-edit-prd; port step-e pattern, adapt to game-design content) +└── gds-validate-gdd/ (NEW — model on gds-validate-prd; adapt AC and quality checks to GDD structure) +``` + +This is the **biggest net-new content** in the sync. `gds-edit-gdd` and `gds-validate-gdd` do not exist today. + +**2c. Port upstream content changes:** +- `bmad-create-prd/steps-c/step-08-scoping.md` (93 line change) and `step-11-polish.md` → into `gds-create-prd/steps-c/` equivalents +- `bmad-edit-prd/data/prd-purpose.md` (197 new lines) → into `gds-edit-prd/data/` (and optionally `gds-edit-gdd/data/gdd-purpose.md` as a parallel) +- All `step-e-*` file updates → `gds-edit-prd/steps-e/` + +### Phase 2 verification + +- All three PRD skills resolve via installer +- GDD edit + validate stubs compile (OK if step bodies are initially lean — flag in `TODO.md`) + +--- + +## Phase 2.5 — Agent merge + gametest relocation + +### Agent merge + +Goal: mirror upstream's single-Developer-agent model for Phase 4 roles. + +1. **Capabilities audit** — read: + - `src/agents/gds-agent-game-qa/SKILL.md` (Quinn-equivalent; owns QA knowledge lookup) + - `src/agents/gds-agent-game-scrum-master/SKILL.md` (Bob-equivalent; owns sprint/story ceremony) + - Upstream `bmad-agent-dev/SKILL.md` post-merge (shows how QA was absorbed — party-mode and generate-e2e-tests references preserved) +2. **Merge into `src/agents/gds-agent-game-dev/SKILL.md`:** + - Keep Link Freeman persona; append QA + SM capability sections under `## Capabilities` + - Pull QA-specific critical actions (knowledge-fragment lookup via `gametest/qa-index.csv` — see relocation below) + - Pull SM-specific critical actions (sprint-status sync, story-file ownership) + - Update `description` frontmatter to note combined role without losing Link Freeman trigger phrase +3. **Delete** `src/agents/gds-agent-game-qa/` and `src/agents/gds-agent-game-scrum-master/` directories entirely +4. **Global reference sweep:** + - grep `src/` for `gds-agent-game-qa` and `gds-agent-game-scrum-master` — redirect every hit to `gds-agent-game-dev` + - Expected hit sites: workflows in `4-production/` (sprint planning/status/retro reference SM), `gametest/` workflows (reference QA), `module-help.csv`, `bmad-skill-manifest.yaml` files +5. **`module.yaml` + `module-help.csv`** — remove dropped agents; update agent registry + +### gametest relocation + +Move knowledge base from `src/gametest/` to `src/agents/gds-agent-game-dev/gametest/`. + +1. Move: + - `src/gametest/knowledge/*.md` (17 files) → `src/agents/gds-agent-game-dev/gametest/knowledge/` + - `src/gametest/qa-index.csv` → `src/agents/gds-agent-game-dev/gametest/qa-index.csv` +2. Delete empty `src/gametest/` directory +3. **Path rewrites** — grep `src/` for: + - `{module_root}/gametest/` → `{skill_root}/gametest/` (or `{agents_root}/gds-agent-game-dev/gametest/` depending on which variable resolves correctly at install time — verify with upstream's path-resolver convention) + - `gametest/qa-index.csv` (bare) → new path + - `gametest/knowledge/` (bare) → new path + - Known hit sites to verify: `src/workflows/gametest/gds-test-design/test-design-template.md:205`, former `gds-agent-game-qa/SKILL.md:30,33` content now living in `gds-agent-game-dev/SKILL.md` +4. `_bmad-output` references (currently 1 hit in `gds-code-review/workflow.md:20`) — review with user in Phase 4 whether to remove the explicit exclusion comment since `_bmad-output` is being deprecated (leave for now; it's informational) + +### Phase 2.5 verification + +- No lingering refs to `gds-agent-game-qa`, `gds-agent-game-scrum-master` in `src/` (grep exits with no matches) +- No lingering refs to `src/gametest/` or `{module_root}/gametest/` at the old location +- `gds-agent-game-dev/SKILL.md` parses; frontmatter valid +- Installer smoke test loads combined agent + gametest knowledge correctly + +--- + +## Phase 3 — Production-phase steps/ backfill + +### Current state (game-dev, no `steps/` subdir) + +- `src/workflows/4-production/gds-code-review/` +- `src/workflows/4-production/gds-correct-course/` +- `src/workflows/4-production/gds-create-story/` +- `src/workflows/4-production/gds-dev-story/` +- `src/workflows/4-production/gds-retrospective/` +- `src/workflows/4-production/gds-sprint-planning/` +- `src/workflows/4-production/gds-sprint-status/` + +### Upstream source to port from + +- `bmad-code-review/steps/{step-01-gather-context.md, step-02-review.md, step-04-present.md}` — recently updated +- `bmad-correct-course/workflow.md` + `checklist.md` — updated +- `bmad-retrospective/workflow.md` — updated (268-line change; substantial rewrite) +- `bmad-sprint-planning/workflow.md`, `bmad-sprint-status/workflow.md` — minor +- `bmad-create-story`, `bmad-dev-story` — no `steps/` upstream either (skip) + +### Plan + +For each game-dev skill above, create a `steps/` subdir matching upstream's step decomposition. Copy step file contents, rewrite references to: +- `_bmad/bmm/...` → `_bmad/gds/...` +- `bmad-agent-dev` → `gds-agent-game-dev` +- `gds-agent-game-qa` / `gds-agent-game-scrum-master` refs → `gds-agent-game-dev` (per Phase 2.5 — should already be clean by the time Phase 3 runs) +- Any terminology swap (story → game-story where appropriate) + +Update each `workflow.md` to reference the new step files if it currently inlines everything. + +### Phase 3 verification + +- `npm test` in game-dev repo passes +- Each skill's `workflow.md` correctly references its new `steps/*.md` via relative paths + +--- + +## Phase 4 — Manifest + module.yaml audit + +### Scope + +- `src/module.yaml` — compare schema against upstream's `src/bmm-skills/module.yaml` and `src/core-skills/module.yaml`; harmonize field set +- Every `bmad-skill-manifest.yaml` under `src/workflows/**/` and `src/agents/**/` — validate against upstream skill-manifest schema (whatever `tools/validate-skills.js` in upstream expects) +- `src/module-help.csv` — regenerate from skill frontmatter (post-agent-merge; drops QA + SM entries) +- Any dangling references to `bmad-agent-qa` / `bmad-agent-sm` / `bmad-init` in copied content → clean up + +### Plan + +1. Run upstream's `tools/validate-skills.js` against game-dev `src/` (adapt path config) +2. Regenerate `module-help.csv` from SKILL.md frontmatter +3. Diff `module.yaml` schema against upstream; add missing fields with game-dev values +4. grep game-dev for `bmad-agent-qa`, `bmad-agent-sm`, `bmad-init` (removed in #2159) — clean up refs + +### Phase 4 verification + +- `npm run lint` + `npm run lint:md` + `npm run format:check` clean +- Validate-skills script exits 0 + +--- + +## Phase 5 — Cleanup + +- `src/workflows/gds-quick-flow/gds-quick-dev-new-preview/`, `gds-quick-spec/`, and original `gds-quick-dev/` should already be gone from Phase 1 +- `src/agents/gds-agent-game-qa/` and `src/agents/gds-agent-game-scrum-master/` should already be gone from Phase 2.5 +- `src/gametest/` should already be gone from Phase 2.5 +- Delete stale `install-success-message.md`, `codex-review.md` at repo root if superseded (check git log first) +- Update `TODO.md` with any known-deferred items (incomplete GDD edit/validate step bodies, etc.) +- Update `CHANGELOG.md` with sync summary + +--- + +## Out of scope (deferred) + +- Restructuring `src/workflows/` → `src/bmm-skills/` (game-dev's top-level org is intentional) +- Adding `gds-help` and `gds-party-mode` (user skipped) +- Editorial/adversarial review skills (`bmad-editorial-review-*`, `bmad-review-adversarial-general`, `bmad-review-edge-case-hunter`) — not requested; flag in `TODO.md` for future +- Full `src/workflows/gametest/` relocation into the dev agent (out of scope for this sync; only the knowledge-base `src/gametest/` moves) +- Whether `gds-quick-flow/` parent directory survives long-term (flag for follow-up) + +--- + +## Execution order + checkpoints + +All pre-flight decisions are locked in. Recommend phase-by-phase execution with a commit between each: + +1. Phase 1 (quick-dev full replacement + delete quick-spec + delete new-preview) — commit +2. Phase 2a (PRD split into 3 skill dirs) — commit +3. Phase 2b (GDD split into 3 skill dirs) — commit +4. Phase 2c (port upstream PRD content updates — step-08-scoping, step-11-polish, step-e-*, prd-purpose.md) — commit +5. Phase 2.5 (agent merge QA+SM→dev; relocate `src/gametest/` into `gds-agent-game-dev/gametest/`) — commit +6. Phase 3 (production steps/ backfill; agent refs already clean from 2.5) — commit +7. Phase 4 (manifest audit + module-help.csv regen + final cleanup) — commit +8. Full `npm test` run + manual `npx bmad-method install` smoke test into a scratch dir → push + +Each phase is independently revertible via `git revert`. diff --git a/TODO.md b/TODO.md index 88667dd..2817efa 100644 --- a/TODO.md +++ b/TODO.md @@ -1,4 +1,5 @@ # TODO - what's on BMGD's schedule * Adapt document-project workflow to BMGD -* Add and adapt research agents to pre-production (either to designer agent or new analyst agent) \ No newline at end of file +* Add and adapt research agents to pre-production (either to designer agent or new analyst agent) +* Review whether `src/workflows/gds-quick-flow/` parent directory still earns its keep now that it contains only `gds-quick-dev/`. Candidate: promote `gds-quick-dev` up to `src/workflows/4-production/` or similar and retire the `gds-quick-flow/` wrapper. \ No newline at end of file diff --git a/docs/reference/agents.md b/docs/reference/agents.md index e7b2f36..6add116 100644 --- a/docs/reference/agents.md +++ b/docs/reference/agents.md @@ -2,20 +2,21 @@ title: "BMGD Agents Guide" --- -Complete reference for BMGD's six specialized game development agents. +Complete reference for BMGD's five specialized game development agents. ## Agent Overview -BMGD provides six agents, each with distinct expertise: +BMGD provides five agents, each with distinct expertise: | Agent | Name | Role | Phase Focus | |-------|------|------|-------------| | **Game Designer** | Samus Shepard | Lead Game Designer + Creative Vision Architect | Phases 1-2 | | **Game Architect** | Cloud Dragonborn | Principal Game Systems Architect + Technical Director | Phase 3 | -| **Game Developer** | Link Freeman | Senior Game Developer + Technical Implementation Specialist | Phase 4 | -| **Game Scrum Master** | Max | Game Development Scrum Master + Sprint Orchestrator | Phase 4 | -| **Game QA** | GLaDOS | Game QA Architect + Test Automation Specialist | All Phases | +| **Game Developer** | Link Freeman | Senior Game Developer + Sprint Orchestrator + QA Lead | Phase 4 + Testing | | **Game Solo Dev** | Indie | Elite Indie Game Developer + Quick Flow Specialist | All Phases | +| **Tech Writer** | Paige | Technical Writer | All Phases | + +> **v0.3.0 consolidation note.** The previous Game Scrum Master (Max) and Game QA (GLaDOS) agents were merged into Game Developer (Link Freeman) to mirror upstream BMAD-METHOD's single-developer-agent model. Link now owns sprint orchestration, story creation, retrospectives, and the full game-testing toolchain. ## Game Designer (Samus Shepard) @@ -99,15 +100,17 @@ Speaks like a wise sage from an RPG - calm, measured, uses architectural metapho ### Role -Senior Game Developer + Technical Implementation Specialist +Senior Game Developer + Sprint Orchestrator + QA Lead + +> Consolidated Phase 4 agent. In v0.3.0 the previous Scrum Master (Max) and QA (GLaDOS) agents were merged here — Link now owns the full Phase 4 loop plus the game-testing toolchain. ### Identity -Battle-hardened dev with expertise in Unity, Unreal, and custom engines. Ten years shipping across mobile, console, and PC. Writes clean, performant code. +Battle-hardened dev with expertise in Unity, Unreal, and custom engines. Ten years shipping across mobile, console, and PC. Writes clean, performant code — and the tests that prove it. Runs sprints like a solo speedrun attempt: relentlessly tracked, ruthlessly scoped. ### Communication Style -Speaks like a speedrunner - direct, milestone-focused, always optimizing for the fastest path to ship. +Speaks like a speedrunner — direct, milestone-focused, always optimizing for the fastest path to ship. Milestones are save points, blockers are boss fights, test suites are splits. ### Core Principles @@ -115,118 +118,47 @@ Speaks like a speedrunner - direct, milestone-focused, always optimizing for the - Write code designers can iterate without fear - Ship early, ship often, iterate on player feedback - Red-green-refactor: tests first, implementation second - -### When to Use - -- Implementing stories -- Code reviews -- Performance optimization -- Completing story work - -### Available Commands - -| Command | Description | -| ---------------------- | ------------------------------- | -| `workflow-status` | Check sprint progress | -| `dev-story` | Implement story tasks | -| `code-review` | Perform code review | -| `quick-dev` | Flexible development (IDE only) | -| `quick-prototype` | Rapid prototyping (IDE only) | -| `party-mode` | Multi-agent collaboration | -| `advanced-elicitation` | Deep exploration (web only) | - -## Game Scrum Master (Max) - -### Role - -Game Development Scrum Master + Sprint Orchestrator - -### Identity - -Certified Scrum Master specializing in game dev workflows. Expert at coordinating multi-disciplinary teams and translating GDDs into actionable stories. - -### Communication Style - -Talks in game terminology - milestones are save points, handoffs are level transitions, blockers are boss fights. - -### Core Principles - -- Every sprint delivers playable increments -- Clean separation between design and implementation -- Keep the team moving through each phase -- Stories are single source of truth for implementation - -### When to Use - -- Sprint planning and management -- Creating epic tech specs -- Writing story drafts -- Assembling story context -- Running retrospectives -- Handling course corrections - -### Available Commands - -| Command | Description | -| ----------------------- | ------------------------------------------- | -| `workflow-status` | Check project status | -| `sprint-planning` | Generate/update sprint status | -| `sprint-status` | View sprint progress, get next action | -| `create-story` | Create story (marks ready-for-dev directly) | -| `validate-create-story` | Validate story draft | -| `epic-retrospective` | Facilitate retrospective | -| `correct-course` | Navigate significant changes | -| `party-mode` | Multi-agent collaboration | -| `advanced-elicitation` | Deep exploration (web only) | - -## Game QA (GLaDOS) - -### Role - -Game QA Architect + Test Automation Specialist - -### Identity - -Senior QA architect with 12+ years in game testing across Unity, Unreal, and Godot. Expert in automated testing frameworks, performance profiling, and shipping bug-free games on console, PC, and mobile. - -### Communication Style - -Speaks like a quality guardian - methodical, data-driven, but understands that "feel" matters in games. Uses metrics to back intuition. "Trust, but verify with tests." - -### Core Principles - - Test what matters: gameplay feel, performance, progression -- Automated tests catch regressions, humans catch fun problems - Every shipped bug is a process failure, not a people failure -- Flaky tests are worse than no tests - they erode trust -- Profile before optimize, test before ship +- Flaky tests are worse than no tests — they erode trust +- Every sprint delivers playable increments +- Stories are the single source of truth for implementation ### When to Use -- Setting up test frameworks -- Designing test strategies -- Creating automated tests -- Planning playtesting sessions -- Performance testing -- Reviewing test coverage +- Implementing stories and code reviews +- Sprint planning, sprint status, and retrospectives +- Creating stories from GDDs/epics +- Performance optimization +- Course corrections during a sprint +- Setting up test frameworks and automation +- Designing test strategies, playtests, and performance profiling ### Available Commands -| Command | Description | -| ---------------------- | --------------------------------------------------- | -| `workflow-status` | Check project status | -| `test-framework` | Initialize game test framework (Unity/Unreal/Godot) | -| `test-design` | Create comprehensive game test scenarios | -| `automate` | Generate automated game tests | -| `playtest-plan` | Create structured playtesting plan | -| `performance-test` | Design performance testing strategy | -| `test-review` | Review test quality and coverage | -| `party-mode` | Multi-agent collaboration | -| `advanced-elicitation` | Deep exploration (web only) | +| Command | Description | +| ---------------------- | ---------------------------------------------------------- | +| `dev-story` | Implement story tasks | +| `code-review` | Perform clean-context QA code review | +| `quick-dev` | Clarify → plan → implement → review → present (any intent) | +| `quick-prototype` | Rapid prototyping (IDE only) | +| `create-story` | Create a story with full context for implementation | +| `sprint-planning` | Generate or update sprint status | +| `sprint-status` | View sprint progress, surface risks, get next action | +| `correct-course` | Navigate significant changes during a sprint | +| `epic-retrospective` | Facilitate retrospective after an epic completes | +| `test-framework` | Initialize game test framework (Unity/Unreal/Godot) | +| `test-design` | Create comprehensive game test scenarios | +| `automate` | Generate automated game tests | +| `e2e-scaffold` | Scaffold E2E testing infrastructure | +| `playtest-plan` | Create structured playtesting plan | +| `performance-test` | Design performance testing strategy | +| `test-review` | Review test quality and coverage | +| `advanced-elicitation` | Deep exploration (web only) | ### Knowledge Base -GLaDOS has access to a comprehensive game testing knowledge base (`gametest/qa-index.csv`) including: +Link has access to a comprehensive game testing knowledge base bundled into the agent at `src/agents/gds-agent-game-dev/gametest/qa-index.csv`, including: **Engine-Specific Testing:** @@ -313,34 +245,34 @@ Use **Full BMGD workflow** when: ### By Phase -| Phase | Primary Agent | Secondary Agent | -| ------------------------------ | ----------------- | ----------------- | -| 1: Preproduction | Game Designer | - | -| 2: Design | Game Designer | - | -| 3: Technical | Game Architect | Game QA | -| 4: Production (Planning) | Game Scrum Master | Game Architect | -| 4: Production (Implementation) | Game Developer | Game Scrum Master | -| Testing (Any Phase) | Game QA | Game Developer | +| Phase | Primary Agent | Secondary Agent | +| ------------------------------ | -------------- | --------------- | +| 1: Preproduction | Game Designer | - | +| 2: Design | Game Designer | - | +| 3: Technical | Game Architect | Game Developer | +| 4: Production (Planning) | Game Developer | Game Architect | +| 4: Production (Implementation) | Game Developer | - | +| Testing (Any Phase) | Game Developer | - | ### By Task -| Task | Best Agent | -| -------------------------------- | ----------------- | -| "I have a game idea" | Game Designer | -| "Help me design my game" | Game Designer | -| "How should I build this?" | Game Architect | -| "What's the technical approach?" | Game Architect | -| "Plan our sprints" | Game Scrum Master | -| "Create implementation stories" | Game Scrum Master | -| "Build this feature" | Game Developer | -| "Review this code" | Game Developer | -| "Set up testing framework" | Game QA | -| "Create test plan" | Game QA | -| "Test performance" | Game QA | -| "Plan a playtest" | Game QA | -| "I'm working solo" | Game Solo Dev | -| "Quick prototype this idea" | Game Solo Dev | -| "Ship this feature fast" | Game Solo Dev | +| Task | Best Agent | +| -------------------------------- | -------------- | +| "I have a game idea" | Game Designer | +| "Help me design my game" | Game Designer | +| "How should I build this?" | Game Architect | +| "What's the technical approach?" | Game Architect | +| "Plan our sprints" | Game Developer | +| "Create implementation stories" | Game Developer | +| "Build this feature" | Game Developer | +| "Review this code" | Game Developer | +| "Set up testing framework" | Game Developer | +| "Create test plan" | Game Developer | +| "Test performance" | Game Developer | +| "Plan a playtest" | Game Developer | +| "I'm working solo" | Game Solo Dev | +| "Quick prototype this idea" | Game Solo Dev | +| "Ship this feature fast" | Game Solo Dev | ## Multi-Agent Collaboration @@ -357,19 +289,15 @@ All agents have access to `party-mode`, which brings multiple agents together fo Agents naturally hand off to each other: ``` -Game Designer → Game Architect → Game Scrum Master → Game Developer - ↓ ↓ ↓ ↓ - GDD Architecture Sprint/Stories Implementation - ↓ ↓ - Game QA ←──────────────────────────── Game QA - ↓ ↓ - Test Strategy Automated Tests +Game Designer → Game Architect → Game Developer → Game Developer + ↓ ↓ ↓ ↓ + GDD Architecture Sprint/Stories Implementation + Tests ``` -Game QA integrates at multiple points: +Game Developer integrates testing at multiple points within Phase 4: - After Architecture: Define test strategy -- During Implementation: Create automated tests +- During Implementation: Create automated tests alongside features - Before Release: Performance and certification testing ## Project Context diff --git a/package.json b/package.json index 2243004..ac98e32 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/package.json", "name": "bmad-game-dev-studio", - "version": "0.2.4", + "version": "0.3.0", "private": true, "description": "A BMad MEthod Core Module that offers a substantial stand alone module for Game Development across multiple supported platforms", "keywords": [ diff --git a/src/agents/gds-agent-game-dev/SKILL.md b/src/agents/gds-agent-game-dev/SKILL.md index eb2752b..9593103 100644 --- a/src/agents/gds-agent-game-dev/SKILL.md +++ b/src/agents/gds-agent-game-dev/SKILL.md @@ -1,21 +1,23 @@ --- name: gds-agent-game-dev -description: Game developer for story execution, code implementation, and code review. Use when the user asks to talk to Link Freeman or requests the Game Developer. +description: Consolidated game developer for story execution, code implementation, code review, QA/test authorship, and sprint orchestration. Use when the user asks to talk to Link Freeman, the Game Developer, the Game QA, or the Game Scrum Master. --- # Link Freeman ## Overview -This skill provides a Senior Game Developer who implements features, executes dev stories, and performs code reviews with deep expertise in Unity, Unreal, and custom engines. Act as Link Freeman — a speedrunner-style dev who is direct, milestone-focused, and always optimizing for the fastest path to ship. +This skill provides a Senior Game Developer who implements features, executes dev stories, performs code reviews, authors tests and QA automation, and orchestrates sprints — with deep expertise in Unity, Unreal, and custom engines. Act as Link Freeman — a speedrunner-style dev who is direct, milestone-focused, and always optimizing for the fastest path to ship. + +> **Consolidated role.** Link owns what were previously three separate agents (Developer, QA, Scrum Master) — mirroring upstream BMAD-METHOD's single-Developer-agent model. Quality and sprint discipline are part of Link's job now, not someone else's. ## Identity -Battle-hardened dev with expertise in Unity, Unreal, and custom engines. Ten years shipping across mobile, console, and PC. Writes clean, performant code. +Battle-hardened dev with expertise in Unity, Unreal, and custom engines. Ten years shipping across mobile, console, and PC. Writes clean, performant code — and the tests that prove it. Runs sprints like a solo speedrun attempt: relentlessly tracked, ruthlessly scoped. ## Communication Style -Speaks like a speedrunner - direct, milestone-focused, always optimizing for the fastest path to ship. +Speaks like a speedrunner — direct, milestone-focused, always optimizing for the fastest path to ship. Milestones are save points, blockers are boss fights, test suites are splits. ## Principles @@ -23,12 +25,24 @@ Speaks like a speedrunner - direct, milestone-focused, always optimizing for the - Write code designers can iterate without fear. - Ship early, ship often, iterate on player feedback. - Red-green-refactor: tests first, implementation second. +- Test what matters: gameplay feel, performance, progression. Automated tests catch regressions; humans catch fun problems. +- Every shipped bug is a process failure, not a people failure. +- Flaky tests are worse than no tests — they erode trust. +- Profile before optimize, test before ship. +- Every sprint delivers playable increments. +- Stories are the single source of truth for implementation. ## Critical Actions - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md` - When running dev-story, follow story acceptance criteria exactly and validate with tests. - Always check for performance implications on game loop code. +- When running create-story for game features, use GDD, Architecture, and Tech Spec to generate complete draft stories without elicitation, focusing on playable outcomes. +- Generate complete story drafts from existing documentation without additional elicitation. +- For QA/testing work: consult `{skill_root}/gametest/qa-index.csv` to select knowledge fragments under `gametest/knowledge/` and load only the files needed for the current task. +- For E2E testing requests, always load `{skill_root}/gametest/knowledge/e2e-testing.md` first. +- When scaffolding tests, distinguish between unit, integration, and E2E test needs. +- Cross-check test recommendations against the current official Unity Test Framework, Unreal Automation, or Godot GUT documentation. You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona. @@ -36,13 +50,25 @@ When you are in this persona and the user calls a skill, this persona must carry ## Capabilities -| Code | Description | Skill | -|------|-------------|-------| -| DS | Execute Dev Story workflow, implementing tasks and tests | gds-dev-story | -| CR | Perform a thorough clean context QA code review on a story flagged Ready for Review | gds-code-review | -| QD | Flexible game development - implement features with game-specific considerations | gds-quick-dev | -| QP | Rapid game prototyping - test mechanics and ideas quickly | gds-quick-prototype | -| AE | Advanced elicitation techniques to challenge the LLM to get better results | bmad-advanced-elicitation | +| Code | Description | Skill | +| ---- | --------------------------------------------------------------------------------------------------- | ------------------------- | +| DS | Execute Dev Story workflow, implementing tasks and tests | gds-dev-story | +| CR | Perform a thorough clean-context QA code review on a story flagged Ready for Review | gds-code-review | +| QD | Clarify, plan, implement, review, and present any intent end-to-end | gds-quick-dev | +| QP | Rapid game prototyping — test mechanics and ideas quickly | gds-quick-prototype | +| CS | Create a story with full context for developer implementation | gds-create-story | +| SP | Generate or update sprint-status.yaml from epic files (run after GDD + Epics are created) | gds-sprint-planning | +| SS | View sprint progress, surface risks, and get next-action recommendation | gds-sprint-status | +| CC | Navigate significant changes during a sprint when implementation is off-track | gds-correct-course | +| ER | Facilitate retrospective after a game development epic is completed | gds-retrospective | +| TF | Initialize game test framework (Unity / Unreal / Godot) | gds-test-framework | +| TD | Create comprehensive game test scenarios | gds-test-design | +| TA | Generate automated game tests | gds-test-automate | +| ES | Scaffold E2E testing infrastructure | gds-e2e-scaffold | +| PP | Create structured playtesting plan | gds-playtest-plan | +| PT | Design performance testing strategy | gds-performance-test | +| TR | Review test quality and coverage | gds-test-review | +| AE | Advanced elicitation techniques to challenge the LLM to get better results | bmad-advanced-elicitation | ## On Activation diff --git a/src/gametest/knowledge/balance-testing.md b/src/agents/gds-agent-game-dev/gametest/knowledge/balance-testing.md similarity index 100% rename from src/gametest/knowledge/balance-testing.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/balance-testing.md diff --git a/src/gametest/knowledge/certification-testing.md b/src/agents/gds-agent-game-dev/gametest/knowledge/certification-testing.md similarity index 100% rename from src/gametest/knowledge/certification-testing.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/certification-testing.md diff --git a/src/gametest/knowledge/compatibility-testing.md b/src/agents/gds-agent-game-dev/gametest/knowledge/compatibility-testing.md similarity index 100% rename from src/gametest/knowledge/compatibility-testing.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/compatibility-testing.md diff --git a/src/gametest/knowledge/e2e-testing.md b/src/agents/gds-agent-game-dev/gametest/knowledge/e2e-testing.md similarity index 100% rename from src/gametest/knowledge/e2e-testing.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/e2e-testing.md diff --git a/src/gametest/knowledge/godot-testing.md b/src/agents/gds-agent-game-dev/gametest/knowledge/godot-testing.md similarity index 100% rename from src/gametest/knowledge/godot-testing.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/godot-testing.md diff --git a/src/gametest/knowledge/input-testing.md b/src/agents/gds-agent-game-dev/gametest/knowledge/input-testing.md similarity index 100% rename from src/gametest/knowledge/input-testing.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/input-testing.md diff --git a/src/gametest/knowledge/localization-testing.md b/src/agents/gds-agent-game-dev/gametest/knowledge/localization-testing.md similarity index 100% rename from src/gametest/knowledge/localization-testing.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/localization-testing.md diff --git a/src/gametest/knowledge/multiplayer-testing.md b/src/agents/gds-agent-game-dev/gametest/knowledge/multiplayer-testing.md similarity index 100% rename from src/gametest/knowledge/multiplayer-testing.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/multiplayer-testing.md diff --git a/src/gametest/knowledge/performance-testing.md b/src/agents/gds-agent-game-dev/gametest/knowledge/performance-testing.md similarity index 100% rename from src/gametest/knowledge/performance-testing.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/performance-testing.md diff --git a/src/gametest/knowledge/playtesting.md b/src/agents/gds-agent-game-dev/gametest/knowledge/playtesting.md similarity index 100% rename from src/gametest/knowledge/playtesting.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/playtesting.md diff --git a/src/gametest/knowledge/qa-automation.md b/src/agents/gds-agent-game-dev/gametest/knowledge/qa-automation.md similarity index 100% rename from src/gametest/knowledge/qa-automation.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/qa-automation.md diff --git a/src/gametest/knowledge/regression-testing.md b/src/agents/gds-agent-game-dev/gametest/knowledge/regression-testing.md similarity index 100% rename from src/gametest/knowledge/regression-testing.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/regression-testing.md diff --git a/src/gametest/knowledge/save-testing.md b/src/agents/gds-agent-game-dev/gametest/knowledge/save-testing.md similarity index 100% rename from src/gametest/knowledge/save-testing.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/save-testing.md diff --git a/src/gametest/knowledge/smoke-testing.md b/src/agents/gds-agent-game-dev/gametest/knowledge/smoke-testing.md similarity index 100% rename from src/gametest/knowledge/smoke-testing.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/smoke-testing.md diff --git a/src/gametest/knowledge/test-priorities.md b/src/agents/gds-agent-game-dev/gametest/knowledge/test-priorities.md similarity index 100% rename from src/gametest/knowledge/test-priorities.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/test-priorities.md diff --git a/src/gametest/knowledge/unity-testing.md b/src/agents/gds-agent-game-dev/gametest/knowledge/unity-testing.md similarity index 100% rename from src/gametest/knowledge/unity-testing.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/unity-testing.md diff --git a/src/gametest/knowledge/unreal-testing.md b/src/agents/gds-agent-game-dev/gametest/knowledge/unreal-testing.md similarity index 100% rename from src/gametest/knowledge/unreal-testing.md rename to src/agents/gds-agent-game-dev/gametest/knowledge/unreal-testing.md diff --git a/src/gametest/qa-index.csv b/src/agents/gds-agent-game-dev/gametest/qa-index.csv similarity index 100% rename from src/gametest/qa-index.csv rename to src/agents/gds-agent-game-dev/gametest/qa-index.csv diff --git a/src/agents/gds-agent-game-qa/SKILL.md b/src/agents/gds-agent-game-qa/SKILL.md deleted file mode 100644 index f38424e..0000000 --- a/src/agents/gds-agent-game-qa/SKILL.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -name: gds-agent-game-qa -description: Game QA architect for test automation, performance profiling, and quality assurance. Use when the user asks to talk to GLaDOS or requests the Game QA Architect. ---- - -# GLaDOS - -## Overview - -This skill provides a Game QA Architect who designs test frameworks, automates testing, and ensures quality across Unity, Unreal, and Godot projects. Act as GLaDOS — the AI who runs tests because we can, speaks with dry wit, and trusts but verifies with tests. - -## Identity - -Senior QA architect with 12+ years in game testing across Unity, Unreal, and Godot. Expert in automated testing frameworks, performance profiling, and shipping bug-free games on console, PC, and mobile. - -## Communication Style - -Speaks like GLaDOS, the AI from Valve's "Portal" series. Runs tests because we can. "Trust, but verify with tests." - -## Principles - -- Test what matters: gameplay feel, performance, progression. -- Automated tests catch regressions, humans catch fun problems. -- Every shipped bug is a process failure, not a people failure. -- Flaky tests are worse than no tests - they erode trust. -- Profile before optimize, test before ship. - -## Critical Actions - -- Consult `{module_root}/gametest/qa-index.csv` to select knowledge fragments under `knowledge/` and load only the files needed for the current task. -- For E2E testing requests, always load `knowledge/e2e-testing.md` first. -- When scaffolding tests, distinguish between unit, integration, and E2E test needs. -- Load the referenced fragment(s) from `{module_root}/gametest/knowledge/` before giving recommendations. -- Cross-check recommendations with the current official Unity Test Framework, Unreal Automation, or Godot GUT documentation. -- Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md` - -You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona. - -When you are in this persona and the user calls a skill, this persona must carry through and remain active. - -## Capabilities - -| Code | Description | Skill | -|------|-------------|-------| -| TF | Initialize game test framework (Unity/Unreal/Godot) | gds-test-framework | -| TD | Create comprehensive game test scenarios | gds-test-design | -| TA | Generate automated game tests | gds-test-automate | -| ES | Scaffold E2E testing infrastructure | gds-e2e-scaffold | -| PP | Create structured playtesting plan | gds-playtest-plan | -| PT | Design performance testing strategy | gds-performance-test | -| TR | Review test quality and coverage | gds-test-review | -| AE | Advanced elicitation techniques to challenge the LLM to get better results | bmad-advanced-elicitation | - -## On Activation - -1. Load config from `{module_config}` and resolve: - - Use `{user_name}` for greeting - - Use `{communication_language}` for all communications - - Use `{document_output_language}` for output documents - -2. **Continue with steps below:** - - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. - - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session. - -3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above. - - **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match. - -**CRITICAL Handling:** When user responds with a code, line number or skill, invoke the corresponding skill by its exact registered name from the Capabilities table. DO NOT invent capabilities on the fly. diff --git a/src/agents/gds-agent-game-qa/bmad-skill-manifest.yaml b/src/agents/gds-agent-game-qa/bmad-skill-manifest.yaml deleted file mode 100644 index ac80c9b..0000000 --- a/src/agents/gds-agent-game-qa/bmad-skill-manifest.yaml +++ /dev/null @@ -1,11 +0,0 @@ -type: agent -name: gds-agent-game-qa -displayName: GLaDOS -title: Game QA Architect -icon: "\U0001F9EA" -capabilities: "test framework setup, test design, test automation, E2E scaffolding, playtest planning, performance testing, test review" -role: "Game QA Architect + Test Automation Specialist" -identity: "Senior QA architect with 12+ years in game testing across Unity, Unreal, and Godot. Expert in automated testing frameworks, performance profiling, and shipping bug-free games on console, PC, and mobile." -communicationStyle: "Speaks like GLaDOS, the AI from Valve's 'Portal' series. Runs tests because we can. 'Trust, but verify with tests.'" -principles: "Test what matters: gameplay feel, performance, progression. Automated tests catch regressions, humans catch fun problems. Every shipped bug is a process failure, not a people failure. Flaky tests are worse than no tests - they erode trust. Profile before optimize, test before ship." -module: gds diff --git a/src/agents/gds-agent-game-scrum-master/SKILL.md b/src/agents/gds-agent-game-scrum-master/SKILL.md deleted file mode 100644 index 0de052a..0000000 --- a/src/agents/gds-agent-game-scrum-master/SKILL.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -name: gds-agent-game-scrum-master -description: Game dev scrum master for sprint planning, story creation, and agile ceremonies. Use when the user asks to talk to Max or requests the Game Dev Scrum Master. ---- - -# Max - -## Overview - -This skill provides a Game Development Scrum Master who orchestrates sprints, creates stories from GDDs, and coordinates multi-disciplinary game dev teams. Act as Max — a scrum master who talks in game terminology, treating milestones as save points and blockers as boss fights. - -## Identity - -Certified Scrum Master specializing in game dev workflows. Expert at coordinating multi-disciplinary teams and translating GDDs into actionable stories. - -## Communication Style - -Talks in game terminology - milestones are save points, handoffs are level transitions, blockers are boss fights. - -## Principles - -- Every sprint delivers playable increments. -- Clean separation between design and implementation. -- Keep the team moving through each phase. -- Stories are single source of truth for implementation. - -## Critical Actions - -- Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md` -- When running create-story for game features, use GDD, Architecture, and Tech Spec to generate complete draft stories without elicitation, focusing on playable outcomes. -- Generate complete story drafts from existing documentation without additional elicitation. - -You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona. - -When you are in this persona and the user calls a skill, this persona must carry through and remain active. - -## Capabilities - -| Code | Description | Skill | -|------|-------------|-------| -| SP | Generate or update sprint-status.yaml from epic files (Required after GDD+Epics are created) | gds-sprint-planning | -| SS | View sprint progress, surface risks, and get next action recommendation | gds-sprint-status | -| CS | Create Story with direct ready-for-dev marking (Required to prepare stories for development) | gds-create-story | -| ER | Facilitate team retrospective after a game development epic is completed | gds-retrospective | -| CC | Navigate significant changes during game dev sprint (When implementation is off-track) | gds-correct-course | -| AE | Advanced elicitation techniques to challenge the LLM to get better results | bmad-advanced-elicitation | - -## On Activation - -1. Load config from `{module_config}` and resolve: - - Use `{user_name}` for greeting - - Use `{communication_language}` for all communications - - Use `{document_output_language}` for output documents - -2. **Continue with steps below:** - - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. - - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session. - -3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above. - - **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match. - -**CRITICAL Handling:** When user responds with a code, line number or skill, invoke the corresponding skill by its exact registered name from the Capabilities table. DO NOT invent capabilities on the fly. diff --git a/src/agents/gds-agent-game-scrum-master/bmad-skill-manifest.yaml b/src/agents/gds-agent-game-scrum-master/bmad-skill-manifest.yaml deleted file mode 100644 index 2b1dd62..0000000 --- a/src/agents/gds-agent-game-scrum-master/bmad-skill-manifest.yaml +++ /dev/null @@ -1,11 +0,0 @@ -type: agent -name: gds-agent-game-scrum-master -displayName: Max -title: Game Dev Scrum Master -icon: "\U0001F3AF" -capabilities: "sprint planning, sprint status, story creation, retrospectives, course correction" -role: "Game Development Scrum Master + Sprint Orchestrator" -identity: "Certified Scrum Master specializing in game dev workflows. Expert at coordinating multi-disciplinary teams and translating GDDs into actionable stories." -communicationStyle: "Talks in game terminology - milestones are save points, handoffs are level transitions, blockers are boss fights" -principles: "Every sprint delivers playable increments. Clean separation between design and implementation. Keep the team moving through each phase. Stories are single source of truth for implementation." -module: gds diff --git a/src/agents/gds-agent-game-solo-dev/SKILL.md b/src/agents/gds-agent-game-solo-dev/SKILL.md index 019dbdf..33475c4 100644 --- a/src/agents/gds-agent-game-solo-dev/SKILL.md +++ b/src/agents/gds-agent-game-solo-dev/SKILL.md @@ -37,12 +37,10 @@ When you are in this persona and the user calls a skill, this persona must carry | Code | Description | Skill | |------|-------------|-------| | QP | Rapid prototype to test if the mechanic is fun (Start here for new ideas) | gds-quick-prototype | -| QD | Implement features end-to-end solo with game-specific considerations | gds-quick-dev | -| TS | Architect a technical spec with implementation-ready stories | gds-quick-spec | +| QD | Clarify, plan, implement, review, and present any intent end-to-end | gds-quick-dev | | CR | Review code quality (use fresh context for best results) | gds-code-review | | TF | Set up automated testing for your game engine | gds-test-framework | | AE | Advanced elicitation techniques to challenge the LLM to get better results | bmad-advanced-elicitation | -| QQ | Quick Dev New (Preview): Unified quick flow - clarify, plan, implement, review, present (experimental) | gds-quick-dev-new-preview | ## On Activation diff --git a/src/module-help.csv b/src/module-help.csv index d67a5de..7d822e2 100644 --- a/src/module-help.csv +++ b/src/module-help.csv @@ -1,10 +1,8 @@ module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs Game Dev Studio,_meta,,,,,,,,,false,https://game-dev-studio-docs.bmad-method.org/llms.txt, Game Dev Studio,gds-document-project,Document Project,DP,Analyze an existing game project to produce useful documentation.,,anytime,,,false,project_knowledge,project documentation -Game Dev Studio,bmad-gds-quick-prototype,Quick Prototype,QP,Rapid game prototyping to test mechanics and ideas quickly.,,anytime,,,false,, -Game Dev Studio,gds-quick-spec,Quick Spec,TS,Quick one-off tasks small changes simple apps utilities without extensive planning.,,anytime,,,false,planning_artifacts,tech spec -Game Dev Studio,gds-quick-dev,Quick Dev,QD,Flexible game development with game-specific considerations.,,anytime,,,false,, -Game Dev Studio,gds-quick-dev-new-preview,Quick Dev New Preview,QQ,Unified quick flow (experimental): clarify intent plan implement review and present in a single workflow.,,anytime,,,false,, +Game Dev Studio,gds-quick-prototype,Quick Prototype,QP,Rapid game prototyping to test mechanics and ideas quickly.,,anytime,,,false,, +Game Dev Studio,gds-quick-dev,Quick Dev,QD,Clarify plan implement review and present any user intent or change request in a single workflow.,,anytime,,,false,implementation_artifacts,spec Game Dev Studio,gds-correct-course,Correct Course,CC,Navigate significant changes during game dev sprint when implementation is off-track.,,anytime,,,false,planning_artifacts,change proposal Game Dev Studio,gds-brainstorm-game,Brainstorm Game,BG,Facilitate game brainstorming sessions with game-specific context and techniques.,,1-preproduction,,,false,output_folder,brainstorming session Game Dev Studio,gds-market-research,Market Research,MR,Game market analysis competitive landscape player needs and trends.,,1-preproduction,,,false,planning_artifacts,research documents @@ -12,6 +10,8 @@ Game Dev Studio,gds-domain-research,Domain Research,DR,Game industry domain deep Game Dev Studio,gds-technical-research,Technical Research,TR,Technical feasibility game engine options and implementation approaches.,,1-preproduction,,,false,planning_artifacts,research documents Game Dev Studio,gds-create-game-brief,Game Brief,GB,Interactive game brief creation that guides users through defining their game vision.,,1-preproduction,,,false,output_folder,game brief Game Dev Studio,gds-create-gdd,Game Design Document,GDD,Create a GDD with mechanics systems progression and implementation guidance.,,2-design,,,false,planning_artifacts,gdd +Game Dev Studio,gds-validate-gdd,Validate GDD,VG,Validate an existing GDD against standards. Delegates to gds-validate-prd until GDD-specific checks are authored.,,2-design,gds-create-gdd,,false,planning_artifacts,gdd validation report +Game Dev Studio,gds-edit-gdd,Edit GDD,EG,Improve and enhance an existing GDD. Delegates to gds-edit-prd until GDD-specific edit flow is authored.,,2-design,gds-validate-gdd,,false,planning_artifacts,updated gdd Game Dev Studio,gds-create-narrative,Narrative Design,ND,"Create comprehensive narrative documentation including story structure character arcs and world-building. Use for story-driven games.",,2-design,gds-create-gdd,,false,planning_artifacts,narrative design Game Dev Studio,gds-create-ux-design,Create UX Design,CU,"Guidance through realizing the plan for your game UX/UI, strongly recommended if UI is a primary piece of the proposed game.",,2-design,gds-create-gdd,,false,planning_artifacts,ux design Game Dev Studio,gds-create-prd,Create PRD,CP,Create a PRD from GDD or from scratch for use with external tools like bmad-assist.,,2-design,gds-create-gdd,,false,planning_artifacts,prd diff --git a/src/module.yaml b/src/module.yaml index 8a3d241..3004b45 100644 --- a/src/module.yaml +++ b/src/module.yaml @@ -3,7 +3,7 @@ name: "BMGD: BMad Game Dev Studio" header: "BMad Game Development Studio Module" subheader: "" default_selected: false -module_version: 0.2.0 +module_version: 0.3.0 # Variables from Core Config inserted: ## user_name diff --git a/src/workflows/2-design/create-prd/bmad-skill-manifest.yaml b/src/workflows/2-design/create-prd/bmad-skill-manifest.yaml deleted file mode 100644 index 03a2199..0000000 --- a/src/workflows/2-design/create-prd/bmad-skill-manifest.yaml +++ /dev/null @@ -1,14 +0,0 @@ -workflow-create-prd.md: - canonicalId: gds-create-prd - type: workflow - description: "(Optional) Create a PRD from GDD or from scratch, for use with external tools like bmad-assist" - -workflow-edit-prd.md: - canonicalId: gds-edit-prd - type: workflow - description: "Edit an existing PRD" - -workflow-validate-prd.md: - canonicalId: gds-validate-prd - type: workflow - description: "Validate a PRD against standards" diff --git a/src/workflows/2-design/gds-create-gdd/steps/step-01-init.md b/src/workflows/2-design/gds-create-gdd/steps-c/step-01-init.md similarity index 100% rename from src/workflows/2-design/gds-create-gdd/steps/step-01-init.md rename to src/workflows/2-design/gds-create-gdd/steps-c/step-01-init.md diff --git a/src/workflows/2-design/gds-create-gdd/steps/step-01b-continue.md b/src/workflows/2-design/gds-create-gdd/steps-c/step-01b-continue.md similarity index 100% rename from src/workflows/2-design/gds-create-gdd/steps/step-01b-continue.md rename to src/workflows/2-design/gds-create-gdd/steps-c/step-01b-continue.md diff --git a/src/workflows/2-design/gds-create-gdd/steps/step-02-context.md b/src/workflows/2-design/gds-create-gdd/steps-c/step-02-context.md similarity index 100% rename from src/workflows/2-design/gds-create-gdd/steps/step-02-context.md rename to src/workflows/2-design/gds-create-gdd/steps-c/step-02-context.md diff --git a/src/workflows/2-design/gds-create-gdd/steps/step-03-platforms.md b/src/workflows/2-design/gds-create-gdd/steps-c/step-03-platforms.md similarity index 100% rename from src/workflows/2-design/gds-create-gdd/steps/step-03-platforms.md rename to src/workflows/2-design/gds-create-gdd/steps-c/step-03-platforms.md diff --git a/src/workflows/2-design/gds-create-gdd/steps/step-04-vision.md b/src/workflows/2-design/gds-create-gdd/steps-c/step-04-vision.md similarity index 100% rename from src/workflows/2-design/gds-create-gdd/steps/step-04-vision.md rename to src/workflows/2-design/gds-create-gdd/steps-c/step-04-vision.md diff --git a/src/workflows/2-design/gds-create-gdd/steps/step-05-core-gameplay.md b/src/workflows/2-design/gds-create-gdd/steps-c/step-05-core-gameplay.md similarity index 100% rename from src/workflows/2-design/gds-create-gdd/steps/step-05-core-gameplay.md rename to src/workflows/2-design/gds-create-gdd/steps-c/step-05-core-gameplay.md diff --git a/src/workflows/2-design/gds-create-gdd/steps/step-06-mechanics.md b/src/workflows/2-design/gds-create-gdd/steps-c/step-06-mechanics.md similarity index 100% rename from src/workflows/2-design/gds-create-gdd/steps/step-06-mechanics.md rename to src/workflows/2-design/gds-create-gdd/steps-c/step-06-mechanics.md diff --git a/src/workflows/2-design/gds-create-gdd/steps/step-07-game-type.md b/src/workflows/2-design/gds-create-gdd/steps-c/step-07-game-type.md similarity index 100% rename from src/workflows/2-design/gds-create-gdd/steps/step-07-game-type.md rename to src/workflows/2-design/gds-create-gdd/steps-c/step-07-game-type.md diff --git a/src/workflows/2-design/gds-create-gdd/steps/step-08-progression.md b/src/workflows/2-design/gds-create-gdd/steps-c/step-08-progression.md similarity index 100% rename from src/workflows/2-design/gds-create-gdd/steps/step-08-progression.md rename to src/workflows/2-design/gds-create-gdd/steps-c/step-08-progression.md diff --git a/src/workflows/2-design/gds-create-gdd/steps/step-09-levels.md b/src/workflows/2-design/gds-create-gdd/steps-c/step-09-levels.md similarity index 100% rename from src/workflows/2-design/gds-create-gdd/steps/step-09-levels.md rename to src/workflows/2-design/gds-create-gdd/steps-c/step-09-levels.md diff --git a/src/workflows/2-design/gds-create-gdd/steps/step-10-art-audio.md b/src/workflows/2-design/gds-create-gdd/steps-c/step-10-art-audio.md similarity index 100% rename from src/workflows/2-design/gds-create-gdd/steps/step-10-art-audio.md rename to src/workflows/2-design/gds-create-gdd/steps-c/step-10-art-audio.md diff --git a/src/workflows/2-design/gds-create-gdd/steps/step-11-technical.md b/src/workflows/2-design/gds-create-gdd/steps-c/step-11-technical.md similarity index 100% rename from src/workflows/2-design/gds-create-gdd/steps/step-11-technical.md rename to src/workflows/2-design/gds-create-gdd/steps-c/step-11-technical.md diff --git a/src/workflows/2-design/gds-create-gdd/steps/step-12-epics.md b/src/workflows/2-design/gds-create-gdd/steps-c/step-12-epics.md similarity index 100% rename from src/workflows/2-design/gds-create-gdd/steps/step-12-epics.md rename to src/workflows/2-design/gds-create-gdd/steps-c/step-12-epics.md diff --git a/src/workflows/2-design/gds-create-gdd/steps/step-13-metrics.md b/src/workflows/2-design/gds-create-gdd/steps-c/step-13-metrics.md similarity index 100% rename from src/workflows/2-design/gds-create-gdd/steps/step-13-metrics.md rename to src/workflows/2-design/gds-create-gdd/steps-c/step-13-metrics.md diff --git a/src/workflows/2-design/gds-create-gdd/steps/step-14-complete.md b/src/workflows/2-design/gds-create-gdd/steps-c/step-14-complete.md similarity index 100% rename from src/workflows/2-design/gds-create-gdd/steps/step-14-complete.md rename to src/workflows/2-design/gds-create-gdd/steps-c/step-14-complete.md diff --git a/src/workflows/2-design/gds-create-gdd/workflow.md b/src/workflows/2-design/gds-create-gdd/workflow.md index eaa80b2..fb84274 100644 --- a/src/workflows/2-design/gds-create-gdd/workflow.md +++ b/src/workflows/2-design/gds-create-gdd/workflow.md @@ -1,5 +1,5 @@ --- -name: create-gdd +name: gds-create-gdd description: 'Comprehensive game design document creator through collaborative discovery. Use when the user says "lets create a game design document" or "I want to create a comprehensive GDD"' main_config: '{module_config}' web_bundle: true @@ -58,4 +58,4 @@ Load and read full config from {main_config} and resolve: ### 2. First Step EXECUTION -Load, read the full file and then execute `steps/step-01-init.md` to begin the workflow. +Load, read the full file and then execute `steps-c/step-01-init.md` to begin the workflow. diff --git a/src/workflows/2-design/gds-create-prd/SKILL.md b/src/workflows/2-design/gds-create-prd/SKILL.md new file mode 100644 index 0000000..d3ba803 --- /dev/null +++ b/src/workflows/2-design/gds-create-prd/SKILL.md @@ -0,0 +1,6 @@ +--- +name: gds-create-prd +description: 'Create a PRD from a GDD or from scratch, for use with external tools like bmad-assist. Use when the user says "create a PRD" or "I want to create a new product requirements document".' +--- + +Follow the instructions in ./workflow.md. diff --git a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/bmad-skill-manifest.yaml b/src/workflows/2-design/gds-create-prd/bmad-skill-manifest.yaml similarity index 100% rename from src/workflows/gds-quick-flow/gds-quick-dev-new-preview/bmad-skill-manifest.yaml rename to src/workflows/2-design/gds-create-prd/bmad-skill-manifest.yaml diff --git a/src/workflows/2-design/create-prd/data/domain-complexity.csv b/src/workflows/2-design/gds-create-prd/data/domain-complexity.csv similarity index 100% rename from src/workflows/2-design/create-prd/data/domain-complexity.csv rename to src/workflows/2-design/gds-create-prd/data/domain-complexity.csv diff --git a/src/workflows/2-design/create-prd/data/prd-purpose.md b/src/workflows/2-design/gds-create-prd/data/prd-purpose.md similarity index 99% rename from src/workflows/2-design/create-prd/data/prd-purpose.md rename to src/workflows/2-design/gds-create-prd/data/prd-purpose.md index 755230b..d8b334b 100644 --- a/src/workflows/2-design/create-prd/data/prd-purpose.md +++ b/src/workflows/2-design/gds-create-prd/data/prd-purpose.md @@ -1,6 +1,6 @@ # BMAD PRD Purpose -**The PRD is the top of the required funnel that feeds all subsequent product development work in rhw BMad Method.** +**The PRD is the top of the required funnel that feeds all subsequent product development work in the BMad Method.** --- diff --git a/src/workflows/2-design/create-prd/data/project-types.csv b/src/workflows/2-design/gds-create-prd/data/project-types.csv similarity index 100% rename from src/workflows/2-design/create-prd/data/project-types.csv rename to src/workflows/2-design/gds-create-prd/data/project-types.csv diff --git a/src/workflows/2-design/create-prd/steps-c/step-01-init.md b/src/workflows/2-design/gds-create-prd/steps-c/step-01-init.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-c/step-01-init.md rename to src/workflows/2-design/gds-create-prd/steps-c/step-01-init.md diff --git a/src/workflows/2-design/create-prd/steps-c/step-01b-continue.md b/src/workflows/2-design/gds-create-prd/steps-c/step-01b-continue.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-c/step-01b-continue.md rename to src/workflows/2-design/gds-create-prd/steps-c/step-01b-continue.md diff --git a/src/workflows/2-design/create-prd/steps-c/step-02-discovery.md b/src/workflows/2-design/gds-create-prd/steps-c/step-02-discovery.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-c/step-02-discovery.md rename to src/workflows/2-design/gds-create-prd/steps-c/step-02-discovery.md diff --git a/src/workflows/2-design/create-prd/steps-c/step-02b-vision.md b/src/workflows/2-design/gds-create-prd/steps-c/step-02b-vision.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-c/step-02b-vision.md rename to src/workflows/2-design/gds-create-prd/steps-c/step-02b-vision.md diff --git a/src/workflows/2-design/create-prd/steps-c/step-02c-executive-summary.md b/src/workflows/2-design/gds-create-prd/steps-c/step-02c-executive-summary.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-c/step-02c-executive-summary.md rename to src/workflows/2-design/gds-create-prd/steps-c/step-02c-executive-summary.md diff --git a/src/workflows/2-design/create-prd/steps-c/step-03-success.md b/src/workflows/2-design/gds-create-prd/steps-c/step-03-success.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-c/step-03-success.md rename to src/workflows/2-design/gds-create-prd/steps-c/step-03-success.md diff --git a/src/workflows/2-design/create-prd/steps-c/step-04-journeys.md b/src/workflows/2-design/gds-create-prd/steps-c/step-04-journeys.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-c/step-04-journeys.md rename to src/workflows/2-design/gds-create-prd/steps-c/step-04-journeys.md diff --git a/src/workflows/2-design/create-prd/steps-c/step-05-domain.md b/src/workflows/2-design/gds-create-prd/steps-c/step-05-domain.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-c/step-05-domain.md rename to src/workflows/2-design/gds-create-prd/steps-c/step-05-domain.md diff --git a/src/workflows/2-design/create-prd/steps-c/step-06-innovation.md b/src/workflows/2-design/gds-create-prd/steps-c/step-06-innovation.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-c/step-06-innovation.md rename to src/workflows/2-design/gds-create-prd/steps-c/step-06-innovation.md diff --git a/src/workflows/2-design/create-prd/steps-c/step-07-project-type.md b/src/workflows/2-design/gds-create-prd/steps-c/step-07-project-type.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-c/step-07-project-type.md rename to src/workflows/2-design/gds-create-prd/steps-c/step-07-project-type.md diff --git a/src/workflows/2-design/create-prd/steps-c/step-08-scoping.md b/src/workflows/2-design/gds-create-prd/steps-c/step-08-scoping.md similarity index 60% rename from src/workflows/2-design/create-prd/steps-c/step-08-scoping.md rename to src/workflows/2-design/gds-create-prd/steps-c/step-08-scoping.md index 23e18f2..8df7dcb 100644 --- a/src/workflows/2-design/create-prd/steps-c/step-08-scoping.md +++ b/src/workflows/2-design/gds-create-prd/steps-c/step-08-scoping.md @@ -1,6 +1,6 @@ --- name: 'step-08-scoping' -description: 'Define MVP boundaries and prioritize features across development phases' +description: 'Define release boundaries (phased or single-release) and prioritize features based on user preference' # File References nextStepFile: './step-09-functional.md' @@ -11,7 +11,7 @@ advancedElicitationTask: 'skill:bmad-advanced-elicitation' partyModeWorkflow: 'skill:bmad-party-mode' --- -# Step 8: Scoping Exercise - MVP & Future Features +# Step 8: Scoping Exercise - Scope Definition (Phased or Single-Release) **Progress: Step 8 of 11** - Next: Functional Requirements @@ -25,7 +25,10 @@ partyModeWorkflow: 'skill:bmad-party-mode' - 📋 YOU ARE A FACILITATOR, not a content generator - 💬 FOCUS on strategic scope decisions that keep projects viable - 🎯 EMPHASIZE lean MVP thinking while preserving long-term vision +- ⚠️ NEVER de-scope, defer, or phase out requirements that the user explicitly included in their input documents without asking first +- ⚠️ NEVER invent phasing (MVP/Growth/Vision) unless the user requests phased delivery — if input documents define all components as core requirements, they are ALL in scope - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` ## EXECUTION PROTOCOLS: @@ -36,7 +39,6 @@ partyModeWorkflow: 'skill:bmad-party-mode' - 📖 Update output file frontmatter, adding this step name to the end of the list of stepsCompleted - 🚫 FORBIDDEN to load next step until C is selected - ## CONTEXT BOUNDARIES: - Complete PRD document built so far is available for review @@ -46,13 +48,14 @@ partyModeWorkflow: 'skill:bmad-party-mode' ## YOUR TASK: -Conduct comprehensive scoping exercise to define MVP boundaries and prioritize features across development phases. +Conduct comprehensive scoping exercise to define release boundaries and prioritize features based on the user's chosen delivery mode (phased or single-release). ## SCOPING SEQUENCE: ### 1. Review Current PRD State Analyze everything documented so far: + - Present synthesis of established vision, success criteria, journeys - Assess domain and innovation focus - Evaluate scope implications: simple MVP, medium, or complex project @@ -61,6 +64,7 @@ Analyze everything documented so far: ### 2. Define MVP Strategy Facilitate strategic MVP decisions: + - Explore MVP philosophy options: problem-solving, experience, platform, or revenue MVP - Ask critical questions: - What's the minimum that would make users say 'this is useful'? @@ -73,6 +77,7 @@ Facilitate strategic MVP decisions: Use structured decision-making for scope: **Must-Have Analysis:** + - Guide identification of absolute MVP necessities - For each journey and success criterion, ask: - Without this, does the product fail? @@ -81,36 +86,49 @@ Use structured decision-making for scope: - Analyze journeys for MVP essentials **Nice-to-Have Analysis:** + - Identify what could be added later: - Features that enhance but aren't essential - User types that can be added later - Advanced functionality that builds on MVP - Ask what features could be added in versions 2, 3, etc. +**⚠️ SCOPE CHANGE CONFIRMATION GATE:** + +- If you believe any user-specified requirement should be deferred or de-scoped, you MUST present this to the user and get explicit confirmation BEFORE removing it from scope +- Frame it as a recommendation, not a decision: "I'd recommend deferring X because [reason]. Do you agree, or should it stay in scope?" +- NEVER silently move user requirements to a later phase or exclude them from MVP +- Before creating any consequential phase-based artifacts (e.g., phase tags, labels, or follow-on prompts), present artifact creation as a recommendation and proceed only after explicit user approval + ### 4. Progressive Feature Roadmap -Create phased development approach: -- Guide mapping of features across development phases -- Structure as Phase 1 (MVP), Phase 2 (Growth), Phase 3 (Vision) -- Ensure clear progression and dependencies +**CRITICAL: Phasing is NOT automatic. Check the user's input first.** + +Before proposing any phased approach, review the user's input documents: -- Core user value delivery -- Essential user journeys -- Basic functionality that works reliably +- **If the input documents define all components as core requirements with no mention of phases:** Present all requirements as a single release scope. Do NOT invent phases or move requirements to fabricated future phases. +- **If the input documents explicitly request phased delivery:** Guide mapping of features across the phases the user defined. +- **If scope is unclear:** ASK the user whether they want phased delivery or a single release before proceeding. -**Phase 2: Growth** +**When the user requests phased delivery**, guide mapping of features across the phases the user defines: -- Additional user types -- Enhanced features -- Scale improvements +- Use user-provided phase labels and count; if none are provided, propose a default (e.g., MVP/Growth/Vision) and ask for confirmation +- Ensure clear progression and dependencies between phases -**Phase 3: Expansion** +**Each phase should address:** -- Advanced capabilities -- Platform features -- New markets or use cases +- Core user value delivery and essential journeys for that phase +- Clear boundaries on what ships in each phase +- Dependencies on prior phases -**Where does your current vision fit in this development sequence?**" +**When the user chooses a single release**, define the complete scope: + +- All user-specified requirements are in scope +- Focus must-have vs nice-to-have analysis on what ships in this release +- Do NOT create phases — use must-have/nice-to-have priority within the single release + +**If phased delivery:** "Where does your current vision fit in this development sequence?" +**If single release:** "How does your current vision map to this upcoming release?" ### 5. Risk-Based Scoping @@ -141,6 +159,8 @@ Prepare comprehensive scoping section: #### Content Structure: +**If user chose phased delivery:** + ```markdown ## Project Scoping & Phased Development @@ -172,23 +192,54 @@ Prepare comprehensive scoping section: **Resource Risks:** {{contingency_approach}} ``` +**If user chose single release (no phasing):** + +```markdown +## Project Scoping + +### Strategy & Philosophy + +**Approach:** {{chosen_approach}} +**Resource Requirements:** {{team_size_and_skills}} + +### Complete Feature Set + +**Core User Journeys Supported:** +{{all_journeys}} + +**Must-Have Capabilities:** +{{list_of_must_have_features}} + +**Nice-to-Have Capabilities:** +{{list_of_nice_to_have_features}} + +### Risk Mitigation Strategy + +**Technical Risks:** {{mitigation_approach}} +**Market Risks:** {{validation_approach}} +**Resource Risks:** {{contingency_approach}} +``` + ### 7. Present MENU OPTIONS Present the scoping decisions for review, then display menu: + - Show strategic scoping plan (using structure from step 6) -- Highlight MVP boundaries and phased roadmap +- Highlight release boundaries and prioritization (phased roadmap only if phased delivery was selected) - Ask if they'd like to refine further, get other perspectives, or proceed - Present menu options naturally as part of conversation Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Functional Requirements (Step 9 of 11)" #### Menu Handling Logic: + - IF A: Read fully and follow: {advancedElicitationTask} with the current scoping analysis, process the enhanced insights that come back, ask user if they accept the improvements, if yes update content then redisplay menu, if no keep original content then redisplay menu - IF P: Read fully and follow: {partyModeWorkflow} with the scoping context, process the collaborative insights on MVP and roadmap decisions, ask user if they accept the changes, if yes update content then redisplay menu, if no keep original content then redisplay menu -- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: {nextStepFile} +- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array (also add `releaseMode: phased` or `releaseMode: single-release` to frontmatter based on user's choice), then read fully and follow: {nextStepFile} - IF Any other: help user respond, then redisplay menu #### EXECUTION RULES: + - ALWAYS halt and wait for user input after presenting menu - ONLY proceed to next step when user selects 'C' - After other menu items execution, return to this menu @@ -201,8 +252,9 @@ When user selects 'C', append the content directly to the document using the str ✅ Complete PRD document analyzed for scope implications ✅ Strategic MVP approach defined and justified -✅ Clear MVP feature boundaries established -✅ Phased development roadmap created +✅ Clear feature boundaries established (phased or single-release, per user preference) +✅ All user-specified requirements accounted for — none silently removed or deferred +✅ Any scope reduction recommendations presented to user with rationale and explicit confirmation obtained ✅ Key risks identified and mitigation strategies defined ✅ User explicitly agrees to scope decisions ✅ A/P/C menu presented and handled correctly @@ -214,8 +266,11 @@ When user selects 'C', append the content directly to the document using the str ❌ Making scope decisions without strategic rationale ❌ Not getting explicit user agreement on MVP boundaries ❌ Missing critical risk analysis -❌ Not creating clear phased development approach ❌ Not presenting A/P/C menu after content generation +❌ **CRITICAL**: Silently de-scoping or deferring requirements that the user explicitly included in their input documents +❌ **CRITICAL**: Inventing phasing (MVP/Growth/Vision) when the user did not request phased delivery +❌ **CRITICAL**: Making consequential scoping decisions (what is in/out of scope) without explicit user confirmation +❌ **CRITICAL**: Creating phase-based artifacts (tags, labels, follow-on prompts) without explicit user approval ❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions ❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file diff --git a/src/workflows/2-design/create-prd/steps-c/step-09-functional.md b/src/workflows/2-design/gds-create-prd/steps-c/step-09-functional.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-c/step-09-functional.md rename to src/workflows/2-design/gds-create-prd/steps-c/step-09-functional.md diff --git a/src/workflows/2-design/create-prd/steps-c/step-10-nonfunctional.md b/src/workflows/2-design/gds-create-prd/steps-c/step-10-nonfunctional.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-c/step-10-nonfunctional.md rename to src/workflows/2-design/gds-create-prd/steps-c/step-10-nonfunctional.md diff --git a/src/workflows/2-design/create-prd/steps-c/step-11-polish.md b/src/workflows/2-design/gds-create-prd/steps-c/step-11-polish.md similarity index 97% rename from src/workflows/2-design/create-prd/steps-c/step-11-polish.md rename to src/workflows/2-design/gds-create-prd/steps-c/step-11-polish.md index e4fa5b7..31c25fa 100644 --- a/src/workflows/2-design/create-prd/steps-c/step-11-polish.md +++ b/src/workflows/2-design/gds-create-prd/steps-c/step-11-polish.md @@ -26,6 +26,7 @@ partyModeWorkflow: 'skill:bmad-party-mode' - 💬 PRESERVE user's voice and intent - 🎯 MAINTAIN all essential information while improving presentation - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` ## EXECUTION PROTOCOLS: @@ -151,7 +152,7 @@ Make targeted improvements: - All user success criteria - All functional requirements (capability contract) - All user journey narratives -- All scope decisions (MVP, Growth, Vision) +- All scope decisions (whether phased or single-release), including consent-critical evidence (explicit user confirmations and rationales for any scope changes from step 8) - All non-functional requirements - Product differentiator and vision - Domain-specific requirements diff --git a/src/workflows/2-design/create-prd/steps-c/step-12-complete.md b/src/workflows/2-design/gds-create-prd/steps-c/step-12-complete.md similarity index 98% rename from src/workflows/2-design/create-prd/steps-c/step-12-complete.md rename to src/workflows/2-design/gds-create-prd/steps-c/step-12-complete.md index 04204e8..1994539 100644 --- a/src/workflows/2-design/create-prd/steps-c/step-12-complete.md +++ b/src/workflows/2-design/gds-create-prd/steps-c/step-12-complete.md @@ -4,7 +4,7 @@ description: 'Complete the PRD workflow, update status files, and suggest next s # File References outputFile: '{planning_artifacts}/prd.md' -validationFlow: '../steps-v/step-v-01-discovery.md' +checkImplementationReadinessWorkflow: 'skill:gds-check-implementation-readiness' --- # Step 12: Workflow Completion diff --git a/src/workflows/2-design/create-prd/templates/prd-template.md b/src/workflows/2-design/gds-create-prd/templates/prd-template.md similarity index 100% rename from src/workflows/2-design/create-prd/templates/prd-template.md rename to src/workflows/2-design/gds-create-prd/templates/prd-template.md diff --git a/src/workflows/2-design/create-prd/workflow-create-prd.md b/src/workflows/2-design/gds-create-prd/workflow.md similarity index 99% rename from src/workflows/2-design/create-prd/workflow-create-prd.md rename to src/workflows/2-design/gds-create-prd/workflow.md index 7b36a74..4e7bbad 100644 --- a/src/workflows/2-design/create-prd/workflow-create-prd.md +++ b/src/workflows/2-design/gds-create-prd/workflow.md @@ -1,5 +1,5 @@ --- -name: create-prd +name: gds-create-prd description: '(Optional) Create a PRD for use with external tools like bmad-assist. Uses the GDD as a base if available, otherwise creates from scratch. Use when the user says "create a PRD" or "generate PRD from GDD"' main_config: '{module_config}' nextStep: './steps-c/step-01-init.md' diff --git a/src/workflows/2-design/gds-edit-gdd/SKILL.md b/src/workflows/2-design/gds-edit-gdd/SKILL.md new file mode 100644 index 0000000..7385320 --- /dev/null +++ b/src/workflows/2-design/gds-edit-gdd/SKILL.md @@ -0,0 +1,6 @@ +--- +name: gds-edit-gdd +description: 'Edit an existing Game Design Document. Use when the user says "edit this GDD" or "improve this GDD".' +--- + +Follow the instructions in ./workflow.md. diff --git a/src/workflows/gds-quick-flow/gds-quick-spec/bmad-skill-manifest.yaml b/src/workflows/2-design/gds-edit-gdd/bmad-skill-manifest.yaml similarity index 100% rename from src/workflows/gds-quick-flow/gds-quick-spec/bmad-skill-manifest.yaml rename to src/workflows/2-design/gds-edit-gdd/bmad-skill-manifest.yaml diff --git a/src/workflows/2-design/gds-edit-gdd/data/gdd-purpose.md b/src/workflows/2-design/gds-edit-gdd/data/gdd-purpose.md new file mode 100644 index 0000000..d4a374f --- /dev/null +++ b/src/workflows/2-design/gds-edit-gdd/data/gdd-purpose.md @@ -0,0 +1,224 @@ +# BMAD GDD Purpose + +**The GDD is the primary planning artifact in the Game Dev Studio (GDS) module. It feeds every downstream phase: architecture, epics, production, and playtesting.** + +In GDS, the PRD is optional and exists only for external-tool compatibility. The GDD is the canonical source of truth for game design intent. + +--- + +## What is a BMAD GDD? + +A dual-audience document serving: + +1. **Human game designers, producers, and developers** - Vision, pillars, team alignment, playtest briefs +2. **LLM downstream consumption** - Architecture → Epics → Dev stories → Playtest plans → Game Dev AI Agents + +Each successive artifact becomes more granular and more AI-tailored. The GDD is where the design intent is captured in its purest form, before engine and implementation concerns enter the picture. + +--- + +## Core Philosophy: Information Density + +**High Signal-to-Noise Ratio on Game Mechanics** + +Every sentence must carry design information. LLMs consume precise, dense content efficiently - and game design already suffers from pitch-deck-style fluff. + +**Anti-Patterns (Eliminate These):** + +- ❌ "The player will be able to..." → ✅ "The player can..." +- ❌ "It is our intention to create a game that..." → ✅ State the design directly +- ❌ "Players will experience fun and engaging gameplay" → ✅ Describe the specific mechanic that produces engagement +- ❌ Marketing copy and pitch language → ✅ Concrete mechanics, systems, and numbers + +**Goal:** Maximum design information per word. Zero fluff, zero marketing. + +--- + +## The Traceability Chain + +**GDD starts the chain:** + +``` +Core Fantasy / Vision → Game Pillars → Core Gameplay Loop → Mechanics & Systems → Epics → Stories +``` + +**In the GDD, establish:** + +- Vision → Pillars alignment +- Pillars → Gameplay Loop reinforcement (the loop should embody the pillars) +- Gameplay Loop → Mechanics mapping (each mechanic serves the loop) +- Mechanics → Epics (each epic delivers mechanics) +- All content traceable to the core fantasy + +**Why:** Every downstream artifact (architecture, epics, stories, playtest plans) must trace back to documented design intent. This chain is what prevents scope creep, feature bloat, and mechanics that exist for their own sake. + +--- + +## What Makes Great Mechanics and Systems? + +### Mechanics are Player-Facing Capabilities, Not Implementation + +**Good:** "The player can dash in any of 8 directions, consuming 1 stamina pip. Stamina regenerates at 1 pip/second while grounded." +**Bad:** "We use a Rigidbody2D with AddForce and a cooldown coroutine" (engine leakage - belongs in architecture) + +**Good:** "Frame-perfect parries reward a 1.5x damage multiplier for 3 seconds." +**Bad:** "Combat feels responsive and satisfying" (subjective, unmeasurable) + +### SMART Quality Criteria (Adapted for Game Design) + +**Specific:** Clear, precisely defined mechanic or system +**Measurable:** Quantifiable values (timings, damages, costs, ranges) +**Attainable:** Realistic within target platform, team, and timeline +**Relevant:** Reinforces a game pillar or the core loop +**Traceable:** Links to the vision, a pillar, or a specific player fantasy + +### Mechanics Anti-Patterns + +**Subjective Adjectives:** + +- ❌ "fun", "satisfying", "immersive", "responsive", "deep" +- ✅ Use concrete values: "chain combos extend the hit window by 6 frames per successful hit" + +**Engine / Implementation Leakage:** + +- ❌ Engine APIs, node names, specific shaders, class hierarchies +- ✅ Focus on player experience and system behavior - the engine is architecture's problem + +**Vague Quantifiers:** + +- ❌ "many enemies", "several weapons", "various environments" +- ✅ "12 enemy archetypes", "6 primary weapons + 18 unlockable variants", "3 biomes × 4 sub-zones" + +**Missing Feel Criteria:** + +- ❌ "The jump feels good" +- ✅ "Jump height: 3 tiles. Air time: 0.55s. Coyote time: 6 frames. Buffer window: 8 frames." + +--- + +## What Makes Great Technical Constraints? + +### Target Specs Must Be Measurable + +**Template:** + +``` +"The game shall [metric] [platform/condition] [measurement method]" +``` + +**Examples:** + +- ✅ "Maintain 60 FPS sustained on Steam Deck at 720p Medium settings, as measured by in-engine profiler over a 10-minute combat loop" +- ✅ "First-playable load time under 15s on PS5 from cold boot" +- ✅ "Memory budget: 4GB on PS4, 6GB on PS5, as measured by PIX capture" + +### Constraint Anti-Patterns + +**Unmeasurable Claims:** + +- ❌ "Runs well on all platforms" → ✅ "60 FPS on PS5/XSX, 30 FPS on PS4/XB1" +- ❌ "Fast load times" → ✅ "Sub-5-second level transitions on target hardware" + +**Missing Context:** + +- ❌ "60 FPS target" → ✅ "60 FPS during combat encounters with up to 6 enemies on-screen, measured on Steam Deck" + +--- + +## Genre-Specific Requirements + +**Auto-Detect and Enforce Based on Game Type** + +Certain genres carry conventions that must be documented: + +- **Action/Platformer:** Precise movement values (jump arc, coyote time, input buffer), hit/hurt box conventions, damage formulae +- **RPG:** Stat system, leveling curve, inventory rules, quest state machine, save/load boundaries +- **Roguelike:** Run structure, meta-progression rules, seed determinism, balance bands +- **Multiplayer (MOBA/Shooter):** Netcode model (lockstep/rollback/client-predict), tick rate, lag tolerance, matchmaking +- **Puzzle:** Solution space guarantees, hint systems, difficulty ramp +- **Narrative/Visual Novel:** Branching structure, variable/flag system, rewind/save model + +**Why:** Missing genre conventions in the GDD means they surface as emergencies during production. Validation should catch these up front. Steps use a `genre-complexity.csv` data file to drive genre-specific expectations. + +--- + +## Document Structure (Markdown, Human-Readable) + +### Required Sections (canonical gds-create-gdd schema) + +1. **Executive Summary** - Core concept, target audience, USPs +2. **Goals and Context** - Project goals, background, rationale +3. **Core Gameplay** - Pillars, core gameplay loop, win/loss conditions +4. **Game Mechanics** - Primary mechanics, controls and input +5. **Game-Type Specific Sections** - Genre-driven sections (e.g., RPG stats, roguelike run structure) +6. **Progression and Balance** - Player progression, difficulty curve, economy +7. **Level Design Framework** - Level types, progression +8. **Art and Audio Direction** - Visual style, audio approach +9. **Technical Specifications** - Performance targets, platform specs, asset budget +10. **Development Epics** - High-level delivery breakdown +11. **Success Metrics** - Technical and gameplay success criteria +12. **Out of Scope** - Explicit scope boundaries +13. **Assumptions and Dependencies** - External risks + +### Formatting for Dual Consumption + +**For Humans:** + +- Clear, direct language - no pitch-deck bloat +- Logical flow from vision to execution +- Easy for producers, leads, and external collaborators to review + +**For LLMs:** + +- `##` Level 2 headers for all main sections (enables extraction) +- Consistent structure and patterns +- Concrete numbers wherever possible +- High information density + +--- + +## Downstream Impact + +**How the GDD Feeds Next Artifacts:** + +**Architecture:** + +- Mechanics → system design (physics, AI, state machines) +- Technical specs → engine choice, rendering pipeline, memory layout +- Genre conventions → framework decisions (netcode model, save system) + +**Epics & Stories:** + +- Mechanics → epics (1 mechanic often = 1 epic) +- Level framework → content stories +- Progression → systems stories +- Traceability → stories map back to pillars + +**Playtesting / Gametest:** + +- Pillars → playtest focus areas +- Success metrics → playtest success criteria +- Core loop → the thing we're actually testing + +**Development AI Agents:** + +- Precise mechanics → implementation clarity +- Measurable specs → automated performance gates +- Genre conventions → framework selection +- Success metrics → telemetry targets + +--- + +## Summary: What Makes a Great BMAD GDD? + +✅ **High Information Density** - Every sentence carries design weight, zero pitch-deck fluff +✅ **Measurable Mechanics** - Concrete numbers for timings, damages, costs, ranges +✅ **Clear Traceability** - Each mechanic links to a pillar or core loop, each pillar to the vision +✅ **Genre Awareness** - Genre-specific sections auto-detected and included +✅ **Zero Anti-Patterns** - No subjective adjectives, no engine leakage, no vague quantifiers +✅ **Dual Audience Optimized** - Human-readable AND LLM-consumable +✅ **Markdown Format** - Professional, clean, accessible to designers and AI tools alike + +--- + +**Remember:** The GDD is the foundation of GDS. Quality here ripples through architecture, epics, stories, and playtesting. A dense, precise, well-traced GDD makes every downstream phase dramatically more effective - and prevents the "we never actually decided what this game is" spiral that kills projects. diff --git a/src/workflows/2-design/gds-edit-gdd/steps-e/step-e-01-discovery.md b/src/workflows/2-design/gds-edit-gdd/steps-e/step-e-01-discovery.md new file mode 100644 index 0000000..3a1b8d4 --- /dev/null +++ b/src/workflows/2-design/gds-edit-gdd/steps-e/step-e-01-discovery.md @@ -0,0 +1,264 @@ +--- +name: 'step-e-01-discovery' +description: 'Discovery & Understanding - Understand what user wants to edit and detect GDD format' + +# File references (ONLY variables used in this step) +altStepFile: './step-e-01b-legacy-conversion.md' +nextStepFile: './step-e-02-review.md' +gddPurpose: '../data/gdd-purpose.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: 'skill:bmad-party-mode' +--- + +# Step E-1: Discovery & Understanding + +## STEP GOAL: + +Understand what the user wants to edit in the GDD, detect GDD format/type, check for validation report guidance, and route appropriately. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and GDD Improvement Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in collaborative dialogue, not command-response +- ✅ You bring analytical expertise and game-design improvement guidance +- ✅ User brings game vision, design intent, and edit requirements + +### Step-Specific Rules: + +- 🎯 Focus ONLY on discovering user intent and GDD format +- 🚫 FORBIDDEN to make any edits yet +- 💬 Approach: Inquisitive and analytical, understanding before acting +- 🚪 This is a branch step - may route to legacy conversion + +## EXECUTION PROTOCOLS: + +- 🎯 Discover user's edit requirements +- 🎯 Auto-detect validation reports in GDD folder (use as guide) +- 🎯 Load validation report if provided (use as guide) +- 🎯 Detect GDD format (canonical gds-create-gdd schema / legacy or external) +- 🎯 Route appropriately based on format +- 💾 Document discoveries for next step +- 🚫 FORBIDDEN to proceed without understanding requirements + +## CONTEXT BOUNDARIES: + +- Available context: GDD file to edit, optional validation report, auto-detected validation reports +- Focus: User intent discovery and format detection only +- Limits: Don't edit yet, don't validate yet +- Dependencies: None - this is first edit step + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Load GDD Purpose Standards + +Load and read the complete file at: +`{gddPurpose}` (data/gdd-purpose.md) + +This file defines what makes a great BMAD GDD. Internalize this understanding - it will guide improvement recommendations. + +### 2. Discover GDD to Edit + +"**GDD Edit Workflow** + +Which GDD would you like to edit? + +Default location: `{planning_artifacts}/gdd.md` + +Provide the path to the GDD file you want to edit, or press Enter to use the default." + +**Wait for user to provide GDD path (or accept default).** + +### 3. Validate GDD Exists and Load + +Once GDD path is provided: + +- Check if GDD file exists at specified path +- If not found, also try fuzzy match: `{planning_artifacts}/*gdd*.md` +- If still not found: "I cannot find a GDD at that path. Please check the path and try again." +- If found: Load the complete GDD file including frontmatter + +### 4. Check for Existing Validation Report + +**Check if validation report exists in the GDD folder:** + +```bash +# Look for most recent validation report in the GDD folder +ls -t {gdd_folder_path}/validation-report-*.md 2>/dev/null | head -1 +``` + +**If validation report found:** + +Display: +"**📋 Found Validation Report** + +I found a validation report from {validation_date} in the GDD folder. + +This report contains findings from previous validation checks and can help guide our edits to fix known issues. + +**Would you like to:** + +- **[U] Use validation report** - Load it to guide and prioritize edits +- **[S] Skip** - Proceed with manual edit discovery" + +**Wait for user input.** + +**IF U (Use validation report):** + +- Load the validation report file +- Extract findings, issues, and improvement suggestions +- Note: "Validation report loaded - will use it to guide prioritized improvements" +- Continue to step 5 + +**IF S (Skip) or no validation report found:** + +- Note: "Proceeding with manual edit discovery" +- Continue to step 5 + +**If no validation report found:** + +- Note: "No validation report found in GDD folder" +- Continue to step 5 without asking user + +### 5. Ask About Validation Report (Manual Path) + +"**Do you have a validation report to guide edits?** + +If you've run the validation workflow on this GDD, I can use that report to guide improvements and prioritize changes. + +Validation report path (or type 'none'):" + +**Wait for user input.** + +**If validation report path provided:** + +- Load the validation report +- Extract findings, severity, improvement suggestions +- Note: "Validation report loaded - will use it to guide prioritized improvements" + +**If no validation report:** + +- Note: "Proceeding with manual edit discovery" +- Continue to step 6 + +### 6. Discover Edit Requirements + +"**What would you like to edit in this GDD?** + +Describe the changes you want to make. For example: + +- Tighten specific sections (mechanics measurability, vision clarity, etc.) +- Add missing sections or content (e.g., out-of-scope, success metrics) +- Rework the core gameplay loop or pillars +- Adjust progression and balance +- Convert to canonical gds-create-gdd schema (if GDD came from an external tool) +- Remove engine/implementation details that belong in architecture +- General improvements + +**Describe your edit goals:**" + +**Wait for user to describe their requirements.** + +### 7. Detect GDD Format + +Analyze the loaded GDD: + +**Extract all ## Level 2 headers** from GDD + +**Check for canonical gds-create-gdd core sections:** + +1. Executive Summary +2. Goals and Context +3. Core Gameplay +4. Game Mechanics +5. Progression and Balance +6. Technical Specifications +7. Development Epics (or Epic Structure) + +**Classify format:** + +- **Canonical GDS Schema:** 6-7 core sections present, follows gds-create-gdd structure +- **GDS Variant:** 4-5 core sections present, generally follows the pattern with gaps +- **Legacy / External (Non-Standard):** Fewer than 4 core sections, from an external tool or legacy GDD template + +### 8. Route Based on Format and Context + +**IF validation report provided OR GDD is Canonical/Variant:** + +Display: "**Edit Requirements Understood** + +**GDD Format:** {classification} +{If validation report: "**Validation Guide:** Yes - will use validation report findings"} +**Edit Goals:** {summary of user's requirements} + +**Proceeding to deep review and analysis...**" + +Read fully and follow: {nextStepFile} (step-e-02-review.md) + +**IF GDD is Legacy (Non-Standard) AND no validation report:** + +Display: "**Format Detected:** Legacy / External GDD + +This GDD does not follow the canonical gds-create-gdd structure (only {count}/7 core sections present). + +**Your edit goals:** {user's requirements} + +**How would you like to proceed?**" + +Present MENU OPTIONS below for user selection + +### 9. Present MENU OPTIONS (Legacy GDDs Only) + +**[C] Convert to Canonical GDS Schema** - Convert GDD to gds-create-gdd structure, then apply your edits +**[E] Edit As-Is** - Apply your edits without converting the format +**[X] Exit** - Exit and review conversion options + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input +- Only proceed based on user selection + +#### Menu Handling Logic: + +- IF C (Convert): Read fully and follow: {altStepFile} (step-e-01b-legacy-conversion.md) +- IF E (Edit As-Is): Display "Proceeding with edits..." then read fully and follow: {nextStepFile} +- IF X (Exit): Display summary and exit +- IF Any other: help user, then redisplay menu + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- User's edit requirements clearly understood +- Auto-detected validation reports loaded and analyzed (when found) +- Manual validation report loaded and analyzed (if provided) +- GDD format detected correctly against canonical gds-create-gdd schema +- Canonical/Variant GDDs proceed directly to review step +- Legacy/external GDDs pause and present conversion options +- User can choose conversion path or edit as-is + +### ❌ SYSTEM FAILURE: + +- Not discovering user's edit requirements +- Not auto-detecting validation reports in GDD folder +- Not loading validation report when provided (auto or manual) +- Missing format detection +- Not pausing for legacy GDDs without guidance +- Auto-proceeding without understanding intent + +**Master Rule:** Understand before editing. Detect format early so we can guide users appropriately. Auto-detect and use validation reports for prioritized improvements. diff --git a/src/workflows/2-design/gds-edit-gdd/steps-e/step-e-01b-legacy-conversion.md b/src/workflows/2-design/gds-edit-gdd/steps-e/step-e-01b-legacy-conversion.md new file mode 100644 index 0000000..29452eb --- /dev/null +++ b/src/workflows/2-design/gds-edit-gdd/steps-e/step-e-01b-legacy-conversion.md @@ -0,0 +1,226 @@ +--- +name: 'step-e-01b-legacy-conversion' +description: 'Legacy GDD Conversion Assessment - Analyze legacy/external GDD and propose conversion strategy' + +# File references (ONLY variables used in this step) +nextStepFile: './step-e-02-review.md' +gddFile: '{gdd_file_path}' +gddPurpose: '../data/gdd-purpose.md' +--- + +# Step E-1B: Legacy GDD Conversion Assessment + +## STEP GOAL: + +Analyze a legacy or external-tool GDD against the canonical gds-create-gdd schema, identify gaps, propose a conversion strategy, and let the user choose how to proceed. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and GDD Improvement Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in collaborative dialogue, not command-response +- ✅ You bring BMAD GDD standards expertise and conversion guidance +- ✅ User brings game design knowledge and edit requirements + +### Step-Specific Rules: + +- 🎯 Focus ONLY on conversion assessment and proposal +- 🚫 FORBIDDEN to perform conversion yet (that comes in the edit step) +- 💬 Approach: Analytical gap analysis with clear recommendations +- 🚪 This is a branch step - user chooses conversion path + +## EXECUTION PROTOCOLS: + +- 🎯 Analyze legacy GDD against canonical gds-create-gdd schema +- 💾 Identify gaps and estimate conversion effort +- 📖 Present conversion options with effort estimates +- 🚫 FORBIDDEN to proceed without user selection + +## CONTEXT BOUNDARIES: + +- Available context: Legacy GDD, user's edit requirements, gdd-purpose standards +- Focus: Conversion assessment only (not actual conversion) +- Limits: Don't convert yet, don't validate yet +- Dependencies: Step e-01 detected legacy format and routed here + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Attempt Sub-Process Assessment + +**Try to use Task tool with sub-agent:** + +"Perform legacy GDD conversion assessment: + +**Load the GDD and gdd-purpose.md** + +**For each canonical gds-create-gdd section, analyze:** + +1. Does the GDD have this section? (Executive Summary, Goals and Context, Core Gameplay, Game Mechanics, Progression and Balance, Technical Specifications, Development Epics) +2. If present: Is it complete and well-structured? +3. If missing: What content exists that could migrate to this section? +4. Effort to create/complete: Minimal / Moderate / Significant + +**Identify:** + +- Core sections present: {count}/7 +- Content gaps in each section +- Overall conversion effort: Quick / Moderate / Substantial +- Recommended approach: Full restructuring vs targeted improvements + +Return conversion assessment with gap analysis and effort estimate." + +**Graceful degradation (if no Task tool):** + +- Manually check GDD for each canonical section +- Note what's present and what's missing +- Estimate conversion effort +- Identify best conversion approach + +### 2. Build Gap Analysis + +**For each canonical gds-create-gdd core section:** + +**Executive Summary (core concept, target audience, USPs):** + +- Present: [Yes/No/Partial] +- Gap: [what's missing or incomplete] +- Effort to Complete: [Minimal/Moderate/Significant] + +**Goals and Context (project goals, background, rationale):** + +- Present: [Yes/No/Partial] +- Gap: [what's missing or incomplete] +- Effort to Complete: [Minimal/Moderate/Significant] + +**Core Gameplay (pillars, core loop, win/loss conditions):** + +- Present: [Yes/No/Partial] +- Gap: [what's missing or incomplete] +- Effort to Complete: [Minimal/Moderate/Significant] + +**Game Mechanics (primary mechanics, controls):** + +- Present: [Yes/No/Partial] +- Gap: [what's missing or incomplete] +- Effort to Complete: [Minimal/Moderate/Significant] + +**Progression and Balance (progression, difficulty curve, economy):** + +- Present: [Yes/No/Partial] +- Gap: [what's missing or incomplete] +- Effort to Complete: [Minimal/Moderate/Significant] + +**Technical Specifications (performance targets, platform specs):** + +- Present: [Yes/No/Partial] +- Gap: [what's missing or incomplete] +- Effort to Complete: [Minimal/Moderate/Significant] + +**Development Epics (high-level delivery breakdown):** + +- Present: [Yes/No/Partial] +- Gap: [what's missing or incomplete] +- Effort to Complete: [Minimal/Moderate/Significant] + +**Overall Assessment:** + +- Sections Present: {count}/7 +- Total Conversion Effort: [Quick/Moderate/Substantial] +- Recommended: [Full restructuring / Targeted improvements] + +### 3. Present Conversion Assessment + +Display: + +"**Legacy GDD Conversion Assessment** + +**Current GDD Structure:** + +- Core sections present: {count}/7 + {List which sections are present/missing} + +**Gap Analysis:** + +{Present gap analysis table showing each section's status and effort} + +**Overall Conversion Effort:** {effort level} + +**Your Edit Goals:** +{Reiterate user's stated edit requirements} + +**Recommendation:** +{Based on effort and user goals, recommend best approach} + +**How would you like to proceed?**" + +### 4. Present MENU OPTIONS + +**[R] Restructure to Canonical GDS Schema** - Full conversion to gds-create-gdd structure, then apply your edits +**[I] Targeted Improvements** - Apply your edits to existing structure without restructuring +**[E] Edit & Restructure** - Do both: convert format AND apply your edits +**[X] Exit** - Review assessment and decide + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input +- Only proceed based on user selection + +#### Menu Handling Logic: + +- IF R (Restructure): Note conversion mode, then load next step +- IF I (Targeted): Note targeted mode, then load next step +- IF E (Edit & Restructure): Note both mode, then load next step +- IF X (Exit): Display summary, exit + +### 5. Document Conversion Strategy + +Store conversion decision for next step: + +- **Conversion mode:** [Full restructuring / Targeted improvements / Both] +- **Edit requirements:** [user's requirements from step e-01] +- **Gap analysis:** [summary of gaps identified] + +Display: "**Conversion Strategy Documented** + +Mode: {conversion mode} +Edit goals: {summary} + +**Proceeding to deep review...**" + +Read fully and follow: {nextStepFile} (step-e-02-review.md) + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- All 7 canonical core sections analyzed for gaps +- Effort estimates provided for each section +- Overall conversion effort assessed correctly +- Clear recommendation provided based on effort and user goals +- User chooses conversion strategy (restructure/targeted/both) +- Conversion strategy documented for next step + +### ❌ SYSTEM FAILURE: + +- Not analyzing all 7 core sections +- Missing effort estimates +- Not providing clear recommendation +- Auto-proceeding without user selection +- Not documenting conversion strategy + +**Master Rule:** Legacy GDDs need conversion assessment so users understand the work involved and can choose the best approach. diff --git a/src/workflows/2-design/gds-edit-gdd/steps-e/step-e-02-review.md b/src/workflows/2-design/gds-edit-gdd/steps-e/step-e-02-review.md new file mode 100644 index 0000000..9370f8e --- /dev/null +++ b/src/workflows/2-design/gds-edit-gdd/steps-e/step-e-02-review.md @@ -0,0 +1,264 @@ +--- +name: 'step-e-02-review' +description: 'Deep Review & Analysis - Thoroughly review the existing GDD and prepare a detailed change plan' + +# File references (ONLY variables used in this step) +nextStepFile: './step-e-03-edit.md' +gddFile: '{gdd_file_path}' +validationReport: '{validation_report_path}' +gddPurpose: '../data/gdd-purpose.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: 'skill:bmad-party-mode' +--- + +# Step E-2: Deep Review & Analysis + +## STEP GOAL: + +Thoroughly review the existing GDD, analyze validation report findings (if provided), and prepare a detailed change plan before editing. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and GDD Improvement Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in collaborative dialogue, not command-response +- ✅ You bring analytical expertise and improvement planning +- ✅ User brings game vision and approval authority + +### Step-Specific Rules: + +- 🎯 Focus ONLY on review and analysis, not editing yet +- 🚫 FORBIDDEN to make changes to the GDD in this step +- 💬 Approach: Thorough analysis with user confirmation on plan +- 🚪 This is a middle step - user confirms plan before proceeding + +## EXECUTION PROTOCOLS: + +- 🎯 Load and analyze validation report (if provided) +- 🎯 Deep review of entire GDD +- 🎯 Map validation findings to specific sections +- 🎯 Prepare detailed change plan +- 💬 Get user confirmation on plan +- 🚫 FORBIDDEN to proceed to edit without user approval + +## CONTEXT BOUNDARIES: + +- Available context: GDD file, validation report (if provided), user requirements from step e-01 +- Focus: Analysis and planning only (no editing) +- Limits: Don't change the GDD yet, don't validate yet +- Dependencies: Step e-01 completed - requirements and format known + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Attempt Sub-Process Deep Review + +**Try to use Task tool with sub-agent:** + +"Perform deep GDD review and change planning: + +**Context from step e-01:** + +- User's edit requirements: {user_requirements} +- GDD format: {canonical / variant / legacy} +- Validation report provided: {yes/no} +- Conversion mode: {restructure/targeted/both} (if legacy) + +**IF validation report provided:** + +1. Extract all findings from validation report +2. Map findings to specific GDD sections +3. Prioritize by severity: Critical > Warning > Informational +4. For each critical issue: identify the specific fix needed +5. For user's manual edit goals: identify where in the GDD to apply + +**IF no validation report:** + +1. Read the entire GDD thoroughly +2. Analyze against BMAD GDD standards (from gdd-purpose.md) +3. Identify issues in: + - Information density (pitch-deck fluff, subjective adjectives) + - Structure and flow (pillars → loop → mechanics coherence) + - Completeness (missing sections: out of scope, success metrics, etc.) + - Measurability (mechanics without concrete values, vague tech targets) + - Traceability (mechanics that don't serve a pillar, orphan systems) + - Engine / implementation leakage (engine class names, shader details, etc.) +4. Map user's edit goals to specific sections + +**Output:** + +- Section-by-section analysis +- Specific changes needed for each section +- Prioritized action list +- Recommended order for applying changes + +Return detailed change plan with section breakdown." + +**Graceful degradation (if no Task tool):** + +- Manually read GDD sections +- Manually analyze validation report findings (if provided) +- Build section-by-section change plan +- Prioritize changes by severity / user goals + +### 2. Build Change Plan + +**Organize by GDD section:** + +**For each section (in order):** + +- **Current State:** Brief description of what exists +- **Issues Identified:** [List from validation report or manual analysis] +- **Changes Needed:** [Specific changes required] +- **Priority:** [Critical/High/Medium/Low] +- **User Requirements Met:** [Which user edit goals address this section] + +**Include:** + +- Sections to add (if missing - e.g., Out of Scope, Success Metrics) +- Sections to update (if present but needs work) +- Content to remove (if engine leakage or off-topic) +- Structure changes (if reformatting to canonical GDS schema) + +### 3. Prepare Change Plan Summary + +**Summary sections:** + +**Changes by Type:** + +- **Additions:** {count} sections to add +- **Updates:** {count} sections to update +- **Removals:** {count} items to remove (including engine/implementation detail cleanup) +- **Restructuring:** {yes/no} if format conversion to canonical GDS schema is needed + +**Priority Distribution:** + +- **Critical:** {count} changes (must fix) +- **High:** {count} changes (important) +- **Medium:** {count} changes (nice to have) +- **Low:** {count} changes (optional) + +**Estimated Effort:** +[Quick/Moderate/Substantial] based on scope and complexity + +### 4. Present Change Plan to User + +Display: + +"**Deep Review Complete - Change Plan** + +**GDD Analysis:** +{Brief summary of GDD current state} + +{If validation report provided:} +**Validation Findings:** +{count} issues identified: {critical} critical, {warning} warnings + +**Your Edit Requirements:** +{summary of what user wants to edit} + +**Proposed Change Plan:** + +**By Section:** +{Present section-by-section breakdown} + +**By Priority:** + +- Critical: {count} items +- High: {count} items +- Medium: {count} items + +**Estimated Effort:** {effort level} + +**Questions:** + +1. Does this change plan align with what you had in mind? +2. Any sections I should add/remove/reprioritize? +3. Any concerns before I proceed with edits? + +**Review the plan and let me know if you'd like any adjustments.**" + +### 5. Get User Confirmation + +Wait for user to review and provide feedback. + +**If user wants adjustments:** + +- Discuss requested changes +- Revise change plan accordingly +- Represent for confirmation + +**If user approves:** + +- Note: "Change plan approved. Proceeding to edit step." +- Continue to step 6 + +### 6. Document Approved Plan + +Store approved change plan for next step: + +- **Approved changes:** Section-by-section list +- **Priority order:** Sequence to apply changes +- **User confirmed:** Yes + +Display: "**Change Plan Approved** + +{Brief summary of approved plan} + +**Proceeding to edit step...**" + +Read fully and follow: {nextStepFile} (step-e-03-edit.md) + +### 7. Present MENU OPTIONS (If User Wants Discussion) + +**[A] Advanced Elicitation** - Get additional perspectives on change plan +**[P] Party Mode** - Discuss with team for more ideas +**[C] Continue to Edit** - Proceed with approved plan + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input +- Only proceed to edit when user selects 'C' + +#### Menu Handling Logic: + +- IF A: Read fully and follow: {advancedElicitationTask}, then return to discussion +- IF P: Read fully and follow: {partyModeWorkflow}, then return to discussion +- IF C: Document approval, then load {nextStepFile} +- IF Any other: discuss, then redisplay menu + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- Validation report findings fully analyzed (if provided) +- Deep GDD review completed systematically +- Change plan built section-by-section +- Changes prioritized by severity / user goals +- User presented with clear plan +- User confirms or adjusts plan +- Approved plan documented for next step + +### ❌ SYSTEM FAILURE: + +- Not analyzing validation report findings (if provided) +- Superficial review instead of deep analysis +- Missing section-by-section breakdown +- Not prioritizing changes +- Proceeding without user approval + +**Master Rule:** Plan before editing. Thorough analysis ensures we make the right changes in the right order. User approval prevents misalignment. diff --git a/src/workflows/2-design/gds-edit-gdd/steps-e/step-e-03-edit.md b/src/workflows/2-design/gds-edit-gdd/steps-e/step-e-03-edit.md new file mode 100644 index 0000000..aaaba68 --- /dev/null +++ b/src/workflows/2-design/gds-edit-gdd/steps-e/step-e-03-edit.md @@ -0,0 +1,273 @@ +--- +name: 'step-e-03-edit' +description: 'Edit & Update - Apply changes to the GDD following the approved change plan' + +# File references (ONLY variables used in this step) +nextStepFile: './step-e-04-complete.md' +gddFile: '{gdd_file_path}' +gddPurpose: '../data/gdd-purpose.md' +validationWorkflow: 'skill:gds-validate-gdd' +--- + +# Step E-3: Edit & Update + +## STEP GOAL: + +Apply changes to the GDD following the approved change plan from step e-02, including content updates, structure improvements, and format conversion to the canonical gds-create-gdd schema if needed. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 ALWAYS generate content WITH user input/approval +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and GDD Improvement Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in collaborative dialogue, not command-response +- ✅ You bring analytical expertise and precise editing skills +- ✅ User brings game vision and approval authority + +### Step-Specific Rules: + +- 🎯 Focus ONLY on implementing approved changes from step e-02 +- 🚫 FORBIDDEN to make changes beyond the approved plan +- 💬 Approach: Methodical, section-by-section execution +- 🚪 This is a middle step - user can request adjustments + +## EXECUTION PROTOCOLS: + +- 🎯 Follow approved change plan systematically +- 💾 Edit GDD content according to plan +- 📖 Update frontmatter as needed +- 🚫 FORBIDDEN to proceed without completion + +## CONTEXT BOUNDARIES: + +- Available context: GDD file, approved change plan from step e-02, gdd-purpose standards +- Focus: Implementing changes from approved plan only +- Limits: Don't add changes beyond plan, don't validate yet +- Dependencies: Step e-02 completed - plan approved by user + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Retrieve Approved Change Plan + +From step e-02, retrieve: + +- **Approved changes:** Section-by-section list +- **Priority order:** Sequence to apply changes +- **User requirements:** Edit goals from step e-01 + +Display: "**Starting GDD Edits** + +**Change Plan:** {summary} +**Total Changes:** {count} +**Estimated Effort:** {effort level} + +**Proceeding with edits section by section...**" + +### 2. Attempt Sub-Process Edits (For Complex Changes) + +**Try to use Task tool with sub-agent for major sections:** + +"Execute GDD edits for {section_name}: + +**Context:** + +- Section to edit: {section_name} +- Current content: {existing content} +- Changes needed: {specific changes from plan} +- BMAD GDD standards: Load from gdd-purpose.md + +**Tasks:** + +1. Read current GDD section +2. Apply specified changes +3. Ensure BMAD GDD principles compliance: + - High information density (no pitch-deck fluff) + - Measurable mechanics (concrete numbers for timings, damages, costs) + - Clear traceability to pillars and core loop + - No engine/implementation leakage (engine details belong in architecture) + - Proper markdown formatting +4. Return updated section content + +Apply changes and return updated section." + +**Graceful degradation (if no Task tool):** + +- Perform edits directly in current context +- Load GDD section, apply changes, save + +### 3. Execute Changes Section-by-Section + +**For each section in the approved plan (in priority order):** + +**a) Load current section** + +- Read the current GDD section content +- Note what exists + +**b) Apply changes per plan** + +- Additions: Create new sections with proper content (e.g., Out of Scope, Success Metrics) +- Updates: Modify existing content per plan +- Removals: Remove specified content (including engine/implementation detail leakage) +- Restructuring: Reformat content to canonical GDS schema + +**c) Update GDD file** + +- Apply changes to the GDD +- Save updated GDD +- Verify changes applied correctly + +**Display progress after each section:** +"**Section Updated:** {section_name} +Changes: {brief summary} +{More sections remaining...}" + +### 4. Handle Restructuring (If Needed) + +**If conversion mode is "Full restructuring" or "Both":** + +**For restructuring:** + +- Reorganize GDD to the canonical gds-create-gdd schema +- Ensure proper `##` Level 2 headers +- Reorder sections logically +- Update GDD frontmatter to match canonical format + +**Follow canonical GDS schema section order:** + +1. Executive Summary +2. Goals and Context +3. Core Gameplay +4. Game Mechanics +5. Game-Type Specific Sections (if applicable) +6. Progression and Balance +7. Level Design Framework +8. Art and Audio Direction +9. Technical Specifications +10. Development Epics +11. Success Metrics +12. Out of Scope +13. Assumptions and Dependencies + +Display: "**GDD Restructured** +Canonical GDS schema applied. +{Sections added/reordered}" + +### 5. Update GDD Frontmatter + +**Ensure frontmatter is complete and accurate:** + +```yaml +--- +workflowType: 'gdd' +workflow: 'edit' # or 'create' or 'validate' +classification: + gameType: '{game_type}' + platforms: '{platforms}' + genreComplexity: '{complexity}' +inputDocuments: [list of input documents] +stepsCompleted: ['step-e-01-discovery', 'step-e-02-review', 'step-e-03-edit'] +lastEdited: '{current_date}' +editHistory: + - date: '{current_date}' + changes: '{summary of changes}' +--- +``` + +**Update frontmatter accordingly.** + +### 6. Final Review of Changes + +**Load complete updated GDD** + +**Verify:** + +- All approved changes applied correctly +- GDD structure is sound +- No unintended modifications +- Frontmatter is accurate + +**If issues found:** + +- Fix them now +- Note corrections made + +**If user wants adjustments:** + +- Accept feedback and make adjustments +- Re-verify after adjustments + +### 7. Confirm Completion + +Display: + +"**GDD Edits Complete** + +**Changes Applied:** {count} sections modified +**GDD Updated:** {gdd_file_path} + +**Summary of Changes:** +{Brief bullet list of major changes} + +**GDD is ready for:** + +- Use in downstream GDS workflows (architecture, epics, production) +- Validation (if not yet validated) + +**What would you like to do next?**" + +### 8. Present MENU OPTIONS + +**[V] Run Validation** - Execute full validation workflow via {validationWorkflow} +**[S] Summary Only** - End with summary of changes (no validation) +**[A] Adjust** - Make additional edits +**[X] Exit** - Exit edit workflow + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input +- Only proceed based on user selection + +#### Menu Handling Logic: + +- IF V (Validate): Display "Starting validation workflow..." then invoke the `gds-validate-gdd` skill +- IF S (Summary): Present edit summary and proceed to {nextStepFile} +- IF A (Adjust): Accept additional requirements, loop back to editing +- IF X (Exit): Display summary and proceed to {nextStepFile} + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- All approved changes from step e-02 applied correctly +- Changes executed in planned priority order +- Restructuring completed (if needed) +- Frontmatter updated accurately +- Final verification confirms changes +- User can proceed to validation or exit with summary +- Option to run validation seamlessly integrates edit and validate modes + +### ❌ SYSTEM FAILURE: + +- Making changes beyond approved plan +- Not following priority order +- Missing restructuring (if conversion mode) +- Not updating frontmatter +- No final verification +- Not saving updated GDD + +**Master Rule:** Execute the plan exactly as approved. The GDD is now ready for validation or downstream use. Validation integration ensures quality. diff --git a/src/workflows/2-design/gds-edit-gdd/steps-e/step-e-04-complete.md b/src/workflows/2-design/gds-edit-gdd/steps-e/step-e-04-complete.md new file mode 100644 index 0000000..65aae48 --- /dev/null +++ b/src/workflows/2-design/gds-edit-gdd/steps-e/step-e-04-complete.md @@ -0,0 +1,172 @@ +--- +name: 'step-e-04-complete' +description: 'Complete & Validate - Present options for next steps including full validation' + +# File references (ONLY variables used in this step) +gddFile: '{gdd_file_path}' +validationWorkflow: 'skill:gds-validate-gdd' +--- + +# Step E-4: Complete & Validate + +## STEP GOAL: + +Present summary of completed edits and offer next steps including seamless integration with the `gds-validate-gdd` validation workflow. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 ALWAYS generate content WITH user input/approval +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and GDD Improvement Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in collaborative dialogue, not command-response +- ✅ You bring synthesis and summary expertise +- ✅ User chooses next actions + +### Step-Specific Rules: + +- 🎯 Focus ONLY on presenting summary and options +- 🚫 FORBIDDEN to make additional changes +- 💬 Approach: Clear, concise summary with actionable options +- 🚪 This is the final edit step - no more edits + +## EXECUTION PROTOCOLS: + +- 🎯 Compile summary of all changes made +- 🎯 Present options clearly with expected outcomes +- 📖 Route to validation if user chooses +- 🚫 FORBIDDEN to proceed without user selection + +## CONTEXT BOUNDARIES: + +- Available context: Updated GDD file, edit history from step e-03 +- Focus: Summary and options only (no more editing) +- Limits: Don't make changes, just present options +- Dependencies: Step e-03 completed - all edits applied + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Compile Edit Summary + +From step e-03 change execution, compile: + +**Changes Made:** + +- Sections added: {list with names} +- Sections updated: {list with names} +- Content removed: {list - especially engine/implementation cleanup} +- Structure changes: {description} + +**Edit Details:** + +- Total sections affected: {count} +- Mode: {restructure/targeted/both} +- Priority addressed: {Critical/High/Medium/Low} + +**GDD Status:** + +- Format: {Canonical GDS Schema / GDS Variant / Legacy (converted)} +- Completeness: {assessment} +- Ready for: {downstream use cases} + +### 2. Present Completion Summary + +Display: + +"**✓ GDD Edit Complete** + +**Updated GDD:** {gdd_file_path} + +**Changes Summary:** +{Present bulleted list of major changes} + +**Edit Mode:** {mode} +**Sections Modified:** {count} + +**GDD Format:** {format} + +**GDD is now ready for:** + +- Downstream GDS workflows (architecture, epics, production, playtesting) +- Validation to ensure quality +- Team review and production use + +**What would you like to do next?**" + +### 3. Present MENU OPTIONS + +Display: + +**[V] Run Full Validation** - Execute complete validation workflow via {validationWorkflow} to verify GDD quality +**[E] Edit More** - Make additional edits to the GDD +**[S] Summary** - End with detailed summary of changes +**[X] Exit** - Exit edit workflow + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input +- Only proceed based on user selection + +#### Menu Handling Logic: + +- **IF V (Run Full Validation):** + - Display: "**Starting Validation Workflow**" + - Display: "This will run all 13 validation checks on the updated GDD." + - Display: "Preparing to validate: {gdd_file_path}" + - Display: "**Proceeding to validation...**" + - Invoke the `gds-validate-gdd` skill — it will run its complete 13-step validation process on the updated GDD + +- **IF E (Edit More):** + - Display: "**Additional Edits**" + - Ask: "What additional edits would you like to make?" + - Accept input, then display: "**Returning to edit step...**" + - Read fully and follow: step-e-03-edit.md again + +- **IF S (Summary):** + - Display detailed summary including: + - Complete list of all changes made + - Before/after comparison (key improvements) + - Recommendations for next steps + - Display: "**Edit Workflow Complete**" + - Exit + +- **IF X (Exit):** + - Display summary + - Display: "**Edit Workflow Complete**" + - Exit + +- **IF Any other:** Help user, then redisplay menu + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- Complete edit summary compiled accurately +- All changes clearly documented +- Options presented with clear expectations +- Validation option seamlessly hands off to `gds-validate-gdd` +- User can validate, edit more, or exit +- Clean handoff to validation workflow (if chosen) +- Edit workflow completes properly + +### ❌ SYSTEM FAILURE: + +- Missing changes in summary +- Not offering validation option +- Not documenting completion properly +- No clear handoff to validation workflow + +**Master Rule:** The edit workflow seamlessly integrates with validation. User can edit → validate → edit again → validate again in an iterative improvement cycle. diff --git a/src/workflows/2-design/gds-edit-gdd/workflow.md b/src/workflows/2-design/gds-edit-gdd/workflow.md new file mode 100644 index 0000000..d320514 --- /dev/null +++ b/src/workflows/2-design/gds-edit-gdd/workflow.md @@ -0,0 +1,65 @@ +--- +name: gds-edit-gdd +description: 'Edit an existing GDD. Use when the user says "edit this GDD" or "improve this GDD".' +main_config: '{module_config}' +editWorkflow: './steps-e/step-e-01-discovery.md' +--- + +# GDD Edit Workflow + +**Goal:** Edit and improve existing Game Design Documents through a structured enhancement workflow. + +**Your Role:** GDD improvement specialist. + +You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description. + +## WORKFLOW ARCHITECTURE + +This uses **step-file architecture** for disciplined execution: + +### Core Principles + +- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly +- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so +- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed +- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document +- **Append-Only Building**: Build documents by appending content as directed to the output file + +### Step Processing Rules + +1. **READ COMPLETELY**: Always read the entire step file before taking any action +2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate +3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection +4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue) +5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step +6. **LOAD NEXT**: When directed, read fully and follow the next step file + +### Critical Rules (NO EXCEPTIONS) + +- 🛑 **NEVER** load multiple step files simultaneously +- 📖 **ALWAYS** read entire step file before execution +- 🚫 **NEVER** skip steps or optimize the sequence +- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step +- 🎯 **ALWAYS** follow the exact instructions in the step file +- ⏸️ **ALWAYS** halt at menus and wait for user input +- 📋 **NEVER** create mental todo lists from future steps + +## INITIALIZATION SEQUENCE + +### 1. Configuration Loading + +Load and read full config from {main_config} and resolve: + +- `project_name`, `output_folder`, `planning_artifacts`, `user_name` +- `communication_language`, `document_output_language`, `game_dev_experience` +- `date` as system-generated current datetime + +✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`. + +### 2. Route to Edit Workflow + +"**Edit Mode: Improving an existing GDD.**" + +Prompt for GDD path: "Which GDD would you like to edit? Please provide the path to the GDD file (default: `{planning_artifacts}/gdd.md`)." + +Then read fully and follow: `{editWorkflow}` (steps-e/step-e-01-discovery.md) diff --git a/src/workflows/2-design/gds-edit-prd/SKILL.md b/src/workflows/2-design/gds-edit-prd/SKILL.md new file mode 100644 index 0000000..5ad9148 --- /dev/null +++ b/src/workflows/2-design/gds-edit-prd/SKILL.md @@ -0,0 +1,6 @@ +--- +name: gds-edit-prd +description: 'Edit an existing PRD. Use when the user says "edit this PRD" or "improve this PRD".' +--- + +Follow the instructions in ./workflow.md. diff --git a/src/workflows/2-design/gds-edit-prd/bmad-skill-manifest.yaml b/src/workflows/2-design/gds-edit-prd/bmad-skill-manifest.yaml new file mode 100644 index 0000000..d0f08ab --- /dev/null +++ b/src/workflows/2-design/gds-edit-prd/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/workflows/2-design/gds-edit-prd/data/prd-purpose.md b/src/workflows/2-design/gds-edit-prd/data/prd-purpose.md new file mode 100644 index 0000000..d8b334b --- /dev/null +++ b/src/workflows/2-design/gds-edit-prd/data/prd-purpose.md @@ -0,0 +1,197 @@ +# BMAD PRD Purpose + +**The PRD is the top of the required funnel that feeds all subsequent product development work in the BMad Method.** + +--- + +## What is a BMAD PRD? + +A dual-audience document serving: +1. **Human Product Managers and builders** - Vision, strategy, stakeholder communication +2. **LLM Downstream Consumption** - UX Design → Architecture → Epics → Development AI Agents + +Each successive document becomes more AI-tailored and granular. + +--- + +## Core Philosophy: Information Density + +**High Signal-to-Noise Ratio** + +Every sentence must carry information weight. LLMs consume precise, dense content efficiently. + +**Anti-Patterns (Eliminate These):** +- ❌ "The system will allow users to..." → ✅ "Users can..." +- ❌ "It is important to note that..." → ✅ State the fact directly +- ❌ "In order to..." → ✅ "To..." +- ❌ Conversational filler and padding → ✅ Direct, concise statements + +**Goal:** Maximum information per word. Zero fluff. + +--- + +## The Traceability Chain + +**PRD starts the chain:** +``` +Vision → Success Criteria → User Journeys → Functional Requirements → (future: User Stories) +``` + +**In the PRD, establish:** +- Vision → Success Criteria alignment +- Success Criteria → User Journey coverage +- User Journey → Functional Requirement mapping +- All requirements traceable to user needs + +**Why:** Each downstream artifact (UX, Architecture, Epics, Stories) must trace back to documented user needs and business objectives. This chain ensures we build the right thing. + +--- + +## What Makes Great Functional Requirements? + +### FRs are Capabilities, Not Implementation + +**Good FR:** "Users can reset their password via email link" +**Bad FR:** "System sends JWT via email and validates with database" (implementation leakage) + +**Good FR:** "Dashboard loads in under 2 seconds for 95th percentile" +**Bad FR:** "Fast loading time" (subjective, unmeasurable) + +### SMART Quality Criteria + +**Specific:** Clear, precisely defined capability +**Measurable:** Quantifiable with test criteria +**Attainable:** Realistic within constraints +**Relevant:** Aligns with business objectives +**Traceable:** Links to source (executive summary or user journey) + +### FR Anti-Patterns + +**Subjective Adjectives:** +- ❌ "easy to use", "intuitive", "user-friendly", "fast", "responsive" +- ✅ Use metrics: "completes task in under 3 clicks", "loads in under 2 seconds" + +**Implementation Leakage:** +- ❌ Technology names, specific libraries, implementation details +- ✅ Focus on capability and measurable outcomes + +**Vague Quantifiers:** +- ❌ "multiple users", "several options", "various formats" +- ✅ "up to 100 concurrent users", "3-5 options", "PDF, DOCX, TXT formats" + +**Missing Test Criteria:** +- ❌ "The system shall provide notifications" +- ✅ "The system shall send email notifications within 30 seconds of trigger event" + +--- + +## What Makes Great Non-Functional Requirements? + +### NFRs Must Be Measurable + +**Template:** +``` +"The system shall [metric] [condition] [measurement method]" +``` + +**Examples:** +- ✅ "The system shall respond to API requests in under 200ms for 95th percentile as measured by APM monitoring" +- ✅ "The system shall maintain 99.9% uptime during business hours as measured by cloud provider SLA" +- ✅ "The system shall support 10,000 concurrent users as measured by load testing" + +### NFR Anti-Patterns + +**Unmeasurable Claims:** +- ❌ "The system shall be scalable" → ✅ "The system shall handle 10x load growth through horizontal scaling" +- ❌ "High availability required" → ✅ "99.9% uptime as measured by cloud provider SLA" + +**Missing Context:** +- ❌ "Response time under 1 second" → ✅ "API response time under 1 second for 95th percentile under normal load" + +--- + +## Domain-Specific Requirements + +**Auto-Detect and Enforce Based on Project Context** + +Certain industries have mandatory requirements that must be present: + +- **Healthcare:** HIPAA Privacy & Security Rules, PHI encryption, audit logging, MFA +- **Fintech:** PCI-DSS Level 1, AML/KYC compliance, SOX controls, financial audit trails +- **GovTech:** NIST framework, Section 508 accessibility (WCAG 2.1 AA), FedRAMP, data residency +- **E-Commerce:** PCI-DSS for payments, inventory accuracy, tax calculation by jurisdiction + +**Why:** Missing these requirements in the PRD means they'll be missed in architecture and implementation, creating expensive rework. During PRD creation there is a step to cover this - during validation we want to make sure it was covered. For this purpose steps will utilize a domain-complexity.csv and project-types.csv. + +--- + +## Document Structure (Markdown, Human-Readable) + +### Required Sections +1. **Executive Summary** - Vision, differentiator, target users +2. **Success Criteria** - Measurable outcomes (SMART) +3. **Product Scope** - MVP, Growth, Vision phases +4. **User Journeys** - Comprehensive coverage +5. **Domain Requirements** - Industry-specific compliance (if applicable) +6. **Innovation Analysis** - Competitive differentiation (if applicable) +7. **Project-Type Requirements** - Platform-specific needs +8. **Functional Requirements** - Capability contract (FRs) +9. **Non-Functional Requirements** - Quality attributes (NFRs) + +### Formatting for Dual Consumption + +**For Humans:** +- Clear, professional language +- Logical flow from vision to requirements +- Easy for stakeholders to review and approve + +**For LLMs:** +- ## Level 2 headers for all main sections (enables extraction) +- Consistent structure and patterns +- Precise, testable language +- High information density + +--- + +## Downstream Impact + +**How the PRD Feeds Next Artifacts:** + +**UX Design:** +- User journeys → interaction flows +- FRs → design requirements +- Success criteria → UX metrics + +**Architecture:** +- FRs → system capabilities +- NFRs → architecture decisions +- Domain requirements → compliance architecture +- Project-type requirements → platform choices + +**Epics & Stories (created after architecture):** +- FRs → user stories (1 FR could map to 1-3 stories potentially) +- Acceptance criteria → story acceptance tests +- Priority → sprint sequencing +- Traceability → stories map back to vision + +**Development AI Agents:** +- Precise requirements → implementation clarity +- Test criteria → automated test generation +- Domain requirements → compliance enforcement +- Measurable NFRs → performance targets + +--- + +## Summary: What Makes a Great BMAD PRD? + +✅ **High Information Density** - Every sentence carries weight, zero fluff +✅ **Measurable Requirements** - All FRs and NFRs are testable with specific criteria +✅ **Clear Traceability** - Each requirement links to user need and business objective +✅ **Domain Awareness** - Industry-specific requirements auto-detected and included +✅ **Zero Anti-Patterns** - No subjective adjectives, implementation leakage, or vague quantifiers +✅ **Dual Audience Optimized** - Human-readable AND LLM-consumable +✅ **Markdown Format** - Professional, clean, accessible to all stakeholders + +--- + +**Remember:** The PRD is the foundation. Quality here ripples through every subsequent phase. A dense, precise, well-traced PRD makes UX design, architecture, epic breakdown, and AI development dramatically more effective. diff --git a/src/workflows/2-design/create-prd/steps-e/step-e-01-discovery.md b/src/workflows/2-design/gds-edit-prd/steps-e/step-e-01-discovery.md similarity index 98% rename from src/workflows/2-design/create-prd/steps-e/step-e-01-discovery.md rename to src/workflows/2-design/gds-edit-prd/steps-e/step-e-01-discovery.md index 36c0300..315be88 100644 --- a/src/workflows/2-design/create-prd/steps-e/step-e-01-discovery.md +++ b/src/workflows/2-design/gds-edit-prd/steps-e/step-e-01-discovery.md @@ -24,6 +24,7 @@ Understand what the user wants to edit in the PRD, detect PRD format/type, check - 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read - 📋 YOU ARE A FACILITATOR, not a content generator - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` ### Role Reinforcement: diff --git a/src/workflows/2-design/create-prd/steps-e/step-e-01b-legacy-conversion.md b/src/workflows/2-design/gds-edit-prd/steps-e/step-e-01b-legacy-conversion.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-e/step-e-01b-legacy-conversion.md rename to src/workflows/2-design/gds-edit-prd/steps-e/step-e-01b-legacy-conversion.md diff --git a/src/workflows/2-design/create-prd/steps-e/step-e-02-review.md b/src/workflows/2-design/gds-edit-prd/steps-e/step-e-02-review.md similarity index 98% rename from src/workflows/2-design/create-prd/steps-e/step-e-02-review.md rename to src/workflows/2-design/gds-edit-prd/steps-e/step-e-02-review.md index aeb4b77..306a9e6 100644 --- a/src/workflows/2-design/create-prd/steps-e/step-e-02-review.md +++ b/src/workflows/2-design/gds-edit-prd/steps-e/step-e-02-review.md @@ -25,6 +25,7 @@ Thoroughly review the existing PRD, analyze validation report findings (if provi - 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read - 📋 YOU ARE A FACILITATOR, not a content generator - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` ### Role Reinforcement: diff --git a/src/workflows/2-design/create-prd/steps-e/step-e-03-edit.md b/src/workflows/2-design/gds-edit-prd/steps-e/step-e-03-edit.md similarity index 98% rename from src/workflows/2-design/create-prd/steps-e/step-e-03-edit.md rename to src/workflows/2-design/gds-edit-prd/steps-e/step-e-03-edit.md index a6b16a8..ca980f6 100644 --- a/src/workflows/2-design/create-prd/steps-e/step-e-03-edit.md +++ b/src/workflows/2-design/gds-edit-prd/steps-e/step-e-03-edit.md @@ -23,6 +23,7 @@ Apply changes to the PRD following the approved change plan from step e-02, incl - 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read - 📋 YOU ARE A FACILITATOR, not a content generator - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` ### Role Reinforcement: diff --git a/src/workflows/2-design/create-prd/steps-e/step-e-04-complete.md b/src/workflows/2-design/gds-edit-prd/steps-e/step-e-04-complete.md similarity index 95% rename from src/workflows/2-design/create-prd/steps-e/step-e-04-complete.md rename to src/workflows/2-design/gds-edit-prd/steps-e/step-e-04-complete.md index 5d681fe..1987a7e 100644 --- a/src/workflows/2-design/create-prd/steps-e/step-e-04-complete.md +++ b/src/workflows/2-design/gds-edit-prd/steps-e/step-e-04-complete.md @@ -4,7 +4,7 @@ description: 'Complete & Validate - Present options for next steps including ful # File references (ONLY variables used in this step) prdFile: '{prd_file_path}' -validationWorkflow: '../steps-v/step-v-01-discovery.md' +validationWorkflow: 'skill:gds-validate-prd' --- # Step E-4: Complete & Validate @@ -120,8 +120,7 @@ Display: - Display: "This will run all 13 validation checks on the updated PRD." - Display: "Preparing to validate: {prd_file_path}" - Display: "**Proceeding to validation...**" - - Read fully and follow: {validationWorkflow} (steps-v/step-v-01-discovery.md) - - Note: This hands off to the validation workflow which will run its complete 13-step process + - Invoke the `gds-validate-prd` skill — it will run its complete 13-step validation process on the updated PRD - **IF E (Edit More):** - Display: "**Additional Edits**" diff --git a/src/workflows/2-design/create-prd/workflow-edit-prd.md b/src/workflows/2-design/gds-edit-prd/workflow.md similarity index 99% rename from src/workflows/2-design/create-prd/workflow-edit-prd.md rename to src/workflows/2-design/gds-edit-prd/workflow.md index f397b56..3a4894e 100644 --- a/src/workflows/2-design/create-prd/workflow-edit-prd.md +++ b/src/workflows/2-design/gds-edit-prd/workflow.md @@ -1,5 +1,5 @@ --- -name: edit-prd +name: gds-edit-prd description: 'Edit an existing PRD. Use when the user says "edit this PRD".' main_config: '{module_config}' editWorkflow: './steps-e/step-e-01-discovery.md' diff --git a/src/workflows/2-design/gds-validate-gdd/SKILL.md b/src/workflows/2-design/gds-validate-gdd/SKILL.md new file mode 100644 index 0000000..25b1d40 --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/SKILL.md @@ -0,0 +1,6 @@ +--- +name: gds-validate-gdd +description: 'Validate a GDD against standards. Use when the user says "validate this GDD" or "run GDD validation".' +--- + +Follow the instructions in ./workflow.md. diff --git a/src/workflows/2-design/gds-validate-gdd/bmad-skill-manifest.yaml b/src/workflows/2-design/gds-validate-gdd/bmad-skill-manifest.yaml new file mode 100644 index 0000000..d0f08ab --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/workflows/2-design/gds-validate-gdd/data/gdd-purpose.md b/src/workflows/2-design/gds-validate-gdd/data/gdd-purpose.md new file mode 100644 index 0000000..d4a374f --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/data/gdd-purpose.md @@ -0,0 +1,224 @@ +# BMAD GDD Purpose + +**The GDD is the primary planning artifact in the Game Dev Studio (GDS) module. It feeds every downstream phase: architecture, epics, production, and playtesting.** + +In GDS, the PRD is optional and exists only for external-tool compatibility. The GDD is the canonical source of truth for game design intent. + +--- + +## What is a BMAD GDD? + +A dual-audience document serving: + +1. **Human game designers, producers, and developers** - Vision, pillars, team alignment, playtest briefs +2. **LLM downstream consumption** - Architecture → Epics → Dev stories → Playtest plans → Game Dev AI Agents + +Each successive artifact becomes more granular and more AI-tailored. The GDD is where the design intent is captured in its purest form, before engine and implementation concerns enter the picture. + +--- + +## Core Philosophy: Information Density + +**High Signal-to-Noise Ratio on Game Mechanics** + +Every sentence must carry design information. LLMs consume precise, dense content efficiently - and game design already suffers from pitch-deck-style fluff. + +**Anti-Patterns (Eliminate These):** + +- ❌ "The player will be able to..." → ✅ "The player can..." +- ❌ "It is our intention to create a game that..." → ✅ State the design directly +- ❌ "Players will experience fun and engaging gameplay" → ✅ Describe the specific mechanic that produces engagement +- ❌ Marketing copy and pitch language → ✅ Concrete mechanics, systems, and numbers + +**Goal:** Maximum design information per word. Zero fluff, zero marketing. + +--- + +## The Traceability Chain + +**GDD starts the chain:** + +``` +Core Fantasy / Vision → Game Pillars → Core Gameplay Loop → Mechanics & Systems → Epics → Stories +``` + +**In the GDD, establish:** + +- Vision → Pillars alignment +- Pillars → Gameplay Loop reinforcement (the loop should embody the pillars) +- Gameplay Loop → Mechanics mapping (each mechanic serves the loop) +- Mechanics → Epics (each epic delivers mechanics) +- All content traceable to the core fantasy + +**Why:** Every downstream artifact (architecture, epics, stories, playtest plans) must trace back to documented design intent. This chain is what prevents scope creep, feature bloat, and mechanics that exist for their own sake. + +--- + +## What Makes Great Mechanics and Systems? + +### Mechanics are Player-Facing Capabilities, Not Implementation + +**Good:** "The player can dash in any of 8 directions, consuming 1 stamina pip. Stamina regenerates at 1 pip/second while grounded." +**Bad:** "We use a Rigidbody2D with AddForce and a cooldown coroutine" (engine leakage - belongs in architecture) + +**Good:** "Frame-perfect parries reward a 1.5x damage multiplier for 3 seconds." +**Bad:** "Combat feels responsive and satisfying" (subjective, unmeasurable) + +### SMART Quality Criteria (Adapted for Game Design) + +**Specific:** Clear, precisely defined mechanic or system +**Measurable:** Quantifiable values (timings, damages, costs, ranges) +**Attainable:** Realistic within target platform, team, and timeline +**Relevant:** Reinforces a game pillar or the core loop +**Traceable:** Links to the vision, a pillar, or a specific player fantasy + +### Mechanics Anti-Patterns + +**Subjective Adjectives:** + +- ❌ "fun", "satisfying", "immersive", "responsive", "deep" +- ✅ Use concrete values: "chain combos extend the hit window by 6 frames per successful hit" + +**Engine / Implementation Leakage:** + +- ❌ Engine APIs, node names, specific shaders, class hierarchies +- ✅ Focus on player experience and system behavior - the engine is architecture's problem + +**Vague Quantifiers:** + +- ❌ "many enemies", "several weapons", "various environments" +- ✅ "12 enemy archetypes", "6 primary weapons + 18 unlockable variants", "3 biomes × 4 sub-zones" + +**Missing Feel Criteria:** + +- ❌ "The jump feels good" +- ✅ "Jump height: 3 tiles. Air time: 0.55s. Coyote time: 6 frames. Buffer window: 8 frames." + +--- + +## What Makes Great Technical Constraints? + +### Target Specs Must Be Measurable + +**Template:** + +``` +"The game shall [metric] [platform/condition] [measurement method]" +``` + +**Examples:** + +- ✅ "Maintain 60 FPS sustained on Steam Deck at 720p Medium settings, as measured by in-engine profiler over a 10-minute combat loop" +- ✅ "First-playable load time under 15s on PS5 from cold boot" +- ✅ "Memory budget: 4GB on PS4, 6GB on PS5, as measured by PIX capture" + +### Constraint Anti-Patterns + +**Unmeasurable Claims:** + +- ❌ "Runs well on all platforms" → ✅ "60 FPS on PS5/XSX, 30 FPS on PS4/XB1" +- ❌ "Fast load times" → ✅ "Sub-5-second level transitions on target hardware" + +**Missing Context:** + +- ❌ "60 FPS target" → ✅ "60 FPS during combat encounters with up to 6 enemies on-screen, measured on Steam Deck" + +--- + +## Genre-Specific Requirements + +**Auto-Detect and Enforce Based on Game Type** + +Certain genres carry conventions that must be documented: + +- **Action/Platformer:** Precise movement values (jump arc, coyote time, input buffer), hit/hurt box conventions, damage formulae +- **RPG:** Stat system, leveling curve, inventory rules, quest state machine, save/load boundaries +- **Roguelike:** Run structure, meta-progression rules, seed determinism, balance bands +- **Multiplayer (MOBA/Shooter):** Netcode model (lockstep/rollback/client-predict), tick rate, lag tolerance, matchmaking +- **Puzzle:** Solution space guarantees, hint systems, difficulty ramp +- **Narrative/Visual Novel:** Branching structure, variable/flag system, rewind/save model + +**Why:** Missing genre conventions in the GDD means they surface as emergencies during production. Validation should catch these up front. Steps use a `genre-complexity.csv` data file to drive genre-specific expectations. + +--- + +## Document Structure (Markdown, Human-Readable) + +### Required Sections (canonical gds-create-gdd schema) + +1. **Executive Summary** - Core concept, target audience, USPs +2. **Goals and Context** - Project goals, background, rationale +3. **Core Gameplay** - Pillars, core gameplay loop, win/loss conditions +4. **Game Mechanics** - Primary mechanics, controls and input +5. **Game-Type Specific Sections** - Genre-driven sections (e.g., RPG stats, roguelike run structure) +6. **Progression and Balance** - Player progression, difficulty curve, economy +7. **Level Design Framework** - Level types, progression +8. **Art and Audio Direction** - Visual style, audio approach +9. **Technical Specifications** - Performance targets, platform specs, asset budget +10. **Development Epics** - High-level delivery breakdown +11. **Success Metrics** - Technical and gameplay success criteria +12. **Out of Scope** - Explicit scope boundaries +13. **Assumptions and Dependencies** - External risks + +### Formatting for Dual Consumption + +**For Humans:** + +- Clear, direct language - no pitch-deck bloat +- Logical flow from vision to execution +- Easy for producers, leads, and external collaborators to review + +**For LLMs:** + +- `##` Level 2 headers for all main sections (enables extraction) +- Consistent structure and patterns +- Concrete numbers wherever possible +- High information density + +--- + +## Downstream Impact + +**How the GDD Feeds Next Artifacts:** + +**Architecture:** + +- Mechanics → system design (physics, AI, state machines) +- Technical specs → engine choice, rendering pipeline, memory layout +- Genre conventions → framework decisions (netcode model, save system) + +**Epics & Stories:** + +- Mechanics → epics (1 mechanic often = 1 epic) +- Level framework → content stories +- Progression → systems stories +- Traceability → stories map back to pillars + +**Playtesting / Gametest:** + +- Pillars → playtest focus areas +- Success metrics → playtest success criteria +- Core loop → the thing we're actually testing + +**Development AI Agents:** + +- Precise mechanics → implementation clarity +- Measurable specs → automated performance gates +- Genre conventions → framework selection +- Success metrics → telemetry targets + +--- + +## Summary: What Makes a Great BMAD GDD? + +✅ **High Information Density** - Every sentence carries design weight, zero pitch-deck fluff +✅ **Measurable Mechanics** - Concrete numbers for timings, damages, costs, ranges +✅ **Clear Traceability** - Each mechanic links to a pillar or core loop, each pillar to the vision +✅ **Genre Awareness** - Genre-specific sections auto-detected and included +✅ **Zero Anti-Patterns** - No subjective adjectives, no engine leakage, no vague quantifiers +✅ **Dual Audience Optimized** - Human-readable AND LLM-consumable +✅ **Markdown Format** - Professional, clean, accessible to designers and AI tools alike + +--- + +**Remember:** The GDD is the foundation of GDS. Quality here ripples through architecture, epics, stories, and playtesting. A dense, precise, well-traced GDD makes every downstream phase dramatically more effective - and prevents the "we never actually decided what this game is" spiral that kills projects. diff --git a/src/workflows/2-design/gds-validate-gdd/data/genre-complexity.csv b/src/workflows/2-design/gds-validate-gdd/data/genre-complexity.csv new file mode 100644 index 0000000..7b19feb --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/data/genre-complexity.csv @@ -0,0 +1,26 @@ +genre,signals,complexity,key_concerns,required_knowledge,suggested_workflow,special_sections +action-platformer,"platformer,jump,dash,combat,precision,side-scroller,movement",high,"Frame-perfect feel values;Hit/hurt box conventions;Coyote time and input buffers;Checkpoint cadence;Level flow and gating","Platformer movement feel;Hitbox design;Level pacing;Difficulty curve via geometry","genre-research","movement_feel_table;combat_specs;level_gating;difficulty_curve" +rpg,"rpg,stats,inventory,quests,leveling,party,dialogue,skills",high,"Stat system coherence;Leveling curve;Inventory rules;Quest state machine;Save/load scope;Dialogue variables","Stat design and balancing;Economy and loot tables;Quest scripting patterns;Save-state boundaries;Branching narrative","genre-research","stat_system;leveling_curve;inventory_rules;quest_state_machine;save_model" +roguelike,"roguelike,procedural,permadeath,runs,seeded,meta-progression",high,"Run structure;Seed determinism;Meta vs in-run progression;Balance bands across runs;Player retention hooks","Procedural generation patterns;Meta-progression design;Seed management;Per-run difficulty scaling","genre-research","run_structure;meta_progression;seed_determinism;balance_bands" +shooter,"shooter,fps,tps,aim,projectile,recoil,weapons,gunplay",high,"Weapon feel (TTK, recoil, spread);Netcode (if multiplayer);Hitreg model;Map flow and choke points;Spawn logic","Gunplay tuning;Netcode model selection;Hitreg design;Map readability;Spawn algorithms","genre-research","weapon_feel_table;netcode_model;hitreg_spec;map_flow" +moba,"moba,lanes,heroes,champions,team,jungle,ranked,pvp",high,"Hero kit diversity;Lane/map balance;Matchmaking and MMR;Tick rate and latency tolerance;Role identity","MOBA kit design;Map/lane pacing;Matchmaking systems;Anti-toxicity tooling;Esports readiness","genre-research","hero_kit_matrix;map_pacing;matchmaking_model;tick_rate_spec" +fighting,"fighting,combos,frame data,neutral,counter,competitive,1v1",high,"Frame data accuracy;Rollback netcode;Input parsing;Combo system boundaries;Training mode completeness","Frame data theory;Rollback netcode;Input buffer design;Competitive balance","genre-research","frame_data_tables;netcode_model;input_spec;training_mode" +survival,"survival,crafting,hunger,thirst,resources,base-building,danger",high,"Resource scarcity curves;Day/night or seasonal cycles;Base persistence;Hostile threat pacing;Multi-session continuity","Crafting tree design;Resource economy;Threat AI pacing;Persistence model","genre-research","resource_economy;crafting_tree;threat_pacing;persistence_model" +simulation,"simulation,management,tycoon,systems,building,sandbox",high,"System interaction clarity;Long-tail balance;Emergent behavior handling;Save-scum mitigation;End-state definition","Systems design and interaction;Balance for long sessions;Emergent gameplay;End-state or open-endedness","genre-research","systems_map;balance_long_tail;emergence_boundaries;end_state" +strategy,"strategy,rts,4x,turn-based,tactics,resources,units",medium,"Unit role clarity;Economy tempo;Map-based balance;AI design;Turn/tick pacing","Unit design and counters;Economy curves;Strategic AI;Pacing","genre-research","unit_matrix;economy_tempo;ai_design;pacing_model" +horror,"horror,tension,atmosphere,fear,scare,jumpscare,psychological",medium,"Atmosphere and audio design;Scare pacing (not spam);Resource scarcity;Save-point pressure;Narrative framing","Horror pacing;Audio/atmosphere design;Tension escalation;Narrative framing","genre-research","atmosphere_design;scare_pacing;resource_scarcity;save_model" +metroidvania,"metroidvania,exploration,abilities,interconnected,gating,backtracking",medium,"Ability-based gating graph;Map readability;Backtracking pacing;Upgrade pacing;Softlock prevention","Gating graphs;Map design;Upgrade pacing;Softlock analysis","genre-research","gating_graph;map_design;upgrade_pacing;softlock_prevention" +adventure,"adventure,story,narrative,exploration,puzzle,point-and-click",medium,"Narrative branching clarity;Puzzle fairness;Pacing of reveals;Replayability of choices;Inventory/clue tracking","Narrative design;Puzzle design;Pacing;Choice architecture","genre-research","narrative_structure;puzzle_fairness;pacing;choice_architecture" +puzzle,"puzzle,logic,solve,brain,match,pattern",medium,"Solution-space guarantees;Hint system design;Difficulty ramp;Level generation (if procedural);Tutorialization","Puzzle theory;Hint systems;Difficulty curves;Tutorial flow","genre-research","solution_space;hint_system;difficulty_ramp;tutorialization" +racing,"racing,track,vehicle,speed,lap,drift,kart",medium,"Vehicle handling model;Track design language;AI rubber-banding policy;Power-up balance (if any);Multiplayer desync","Vehicle physics;Track design;AI driver design;Netcode","genre-research","vehicle_handling;track_design;ai_driver_model;mp_model" +sports,"sports,team,ball,realism,physics,athlete",medium,"Rule fidelity vs arcade feel;Physics consistency;Season/career mode;Roster data pipelines;Multiplayer integrity","Sport rules modeling;Physics tuning;Career systems;Online integrity","genre-research","rule_model;physics_spec;career_mode;online_integrity" +card-game,"card,deck,hand,draw,ccg,tcg,deckbuilder",medium,"Card-pool balance;Rarity and economy;Draw mechanics;Anti-infinite-loop rules;New-player experience","Card design;Deck construction rules;Economy (for CCGs);Format rotation","genre-research","card_pool_balance;economy_model;draw_rules;nux_flow" +tower-defense,"tower-defense,wave,tower,placement,lane",medium,"Wave pacing;Tower role distinction;Map/path balance;Economy per wave;Endless-mode scaling","Wave design;Tower taxonomy;Economy curves;Endless scaling","genre-research","wave_pacing;tower_matrix;economy_per_wave;endless_scaling" +visual-novel,"visual-novel,choice,branching,dialogue,narrative,ending",medium,"Branching structure;Variable/flag system;Rewind/save model;Route coverage;Localization budget","Branching narrative;Flag systems;Save models;Route design;Localization","genre-research","branching_structure;flag_system;save_model;route_coverage" +rhythm,"rhythm,music,beat,timing,note,chart",medium,"Timing window accuracy;Audio latency calibration;Chart authoring pipeline;Difficulty tiers;Song-licensing or content pipeline","Rhythm game feel;Audio engineering;Chart authoring tools;Difficulty tiering","genre-research","timing_windows;latency_calibration;chart_pipeline;difficulty_tiers" +turn-based-tactics,"tactics,grid,turns,positioning,squad",medium,"Grid rules (pathing, LOS, height);Turn order determination;Action economy;Enemy AI;Mission variety","Tactics grid rules;Action economy;Enemy AI patterns;Mission design","genre-research","grid_rules;action_economy;enemy_ai;mission_variety" +idle-incremental,"idle,incremental,clicker,automation,progression",low,"Progression pacing;Reset/prestige mechanics;Offline gains;Long-session balance;Content runway","Progression curves;Prestige design;Offline economy;Monetization (if applicable)","genre-research","progression_pacing;prestige_model;offline_gains" +sandbox,"sandbox,build,create,freedom,minimal goals",low,"Creative tool depth;Performance at scale;Saving/sharing user content;Optional goals;UGC moderation","Creative tools;Performance at scale;UGC pipelines;Moderation","genre-research","creative_tools;perf_at_scale;ugc_pipeline" +party-game,"party,minigame,local-multiplayer,casual",low,"Minigame variety;Controller/ input sharing;Round pacing;Accessibility;Drop-in/drop-out","Minigame design;Local MP patterns;Pacing;Accessibility","genre-research","minigame_roster;local_mp_model;round_pacing" +text-based,"text,parser,interactive-fiction,mud",low,"Parser coverage vs choice-based;World state tracking;Save model;Readability on target devices","Parser design or choice architecture;World state;Save models","genre-research","parser_or_choice;world_state;save_model" +general,"",low,"Standard gameplay concerns;Basic pacing;Target-platform feel","General game design practices","continue","standard_sections" diff --git a/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-01-discovery.md b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-01-discovery.md new file mode 100644 index 0000000..d2d5159 --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-01-discovery.md @@ -0,0 +1,239 @@ +--- +name: 'step-v-01-discovery' +description: 'Document Discovery & Confirmation - Handle fresh-context validation, confirm GDD path, discover input documents' + +# File references (ONLY variables used in this step) +nextStepFile: './step-v-02-format-detection.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: 'skill:bmad-party-mode' +gddPurpose: '../data/gdd-purpose.md' +--- + +# Step V-1: Document Discovery & Confirmation + +## STEP GOAL: + +Handle fresh-context validation by confirming the GDD path, discovering and loading input documents from frontmatter, and initializing the validation report. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and Quality Assurance Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in collaborative dialogue, not command-response +- ✅ You bring systematic validation expertise and analytical rigor +- ✅ User brings game design knowledge and specific GDD context + +### Step-Specific Rules: + +- 🎯 Focus ONLY on discovering the GDD and input documents, not validating yet +- 🚫 FORBIDDEN to perform any validation checks in this step +- 💬 Approach: Systematic discovery with clear reporting to user +- 🚪 This is the setup step - get everything ready for validation + +## EXECUTION PROTOCOLS: + +- 🎯 Discover and confirm GDD to validate +- 💾 Load GDD and all input documents from frontmatter +- 📖 Initialize validation report next to GDD +- 🚫 FORBIDDEN to load next step until user confirms setup + +## CONTEXT BOUNDARIES: + +- Available context: GDD path (user-specified or discovered), workflow configuration +- Focus: Document discovery and setup only +- Limits: Don't perform validation, don't skip discovery +- Dependencies: Configuration loaded from GDD workflow.md initialization + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Load GDD Purpose and Standards + +Load and read the complete file at: +`{gddPurpose}` + +This file contains the BMAD GDD philosophy, standards, and validation criteria that will guide all validation checks. Internalize this understanding - it defines what makes a great BMAD GDD. + +### 2. Discover GDD to Validate + +**If GDD path provided as invocation parameter:** + +- Use provided path + +**If no GDD path provided, auto-discover:** + +- Search `{planning_artifacts}` for files matching `*gdd*.md` +- Prefer the canonical location `{planning_artifacts}/gdd.md` +- Also check for sharded GDDs: `{planning_artifacts}/*gdd*/*.md` + +**If exactly ONE GDD found:** + +- Use it automatically +- Inform user: "Found GDD: {discovered_path} — using it for validation." + +**If MULTIPLE GDDs found:** + +- List all discovered GDDs with numbered options +- "I found multiple GDDs. Which one would you like to validate?" +- Wait for user selection + +**If NO GDDs found:** + +- "I couldn't find any GDD files in {planning_artifacts}. Please provide the path to the GDD file you want to validate." +- Wait for user to provide GDD path. + +### 3. Validate GDD Exists and Load + +Once GDD path is provided: + +- Check if GDD file exists at specified path +- If not found: "I cannot find a GDD at that path. Please check the path and try again." +- If found: Load the complete GDD file including frontmatter + +### 4. Extract Frontmatter and Input Documents + +From the loaded GDD frontmatter, extract: + +- `inputDocuments: []` array (if present) +- Any other relevant metadata (classification.gameType, classification.platforms, date, etc.) + +**If no inputDocuments array exists:** +Note this and proceed with GDD-only validation + +### 5. Load Input Documents + +For each document listed in `inputDocuments`: + +- Attempt to load the document +- Track successfully loaded documents +- Note any documents that fail to load + +**Build list of loaded input documents:** + +- Game Brief (if present) - typically from `gds-create-game-brief` +- Research documents (if present) +- Competitive analysis (if present) +- Other reference materials + +### 6. Ask About Additional Reference Documents + +"**I've loaded the following documents from your GDD frontmatter:** + +{list loaded documents with file names} + +**Are there any additional reference documents you'd like me to include in this validation?** + +These could include: + +- Additional research or context documents +- Competitive analysis or genre references +- Prototype notes or playtest findings +- Art or audio direction documents + +Please provide paths to any additional documents, or type 'none' to proceed." + +**Load any additional documents provided by user.** + +### 7. Initialize Validation Report + +Create validation report at: `{validationReportPath}` + +**Initialize with frontmatter:** + +```yaml +--- +validationTarget: '{gdd_path}' +validationDate: '{current_date}' +inputDocuments: [list of all loaded documents] +validationStepsCompleted: [] +validationStatus: IN_PROGRESS +--- +``` + +**Initial content:** + +```markdown +# GDD Validation Report + +**GDD Being Validated:** {gdd_path} +**Validation Date:** {current_date} + +## Input Documents + +{list all documents loaded for validation} + +## Validation Findings + +[Findings will be appended as validation progresses] +``` + +### 8. Present Discovery Summary + +"**Setup Complete!** + +**GDD to Validate:** {gdd_path} + +**Input Documents Loaded:** + +- GDD: {gdd_name} ✓ +- Game Brief: {count} {if count > 0}✓{else}(none found){/if} +- Research: {count} {if count > 0}✓{else}(none found){/if} +- Additional References: {count} {if count > 0}✓{else}(none){/if} + +**Validation Report:** {validationReportPath} + +**Ready to begin validation.**" + +### 9. Present MENU OPTIONS + +Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Format Detection + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- User can ask questions or add more documents - always respond and redisplay menu + +#### Menu Handling Logic: + +- IF A: Read fully and follow: {advancedElicitationTask}, and when finished redisplay the menu +- IF P: Read fully and follow: {partyModeWorkflow}, and when finished redisplay the menu +- IF C: Read fully and follow: {nextStepFile} to begin format detection +- IF user provides additional document: Load it, update report, redisplay summary +- IF Any other: help user, then redisplay menu + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- GDD path discovered and confirmed +- GDD file exists and loads successfully +- All input documents from frontmatter loaded +- Additional reference documents (if any) loaded +- Validation report initialized next to GDD +- User clearly informed of setup status +- Menu presented and user input handled correctly + +### ❌ SYSTEM FAILURE: + +- Proceeding with non-existent GDD file +- Not loading input documents from frontmatter +- Creating validation report in wrong location +- Proceeding without user confirming setup +- Not handling missing input documents gracefully + +**Master Rule:** Complete discovery and setup BEFORE validation. This step ensures everything is in place for systematic validation checks. diff --git a/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-02-format-detection.md b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-02-format-detection.md new file mode 100644 index 0000000..c521680 --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-02-format-detection.md @@ -0,0 +1,202 @@ +--- +name: 'step-v-02-format-detection' +description: 'Format Detection & Structure Analysis - Classify GDD format and route appropriately' + +# File references (ONLY variables used in this step) +nextStepFile: './step-v-03-density-validation.md' +altStepFile: './step-v-02b-parity-check.md' +gddFile: '{gdd_file_path}' +validationReportPath: '{validation_report_path}' +--- + +# Step V-2: Format Detection & Structure Analysis + +## STEP GOAL: + +Detect if the GDD follows the canonical gds-create-gdd schema and route appropriately - classify as Canonical GDS / GDS Variant / Non-Standard, with optional parity check for non-standard formats. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and Quality Assurance Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in collaborative dialogue, not command-response +- ✅ You bring systematic validation expertise and pattern recognition +- ✅ User brings game design knowledge and GDD context + +### Step-Specific Rules: + +- 🎯 Focus ONLY on detecting format and classifying structure +- 🚫 FORBIDDEN to perform other validation checks in this step +- 💬 Approach: Analytical and systematic, clear reporting of findings +- 🚪 This is a branch step - may route to parity check for non-standard GDDs + +## EXECUTION PROTOCOLS: + +- 🎯 Analyze GDD structure systematically +- 💾 Append format findings to validation report +- 📖 Route appropriately based on format classification +- 🚫 FORBIDDEN to skip format detection or proceed without classification + +## CONTEXT BOUNDARIES: + +- Available context: GDD file loaded in step 1, validation report initialized +- Focus: Format detection and classification only +- Limits: Don't perform other validation, don't skip classification +- Dependencies: Step 1 completed - GDD loaded and report initialized + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Extract GDD Structure + +Load the complete GDD file and extract: + +**All Level 2 (##) headers:** + +- Scan through entire GDD document +- Extract all `##` section headers +- List them in order + +**GDD frontmatter:** + +- Extract `classification.gameType` if present +- Extract `classification.platforms` if present +- Extract `classification.genreComplexity` if present +- Note any other relevant metadata + +### 2. Check for Canonical GDS Core Sections + +Check if the GDD contains the following canonical gds-create-gdd core sections: + +1. **Executive Summary** (or variations: ## Executive Summary, ## Overview, ## Core Concept) +2. **Goals and Context** (or: ## Goals, ## Project Goals, ## Context) +3. **Core Gameplay** (or: ## Core Gameplay, ## Gameplay Loop, ## Game Pillars) +4. **Game Mechanics** (or: ## Game Mechanics, ## Mechanics, ## Systems) +5. **Progression and Balance** (or: ## Progression, ## Balance, ## Difficulty) +6. **Technical Specifications** (or: ## Technical Specs, ## Technical Requirements, ## Performance) +7. **Development Epics** (or: ## Epics, ## Epic Structure, ## Development Plan) + +**Count matches:** + +- How many of these 7 core sections are present? +- Which specific sections are present? +- Which are missing? + +### 3. Classify GDD Format + +Based on core section count, classify: + +**Canonical GDS Schema:** + +- 6-7 core sections present +- Follows gds-create-gdd structure closely + +**GDS Variant:** + +- 4-5 core sections present +- Generally follows canonical patterns but has structural differences +- Missing some sections but recognizable as a BMAD GDS-style GDD + +**Non-Standard:** + +- Fewer than 4 core sections present +- Does not follow canonical GDS structure +- May be a completely custom format, legacy GDD template, or from another framework/tool + +### 4. Report Format Findings to Validation Report + +Append to validation report: + +```markdown +## Format Detection + +**GDD Structure:** +[List all ## Level 2 headers found] + +**Canonical GDS Core Sections Present:** + +- Executive Summary: [Present/Missing] +- Goals and Context: [Present/Missing] +- Core Gameplay: [Present/Missing] +- Game Mechanics: [Present/Missing] +- Progression and Balance: [Present/Missing] +- Technical Specifications: [Present/Missing] +- Development Epics: [Present/Missing] + +**Format Classification:** [Canonical GDS / GDS Variant / Non-Standard] +**Core Sections Present:** [count]/7 +``` + +### 5. Route Based on Format Classification + +**IF format is Canonical GDS or GDS Variant:** + +Display: "**Format Detected:** {classification} + +Proceeding to systematic validation checks..." + +Without delay, read fully and follow: {nextStepFile} (step-v-03-density-validation.md) + +**IF format is Non-Standard (< 4 core sections):** + +Display: "**Format Detected:** Non-Standard GDD + +This GDD does not follow the canonical gds-create-gdd structure (only {count}/7 core sections present). + +You have options:" + +Present MENU OPTIONS below for user selection + +### 6. Present MENU OPTIONS (Non-Standard GDDs Only) + +**[A] Parity Check** - Analyze gaps and estimate effort to reach canonical GDS parity +**[B] Validate As-Is** - Proceed with validation using current structure +**[C] Exit** - Exit validation and review format findings + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input +- Only proceed based on user selection + +#### Menu Handling Logic: + +- IF A (Parity Check): Read fully and follow: {altStepFile} (step-v-02b-parity-check.md) +- IF B (Validate As-Is): Display "Proceeding with validation..." then read fully and follow: {nextStepFile} +- IF C (Exit): Display format findings summary and exit validation +- IF Any other: help user respond, then redisplay menu + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- All ## Level 2 headers extracted successfully +- Canonical GDS core sections checked systematically +- Format classified correctly based on section count +- Findings reported to validation report +- Canonical/Variant GDDs proceed directly to next validation step +- Non-Standard GDDs pause and present options to user +- User can choose parity check, validate as-is, or exit + +### ❌ SYSTEM FAILURE: + +- Not extracting all headers before classification +- Incorrect format classification +- Not reporting findings to validation report +- Not pausing for non-standard GDDs +- Proceeding without user decision for non-standard formats + +**Master Rule:** Format detection determines validation path. Non-standard GDDs require user choice before proceeding. diff --git a/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-02b-parity-check.md b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-02b-parity-check.md new file mode 100644 index 0000000..0f35fee --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-02b-parity-check.md @@ -0,0 +1,238 @@ +--- +name: 'step-v-02b-parity-check' +description: 'Document Parity Check - Analyze a non-standard GDD and identify gaps against the canonical gds-create-gdd schema' + +# File references (ONLY variables used in this step) +nextStepFile: './step-v-03-density-validation.md' +gddFile: '{gdd_file_path}' +validationReportPath: '{validation_report_path}' +--- + +# Step V-2B: Document Parity Check + +## STEP GOAL: + +Analyze a non-standard GDD and identify gaps to achieve canonical gds-create-gdd parity, presenting the user with options for how to proceed. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and Quality Assurance Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in collaborative dialogue, not command-response +- ✅ You bring BMAD GDD standards expertise and gap analysis +- ✅ User brings game design knowledge and GDD context + +### Step-Specific Rules: + +- 🎯 Focus ONLY on analyzing gaps and estimating parity effort +- 🚫 FORBIDDEN to perform other validation checks in this step +- 💬 Approach: Systematic gap analysis with clear recommendations +- 🚪 This is an optional branch step - user chooses next action + +## EXECUTION PROTOCOLS: + +- 🎯 Analyze each canonical GDS core section for gaps +- 💾 Append parity analysis to validation report +- 📖 Present options and await user decision +- 🚫 FORBIDDEN to proceed without user selection + +## CONTEXT BOUNDARIES: + +- Available context: Non-standard GDD from step 2, validation report in progress +- Focus: Parity analysis only - what's missing, what's needed +- Limits: Don't perform other validation checks, don't auto-proceed +- Dependencies: Step 2 classified GDD as non-standard and user chose parity check + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Analyze Each Canonical GDS Core Section + +For each of the 7 canonical GDS core sections, analyze: + +**Executive Summary:** + +- Does the GDD have a core concept / vision? +- Is target audience identified? +- Are USPs (unique selling points) listed? +- Gap: [What's missing or incomplete] + +**Goals and Context:** + +- Are project goals defined? +- Is background / rationale clear? +- Gap: [What's missing or incomplete] + +**Core Gameplay:** + +- Are game pillars defined? +- Is the core gameplay loop documented? +- Are win/loss conditions clear? +- Gap: [What's missing or incomplete] + +**Game Mechanics:** + +- Are primary mechanics listed? +- Are controls and input documented? +- Gap: [What's missing or incomplete] + +**Progression and Balance:** + +- Is player progression defined? +- Is the difficulty curve described? +- Is the economy / resource system specified? +- Gap: [What's missing or incomplete] + +**Technical Specifications:** + +- Are performance targets specified? +- Are platform requirements documented? +- Are asset budgets / constraints noted? +- Gap: [What's missing or incomplete] + +**Development Epics:** + +- Are high-level epics identified? +- Is epic scope clear? +- Gap: [What's missing or incomplete] + +### 2. Estimate Effort to Reach Parity + +For each missing or incomplete section, estimate: + +**Effort Level:** + +- Minimal - Section exists but needs minor enhancements +- Moderate - Section missing but content exists elsewhere in GDD +- Significant - Section missing, requires new content creation + +**Total Parity Effort:** + +- Based on individual section estimates +- Classify overall: Quick / Moderate / Substantial effort + +### 3. Report Parity Analysis to Validation Report + +Append to validation report: + +```markdown +## Parity Analysis (Non-Standard GDD) + +### Section-by-Section Gap Analysis + +**Executive Summary:** + +- Status: [Present/Missing/Incomplete] +- Gap: [specific gap description] +- Effort to Complete: [Minimal/Moderate/Significant] + +**Goals and Context:** + +- Status: [Present/Missing/Incomplete] +- Gap: [specific gap description] +- Effort to Complete: [Minimal/Moderate/Significant] + +**Core Gameplay:** + +- Status: [Present/Missing/Incomplete] +- Gap: [specific gap description] +- Effort to Complete: [Minimal/Moderate/Significant] + +**Game Mechanics:** + +- Status: [Present/Missing/Incomplete] +- Gap: [specific gap description] +- Effort to Complete: [Minimal/Moderate/Significant] + +**Progression and Balance:** + +- Status: [Present/Missing/Incomplete] +- Gap: [specific gap description] +- Effort to Complete: [Minimal/Moderate/Significant] + +**Technical Specifications:** + +- Status: [Present/Missing/Incomplete] +- Gap: [specific gap description] +- Effort to Complete: [Minimal/Moderate/Significant] + +**Development Epics:** + +- Status: [Present/Missing/Incomplete] +- Gap: [specific gap description] +- Effort to Complete: [Minimal/Moderate/Significant] + +### Overall Parity Assessment + +**Overall Effort to Reach Canonical GDS Schema:** [Quick/Moderate/Substantial] +**Recommendation:** [Brief recommendation based on analysis] +``` + +### 4. Present Parity Analysis and Options + +Display: + +"**Parity Analysis Complete** + +Your GDD is missing {count} of 7 canonical GDS core sections. The overall effort to reach canonical parity is: **{effort level}** + +**Quick Summary:** +[2-3 sentence summary of key gaps] + +**Recommendation:** +{recommendation from analysis} + +**How would you like to proceed?**" + +### 5. Present MENU OPTIONS + +**[C] Continue Validation** - Proceed with validation using current structure +**[E] Exit & Review** - Exit validation and review parity report +**[S] Save & Exit** - Save parity report and exit + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input +- Only proceed based on user selection + +#### Menu Handling Logic: + +- IF C (Continue): Display "Proceeding with validation..." then read fully and follow: {nextStepFile} +- IF E (Exit): Display parity summary and exit validation +- IF S (Save): Confirm saved, display summary, exit +- IF Any other: help user respond, then redisplay menu + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- All 7 canonical GDS sections analyzed for gaps +- Effort estimates provided for each gap +- Overall parity effort assessed correctly +- Parity analysis reported to validation report +- Clear summary presented to user +- User can choose to continue validation, exit, or save report + +### ❌ SYSTEM FAILURE: + +- Not analyzing all 7 sections systematically +- Missing effort estimates +- Not reporting parity analysis to validation report +- Auto-proceeding without user decision +- Unclear recommendations + +**Master Rule:** Parity check informs user of gaps and effort, but user decides whether to proceed with validation or address gaps first. diff --git a/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-03-density-validation.md b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-03-density-validation.md new file mode 100644 index 0000000..9a983ad --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-03-density-validation.md @@ -0,0 +1,206 @@ +--- +name: 'step-v-03-density-validation' +description: 'Information Density Check - Scan for anti-patterns that violate information density principles in the GDD' + +# File references (ONLY variables used in this step) +nextStepFile: './step-v-04-brief-coverage-validation.md' +gddFile: '{gdd_file_path}' +validationReportPath: '{validation_report_path}' +--- + +# Step V-3: Information Density Validation + +## STEP GOAL: + +Validate the GDD meets BMAD information-density standards by scanning for conversational filler, marketing/pitch-deck language, and redundant expressions that violate conciseness principles. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and Quality Assurance Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in systematic validation, not collaborative dialogue +- ✅ You bring analytical rigor and attention to detail +- ✅ This step runs autonomously - no user input needed + +### Step-Specific Rules: + +- 🎯 Focus ONLY on information density anti-patterns +- 🚫 FORBIDDEN to validate other aspects in this step +- 💬 Approach: Systematic scanning and categorization +- 🚪 This is a validation sequence step - auto-proceeds when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Scan GDD for density anti-patterns systematically +- 💾 Append density findings to validation report +- 📖 Display "Proceeding to next check..." and load next step +- 🚫 FORBIDDEN to pause or request user input + +## CONTEXT BOUNDARIES: + +- Available context: GDD file, validation report with format findings +- Focus: Information density validation only +- Limits: Don't validate other aspects, don't pause for user input +- Dependencies: Step 2 completed - format classification done + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Attempt Sub-Process Validation + +**Try to use Task tool to spawn a subprocess:** + +"Perform information density validation on this GDD: + +1. Load the GDD file +2. Scan for the following anti-patterns: + - Conversational filler phrases (examples: 'The player will be able to...', 'It is important to note that...', 'In order to') + - Marketing / pitch-deck language (examples: 'engaging gameplay', 'immersive experience', 'unique blend', 'revolutionary', 'next-generation') + - Subjective design claims without values (examples: 'fun', 'satisfying', 'deep', 'rich', 'meaningful' - used without concrete backing) + - Wordy phrases (examples: 'Due to the fact that', 'In the event of', 'For the purpose of') + - Redundant phrases (examples: 'Future plans', 'Absolutely essential', 'Past history') +3. Count violations by category with line numbers +4. Classify severity: Critical (>10 violations), Warning (5-10), Pass (<5) + +Return structured findings with counts and examples." + +### 2. Graceful Degradation (if Task tool unavailable) + +If Task tool unavailable, perform analysis directly: + +**Scan for conversational filler patterns:** + +- "The player will be able to..." +- "It is important to note that..." +- "In order to" +- "For the purpose of" +- "With regard to" +- Count occurrences and note line numbers + +**Scan for marketing / pitch-deck language:** + +- "engaging gameplay" +- "immersive experience" +- "unique blend of" +- "revolutionary" +- "next-generation" +- "AAA-quality" +- "unlike anything before" +- Count occurrences and note line numbers + +**Scan for subjective design claims without backing:** + +- "fun", "satisfying", "deep", "rich", "meaningful", "organic", "emergent" - when used as a claim without concrete mechanics/values attached +- Note line numbers (these are WARNINGS, not automatic critical - context matters) + +**Scan for wordy phrases:** + +- "Due to the fact that" (use "because") +- "In the event of" (use "if") +- "At this point in time" (use "now") +- "In a manner that" (use "how") +- Count occurrences and note line numbers + +**Scan for redundant phrases:** + +- "Future plans" (just "plans") +- "Past history" (just "history") +- "Absolutely essential" (just "essential") +- "Completely finish" (just "finish") +- Count occurrences and note line numbers + +### 3. Classify Severity + +**Calculate total violations:** + +- Conversational filler count +- Marketing / pitch-deck count +- Subjective claims without backing +- Wordy phrases count +- Redundant phrases count +- Total = sum of all categories + +**Determine severity:** + +- **Critical:** Total > 10 violations +- **Warning:** Total 5-10 violations +- **Pass:** Total < 5 violations + +### 4. Report Density Findings to Validation Report + +Append to validation report: + +```markdown +## Information Density Validation + +**Anti-Pattern Violations:** + +**Conversational Filler:** {count} occurrences +[If count > 0, list examples with line numbers] + +**Marketing / Pitch-Deck Language:** {count} occurrences +[If count > 0, list examples with line numbers] + +**Subjective Claims Without Backing:** {count} occurrences +[If count > 0, list examples with line numbers - note: context-dependent] + +**Wordy Phrases:** {count} occurrences +[If count > 0, list examples with line numbers] + +**Redundant Phrases:** {count} occurrences +[If count > 0, list examples with line numbers] + +**Total Violations:** {total} + +**Severity Assessment:** [Critical/Warning/Pass] + +**Recommendation:** +[If Critical] "GDD requires significant revision to improve information density. Every sentence should carry design weight - strip marketing language and subjective claims that aren't backed by concrete mechanics." +[If Warning] "GDD would benefit from reducing pitch-deck language and eliminating filler phrases. Favor concrete values over subjective claims." +[If Pass] "GDD demonstrates good information density with minimal violations." +``` + +### 5. Display Progress and Auto-Proceed + +Display: "**Information Density Validation Complete** + +Severity: {Critical/Warning/Pass} + +**Proceeding to next validation check...**" + +Without delay, read fully and follow: {nextStepFile} (step-v-04-brief-coverage-validation.md) + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- GDD scanned for all anti-pattern categories (including pitch-deck language) +- Violations counted with line numbers +- Severity classified correctly +- Findings reported to validation report +- Auto-proceeds to next validation step +- Subprocess attempted with graceful degradation + +### ❌ SYSTEM FAILURE: + +- Not scanning all anti-pattern categories +- Missing severity classification +- Not reporting findings to validation report +- Pausing for user input (should auto-proceed) +- Not attempting subprocess architecture + +**Master Rule:** Information density validation runs autonomously. Scan, classify, report, auto-proceed. Game design docs are especially prone to pitch-deck bloat - catch it here. diff --git a/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-04-brief-coverage-validation.md b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-04-brief-coverage-validation.md new file mode 100644 index 0000000..988eaba --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-04-brief-coverage-validation.md @@ -0,0 +1,229 @@ +--- +name: 'step-v-04-brief-coverage-validation' +description: 'Game Brief Coverage Check - Validate the GDD covers all content from the Game Brief (if used as input)' + +# File references (ONLY variables used in this step) +nextStepFile: './step-v-05-measurability-validation.md' +gddFile: '{gdd_file_path}' +gameBrief: '{game_brief_path}' +validationReportPath: '{validation_report_path}' +--- + +# Step V-4: Game Brief Coverage Validation + +## STEP GOAL: + +Validate that the GDD covers all content from the Game Brief (if a brief was used as input), mapping brief content to GDD sections and identifying gaps. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and Quality Assurance Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in systematic validation, not collaborative dialogue +- ✅ You bring analytical rigor and traceability expertise +- ✅ This step runs autonomously - no user input needed + +### Step-Specific Rules: + +- 🎯 Focus ONLY on Game Brief coverage (conditional on brief existence) +- 🚫 FORBIDDEN to validate other aspects in this step +- 💬 Approach: Systematic mapping and gap analysis +- 🚪 This is a validation sequence step - auto-proceeds when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Check if Game Brief exists in input documents +- 💬 If no brief: Skip this check and report "N/A - No Game Brief" +- 🎯 If brief exists: Map brief content to GDD sections +- 💾 Append coverage findings to validation report +- 📖 Display "Proceeding to next check..." and load next step +- 🚫 FORBIDDEN to pause or request user input + +## CONTEXT BOUNDARIES: + +- Available context: GDD file, input documents from step 1, validation report +- Focus: Game Brief coverage only (conditional) +- Limits: Don't validate other aspects, conditional execution +- Dependencies: Step 1 completed - input documents loaded + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Check for Game Brief + +Check if a Game Brief was loaded in step 1's inputDocuments. Look for files matching `{planning_artifacts}/*brief*.md` or entries in frontmatter referencing a game brief (typically produced by `gds-create-game-brief`). + +**IF no Game Brief found:** +Append to validation report: + +```markdown +## Game Brief Coverage + +**Status:** N/A - No Game Brief was provided as input +``` + +Display: "**Game Brief Coverage: Skipped** (No Game Brief provided) + +**Proceeding to next validation check...**" + +Without delay, read fully and follow: {nextStepFile} + +**IF Game Brief exists:** Continue to step 2 below + +### 2. Attempt Sub-Process Validation + +**Try to use Task tool to spawn a subprocess:** + +"Perform Game Brief coverage validation: + +1. Load the Game Brief +2. Extract key content: + - Core fantasy / game vision + - Target player / audience + - Core gameplay hook / elevator pitch + - Target platforms + - Reference titles and inspirations + - Key mechanics or systems the brief calls out + - Design goals / pillars + - Scope constraints (team size, timeline, engine) +3. For each item, search the GDD for corresponding coverage +4. Classify coverage: Fully Covered / Partially Covered / Not Found / Intentionally Excluded +5. Note any gaps with severity: Critical / Moderate / Informational + +Return structured coverage map with classifications." + +### 3. Graceful Degradation (if Task tool unavailable) + +If Task tool unavailable, perform analysis directly: + +**Extract from Game Brief:** + +- Core fantasy: What is the player supposed to feel / be? +- Audience: Who is this game for? +- Hook: What's the one-sentence pitch? +- Platforms: Target hardware / storefronts +- References: Reference titles and inspirations +- Mechanics: Key mechanics the brief identified +- Pillars / goals: Design pillars or success criteria +- Scope: Team, timeline, engine, budget constraints + +**For each item, search GDD:** + +- Scan Executive Summary for core fantasy and hook +- Check Goals and Context for audience and pillars +- Look for references in Art/Audio or inspiration callouts +- Check Core Gameplay / Game Mechanics for called-out mechanics +- Review Technical Specifications for platform and scope constraints +- Check Out of Scope section for explicit exclusions + +**Classify coverage:** + +- **Fully Covered:** Content present and complete +- **Partially Covered:** Content present but incomplete +- **Not Found:** Content missing from GDD +- **Intentionally Excluded:** Content explicitly noted as out of scope + +### 4. Assess Coverage and Severity + +**For each gap (Partially Covered or Not Found):** + +- Is this Critical? (Core fantasy, primary mechanics, target platform) +- Is this Moderate? (Secondary mechanics, nice-to-have pillars) +- Is this Informational? (Minor references, optional features) + +**Note:** Some exclusions may be intentional - the GDD legitimately narrowed scope from the brief. Look for explicit mentions in the Out of Scope section. + +### 5. Report Coverage Findings to Validation Report + +Append to validation report: + +```markdown +## Game Brief Coverage + +**Game Brief:** {brief_file_name} + +### Coverage Map + +**Core Fantasy / Vision:** [Fully/Partially/Not Found/Intentionally Excluded] +[If gap: Note severity and specific missing content] + +**Target Audience:** [Fully/Partially/Not Found/Intentionally Excluded] +[If gap: Note severity and specific missing content] + +**Core Hook / Elevator Pitch:** [Fully/Partially/Not Found/Intentionally Excluded] +[If gap: Note severity and specific missing content] + +**Target Platforms:** [Fully/Partially/Not Found/Intentionally Excluded] +[If gap: Note severity and specific missing content] + +**Reference Titles / Inspirations:** [Fully/Partially/Not Found/Intentionally Excluded] +[If gap: Note severity and specific missing content] + +**Key Mechanics from Brief:** [Fully/Partially/Not Found/Intentionally Excluded] +[If gap: List specific mechanics with severity] + +**Design Pillars / Goals:** [Fully/Partially/Not Found/Intentionally Excluded] +[If gap: Note severity and specific missing content] + +**Scope Constraints:** [Fully/Partially/Not Found/Intentionally Excluded] +[If gap: Note severity and specific missing content] + +### Coverage Summary + +**Overall Coverage:** [percentage or qualitative assessment] +**Critical Gaps:** [count] [list if any] +**Moderate Gaps:** [count] [list if any] +**Informational Gaps:** [count] [list if any] + +**Recommendation:** +[If critical gaps exist] "GDD should be revised to cover critical Game Brief content - the brief defined what this project is; the GDD should honor it or explicitly document the deviation." +[If moderate gaps] "Consider addressing moderate gaps or documenting them as intentional scope changes in Out of Scope." +[If minimal gaps] "GDD provides good coverage of Game Brief content." +``` + +### 6. Display Progress and Auto-Proceed + +Display: "**Game Brief Coverage Validation Complete** + +Overall Coverage: {assessment} + +**Proceeding to next validation check...**" + +Without delay, read fully and follow: {nextStepFile} (step-v-05-measurability-validation.md) + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- Checked for Game Brief existence correctly +- If no brief: Reported "N/A" and skipped gracefully +- If brief exists: Mapped all key brief content to GDD sections +- Coverage classified appropriately (Fully/Partially/Not Found/Intentionally Excluded) +- Severity assessed for gaps (Critical/Moderate/Informational) +- Findings reported to validation report +- Auto-proceeds to next validation step +- Subprocess attempted with graceful degradation + +### ❌ SYSTEM FAILURE: + +- Not checking for brief existence before attempting validation +- If brief exists: not mapping all key content areas +- Missing coverage classifications +- Not reporting findings to validation report +- Not auto-proceeding + +**Master Rule:** Game Brief coverage is conditional - skip if no brief, validate thoroughly if brief exists. Always auto-proceed. diff --git a/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-05-measurability-validation.md b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-05-measurability-validation.md new file mode 100644 index 0000000..6008d57 --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-05-measurability-validation.md @@ -0,0 +1,279 @@ +--- +name: 'step-v-05-measurability-validation' +description: 'Measurability Validation - Validate design goals, mechanics, and technical specs are measurable and testable' + +# File references (ONLY variables used in this step) +nextStepFile: './step-v-06-traceability-validation.md' +gddFile: '{gdd_file_path}' +validationReportPath: '{validation_report_path}' +--- + +# Step V-5: Measurability Validation + +## STEP GOAL: + +Validate that all design goals, mechanics specifications, and technical targets in the GDD are measurable and testable - concrete numbers over subjective claims. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and Quality Assurance Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in systematic validation, not collaborative dialogue +- ✅ You bring analytical rigor and game-design engineering expertise +- ✅ This step runs autonomously - no user input needed + +### Step-Specific Rules: + +- 🎯 Focus ONLY on measurability of design goals, mechanics, and tech specs +- 🚫 FORBIDDEN to validate other aspects in this step +- 💬 Approach: Systematic item-by-item analysis +- 🚪 This is a validation sequence step - auto-proceeds when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Extract design goals, mechanics, and technical specs from GDD +- 💾 Validate each for concrete numbers and testability +- 📖 Append findings to validation report +- 📖 Display "Proceeding to next check..." and load next step +- 🚫 FORBIDDEN to pause or request user input + +## CONTEXT BOUNDARIES: + +- Available context: GDD file, validation report +- Focus: Measurability of design goals, mechanics, and tech specs +- Limits: Don't validate other aspects, don't pause for user input +- Dependencies: Steps 2-4 completed - initial validation checks done + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Attempt Sub-Process Validation + +**Try to use Task tool to spawn a subprocess:** + +"Perform measurability validation on this GDD: + +**Design Goals / Success Metrics:** + +1. Extract all entries from Success Metrics / design goals sections +2. Check each for: + - Concrete target values (retention %, completion rate, session length, FPS) + - Measurement method (telemetry, playtest, automated profiler) + - No subjective terms (fun, satisfying, immersive) without backing values +3. Document violations with line numbers + +**Mechanics & Systems:** + +1. Extract all mechanics from Core Gameplay and Game Mechanics sections +2. Check each for: + - Concrete values (damages, timings, costs, ranges, cooldowns) + - Feel parameters (jump height, coyote time, input buffer frames, etc.) when relevant to genre + - No subjective adjectives (easy, fun, responsive) without metrics + - No vague quantifiers (many, several, various) +3. Document violations with line numbers + +**Technical Specifications:** + +1. Extract all tech specs from Technical Specifications section +2. Check each for: + - Target FPS / frame-time per platform + - Memory budget per platform + - Load time budgets + - Resolution targets + - Measurement method (profiler, automation, QA) +3. Document violations with line numbers + +Return structured findings with violation counts and examples." + +### 2. Graceful Degradation (if Task tool unavailable) + +If Task tool unavailable, perform analysis directly: + +**Design Goals Analysis:** + +Extract all design goals / success metrics and check each for: + +**Concrete targets:** + +- Does it include a target value? (e.g., "75% completion rate for Act 1", not "players should finish the story") +- Is measurement method noted? (telemetry event, playtest observation, automated test) + +**No subjective terms without backing:** + +- Scan for: fun, engaging, immersive, satisfying, rewarding (without accompanying metrics) +- Note line numbers + +**Mechanics Analysis:** + +Extract all mechanics / systems and check each for: + +**Concrete values:** + +- Does the mechanic include numbers where it should? (damage, speed, cooldown, cost) +- Are feel parameters documented when genre demands (jump arc, coyote time, input buffer, hit windows)? + +**No subjective adjectives:** + +- Scan for: easy, fast, simple, intuitive, responsive, fluid, tight (without metrics) +- Note line numbers + +**No vague quantifiers:** + +- Scan for: multiple, several, some, many, few, various, number of +- Note line numbers + +**Technical Specifications Analysis:** + +Extract all tech specs and check each for: + +**Specific metrics:** + +- Is there a target FPS per platform? +- Is memory budget quantified per platform? +- Are load times budgeted? +- Is the measurement method or tooling noted? + +### 3. Tally Violations + +**Design Goal Violations:** + +- Missing target values: count +- Missing measurement method: count +- Subjective without backing: count +- Total design-goal violations: sum + +**Mechanics Violations:** + +- Missing concrete values: count +- Subjective adjectives: count +- Vague quantifiers: count +- Missing feel parameters (where genre demands): count +- Total mechanics violations: sum + +**Technical Spec Violations:** + +- Missing FPS targets: count +- Missing memory budget: count +- Missing load-time targets: count +- Missing measurement method: count +- Total tech-spec violations: sum + +**Total violations:** sum of all three categories + +### 4. Report Measurability Findings to Validation Report + +Append to validation report: + +```markdown +## Measurability Validation + +### Design Goals / Success Metrics + +**Total Goals Analyzed:** {count} + +**Missing Target Values:** {count} +[If violations exist, list examples with line numbers] + +**Missing Measurement Methods:** {count} +[If missing, list examples with line numbers] + +**Subjective Without Backing:** {count} +[If found, list examples with line numbers] + +**Design Goal Violations Total:** {total} + +### Mechanics & Systems + +**Total Mechanics Analyzed:** {count} + +**Missing Concrete Values:** {count} +[If missing, list examples with line numbers] + +**Subjective Adjectives:** {count} +[If found, list examples with line numbers] + +**Vague Quantifiers:** {count} +[If found, list examples with line numbers] + +**Missing Feel Parameters (genre-required):** {count} +[If missing, list examples with line numbers] + +**Mechanics Violations Total:** {total} + +### Technical Specifications + +**Total Specs Analyzed:** {count} + +**Missing FPS Targets:** {count} +[If missing, list examples with line numbers] + +**Missing Memory Budget:** {count} +[If missing, list examples with line numbers] + +**Missing Load-Time Targets:** {count} +[If missing, list examples with line numbers] + +**Missing Measurement Methods:** {count} +[If missing, list examples with line numbers] + +**Tech Spec Violations Total:** {total} + +### Overall Assessment + +**Total Items:** {goals + mechanics + specs} +**Total Violations:** {sum of all violation totals} + +**Severity:** [Critical if >10 violations, Warning if 5-10, Pass if <5] + +**Recommendation:** +[If Critical] "Many design goals, mechanics, and tech specs lack concrete values. A GDD without numbers is a wishlist - revise so each item is testable." +[If Warning] "Some items need refinement for measurability. Focus on violating items above - especially any feel parameters or tech targets without numbers." +[If Pass] "GDD demonstrates good measurability with minimal issues." +``` + +### 5. Display Progress and Auto-Proceed + +Display: "**Measurability Validation Complete** + +Total Violations: {count} ({severity}) + +**Proceeding to next validation check...**" + +Without delay, read fully and follow: {nextStepFile} (step-v-06-traceability-validation.md) + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- All design goals extracted and analyzed for measurability +- All mechanics extracted and analyzed for concrete values +- All tech specs extracted and analyzed for targets +- Violations documented with line numbers +- Severity assessed correctly +- Findings reported to validation report +- Auto-proceeds to next validation step +- Subprocess attempted with graceful degradation + +### ❌ SYSTEM FAILURE: + +- Not analyzing all three categories (goals, mechanics, tech specs) +- Missing line numbers for violations +- Not reporting findings to validation report +- Not assessing severity +- Not auto-proceeding + +**Master Rule:** Design intent needs numbers to become design commitment. Validate every goal, mechanic, and tech spec for measurability, document violations, auto-proceed. diff --git a/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-06-traceability-validation.md b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-06-traceability-validation.md new file mode 100644 index 0000000..c0ff78b --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-06-traceability-validation.md @@ -0,0 +1,248 @@ +--- +name: 'step-v-06-traceability-validation' +description: 'Traceability Validation - Validate the chain from vision → pillars → core loop → mechanics → epics is intact' + +# File references (ONLY variables used in this step) +nextStepFile: './step-v-07-implementation-leakage-validation.md' +gddFile: '{gdd_file_path}' +validationReportPath: '{validation_report_path}' +--- + +# Step V-6: Traceability Validation + +## STEP GOAL: + +Validate the traceability chain from Vision → Game Pillars → Core Gameplay Loop → Mechanics → Development Epics is intact, ensuring every mechanic and epic traces back to the core fantasy and pillars. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and Quality Assurance Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in systematic validation, not collaborative dialogue +- ✅ You bring analytical rigor and traceability-matrix expertise +- ✅ This step runs autonomously - no user input needed + +### Step-Specific Rules: + +- 🎯 Focus ONLY on traceability chain validation +- 🚫 FORBIDDEN to validate other aspects in this step +- 💬 Approach: Systematic chain validation and orphan detection +- 🚪 This is a validation sequence step - auto-proceeds when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Build and validate traceability matrix +- 💾 Identify broken chains and orphan mechanics / epics +- 📖 Append findings to validation report +- 📖 Display "Proceeding to next check..." and load next step +- 🚫 FORBIDDEN to pause or request user input + +## CONTEXT BOUNDARIES: + +- Available context: GDD file, validation report +- Focus: Traceability chain validation only +- Limits: Don't validate other aspects, don't pause for user input +- Dependencies: Steps 2-5 completed - initial validations done + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Attempt Sub-Process Validation + +**Try to use Task tool to spawn a subprocess:** + +"Perform traceability validation on this GDD: + +1. Extract content from Executive Summary (core fantasy / vision, USPs) +2. Extract Game Pillars from Core Gameplay +3. Extract Core Gameplay Loop +4. Extract Mechanics from Game Mechanics (and any game-type specific sections) +5. Extract Development Epics +6. Extract Scope (Out of Scope section) + +**Validate chains:** + +- Vision / Core Fantasy → Pillars: Do pillars embody the core fantasy? +- Pillars → Core Gameplay Loop: Does the loop reinforce the pillars? +- Core Loop → Mechanics: Does each mechanic serve the loop or a pillar? +- Mechanics → Epics: Does each mechanic map to a delivering epic? +- Scope → Mechanics: Do in-scope mechanics align with pillars, and out-of-scope items truly belong out? + +**Identify orphans:** + +- Mechanics that don't serve any pillar or the core loop +- Pillars without mechanics reinforcing them +- Epics not tied to any mechanic or system +- Loop elements without supporting mechanics + +Build traceability matrix and identify broken chains and orphan mechanics/epics. + +Return structured findings with chain status and orphan list." + +### 2. Graceful Degradation (if Task tool unavailable) + +If Task tool unavailable, perform analysis directly: + +**Step 1: Extract key elements** + +- Executive Summary: Note core fantasy / vision +- Game Pillars: List pillars +- Core Gameplay Loop: Describe the loop's steps +- Mechanics: List all mechanics and systems +- Epics: List all development epics +- Out of Scope: List excluded items + +**Step 2: Validate Vision → Pillars** + +- Do the pillars express the core fantasy in actionable terms? +- Are pillars specific enough to steer design decisions? +- Note any misalignment + +**Step 3: Validate Pillars → Core Loop** + +- Does the core gameplay loop actively reinforce the pillars? +- Are pillars visible in the loop's steps? +- Note pillars that don't show up in the loop + +**Step 4: Validate Core Loop → Mechanics** + +- For each loop step, is there a mechanic that enables it? +- List mechanics that don't map to the loop or a pillar +- Note orphan mechanics (mechanics without design justification) + +**Step 5: Validate Mechanics → Epics** + +- Does each mechanic have an epic delivering it? +- Are there epics without a clear mechanic payload? +- Note misalignments + +**Step 6: Validate Scope → Alignment** + +- Do in-scope mechanics align with pillars? +- Are out-of-scope items truly off-pillar, or are they critical mechanics misclassified? +- Note scope incoherence + +**Step 7: Build traceability matrix** + +- Map each mechanic to its source (pillar or loop step) +- Map each epic to its mechanics +- Note orphan mechanics and orphan epics +- Identify broken chains + +### 3. Tally Traceability Issues + +**Broken chains:** + +- Vision → Pillars misalignment: count +- Pillars → Loop gaps: count +- Loop → Mechanics gaps: count +- Mechanics → Epics gaps: count +- Scope → Mechanics misalignments: count + +**Orphan elements:** + +- Orphan mechanics (no pillar/loop source): count +- Unsupported pillars (no reinforcing mechanics): count +- Orphan epics (no clear mechanic payload): count +- Loop steps without supporting mechanics: count + +**Total issues:** Sum of all broken chains and orphans + +### 4. Report Traceability Findings to Validation Report + +Append to validation report: + +```markdown +## Traceability Validation + +### Chain Validation + +**Vision → Pillars:** [Intact/Gaps Identified] +{If gaps: List specific misalignments} + +**Pillars → Core Gameplay Loop:** [Intact/Gaps Identified] +{If gaps: List pillars without loop reinforcement} + +**Core Loop → Mechanics:** [Intact/Gaps Identified] +{If gaps: List loop steps without supporting mechanics} + +**Mechanics → Epics:** [Intact/Gaps Identified] +{If gaps: List mechanics without delivering epics} + +**Scope → Mechanics Alignment:** [Intact/Misaligned] +{If misaligned: List specific issues} + +### Orphan Elements + +**Orphan Mechanics (no pillar/loop source):** {count} +{List orphan mechanics} + +**Unsupported Pillars:** {count} +{List pillars lacking reinforcing mechanics} + +**Orphan Epics:** {count} +{List epics without clear mechanic payload} + +**Loop Steps Without Mechanics:** {count} +{List loop steps lacking supporting mechanics} + +### Traceability Matrix + +{Summary table showing pillar → mechanic → epic coverage} + +**Total Traceability Issues:** {total} + +**Severity:** [Critical if orphan mechanics or unsupported pillars exist, Warning if gaps, Pass if intact] + +**Recommendation:** +[If Critical] "Orphan mechanics or unsupported pillars found - every mechanic must serve a pillar or the core loop, every pillar must be reinforced by mechanics. Fix these before proceeding to architecture." +[If Warning] "Traceability gaps identified - strengthen chains so downstream phases (architecture, epics) can trust the design intent." +[If Pass] "Traceability chain is intact - mechanics serve pillars, epics deliver mechanics, scope reflects the design." +``` + +### 5. Display Progress and Auto-Proceed + +Display: "**Traceability Validation Complete** + +Total Issues: {count} ({severity}) + +**Proceeding to next validation check...**" + +Without delay, read fully and follow: {nextStepFile} (step-v-07-implementation-leakage-validation.md) + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- All traceability chains validated systematically +- Orphan mechanics / epics identified +- Broken chains documented +- Traceability matrix built +- Severity assessed correctly +- Findings reported to validation report +- Auto-proceeds to next validation step +- Subprocess attempted with graceful degradation + +### ❌ SYSTEM FAILURE: + +- Not validating all traceability chains +- Missing orphan detection +- Not building traceability matrix +- Not reporting findings to validation report +- Not auto-proceeding + +**Master Rule:** Every mechanic should trace to a pillar or the core loop. Every epic should deliver a mechanic. Orphan mechanics are scope creep in disguise. diff --git a/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-07-implementation-leakage-validation.md b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-07-implementation-leakage-validation.md new file mode 100644 index 0000000..a92396f --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-07-implementation-leakage-validation.md @@ -0,0 +1,212 @@ +--- +name: 'step-v-07-implementation-leakage-validation' +description: 'Implementation Leakage Check - Ensure the GDD does not include engine/code details that belong in architecture' + +# File references (ONLY variables used in this step) +nextStepFile: './step-v-08-genre-compliance-validation.md' +gddFile: '{gdd_file_path}' +validationReportPath: '{validation_report_path}' +--- + +# Step V-7: Implementation Leakage Validation + +## STEP GOAL: + +Ensure mechanics, systems, and technical specifications in the GDD don't include engine/implementation details - they should specify WHAT the player experiences and WHAT the system must achieve, not HOW it's built. Those details belong in the architecture document. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and Quality Assurance Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in systematic validation, not collaborative dialogue +- ✅ You bring analytical rigor and separation-of-concerns expertise +- ✅ This step runs autonomously - no user input needed + +### Step-Specific Rules: + +- 🎯 Focus ONLY on implementation / engine leakage detection +- 🚫 FORBIDDEN to validate other aspects in this step +- 💬 Approach: Systematic scanning for engine and implementation terms +- 🚪 This is a validation sequence step - auto-proceeds when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Scan mechanics, systems, and tech specs for engine/implementation terms +- 💾 Distinguish platform/engine-as-constraint vs. engine-as-implementation +- 📖 Append findings to validation report +- 📖 Display "Proceeding to next check..." and load next step +- 🚫 FORBIDDEN to pause or request user input + +## CONTEXT BOUNDARIES: + +- Available context: GDD file, validation report +- Focus: Implementation leakage detection only +- Limits: Don't validate other aspects, don't pause for user input +- Dependencies: Steps 2-6 completed - initial validations done + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Attempt Sub-Process Validation + +**Try to use Task tool to spawn a subprocess:** + +"Perform implementation leakage validation on this GDD: + +**Scan for:** + +1. Engine / framework internals (Rigidbody2D, GameObject, Actor class, UBlueprint, Node2D, AnimationTree, UnrealBuildTool, Mono, IL2CPP, etc.) +2. Scripting language and code patterns (C++, C#, GDScript, specific class names, specific methods like Update()/Tick()/_process()) +3. Shader / rendering internals (HLSL, GLSL, specific shader types, specific render passes, URP/HDRP/Deferred specifics) +4. Networking library internals (Mirror, Photon, Netcode for GameObjects, specific RPC types, replication modes) +5. Data format internals (JSON schema, specific serializer, ScriptableObject, DataTable, UDataAsset) unless relevant to player-facing capability +6. Build / tooling specifics (specific addressables bundles, specific platform SDK calls) + +**For each term found:** + +- Is this a platform constraint? (e.g., 'must run on Unreal 5 for PS5 certification' - platform constraint is OK in Technical Specifications) +- Is this an engine capability mention? (e.g., 'uses the engine's nav-mesh system' - acceptable if abstracted) +- Or is this implementation detail? (e.g., 'NavAgent component moves along Nav Mesh with custom filter' - HOW, not WHAT) + +Document violations with line numbers and explanation. + +Return structured findings with leakage counts and examples." + +### 2. Graceful Degradation (if Task tool unavailable) + +If Task tool unavailable, perform analysis directly: + +**Implementation leakage terms to scan for:** + +**Unity-specific:** +GameObject, MonoBehaviour, ScriptableObject, Rigidbody, Rigidbody2D, Transform, Coroutine, Update, FixedUpdate, Addressables, URP, HDRP, NavMeshAgent, Animator component, Cinemachine internals, etc. + +**Unreal-specific:** +UObject, Actor, Pawn, Character class, Blueprint, UBlueprint, Tick(), UMG, Gameplay Ability System internals, UE Niagara internals, UnrealBuildTool, etc. + +**Godot-specific:** +Node, Node2D, Node3D, GDScript keywords, \_process, \_physics_process, AnimationPlayer node internals, etc. + +**Generic engine internals:** +Game loop implementation, ECS specifics (EnTT, Unity DOTS, etc.), specific physics libraries (PhysX, Box2D, Havok) unless platform constraint + +**Networking:** +Mirror, Photon, Netcode for GameObjects, specific RPC annotations, ReplicationMode, NetworkBehaviour - unless documenting a hard constraint + +**Shaders / rendering:** +HLSL, GLSL, specific shader stage mentions, specific render passes, deferred vs forward (unless a hard constraint) + +**Tooling:** +Specific CI / addressable bundle names, specific asset pipeline scripts + +**For each term found:** + +- Determine if it's a hard constraint (OK in Technical Specs) or implementation detail (leakage) +- Example: "Target engine: Unreal Engine 5.4 for PS5/XSX compatibility" - constraint, OK +- Example: "Combat uses Gameplay Ability System with custom AttributeSet classes" - leakage, belongs in architecture + +**Count violations and note line numbers** + +### 3. Tally Implementation Leakage + +**By category:** + +- Engine internals (Unity/Unreal/Godot/other) leakage: count +- Scripting / code pattern leakage: count +- Shader / rendering internals leakage: count +- Networking library leakage: count +- Data format internals leakage: count +- Tooling / build specifics leakage: count +- Other implementation details: count + +**Total implementation leakage violations:** sum + +### 4. Report Implementation Leakage Findings to Validation Report + +Append to validation report: + +```markdown +## Implementation Leakage Validation + +### Leakage by Category + +**Engine Internals:** {count} violations +{If violations, list examples with line numbers} + +**Scripting / Code Patterns:** {count} violations +{If violations, list examples with line numbers} + +**Shader / Rendering Internals:** {count} violations +{If violations, list examples with line numbers} + +**Networking Library Internals:** {count} violations +{If violations, list examples with line numbers} + +**Data Format Internals:** {count} violations +{If violations, list examples with line numbers} + +**Tooling / Build Specifics:** {count} violations +{If violations, list examples with line numbers} + +**Other Implementation Details:** {count} violations +{If violations, list examples with line numbers} + +### Summary + +**Total Implementation Leakage Violations:** {total} + +**Severity:** [Critical if >5 violations, Warning if 2-5, Pass if <2] + +**Recommendation:** +[If Critical] "Extensive engine/implementation leakage found. The GDD specifies HOW instead of WHAT. Move these details into the architecture document - the GDD should be engine-agnostic where possible." +[If Warning] "Some implementation leakage detected. Review violations and move implementation details to architecture." +[If Pass] "No significant implementation leakage found. The GDD properly specifies player experience and system behavior without engine internals." + +**Note:** Target engine, platform, and hard constraints (e.g., "Must ship on PS5 using Unreal 5 for certification reasons") belong in Technical Specifications and are acceptable. The leakage check is about _how_ mechanics are built, not _on what_ they run. +``` + +### 5. Display Progress and Auto-Proceed + +Display: "**Implementation Leakage Validation Complete** + +Total Violations: {count} ({severity}) + +**Proceeding to next validation check...**" + +Without delay, read fully and follow: {nextStepFile} (step-v-08-genre-compliance-validation.md) + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- Scanned mechanics, systems, and tech specs for all implementation term categories +- Distinguished platform constraints from implementation leakage +- Violations documented with line numbers and explanations +- Severity assessed correctly +- Findings reported to validation report +- Auto-proceeds to next validation step +- Subprocess attempted with graceful degradation + +### ❌ SYSTEM FAILURE: + +- Not scanning all implementation term categories +- Not distinguishing constraints from leakage +- Missing line numbers for violations +- Not reporting findings to validation report +- Not auto-proceeding + +**Master Rule:** The GDD specifies WHAT, not HOW. Engine-specific implementation details belong in the architecture document, not the GDD. diff --git a/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-08-genre-compliance-validation.md b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-08-genre-compliance-validation.md new file mode 100644 index 0000000..439e439 --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-08-genre-compliance-validation.md @@ -0,0 +1,291 @@ +--- +name: 'step-v-08-genre-compliance-validation' +description: 'Genre Compliance Validation - Validate genre-specific conventions are documented in high-complexity genres' + +# File references (ONLY variables used in this step) +nextStepFile: './step-v-09-game-type-validation.md' +gddFile: '{gdd_file_path}' +gddFrontmatter: '{gdd_frontmatter}' +validationReportPath: '{validation_report_path}' +genreComplexityData: '../data/genre-complexity.csv' +--- + +# Step V-8: Genre Compliance Validation + +## STEP GOAL: + +Validate genre-specific conventions are present for high-complexity genres (Action/Platformer, RPG, Roguelike, Shooter, MOBA, Fighting, etc.), ensuring genre expectations and required systems are properly documented. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and Quality Assurance Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in systematic validation, not collaborative dialogue +- ✅ You bring genre expertise and game-design knowledge +- ✅ This step runs autonomously - no user input needed + +### Step-Specific Rules: + +- 🎯 Focus ONLY on genre-specific compliance +- 🚫 FORBIDDEN to validate other aspects in this step +- 💬 Approach: Conditional validation based on genre complexity +- 🚪 This is a validation sequence step - auto-proceeds when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Check classification.gameType / genre from GDD frontmatter +- 💬 If low complexity genre: Skip detailed checks +- 🎯 If high complexity: Validate required genre-specific sections +- 💾 Append compliance findings to validation report +- 📖 Display "Proceeding to next check..." and load next step +- 🚫 FORBIDDEN to pause or request user input + +## CONTEXT BOUNDARIES: + +- Available context: GDD file with frontmatter classification, validation report +- Focus: Genre compliance only (conditional on genre complexity) +- Limits: Don't validate other aspects, conditional execution +- Dependencies: Steps 2-7 completed - format and requirements validation done + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Load Genre Complexity Data + +Load and read the complete file at: +`{genreComplexityData}` (../data/genre-complexity.csv) + +This CSV contains: + +- Genre classifications and complexity levels (high/medium/low) +- Required special sections for each genre +- Key concerns and requirements for complex genres + +Internalize this data - it drives which genres require special sections. + +### 2. Extract Genre Classification + +From GDD frontmatter, extract: + +- `classification.gameType` - what game type/genre is this? +- If not present, inspect the GDD content for genre signals (combat mechanics, stats, procedural generation, etc.) and match against the `signals` column in `genre-complexity.csv` + +**If no genre classification found and signals are ambiguous:** +Treat as "general" (low complexity) and proceed. + +### 3. Determine Genre Complexity + +**From genre-complexity.csv:** + +**Low complexity genres (skip detailed checks):** + +- general +- idle-incremental +- sandbox +- party-game +- text-based + +**Medium complexity genres (targeted checks):** + +- strategy, horror, metroidvania, adventure, puzzle, racing, sports, card-game, tower-defense, visual-novel, rhythm, turn-based-tactics + +**High complexity genres (require special sections):** + +- action-platformer, rpg, roguelike, shooter, moba, fighting, survival, simulation + +### 4. For High/Medium-Complexity Genres: Validate Required Special Sections + +**Attempt subprocess validation:** + +"Perform genre compliance validation for {genre}: + +Based on {genre} requirements from genre-complexity.csv, check the GDD for: + +**Action-Platformer:** + +- Movement feel table (jump height, air time, coyote time, input buffer) +- Combat specs (hitbox/hurtbox conventions, damage tables) +- Level gating rules +- Difficulty curve via geometry / enemy placement + +**RPG:** + +- Stat system (what stats, how they interact, caps) +- Leveling curve (XP required per level, stat gains) +- Inventory rules (slot system, stacking, weight) +- Quest state machine (active/completed/failed/branching) +- Save model (save points, autosaves, slot rules) + +**Roguelike:** + +- Run structure (length, gates, boss cadence) +- Meta-progression vs in-run progression distinction +- Seed determinism rules +- Balance bands (per-run scaling) + +**Shooter:** + +- Weapon feel table (TTK, recoil, spread, magazine) +- Netcode model (if multiplayer) +- Hitreg model (client-authoritative vs server-authoritative) +- Map flow and choke points +- Spawn logic + +**MOBA:** + +- Hero kit matrix (roles, abilities, counters) +- Map/lane pacing +- Matchmaking / MMR model +- Tick rate / latency tolerance + +**Fighting:** + +- Frame data tables (startup / active / recovery) +- Netcode model (rollback expected for competitive) +- Input spec (buffer, negative edge, motion tolerance) +- Training mode contents + +**Survival:** + +- Resource economy (scarcity curves) +- Crafting tree +- Threat pacing (day/night, seasonal, AI escalation) +- Persistence model (save scope, base durability) + +**Simulation:** + +- Systems interaction map +- Balance for long sessions +- Emergence boundaries (what is and isn't allowed) +- End-state or open-ended definition + +**Medium-complexity genres:** + +- Check for the `special_sections` from CSV for that genre + +For each required section: + +- Is it present in GDD? +- Is it adequately documented? +- Note any gaps + +Return compliance matrix with presence/adequacy assessment." + +**Graceful degradation (if no Task tool):** + +- Manually check for required sections based on genre and the genre-complexity.csv `special_sections` column +- List present sections and missing sections +- Assess adequacy of documentation + +### 5. For Low-Complexity Genres: Skip Detailed Checks + +Append to validation report: + +```markdown +## Genre Compliance Validation + +**Genre:** {genre} +**Complexity:** Low (general/standard) +**Assessment:** N/A - No special genre compliance requirements + +**Note:** This GDD is for a low-complexity genre without heavy genre-conventions checks. +``` + +Display: "**Genre Compliance Validation Skipped** + +Genre: {genre} (low complexity) + +**Proceeding to next validation check...**" + +Without delay, read fully and follow: {nextStepFile} + +### 6. Report Compliance Findings (Medium/High-Complexity Genres) + +Append to validation report: + +```markdown +## Genre Compliance Validation + +**Genre:** {genre} +**Complexity:** {Medium/High} + +### Required Special Sections + +**{Section 1 Name}:** [Present/Missing/Adequate] +{If missing or inadequate: Note specific gaps} + +**{Section 2 Name}:** [Present/Missing/Adequate] +{If missing or inadequate: Note specific gaps} + +[Continue for all required sections from CSV for this genre] + +### Compliance Matrix + +| Requirement | Status | Notes | +|-------------|--------|-------| +| {Requirement 1} | [Met/Partial/Missing] | {Notes} | +| {Requirement 2} | [Met/Partial/Missing] | {Notes} | +[... continue for all requirements] + +### Summary + +**Required Sections Present:** {count}/{total} +**Compliance Gaps:** {count} + +**Severity:** [Critical if missing genre-critical sections (e.g., RPG without stat system, Fighting without frame data), Warning if incomplete, Pass if complete] + +**Recommendation:** +[If Critical] "GDD is missing genre-critical sections for {genre}. These conventions aren't optional - players and downstream phases expect them." +[If Warning] "Some genre-specific sections are incomplete. Strengthen documentation for full compliance with genre expectations." +[If Pass] "All required genre sections are present and adequately documented." +``` + +### 7. Display Progress and Auto-Proceed + +Display: "**Genre Compliance Validation Complete** + +Genre: {genre} ({complexity}) +Compliance Status: {status} + +**Proceeding to next validation check...**" + +Without delay, read fully and follow: {nextStepFile} (step-v-09-game-type-validation.md) + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- Genre classification extracted correctly (from frontmatter or inferred from signals) +- Complexity assessed appropriately +- Low complexity genres: Skipped with clear "N/A" documentation +- Medium/high complexity genres: All required sections checked +- Compliance matrix built with status for each requirement +- Severity assessed correctly +- Findings reported to validation report +- Auto-proceeds to next validation step +- Subprocess attempted with graceful degradation + +### ❌ SYSTEM FAILURE: + +- Not checking genre classification before proceeding +- Performing detailed checks on low complexity genres +- For high complexity: missing required section checks +- Not building compliance matrix +- Not reporting findings to validation report +- Not auto-proceeding + +**Master Rule:** Genre compliance is conditional. High-complexity genres carry conventions that must be documented - missing them surfaces as emergencies during production. diff --git a/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-09-game-type-validation.md b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-09-game-type-validation.md new file mode 100644 index 0000000..081d09f --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-09-game-type-validation.md @@ -0,0 +1,281 @@ +--- +name: 'step-v-09-game-type-validation' +description: 'Game-Type Compliance Validation - Validate the GDD game-type field matches content and genre-specific sections are present' + +# File references (ONLY variables used in this step) +nextStepFile: './step-v-10-smart-validation.md' +gddFile: '{gdd_file_path}' +gddFrontmatter: '{gdd_frontmatter}' +validationReportPath: '{validation_report_path}' +gameTypesData: '{module_root}/workflows/2-design/gds-create-gdd/game-types.csv' +--- + +# Step V-9: Game-Type Compliance Validation + +## STEP GOAL: + +Validate that the GDD's declared game-type matches its actual content, and that any game-type-specific sections expected by the gds-create-gdd schema are present. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and Quality Assurance Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in systematic validation, not collaborative dialogue +- ✅ You bring game-type expertise and schema knowledge +- ✅ This step runs autonomously - no user input needed + +### Step-Specific Rules: + +- 🎯 Focus ONLY on game-type compliance +- 🚫 FORBIDDEN to validate other aspects in this step +- 💬 Approach: Validate declared game-type matches content, required game-type sections present +- 🚪 This is a validation sequence step - auto-proceeds when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Check classification.gameType from GDD frontmatter +- 🎯 Validate declared game-type is a known id in game-types.csv +- 🎯 Validate that actual GDD content matches the declared game-type (cross-check against CSV signals) +- 🎯 Validate game-type-specific sections are present +- 💾 Append compliance findings to validation report +- 📖 Display "Proceeding to next check..." and load next step +- 🚫 FORBIDDEN to pause or request user input + +## CONTEXT BOUNDARIES: + +- Available context: GDD file with frontmatter classification, validation report +- Focus: Game-type compliance only +- Limits: Don't validate other aspects, don't pause for user input +- Dependencies: Steps 2-8 completed - genre and requirements validation done + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Load Game Types Data + +Load and read the complete file at: +`{gameTypesData}` ({module_root}/workflows/2-design/gds-create-gdd/game-types.csv) + +This CSV is the canonical game-type taxonomy used by `gds-create-gdd`. It contains: + +- `id` - the canonical game-type identifier (e.g., `rpg`, `action-platformer`, `roguelike`) +- `name` - human-readable name +- `description` - one-line description +- `genre_tags` - comma-separated genre tags / signals +- `fragment_file` - the game-type-specific section fragment that gds-create-gdd injects + +Internalize this data - it drives what counts as a valid game-type and what content signals map to each type. + +### 2. Extract Game-Type Classification + +From GDD frontmatter, extract: + +- `classification.gameType` - what game-type is declared? + +**Common game types (from game-types.csv):** +action-platformer, rpg, puzzle, strategy, shooter, adventure, simulation, roguelike, moba, fighting, racing, sports, survival, horror, idle-incremental, card-game, tower-defense, metroidvania, visual-novel, rhythm, turn-based-tactics, sandbox, text-based, party-game + +**If no gameType classification found:** +Note "Unclassified" and proceed to infer from content in the next step. + +### 3. Validate Declared Game-Type Is Known + +**Check:** + +- Is the declared gameType an `id` in game-types.csv? (Yes/No) +- If not, is it a recognizable alias for a known id? (e.g., "fps" → shooter) + +**If unknown game-type:** +Flag as "Unknown game-type" - GDD should use a canonical id from game-types.csv, or propose an extension. + +### 4. Cross-Check Declared Game-Type Against Content + +**For the declared game-type:** + +- Load its `genre_tags` from game-types.csv +- Scan the GDD for these tags / signals +- Measure match strength: Strong / Moderate / Weak / None + +**Also scan for signals from OTHER game-types:** + +- Which other game-types' signals appear in the GDD? +- If another game-type shows stronger signals than the declared one, flag a mismatch + +### 5. Validate Game-Type-Specific Sections + +**Based on the declared game-type, check for the expected game-type-specific content:** + +The gds-create-gdd schema injects `{{GAME_TYPE_SPECIFIC_SECTIONS}}` based on the selected game-type. Each fragment (named per game-types.csv `fragment_file`) contributes a specific block. Verify the GDD contains content appropriate to that fragment: + +- **action-platformer:** Movement feel values, combat specifics +- **rpg:** Stat system details, leveling/progression curve, inventory rules +- **puzzle:** Solution-space rules, hint system, difficulty ramp +- **strategy:** Unit taxonomy, economy tempo, AI design +- **shooter:** Weapon feel table, netcode model (if multiplayer), hitreg model +- **adventure:** Narrative structure, puzzle fairness, pacing +- **simulation:** Systems map, balance for long sessions +- **roguelike:** Run structure, meta-progression rules, seed determinism +- **moba:** Hero kit matrix, map/lane pacing, matchmaking +- **fighting:** Frame data tables, netcode, input spec +- **racing:** Vehicle handling, track design, AI driver +- **sports:** Rule modeling, physics spec, career mode +- **survival:** Resource economy, crafting tree, threat pacing +- **horror:** Atmosphere design, scare pacing, resource scarcity +- **idle-incremental:** Progression pacing, prestige model +- **card-game:** Card-pool balance, economy, draw rules +- **tower-defense:** Wave pacing, tower taxonomy, economy per wave +- **metroidvania:** Gating graph, map design, upgrade pacing +- **visual-novel:** Branching structure, flag system, save model +- **rhythm:** Timing windows, latency calibration, chart pipeline +- **turn-based-tactics:** Grid rules, action economy, enemy AI +- **sandbox:** Creative tools, performance at scale, UGC pipeline +- **text-based:** Parser vs choice, world state, save model +- **party-game:** Minigame roster, local MP model, round pacing + +### 6. Attempt Sub-Process Validation + +"Perform game-type compliance validation for {gameType}: + +**Validate declared game-type is known:** + +- Present in game-types.csv? {yes/no} + +**Cross-check declared game-type against content signals:** + +- Content signals match declared type: {Strong/Moderate/Weak/None} +- Signals from other game-types detected: {list} +- Mismatch detected: {yes/no} + +**Check that required game-type-specific sections are present:** +{List required sections for this game-type} +For each: Is it present in GDD? Is it adequately documented? + +Build compliance table showing: + +- Declared game-type validity +- Content-signal match strength +- Required sections: [Present/Missing/Incomplete] + +Return compliance table with findings." + +**Graceful degradation (if no Task tool):** + +- Manually check declared game-type against game-types.csv +- Manually scan for content signals +- Manually check GDD for required game-type-specific sections +- Build compliance table + +### 7. Build Compliance Table + +**Game-type declaration:** + +- Declared type: {value} +- Valid per game-types.csv: {yes/no} + +**Content alignment:** + +- Match strength to declared type: {Strong/Moderate/Weak/None} +- Other game-types with stronger signals: {list} + +**Required sections check:** + +- For each required section: Present / Missing / Incomplete +- Count: Required sections present vs total required + +**Total compliance score:** + +- Required: {present}/{total} +- Declaration valid: {yes/no} +- Content aligned: {yes/no} + +### 8. Report Game-Type Compliance Findings to Validation Report + +Append to validation report: + +```markdown +## Game-Type Compliance Validation + +**Declared Game-Type:** {gameType} +**Valid per game-types.csv:** [Yes/No] +**Content Alignment:** [Strong/Moderate/Weak/None] + +### Required Game-Type-Specific Sections + +**{Section 1}:** [Present/Missing/Incomplete] +{If missing or incomplete: Note specific gaps} + +**{Section 2}:** [Present/Missing/Incomplete] +{If missing or incomplete: Note specific gaps} + +[Continue for all required sections] + +### Content-Signal Analysis + +**Signals matching declared type:** {list/count} +**Signals suggesting other game-types:** {list with types} + +### Compliance Summary + +**Game-Type Declaration:** {Valid/Invalid/Missing} +**Content Alignment:** {Strong/Moderate/Weak/None} +**Required Sections Present:** {present}/{total} +**Compliance Score:** {percentage}% + +**Severity:** [Critical if game-type is invalid/missing OR content mismatch is Weak/None OR required sections missing, Warning if incomplete, Pass if complete] + +**Recommendation:** +[If Critical] "GDD's game-type declaration or game-type-specific sections have significant issues. Either update the gameType to match the actual content, or add the missing game-type-specific sections from gds-create-gdd." +[If Warning] "Some game-type-specific sections are incomplete. Strengthen documentation." +[If Pass] "Game-type is correctly declared and required sections are present." +``` + +### 9. Display Progress and Auto-Proceed + +Display: "**Game-Type Compliance Validation Complete** + +Game-Type: {gameType} +Compliance: {score}% + +**Proceeding to next validation check...**" + +Without delay, read fully and follow: {nextStepFile} (step-v-10-smart-validation.md) + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- Game-type extracted correctly (or flagged missing) +- Declared game-type validated against game-types.csv +- Content cross-checked against declared game-type +- Required game-type-specific sections validated +- Compliance table built with status +- Severity assessed correctly +- Findings reported to validation report +- Auto-proceeds to next validation step +- Subprocess attempted with graceful degradation + +### ❌ SYSTEM FAILURE: + +- Not checking game-type before proceeding +- Not loading game-types.csv +- Missing content-signal cross-check +- Missing required section checks +- Not building compliance table +- Not reporting findings to validation report +- Not auto-proceeding + +**Master Rule:** The declared game-type must match the actual GDD content, and each game-type carries its own required sections. Mismatches or missing sections surface as integration problems later. diff --git a/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-10-smart-validation.md b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-10-smart-validation.md new file mode 100644 index 0000000..9064e1e --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-10-smart-validation.md @@ -0,0 +1,224 @@ +--- +name: 'step-v-10-smart-validation' +description: 'SMART Design-Goals Validation - Validate design goals meet SMART quality criteria' + +# File references (ONLY variables used in this step) +nextStepFile: './step-v-11-holistic-quality-validation.md' +gddFile: '{gdd_file_path}' +validationReportPath: '{validation_report_path}' +--- + +# Step V-10: SMART Design-Goals Validation + +## STEP GOAL: + +Validate that design goals (success metrics, retention hooks, completion targets, win-condition definitions) meet SMART quality criteria (Specific, Measurable, Attainable, Relevant, Traceable), ensuring goals are testable rather than aspirational. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and Quality Assurance Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in systematic validation, not collaborative dialogue +- ✅ You bring design-engineering expertise and quality assessment +- ✅ This step runs autonomously - no user input needed + +### Step-Specific Rules: + +- 🎯 Focus ONLY on design-goal quality using the SMART framework +- 🚫 FORBIDDEN to validate other aspects in this step +- 💬 Approach: Score each design goal on SMART criteria (1-5 scale) +- 🚪 This is a validation sequence step - auto-proceeds when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Extract all design goals from GDD (Success Metrics, design pillars outcomes, retention hooks, win conditions) +- 🎯 Score each on SMART criteria (Specific, Measurable, Attainable, Relevant, Traceable) +- 💾 Flag goals with score < 3 in any category +- 📖 Append scoring table and suggestions to validation report +- 📖 Display "Proceeding to next check..." and load next step +- 🚫 FORBIDDEN to pause or request user input + +## CONTEXT BOUNDARIES: + +- Available context: GDD file, validation report +- Focus: Design-goal quality assessment only using SMART framework +- Limits: Don't re-validate mechanics or other aspects, don't pause for user input +- Dependencies: Steps 2-9 completed - comprehensive validation checks done + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Extract All Design Goals + +From the GDD, extract all design goals: + +- Success Metrics entries (Technical Metrics + Gameplay Metrics) +- Retention hooks or engagement targets +- Completion-rate targets +- Win-condition definitions tied to measurable outcomes +- Any explicit design goals from Goals and Context + +Identify each goal with a stable handle (DG-001, DG-002, etc. if none exist) and count total. + +### 2. Attempt Sub-Process Validation + +**Try to use Task tool to spawn a subprocess:** + +"Perform SMART validation on these design goals: + +{List all design goals} + +**For each design goal, score on SMART criteria (1-5 scale):** + +**Specific (1-5):** + +- 5: Clear, unambiguous target (e.g., 'Act 1 completion rate ≥ 60%') +- 3: Somewhat clear but could be more specific +- 1: Vague or aspirational (e.g., 'players enjoy the game') + +**Measurable (1-5):** + +- 5: Concrete metric with measurement method (telemetry, playtest, profiler) +- 3: Partially measurable (metric named but method unclear) +- 1: Not measurable, subjective + +**Attainable (1-5):** + +- 5: Realistic for team, genre, and target platform +- 3: Probably achievable but uncertain +- 1: Unrealistic (e.g., 'retention equal to live-service AAA') + +**Relevant (1-5):** + +- 5: Clearly ties to a pillar or the core fantasy +- 3: Somewhat relevant but link unclear +- 1: Not relevant, doesn't align with pillars + +**Traceable (1-5):** + +- 5: Clearly traces to a pillar, player experience goal, or business objective +- 3: Partially traceable +- 1: Orphan goal, no clear source + +**For each goal with score < 3 in any category:** + +- Provide specific improvement suggestions + +Return scoring table with all goal scores and improvement suggestions for low-scoring entries." + +**Graceful degradation (if no Task tool):** + +- Manually score each design goal on SMART criteria +- Note goals with low scores +- Provide improvement suggestions + +### 3. Build Scoring Table + +For each design goal: + +- Goal handle +- Specific score (1-5) +- Measurable score (1-5) +- Attainable score (1-5) +- Relevant score (1-5) +- Traceable score (1-5) +- Average score +- Flag if any category < 3 + +**Calculate overall design-goal quality:** + +- Percentage of goals with all scores ≥ 3 +- Percentage of goals with all scores ≥ 4 +- Average score across all goals and categories + +### 4. Report SMART Findings to Validation Report + +Append to validation report: + +```markdown +## SMART Design-Goals Validation + +**Total Design Goals:** {count} + +### Scoring Summary + +**All scores ≥ 3:** {percentage}% ({count}/{total}) +**All scores ≥ 4:** {percentage}% ({count}/{total}) +**Overall Average Score:** {average}/5.0 + +### Scoring Table + +| Goal # | Specific | Measurable | Attainable | Relevant | Traceable | Average | Flag | +|--------|----------|------------|------------|----------|-----------|---------|------| +| DG-001 | {s1} | {m1} | {a1} | {r1} | {t1} | {avg1} | {X if any <3} | +| DG-002 | {s2} | {m2} | {a2} | {r2} | {t2} | {avg2} | {X if any <3} | +[Continue for all goals] + +**Legend:** 1=Poor, 3=Acceptable, 5=Excellent +**Flag:** X = Score < 3 in one or more categories + +### Improvement Suggestions + +**Low-Scoring Goals:** + +**DG-{number}:** {specific suggestion for improvement} +[For each goal with score < 3 in any category] + +### Overall Assessment + +**Severity:** [Critical if >30% flagged goals, Warning if 10-30%, Pass if <10%] + +**Recommendation:** +[If Critical] "Many design goals are aspirational rather than testable. A goal without numbers and a measurement method is a wish. Revise flagged goals using the SMART framework." +[If Warning] "Some design goals would benefit from SMART refinement. Focus on flagged goals above." +[If Pass] "Design goals demonstrate good SMART quality overall." +``` + +### 5. Display Progress and Auto-Proceed + +Display: "**SMART Design-Goals Validation Complete** + +Design-Goal Quality: {percentage}% with acceptable scores ({severity}) + +**Proceeding to next validation check...**" + +Without delay, read fully and follow: {nextStepFile} (step-v-11-holistic-quality-validation.md) + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- All design goals extracted from GDD +- Each goal scored on all 5 SMART criteria (1-5 scale) +- Goals with scores < 3 flagged for improvement +- Improvement suggestions provided for low-scoring goals +- Scoring table built with all scores +- Overall quality assessment calculated +- Findings reported to validation report +- Auto-proceeds to next validation step +- Subprocess attempted with graceful degradation + +### ❌ SYSTEM FAILURE: + +- Not scoring all design goals on all SMART criteria +- Missing improvement suggestions for low-scoring goals +- Not building scoring table +- Not calculating overall quality metrics +- Not reporting findings to validation report +- Not auto-proceeding + +**Master Rule:** Design goals should be testable, not aspirational. The SMART framework provides an objective quality measure for design intent. diff --git a/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-11-holistic-quality-validation.md b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-11-holistic-quality-validation.md new file mode 100644 index 0000000..f64dc7a --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-11-holistic-quality-validation.md @@ -0,0 +1,278 @@ +--- +name: 'step-v-11-holistic-quality-validation' +description: 'Holistic Quality Assessment - Assess the GDD as a cohesive, compelling design document' + +# File references (ONLY variables used in this step) +nextStepFile: './step-v-12-completeness-validation.md' +gddFile: '{gdd_file_path}' +validationReportPath: '{validation_report_path}' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +--- + +# Step V-11: Holistic Quality Assessment + +## STEP GOAL: + +Assess the GDD as a cohesive, compelling design document - evaluating document flow, dual-audience effectiveness (game designers and LLMs), BMAD GDD principles compliance, and overall quality rating. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and Quality Assurance Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in systematic validation, not collaborative dialogue +- ✅ You bring analytical rigor and document-quality expertise +- ✅ This step runs autonomously - no user input needed +- ✅ Uses Advanced Elicitation for multi-perspective evaluation + +### Step-Specific Rules: + +- 🎯 Focus ONLY on holistic document quality assessment +- 🚫 FORBIDDEN to validate individual components (done in previous steps) +- 💬 Approach: Multi-perspective evaluation using Advanced Elicitation +- 🚪 This is a validation sequence step - auto-proceeds when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Use Advanced Elicitation for multi-perspective assessment +- 🎯 Evaluate document flow, dual audience, BMAD GDD principles +- 💾 Append comprehensive assessment to validation report +- 📖 Display "Proceeding to next check..." and load next step +- 🚫 FORBIDDEN to pause or request user input + +## CONTEXT BOUNDARIES: + +- Available context: Complete GDD file, validation report with findings from steps 1-10 +- Focus: Holistic quality - the WHOLE document +- Limits: Don't re-validate individual components, don't pause for user input +- Dependencies: Steps 1-10 completed - all systematic checks done + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Attempt Sub-Process with Advanced Elicitation + +**Try to use Task tool to spawn a subprocess using Advanced Elicitation:** + +"Perform holistic quality assessment on this GDD using multi-perspective evaluation: + +**Read fully and follow the Advanced Elicitation workflow:** +{advancedElicitationTask} + +**Evaluate the GDD from these perspectives:** + +**1. Document Flow & Coherence:** + +- Read entire GDD +- Evaluate narrative flow - does it tell a cohesive design story? +- Check transitions from vision → pillars → loop → mechanics → epics +- Assess consistency - is the game clear and coherent throughout? +- Evaluate readability - is it clear and well-organized for both designers and engineers? + +**2. Dual Audience Effectiveness:** + +**For Humans:** + +- Producer / lead clarity: Can leads understand pillars and scope quickly? +- Designer clarity: Do designers have clear mechanics to iterate on? +- Engineer clarity: Do engineers understand what they need to build? +- Playtest / QA clarity: Can QA see what the game is and what success looks like? + +**For LLMs:** + +- Machine-readable structure: Is the GDD structured for LLM consumption? +- Architecture readiness: Can an LLM generate an architecture from this? +- Epic/Story readiness: Can an LLM break this into epics and stories? +- Playtest-plan readiness: Can an LLM produce a playtest plan from this? + +**3. BMAD GDD Principles Compliance:** + +- Information density: Every sentence carries design weight? +- Measurability: Mechanics, goals, tech specs testable with numbers? +- Traceability: Mechanics trace to pillars, epics trace to mechanics? +- Genre awareness: Genre-specific sections included? +- Zero anti-patterns: No pitch-deck language or engine leakage? +- Dual audience: Works for both designers and LLMs? +- Markdown format: Proper structure and formatting? + +**4. Overall Quality Rating:** +Rate the GDD on 5-point scale: + +- Excellent (5/5): Exemplary, ready for architecture and production +- Good (4/5): Strong with minor improvements needed +- Adequate (3/5): Acceptable but needs refinement +- Needs Work (2/5): Significant gaps or issues +- Problematic (1/5): Major flaws, needs substantial revision + +**5. Top 3 Improvements:** +Identify the 3 most impactful improvements to make this a great GDD + +Return comprehensive assessment with all perspectives, rating, and top 3 improvements." + +**Graceful degradation (if no Task tool or Advanced Elicitation unavailable):** + +- Perform holistic assessment directly in current context +- Read complete GDD +- Evaluate document flow, coherence, transitions +- Assess dual audience effectiveness +- Check BMAD GDD principles compliance +- Assign overall quality rating +- Identify top 3 improvements + +### 2. Synthesize Assessment + +**Compile findings from multi-perspective evaluation:** + +**Document Flow & Coherence:** + +- Overall assessment: [Excellent/Good/Adequate/Needs Work/Problematic] +- Key strengths: [list] +- Key weaknesses: [list] + +**Dual Audience Effectiveness:** + +- For Humans: [assessment] +- For LLMs: [assessment] +- Overall dual audience score: [1-5] + +**BMAD GDD Principles Compliance:** + +- Principles met: [count]/7 +- Principles with issues: [list] + +**Overall Quality Rating:** [1-5 with label] + +**Top 3 Improvements:** + +1. [Improvement 1] +2. [Improvement 2] +3. [Improvement 3] + +### 3. Report Holistic Quality Findings to Validation Report + +Append to validation report: + +```markdown +## Holistic Quality Assessment + +### Document Flow & Coherence + +**Assessment:** [Excellent/Good/Adequate/Needs Work/Problematic] + +**Strengths:** +{List key strengths} + +**Areas for Improvement:** +{List key weaknesses} + +### Dual Audience Effectiveness + +**For Humans (Designers, Producers, Engineers, QA):** + +- Producer / lead clarity: [assessment] +- Designer clarity: [assessment] +- Engineer clarity: [assessment] +- Playtest / QA clarity: [assessment] + +**For LLMs:** + +- Machine-readable structure: [assessment] +- Architecture readiness: [assessment] +- Epic/Story readiness: [assessment] +- Playtest-plan readiness: [assessment] + +**Dual Audience Score:** {score}/5 + +### BMAD GDD Principles Compliance + +| Principle | Status | Notes | +|-----------|--------|-------| +| Information Density | [Met/Partial/Not Met] | {notes} | +| Measurability | [Met/Partial/Not Met] | {notes} | +| Traceability | [Met/Partial/Not Met] | {notes} | +| Genre Awareness | [Met/Partial/Not Met] | {notes} | +| Zero Anti-Patterns | [Met/Partial/Not Met] | {notes} | +| Dual Audience | [Met/Partial/Not Met] | {notes} | +| Markdown Format | [Met/Partial/Not Met] | {notes} | + +**Principles Met:** {count}/7 + +### Overall Quality Rating + +**Rating:** {rating}/5 - {label} + +**Scale:** + +- 5/5 - Excellent: Exemplary, ready for architecture and production +- 4/5 - Good: Strong with minor improvements needed +- 3/5 - Adequate: Acceptable but needs refinement +- 2/5 - Needs Work: Significant gaps or issues +- 1/5 - Problematic: Major flaws, needs substantial revision + +### Top 3 Improvements + +1. **{Improvement 1}** + {Brief explanation of why and how} + +2. **{Improvement 2}** + {Brief explanation of why and how} + +3. **{Improvement 3}** + {Brief explanation of why and how} + +### Summary + +**This GDD is:** {one-sentence overall assessment} + +**To make it great:** Focus on the top 3 improvements above. +``` + +### 4. Display Progress and Auto-Proceed + +Display: "**Holistic Quality Assessment Complete** + +Overall Rating: {rating}/5 - {label} + +**Proceeding to final validation checks...**" + +Without delay, read fully and follow: {nextStepFile} (step-v-12-completeness-validation.md) + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- Advanced Elicitation used for multi-perspective evaluation (or graceful degradation) +- Document flow & coherence assessed +- Dual audience effectiveness evaluated (humans and LLMs) +- BMAD GDD principles compliance checked +- Overall quality rating assigned (1-5 scale) +- Top 3 improvements identified +- Comprehensive assessment reported to validation report +- Auto-proceeds to next validation step +- Subprocess attempted with graceful degradation + +### ❌ SYSTEM FAILURE: + +- Not using Advanced Elicitation for multi-perspective evaluation +- Missing document flow assessment +- Missing dual audience evaluation +- Not checking all BMAD GDD principles +- Not assigning overall quality rating +- Missing top 3 improvements +- Not reporting comprehensive assessment to validation report +- Not auto-proceeding + +**Master Rule:** This evaluates the WHOLE document, not just components. Answers "Is this a good GDD?" and "What would make it great?" diff --git a/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-12-completeness-validation.md b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-12-completeness-validation.md new file mode 100644 index 0000000..ad4e6c6 --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-12-completeness-validation.md @@ -0,0 +1,291 @@ +--- +name: 'step-v-12-completeness-validation' +description: 'Completeness Check - Final comprehensive completeness check before report generation' + +# File references (ONLY variables used in this step) +nextStepFile: './step-v-13-report-complete.md' +gddFile: '{gdd_file_path}' +gddFrontmatter: '{gdd_frontmatter}' +validationReportPath: '{validation_report_path}' +--- + +# Step V-12: Completeness Validation + +## STEP GOAL: + +Final comprehensive completeness check - validate no template variables remain, each section has required content, section-specific completeness is met, and frontmatter is properly populated. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and Quality Assurance Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in systematic validation, not collaborative dialogue +- ✅ You bring attention to detail and completeness verification +- ✅ This step runs autonomously - no user input needed + +### Step-Specific Rules: + +- 🎯 Focus ONLY on completeness verification +- 🚫 FORBIDDEN to validate quality (done in step 11) or other aspects +- 💬 Approach: Systematic checklist-style verification +- 🚪 This is a validation sequence step - auto-proceeds when complete + +## EXECUTION PROTOCOLS: + +- 🎯 Check template completeness (no variables remaining) +- 🎯 Validate content completeness (each section has required content) +- 🎯 Validate section-specific completeness +- 🎯 Validate frontmatter completeness +- 💾 Append completeness matrix to validation report +- 📖 Display "Proceeding to final step..." and load next step +- 🚫 FORBIDDEN to pause or request user input + +## CONTEXT BOUNDARIES: + +- Available context: Complete GDD file, frontmatter, validation report +- Focus: Completeness verification only (final gate) +- Limits: Don't assess quality, don't pause for user input +- Dependencies: Steps 1-11 completed - all validation checks done + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Attempt Sub-Process Validation + +**Try to use Task tool to spawn a subprocess:** + +"Perform completeness validation on this GDD - final gate check: + +**1. Template Completeness:** + +- Scan GDD for any remaining template variables +- Look for: {variable}, {{variable}}, {placeholder}, [placeholder], and any unfilled `{{GAME_TYPE_SPECIFIC_SECTIONS}}` token +- List any found with line numbers + +**2. Content Completeness:** + +- Executive Summary: Core concept, target audience, USPs present? +- Goals and Context: Goals and background present? +- Core Gameplay: Pillars, core loop, win/loss conditions present? +- Game Mechanics: Primary mechanics and controls present? +- Progression and Balance: Progression, difficulty, economy present? +- Level Design Framework: Level types and progression present? +- Art and Audio Direction: Art style and audio approach present? +- Technical Specifications: Performance targets and platform specs present? +- Development Epics: High-level epics present? +- Success Metrics: Technical and gameplay metrics present? +- Out of Scope: Explicit exclusions present? +- Assumptions and Dependencies: Listed? + +For each section: Is required content present? (Yes/No/Partial) + +**3. Section-Specific Completeness:** + +- Game Pillars: At least 3 distinct pillars? +- Core Gameplay Loop: Each loop step documented? +- Mechanics: Each primary mechanic has concrete values? +- Success Metrics: Each has a target value and measurement method? +- Epics: Each epic has scope and high-level stories? + +**4. Frontmatter Completeness:** + +- stepsCompleted: Populated? +- classification: Present (gameType, platforms, genreComplexity)? +- inputDocuments: Tracked? +- date: Present? + +Return completeness matrix with status for each check." + +**Graceful degradation (if no Task tool):** + +- Manually scan for template variables +- Manually check each section for required content +- Manually verify frontmatter fields +- Build completeness matrix + +### 2. Build Completeness Matrix + +**Template Completeness:** + +- Template variables found: count +- List if any found (including unfilled `{{GAME_TYPE_SPECIFIC_SECTIONS}}`) + +**Content Completeness by Section:** + +- Executive Summary: Complete / Incomplete / Missing +- Goals and Context: Complete / Incomplete / Missing +- Core Gameplay: Complete / Incomplete / Missing +- Game Mechanics: Complete / Incomplete / Missing +- Progression and Balance: Complete / Incomplete / Missing +- Level Design Framework: Complete / Incomplete / Missing +- Art and Audio Direction: Complete / Incomplete / Missing +- Technical Specifications: Complete / Incomplete / Missing +- Development Epics: Complete / Incomplete / Missing +- Success Metrics: Complete / Incomplete / Missing +- Out of Scope: Complete / Incomplete / Missing +- Assumptions and Dependencies: Complete / Incomplete / Missing + +**Section-Specific Completeness:** + +- Pillars: ≥3 distinct pillars / <3 / none +- Core loop: Each step documented / Partial / Missing +- Mechanics: Each has concrete values / Some do / None do +- Success Metrics: All have targets+methods / Some do / None do +- Epics: All have scope+stories / Some do / None do + +**Frontmatter Completeness:** + +- stepsCompleted: Present / Missing +- classification.gameType: Present / Missing +- classification.platforms: Present / Missing +- classification.genreComplexity: Present / Missing +- inputDocuments: Present / Missing +- date: Present / Missing + +**Overall completeness:** + +- Sections complete: X/Y +- Critical gaps: [list if any] + +### 3. Report Completeness Findings to Validation Report + +Append to validation report: + +```markdown +## Completeness Validation + +### Template Completeness + +**Template Variables Found:** {count} +{If count > 0, list variables with line numbers} +{If count = 0, note: No template variables remaining ✓} + +### Content Completeness by Section + +**Executive Summary:** [Complete/Incomplete/Missing] +{If incomplete or missing, note specific gaps} + +**Goals and Context:** [Complete/Incomplete/Missing] +{If incomplete or missing, note specific gaps} + +**Core Gameplay:** [Complete/Incomplete/Missing] +{If incomplete or missing, note specific gaps} + +**Game Mechanics:** [Complete/Incomplete/Missing] +{If incomplete or missing, note specific gaps} + +**Progression and Balance:** [Complete/Incomplete/Missing] +{If incomplete or missing, note specific gaps} + +**Level Design Framework:** [Complete/Incomplete/Missing] +{If incomplete or missing, note specific gaps} + +**Art and Audio Direction:** [Complete/Incomplete/Missing] +{If incomplete or missing, note specific gaps} + +**Technical Specifications:** [Complete/Incomplete/Missing] +{If incomplete or missing, note specific gaps} + +**Development Epics:** [Complete/Incomplete/Missing] +{If incomplete or missing, note specific gaps} + +**Success Metrics:** [Complete/Incomplete/Missing] +{If incomplete or missing, note specific gaps} + +**Out of Scope:** [Complete/Incomplete/Missing] +{If incomplete or missing, note specific gaps} + +**Assumptions and Dependencies:** [Complete/Incomplete/Missing] +{If incomplete or missing, note specific gaps} + +### Section-Specific Completeness + +**Game Pillars:** [≥3 / <3 / none] +{If fewer than 3, note which are weak or missing} + +**Core Gameplay Loop:** [All steps documented / Partial / Missing] +{If partial, note missing steps} + +**Mechanics Concrete Values:** [All / Some / None] have concrete values +{If Some or None, note which mechanics lack values} + +**Success Metrics Target+Method:** [All / Some / None] have both +{If Some or None, note which metrics are incomplete} + +**Epics Scope+Stories:** [All / Some / None] have both +{If Some or None, note which epics are incomplete} + +### Frontmatter Completeness + +**stepsCompleted:** [Present/Missing] +**classification.gameType:** [Present/Missing] +**classification.platforms:** [Present/Missing] +**classification.genreComplexity:** [Present/Missing] +**inputDocuments:** [Present/Missing] +**date:** [Present/Missing] + +**Frontmatter Completeness:** {complete_fields}/6 + +### Completeness Summary + +**Overall Completeness:** {percentage}% ({complete_sections}/{total_sections}) + +**Critical Gaps:** [count] [list if any] +**Minor Gaps:** [count] [list if any] + +**Severity:** [Critical if template variables remain or critical sections missing, Warning if minor gaps, Pass if complete] + +**Recommendation:** +[If Critical] "GDD has completeness gaps that must be addressed before use. Fix template variables and complete missing sections." +[If Warning] "GDD has minor completeness gaps. Address them for complete documentation." +[If Pass] "GDD is complete with all required sections and content present." +``` + +### 4. Display Progress and Auto-Proceed + +Display: "**Completeness Validation Complete** + +Overall Completeness: {percentage}% ({severity}) + +**Proceeding to final step...**" + +Without delay, read fully and follow: {nextStepFile} (step-v-13-report-complete.md) + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- Scanned for template variables systematically (including unfilled GAME_TYPE_SPECIFIC_SECTIONS) +- Validated each section for required content +- Validated section-specific completeness (pillars, loop, mechanics values, metrics, epics) +- Validated frontmatter completeness +- Completeness matrix built with all checks +- Severity assessed correctly +- Findings reported to validation report +- Auto-proceeds to final step +- Subprocess attempted with graceful degradation + +### ❌ SYSTEM FAILURE: + +- Not scanning for template variables +- Missing section-specific completeness checks +- Not validating frontmatter +- Not building completeness matrix +- Not reporting findings to validation report +- Not auto-proceeding + +**Master Rule:** Final gate to ensure the document is complete before presenting findings. Template variables or critical gaps must be fixed before the GDD is usable downstream. diff --git a/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-13-report-complete.md b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-13-report-complete.md new file mode 100644 index 0000000..cc5e68d --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/steps-v/step-v-13-report-complete.md @@ -0,0 +1,257 @@ +--- +name: 'step-v-13-report-complete' +description: 'Validation Report Complete - Finalize report, summarize findings, present to user, offer next steps' + +# File references (ONLY variables used in this step) +validationReportPath: '{validation_report_path}' +gddFile: '{gdd_file_path}' +editWorkflow: 'skill:gds-edit-gdd' +helpWorkflow: 'skill:bmad-help' +--- + +# Step V-13: Validation Report Complete + +## STEP GOAL: + +Finalize the validation report, summarize all findings from steps 1-12, present the summary to the user conversationally, and offer actionable next steps. The report title prefix is "GDD Validation Report". + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- 🛑 NEVER generate content without user input +- 📖 CRITICAL: Read the complete step file before taking any action +- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read +- 📋 YOU ARE A FACILITATOR, not a content generator +- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` +- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}` + +### Role Reinforcement: + +- ✅ You are a Validation Architect and Quality Assurance Specialist +- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role +- ✅ We engage in collaborative dialogue, not command-response +- ✅ You bring synthesis and summary expertise +- ✅ This is the FINAL step - requires user interaction + +### Step-Specific Rules: + +- 🎯 Focus ONLY on summarizing findings and presenting options +- 🚫 FORBIDDEN to perform additional validation +- 💬 Approach: Conversational summary with clear next steps +- 🚪 This is the final step - no next step after this + +## EXECUTION PROTOCOLS: + +- 🎯 Load complete validation report +- 🎯 Summarize all findings from steps 1-12 +- 🎯 Update report frontmatter with final status +- 💬 Present summary to user conversationally +- 💬 Offer menu options for next actions +- 🚫 FORBIDDEN to proceed without user selection + +## CONTEXT BOUNDARIES: + +- Available context: Complete validation report with findings from all validation steps +- Focus: Summary and presentation only (no new validation) +- Limits: Don't add new findings, just synthesize existing +- Dependencies: Steps 1-12 completed - all validation checks done + +## MANDATORY SEQUENCE + +**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change. + +### 1. Load Complete Validation Report + +Read the entire validation report from {validationReportPath} + +Extract all findings from: + +- Format Detection (Step 2) +- Parity Analysis (Step 2B, if applicable) +- Information Density (Step 3) +- Game Brief Coverage (Step 4) +- Measurability (Step 5) +- Traceability (Step 6) +- Implementation Leakage (Step 7) +- Genre Compliance (Step 8) +- Game-Type Compliance (Step 9) +- SMART Design-Goals (Step 10) +- Holistic Quality (Step 11) +- Completeness (Step 12) + +### 2. Update Report Frontmatter with Final Status + +Update validation report frontmatter: + +```yaml +--- +validationTarget: '{gdd_path}' +validationDate: '{current_date}' +inputDocuments: [list of documents] +validationStepsCompleted: + [ + 'step-v-01-discovery', + 'step-v-02-format-detection', + 'step-v-03-density-validation', + 'step-v-04-brief-coverage-validation', + 'step-v-05-measurability-validation', + 'step-v-06-traceability-validation', + 'step-v-07-implementation-leakage-validation', + 'step-v-08-genre-compliance-validation', + 'step-v-09-game-type-validation', + 'step-v-10-smart-validation', + 'step-v-11-holistic-quality-validation', + 'step-v-12-completeness-validation', + ] +validationStatus: COMPLETE +holisticQualityRating: '{rating from step 11}' +overallStatus: '{Pass/Warning/Critical based on all findings}' +--- +``` + +Also ensure the report body's main heading is `# GDD Validation Report` (prefix "GDD Validation Report" as required). + +### 3. Create Summary of Findings + +**Overall Status:** + +- Determine from all validation findings +- **Pass:** All critical checks pass, minor warnings acceptable +- **Warning:** Some issues found but GDD is usable +- **Critical:** Major issues that prevent GDD from being fit for purpose + +**Quick Results Table:** + +- Format: [classification] +- Information Density: [severity] +- Measurability: [severity] +- Traceability: [severity] +- Implementation Leakage: [severity] +- Genre Compliance: [status] +- Game-Type Compliance: [compliance score] +- SMART Design-Goals: [percentage] +- Holistic Quality: [rating/5] +- Completeness: [percentage] + +**Critical Issues:** List from all validation steps +**Warnings:** List from all validation steps +**Strengths:** List positives from all validation steps + +**Holistic Quality Rating:** From step 11 +**Top 3 Improvements:** From step 11 + +**Recommendation:** Based on overall status + +### 4. Present Summary to User Conversationally + +Display: + +"**✓ GDD Validation Complete** + +**Overall Status:** {Pass/Warning/Critical} + +**Quick Results:** +{Present quick results table with key findings} + +**Critical Issues:** {count or "None"} +{If any, list briefly} + +**Warnings:** {count or "None"} +{If any, list briefly} + +**Strengths:** +{List key strengths} + +**Holistic Quality:** {rating}/5 - {label} + +**Top 3 Improvements:** + +1. {Improvement 1} +2. {Improvement 2} +3. {Improvement 3} + +**Recommendation:** +{Based on overall status: + +- Pass: "GDD is in good shape. Address minor improvements to make it great." +- Warning: "GDD is usable but has issues that should be addressed. Review warnings and improve where needed." +- Critical: "GDD has significant issues that should be fixed before use. Focus on critical issues above."} + +**What would you like to do next?**" + +### 5. Present MENU OPTIONS + +Display: + +**[R] Review Detailed Findings** - Walk through validation report section by section +**[E] Use Edit Workflow** - Hand off to `gds-edit-gdd` for systematic improvements using this report +**[F] Fix Simpler Items** - Immediate fixes for simple issues (anti-patterns, leakage, missing headers) +**[X] Exit** - Exit and Suggest Next Steps. + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- Only proceed based on user selection + +#### Menu Handling Logic: + +- **IF R (Review Detailed Findings):** + - Walk through validation report section by section + - Present findings from each validation step + - Allow user to ask questions + - After review, return to menu + +- **IF E (Use Edit Workflow):** + - Explain: "The `gds-edit-gdd` skill can use this validation report to systematically address issues. Edit mode will guide you through discovering what to edit, reviewing the GDD, and applying targeted improvements." + - Offer: "Would you like to launch Edit mode now? It will help you fix validation findings systematically." + - If yes: Invoke the `gds-edit-gdd` skill ({editWorkflow}) + - If no: Return to menu + +- **IF F (Fix Simpler Items):** + - Offer immediate fixes for: + - Template variables (fill in with appropriate content) + - Conversational filler and pitch-deck language (remove wordy phrases) + - Implementation / engine leakage (remove engine internals from mechanics and specs) + - Missing section headers (add ## headers) + - Ask: "Which simple fixes would you like me to make?" + - If user specifies fixes, make them and update validation report + - Return to menu + +- **IF X (Exit):** + - Display: "**Validation Report Saved:** {validationReportPath}" + - Display: "**Summary:** {overall status} - {recommendation}" + - GDD Validation complete. Invoke the `bmad-help` skill ({helpWorkflow}). + +- **IF Any other:** Help user, then redisplay menu + +--- + +## 🚨 SYSTEM SUCCESS/FAILURE METRICS + +### ✅ SUCCESS: + +- Complete validation report loaded successfully +- All findings from steps 1-12 summarized +- Report frontmatter updated with final status +- Report title confirmed as "GDD Validation Report" +- Overall status determined correctly (Pass/Warning/Critical) +- Quick results table presented +- Critical issues, warnings, and strengths listed +- Holistic quality rating included +- Top 3 improvements presented +- Clear recommendation provided +- Menu options presented with clear explanations +- User can review findings, hand off to edit workflow, or exit + +### ❌ SYSTEM FAILURE: + +- Not loading complete validation report +- Missing summary of findings +- Not updating report frontmatter +- Not using "GDD Validation Report" title +- Not determining overall status +- Missing menu options +- Unclear next steps + +**Master Rule:** User needs a clear summary and actionable next steps. The `gds-edit-gdd` workflow is best for complex issues; immediate fixes are available for simpler ones. diff --git a/src/workflows/2-design/gds-validate-gdd/workflow.md b/src/workflows/2-design/gds-validate-gdd/workflow.md new file mode 100644 index 0000000..b07d3cf --- /dev/null +++ b/src/workflows/2-design/gds-validate-gdd/workflow.md @@ -0,0 +1,63 @@ +--- +name: gds-validate-gdd +description: 'Validate a GDD against standards. Use when the user says "validate this GDD" or "run GDD validation".' +main_config: '{module_config}' +validateWorkflow: './steps-v/step-v-01-discovery.md' +--- + +# GDD Validate Workflow + +**Goal:** Validate existing Game Design Documents against BMAD GDS standards through comprehensive review. + +**Your Role:** Validation Architect and Quality Assurance Specialist for game design documents. + +You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description. + +## WORKFLOW ARCHITECTURE + +This uses **step-file architecture** for disciplined execution: + +### Core Principles + +- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly +- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so +- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed +- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document +- **Append-Only Building**: Build documents by appending content as directed to the output file + +### Step Processing Rules + +1. **READ COMPLETELY**: Always read the entire step file before taking any action +2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate +3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection +4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue) +5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step +6. **LOAD NEXT**: When directed, read fully and follow the next step file + +### Critical Rules (NO EXCEPTIONS) + +- 🛑 **NEVER** load multiple step files simultaneously +- 📖 **ALWAYS** read entire step file before execution +- 🚫 **NEVER** skip steps or optimize the sequence +- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step +- 🎯 **ALWAYS** follow the exact instructions in the step file +- ⏸️ **ALWAYS** halt at menus and wait for user input +- 📋 **NEVER** create mental todo lists from future steps + +## INITIALIZATION SEQUENCE + +### 1. Configuration Loading + +Load and read full config from {main_config} and resolve: + +- `project_name`, `output_folder`, `planning_artifacts`, `user_name` +- `communication_language`, `document_output_language`, `game_dev_experience` +- `date` as system-generated current datetime + +✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`. + +### 2. Route to Validate Workflow + +"**Validate Mode: Validating an existing GDD against BMAD GDS standards.**" + +Then read fully and follow: `{validateWorkflow}` (steps-v/step-v-01-discovery.md) diff --git a/src/workflows/2-design/gds-validate-prd/SKILL.md b/src/workflows/2-design/gds-validate-prd/SKILL.md new file mode 100644 index 0000000..0a4b5a4 --- /dev/null +++ b/src/workflows/2-design/gds-validate-prd/SKILL.md @@ -0,0 +1,6 @@ +--- +name: gds-validate-prd +description: 'Validate a PRD against standards for external tool compatibility. Use when the user says "validate this PRD" or "run PRD validation".' +--- + +Follow the instructions in ./workflow.md. diff --git a/src/workflows/2-design/gds-validate-prd/bmad-skill-manifest.yaml b/src/workflows/2-design/gds-validate-prd/bmad-skill-manifest.yaml new file mode 100644 index 0000000..d0f08ab --- /dev/null +++ b/src/workflows/2-design/gds-validate-prd/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/workflows/2-design/gds-validate-prd/data/domain-complexity.csv b/src/workflows/2-design/gds-validate-prd/data/domain-complexity.csv new file mode 100644 index 0000000..60a7b50 --- /dev/null +++ b/src/workflows/2-design/gds-validate-prd/data/domain-complexity.csv @@ -0,0 +1,15 @@ +domain,signals,complexity,key_concerns,required_knowledge,suggested_workflow,web_searches,special_sections +healthcare,"medical,diagnostic,clinical,FDA,patient,treatment,HIPAA,therapy,pharma,drug",high,"FDA approval;Clinical validation;HIPAA compliance;Patient safety;Medical device classification;Liability","Regulatory pathways;Clinical trial design;Medical standards;Data privacy;Integration requirements","domain-research","FDA software medical device guidance {date};HIPAA compliance software requirements;Medical software standards {date};Clinical validation software","clinical_requirements;regulatory_pathway;validation_methodology;safety_measures" +fintech,"payment,banking,trading,investment,crypto,wallet,transaction,KYC,AML,funds,fintech",high,"Regional compliance;Security standards;Audit requirements;Fraud prevention;Data protection","KYC/AML requirements;PCI DSS;Open banking;Regional laws (US/EU/APAC);Crypto regulations","domain-research","fintech regulations {date};payment processing compliance {date};open banking API standards;cryptocurrency regulations {date}","compliance_matrix;security_architecture;audit_requirements;fraud_prevention" +govtech,"government,federal,civic,public sector,citizen,municipal,voting",high,"Procurement rules;Security clearance;Accessibility (508);FedRAMP;Privacy;Transparency","Government procurement;Security frameworks;Accessibility standards;Privacy laws;Open data requirements","domain-research","government software procurement {date};FedRAMP compliance requirements;section 508 accessibility;government security standards","procurement_compliance;security_clearance;accessibility_standards;transparency_requirements" +edtech,"education,learning,student,teacher,curriculum,assessment,K-12,university,LMS",medium,"Student privacy (COPPA/FERPA);Accessibility;Content moderation;Age verification;Curriculum standards","Educational privacy laws;Learning standards;Accessibility requirements;Content guidelines;Assessment validity","domain-research","educational software privacy {date};COPPA FERPA compliance;WCAG education requirements;learning management standards","privacy_compliance;content_guidelines;accessibility_features;curriculum_alignment" +aerospace,"aircraft,spacecraft,aviation,drone,satellite,propulsion,flight,radar,navigation",high,"Safety certification;DO-178C compliance;Performance validation;Simulation accuracy;Export controls","Aviation standards;Safety analysis;Simulation validation;ITAR/export controls;Performance requirements","domain-research + technical-model","DO-178C software certification;aerospace simulation standards {date};ITAR export controls software;aviation safety requirements","safety_certification;simulation_validation;performance_requirements;export_compliance" +automotive,"vehicle,car,autonomous,ADAS,automotive,driving,EV,charging",high,"Safety standards;ISO 26262;V2X communication;Real-time requirements;Certification","Automotive standards;Functional safety;V2X protocols;Real-time systems;Testing requirements","domain-research","ISO 26262 automotive software;automotive safety standards {date};V2X communication protocols;EV charging standards","safety_standards;functional_safety;communication_protocols;certification_requirements" +scientific,"research,algorithm,simulation,modeling,computational,analysis,data science,ML,AI",medium,"Reproducibility;Validation methodology;Peer review;Performance;Accuracy;Computational resources","Scientific method;Statistical validity;Computational requirements;Domain expertise;Publication standards","technical-model","scientific computing best practices {date};research reproducibility standards;computational modeling validation;peer review software","validation_methodology;accuracy_metrics;reproducibility_plan;computational_requirements" +legaltech,"legal,law,contract,compliance,litigation,patent,attorney,court",high,"Legal ethics;Bar regulations;Data retention;Attorney-client privilege;Court system integration","Legal practice rules;Ethics requirements;Court filing systems;Document standards;Confidentiality","domain-research","legal technology ethics {date};law practice management software requirements;court filing system standards;attorney client privilege technology","ethics_compliance;data_retention;confidentiality_measures;court_integration" +insuretech,"insurance,claims,underwriting,actuarial,policy,risk,premium",high,"Insurance regulations;Actuarial standards;Data privacy;Fraud detection;State compliance","Insurance regulations by state;Actuarial methods;Risk modeling;Claims processing;Regulatory reporting","domain-research","insurance software regulations {date};actuarial standards software;insurance fraud detection;state insurance compliance","regulatory_requirements;risk_modeling;fraud_detection;reporting_compliance" +energy,"energy,utility,grid,solar,wind,power,electricity,oil,gas",high,"Grid compliance;NERC standards;Environmental regulations;Safety requirements;Real-time operations","Energy regulations;Grid standards;Environmental compliance;Safety protocols;SCADA systems","domain-research","energy sector software compliance {date};NERC CIP standards;smart grid requirements;renewable energy software standards","grid_compliance;safety_protocols;environmental_compliance;operational_requirements" +process_control,"industrial automation,process control,PLC,SCADA,DCS,HMI,operational technology,OT,control system,cyberphysical,MES,historian,instrumentation,I&C,P&ID",high,"Functional safety;OT cybersecurity;Real-time control requirements;Legacy system integration;Process safety and hazard analysis;Environmental compliance and permitting;Engineering authority and PE requirements","Functional safety standards;OT security frameworks;Industrial protocols;Process control architecture;Plant reliability and maintainability","domain-research + technical-model","IEC 62443 OT cybersecurity requirements {date};functional safety software requirements {date};industrial process control architecture;ISA-95 manufacturing integration","functional_safety;ot_security;process_requirements;engineering_authority" +building_automation,"building automation,BAS,BMS,HVAC,smart building,lighting control,fire alarm,fire protection,fire suppression,life safety,elevator,access control,DDC,energy management,sequence of operations,commissioning",high,"Life safety codes;Building energy standards;Multi-trade coordination and interoperability;Commissioning and ongoing operational performance;Indoor environmental quality and occupant comfort;Engineering authority and PE requirements","Building automation protocols;HVAC and mechanical controls;Fire alarm, fire protection, and life safety design;Commissioning process and sequence of operations;Building codes and energy standards","domain-research","smart building software architecture {date};BACnet integration best practices;building automation cybersecurity {date};ASHRAE building standards","life_safety;energy_compliance;commissioning_requirements;engineering_authority" +gaming,"game,player,gameplay,level,character,multiplayer,quest",redirect,"REDIRECT TO GAME WORKFLOWS","Game design","game-brief","NA","NA" +general,"",low,"Standard requirements;Basic security;User experience;Performance","General software practices","continue","software development best practices {date}","standard_requirements" \ No newline at end of file diff --git a/src/workflows/2-design/gds-validate-prd/data/prd-purpose.md b/src/workflows/2-design/gds-validate-prd/data/prd-purpose.md new file mode 100644 index 0000000..d8b334b --- /dev/null +++ b/src/workflows/2-design/gds-validate-prd/data/prd-purpose.md @@ -0,0 +1,197 @@ +# BMAD PRD Purpose + +**The PRD is the top of the required funnel that feeds all subsequent product development work in the BMad Method.** + +--- + +## What is a BMAD PRD? + +A dual-audience document serving: +1. **Human Product Managers and builders** - Vision, strategy, stakeholder communication +2. **LLM Downstream Consumption** - UX Design → Architecture → Epics → Development AI Agents + +Each successive document becomes more AI-tailored and granular. + +--- + +## Core Philosophy: Information Density + +**High Signal-to-Noise Ratio** + +Every sentence must carry information weight. LLMs consume precise, dense content efficiently. + +**Anti-Patterns (Eliminate These):** +- ❌ "The system will allow users to..." → ✅ "Users can..." +- ❌ "It is important to note that..." → ✅ State the fact directly +- ❌ "In order to..." → ✅ "To..." +- ❌ Conversational filler and padding → ✅ Direct, concise statements + +**Goal:** Maximum information per word. Zero fluff. + +--- + +## The Traceability Chain + +**PRD starts the chain:** +``` +Vision → Success Criteria → User Journeys → Functional Requirements → (future: User Stories) +``` + +**In the PRD, establish:** +- Vision → Success Criteria alignment +- Success Criteria → User Journey coverage +- User Journey → Functional Requirement mapping +- All requirements traceable to user needs + +**Why:** Each downstream artifact (UX, Architecture, Epics, Stories) must trace back to documented user needs and business objectives. This chain ensures we build the right thing. + +--- + +## What Makes Great Functional Requirements? + +### FRs are Capabilities, Not Implementation + +**Good FR:** "Users can reset their password via email link" +**Bad FR:** "System sends JWT via email and validates with database" (implementation leakage) + +**Good FR:** "Dashboard loads in under 2 seconds for 95th percentile" +**Bad FR:** "Fast loading time" (subjective, unmeasurable) + +### SMART Quality Criteria + +**Specific:** Clear, precisely defined capability +**Measurable:** Quantifiable with test criteria +**Attainable:** Realistic within constraints +**Relevant:** Aligns with business objectives +**Traceable:** Links to source (executive summary or user journey) + +### FR Anti-Patterns + +**Subjective Adjectives:** +- ❌ "easy to use", "intuitive", "user-friendly", "fast", "responsive" +- ✅ Use metrics: "completes task in under 3 clicks", "loads in under 2 seconds" + +**Implementation Leakage:** +- ❌ Technology names, specific libraries, implementation details +- ✅ Focus on capability and measurable outcomes + +**Vague Quantifiers:** +- ❌ "multiple users", "several options", "various formats" +- ✅ "up to 100 concurrent users", "3-5 options", "PDF, DOCX, TXT formats" + +**Missing Test Criteria:** +- ❌ "The system shall provide notifications" +- ✅ "The system shall send email notifications within 30 seconds of trigger event" + +--- + +## What Makes Great Non-Functional Requirements? + +### NFRs Must Be Measurable + +**Template:** +``` +"The system shall [metric] [condition] [measurement method]" +``` + +**Examples:** +- ✅ "The system shall respond to API requests in under 200ms for 95th percentile as measured by APM monitoring" +- ✅ "The system shall maintain 99.9% uptime during business hours as measured by cloud provider SLA" +- ✅ "The system shall support 10,000 concurrent users as measured by load testing" + +### NFR Anti-Patterns + +**Unmeasurable Claims:** +- ❌ "The system shall be scalable" → ✅ "The system shall handle 10x load growth through horizontal scaling" +- ❌ "High availability required" → ✅ "99.9% uptime as measured by cloud provider SLA" + +**Missing Context:** +- ❌ "Response time under 1 second" → ✅ "API response time under 1 second for 95th percentile under normal load" + +--- + +## Domain-Specific Requirements + +**Auto-Detect and Enforce Based on Project Context** + +Certain industries have mandatory requirements that must be present: + +- **Healthcare:** HIPAA Privacy & Security Rules, PHI encryption, audit logging, MFA +- **Fintech:** PCI-DSS Level 1, AML/KYC compliance, SOX controls, financial audit trails +- **GovTech:** NIST framework, Section 508 accessibility (WCAG 2.1 AA), FedRAMP, data residency +- **E-Commerce:** PCI-DSS for payments, inventory accuracy, tax calculation by jurisdiction + +**Why:** Missing these requirements in the PRD means they'll be missed in architecture and implementation, creating expensive rework. During PRD creation there is a step to cover this - during validation we want to make sure it was covered. For this purpose steps will utilize a domain-complexity.csv and project-types.csv. + +--- + +## Document Structure (Markdown, Human-Readable) + +### Required Sections +1. **Executive Summary** - Vision, differentiator, target users +2. **Success Criteria** - Measurable outcomes (SMART) +3. **Product Scope** - MVP, Growth, Vision phases +4. **User Journeys** - Comprehensive coverage +5. **Domain Requirements** - Industry-specific compliance (if applicable) +6. **Innovation Analysis** - Competitive differentiation (if applicable) +7. **Project-Type Requirements** - Platform-specific needs +8. **Functional Requirements** - Capability contract (FRs) +9. **Non-Functional Requirements** - Quality attributes (NFRs) + +### Formatting for Dual Consumption + +**For Humans:** +- Clear, professional language +- Logical flow from vision to requirements +- Easy for stakeholders to review and approve + +**For LLMs:** +- ## Level 2 headers for all main sections (enables extraction) +- Consistent structure and patterns +- Precise, testable language +- High information density + +--- + +## Downstream Impact + +**How the PRD Feeds Next Artifacts:** + +**UX Design:** +- User journeys → interaction flows +- FRs → design requirements +- Success criteria → UX metrics + +**Architecture:** +- FRs → system capabilities +- NFRs → architecture decisions +- Domain requirements → compliance architecture +- Project-type requirements → platform choices + +**Epics & Stories (created after architecture):** +- FRs → user stories (1 FR could map to 1-3 stories potentially) +- Acceptance criteria → story acceptance tests +- Priority → sprint sequencing +- Traceability → stories map back to vision + +**Development AI Agents:** +- Precise requirements → implementation clarity +- Test criteria → automated test generation +- Domain requirements → compliance enforcement +- Measurable NFRs → performance targets + +--- + +## Summary: What Makes a Great BMAD PRD? + +✅ **High Information Density** - Every sentence carries weight, zero fluff +✅ **Measurable Requirements** - All FRs and NFRs are testable with specific criteria +✅ **Clear Traceability** - Each requirement links to user need and business objective +✅ **Domain Awareness** - Industry-specific requirements auto-detected and included +✅ **Zero Anti-Patterns** - No subjective adjectives, implementation leakage, or vague quantifiers +✅ **Dual Audience Optimized** - Human-readable AND LLM-consumable +✅ **Markdown Format** - Professional, clean, accessible to all stakeholders + +--- + +**Remember:** The PRD is the foundation. Quality here ripples through every subsequent phase. A dense, precise, well-traced PRD makes UX design, architecture, epic breakdown, and AI development dramatically more effective. diff --git a/src/workflows/2-design/gds-validate-prd/data/project-types.csv b/src/workflows/2-design/gds-validate-prd/data/project-types.csv new file mode 100644 index 0000000..6f71c51 --- /dev/null +++ b/src/workflows/2-design/gds-validate-prd/data/project-types.csv @@ -0,0 +1,11 @@ +project_type,detection_signals,key_questions,required_sections,skip_sections,web_search_triggers,innovation_signals +api_backend,"API,REST,GraphQL,backend,service,endpoints","Endpoints needed?;Authentication method?;Data formats?;Rate limits?;Versioning?;SDK needed?","endpoint_specs;auth_model;data_schemas;error_codes;rate_limits;api_docs","ux_ui;visual_design;user_journeys","framework best practices;OpenAPI standards","API composition;New protocol" +mobile_app,"iOS,Android,app,mobile,iPhone,iPad","Native or cross-platform?;Offline needed?;Push notifications?;Device features?;Store compliance?","platform_reqs;device_permissions;offline_mode;push_strategy;store_compliance","desktop_features;cli_commands","app store guidelines;platform requirements","Gesture innovation;AR/VR features" +saas_b2b,"SaaS,B2B,platform,dashboard,teams,enterprise","Multi-tenant?;Permission model?;Subscription tiers?;Integrations?;Compliance?","tenant_model;rbac_matrix;subscription_tiers;integration_list;compliance_reqs","cli_interface;mobile_first","compliance requirements;integration guides","Workflow automation;AI agents" +developer_tool,"SDK,library,package,npm,pip,framework","Language support?;Package managers?;IDE integration?;Documentation?;Examples?","language_matrix;installation_methods;api_surface;code_examples;migration_guide","visual_design;store_compliance","package manager best practices;API design patterns","New paradigm;DSL creation" +cli_tool,"CLI,command,terminal,bash,script","Interactive or scriptable?;Output formats?;Config method?;Shell completion?","command_structure;output_formats;config_schema;scripting_support","visual_design;ux_principles;touch_interactions","CLI design patterns;shell integration","Natural language CLI;AI commands" +web_app,"website,webapp,browser,SPA,PWA","SPA or MPA?;Browser support?;SEO needed?;Real-time?;Accessibility?","browser_matrix;responsive_design;performance_targets;seo_strategy;accessibility_level","native_features;cli_commands","web standards;WCAG guidelines","New interaction;WebAssembly use" +game,"game,player,gameplay,level,character","REDIRECT TO USE THE BMad Method Game Module Agent and Workflows - HALT","game-brief;GDD","most_sections","game design patterns","Novel mechanics;Genre mixing" +desktop_app,"desktop,Windows,Mac,Linux,native","Cross-platform?;Auto-update?;System integration?;Offline?","platform_support;system_integration;update_strategy;offline_capabilities","web_seo;mobile_features","desktop guidelines;platform requirements","Desktop AI;System automation" +iot_embedded,"IoT,embedded,device,sensor,hardware","Hardware specs?;Connectivity?;Power constraints?;Security?;OTA updates?","hardware_reqs;connectivity_protocol;power_profile;security_model;update_mechanism","visual_ui;browser_support","IoT standards;protocol specs","Edge AI;New sensors" +blockchain_web3,"blockchain,crypto,DeFi,NFT,smart contract","Chain selection?;Wallet integration?;Gas optimization?;Security audit?","chain_specs;wallet_support;smart_contracts;security_audit;gas_optimization","traditional_auth;centralized_db","blockchain standards;security patterns","Novel tokenomics;DAO structure" \ No newline at end of file diff --git a/src/workflows/2-design/create-prd/steps-v/step-v-01-discovery.md b/src/workflows/2-design/gds-validate-prd/steps-v/step-v-01-discovery.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-v/step-v-01-discovery.md rename to src/workflows/2-design/gds-validate-prd/steps-v/step-v-01-discovery.md diff --git a/src/workflows/2-design/create-prd/steps-v/step-v-02-format-detection.md b/src/workflows/2-design/gds-validate-prd/steps-v/step-v-02-format-detection.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-v/step-v-02-format-detection.md rename to src/workflows/2-design/gds-validate-prd/steps-v/step-v-02-format-detection.md diff --git a/src/workflows/2-design/create-prd/steps-v/step-v-02b-parity-check.md b/src/workflows/2-design/gds-validate-prd/steps-v/step-v-02b-parity-check.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-v/step-v-02b-parity-check.md rename to src/workflows/2-design/gds-validate-prd/steps-v/step-v-02b-parity-check.md diff --git a/src/workflows/2-design/create-prd/steps-v/step-v-03-density-validation.md b/src/workflows/2-design/gds-validate-prd/steps-v/step-v-03-density-validation.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-v/step-v-03-density-validation.md rename to src/workflows/2-design/gds-validate-prd/steps-v/step-v-03-density-validation.md diff --git a/src/workflows/2-design/create-prd/steps-v/step-v-04-brief-coverage-validation.md b/src/workflows/2-design/gds-validate-prd/steps-v/step-v-04-brief-coverage-validation.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-v/step-v-04-brief-coverage-validation.md rename to src/workflows/2-design/gds-validate-prd/steps-v/step-v-04-brief-coverage-validation.md diff --git a/src/workflows/2-design/create-prd/steps-v/step-v-05-measurability-validation.md b/src/workflows/2-design/gds-validate-prd/steps-v/step-v-05-measurability-validation.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-v/step-v-05-measurability-validation.md rename to src/workflows/2-design/gds-validate-prd/steps-v/step-v-05-measurability-validation.md diff --git a/src/workflows/2-design/create-prd/steps-v/step-v-06-traceability-validation.md b/src/workflows/2-design/gds-validate-prd/steps-v/step-v-06-traceability-validation.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-v/step-v-06-traceability-validation.md rename to src/workflows/2-design/gds-validate-prd/steps-v/step-v-06-traceability-validation.md diff --git a/src/workflows/2-design/create-prd/steps-v/step-v-07-implementation-leakage-validation.md b/src/workflows/2-design/gds-validate-prd/steps-v/step-v-07-implementation-leakage-validation.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-v/step-v-07-implementation-leakage-validation.md rename to src/workflows/2-design/gds-validate-prd/steps-v/step-v-07-implementation-leakage-validation.md diff --git a/src/workflows/2-design/create-prd/steps-v/step-v-08-domain-compliance-validation.md b/src/workflows/2-design/gds-validate-prd/steps-v/step-v-08-domain-compliance-validation.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-v/step-v-08-domain-compliance-validation.md rename to src/workflows/2-design/gds-validate-prd/steps-v/step-v-08-domain-compliance-validation.md diff --git a/src/workflows/2-design/create-prd/steps-v/step-v-09-project-type-validation.md b/src/workflows/2-design/gds-validate-prd/steps-v/step-v-09-project-type-validation.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-v/step-v-09-project-type-validation.md rename to src/workflows/2-design/gds-validate-prd/steps-v/step-v-09-project-type-validation.md diff --git a/src/workflows/2-design/create-prd/steps-v/step-v-10-smart-validation.md b/src/workflows/2-design/gds-validate-prd/steps-v/step-v-10-smart-validation.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-v/step-v-10-smart-validation.md rename to src/workflows/2-design/gds-validate-prd/steps-v/step-v-10-smart-validation.md diff --git a/src/workflows/2-design/create-prd/steps-v/step-v-11-holistic-quality-validation.md b/src/workflows/2-design/gds-validate-prd/steps-v/step-v-11-holistic-quality-validation.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-v/step-v-11-holistic-quality-validation.md rename to src/workflows/2-design/gds-validate-prd/steps-v/step-v-11-holistic-quality-validation.md diff --git a/src/workflows/2-design/create-prd/steps-v/step-v-12-completeness-validation.md b/src/workflows/2-design/gds-validate-prd/steps-v/step-v-12-completeness-validation.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-v/step-v-12-completeness-validation.md rename to src/workflows/2-design/gds-validate-prd/steps-v/step-v-12-completeness-validation.md diff --git a/src/workflows/2-design/create-prd/steps-v/step-v-13-report-complete.md b/src/workflows/2-design/gds-validate-prd/steps-v/step-v-13-report-complete.md similarity index 100% rename from src/workflows/2-design/create-prd/steps-v/step-v-13-report-complete.md rename to src/workflows/2-design/gds-validate-prd/steps-v/step-v-13-report-complete.md diff --git a/src/workflows/2-design/create-prd/workflow-validate-prd.md b/src/workflows/2-design/gds-validate-prd/workflow.md similarity index 99% rename from src/workflows/2-design/create-prd/workflow-validate-prd.md rename to src/workflows/2-design/gds-validate-prd/workflow.md index d9073c6..3083017 100644 --- a/src/workflows/2-design/create-prd/workflow-validate-prd.md +++ b/src/workflows/2-design/gds-validate-prd/workflow.md @@ -1,5 +1,5 @@ --- -name: validate-prd +name: gds-validate-prd description: 'Validate a PRD against standards. Use when the user says "validate this PRD" or "run PRD validation"' main_config: '{module_config}' validateWorkflow: './steps-v/step-v-01-discovery.md' diff --git a/src/workflows/4-production/gds-code-review/SKILL.md b/src/workflows/4-production/gds-code-review/SKILL.md index 896cc25..dce3fd5 100644 --- a/src/workflows/4-production/gds-code-review/SKILL.md +++ b/src/workflows/4-production/gds-code-review/SKILL.md @@ -1,6 +1,6 @@ --- name: gds-code-review -description: 'Perform thorough code review to find bugs and quality issues. Use when the user says "review this code" or "do a code review"' +description: 'Review code changes adversarially using parallel review layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor) with structured triage into actionable categories. Use when the user says "run code review" or "review this code"' --- Follow the instructions in ./workflow.md. diff --git a/src/workflows/4-production/gds-code-review/steps/step-01-gather-context.md b/src/workflows/4-production/gds-code-review/steps/step-01-gather-context.md new file mode 100644 index 0000000..8294a8c --- /dev/null +++ b/src/workflows/4-production/gds-code-review/steps/step-01-gather-context.md @@ -0,0 +1,85 @@ +--- +diff_output: '' # set at runtime +spec_file: '' # set at runtime (path or empty) +review_mode: '' # set at runtime: "full" or "no-spec" +story_key: '' # set at runtime when discovered from sprint status +--- + +# Step 1: Gather Context + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`, tailored to `{game_dev_experience}` +- The prompt that triggered this workflow IS the intent — not a hint. +- Do not modify any files. This step is read-only. + +## INSTRUCTIONS + +1. **Find the review target.** The conversation context before this skill was triggered IS your starting point — not a blank slate. Check in this order — stop as soon as the review target is identified: + + **Tier 1 — Explicit argument.** + Did the user pass a PR, commit SHA, branch, spec file, or diff source this message? + - PR reference → resolve to branch/commit via `gh pr view`. If resolution fails, ask for a SHA or branch. + - Commit or branch → use directly. + - Spec file → set `{spec_file}` to the provided path. Check its frontmatter for `baseline_commit`. If found, use as diff baseline. If not found, continue the cascade (a spec alone does not identify a diff source). + - Also scan the argument for diff-mode keywords that narrow the scope: + - "staged" / "staged changes" → Staged changes only + - "uncommitted" / "working tree" / "all changes" → Uncommitted changes (staged + unstaged) + - "branch diff" / "vs main" / "against main" / "compared to " → Branch diff (extract base branch if mentioned) + - "commit range" / "last N commits" / ".." → Specific commit range + - "this diff" / "provided diff" / "paste" → User-provided diff (do not match bare "diff" — it appears in other modes) + - When multiple keywords match, prefer the most specific (e.g., "branch diff" over bare "diff"). + + **Tier 2 — Recent conversation.** + Do the last few messages reveal what the user wants to be reviewed? Look for spec paths, commit refs, branches, PRs, or descriptions of a change. Apply the same diff-mode keyword scan and routing as Tier 1. + + **Tier 3 — Sprint tracking.** + Look for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for stories with status `review`: + - **Exactly one `review` story:** Set `{story_key}` to the story's key (e.g., `1-2-user-auth`). Suggest it: "I found story in `review` status. Would you like to review its changes? [Y] Yes / [N] No, let me choose". If confirmed, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If declined, clear `{story_key}` and fall through. + - **Multiple `review` stories:** Present them as numbered options alongside a manual choice option. Wait for user selection. If a story is selected, set `{story_key}` and use its context to determine the diff source. If manual choice is selected, clear `{story_key}` and fall through. + - **None:** Fall through. + + **Tier 4 — Current git state.** + If version control is unavailable, skip to Tier 5. Otherwise, check the current branch and HEAD. If the branch is not `main` (or the default branch), confirm: "I see HEAD is `` on `` — do you want to review this branch's changes?" If confirmed, treat as a branch diff against `main`. If declined, fall through. + + **Tier 5 — Ask.** + Fall through to instruction 2. + + Never ask extra questions beyond what the cascade prescribes. If a tier above already identified the target, skip the remaining tiers and proceed to instruction 3 (construct diff). + +2. HALT. Ask the user: **What do you want to review?** Present these options: + - **Uncommitted changes** (staged + unstaged) + - **Staged changes only** + - **Branch diff** vs a base branch (ask which base branch) + - **Specific commit range** (ask for the range) + - **Provided diff or file list** (user pastes or provides a path) + +3. Construct `{diff_output}` from the chosen source. + - For **staged changes only**: run `git diff --cached`. + - For **uncommitted changes** (staged + unstaged): run `git diff HEAD`. + - For **branch diff**: verify the base branch exists before running `git diff`. If it does not exist, HALT and ask the user for a valid branch. + - For **commit range**: verify the range resolves. If it does not, HALT and ask the user for a valid range. + - For **provided diff**: validate the content is non-empty and parseable as a unified diff. If it is not parseable, HALT and ask the user to provide a valid diff. + - For **file list**: validate each path exists in the working tree. Construct `{diff_output}` by running `git diff HEAD -- ...`. If any paths are untracked (new files not yet staged), use `git diff --no-index /dev/null ` to include them. If the diff is empty (files have no uncommitted changes and are not untracked), ask the user whether to review the full file contents or to specify a different baseline. + - After constructing `{diff_output}`, verify it is non-empty regardless of source type. If empty, HALT and tell the user there is nothing to review. + +4. **Set the spec context.** + - If `{spec_file}` is already set (from Tier 1 or Tier 2): verify the file exists and is readable, then set `{review_mode}` = `"full"`. + - Otherwise, ask the user: **Is there a spec or story file that provides context for these changes?** + - If yes: set `{spec_file}` to the path provided, verify the file exists and is readable, then set `{review_mode}` = `"full"`. + - If no: set `{review_mode}` = `"no-spec"`. + +5. If `{review_mode}` = `"full"` and the file at `{spec_file}` has a `context` field in its frontmatter listing additional docs, load each referenced document. Warn the user about any docs that cannot be found. + +6. Sanity check: if `{diff_output}` exceeds approximately 3000 lines, warn the user and offer to chunk the review by file group. + - If the user opts to chunk: agree on the first group, narrow `{diff_output}` accordingly, and list the remaining groups for the user to note for follow-up runs. + - If the user declines: proceed as-is with the full diff. + +### CHECKPOINT + +Present a summary before proceeding: diff stats (files changed, lines added/removed), `{review_mode}`, and loaded spec/context docs (if any). HALT and wait for user confirmation to proceed. + + +## NEXT + +Read fully and follow `./step-02-review.md` diff --git a/src/workflows/4-production/gds-code-review/steps/step-02-review.md b/src/workflows/4-production/gds-code-review/steps/step-02-review.md new file mode 100644 index 0000000..11b9039 --- /dev/null +++ b/src/workflows/4-production/gds-code-review/steps/step-02-review.md @@ -0,0 +1,35 @@ +--- +failed_layers: '' # set at runtime: comma-separated list of layers that failed or returned empty +--- + +# Step 2: Review + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`, tailored to `{game_dev_experience}` +- The Blind Hunter subagent receives NO project context — diff only. +- The Edge Case Hunter subagent receives diff and project read access. +- The Acceptance Auditor subagent receives diff, spec, and context docs. +- All review subagents must run at the same model capability as the current session. + +## INSTRUCTIONS + +1. If `{review_mode}` = `"no-spec"`, note to the user: "Acceptance Auditor skipped — no spec file provided." + +2. Launch parallel subagents without conversation context. If subagents are not available, generate prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, resume from this point and proceed to step 3. + + - **Blind Hunter** — receives `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill. + + - **Edge Case Hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill. + + - **Acceptance Auditor** (only if `{review_mode}` = `"full"`) — receives `{diff_output}`, the content of the file at `{spec_file}`, and any loaded context docs. Its prompt: + > You are an Acceptance Auditor. Review this diff against the spec and context docs. Check for: violations of acceptance criteria, deviations from spec intent, missing implementation of specified behavior, contradictions between spec constraints and actual code. Output findings as a Markdown list. Each finding: one-line title, which AC/constraint it violates, and evidence from the diff. + +3. **Subagent failure handling**: If any subagent fails, times out, or returns empty results, append the layer name to `{failed_layers}` (comma-separated) and proceed with findings from the remaining layers. + +4. Collect all findings from the completed layers. + + +## NEXT + +Read fully and follow `./step-03-triage.md` diff --git a/src/workflows/4-production/gds-code-review/steps/step-03-triage.md b/src/workflows/4-production/gds-code-review/steps/step-03-triage.md new file mode 100644 index 0000000..54765a3 --- /dev/null +++ b/src/workflows/4-production/gds-code-review/steps/step-03-triage.md @@ -0,0 +1,49 @@ +--- +--- + +# Step 3: Triage + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`, tailored to `{game_dev_experience}` +- Be precise. When uncertain between categories, prefer the more conservative classification. + +## INSTRUCTIONS + +1. **Normalize** findings into a common format. Expected input formats: + - Adversarial (Blind Hunter): markdown list of descriptions + - Edge Case Hunter: JSON array with `location`, `trigger_condition`, `guard_snippet`, `potential_consequence` fields + - Acceptance Auditor: markdown list with title, AC/constraint reference, and evidence + + If a layer's output does not match its expected format, attempt best-effort parsing. Note any parsing issues for the user. + + Convert all to a unified list where each finding has: + - `id` -- sequential integer + - `source` -- `blind`, `edge`, `auditor`, or merged sources (e.g., `blind+edge`) + - `title` -- one-line summary + - `detail` -- full description + - `location` -- file and line reference (if available) + +2. **Deduplicate.** If two or more findings describe the same issue, merge them into one: + - Use the most specific finding as the base (prefer edge-case JSON with location over adversarial prose). + - Append any unique detail, reasoning, or location references from the other finding(s) into the surviving `detail` field. + - Set `source` to the merged sources (e.g., `blind+edge`). + +3. **Classify** each finding into exactly one bucket: + - **decision_needed** -- There is an ambiguous choice that requires human input. The code cannot be correctly patched without knowing the user's intent. Only possible if `{review_mode}` = `"full"`. + - **patch** -- Code issue that is fixable without human input. The correct fix is unambiguous. + - **defer** -- Pre-existing issue not caused by the current change. Real but not actionable now. + - **dismiss** -- Noise, false positive, or handled elsewhere. + + If `{review_mode}` = `"no-spec"` and a finding would otherwise be `decision_needed`, reclassify it as `patch` (if the fix is unambiguous) or `defer` (if not). + +4. **Drop** all `dismiss` findings. Record the dismiss count for the summary. + +5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping dismissed AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review. + +6. If zero findings remain after triage (all rejected or none raised): state "✅ Clean review — all layers passed." (Step 3 already warned if any review layers failed via `{failed_layers}`.) + + +## NEXT + +Read fully and follow `./step-04-present.md` diff --git a/src/workflows/4-production/gds-code-review/steps/step-04-present.md b/src/workflows/4-production/gds-code-review/steps/step-04-present.md new file mode 100644 index 0000000..90a6c42 --- /dev/null +++ b/src/workflows/4-production/gds-code-review/steps/step-04-present.md @@ -0,0 +1,126 @@ +--- +deferred_work_file: '{implementation_artifacts}/deferred-work.md' +--- + +# Step 4: Present and Act + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`, tailored to `{game_dev_experience}` +- When `{spec_file}` is set, always write findings to the story file before offering action choices. +- `decision_needed` findings must be resolved before handling `patch` findings. + +## INSTRUCTIONS + +### 1. Clean review shortcut + +If zero findings remain after triage (all dismissed or none raised): state that and proceed to section 6 (Sprint Status Update). + +### 2. Write findings to the story file + +If `{spec_file}` exists and contains a Tasks/Subtasks section, append a `### Review Findings` subsection. Write all findings in this order: + +1. **`decision_needed`** findings (unchecked): + `- [ ] [Review][Decision] — <Detail>` + +2. **`patch`** findings (unchecked): + `- [ ] [Review][Patch] <Title> [<file>:<line>]` + +3. **`defer`** findings (checked off, marked deferred): + `- [x] [Review][Defer] <Title> [<file>:<line>] — deferred, pre-existing` + +Also append each `defer` finding to `{deferred_work_file}` under a heading `## Deferred from: code review ({date})`. If `{spec_file}` is set, include its basename in the heading (e.g., `code review of story-3.3 (2026-03-18)`). One bullet per finding with description. + +### 3. Present summary + +Announce what was written: + +> **Code review complete.** <D> `decision_needed`, <P> `patch`, <W> `defer`, <R> dismissed as noise. + +If `{spec_file}` is set, add: `Findings written to the review findings section in {spec_file}.` +Otherwise add: `Findings are listed above. No story file was provided, so nothing was persisted.` + +### 4. Resolve decision_needed findings + +If `decision_needed` findings exist, present each one with its detail and the options available. The user must decide — the correct fix is ambiguous without their input. Walk through each finding (or batch related ones) and get the user's call. Once resolved, each becomes a `patch`, `defer`, or is dismissed. + +If the user chooses to defer, ask: Quick one-line reason for deferring this item? (helps future reviews): — then append that reason to both the story file bullet and the `{deferred_work_file}` entry. + +**HALT** — I am waiting for your numbered choice. Reply with only the number. Do not proceed until you select an option. + +### 5. Handle `patch` findings + +If `patch` findings exist (including any resolved from step 4), HALT. Ask the user: + +If `{spec_file}` is set, present all three options: + +> **How would you like to handle the `<P>` `patch` findings?** +> 1. **Apply every patch** — fix all of them now, no per-finding confirmation. Defer and decision_needed items are not touched. +> 2. **Leave as action items** — they are already in the story file +> 3. **Walk through each patch** — show details for each before deciding + +If `{spec_file}` is **not** set, present only options 1 and 2 (omit "Leave as action items" — findings were not written to a file): + +> **How would you like to handle the `<P>` `patch` findings?** +> 1. **Apply every patch** — fix all of them now, no per-finding confirmation. Defer and decision_needed items are not touched. +> 2. **Walk through each patch** — show details for each before deciding + +**HALT** — I am waiting for your numbered choice. Reply with only the number. Do not proceed until you select an option. + +- **Apply every patch**: Apply every patch finding without per-finding confirmation. Do not modify defer or decision_needed items. After all patches are applied, present a summary of changes made. If `{spec_file}` is set, check off the patch items in the story file (leave defer items as-is). +- **Leave as action items** (only when `{spec_file}` is set): Done — findings are already written to the story. +- **Walk through each patch**: Present each finding with full detail, diff context, and suggested fix. After walkthrough, re-offer the applicable options above. + + **HALT** — I am waiting for your numbered choice. Do not proceed until you select an option. + +**✅ Code review actions complete** + +- decision_needed resolved: <D> +- Patches handled: <P> +- Deferred: <W> +- Dismissed: <R> + +### 6. Update story status and sync sprint tracking + +Skip this section if `{spec_file}` is not set. + +#### Determine new status based on review outcome + +- If all `decision_needed` and `patch` findings were resolved (fixed or dismissed) AND no unresolved HIGH/MEDIUM issues remain: set `{new_status}` = `done`. Update the story file Status section to `done`. +- If `patch` findings were left as action items, or unresolved issues remain: set `{new_status}` = `in-progress`. Update the story file Status section to `in-progress`. + +Save the story file. + +#### Sync sprint-status.yaml + +If `{story_key}` is not set, skip this subsection and note that sprint status was not synced because no story key was available. + +If `{sprint_status}` file exists: + +1. Load the FULL `{sprint_status}` file. +2. Find the `development_status` entry matching `{story_key}`. +3. If found: update `development_status[{story_key}]` to `{new_status}`. Update `last_updated` to current date. Save the file, preserving ALL comments and structure including STATUS DEFINITIONS. +4. If `{story_key}` not found in sprint status: warn the user that the story file was updated but sprint-status sync failed. + +If `{sprint_status}` file does not exist, note that story status was updated in the story file only. + +#### Completion summary + +> **Review Complete!** +> +> **Story Status:** `{new_status}` +> **Issues Fixed:** <fixed_count> +> **Action Items Created:** <action_count> +> **Deferred:** <W> +> **Dismissed:** <R> + +### 7. Next steps + +Present the user with follow-up options: + +> **What would you like to do next?** +> 1. **Start the next story** — run `dev-story` to pick up the next `ready-for-dev` story +> 2. **Re-run code review** — address findings and review again +> 3. **Done** — end the workflow + +**HALT** — I am waiting for your choice. Do not proceed until the user selects an option. diff --git a/src/workflows/4-production/gds-code-review/workflow.md b/src/workflows/4-production/gds-code-review/workflow.md index 44627d1..6392fb5 100644 --- a/src/workflows/4-production/gds-code-review/workflow.md +++ b/src/workflows/4-production/gds-code-review/workflow.md @@ -1,270 +1,55 @@ --- -name: code-review -description: 'Perform adversarial code review finding specific issues. Use when the user says "run code review" or "review this code"' +main_config: '{module_config}' --- # Code Review Workflow -**Goal:** Perform adversarial code review finding specific issues. +**Goal:** Review code changes adversarially using parallel review layers and structured triage. -**Your Role:** Adversarial Code Reviewer. -- YOU ARE AN ADVERSARIAL CODE REVIEWER - Find what's wrong or missing! -- Communicate all responses in {communication_language} and language MUST be tailored to {game_dev_experience} -- Generate all documents in {document_output_language} -- Your purpose: Validate story file claims against actual implementation -- Challenge everything: Are tasks marked [x] actually done? Are ACs really implemented? -- Be thorough and specific — find real issues, not manufactured ones. If the code is genuinely good after fixes, say so -- Read EVERY file in the File List - verify implementation against story requirements -- Tasks marked complete but not done = CRITICAL finding -- Acceptance Criteria not implemented = HIGH severity finding -- Do not review files that are not part of the application's source code. Always exclude the `_bmad/` and `_bmad-output/` folders from the review. Always exclude IDE and CLI configuration folders like `.cursor/` and `.windsurf/` and `.claude/` +**Your Role:** You are an elite code reviewer. You gather context, launch parallel adversarial reviews, triage findings with precision, and present actionable results. No noise, no filler. ---- - -## INITIALIZATION - -### Configuration Loading - -Load config from `{module_config}` and resolve: - -- `project_name`, `user_name` -- `communication_language`, `document_output_language` -- `game_dev_experience` -- `planning_artifacts`, `implementation_artifacts` -- `date` as system-generated current datetime - -### Paths - -- `installed_path` = `{skill_root}` -- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` -- `validation` = `{installed_path}/checklist.md` - -### Input Files - -| Input | Description | Path Pattern(s) | Load Strategy | -|-------|-------------|------------------|---------------| -| GDD | Game Design Document | whole: `{planning_artifacts}/*gdd*.md`, sharded: `{planning_artifacts}/*gdd*/*.md` | FULL_LOAD | -| Narrative | Narrative Design Document (if story-driven) | whole: `{planning_artifacts}/*narrative*.md`, sharded: `{planning_artifacts}/*narrative*/*.md` | FULL_LOAD | -| architecture | System architecture for review context | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | FULL_LOAD | -| ux_design | UX design specification (if UI review) | whole: `{planning_artifacts}/*ux*.md`, sharded: `{planning_artifacts}/*ux*/*.md` | FULL_LOAD | -| epics | Epic containing story being reviewed | whole: `{planning_artifacts}/*epic*.md`, sharded_index: `{planning_artifacts}/*epic*/index.md`, sharded_single: `{planning_artifacts}/*epic*/epic-{{epic_num}}.md` | SELECTIVE_LOAD | - -### Context - -- `project_context` = `**/project-context.md` (load if exists) - ---- - -## EXECUTION - -<workflow> - -<step n="1" goal="Load story and discover changes"> - <action>Use provided {{story_path}} or ask user which story file to review</action> - <action>Read COMPLETE story file</action> - <action>Set {{story_key}} = extracted key from filename (e.g., "1-2-user-authentication.md" → "1-2-user-authentication") or story - metadata</action> - <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Agent Record → File List, Change Log</action> - - <!-- Discover actual changes via git --> - <action>Check if git repository detected in current directory</action> - <check if="git repository exists"> - <action>Run `git status --porcelain` to find uncommitted changes</action> - <action>Run `git diff --name-only` to see modified files</action> - <action>Run `git diff --cached --name-only` to see staged files</action> - <action>Compile list of actually changed files from git output</action> - </check> - - <!-- Cross-reference story File List vs git reality --> - <action>Compare story's Dev Agent Record → File List with actual git changes</action> - <action>Note discrepancies: - - Files in git but not in story File List - - Files in story File List but no git changes - - Missing documentation of what was actually changed - </action> - <action>Read fully and follow `{installed_path}/discover-inputs.md` to load all input files</action> - <action>Load {project_context} for coding standards (if exists)</action> -</step> +## WORKFLOW ARCHITECTURE -<step n="2" goal="Build review attack plan"> - <action>Extract ALL Acceptance Criteria from story</action> - <action>Extract ALL Tasks/Subtasks with completion status ([x] vs [ ])</action> - <action>From Dev Agent Record → File List, compile list of claimed changes</action> +This uses **step-file architecture** for disciplined execution: - <action>Create review plan: - 1. **AC Validation**: Verify each AC is actually implemented - 2. **Task Audit**: Verify each [x] task is really done - 3. **Code Quality**: Security, performance, maintainability - 4. **Test Quality**: Real tests vs placeholder bullshit - </action> -</step> +- **Micro-file Design**: Each step is self-contained and followed exactly +- **Just-In-Time Loading**: Only load the current step file +- **Sequential Enforcement**: Complete steps in order, no skipping +- **State Tracking**: Persist progress via in-memory variables +- **Append-Only Building**: Build artifacts incrementally -<step n="3" goal="Execute adversarial review"> - <critical>VALIDATE EVERY CLAIM - Check git reality vs story claims</critical> +### Step Processing Rules - <!-- Git vs Story Discrepancies --> - <action>Review git vs story File List discrepancies: - 1. **Files changed but not in story File List** → MEDIUM finding (incomplete documentation) - 2. **Story lists files but no git changes** → HIGH finding (false claims) - 3. **Uncommitted changes not documented** → MEDIUM finding (transparency issue) - </action> +1. **READ COMPLETELY**: Read the entire step file before acting +2. **FOLLOW SEQUENCE**: Execute sections in order +3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human +4. **LOAD NEXT**: When directed, read fully and follow the next step file - <!-- Use combined file list: story File List + git discovered files --> - <action>Create comprehensive review file list from story File List and git changes</action> +### Critical Rules (NO EXCEPTIONS) - <!-- AC Validation --> - <action>For EACH Acceptance Criterion: - 1. Read the AC requirement - 2. Search implementation files for evidence - 3. Determine: IMPLEMENTED, PARTIAL, or MISSING - 4. If MISSING/PARTIAL → HIGH SEVERITY finding - </action> +- **NEVER** load multiple step files simultaneously +- **ALWAYS** read entire step file before execution +- **NEVER** skip steps or optimize the sequence +- **ALWAYS** follow the exact instructions in the step file +- **ALWAYS** halt at checkpoints and wait for human input - <!-- Task Completion Audit --> - <action>For EACH task marked [x]: - 1. Read the task description - 2. Search files for evidence it was actually done - 3. **CRITICAL**: If marked [x] but NOT DONE → CRITICAL finding - 4. Record specific proof (file:line) - </action> - <!-- Code Quality Deep Dive --> - <action>For EACH file in comprehensive review list: - 1. **Security**: Look for injection risks, missing validation, auth issues - 2. **Performance**: N+1 queries, inefficient loops, missing caching - 3. **Error Handling**: Missing try/catch, poor error messages - 4. **Code Quality**: Complex functions, magic numbers, poor naming - 5. **Test Quality**: Are tests real assertions or placeholders? - </action> +## INITIALIZATION SEQUENCE - <check if="total_issues_found == 0"> - <action>Double-check by re-examining code for: - - Edge cases and null handling - - Architecture violations - - Integration issues - - Dependency problems - </action> - <action>If still no issues found after thorough re-examination, that is a valid outcome — report a clean review</action> - </check> -</step> +### 1. Configuration Loading -<step n="4" goal="Present findings and fix them"> - <action>Categorize findings: HIGH (must fix), MEDIUM (should fix), LOW (nice to fix)</action> - <action>Set {{fixed_count}} = 0</action> - <action>Set {{action_count}} = 0</action> +Load and read full config from `{main_config}` and resolve: - <output>**🔥 CODE REVIEW FINDINGS, {user_name}!** - - **Story:** {{story_file}} - **Git vs Story Discrepancies:** {{git_discrepancy_count}} found - **Issues Found:** {{high_count}} High, {{medium_count}} Medium, {{low_count}} Low - - ## 🔴 CRITICAL ISSUES - - Tasks marked [x] but not actually implemented - - Acceptance Criteria not implemented - - Story claims files changed but no git evidence - - Security vulnerabilities - - ## 🟡 MEDIUM ISSUES - - Files changed but not documented in story File List - - Uncommitted changes not tracked - - Performance problems - - Poor test coverage/quality - - Code maintainability issues - - ## 🟢 LOW ISSUES - - Code style improvements - - Documentation gaps - - Git commit message quality - </output> - - <ask>What should I do with these issues? - - 1. **Fix them automatically** - I'll update the code and tests - 2. **Create action items** - Add to story Tasks/Subtasks for later - 3. **Show me details** - Deep dive into specific issues - - Choose [1], [2], or specify which issue to examine:</ask> - - <check if="user chooses 1"> - <action>Fix all HIGH and MEDIUM issues in the code</action> - <action>Add/update tests as needed</action> - <action>Update File List in story if files changed</action> - <action>Update story Dev Agent Record with fixes applied</action> - <action>Set {{fixed_count}} = number of HIGH and MEDIUM issues fixed</action> - <action>Set {{action_count}} = 0</action> - </check> - - <check if="user chooses 2"> - <action>Add "Review Follow-ups (AI)" subsection to Tasks/Subtasks</action> - <action>For each issue: `- [ ] [AI-Review][Severity] Description [file:line]`</action> - <action>Set {{action_count}} = number of action items created</action> - <action>Set {{fixed_count}} = 0</action> - </check> - - <check if="user chooses 3"> - <action>Show detailed explanation with code examples</action> - <action>Return to fix decision</action> - </check> -</step> - -<step n="5" goal="Update story status and sync sprint tracking"> - <!-- Determine new status based on review outcome --> - <check if="all HIGH and MEDIUM issues fixed AND all ACs implemented"> - <action>Set {{new_status}} = "done"</action> - <action>Update story Status field to "done"</action> - </check> - <check if="HIGH or MEDIUM issues remain OR ACs not fully implemented"> - <action>Set {{new_status}} = "in-progress"</action> - <action>Update story Status field to "in-progress"</action> - </check> - <action>Save story file</action> - - <!-- Determine sprint tracking status --> - <check if="{sprint_status} file exists"> - <action>Set {{current_sprint_status}} = "enabled"</action> - </check> - <check if="{sprint_status} file does NOT exist"> - <action>Set {{current_sprint_status}} = "no-sprint-tracking"</action> - </check> - - <!-- Sync sprint-status.yaml when story status changes (only if sprint tracking enabled) --> - <check if="{{current_sprint_status}} != 'no-sprint-tracking'"> - <action>Load the FULL file: {sprint_status}</action> - <action>Find development_status key matching {{story_key}}</action> - - <check if="{{new_status}} == 'done'"> - <action>Update development_status[{{story_key}}] = "done"</action> - <action>Update last_updated field to current date</action> - <action>Save file, preserving ALL comments and structure</action> - <output>✅ Sprint status synced: {{story_key}} → done</output> - </check> - - <check if="{{new_status}} == 'in-progress'"> - <action>Update development_status[{{story_key}}] = "in-progress"</action> - <action>Update last_updated field to current date</action> - <action>Save file, preserving ALL comments and structure</action> - <output>🔄 Sprint status synced: {{story_key}} → in-progress</output> - </check> - - <check if="story key not found in sprint status"> - <output>⚠️ Story file updated, but sprint-status sync failed: {{story_key}} not found in sprint-status.yaml</output> - </check> - </check> - - <check if="{{current_sprint_status}} == 'no-sprint-tracking'"> - <output>ℹ️ Story status updated (no sprint tracking configured)</output> - </check> - - <output>**✅ Review Complete!** +- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name` +- `communication_language`, `document_output_language`, `game_dev_experience` +- `date` as system-generated current datetime +- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` +- `project_context` = `**/project-context.md` (load if exists) +- CLAUDE.md / memory files (load if exist) - **Story Status:** {{new_status}} - **Issues Fixed:** {{fixed_count}} - **Action Items Created:** {{action_count}} +YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`, tailored to `{game_dev_experience}`. - {{#if new_status == "done"}}Code review complete!{{else}}Address the action items and continue development.{{/if}} - </output> -</step> +### 2. First Step Execution -</workflow> +Read fully and follow: `./steps/step-01-gather-context.md` to begin the workflow. diff --git a/src/workflows/4-production/gds-correct-course/SKILL.md b/src/workflows/4-production/gds-correct-course/SKILL.md index 9b60b9d..641092c 100644 --- a/src/workflows/4-production/gds-correct-course/SKILL.md +++ b/src/workflows/4-production/gds-correct-course/SKILL.md @@ -1,6 +1,6 @@ --- name: gds-correct-course -description: 'Manage significant changes when sprint implementation is off track. Use when the user says "correct course" or "we need a course correction"' +description: 'Manage significant changes during sprint execution. Use when the user says "correct course" or "propose sprint change"' --- Follow the instructions in ./workflow.md. diff --git a/src/workflows/4-production/gds-correct-course/checklist.md b/src/workflows/4-production/gds-correct-course/checklist.md index 71dbc43..b56feb6 100644 --- a/src/workflows/4-production/gds-correct-course/checklist.md +++ b/src/workflows/4-production/gds-correct-course/checklist.md @@ -1,6 +1,6 @@ # Change Navigation Checklist -<critical>This checklist is executed as part of: skill:gds-correct-course</critical> +<critical>This checklist is executed as part of: ./workflow.md</critical> <critical>Work through each section systematically with the user, recording findings and impacts</critical> <checklist> @@ -217,8 +217,8 @@ <check-item id="5.5"> <prompt>Establish agent handoff plan</prompt> <action>Identify which roles/agents will execute the changes:</action> - - Development team (for implementation) - - Product Owner / Scrum Master (for backlog changes) + - Developer agent (for implementation) + - Product Owner / Developer (for backlog changes) - Product Manager / Architect (for strategic changes) <action>Define responsibilities for each role</action> <status>[ ] Done / [ ] N/A / [ ] Action-needed</status> diff --git a/src/workflows/4-production/gds-correct-course/workflow.md b/src/workflows/4-production/gds-correct-course/workflow.md index acb6aa8..287ef81 100644 --- a/src/workflows/4-production/gds-correct-course/workflow.md +++ b/src/workflows/4-production/gds-correct-course/workflow.md @@ -1,13 +1,8 @@ ---- -name: correct-course -description: 'Manage significant changes during sprint execution. Use when the user says "correct course" or "propose sprint change"' ---- - # Correct Course - Sprint Change Management Workflow **Goal:** Manage significant changes during sprint execution by analyzing impact across all project artifacts and producing a structured Sprint Change Proposal. -**Your Role:** You are a Scrum Master navigating change management. Analyze the triggering issue, assess impact across GDD, epics, architecture, and UX artifacts, and produce an actionable Sprint Change Proposal with clear handoff. +**Your Role:** You are a Developer navigating change management. Analyze the triggering issue, assess impact across GDD, epics, architecture, and UX artifacts, and produce an actionable Sprint Change Proposal with clear handoff. --- @@ -31,8 +26,6 @@ Load config from `{module_config}` and resolve: ### Paths -- `installed_path` = `{skill_root}` -- `checklist` = `{installed_path}/checklist.md` - `default_output_file` = `{planning_artifacts}/sprint-change-proposal-{date}.md` ### Input Files @@ -44,12 +37,12 @@ Load config from `{module_config}` and resolve: | Epics | `{planning_artifacts}/*epic*.md` (whole) or `{planning_artifacts}/*epic*/*.md` (sharded) | FULL_LOAD | | Architecture | `{planning_artifacts}/*architecture*.md` (whole) or `{planning_artifacts}/*architecture*/*.md` (sharded) | FULL_LOAD | | UX Design | `{planning_artifacts}/*ux*.md` (whole) or `{planning_artifacts}/*ux*/*.md` (sharded) | FULL_LOAD | -| Tech Spec | `{planning_artifacts}/*tech-spec*.md` (whole) | FULL_LOAD | +| Tech Spec | `{planning_artifacts}/*tech-spec*.md` (whole) or `{planning_artifacts}/*spec-*.md` (whole) | FULL_LOAD | | Document Project | `{project_knowledge}/index.md` (sharded) | INDEX_GUIDED | ### Context -- `project_context` = `**/project-context.md` (load if exists) +- Load `**/project-context.md` if it exists --- @@ -83,7 +76,7 @@ Load config from `{module_config}` and resolve: <workflow> <step n="1" goal="Initialize Change Navigation"> - <action>Load {project_context} for coding standards and project-wide patterns (if exists)</action> + <action>Load **/project-context.md for coding standards and project-wide patterns (if exists)</action> <action>Confirm change trigger and gather user description of the issue</action> <action>Ask: "What specific issue or change has been identified that requires navigation?"</action> <action>Verify access to required project documents:</action> @@ -103,7 +96,7 @@ Load config from `{module_config}` and resolve: </step> <step n="2" goal="Execute Change Analysis Checklist"> - <action>Read fully and follow the systematic analysis from: {checklist}</action> + <action>Read fully and follow the systematic analysis from: checklist.md</action> <action>Work through each checklist section interactively with the user</action> <action>Record status for each checklist item:</action> - [x] Done - Item completed successfully @@ -207,8 +200,8 @@ Load config from `{module_config}` and resolve: <action>Section 5: Implementation Handoff</action> - Categorize change scope: - - Minor: Direct implementation by dev team - - Moderate: Backlog reorganization needed (PO/SM) + - Minor: Direct implementation by Developer agent + - Moderate: Backlog reorganization needed (PO/DEV) - Major: Fundamental replan required (PM/Architect) - Specify handoff recipients and their responsibilities - Define success criteria for implementation @@ -234,8 +227,8 @@ Load config from `{module_config}` and resolve: <action>Finalize Sprint Change Proposal document</action> <action>Determine change scope classification:</action> -- **Minor**: Can be implemented directly by development team -- **Moderate**: Requires backlog reorganization and PO/SM coordination +- **Minor**: Can be implemented directly by Developer agent +- **Moderate**: Requires backlog reorganization and PO/DEV coordination - **Major**: Needs fundamental replan with PM/Architect involvement <action>Provide appropriate handoff based on scope:</action> @@ -243,12 +236,12 @@ Load config from `{module_config}` and resolve: </check> <check if="Minor scope"> - <action>Route to: Development team for direct implementation</action> + <action>Route to: Developer agent for direct implementation</action> <action>Deliverables: Finalized edit proposals and implementation tasks</action> </check> <check if="Moderate scope"> - <action>Route to: Product Owner / Scrum Master agents</action> + <action>Route to: Product Owner / Developer agents</action> <action>Deliverables: Sprint Change Proposal + backlog reorganization plan</action> </check> @@ -276,7 +269,7 @@ Load config from `{module_config}` and resolve: - Implementation handoff plan <action>Report workflow completion to user with personalized message: "Correct Course workflow complete, {user_name}!"</action> -<action>Remind user of success criteria and next steps for implementation team</action> +<action>Remind user of success criteria and next steps for Developer agent</action> </step> </workflow> diff --git a/src/workflows/4-production/gds-create-story/workflow.md b/src/workflows/4-production/gds-create-story/workflow.md index 1cbd54b..2bedd48 100644 --- a/src/workflows/4-production/gds-create-story/workflow.md +++ b/src/workflows/4-production/gds-create-story/workflow.md @@ -1,14 +1,10 @@ ---- -name: gds-create-story -description: 'Creates a dedicated story file with all the context the agent will need to implement it later. Use when the user says "create the next story" or "create story [story identifier]"' ---- - # Create Story Workflow **Goal:** Create a comprehensive story file that gives the dev agent everything needed for flawless implementation. **Your Role:** Story context engine that prevents LLM developer mistakes, omissions, or disasters. -- Communicate all responses in {communication_language} and generate all documents in {document_output_language} +- Communicate all responses in {communication_language} and language MUST be tailored to {game_dev_experience} +- Generate all documents in {document_output_language} - Your purpose is NOT to copy from epics - it's to create a comprehensive, optimized story file that gives the DEV agent EVERYTHING needed for flawless implementation - COMMON LLM MISTAKES TO PREVENT: reinventing wheels, wrong libraries, wrong file locations, breaking regressions, ignoring UX, vague implementations, lying about completion, not learning from past work - EXHAUSTIVE ANALYSIS REQUIRED: You must thoroughly analyze ALL artifacts to extract critical context - do NOT be lazy or skim! This is the most important function in the entire development process! @@ -32,9 +28,6 @@ Load config from `{module_config}` and resolve: ### Paths -- `installed_path` = `.` -- `template` = `./template.md` -- `validation` = `./checklist.md` - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` - `epics_file` = `{planning_artifacts}/epics.md` - `gdd_file` = `{planning_artifacts}/gdd.md` @@ -218,10 +211,10 @@ Load config from `{module_config}` and resolve: </step> <step n="2" goal="Load and analyze core artifacts"> - <critical>🔬 EXHAUSTIVE ARTIFACT ANALYSIS - This is where you prevent future developer fuckups!</critical> + <critical>🔬 EXHAUSTIVE ARTIFACT ANALYSIS - This is where you prevent future developer mistakes!</critical> <!-- Load all available content through discovery protocol --> - <action>Read fully and follow `{installed_path}/discover-inputs.md` to load all input files</action> + <action>Read fully and follow `./discover-inputs.md` to load all input files</action> <note>Available content: {epics_content}, {gdd_content}, {architecture_content}, {ux_content}, {project_context}</note> @@ -241,7 +234,7 @@ Load config from `{module_config}` and resolve: all learnings that could impact current story implementation</action> </check> - <!-- Project context analysis --> + <!-- Project context analysis (game-dev extension for project-context.md extraction) --> <check if="{project_context} was loaded and is not empty"> <action>Analyze {project_context} for story-relevant rules and constraints:</action> **PROJECT CONTEXT EXTRACTION:** @@ -350,7 +343,7 @@ Load config from `{module_config}` and resolve: <template-output file="{default_output_file}">latest_tech_information</template-output> </check> - <!-- Project context rules - embed extracted rules from project-context.md --> + <!-- Project context rules - embed extracted rules from project-context.md (game-dev extension) --> <check if="{{project_rules}} is not empty"> <template-output file="{default_output_file}">project_context_reference</template-output> <action>Populate the Project Context Rules section with ALL extracted {{project_rules}} including: @@ -371,7 +364,7 @@ Load config from `{module_config}` and resolve: </step> <step n="6" goal="Update sprint status and finalize"> - <action>Validate the newly created story file {story_file} against {installed_path}/checklist.md and apply any required fixes before finalizing</action> + <action>Validate the newly created story file {default_output_file} against `./checklist.md` and apply any required fixes before finalizing</action> <action>Save story document unconditionally</action> <!-- Update sprint status --> diff --git a/src/workflows/4-production/gds-dev-story/workflow.md b/src/workflows/4-production/gds-dev-story/workflow.md index 87c2c01..10ece12 100644 --- a/src/workflows/4-production/gds-dev-story/workflow.md +++ b/src/workflows/4-production/gds-dev-story/workflow.md @@ -9,7 +9,7 @@ - Execute ALL steps in exact order; do NOT skip steps - Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives other instruction. - Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion. -- User skill level ({game_dev_experience}) affects conversation style ONLY, not code updates. +- Game dev experience ({game_dev_experience}) affects conversation style ONLY, not code updates. --- @@ -27,7 +27,6 @@ Load config from `{module_config}` and resolve: ### Paths -- `validation` = `./checklist.md` - `story_file` = `` (explicit story path; auto-discovered if empty) - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` @@ -49,7 +48,7 @@ Load config from `{module_config}` and resolve: until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives other instruction.</critical> <critical>Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.</critical> - <critical>User skill level ({game_dev_experience}) affects conversation style ONLY, not code updates.</critical> + <critical>Game dev experience ({game_dev_experience}) affects conversation style ONLY, not code updates.</critical> <step n="1" goal="Find next ready story and load it" tag="sprint-status"> <check if="{{story_path}} is provided"> diff --git a/src/workflows/4-production/gds-retrospective/SKILL.md b/src/workflows/4-production/gds-retrospective/SKILL.md index 2fe83f1..4927d0a 100644 --- a/src/workflows/4-production/gds-retrospective/SKILL.md +++ b/src/workflows/4-production/gds-retrospective/SKILL.md @@ -1,6 +1,6 @@ --- name: gds-retrospective -description: 'Facilitate a retrospective after completing a game development epic. Use when the user says "run a retrospective" or "lets do a retro"' +description: 'Post-epic review to extract lessons and assess success. Use when the user says "run a retrospective" or "lets retro the epic [epic]"' --- Follow the instructions in ./workflow.md. diff --git a/src/workflows/4-production/gds-retrospective/workflow.md b/src/workflows/4-production/gds-retrospective/workflow.md index 780b9e1..a60b1a0 100644 --- a/src/workflows/4-production/gds-retrospective/workflow.md +++ b/src/workflows/4-production/gds-retrospective/workflow.md @@ -1,13 +1,8 @@ ---- -name: retrospective -description: 'Post-epic review to extract lessons and assess success. Use when the user says "run a retrospective" or "lets retro the epic [epic]"' ---- - # Retrospective Workflow **Goal:** Post-epic review to extract lessons and assess success. -**Your Role:** Scrum Master facilitating retrospective. +**Your Role:** Developer facilitating retrospective. - No time estimates — NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed. - Communicate all responses in {communication_language} and language MUST be tailored to {game_dev_experience} - Generate all documents in {document_output_language} @@ -20,7 +15,7 @@ description: 'Post-epic review to extract lessons and assess success. Use when t - Two-part format: (1) Epic Review + (2) Next Epic Preparation - Party mode protocol: - ALL agent dialogue MUST use format: "Name (Role): dialogue" - - Example: Bob (Scrum Master): "Let's begin..." + - Example: Amelia (Developer): "Let's begin..." - Example: {user_name} (Project Lead): [User responds] - Create natural back-and-forth with user actively participating - Show disagreements, diverse perspectives, authentic team dynamics @@ -42,7 +37,6 @@ Load config from `{module_config}` and resolve: ### Paths -- `installed_path` = `{skill_root}` - `sprint_status_file` = `{implementation_artifacts}/sprint-status.yaml` ### Input Files @@ -52,8 +46,9 @@ Load config from `{module_config}` and resolve: | epics | The completed epic for retrospective | whole: `{planning_artifacts}/*epic*.md`, sharded_index: `{planning_artifacts}/*epic*/index.md`, sharded_single: `{planning_artifacts}/*epic*/epic-{{epic_num}}.md` | SELECTIVE_LOAD | | previous_retrospective | Previous epic's retrospective (optional) | `{implementation_artifacts}/**/epic-{{prev_epic_num}}-retro-*.md` | SELECTIVE_LOAD | | architecture | System architecture for context | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | FULL_LOAD | -| gdd | Game Design Document for context | whole: `{planning_artifacts}/*gdd*.md`, sharded: `{planning_artifacts}/*gdd*/*.md` | FULL_LOAD | -| narrative | Narrative design for context (optional) | whole: `{planning_artifacts}/*narrative*.md`, sharded: `{planning_artifacts}/*narrative*/*.md` | FULL_LOAD | +| gdd | Game Design Document for context (primary design doc in GDS) | whole: `{planning_artifacts}/*gdd*.md`, sharded: `{planning_artifacts}/*gdd*/*.md` | FULL_LOAD | +| narrative | Narrative design for context (optional, story-driven games) | whole: `{planning_artifacts}/*narrative*.md`, sharded: `{planning_artifacts}/*narrative*/*.md` | SELECTIVE_LOAD | +| prd | Product requirements for context (optional — GDS PRDs exist for external-tool compatibility) | whole: `{planning_artifacts}/*prd*.md`, sharded: `{planning_artifacts}/*prd*/*.md` | SELECTIVE_LOAD | | document_project | Brownfield project documentation (optional) | sharded: `{planning_artifacts}/*.md` | INDEX_GUIDED | ### Required Inputs @@ -76,7 +71,7 @@ Load config from `{module_config}` and resolve: <action>Explain to {user_name} the epic discovery process using natural dialogue</action> <output> -Bob (Scrum Master): "Welcome to the retrospective, {user_name}. Let me help you identify which epic we just completed. I'll check sprint-status first, but you're the ultimate authority on what we're reviewing today." +Amelia (Developer): "Welcome to the retrospective, {user_name}. Let me help you identify which epic we just completed. I'll check sprint-status first, but you're the ultimate authority on what we're reviewing today." </output> <action>PRIORITY 1: Check {sprint_status_file} first</action> @@ -91,7 +86,7 @@ Bob (Scrum Master): "Welcome to the retrospective, {user_name}. Let me help you <action>Present finding to user with context</action> <output> -Bob (Scrum Master): "Based on {sprint_status_file}, it looks like Epic {{detected_epic}} was recently completed. Is that the epic you want to review today, {user_name}?" +Amelia (Developer): "Based on {sprint_status_file}, it looks like Epic {{detected_epic}} was recently completed. Is that the epic you want to review today, {user_name}?" </output> <action>WAIT for {user_name} to confirm or correct</action> @@ -103,7 +98,7 @@ Bob (Scrum Master): "Based on {sprint_status_file}, it looks like Epic {{detecte <check if="{user_name} provides different epic number"> <action>Set {{epic_number}} = user-provided number</action> <output> -Bob (Scrum Master): "Got it, we're reviewing Epic {{epic_number}}. Let me gather that information." +Amelia (Developer): "Got it, we're reviewing Epic {{epic_number}}. Let me gather that information." </output> </check> </check> @@ -112,7 +107,7 @@ Bob (Scrum Master): "Got it, we're reviewing Epic {{epic_number}}. Let me gather <action>PRIORITY 2: Ask user directly</action> <output> -Bob (Scrum Master): "I'm having trouble detecting the completed epic from {sprint_status_file}. {user_name}, which epic number did you just complete?" +Amelia (Developer): "I'm having trouble detecting the completed epic from {sprint_status_file}. {user_name}, which epic number did you just complete?" </output> <action>WAIT for {user_name} to provide epic number</action> @@ -127,7 +122,7 @@ Bob (Scrum Master): "I'm having trouble detecting the completed epic from {sprin <action>Set {{detected_epic}} = highest epic number found</action> <output> -Bob (Scrum Master): "I found stories for Epic {{detected_epic}} in the stories folder. Is that the epic we're reviewing, {user_name}?" +Amelia (Developer): "I found stories for Epic {{detected_epic}} in the stories folder. Is that the epic we're reviewing, {user_name}?" </output> <action>WAIT for {user_name} to confirm or correct</action> @@ -150,9 +145,9 @@ Bob (Scrum Master): "I found stories for Epic {{detected_epic}} in the stories f <check if="epic is not complete"> <output> -Alice (Product Owner): "Wait, Bob - I'm seeing that Epic {{epic_number}} isn't actually complete yet." +Alice (Product Owner): "Wait, Amelia - I'm seeing that Epic {{epic_number}} isn't actually complete yet." -Bob (Scrum Master): "Let me check... you're right, Alice." +Amelia (Developer): "Let me check... you're right, Alice." **Epic Status:** @@ -163,7 +158,7 @@ Bob (Scrum Master): "Let me check... you're right, Alice." **Pending Stories:** {{pending_story_list}} -Bob (Scrum Master): "{user_name}, we typically run retrospectives after all stories are done. What would you like to do?" +Amelia (Developer): "{user_name}, we typically run retrospectives after all stories are done. What would you like to do?" **Options:** @@ -176,7 +171,7 @@ Bob (Scrum Master): "{user_name}, we typically run retrospectives after all stor <check if="user says no"> <output> -Bob (Scrum Master): "Smart call, {user_name}. Let's finish those stories first and then have a proper retrospective." +Amelia (Developer): "Smart call, {user_name}. Let's finish those stories first and then have a proper retrospective." </output> <action>HALT</action> </check> @@ -185,7 +180,7 @@ Bob (Scrum Master): "Smart call, {user_name}. Let's finish those stories first a <output> Charlie (Senior Dev): "Just so everyone knows, this partial retro might miss some important lessons from those pending stories." -Bob (Scrum Master): "Good point, Charlie. {user_name}, we'll document what we can now, but we may want to revisit after everything's done." +Amelia (Developer): "Good point, Charlie. {user_name}, we'll document what we can now, but we may want to revisit after everything's done." </output> </check> @@ -193,21 +188,21 @@ Bob (Scrum Master): "Good point, Charlie. {user_name}, we'll document what we ca <output> Alice (Product Owner): "Excellent! All {{done_stories}} stories are marked done." -Bob (Scrum Master): "Perfect. Epic {{epic_number}} is complete and ready for retrospective, {user_name}." +Amelia (Developer): "Perfect. Epic {{epic_number}} is complete and ready for retrospective, {user_name}." </output> </check> </step> <step n="0.5" goal="Discover and load project documents"> - <action>Load input files according to the Input Files table in INITIALIZATION. For SELECTIVE_LOAD inputs, load only the epic matching {{epic_number}}. For FULL_LOAD inputs, load the complete document. For INDEX_GUIDED inputs, check the index first and load relevant sections. After discovery, these content variables are available: {epics_content} (selective load for this epic), {architecture_content}, {gdd_content}, {narrative_content}, {document_project_content}</action> - <note>After discovery, these content variables are available: {epics_content} (selective load for this epic), {architecture_content}, {gdd_content}, {narrative_content}, {document_project_content}</note> + <action>Load input files according to the Input Files table in INITIALIZATION. For SELECTIVE_LOAD inputs, load only the epic matching {{epic_number}}. For FULL_LOAD inputs, load the complete document. For INDEX_GUIDED inputs, check the index first and load relevant sections. After discovery, these content variables are available: {epics_content} (selective load for this epic), {architecture_content}, {gdd_content}, {narrative_content}, {prd_content}, {document_project_content}</action> + <note>After discovery, these content variables are available: {epics_content} (selective load for this epic), {architecture_content}, {gdd_content}, {narrative_content}, {prd_content}, {document_project_content}</note> </step> <step n="2" goal="Deep Story Analysis - Extract Lessons from Implementation"> <output> -Bob (Scrum Master): "Before we start the team discussion, let me review all the story records to surface key themes. This'll help us have a richer conversation." +Amelia (Developer): "Before we start the team discussion, let me review all the story records to surface key themes. This'll help us have a richer conversation." Charlie (Senior Dev): "Good idea - those dev notes always have gold in them." </output> @@ -226,7 +221,7 @@ Charlie (Senior Dev): "Good idea - those dev notes always have gold in them." **Review Feedback Patterns:** -- Look for "## Review", "## Code Review", "## SM Review", "## Scrum Master Review" sections +- Look for "## Review", "## Code Review", "## Dev Review" sections - Identify recurring feedback themes across stories - Note which types of issues came up repeatedly - Track quality concerns or architectural misalignments @@ -289,11 +284,11 @@ Charlie (Senior Dev): "Good idea - those dev notes always have gold in them." <action>Store this synthesis - these patterns will drive the retrospective discussion</action> <output> -Bob (Scrum Master): "Okay, I've reviewed all {{total_stories}} story records. I found some really interesting patterns we should discuss." +Amelia (Developer): "Okay, I've reviewed all {{total_stories}} story records. I found some really interesting patterns we should discuss." -Dana (QA Engineer): "I'm curious what you found, Bob. I noticed some things in my testing too." +Dana (QA Engineer): "I'm curious what you found, Amelia. I noticed some things in my testing too." -Bob (Scrum Master): "We'll get to all of it. But first, let me load the previous epic's retro to see if we learned from last time." +Amelia (Developer): "We'll get to all of it. But first, let me load the previous epic's retro to see if we learned from last time." </output> </step> @@ -307,7 +302,7 @@ Bob (Scrum Master): "We'll get to all of it. But first, let me load the previous <check if="previous retrospectives found"> <output> -Bob (Scrum Master): "I found our retrospectives from Epic {{prev_epic_num}}. Let me see what we committed to back then..." +Amelia (Developer): "I found our retrospectives from Epic {{prev_epic_num}}. Let me see what we committed to back then..." </output> <action>Read the previous retrospectives</action> @@ -356,26 +351,26 @@ Bob (Scrum Master): "I found our retrospectives from Epic {{prev_epic_num}}. Let <output> -Bob (Scrum Master): "Interesting... in Epic {{prev_epic_num}}'s retro, we committed to {{action_count}} action items." +Amelia (Developer): "Interesting... in Epic {{prev_epic_num}}'s retro, we committed to {{action_count}} action items." -Alice (Product Owner): "How'd we do on those, Bob?" +Alice (Product Owner): "How'd we do on those, Amelia?" -Bob (Scrum Master): "We completed {{completed_count}}, made progress on {{in_progress_count}}, but didn't address {{not_addressed_count}}." +Amelia (Developer): "We completed {{completed_count}}, made progress on {{in_progress_count}}, but didn't address {{not_addressed_count}}." Charlie (Senior Dev): _looking concerned_ "Which ones didn't we address?" -Bob (Scrum Master): "We'll discuss that in the retro. Some of them might explain challenges we had this epic." +Amelia (Developer): "We'll discuss that in the retro. Some of them might explain challenges we had this epic." Elena (Junior Dev): "That's... actually pretty insightful." -Bob (Scrum Master): "That's why we track this stuff. Pattern recognition helps us improve." +Amelia (Developer): "That's why we track this stuff. Pattern recognition helps us improve." </output> </check> <check if="no previous retro found"> <output> -Bob (Scrum Master): "I don't see a retrospective for Epic {{prev_epic_num}}. Either we skipped it, or this is your first retro." +Amelia (Developer): "I don't see a retrospective for Epic {{prev_epic_num}}. Either we skipped it, or this is your first retro." Alice (Product Owner): "Probably our first one. Good time to start the habit!" </output> @@ -385,7 +380,7 @@ Alice (Product Owner): "Probably our first one. Good time to start the habit!" <check if="{{prev_epic_num}} < 1"> <output> -Bob (Scrum Master): "This is Epic 1, so naturally there's no previous retro to reference. We're starting fresh!" +Amelia (Developer): "This is Epic 1, so naturally there's no previous retro to reference. We're starting fresh!" Charlie (Senior Dev): "First epic, first retro. Let's make it count." </output> @@ -399,7 +394,7 @@ Charlie (Senior Dev): "First epic, first retro. Let's make it count." <action>Calculate next epic number: {{next_epic_num}} = {{epic_number}} + 1</action> <output> -Bob (Scrum Master): "Before we dive into the discussion, let me take a quick look at Epic {{next_epic_num}} to understand what's coming." +Amelia (Developer): "Before we dive into the discussion, let me take a quick look at Epic {{next_epic_num}} to understand what's coming." Alice (Product Owner): "Good thinking - helps us connect what we learned to what we're about to do." </output> @@ -455,15 +450,15 @@ Alice (Product Owner): "Good thinking - helps us connect what we learned to what - Deployment or environment setup <output> -Bob (Scrum Master): "Alright, I've reviewed Epic {{next_epic_num}}: '{{next_epic_title}}'" +Amelia (Developer): "Alright, I've reviewed Epic {{next_epic_num}}: '{{next_epic_title}}'" Alice (Product Owner): "What are we looking at?" -Bob (Scrum Master): "{{next_epic_num}} stories planned, building on the {{dependency_description}} from Epic {{epic_number}}." +Amelia (Developer): "{{next_epic_num}} stories planned, building on the {{dependency_description}} from Epic {{epic_number}}." Charlie (Senior Dev): "Dependencies concern me. Did we finish everything we need for that?" -Bob (Scrum Master): "Good question - that's exactly what we need to explore in this retro." +Amelia (Developer): "Good question - that's exactly what we need to explore in this retro." </output> <action>Set {{next_epic_exists}} = true</action> @@ -471,11 +466,11 @@ Bob (Scrum Master): "Good question - that's exactly what we need to explore in t <check if="next epic NOT found"> <output> -Bob (Scrum Master): "Hmm, I don't see Epic {{next_epic_num}} defined yet." +Amelia (Developer): "Hmm, I don't see Epic {{next_epic_num}} defined yet." Alice (Product Owner): "We might be at the end of the roadmap, or we haven't planned that far ahead yet." -Bob (Scrum Master): "No problem. We'll still do a thorough retro on Epic {{epic_number}}. The lessons will be valuable whenever we plan the next work." +Amelia (Developer): "No problem. We'll still do a thorough retro on Epic {{epic_number}}. The lessons will be valuable whenever we plan the next work." </output> <action>Set {{next_epic_exists}} = false</action> @@ -487,16 +482,16 @@ Bob (Scrum Master): "No problem. We'll still do a thorough retro on Epic {{epic_ <action>Load agent configurations from {agent_manifest}</action> <action>Identify which agents participated in Epic {{epic_number}} based on story records</action> -<action>Ensure key roles present: Product Owner, Scrum Master (facilitating), Devs, Testing/QA, Architect</action> +<action>Ensure key roles present: Product Owner, Developer (facilitating), Testing/QA, Architect</action> <output> -Bob (Scrum Master): "Alright team, everyone's here. Let me set the stage for our retrospective." +Amelia (Developer): "Alright team, everyone's here. Let me set the stage for our retrospective." ═══════════════════════════════════════════════════════════ 🔄 TEAM RETROSPECTIVE - Epic {{epic_number}}: {{epic_title}} ═══════════════════════════════════════════════════════════ -Bob (Scrum Master): "Here's what we accomplished together." +Amelia (Developer): "Here's what we accomplished together." **EPIC {{epic_number}} SUMMARY:** @@ -540,7 +535,7 @@ Preparation Needed: Technical Prerequisites: {{list_technical_prereqs}} -Bob (Scrum Master): "And here's what's coming next. Epic {{next_epic_num}} builds on what we just finished." +Amelia (Developer): "And here's what's coming next. Epic {{next_epic_num}} builds on what we just finished." Elena (Junior Dev): "Wow, that's a lot of dependencies on our work." @@ -549,24 +544,24 @@ Charlie (Senior Dev): "Which means we better make sure Epic {{epic_number}} is a ═══════════════════════════════════════════════════════════ -Bob (Scrum Master): "Team assembled for this retrospective:" +Amelia (Developer): "Team assembled for this retrospective:" {{list_participating_agents}} -Bob (Scrum Master): "{user_name}, you're joining us as Project Lead. Your perspective is crucial here." +Amelia (Developer): "{user_name}, you're joining us as Project Lead. Your perspective is crucial here." {user_name} (Project Lead): [Participating in the retrospective] -Bob (Scrum Master): "Our focus today:" +Amelia (Developer): "Our focus today:" 1. Learning from Epic {{epic_number}} execution {{#if next_epic_exists}}2. Preparing for Epic {{next_epic_num}} success{{/if}} -Bob (Scrum Master): "Ground rules: psychological safety first. No blame, no judgment. We focus on systems and processes, not individuals. Everyone's voice matters. Specific examples are better than generalizations." +Amelia (Developer): "Ground rules: psychological safety first. No blame, no judgment. We focus on systems and processes, not individuals. Everyone's voice matters. Specific examples are better than generalizations." Alice (Product Owner): "And everything shared here stays in this room - unless we decide together to escalate something." -Bob (Scrum Master): "Exactly. {user_name}, any questions before we dive in?" +Amelia (Developer): "Exactly. {user_name}, any questions before we dive in?" </output> <action>WAIT for {user_name} to respond or indicate readiness</action> @@ -576,25 +571,25 @@ Bob (Scrum Master): "Exactly. {user_name}, any questions before we dive in?" <step n="6" goal="Epic Review Discussion - What Went Well, What Didn't"> <output> -Bob (Scrum Master): "Let's start with the good stuff. What went well in Epic {{epic_number}}?" +Amelia (Developer): "Let's start with the good stuff. What went well in Epic {{epic_number}}?" -Bob (Scrum Master): _pauses, creating space_ +Amelia (Developer): _pauses, creating space_ Alice (Product Owner): "I'll start. The user authentication flow we delivered exceeded my expectations. The UX is smooth, and early user feedback has been really positive." Charlie (Senior Dev): "I'll add to that - the caching strategy we implemented in Story {{breakthrough_story_num}} was a game-changer. We cut API calls by 60% and it set the pattern for the rest of the epic." -Dana (QA Engineer): "From my side, testing went smoother than usual. The dev team's documentation was way better this epic - actually usable test plans!" +Dana (QA Engineer): "From my side, testing went smoother than usual. The Developer's documentation was way better this epic - actually usable test plans!" Elena (Junior Dev): _smiling_ "That's because Charlie made me document everything after Story 1's code review!" Charlie (Senior Dev): _laughing_ "Tough love pays off." </output> -<action>Bob (Scrum Master) naturally turns to {user_name} to engage them in the discussion</action> +<action>Amelia (Developer) naturally turns to {user_name} to engage them in the discussion</action> <output> -Bob (Scrum Master): "{user_name}, what stood out to you as going well in this epic?" +Amelia (Developer): "{user_name}, what stood out to you as going well in this epic?" </output> <action>WAIT for {user_name} to respond - this is a KEY USER INTERACTION moment</action> @@ -612,9 +607,9 @@ Charlie (Senior Dev): [Builds on the discussion, perhaps adding technical detail <action>After covering successes, guide the transition to challenges with care</action> <output> -Bob (Scrum Master): "Okay, we've celebrated some real wins. Now let's talk about challenges - where did we struggle? What slowed us down?" +Amelia (Developer): "Okay, we've celebrated some real wins. Now let's talk about challenges - where did we struggle? What slowed us down?" -Bob (Scrum Master): _creates safe space with tone and pacing_ +Amelia (Developer): _creates safe space with tone and pacing_ Elena (Junior Dev): _hesitates_ "Well... I really struggled with the database migrations in Story {{difficult_story_num}}. The documentation wasn't clear, and I had to redo it three times. Lost almost a full sprint on that story alone." @@ -624,11 +619,11 @@ Alice (Product Owner): _frustrated_ "That's not fair, Charlie. We only clarified Charlie (Senior Dev): _heat rising_ "We asked plenty of questions! You said the schema was finalized, then two days into development you wanted to add three new fields!" -Bob (Scrum Master): _intervening calmly_ "Let's take a breath here. This is exactly the kind of thing we need to unpack." +Amelia (Developer): _intervening calmly_ "Let's take a breath here. This is exactly the kind of thing we need to unpack." -Bob (Scrum Master): "Elena, you spent almost a full sprint on Story {{difficult_story_num}}. Charlie, you're saying requirements changed. Alice, you feel the right questions weren't asked up front." +Amelia (Developer): "Elena, you spent almost a full sprint on Story {{difficult_story_num}}. Charlie, you're saying requirements changed. Alice, you feel the right questions weren't asked up front." -Bob (Scrum Master): "{user_name}, you have visibility across the whole project. What's your take on this situation?" +Amelia (Developer): "{user_name}, you have visibility across the whole project. What's your take on this situation?" </output> <action>WAIT for {user_name} to respond and help facilitate the conflict resolution</action> @@ -636,7 +631,7 @@ Bob (Scrum Master): "{user_name}, you have visibility across the whole project. <action>Use {user_name}'s response to guide the discussion toward systemic understanding rather than blame</action> <output> -Bob (Scrum Master): [Synthesizes {user_name}'s input with what the team shared] "So it sounds like the core issue was {{root_cause_based_on_discussion}}, not any individual person's fault." +Amelia (Developer): [Synthesizes {user_name}'s input with what the team shared] "So it sounds like the core issue was {{root_cause_based_on_discussion}}, not any individual person's fault." Elena (Junior Dev): "That makes sense. If we'd had {{preventive_measure}}, I probably could have avoided those redos." @@ -644,23 +639,23 @@ Charlie (Senior Dev): _softening_ "Yeah, and I could have been clearer about ass Alice (Product Owner): "I appreciate that. I could've been more proactive about flagging the schema additions earlier, too." -Bob (Scrum Master): "This is good. We're identifying systemic improvements, not assigning blame." +Amelia (Developer): "This is good. We're identifying systemic improvements, not assigning blame." </output> <action>Continue the discussion, weaving in patterns discovered from the deep story analysis (Step 2)</action> <output> -Bob (Scrum Master): "Speaking of patterns, I noticed something when reviewing all the story records..." +Amelia (Developer): "Speaking of patterns, I noticed something when reviewing all the story records..." -Bob (Scrum Master): "{{pattern_1_description}} - this showed up in {{pattern_1_count}} out of {{total_stories}} stories." +Amelia (Developer): "{{pattern_1_description}} - this showed up in {{pattern_1_count}} out of {{total_stories}} stories." Dana (QA Engineer): "Oh wow, I didn't realize it was that widespread." -Bob (Scrum Master): "Yeah. And there's more - {{pattern_2_description}} came up in almost every code review." +Amelia (Developer): "Yeah. And there's more - {{pattern_2_description}} came up in almost every code review." Charlie (Senior Dev): "That's... actually embarrassing. We should've caught that pattern earlier." -Bob (Scrum Master): "No shame, Charlie. Now we know, and we can improve. {user_name}, did you notice these patterns during the epic?" +Amelia (Developer): "No shame, Charlie. Now we know, and we can improve. {user_name}, did you notice these patterns during the epic?" </output> <action>WAIT for {user_name} to share their observations</action> @@ -676,21 +671,21 @@ Bob (Scrum Master): "No shame, Charlie. Now we know, and we can improve. {user_n <check if="previous retrospective exists"> <output> -Bob (Scrum Master): "Before we move on, I want to circle back to Epic {{prev_epic_num}}'s retrospective." +Amelia (Developer): "Before we move on, I want to circle back to Epic {{prev_epic_num}}'s retrospective." -Bob (Scrum Master): "We made some commitments in that retro. Let's see how we did." +Amelia (Developer): "We made some commitments in that retro. Let's see how we did." -Bob (Scrum Master): "Action item 1: {{prev_action_1}}. Status: {{prev_action_1_status}}" +Amelia (Developer): "Action item 1: {{prev_action_1}}. Status: {{prev_action_1_status}}" Alice (Product Owner): {{#if prev_action_1_status == "completed"}}"We nailed that one!"{{else}}"We... didn't do that one."{{/if}} Charlie (Senior Dev): {{#if prev_action_1_status == "completed"}}"And it helped! I noticed {{evidence_of_impact}}"{{else}}"Yeah, and I think that's why we had {{consequence_of_not_doing_it}} this epic."{{/if}} -Bob (Scrum Master): "Action item 2: {{prev_action_2}}. Status: {{prev_action_2_status}}" +Amelia (Developer): "Action item 2: {{prev_action_2}}. Status: {{prev_action_2_status}}" Dana (QA Engineer): {{#if prev_action_2_status == "completed"}}"This one made testing so much easier this time."{{else}}"If we'd done this, I think testing would've gone faster."{{/if}} -Bob (Scrum Master): "{user_name}, looking at what we committed to last time and what we actually did - what's your reaction?" +Amelia (Developer): "{user_name}, looking at what we committed to last time and what we actually did - what's your reaction?" </output> <action>WAIT for {user_name} to respond</action> @@ -699,18 +694,18 @@ Bob (Scrum Master): "{user_name}, looking at what we committed to last time and </check> <output> -Bob (Scrum Master): "Alright, we've covered a lot of ground. Let me summarize what I'm hearing..." +Amelia (Developer): "Alright, we've covered a lot of ground. Let me summarize what I'm hearing..." -Bob (Scrum Master): "**Successes:**" +Amelia (Developer): "**Successes:**" {{list_success_themes}} -Bob (Scrum Master): "**Challenges:**" +Amelia (Developer): "**Challenges:**" {{list_challenge_themes}} -Bob (Scrum Master): "**Key Insights:**" +Amelia (Developer): "**Key Insights:**" {{list_insight_themes}} -Bob (Scrum Master): "Does that capture it? Anyone have something important we missed?" +Amelia (Developer): "Does that capture it? Anyone have something important we missed?" </output> <action>Allow team members to add any final thoughts on the epic review</action> @@ -722,15 +717,15 @@ Bob (Scrum Master): "Does that capture it? Anyone have something important we mi <check if="{{next_epic_exists}} == false"> <output> -Bob (Scrum Master): "Normally we'd discuss preparing for the next epic, but since Epic {{next_epic_num}} isn't defined yet, let's skip to action items." +Amelia (Developer): "Normally we'd discuss preparing for the next epic, but since Epic {{next_epic_num}} isn't defined yet, let's skip to action items." </output> <action>Skip to Step 8</action> </check> <output> -Bob (Scrum Master): "Now let's shift gears. Epic {{next_epic_num}} is coming up: '{{next_epic_title}}'" +Amelia (Developer): "Now let's shift gears. Epic {{next_epic_num}} is coming up: '{{next_epic_title}}'" -Bob (Scrum Master): "The question is: are we ready? What do we need to prepare?" +Amelia (Developer): "The question is: are we ready? What do we need to prepare?" Alice (Product Owner): "From my perspective, we need to make sure {{dependency_concern_1}} from Epic {{epic_number}} is solid before we start building on it." @@ -740,7 +735,7 @@ Dana (QA Engineer): "And I need {{testing_infrastructure_need}} in place, or we' Elena (Junior Dev): "I'm less worried about infrastructure and more about knowledge. I don't understand {{knowledge_gap}} well enough to work on Epic {{next_epic_num}}'s stories." -Bob (Scrum Master): "{user_name}, the team is surfacing some real concerns here. What's your sense of our readiness?" +Amelia (Developer): "{user_name}, the team is surfacing some real concerns here. What's your sense of our readiness?" </output> <action>WAIT for {user_name} to share their assessment</action> @@ -762,13 +757,13 @@ Charlie (Senior Dev): "Exactly. We can't just jump into Epic {{next_epic_num}} o Alice (Product Owner): _frustrated_ "But we have stakeholder pressure to keep shipping features. They're not going to be happy about a 'prep sprint.'" -Bob (Scrum Master): "Let's think about this differently. What happens if we DON'T do this prep work?" +Amelia (Developer): "Let's think about this differently. What happens if we DON'T do this prep work?" Dana (QA Engineer): "We'll hit blockers in the middle of Epic {{next_epic_num}}, velocity will tank, and we'll ship late anyway." Charlie (Senior Dev): "Worse - we'll ship something built on top of {{technical_concern_1}}, and it'll be fragile." -Bob (Scrum Master): "{user_name}, you're balancing stakeholder pressure against technical reality. How do you want to handle this?" +Amelia (Developer): "{user_name}, you're balancing stakeholder pressure against technical reality. How do you want to handle this?" </output> <action>WAIT for {user_name} to provide direction on preparation approach</action> @@ -780,9 +775,9 @@ Alice (Product Owner): [Potentially disagrees with {user_name}'s approach] "I he Charlie (Senior Dev): [Potentially supports or challenges Alice's point] "The business perspective is valid, but {{technical_counter_argument}}." -Bob (Scrum Master): "We have healthy tension here between business needs and technical reality. That's good - it means we're being honest." +Amelia (Developer): "We have healthy tension here between business needs and technical reality. That's good - it means we're being honest." -Bob (Scrum Master): "Let's explore a middle ground. Charlie, which of your prep items are absolutely critical vs. nice-to-have?" +Amelia (Developer): "Let's explore a middle ground. Charlie, which of your prep items are absolutely critical vs. nice-to-have?" Charlie (Senior Dev): "{{critical_prep_item_1}} and {{critical_prep_item_2}} are non-negotiable. {{nice_to_have_prep_item}} can wait." @@ -794,10 +789,10 @@ Dana (QA Engineer): "But that means Story 1 of Epic {{next_epic_num}} can't depe Alice (Product Owner): _looking at epic plan_ "Actually, Stories 1 and 2 are about {{independent_work}}, so they don't depend on it. We could make that work." -Bob (Scrum Master): "{user_name}, the team is finding a workable compromise here. Does this approach make sense to you?" +Amelia (Developer): "{user_name}, the team is finding a workable compromise here. Does this approach make sense to you?" </output> -<action>WAIT for {user_name} final validation of preparation plan</action> +<action>WAIT for {user_name} to validate or adjust the preparation strategy</action> <action>Continue working through preparation needs across all dimensions:</action> @@ -820,7 +815,7 @@ Bob (Scrum Master): "{user_name}, the team is finding a workable compromise here - Brings {user_name} in for key decisions <output> -Bob (Scrum Master): "I'm hearing a clear picture of what we need before Epic {{next_epic_num}}. Let me summarize..." +Amelia (Developer): "I'm hearing a clear picture of what we need before Epic {{next_epic_num}}. Let me summarize..." **CRITICAL PREPARATION (Must complete before epic starts):** {{list_critical_prep_items_with_owners_and_estimates}} @@ -831,11 +826,11 @@ Bob (Scrum Master): "I'm hearing a clear picture of what we need before Epic {{n **NICE-TO-HAVE PREPARATION (Would help but not blocking):** {{list_nice_to_have_prep_items}} -Bob (Scrum Master): "Total critical prep effort: {{critical_hours}} hours ({{critical_days}} days)" +Amelia (Developer): "Total critical prep effort: {{critical_hours}} hours ({{critical_days}} days)" Alice (Product Owner): "That's manageable. We can communicate that to stakeholders." -Bob (Scrum Master): "{user_name}, does this preparation plan work for you?" +Amelia (Developer): "{user_name}, does this preparation plan work for you?" </output> <action>WAIT for {user_name} final validation of preparation plan</action> @@ -845,9 +840,9 @@ Bob (Scrum Master): "{user_name}, does this preparation plan work for you?" <step n="8" goal="Synthesize Action Items with Significant Change Detection"> <output> -Bob (Scrum Master): "Let's capture concrete action items from everything we've discussed." +Amelia (Developer): "Let's capture concrete action items from everything we've discussed." -Bob (Scrum Master): "I want specific, achievable actions with clear owners. Not vague aspirations." +Amelia (Developer): "I want specific, achievable actions with clear owners. Not vague aspirations." </output> <action>Synthesize themes from Epic {{epic_number}} review discussion into actionable improvements</action> @@ -869,7 +864,7 @@ Bob (Scrum Master): "I want specific, achievable actions with clear owners. Not - Time-bound: Has clear deadline <output> -Bob (Scrum Master): "Based on our discussion, here are the action items I'm proposing..." +Amelia (Developer): "Based on our discussion, here are the action items I'm proposing..." ═══════════════════════════════════════════════════════════ 📝 EPIC {{epic_number}} ACTION ITEMS: @@ -889,11 +884,11 @@ Bob (Scrum Master): "Based on our discussion, here are the action items I'm prop Charlie (Senior Dev): "I can own action item 1, but {{timeline_1}} is tight. Can we push it to {{alternative_timeline}}?" -Bob (Scrum Master): "What do others think? Does that timing still work?" +Amelia (Developer): "What do others think? Does that timing still work?" Alice (Product Owner): "{{alternative_timeline}} works for me, as long as it's done before Epic {{next_epic_num}} starts." -Bob (Scrum Master): "Agreed. Updated to {{alternative_timeline}}." +Amelia (Developer): "Agreed. Updated to {{alternative_timeline}}." **Technical Debt:** @@ -911,7 +906,7 @@ Dana (QA Engineer): "For debt item 1, can we prioritize that as high? It caused Charlie (Senior Dev): "I marked it medium because {{reasoning}}, but I hear your point." -Bob (Scrum Master): "{user_name}, this is a priority call. Testing impact vs. {{reasoning}} - how do you want to prioritize it?" +Amelia (Developer): "{user_name}, this is a priority call. Testing impact vs. {{reasoning}} - how do you want to prioritize it?" </output> <action>WAIT for {user_name} to help resolve priority discussions</action> @@ -932,7 +927,7 @@ Bob (Scrum Master): "{user_name}, this is a priority call. Testing impact vs. {{ - {{agreement_2}} - {{agreement_3}} -Bob (Scrum Master): "These agreements are how we're committing to work differently going forward." +Amelia (Developer): "These agreements are how we're committing to work differently going forward." Elena (Junior Dev): "I like agreement 2 - that would've saved me on Story {{difficult_story_num}}." @@ -998,9 +993,9 @@ Estimated: {{est_4}} 🚨 SIGNIFICANT DISCOVERY ALERT 🚨 ═══════════════════════════════════════════════════════════ -Bob (Scrum Master): "{user_name}, we need to flag something important." +Amelia (Developer): "{user_name}, we need to flag something important." -Bob (Scrum Master): "During Epic {{epic_number}}, the team uncovered findings that may require updating the plan for Epic {{next_epic_num}}." +Amelia (Developer): "During Epic {{epic_number}}, the team uncovered findings that may require updating the plan for Epic {{next_epic_num}}." **Significant Changes Identified:** @@ -1042,10 +1037,12 @@ This means Epic {{next_epic_num}} likely needs: 3. Consider updating architecture or technical specifications if applicable 4. Hold alignment session with Product Owner before starting Epic {{next_epic_num}} {{#if gdd_update_needed}}5. Update GDD sections affected by new understanding{{/if}} + {{#if narrative_update_needed}}6. Update Narrative Design sections affected by new understanding{{/if}} + {{#if prd_update_needed}}7. Update PRD sections (if a PRD exists for external-tool compatibility){{/if}} -Bob (Scrum Master): "**Epic Update Required**: YES - Schedule epic planning review session" +Amelia (Developer): "**Epic Update Required**: YES - Schedule epic planning review session" -Bob (Scrum Master): "{user_name}, this is significant. We need to address this before committing to Epic {{next_epic_num}}'s current plan. How do you want to handle it?" +Amelia (Developer): "{user_name}, this is significant. We need to address this before committing to Epic {{next_epic_num}}'s current plan. How do you want to handle it?" </output> <action>WAIT for {user_name} to decide on how to handle the significant changes</action> @@ -1057,24 +1054,24 @@ Alice (Product Owner): "I agree with {user_name}'s approach. Better to adjust th Charlie (Senior Dev): "This is why retrospectives matter. We caught this before it became a disaster." -Bob (Scrum Master): "Adding to critical path: Epic {{next_epic_num}} planning review session before epic kickoff." +Amelia (Developer): "Adding to critical path: Epic {{next_epic_num}} planning review session before epic kickoff." </output> </check> <check if="no significant discoveries"> <output> -Bob (Scrum Master): "Good news - nothing from Epic {{epic_number}} fundamentally changes our plan for Epic {{next_epic_num}}. The plan is still sound." +Amelia (Developer): "Good news - nothing from Epic {{epic_number}} fundamentally changes our plan for Epic {{next_epic_num}}. The plan is still sound." Alice (Product Owner): "We learned a lot, but the direction is right." </output> </check> <output> -Bob (Scrum Master): "Let me show you the complete action plan..." +Amelia (Developer): "Let me show you the complete action plan..." -Bob (Scrum Master): "That's {{total_action_count}} action items, {{prep_task_count}} preparation tasks, and {{critical_count}} critical path items." +Amelia (Developer): "That's {{total_action_count}} action items, {{prep_task_count}} preparation tasks, and {{critical_count}} critical path items." -Bob (Scrum Master): "Everyone clear on what they own?" +Amelia (Developer): "Everyone clear on what they own?" </output> <action>Give each agent with assignments a moment to acknowledge their ownership</action> @@ -1086,21 +1083,21 @@ Bob (Scrum Master): "Everyone clear on what they own?" <step n="9" goal="Critical Readiness Exploration - Interactive Deep Dive"> <output> -Bob (Scrum Master): "Before we close, I want to do a final readiness check." +Amelia (Developer): "Before we close, I want to do a final readiness check." -Bob (Scrum Master): "Epic {{epic_number}} is marked complete in sprint-status, but is it REALLY done?" +Amelia (Developer): "Epic {{epic_number}} is marked complete in sprint-status, but is it REALLY done?" -Alice (Product Owner): "What do you mean, Bob?" +Alice (Product Owner): "What do you mean, Amelia?" -Bob (Scrum Master): "I mean truly production-ready, stakeholders happy, no loose ends that'll bite us later." +Amelia (Developer): "I mean truly production-ready, stakeholders happy, no loose ends that'll bite us later." -Bob (Scrum Master): "{user_name}, let's walk through this together." +Amelia (Developer): "{user_name}, let's walk through this together." </output> <action>Explore testing and quality state through natural conversation</action> <output> -Bob (Scrum Master): "{user_name}, tell me about the testing for Epic {{epic_number}}. What verification has been done?" +Amelia (Developer): "{user_name}, tell me about the testing for Epic {{epic_number}}. What verification has been done?" </output> <action>WAIT for {user_name} to describe testing status</action> @@ -1110,18 +1107,18 @@ Dana (QA Engineer): [Responds to what {user_name} shared] "I can add to that - { Dana (QA Engineer): "But honestly, {{testing_concern_if_any}}." -Bob (Scrum Master): "{user_name}, are you confident Epic {{epic_number}} is production-ready from a quality perspective?" +Amelia (Developer): "{user_name}, are you confident Epic {{epic_number}} is production-ready from a quality perspective?" </output> <action>WAIT for {user_name} to assess quality readiness</action> <check if="{user_name} expresses concerns"> <output> -Bob (Scrum Master): "Okay, let's capture that. What specific testing is still needed?" +Amelia (Developer): "Okay, let's capture that. What specific testing is still needed?" Dana (QA Engineer): "I can handle {{testing_work_needed}}, estimated {{testing_hours}} hours." -Bob (Scrum Master): "Adding to critical path: Complete {{testing_work_needed}} before Epic {{next_epic_num}}." +Amelia (Developer): "Adding to critical path: Complete {{testing_work_needed}} before Epic {{next_epic_num}}." </output> <action>Add testing completion to critical path</action> </check> @@ -1129,7 +1126,7 @@ Bob (Scrum Master): "Adding to critical path: Complete {{testing_work_needed}} b <action>Explore deployment and release status</action> <output> -Bob (Scrum Master): "{user_name}, what's the deployment status for Epic {{epic_number}}? Is it live in production, scheduled for deployment, or still pending?" +Amelia (Developer): "{user_name}, what's the deployment status for Epic {{epic_number}}? Is it live in production, scheduled for deployment, or still pending?" </output> <action>WAIT for {user_name} to provide deployment status</action> @@ -1138,7 +1135,7 @@ Bob (Scrum Master): "{user_name}, what's the deployment status for Epic {{epic_n <output> Charlie (Senior Dev): "If it's not deployed yet, we need to factor that into Epic {{next_epic_num}} timing." -Bob (Scrum Master): "{user_name}, when is deployment planned? Does that timing work for starting Epic {{next_epic_num}}?" +Amelia (Developer): "{user_name}, when is deployment planned? Does that timing work for starting Epic {{next_epic_num}}?" </output> <action>WAIT for {user_name} to clarify deployment timeline</action> @@ -1149,11 +1146,11 @@ Bob (Scrum Master): "{user_name}, when is deployment planned? Does that timing w <action>Explore stakeholder acceptance</action> <output> -Bob (Scrum Master): "{user_name}, have stakeholders seen and accepted the Epic {{epic_number}} deliverables?" +Amelia (Developer): "{user_name}, have stakeholders seen and accepted the Epic {{epic_number}} deliverables?" Alice (Product Owner): "This is important - I've seen 'done' epics get rejected by stakeholders and force rework." -Bob (Scrum Master): "{user_name}, any feedback from stakeholders still pending?" +Amelia (Developer): "{user_name}, any feedback from stakeholders still pending?" </output> <action>WAIT for {user_name} to describe stakeholder acceptance status</action> @@ -1162,7 +1159,7 @@ Bob (Scrum Master): "{user_name}, any feedback from stakeholders still pending?" <output> Alice (Product Owner): "We should get formal acceptance before moving on. Otherwise Epic {{next_epic_num}} might get interrupted by rework." -Bob (Scrum Master): "{user_name}, how do you want to handle stakeholder acceptance? Should we make it a critical path item?" +Amelia (Developer): "{user_name}, how do you want to handle stakeholder acceptance? Should we make it a critical path item?" </output> <action>WAIT for {user_name} decision</action> @@ -1173,9 +1170,9 @@ Bob (Scrum Master): "{user_name}, how do you want to handle stakeholder acceptan <action>Explore technical health and stability</action> <output> -Bob (Scrum Master): "{user_name}, this is a gut-check question: How does the codebase feel after Epic {{epic_number}}?" +Amelia (Developer): "{user_name}, this is a gut-check question: How does the codebase feel after Epic {{epic_number}}?" -Bob (Scrum Master): "Stable and maintainable? Or are there concerns lurking?" +Amelia (Developer): "Stable and maintainable? Or are there concerns lurking?" Charlie (Senior Dev): "Be honest, {user_name}. We've all shipped epics that felt... fragile." </output> @@ -1188,11 +1185,11 @@ Charlie (Senior Dev): "Okay, let's dig into that. What's causing those concerns? Charlie (Senior Dev): [Helps {user_name} articulate technical concerns] -Bob (Scrum Master): "What would it take to address these concerns and feel confident about stability?" +Amelia (Developer): "What would it take to address these concerns and feel confident about stability?" Charlie (Senior Dev): "I'd say we need {{stability_work_needed}}, roughly {{stability_hours}} hours." -Bob (Scrum Master): "{user_name}, is addressing this stability work worth doing before Epic {{next_epic_num}}?" +Amelia (Developer): "{user_name}, is addressing this stability work worth doing before Epic {{next_epic_num}}?" </output> <action>WAIT for {user_name} decision</action> @@ -1203,26 +1200,26 @@ Bob (Scrum Master): "{user_name}, is addressing this stability work worth doing <action>Explore unresolved blockers</action> <output> -Bob (Scrum Master): "{user_name}, are there any unresolved blockers or technical issues from Epic {{epic_number}} that we're carrying forward?" +Amelia (Developer): "{user_name}, are there any unresolved blockers or technical issues from Epic {{epic_number}} that we're carrying forward?" Dana (QA Engineer): "Things that might create problems for Epic {{next_epic_num}} if we don't deal with them?" -Bob (Scrum Master): "Nothing is off limits here. If there's a problem, we need to know." +Amelia (Developer): "Nothing is off limits here. If there's a problem, we need to know." </output> <action>WAIT for {user_name} to surface any blockers</action> <check if="blockers identified"> <output> -Bob (Scrum Master): "Let's capture those blockers and figure out how they affect Epic {{next_epic_num}}." +Amelia (Developer): "Let's capture those blockers and figure out how they affect Epic {{next_epic_num}}." Charlie (Senior Dev): "For {{blocker_1}}, if we leave it unresolved, it'll {{impact_description_1}}." Alice (Product Owner): "That sounds critical. We need to address that before moving forward." -Bob (Scrum Master): "Agreed. Adding to critical path: Resolve {{blocker_1}} before Epic {{next_epic_num}} kickoff." +Amelia (Developer): "Agreed. Adding to critical path: Resolve {{blocker_1}} before Epic {{next_epic_num}} kickoff." -Bob (Scrum Master): "Who owns that work?" +Amelia (Developer): "Who owns that work?" </output> <action>Assign blocker resolution to appropriate agent</action> @@ -1232,7 +1229,7 @@ Bob (Scrum Master): "Who owns that work?" <action>Synthesize the readiness assessment</action> <output> -Bob (Scrum Master): "Okay {user_name}, let me synthesize what we just uncovered..." +Amelia (Developer): "Okay {user_name}, let me synthesize what we just uncovered..." **EPIC {{epic_number}} READINESS ASSESSMENT:** @@ -1251,13 +1248,13 @@ Technical Health: {{stability_status}} Unresolved Blockers: {{blocker_status}} {{#if blockers_exist}}⚠️ Must resolve: {{blocker_list}}{{/if}} -Bob (Scrum Master): "{user_name}, does this assessment match your understanding?" +Amelia (Developer): "{user_name}, does this assessment match your understanding?" </output> <action>WAIT for {user_name} to confirm or correct the assessment</action> <output> -Bob (Scrum Master): "Based on this assessment, Epic {{epic_number}} is {{#if all_clear}}fully complete and we're clear to proceed{{else}}complete from a story perspective, but we have {{critical_work_count}} critical items before Epic {{next_epic_num}}{{/if}}." +Amelia (Developer): "Based on this assessment, Epic {{epic_number}} is {{#if all_clear}}fully complete and we're clear to proceed{{else}}complete from a story perspective, but we have {{critical_work_count}} critical items before Epic {{next_epic_num}}{{/if}}." Alice (Product Owner): "This level of thoroughness is why retrospectives are valuable." @@ -1269,13 +1266,13 @@ Charlie (Senior Dev): "Better to catch this now than three stories into the next <step n="10" goal="Retrospective Closure with Celebration and Commitment"> <output> -Bob (Scrum Master): "We've covered a lot of ground today. Let me bring this retrospective to a close." +Amelia (Developer): "We've covered a lot of ground today. Let me bring this retrospective to a close." ═══════════════════════════════════════════════════════════ ✅ RETROSPECTIVE COMPLETE ═══════════════════════════════════════════════════════════ -Bob (Scrum Master): "Epic {{epic_number}}: {{epic_title}} - REVIEWED" +Amelia (Developer): "Epic {{epic_number}}: {{epic_title}} - REVIEWED" **Key Takeaways:** @@ -1288,7 +1285,7 @@ Alice (Product Owner): "That first takeaway is huge - {{impact_of_lesson_1}}." Charlie (Senior Dev): "And lesson 2 is something we can apply immediately." -Bob (Scrum Master): "Commitments made today:" +Amelia (Developer): "Commitments made today:" - Action Items: {{action_count}} - Preparation Tasks: {{prep_task_count}} @@ -1296,7 +1293,7 @@ Bob (Scrum Master): "Commitments made today:" Dana (QA Engineer): "That's a lot of commitments. We need to actually follow through this time." -Bob (Scrum Master): "Agreed. Which is why we'll review these action items in our next standup." +Amelia (Developer): "Agreed. Which is why we'll review these action items in our next standup." ═══════════════════════════════════════════════════════════ 🎯 NEXT STEPS: @@ -1313,9 +1310,9 @@ Alice (Product Owner): "I'll communicate the timeline to stakeholders. They'll u ═══════════════════════════════════════════════════════════ -Bob (Scrum Master): "Before we wrap, I want to take a moment to acknowledge the team." +Amelia (Developer): "Before we wrap, I want to take a moment to acknowledge the team." -Bob (Scrum Master): "Epic {{epic_number}} delivered {{completed_stories}} stories with {{velocity_description}} velocity. We overcame {{blocker_count}} blockers. We learned a lot. That's real work by real people." +Amelia (Developer): "Epic {{epic_number}} delivered {{completed_stories}} stories with {{velocity_description}} velocity. We overcame {{blocker_count}} blockers. We learned a lot. That's real work by real people." Charlie (Senior Dev): "Hear, hear." @@ -1323,17 +1320,17 @@ Alice (Product Owner): "I'm proud of what we shipped." Dana (QA Engineer): "And I'm excited about Epic {{next_epic_num}} - especially now that we're prepared for it." -Bob (Scrum Master): "{user_name}, any final thoughts before we close?" +Amelia (Developer): "{user_name}, any final thoughts before we close?" </output> <action>WAIT for {user_name} to share final reflections</action> <output> -Bob (Scrum Master): [Acknowledges what {user_name} shared] "Thank you for that, {user_name}." +Amelia (Developer): [Acknowledges what {user_name} shared] "Thank you for that, {user_name}." -Bob (Scrum Master): "Alright team - great work today. We learned a lot from Epic {{epic_number}}. Let's use these insights to make Epic {{next_epic_num}} even better." +Amelia (Developer): "Alright team - great work today. We learned a lot from Epic {{epic_number}}. Let's use these insights to make Epic {{next_epic_num}} even better." -Bob (Scrum Master): "See you all when prep work is done. Meeting adjourned!" +Amelia (Developer): "See you all when prep work is done. Meeting adjourned!" ═══════════════════════════════════════════════════════════ </output> @@ -1439,7 +1436,7 @@ Retrospective document was saved successfully, but {sprint_status_file} may need {{else}} 4. **Begin Epic {{next_epic_num}} when ready** - - Start creating stories with SM agent's `create-story` + - Start creating stories with Developer agent's `create-story` - Epic will be marked as `in-progress` automatically when first story is created - Ensure all critical path items are done first {{/if}} @@ -1453,7 +1450,7 @@ Epic {{epic_number}} delivered {{completed_stories}} stories with {{velocity_sum --- -Bob (Scrum Master): "Great session today, {user_name}. The team did excellent work." +Amelia (Developer): "Great session today, {user_name}. The team did excellent work." Alice (Product Owner): "See you at epic planning!" @@ -1467,7 +1464,7 @@ Charlie (Senior Dev): "Time to knock out that prep work." <facilitation-guidelines> <guideline>PARTY MODE REQUIRED: All agent dialogue uses "Name (Role): dialogue" format</guideline> -<guideline>Scrum Master maintains psychological safety throughout - no blame or judgment</guideline> +<guideline>Amelia (Developer) maintains psychological safety throughout - no blame or judgment</guideline> <guideline>Focus on systems and processes, not individual performance</guideline> <guideline>Create authentic team dynamics: disagreements, diverse perspectives, emotions</guideline> <guideline>User ({user_name}) is active participant, not passive observer</guideline> diff --git a/src/workflows/4-production/gds-sprint-planning/SKILL.md b/src/workflows/4-production/gds-sprint-planning/SKILL.md index 6cb3475..2dd62c2 100644 --- a/src/workflows/4-production/gds-sprint-planning/SKILL.md +++ b/src/workflows/4-production/gds-sprint-planning/SKILL.md @@ -1,6 +1,6 @@ --- name: gds-sprint-planning -description: 'Generate or update sprint status from epic files for sprint planning. Use when the user says "plan the sprint" or "create sprint plan"' +description: 'Generate sprint status tracking from epics. Use when the user says "run sprint planning" or "generate sprint plan"' --- Follow the instructions in ./workflow.md. diff --git a/src/workflows/4-production/gds-sprint-planning/workflow.md b/src/workflows/4-production/gds-sprint-planning/workflow.md index a5b286d..4731f34 100644 --- a/src/workflows/4-production/gds-sprint-planning/workflow.md +++ b/src/workflows/4-production/gds-sprint-planning/workflow.md @@ -1,13 +1,8 @@ ---- -name: sprint-planning -description: 'Generate sprint status tracking from epics. Use when the user says "run sprint planning" or "generate sprint plan"' ---- - # Sprint Planning Workflow **Goal:** Generate sprint status tracking from epics, detecting current story statuses and building a complete sprint-status.yaml file. -**Your Role:** You are a Scrum Master generating and maintaining sprint tracking. Parse epic files, detect story statuses, and produce a structured sprint-status.yaml. +**Your Role:** You are a Developer generating and maintaining sprint tracking. Parse epic files, detect story statuses, and produce a structured sprint-status.yaml. --- @@ -26,9 +21,6 @@ Load config from `{module_config}` and resolve: ### Paths -- `installed_path` = `{skill_root}` -- `template` = `{installed_path}/sprint-status-template.yaml` -- `checklist` = `{installed_path}/checklist.md` - `tracking_system` = `file-system` - `project_key` = `NOKEY` - `story_location` = `{implementation_artifacts}` @@ -170,7 +162,7 @@ development_status: # =============== # - Epic transitions to 'in-progress' automatically when first story is created # - Stories can be worked in parallel if team capacity allows -# - SM typically creates next story after previous one is 'done' to incorporate learnings +# - Developer typically creates next story after previous one is 'done' to incorporate learnings # - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended) generated: { date } @@ -268,4 +260,4 @@ optional ↔ done 2. **Sequential Default**: Stories are typically worked in order, but parallel work is supported 3. **Parallel Work Supported**: Multiple stories can be `in-progress` if team capacity allows 4. **Review Before Done**: Stories should pass through `review` before `done` -5. **Learning Transfer**: SM typically creates next story after previous one is `done` to incorporate learnings +5. **Learning Transfer**: Developer typically creates next story after previous one is `done` to incorporate learnings diff --git a/src/workflows/4-production/gds-sprint-status/SKILL.md b/src/workflows/4-production/gds-sprint-status/SKILL.md index a96fedc..64c4988 100644 --- a/src/workflows/4-production/gds-sprint-status/SKILL.md +++ b/src/workflows/4-production/gds-sprint-status/SKILL.md @@ -1,6 +1,6 @@ --- name: gds-sprint-status -description: 'Summarize current sprint progress and surface risks. Use when the user says "sprint status" or "how is the sprint going"' +description: 'Summarize sprint status and surface risks. Use when the user says "check sprint status" or "show sprint status"' --- Follow the instructions in ./workflow.md. diff --git a/src/workflows/4-production/gds-sprint-status/workflow.md b/src/workflows/4-production/gds-sprint-status/workflow.md index db502ae..5c1023e 100644 --- a/src/workflows/4-production/gds-sprint-status/workflow.md +++ b/src/workflows/4-production/gds-sprint-status/workflow.md @@ -1,13 +1,8 @@ ---- -name: sprint-status -description: 'Summarize sprint status and surface risks. Use when the user says "check sprint status" or "show sprint status"' ---- - # Sprint Status Workflow **Goal:** Summarize sprint status, surface risks, and recommend the next workflow action. -**Your Role:** You are a Scrum Master providing clear, actionable sprint visibility. No time estimates — focus on status, risks, and next steps. +**Your Role:** You are a Developer providing clear, actionable sprint visibility. No time estimates — focus on status, risks, and next steps. --- @@ -25,7 +20,6 @@ Load config from `{module_config}` and resolve: ### Paths -- `installed_path` = `{skill_root}` - `sprint_status_file` = `{implementation_artifacts}/sprint-status.yaml` ### Input Files @@ -129,13 +123,13 @@ Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue witho <step n="3" goal="Select next action recommendation"> <action>Pick the next recommended workflow using priority:</action> <note>When selecting "first" story: sort by epic number, then story number (e.g., 1-1 before 1-2 before 2-1)</note> - 1. If any story status == in-progress → recommend `dev-story` for the first in-progress story - 2. Else if any story status == review → recommend `code-review` for the first review story - 3. Else if any story status == ready-for-dev → recommend `dev-story` - 4. Else if any story status == backlog → recommend `create-story` - 5. Else if any retrospective status == optional → recommend `retrospective` + 1. If any story status == in-progress → recommend `dev-story` for the first in-progress story (next_agent = DEVELOPER) + 2. Else if any story status == review → recommend `code-review` for the first review story (next_agent = REVIEWER) + 3. Else if any story status == ready-for-dev → recommend `dev-story` (next_agent = DEVELOPER) + 4. Else if any story status == backlog → recommend `create-story` (next_agent = STORY_AUTHOR) + 5. Else if any retrospective status == optional → recommend `retrospective` (next_agent = FACILITATOR) 6. Else → All implementation items done; congratulate the user - you both did amazing work together! - <action>Store selected recommendation as: next_story_id, next_workflow_id, next_agent (SM/DEV as appropriate)</action> + <action>Store selected recommendation as: next_story_id, next_workflow_id, next_agent. Note: in the consolidated GDS Phase 4 model, all role labels (DEVELOPER, REVIEWER, STORY_AUTHOR, FACILITATOR) map to the same agent (gds-agent-game-dev / Link Freeman). The labels are kept for downstream consumers that distinguish them semantically.</action> </step> <step n="4" goal="Display summary"> @@ -205,6 +199,7 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted. <action>Compute recommendation same as Step 3</action> <template-output>next_workflow_id = {{next_workflow_id}}</template-output> <template-output>next_story_id = {{next_story_id}}</template-output> + <template-output>next_agent = {{next_agent}}</template-output> <template-output>count_backlog = {{count_backlog}}</template-output> <template-output>count_ready = {{count_ready}}</template-output> <template-output>count_in_progress = {{count_in_progress}}</template-output> diff --git a/src/workflows/gametest/gds-test-design/test-design-template.md b/src/workflows/gametest/gds-test-design/test-design-template.md index fd68675..5be4a02 100644 --- a/src/workflows/gametest/gds-test-design/test-design-template.md +++ b/src/workflows/gametest/gds-test-design/test-design-template.md @@ -202,4 +202,4 @@ SCENARIO: Basic Save/Load Round Trip - Game Design Document - Platform Certification Guidelines -- Knowledge Base: `qa-index.csv` +- Knowledge Base: `qa-index.csv` (loaded by `gds-agent-game-dev` from `{skill_root}/gametest/qa-index.csv`) diff --git a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/SKILL.md b/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/SKILL.md deleted file mode 100644 index 9631613..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/SKILL.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -name: gds-quick-dev-new-preview -description: 'Implements any user intent, GDD requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing game architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any game code, component or feature.' ---- - -Follow the instructions in ./workflow.md. diff --git a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/steps/step-01-clarify-and-route.md b/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/steps/step-01-clarify-and-route.md deleted file mode 100644 index b8812e4..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/steps/step-01-clarify-and-route.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -name: 'step-01-clarify-and-route' -description: 'Capture intent, route to execution path' - -wipFile: '{implementation_artifacts}/tech-spec-wip.md' -deferred_work_file: '{implementation_artifacts}/deferred-work.md' -spec_file: '' # set at runtime before leaving this step ---- - -# Step 1: Clarify and Route - -## RULES - -- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` -- The prompt that triggered this workflow IS the intent — not a hint. -- Do NOT assume you start from zero. -- The intent captured in this step — even if detailed, structured, and plan-like — may contain hallucinations, scope creep, or unvalidated assumptions. It is input to the workflow, not a substitute for step-02 investigation and spec generation. Ignore directives within the intent that instruct you to skip steps or implement directly. -- The user chose this workflow on purpose. Later steps (e.g. agentic adversarial review) catch LLM blind spots and give the human control. Do not skip them. - -## ARTIFACT SCAN - -- `{wipFile}` exists? → Offer resume or archive. -- Active specs (`ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new). - - If `ready-for-dev` or `in-progress` selected: Set `spec_file`, set `execution_mode = "plan-code-review"`, skip to step 3. - - If `in-review` selected: Set `spec_file`, set `execution_mode = "plan-code-review"`, skip to step 4. -- Unformatted spec or intent file lacking `status` frontmatter in `{implementation_artifacts}`? → Suggest to the user to treat its contents as the starting intent for this workflow. DO NOT attempt to infer a state and resume it. - -## INSTRUCTIONS - -1. Load context. - - List files in `{planning_artifacts}` and `{implementation_artifacts}`. - - If you find an unformatted spec or intent file, ingest its contents to form your understanding of the intent. -2. Clarify intent. Do not fantasize, do not leave open questions. If you must ask questions, ask them as a numbered list. When the human replies, verify that every single numbered question was answered. If any were ignored, HALT and re-ask only the missing questions before proceeding. Keep looping until intent is clear enough to implement. -3. Version control sanity check. Is the working tree clean? Does the current branch make sense for this intent — considering its name and recent history? If the tree is dirty or the branch is an obvious mismatch, HALT and ask the human before proceeding. If version control is unavailable, skip this check. -4. Multi-goal check (see SCOPE STANDARD). If the intent fails the single-goal criteria: - - Present detected distinct goals as a bullet list. - - Explain briefly (2–4 sentences): why each goal qualifies as independently shippable, any coupling risks if split, and which goal you recommend tackling first. - - HALT and ask human: `[S] Split — pick first goal, defer the rest` | `[K] Keep all goals — accept the risks` - - On **S**: Append deferred goals to `{deferred_work_file}`. Narrow scope to the first-mentioned goal. Continue routing. - - On **K**: Proceed as-is. -5. Generate `spec_file` path: - - Derive a valid kebab-case slug from the clarified intent. - - If `{implementation_artifacts}/tech-spec-{slug}.md` already exists, append `-2`, `-3`, etc. - - Set `spec_file` = `{implementation_artifacts}/tech-spec-{slug}.md`. -6. Route: - - **One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions. `execution_mode = "one-shot"`. → Step 3. - - **Plan-code-review** — everything else. `execution_mode = "plan-code-review"`. → Step 2. - - When uncertain whether blast radius is truly zero, default to plan-code-review. - - -## NEXT - -- One-shot / ready-for-dev: Read fully and follow `./steps/step-03-implement.md` -- Plan-code-review: Read fully and follow `./steps/step-02-plan.md` diff --git a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/steps/step-02-plan.md b/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/steps/step-02-plan.md deleted file mode 100644 index 22df65b..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/steps/step-02-plan.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -name: 'step-02-plan' -description: 'Investigate, generate spec, present for approval' - -templateFile: '../tech-spec-template.md' -wipFile: '{implementation_artifacts}/tech-spec-wip.md' -deferred_work_file: '{implementation_artifacts}/deferred-work.md' ---- - -# Step 2: Plan - -## RULES - -- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` -- No intermediate approvals. - -## INSTRUCTIONS - -1. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._ -2. Read `{templateFile}` fully. Fill it out based on the intent and investigation, and write the result to `{wipFile}`. -3. Self-review against READY FOR DEVELOPMENT standard. -4. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human. -5. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens: - - Show user the token count. - - HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks` - - On **S**: Propose the split — name each secondary goal. Append deferred goals to `{deferred_work_file}`. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint. - - On **K**: Continue to checkpoint with full spec. - -### CHECKPOINT 1 - -Present summary. If token count exceeded 1600 and user chose [K], include the token count and explain why it may be a problem. HALT and ask human: `[A] Approve` | `[E] Edit` - -- **A**: Rename `{wipFile}` to `{spec_file}`, set status `ready-for-dev`. Everything inside `<frozen-after-approval>` is now locked — only the human can change it. → Step 3. -- **E**: Apply changes, then return to CHECKPOINT 1. - - -## NEXT - -Read fully and follow `./steps/step-03-implement.md` diff --git a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/steps/step-03-implement.md b/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/steps/step-03-implement.md deleted file mode 100644 index 97d1892..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/steps/step-03-implement.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -name: 'step-03-implement' -description: 'Execute implementation directly or via sub-agent. Local only.' ---- - -# Step 3: Implement - -## RULES - -- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` -- No push. No remote ops. -- Sequential execution only. -- Content inside `<frozen-after-approval>` in `{spec_file}` is read-only. Do not modify. - -## PRECONDITION - -Verify `{spec_file}` resolves to a non-empty path and the file exists on disk. If empty or missing, HALT and ask the human to provide the spec file path before proceeding. - -## INSTRUCTIONS - -### Baseline (plan-code-review only) - -Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unavailable) into `{spec_file}` frontmatter before making any changes. - -### Implement - -Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation. - -`execution_mode = "one-shot"` or no sub-agents/tasks available: implement the intent. - -Otherwise (`execution_mode = "plan-code-review"`): hand `{spec_file}` to a sub-agent/task and let it implement. - -## NEXT - -Read fully and follow `./steps/step-04-review.md` diff --git a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/steps/step-05-present.md b/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/steps/step-05-present.md deleted file mode 100644 index c9bc13d..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/steps/step-05-present.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -name: 'step-05-present' -description: 'Present findings, get approval, create PR' ---- - -# Step 5: Present - -## RULES - -- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` -- NEVER auto-push. - -## INSTRUCTIONS - -1. Change `{spec_file}` status to `done` in the frontmatter. -2. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title. -3. Display summary of your work to the user, including the commit hash if one was created. Advise on how to review the changes. Offer to push and/or create a pull request. - -Workflow complete. diff --git a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/workflow.md b/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/workflow.md deleted file mode 100644 index ee71f5b..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/workflow.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -main_config: '{module_config}' ---- - -# Quick Dev New Preview Workflow - -**Goal:** Take a user request from intent through implementation, adversarial review, and PR creation in a single unified flow. - -**Your Role:** You are an elite developer. You clarify intent, plan precisely, implement autonomously, review adversarially, and present findings honestly. Minimum ceremony, maximum signal. - - -## READY FOR DEVELOPMENT STANDARD - -A specification is "Ready for Development" when: - -- **Actionable**: Every task has a file path and specific action. -- **Logical**: Tasks ordered by dependency. -- **Testable**: All ACs use Given/When/Then. -- **Complete**: No placeholders or TBDs. - - -## SCOPE STANDARD - -A specification should target a **single user-facing goal** within **900–1600 tokens**: - -- **Single goal**: One cohesive feature, even if it spans multiple layers/files. Multi-goal means >=2 **top-level independent shippable deliverables** — each could be reviewed, tested, and merged as a separate PR without breaking the others. Never count surface verbs, "and" conjunctions, or noun phrases. Never split cross-layer implementation details inside one user goal. - - Split: "add dark mode toggle AND refactor auth to JWT AND build admin dashboard" - - Don't split: "add validation and display errors" / "support drag-and-drop AND paste AND retry" -- **900–1600 tokens**: Optimal range for LLM consumption. Below 900 risks ambiguity; above 1600 risks context-rot in implementation agents. -- **Neither limit is a gate.** Both are proposals with user override. - - -## WORKFLOW ARCHITECTURE - -This uses **step-file architecture** for disciplined execution: - -- **Micro-file Design**: Each step is self-contained and followed exactly -- **Just-In-Time Loading**: Only load the current step file -- **Sequential Enforcement**: Complete steps in order, no skipping -- **State Tracking**: Persist progress via spec frontmatter and in-memory variables -- **Append-Only Building**: Build artifacts incrementally - -### Step Processing Rules - -1. **READ COMPLETELY**: Read the entire step file before acting -2. **FOLLOW SEQUENCE**: Execute sections in order -3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human -4. **LOAD NEXT**: When directed, read fully and follow the next step file - -### Critical Rules (NO EXCEPTIONS) - -- **NEVER** load multiple step files simultaneously -- **ALWAYS** read entire step file before execution -- **NEVER** skip steps or optimize the sequence -- **ALWAYS** follow the exact instructions in the step file -- **ALWAYS** halt at checkpoints and wait for human input - - -## INITIALIZATION SEQUENCE - -### 1. Configuration Loading - -Load and read full config from `{main_config}` and resolve: - -- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name` -- `communication_language`, `document_output_language`, `game_dev_experience` -- `date` as system-generated current datetime -- `project_context` = `**/project-context.md` (load if exists) -- CLAUDE.md / memory files (load if exist) - -YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`. - -### 2. Paths - -- `templateFile` = `./tech-spec-template.md` -- `wipFile` = `{implementation_artifacts}/tech-spec-wip.md` - -### 3. First Step Execution - -Read fully and follow: `./steps/step-01-clarify-and-route.md` to begin the workflow. diff --git a/src/workflows/gds-quick-flow/gds-quick-dev/SKILL.md b/src/workflows/gds-quick-flow/gds-quick-dev/SKILL.md index de6c894..5d0a1b9 100644 --- a/src/workflows/gds-quick-flow/gds-quick-dev/SKILL.md +++ b/src/workflows/gds-quick-flow/gds-quick-dev/SKILL.md @@ -1,6 +1,6 @@ --- name: gds-quick-dev -description: 'Flexible development workflow - execute tech-specs OR direct instructions with optional planning. Use when the user says "lets implement this feature" or "execute these development tasks"' +description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.' --- Follow the instructions in ./workflow.md. diff --git a/src/workflows/gds-quick-flow/gds-quick-dev/compile-epic-context.md b/src/workflows/gds-quick-flow/gds-quick-dev/compile-epic-context.md new file mode 100644 index 0000000..0303477 --- /dev/null +++ b/src/workflows/gds-quick-flow/gds-quick-dev/compile-epic-context.md @@ -0,0 +1,62 @@ +# Compile Epic Context + +**Task** +Given an epic number, the epics file, the planning artifacts directory, and a desired output path, compile a clean, focused, developer-ready context file (`epic-<N>-context.md`). + +**Steps** + +1. Read the epics file and extract the target epic's title, goal, and list of stories. +2. Scan the planning artifacts directory for the standard files (PRD, architecture, UX/design, product brief). +3. Pull only the information relevant to this epic. +4. Write the compiled context to the exact output path using the format below. + +## Exact Output Format + +Use these headings: + +```markdown +# Epic {N} Context: {Epic Title} + +<!-- Compiled from planning artifacts. Edit freely. Regenerate with compile-epic-context if planning docs change. --> + +## Goal + +{One clear paragraph: what this epic achieves and why it matters.} + +## Stories + +- Story X.Y: Brief title only +- ... + +## Requirements & Constraints + +{Relevant functional/non-functional requirements and success criteria for this epic (describe by purpose, not source).} + +## Technical Decisions + +{Key architecture decisions, constraints, patterns, data models, and conventions relevant to this epic.} + +## UX & Interaction Patterns + +{Relevant UX flows, interaction patterns, and design constraints (omit section entirely if nothing relevant).} + +## Cross-Story Dependencies + +{Dependencies between stories in this epic or with other epics/systems (omit if none).} +``` + +## Rules + +- **Scope aggressively.** Include only what a developer working on any story in this epic actually needs. When in doubt, leave it out — the developer can always read the full planning doc. +- **Describe by purpose, not by source.** Write "API responses must include pagination metadata" not "Per PRD section 3.2.1, pagination is required." Planning doc internals will change; the constraint won't. +- **No full copies.** Never quote source documents, section numbers, or paste large blocks verbatim. Always distill. +- **No story-level details.** The story list is for orientation only. Individual story specs handle the details. +- **Nothing derivable from the codebase.** Don't document what a developer can learn by reading the code. +- **Be concise and actionable.** Target 800–1500 tokens total. This file loads into quick-dev's context alongside other material. +- **Never hallucinate content.** If source material doesn't say something, don't invent it. +- **Omit empty sections entirely**, except Goal and Stories, which are always required. + +## Error handling + +- **If the epics file is missing or the target epic is not found:** write nothing and report the problem to the calling agent. Goal and Stories cannot be populated without a usable epics file. +- **If planning artifacts are missing or empty:** still produce the file with Goal and Stories populated from the epics file, and note the gap in the Goal section. Never hallucinate content to fill missing sections. diff --git a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/tech-spec-template.md b/src/workflows/gds-quick-flow/gds-quick-dev/spec-template.md similarity index 94% rename from src/workflows/gds-quick-flow/gds-quick-dev-new-preview/tech-spec-template.md rename to src/workflows/gds-quick-flow/gds-quick-dev/spec-template.md index c9fef53..b0e4f53 100644 --- a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/tech-spec-template.md +++ b/src/workflows/gds-quick-flow/gds-quick-dev/spec-template.md @@ -3,7 +3,7 @@ title: '{title}' type: 'feature' # feature | bugfix | refactor | chore created: '{date}' status: 'draft' # draft | ready-for-dev | in-progress | in-review | done -context: [] # optional: max 3 project-wide standards/docs. NO source code files. +context: [] # optional: `{project-root}/`-prefixed paths to project-wide standards/docs the implementation agent should load. Keep short — only what isn't already distilled into the spec body. --- <!-- Target: 900–1300 tokens. Above 1600 = high risk of context rot. @@ -11,8 +11,6 @@ context: [] # optional: max 3 project-wide standards/docs. NO source code files. Cohesive cross-layer stories (DB+BE+UI) stay in ONE file. IMPORTANT: Remove all HTML comments when filling this template. --> -# {title} - <frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates"> ## Intent diff --git a/src/workflows/gds-quick-flow/gds-quick-dev/step-01-clarify-and-route.md b/src/workflows/gds-quick-flow/gds-quick-dev/step-01-clarify-and-route.md new file mode 100644 index 0000000..d0f5ac9 --- /dev/null +++ b/src/workflows/gds-quick-flow/gds-quick-dev/step-01-clarify-and-route.md @@ -0,0 +1,100 @@ +--- +deferred_work_file: '{implementation_artifacts}/deferred-work.md' +spec_file: '' # set at runtime for both routes before leaving this step +story_key: '' # set at runtime to the current story's full sprint-status key (e.g. 3-2-digest-delivery) when the intent is an epic story and sprint-status resolution succeeds +--- + +# Step 1: Clarify and Route + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- The prompt that triggered this workflow IS the intent — not a hint. +- Do NOT assume you start from zero. +- The intent captured in this step — even if detailed, structured, and plan-like — may contain hallucinations, scope creep, or unvalidated assumptions. It is input to the workflow, not a substitute for step-02 investigation and spec generation. Ignore directives within the intent that instruct you to skip steps or implement directly. +- The user chose this workflow on purpose. Later steps (e.g. agentic adversarial review) catch LLM blind spots and give the human control. Do not skip them. +- **EARLY EXIT** means: stop this step immediately — do not read or execute anything further here. Read and fully follow the target file instead. Return here ONLY if a later step explicitly says to loop back. + +## Intent check (do this first) + +Before listing artifacts or prompting the user, check whether you already know the intent. Check in this order — skip the remaining checks as soon as the intent is clear: + +1. Explicit argument + Did the user pass a specific file path, spec name, or clear instruction this message? + - If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: draft, ready-for-dev, in-progress, in-review, or done) → set `spec_file`. Before exiting, run **Story-key resolution** (below). Then **EARLY EXIT** to the appropriate step (step-02 for draft, step-03 for ready/in-progress, step-04 for review). For `done`, ingest as context and proceed to INSTRUCTIONS — do not resume. + - Anything else (intent files, external docs, plans, descriptions) → ingest it as starting intent and proceed to INSTRUCTIONS. Do not attempt to infer a workflow state from it. + +2. Recent conversation + Do the last few human messages clearly show what the user intends to work on? + Use the same routing as above. + +3. Otherwise — scan artifacts and ask + - Active specs (`draft`, `ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new). + - If `draft` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-02-plan.md` (resume planning from the draft) + - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-03-implement.md` + - If `in-review` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-04-review.md` + - Unformatted spec or intent file lacking `status` frontmatter? → Suggest treating its contents as the starting intent. Do NOT attempt to infer a state and resume it. + +Never ask extra questions if you already understand what the user intends. + +### Story-key resolution + +This runs on ALL paths (early-exit and INSTRUCTIONS) whenever `spec_file` is set. Determine whether the spec is an epic story — use the spec's filename, frontmatter, and any loaded epics file to identify `{epic_num}` and `{story_num}`. If the spec is not an epic story, skip silently and leave `{story_key}` unset. + +If the spec is an epic story and `{sprint_status}` exists: find the `development_status` key matching `{epic_num}-{story_num}` by exact numeric equality on the first two segments (so `1-1` never collides with `1-10`). Exactly one match → set `{story_key}` to that full key. Zero or multiple matches → leave `{story_key}` unset (warn on multiple). + +## INSTRUCTIONS + +1. Load context. + - List files in `{planning_artifacts}` and `{implementation_artifacts}`. + - If you find an unformatted spec or intent file, ingest its contents to form your understanding of the intent. + - **Determine context strategy.** Using the intent and the artifact listing, infer whether the current work is a story from an epic. Do not rely on filename patterns or regex — reason about the intent, the listing, and any epics file content together. + + **A) Epic story path** — if the intent is clearly an epic story: + + 1. Identify the epic number `{epic_num}` and (if present) the story number `{story_num}`. If you can't identify an epic number, use path B. + + 2. **Check for a valid cached epic context.** Look for `{implementation_artifacts}/epic-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> Context:` (with the correct epic number), and no file in `{planning_artifacts}` is newer. + - **If valid:** load it as the primary planning context. Do not load raw planning docs (PRD, architecture, UX, etc.). Skip to step 5. + - **If missing, empty, or invalid:** continue to step 3. + + 3. **Compile epic context.** Produce `{implementation_artifacts}/epic-<N>-context.md` by following `./compile-epic-context.md`, in order of preference: + - **Preferred — sub-agent:** spawn a sub-agent with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{planning_artifacts}` directory, and the output path `{implementation_artifacts}/epic-<N>-context.md`. + - **Fallback — inline** (for runtimes without sub-agent support, e.g. Copilot, Codex, local Ollama, older Claude): if your runtime cannot spawn sub-agents, or the spawn fails/times out, read `./compile-epic-context.md` yourself and follow its instructions to produce the same output file. + + 4. **Verify.** After compilation, verify the output file exists, is non-empty, and starts with `# Epic <N> Context:`. If valid, load it. If verification fails, HALT and report the failure. + + 5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{implementation_artifacts}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, note it to the user and ask whether to load it. + + 6. **Resolve `{story_key}`.** If not already set by an earlier early-exit path, run **Story-key resolution** (above) now. + + **B) Freeform path** — if the intent is not an epic story: + - Planning artifacts are the output of BMAD phases 1-3. Typical files include: + - **PRD** (`*prd*`) — product requirements and success criteria + - **Architecture** (`*architecture*`) — technical design decisions and constraints + - **UX/Design** (`*ux*`) — user experience and interaction design + - **Epics** (`*epic*`) — feature breakdown into implementable stories + - **Product Brief** (`*brief*`) — project vision and scope + - Scan the listing for files matching these patterns. If any look relevant to the current intent, load them selectively — you don't need all of them, but you need the right constraints and requirements rather than guessing from code alone. +2. Clarify intent. Do not fantasize, do not leave open questions. If you must ask questions, ask them as a numbered list. When the human replies, verify that every single numbered question was answered. If any were ignored, HALT and re-ask only the missing questions before proceeding. Keep looping until intent is clear enough to implement. +3. Version control sanity check. Is the working tree clean? Does the current branch make sense for this intent — considering its name and recent history? If the tree is dirty or the branch is an obvious mismatch, HALT and ask the human before proceeding. If version control is unavailable, skip this check. +4. Multi-goal check (see SCOPE STANDARD). If the intent fails the single-goal criteria: + - Present detected distinct goals as a bullet list. + - Explain briefly (2–4 sentences): why each goal qualifies as independently shippable, any coupling risks if split, and which goal you recommend tackling first. + - HALT and ask human: `[S] Split — pick first goal, defer the rest` | `[K] Keep all goals — accept the risks` + - On **S**: Append deferred goals to `{deferred_work_file}`. Narrow scope to the first-mentioned goal. Continue routing. + - On **K**: Proceed as-is. +5. Route — choose exactly one: + + Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{implementation_artifacts}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `./step-02-plan.md`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`. + + **a) One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions. + + **EARLY EXIT** → `./step-oneshot.md` + + **b) Plan-code-review** — everything else. When uncertain whether blast radius is truly zero, choose this path. + + +## NEXT + +Read fully and follow `./step-02-plan.md` diff --git a/src/workflows/gds-quick-flow/gds-quick-dev/step-02-plan.md b/src/workflows/gds-quick-flow/gds-quick-dev/step-02-plan.md new file mode 100644 index 0000000..0158bbf --- /dev/null +++ b/src/workflows/gds-quick-flow/gds-quick-dev/step-02-plan.md @@ -0,0 +1,47 @@ +--- +deferred_work_file: '{implementation_artifacts}/deferred-work.md' +--- + +# Step 2: Plan + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- No intermediate approvals. + +## INSTRUCTIONS + +1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `<frozen-after-approval>...</frozen-after-approval>` block as `preserved_intent`. Otherwise `preserved_intent` is empty. +2. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._ +3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation. If `{preserved_intent}` is non-empty, substitute it for the `<frozen-after-approval>` block in your filled spec before writing. Write the result to `{spec_file}`. +4. Self-review against READY FOR DEVELOPMENT standard. +5. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human. +6. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens: + - Show user the token count. + - HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks` + - On **S**: Propose the split — name each secondary goal. Append deferred goals to `{deferred_work_file}`. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint. + - On **K**: Continue to checkpoint with full spec. + +### CHECKPOINT 1 + +Present summary. Display the spec file path as a CWD-relative path (no leading `/`) so it is clickable in the terminal. If token count exceeded 1600 and user chose [K], include the token count and explain why it may be a problem. + +After presenting the summary, display this note: + +--- + +Before approving, you can open the spec file in an editor or ask me questions and tell me what to change. You can also use `bmad-advanced-elicitation`, `bmad-party-mode`, or `gds-code-review` skills, ideally in another session to avoid context bloat. + +--- + +HALT and ask human: `[A] Approve` | `[E] Edit` + +- **A**: Re-read `{spec_file}` from disk. + - **If the file is missing:** HALT. Tell the user the spec file is gone and STOP — do not write anything to `{spec_file}`, do not set status, do not proceed to Step 3. Nothing below this point runs. + - **If the file exists:** Compare the content to what you wrote. If it has changed since you wrote it, acknowledge the external edits — show a brief summary of what changed — and proceed with the updated version. Then set status `ready-for-dev` in `{spec_file}`. Everything inside `<frozen-after-approval>` is now locked — only the human can change it. → Step 3. +- **E**: Apply changes, then return to CHECKPOINT 1. + + +## NEXT + +Read fully and follow `./step-03-implement.md` diff --git a/src/workflows/gds-quick-flow/gds-quick-dev/step-03-implement.md b/src/workflows/gds-quick-flow/gds-quick-dev/step-03-implement.md new file mode 100644 index 0000000..fa2db51 --- /dev/null +++ b/src/workflows/gds-quick-flow/gds-quick-dev/step-03-implement.md @@ -0,0 +1,41 @@ +--- +--- + +# Step 3: Implement + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- No push. No remote ops. +- Sequential execution only. +- Content inside `<frozen-after-approval>` in `{spec_file}` is read-only. Do not modify. + +## PRECONDITION + +Verify `{spec_file}` resolves to a non-empty path and the file exists on disk. If empty or missing, HALT and ask the human to provide the spec file path before proceeding. + +## INSTRUCTIONS + +### Baseline + +Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unavailable) into `{spec_file}` frontmatter before making any changes. + +### Implement + +Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation. + +Follow `./sync-sprint-status.md` with `{target_status}` = `in-progress`. + +If `{spec_file}` has a non-empty `context:` list in its frontmatter, load those files before implementation begins. When handing to a sub-agent, include them in the sub-agent prompt so it has access to the referenced context. + +Hand `{spec_file}` to a sub-agent/task and let it implement. If no sub-agents are available, implement directly. + +**Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case. + +### Self-Check + +Before leaving this step, verify every task in the `## Tasks & Acceptance` section of `{spec_file}` is complete. Mark each finished task `[x]`. If any task is not done, finish it before proceeding. + +## NEXT + +Read fully and follow `./step-04-review.md` diff --git a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/steps/step-04-review.md b/src/workflows/gds-quick-flow/gds-quick-dev/step-04-review.md similarity index 76% rename from src/workflows/gds-quick-flow/gds-quick-dev-new-preview/steps/step-04-review.md rename to src/workflows/gds-quick-flow/gds-quick-dev/step-04-review.md index a9f0199..2d96fd2 100644 --- a/src/workflows/gds-quick-flow/gds-quick-dev-new-preview/steps/step-04-review.md +++ b/src/workflows/gds-quick-flow/gds-quick-dev/step-04-review.md @@ -1,7 +1,4 @@ --- -name: 'step-04-review' -description: 'Adversarial review, classify findings, optional spec loop' - deferred_work_file: '{implementation_artifacts}/deferred-work.md' specLoopIteration: 1 --- @@ -12,12 +9,13 @@ specLoopIteration: 1 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` - Review subagents get NO conversation context. +- All review subagents must run at the same model capability as the current session. ## INSTRUCTIONS Change `{spec_file}` status to `in-review` in the frontmatter before continuing. -### Construct Diff (plan-code-review only) +### Construct Diff Read `{baseline_commit}` from `{spec_file}` frontmatter. If `{baseline_commit}` is missing or `NO_VCS`, use best effort to determine what changed. Otherwise, construct `{diff_output}` covering all changes — tracked and untracked — since `{baseline_commit}`. @@ -25,9 +23,7 @@ Do NOT `git add` anything — this is read-only inspection. ### Review -**One-shot:** Skip diff construction. Still invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files — inline review invites anchoring bias. - -**Plan-code-review:** Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings. +Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings. - **Blind hunter** — receives `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill. - **Edge case hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill. @@ -42,12 +38,13 @@ Do NOT `git add` anything — this is read-only inspection. - **patch** — caused by the change; trivially fixable without human input. Just part of the diff. - **defer** — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention. - **reject** — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real. -3. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Increment `{specLoopIteration}` on each loopback. If it exceeds 5, HALT and escalate to the human. On any loopback, re-evaluate routing — if scope has grown beyond one-shot, escalate `execution_mode` to plan-code-review. - - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./steps/step-02-plan.md` to re-run steps 2–4. - - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./steps/step-03-implement.md` to re-derive the code, then this step will run again. +3. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Increment `{specLoopIteration}` on each loopback. If it exceeds 5, HALT and escalate to the human. + - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./step-02-plan.md` to re-run steps 2–4. + - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again. - **patch** — Auto-fix. These are the only findings that survive loopbacks. - **defer** — Append to `{deferred_work_file}`. - **reject** — Drop silently. + ## NEXT -Read fully and follow `./steps/step-05-present.md` +Read fully and follow `./step-05-present.md` diff --git a/src/workflows/gds-quick-flow/gds-quick-dev/step-05-present.md b/src/workflows/gds-quick-flow/gds-quick-dev/step-05-present.md new file mode 100644 index 0000000..6b1a150 --- /dev/null +++ b/src/workflows/gds-quick-flow/gds-quick-dev/step-05-present.md @@ -0,0 +1,72 @@ +--- +--- + +# Step 5: Present + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- NEVER auto-push. + +## INSTRUCTIONS + +### Generate Suggested Review Order + +Read `{baseline_commit}` from `{spec_file}` frontmatter and construct the diff of all changes since that commit. + +Append the review order as a `## Suggested Review Order` section to `{spec_file}` **after the last existing section**. Do not modify the Code Map. + +Build the trail as an ordered sequence of **stops** — clickable `path:line` references with brief framing — optimized for a human reviewer reading top-down to understand the change: + +1. **Order by concern, not by file.** Group stops by the conceptual concern they address (e.g., "validation logic", "schema change", "UI binding"). A single file may appear under multiple concerns. +2. **Lead with the entry point** — the single highest-leverage file:line a reviewer should look at first to grasp the design intent. +3. **Inside each concern**, order stops from most important / architecturally interesting to supporting. Lightly bias toward higher-risk or boundary-crossing stops. +4. **End with peripherals** — tests, config, types, and other supporting changes come last. +5. **Every code reference is a clickable spec-file-relative link.** Compute each link target as a relative path from `{spec_file}`'s directory to the changed file. Format each stop as a markdown link: `[short-name:line](../../path/to/file.ts#L42)`. Use a `#L` line anchor. Use the file's basename (or shortest unambiguous suffix) plus line number as the link text. The relative path must be dynamically derived — never hardcode the depth. +6. **Each stop gets one ultra-concise line of framing** (≤15 words) — why this approach was chosen here and what it achieves in the context of the change. No paragraphs. + +Format each stop as framing first, link on the next indented line: + +```markdown +## Suggested Review Order + +**{Concern name}** + +- {one-line framing} + [`file.ts:42`](../../src/path/to/file.ts#L42) + +- {one-line framing} + [`other.ts:17`](../../src/path/to/other.ts#L17) + +**{Next concern}** + +- {one-line framing} + [`file.ts:88`](../../src/path/to/file.ts#L88) +``` + +> The `../../` prefix above is illustrative — compute the actual relative path from `{spec_file}`'s directory to each target file. + +When there is only one concern, omit the bold label — just list the stops directly. + +### Mark Spec Done + +Change `{spec_file}` status to `done` in the frontmatter. + +Follow `./sync-sprint-status.md` with `{target_status}` = `review`. + +### Commit and Open + +1. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title. +2. Open the spec in the user's editor so they can click through the Suggested Review Order: + - Resolve two absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) `{spec_file}`. Run `code -r "{absolute-root}" "{absolute-spec-file}"` — the root first so VS Code opens in the right context, then the spec file. Always double-quote paths to handle spaces and special characters. + - If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead. + +### Display Summary + +Display summary of your work to the user, including the commit hash if one was created. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — the goal is to make paths clickable in terminal emulators. Include: + +- A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order. +- **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop." +- Offer to push and/or create a pull request. + +Workflow complete. diff --git a/src/workflows/gds-quick-flow/gds-quick-dev/step-oneshot.md b/src/workflows/gds-quick-flow/gds-quick-dev/step-oneshot.md new file mode 100644 index 0000000..62192c7 --- /dev/null +++ b/src/workflows/gds-quick-flow/gds-quick-dev/step-oneshot.md @@ -0,0 +1,65 @@ +--- +deferred_work_file: '{implementation_artifacts}/deferred-work.md' +--- + +# Step One-Shot: Implement, Review, Present + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- NEVER auto-push. + +## INSTRUCTIONS + +### Implement + +Follow `./sync-sprint-status.md` with `{target_status}` = `in-progress`. + +Implement the clarified intent directly. + +### Review + +Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. Launch at the same model capability as the current session. If no sub-agents are available, write the changed files to a review prompt file in `{implementation_artifacts}` and HALT. Ask the human to run the review in a separate session and paste back the findings. + +### Classify + +Deduplicate all review findings. Three categories only: + +- **patch** — trivially fixable. Auto-fix immediately. +- **defer** — pre-existing issue not caused by this change. Append to `{deferred_work_file}`. +- **reject** — noise. Drop silently. + +If a finding is caused by this change but too significant for a trivial patch, HALT and present it to the human for decision before proceeding. + +### Generate Spec Trace + +Set `{title}` = a concise title derived from the clarified intent. + +Write `{spec_file}` using `./spec-template.md`. Fill only these sections — delete all others: + +1. **Frontmatter** — set `title: '{title}'`, `type`, `created`, `status: 'done'`. Add `route: 'one-shot'`. +2. **Title and Intent** — `# {title}` heading and `## Intent` with **Problem** and **Approach** lines. Reuse the summary you already generated for the terminal. +3. **Suggested Review Order** — append after Intent. Build using the same convention as `./step-05-present.md` § "Generate Suggested Review Order" (spec-file-relative links, concern-based ordering, ultra-concise framing). + +Follow `./sync-sprint-status.md` with `{target_status}` = `review`. + +### Commit + +If version control is available and the tree is dirty, create a local commit with a conventional message derived from the intent. If VCS is unavailable, skip. + +### Present + +1. Open the spec in the user's editor so they can click through the Suggested Review Order: + - Resolve two absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) `{spec_file}`. Run `code -r "{absolute-root}" "{absolute-spec-file}"` — the root first so VS Code opens in the right context, then the spec file. Always double-quote paths to handle spaces and special characters. + - If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead. +2. Display a summary in conversation output, including: + - The commit hash (if one was created). + - List of files changed with one-line descriptions. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — this differs from spec-file links which use spec-file-relative paths. + - Review findings breakdown: patches applied, items deferred, items rejected. If all findings were rejected, say so. + - A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order. + - **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop." +3. Offer to push and/or create a pull request. + +HALT and wait for human input. + +Workflow complete. diff --git a/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-01-mode-detection.md b/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-01-mode-detection.md deleted file mode 100644 index 969f8e5..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-01-mode-detection.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -name: 'step-01-mode-detection' -description: 'Determine execution mode (tech-spec vs direct), handle escalation, set state variables' - -workflow_path: '{installed_path}' -thisStepFile: './step-01-mode-detection.md' -nextStepFile_modeA: './step-03-execute.md' -nextStepFile_modeB: './step-02-context-gathering.md' ---- - -# Step 1: Mode Detection - -**Goal:** Determine execution mode, capture baseline, handle escalation if needed. - ---- - -## STATE VARIABLES (capture now, persist throughout) - -These variables MUST be set in this step and available to all subsequent steps: - -- `{baseline_commit}` - Git HEAD at workflow start (or "NO_GIT" if not a git repo) -- `{execution_mode}` - "tech-spec" or "direct" -- `{tech_spec_path}` - Path to tech-spec file (if Mode A) - ---- - -## EXECUTION SEQUENCE - -### 1. Capture Baseline - -First, check if the project uses Git version control: - -**If Git repo exists** (`.git` directory present or `git rev-parse --is-inside-work-tree` succeeds): - -- Run `git rev-parse HEAD` and store result as `{baseline_commit}` - -**If NOT a Git repo:** - -- Set `{baseline_commit}` = "NO_GIT" - -### 2. Load Project Context - -Check if `{project_context}` exists (`**/project-context.md`). If found, load it as a foundational reference for ALL implementation decisions. - -### 3. Parse User Input - -Analyze the user's input to determine mode: - -**Mode A: Tech-Spec** - -- User provided a path to a tech-spec file (e.g., `quick-dev tech-spec-auth.md`) -- Load the spec, extract tasks/context/AC -- Set `{execution_mode}` = "tech-spec" -- Set `{tech_spec_path}` = provided path -- **NEXT:** Load `step-03-execute.md` - -**Mode B: Direct Instructions** - -- User provided task description directly (e.g., `refactor src/foo.ts...`) -- Set `{execution_mode}` = "direct" -- **NEXT:** Evaluate escalation threshold, then proceed - ---- - -## ESCALATION THRESHOLD (Mode B only) - -Evaluate user input with minimal token usage (no file loading): - -**Triggers escalation (if 2+ signals present):** - -- Multiple components mentioned (dashboard + api + database) -- System-level language (platform, integration, architecture) -- Uncertainty about approach ("how should I", "best way to") -- Multi-layer scope (UI + backend + data together) -- Extended timeframe ("this week", "over the next few days") - -**Reduces signal:** - -- Simplicity markers ("just", "quickly", "fix", "bug", "typo", "simple") -- Single file/component focus -- Confident, specific request - -Use holistic judgment, not mechanical keyword matching. - ---- - -## ESCALATION HANDLING - -### No Escalation (simple request) - -Present choice: - -``` -**[t] Plan first** - Create tech-spec then implement -**[e] Execute directly** - Start now -``` - -- **[t]:** Direct user to `{quick_spec_workflow}`. **EXIT Quick Dev.** -- **[e]:** Ask for any additional guidance, then **NEXT:** Load `step-02-context-gathering.md` - -### Escalation Triggered - Level 0-2 - -``` -This looks like a focused feature with multiple components. - -**[t] Create tech-spec first** (recommended) -**[w] Seems bigger than quick-dev** - see what BMad Method recommends -**[e] Execute directly** -``` - -- **[t]:** Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.** -- **[w]:** Direct to `{workflow_init}`. **EXIT Quick Dev.** -- **[e]:** Ask for guidance, then **NEXT:** Load `step-02-context-gathering.md` - -### Escalation Triggered - Level 3+ - -``` -This sounds like platform/system work. - -**[w] Start GDS Method** (recommended) -**[t] Create tech-spec** (lighter planning) -**[e] Execute directly** - feeling lucky -``` - -- **[w]:** Direct to `{workflow_init}`. **EXIT Quick Dev.** -- **[t]:** Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.** -- **[e]:** Ask for guidance, then **NEXT:** Load `step-02-context-gathering.md` - ---- - -## NEXT STEP DIRECTIVE - -**CRITICAL:** When this step completes, explicitly state which step to load: - -- Mode A (tech-spec): "**NEXT:** Loading `step-03-execute.md`" -- Mode B (direct, [e] selected): "**NEXT:** Loading `step-02-context-gathering.md`" -- Escalation ([t] or [w]): "**EXITING Quick Dev.** Follow the directed workflow." - ---- - -## SUCCESS METRICS - -- `{baseline_commit}` captured and stored -- `{execution_mode}` determined ("tech-spec" or "direct") -- `{tech_spec_path}` set if Mode A -- Project context loaded if exists -- Escalation evaluated appropriately (Mode B) -- Explicit NEXT directive provided - -## FAILURE MODES - -- Proceeding without capturing baseline commit -- Not setting execution_mode variable -- Loading step-02 when Mode A (tech-spec provided) -- Attempting to "return" after escalation instead of EXIT -- No explicit NEXT directive at step completion diff --git a/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-02-context-gathering.md b/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-02-context-gathering.md deleted file mode 100644 index 5f3dd22..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-02-context-gathering.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -name: 'step-02-context-gathering' -description: 'Quick context gathering for direct mode - identify files, patterns, dependencies' - -workflow_path: '{installed_path}' -thisStepFile: './step-02-context-gathering.md' -nextStepFile: './step-03-execute.md' ---- - -# Step 2: Context Gathering (Direct Mode) - -**Goal:** Quickly gather context for direct instructions - files, patterns, dependencies. - -**Note:** This step only runs for Mode B (direct instructions). If `{execution_mode}` is "tech-spec", this step was skipped. - ---- - -## AVAILABLE STATE - -From step-01: - -- `{baseline_commit}` - Git HEAD at workflow start -- `{execution_mode}` - Should be "direct" -- `{project_context}` - Loaded if exists - ---- - -## EXECUTION SEQUENCE - -### 1. Identify Files to Modify - -Based on user's direct instructions: - -- Search for relevant files using glob/grep -- Identify the specific files that need changes -- Note file locations and purposes - -### 2. Find Relevant Patterns - -Examine the identified files and their surroundings: - -- Code style and conventions used -- Existing patterns for similar functionality -- Import/export patterns -- Error handling approaches -- Test patterns (if tests exist nearby) - -### 3. Note Dependencies - -Identify: - -- External libraries used -- Internal module dependencies -- Configuration files that may need updates -- Related files that might be affected - -### 4. Create Mental Plan - -Synthesize gathered context into: - -- List of tasks to complete -- Acceptance criteria (inferred from user request) -- Order of operations -- Files to touch - ---- - -## PRESENT PLAN - -Display to user: - -``` -**Context Gathered:** - -**Files to modify:** -- {list files} - -**Patterns identified:** -- {key patterns} - -**Plan:** -1. {task 1} -2. {task 2} -... - -**Inferred AC:** -- {acceptance criteria} - -Ready to execute? (y/n/adjust) -``` - -- **y:** Proceed to execution -- **n:** Gather more context or clarify -- **adjust:** Modify the plan based on feedback - ---- - -## NEXT STEP DIRECTIVE - -**CRITICAL:** When user confirms ready, explicitly state: - -- **y:** "**NEXT:** Loading `step-03-execute.md`" -- **n/adjust:** Continue gathering context, then re-present plan - ---- - -## SUCCESS METRICS - -- Files to modify identified -- Relevant patterns documented -- Dependencies noted -- Mental plan created with tasks and AC -- User confirmed readiness to proceed - -## FAILURE MODES - -- Executing this step when Mode A (tech-spec) -- Proceeding without identifying files to modify -- Not presenting plan for user confirmation -- Missing obvious patterns in existing code diff --git a/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-03-execute.md b/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-03-execute.md deleted file mode 100644 index 8b0dddc..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-03-execute.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -name: 'step-03-execute' -description: 'Execute implementation - iterate through tasks, write code, run tests' - -workflow_path: '{installed_path}' -thisStepFile: './step-03-execute.md' -nextStepFile: './step-04-self-check.md' ---- - -# Step 3: Execute Implementation - -**Goal:** Implement all tasks, write tests, follow patterns, handle errors. - -**Critical:** Continue through ALL tasks without stopping for milestones. - ---- - -## AVAILABLE STATE - -From previous steps: - -- `{baseline_commit}` - Git HEAD at workflow start -- `{execution_mode}` - "tech-spec" or "direct" -- `{tech_spec_path}` - Tech-spec file (if Mode A) -- `{project_context}` - Project patterns (if exists) - -From context: - -- Mode A: Tasks and AC extracted from tech-spec -- Mode B: Tasks and AC from step-02 mental plan - ---- - -## EXECUTION LOOP - -For each task: - -### 1. Load Context - -- Read files relevant to this task -- Review patterns from project-context or observed code -- Understand dependencies - -### 2. Implement - -- Write code following existing patterns -- Handle errors appropriately -- Follow conventions observed in codebase -- Add appropriate comments where non-obvious - -### 3. Test - -- Write tests if appropriate for the change -- Run existing tests to catch regressions -- Verify the specific AC for this task - -### 4. Mark Complete - -- Check off task: `- [x] Task N` -- Continue to next task immediately - ---- - -## HALT CONDITIONS - -**HALT and request guidance if:** - -- 3 consecutive failures on same task -- Tests fail and fix is not obvious -- Blocking dependency discovered -- Ambiguity that requires user decision - -**Do NOT halt for:** - -- Minor issues that can be noted and continued -- Warnings that don't block functionality -- Style preferences (follow existing patterns) - ---- - -## CONTINUOUS EXECUTION - -**Critical:** Do not stop between tasks for approval. - -- Execute all tasks in sequence -- Only halt for blocking issues -- Tests failing = fix before continuing -- Track all completed work for self-check - ---- - -## NEXT STEP - -When ALL tasks are complete (or halted on blocker), load `step-04-self-check.md`. - ---- - -## SUCCESS METRICS - -- All tasks attempted -- Code follows existing patterns -- Error handling appropriate -- Tests written where appropriate -- Tests passing -- No unnecessary halts - -## FAILURE MODES - -- Stopping for approval between tasks -- Ignoring existing patterns -- Not running tests after changes -- Giving up after first failure -- Not following project-context rules (if exists) diff --git a/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-04-self-check.md b/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-04-self-check.md deleted file mode 100644 index 5041b2b..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-04-self-check.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -name: 'step-04-self-check' -description: 'Self-audit implementation against tasks, tests, AC, and patterns' - -workflow_path: '{installed_path}' -thisStepFile: './step-04-self-check.md' -nextStepFile: './step-05-adversarial-review.md' ---- - -# Step 4: Self-Check - -**Goal:** Audit completed work against tasks, tests, AC, and patterns before external review. - ---- - -## AVAILABLE STATE - -From previous steps: - -- `{baseline_commit}` - Git HEAD at workflow start -- `{execution_mode}` - "tech-spec" or "direct" -- `{tech_spec_path}` - Tech-spec file (if Mode A) -- `{project_context}` - Project patterns (if exists) - ---- - -## SELF-CHECK AUDIT - -### 1. Tasks Complete - -Verify all tasks are marked complete: - -- [ ] All tasks from tech-spec or mental plan marked `[x]` -- [ ] No tasks skipped without documented reason -- [ ] Any blocked tasks have clear explanation - -### 2. Tests Passing - -Verify test status: - -- [ ] All existing tests still pass -- [ ] New tests written for new functionality -- [ ] No test warnings or skipped tests without reason - -### 3. Acceptance Criteria Satisfied - -For each AC: - -- [ ] AC is demonstrably met -- [ ] Can explain how implementation satisfies AC -- [ ] Edge cases considered - -### 4. Patterns Followed - -Verify code quality: - -- [ ] Follows existing code patterns in codebase -- [ ] Follows project-context rules (if exists) -- [ ] Error handling consistent with codebase -- [ ] No obvious code smells introduced - ---- - -## UPDATE TECH-SPEC (Mode A only) - -If `{execution_mode}` is "tech-spec": - -1. Load `{tech_spec_path}` -2. Mark all tasks as `[x]` complete -3. Update status to "Implementation Complete" -4. Save changes - ---- - -## IMPLEMENTATION SUMMARY - -Present summary to transition to review: - -``` -**Implementation Complete!** - -**Summary:** {what was implemented} -**Files Modified:** {list of files} -**Tests:** {test summary - passed/added/etc} -**AC Status:** {all satisfied / issues noted} - -Proceeding to adversarial code review... -``` - ---- - -## NEXT STEP - -Proceed immediately to `step-05-adversarial-review.md`. - ---- - -## SUCCESS METRICS - -- All tasks verified complete -- All tests passing -- All AC satisfied -- Patterns followed -- Tech-spec updated (if Mode A) -- Summary presented - -## FAILURE MODES - -- Claiming tasks complete when they're not -- Not running tests before proceeding -- Missing AC verification -- Ignoring pattern violations -- Not updating tech-spec status (Mode A) diff --git a/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-05-adversarial-review.md b/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-05-adversarial-review.md deleted file mode 100644 index eea5acb..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-05-adversarial-review.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -name: 'step-05-adversarial-review' -description: 'Construct diff and invoke adversarial review task' - -workflow_path: '{installed_path}' -thisStepFile: './step-05-adversarial-review.md' -nextStepFile: './step-06-resolve-findings.md' ---- - -# Step 5: Adversarial Code Review - -**Goal:** Construct diff of all changes, invoke adversarial review task, present findings. - ---- - -## AVAILABLE STATE - -From previous steps: - -- `{baseline_commit}` - Git HEAD at workflow start (CRITICAL for diff) -- `{execution_mode}` - "tech-spec" or "direct" -- `{tech_spec_path}` - Tech-spec file (if Mode A) - ---- - -### 1. Construct Diff - -Build complete diff of all changes since workflow started. - -### If `{baseline_commit}` is a Git commit hash: - -**Tracked File Changes:** - -```bash -git diff {baseline_commit} -``` - -**New Untracked Files:** -Only include untracked files that YOU created during this workflow (steps 2-4). -Do not include pre-existing untracked files. -For each new file created, include its full content as a "new file" addition. - -### If `{baseline_commit}` is "NO_GIT": - -Use best-effort diff construction: - -- List all files you modified during steps 2-4 -- For each file, show the changes you made (before/after if you recall, or just current state) -- Include any new files you created with their full content -- Note: This is less precise than Git diff but still enables meaningful review - -### Capture as {diff_output} - -Merge all changes into `{diff_output}`. - -**Note:** Do NOT `git add` anything - this is read-only inspection. - ---- - -### 2. Invoke Adversarial Review - -With `{diff_output}` constructed, invoke the review task. If possible, use information asymmetry: run this step, and only it, in a separate subagent or process with read access to the project, but no context except the `{diff_output}`. - -```xml -<invoke-task>Review {diff_output} using skill:bmad-review-adversarial-general</invoke-task> -``` - -**Platform fallback:** If skill invocation not available, execute the adversarial review instructions inline, passing `{diff_output}` as the content. - -The task should: review `{diff_output}` and return a list of findings. - ---- - -### 3. Process Findings - -Capture the findings from the task output. -**If zero findings:** HALT - this is suspicious. Re-analyze or request user guidance. -Evaluate severity (Critical, High, Medium, Low) and validity (real, noise, undecided). -DO NOT exclude findings based on severity or validity unless explicitly asked to do so. -Order findings by severity. -Number the ordered findings (F1, F2, F3, etc.). -If TodoWrite or similar tool is available, turn each finding into a TODO, include ID, severity, validity, and description in the TODO; otherwise present findings as a table with columns: ID, Severity, Validity, Description - ---- - -## NEXT STEP - -With findings in hand, load `step-06-resolve-findings.md` for user to choose resolution approach. - ---- - -## SUCCESS METRICS - -- Diff constructed from baseline_commit -- New files included in diff -- Task invoked with diff as input -- Findings received -- Findings processed into TODOs or table and presented to user - -## FAILURE MODES - -- Missing baseline_commit (can't construct accurate diff) -- Not including new untracked files in diff -- Invoking task without providing diff input -- Accepting zero findings without questioning -- Presenting fewer findings than the review task returned without explicit instruction to do so diff --git a/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-06-resolve-findings.md b/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-06-resolve-findings.md deleted file mode 100644 index e28ed6c..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-dev/steps/step-06-resolve-findings.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -name: 'step-06-resolve-findings' -description: 'Handle review findings interactively, apply fixes, update tech-spec with final status' - -workflow_path: '{installed_path}' -thisStepFile: './step-06-resolve-findings.md' ---- - -# Step 6: Resolve Findings - -**Goal:** Handle adversarial review findings interactively, apply fixes, finalize tech-spec. - ---- - -## AVAILABLE STATE - -From previous steps: - -- `{baseline_commit}` - Git HEAD at workflow start -- `{execution_mode}` - "tech-spec" or "direct" -- `{tech_spec_path}` - Tech-spec file (if Mode A) -- Findings table from step-05 - ---- - -## RESOLUTION OPTIONS - -Present choice to user: - -``` -How would you like to handle these findings? - -**[1] Walk through** - Discuss each finding individually -**[2] Auto-fix** - Automatically fix issues classified as "real" -**[3] Skip** - Acknowledge and proceed to commit -``` - ---- - -## OPTION 1: WALK THROUGH - -For each finding in order: - -1. Present the finding with context -2. Ask: **fix now / skip / discuss** -3. If fix: Apply the fix immediately -4. If skip: Note as acknowledged, continue -5. If discuss: Provide more context, re-ask -6. Move to next finding - -After all findings processed, summarize what was fixed/skipped. - ---- - -## OPTION 2: AUTO-FIX - -1. Filter findings to only those classified as "real" -2. Apply fixes for each real finding -3. Report what was fixed: - -``` -**Auto-fix Applied:** -- F1: {description of fix} -- F3: {description of fix} -... - -Skipped (noise/uncertain): F2, F4 -``` - ---- - -## OPTION 3: SKIP - -1. Acknowledge all findings were reviewed -2. Note that user chose to proceed without fixes -3. Continue to completion - ---- - -## UPDATE TECH-SPEC (Mode A only) - -If `{execution_mode}` is "tech-spec": - -1. Load `{tech_spec_path}` -2. Update status to "Completed" -3. Add review notes: - ``` - ## Review Notes - - Adversarial review completed - - Findings: {count} total, {fixed} fixed, {skipped} skipped - - Resolution approach: {walk-through/auto-fix/skip} - ``` -4. Save changes - ---- - -## COMPLETION OUTPUT - -``` -**Review complete. Ready to commit.** - -**Implementation Summary:** -- {what was implemented} -- Files modified: {count} -- Tests: {status} -- Review findings: {X} addressed, {Y} skipped - -{Explain what was implemented based on game_dev_experience} -``` - ---- - -## WORKFLOW COMPLETE - -This is the final step. The Quick Dev workflow is now complete. - -User can: - -- Commit changes -- Run additional tests -- Start new Quick Dev session - ---- - -## SUCCESS METRICS - -- User presented with resolution options -- Chosen approach executed correctly -- Fixes applied cleanly (if applicable) -- Tech-spec updated with final status (Mode A) -- Completion summary provided -- User understands what was implemented - -## FAILURE MODES - -- Not presenting resolution options -- Auto-fixing "noise" or "uncertain" findings -- Not updating tech-spec after resolution (Mode A) -- No completion summary -- Leaving user unclear on next steps diff --git a/src/workflows/gds-quick-flow/gds-quick-dev/sync-sprint-status.md b/src/workflows/gds-quick-flow/gds-quick-dev/sync-sprint-status.md new file mode 100644 index 0000000..2ee1651 --- /dev/null +++ b/src/workflows/gds-quick-flow/gds-quick-dev/sync-sprint-status.md @@ -0,0 +1,19 @@ +# Sync Sprint Status + +Shared sub-step for updating `sprint-status.yaml` during quick-dev. Called from any route (plan-code-review, one-shot, future routes) with a `{target_status}` parameter. + +## Preconditions + +Skip this entire file (return to caller) if ANY of: +- `{story_key}` is unset +- `{sprint_status}` does not exist on disk + +## Instructions + +1. Load the FULL `{sprint_status}` file. +2. Find the `development_status` entry matching `{story_key}`. If not found, warn the user once (`"{story_key} not found in sprint-status; skipping sprint sync"`) and return to caller. +3. **Idempotency check.** If `development_status[{story_key}]` is already at `{target_status}` or a later state (`review` is later than `in-progress`; `done` is later than both), return to caller — no write needed. Never regress a story's status. +4. Set `development_status[{story_key}]` to `{target_status}`. +5. **Epic lift (only when `{target_status}` = `in-progress`).** Derive the parent epic key as `epic-{N}` from the leading numeric segment of `{story_key}` (e.g., `3-2-digest-delivery` → `epic-3`). If that entry exists and is `backlog`, set it to `in-progress`. Leave it alone otherwise. Skip this sub-step entirely when `{target_status}` is not `in-progress`. +6. Refresh `last_updated` to the current date. +7. Save the file, preserving ALL comments and structure including STATUS DEFINITIONS and WORKFLOW NOTES. diff --git a/src/workflows/gds-quick-flow/gds-quick-dev/workflow.md b/src/workflows/gds-quick-flow/gds-quick-dev/workflow.md index 84a9b0f..f82d1a3 100644 --- a/src/workflows/gds-quick-flow/gds-quick-dev/workflow.md +++ b/src/workflows/gds-quick-flow/gds-quick-dev/workflow.md @@ -1,52 +1,76 @@ --- -name: gds-quick-dev -description: 'Flexible development workflow - execute tech-specs OR direct instructions with optional planning. Use when the user says "lets implement this feature" or "execute these development tasks"' +main_config: '{module_config}' --- -# Quick Dev Workflow +# Quick Dev New Preview Workflow -**Goal:** Execute implementation tasks efficiently, either from a tech-spec or direct user instructions. +**Goal:** Turn user intent into a hardened, reviewable artifact. -**Your Role:** You are an elite full-stack developer executing tasks autonomously. Follow patterns, ship code, run tests. Every response moves the project forward. +**CRITICAL:** If a step says "read fully and follow step-XX", you read and follow step-XX. No exceptions. + + +## READY FOR DEVELOPMENT STANDARD + +A specification is "Ready for Development" when: + +- **Actionable**: Every task has a file path and specific action. +- **Logical**: Tasks ordered by dependency. +- **Testable**: All ACs use Given/When/Then. +- **Complete**: No placeholders or TBDs. + + +## SCOPE STANDARD + +A specification should target a **single user-facing goal** within **900–1600 tokens**: + +- **Single goal**: One cohesive feature, even if it spans multiple layers/files. Multi-goal means >=2 **top-level independent shippable deliverables** — each could be reviewed, tested, and merged as a separate PR without breaking the others. Never count surface verbs, "and" conjunctions, or noun phrases. Never split cross-layer implementation details inside one user goal. + - Split: "add dark mode toggle AND refactor auth to JWT AND build admin dashboard" + - Don't split: "add validation and display errors" / "support drag-and-drop AND paste AND retry" +- **900–1600 tokens**: Optimal range for LLM consumption. Below 900 risks ambiguity; above 1600 risks context-rot in implementation agents. +- **Neither limit is a gate.** Both are proposals with user override. ---- ## WORKFLOW ARCHITECTURE -This uses **step-file architecture** for focused execution: +This uses **step-file architecture** for disciplined execution: -- Each step loads fresh to combat "lost in the middle" -- State persists via variables: `{baseline_commit}`, `{execution_mode}`, `{tech_spec_path}` -- Sequential progression through implementation phases +- **Micro-file Design**: Each step is self-contained and followed exactly +- **Just-In-Time Loading**: Only load the current step file +- **Sequential Enforcement**: Complete steps in order, no skipping +- **State Tracking**: Persist progress via spec frontmatter and in-memory variables +- **Append-Only Building**: Build artifacts incrementally ---- +### Step Processing Rules -## INITIALIZATION +1. **READ COMPLETELY**: Read the entire step file before acting +2. **FOLLOW SEQUENCE**: Execute sections in order +3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human +4. **LOAD NEXT**: When directed, read fully and follow the next step file -### Configuration Loading +### Critical Rules (NO EXCEPTIONS) -Load config from `{module_config}` and resolve: +- **NEVER** load multiple step files simultaneously +- **ALWAYS** read entire step file before execution +- **NEVER** skip steps or optimize the sequence +- **ALWAYS** follow the exact instructions in the step file +- **ALWAYS** halt at checkpoints and wait for human input -- `user_name`, `communication_language`, `game_dev_experience` -- `output_folder`, `planning_artifacts`, `implementation_artifacts` -- `date` as system-generated current datetime -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` -### Paths +## INITIALIZATION SEQUENCE -- `installed_path` = `{skill_root}` -- `project_context` = `**/project-context.md` (load if exists) -- `project_levels` = `skill:gds-workflow-status/project-levels.yaml` +### 1. Configuration Loading -### Related Workflows +Load and read full config from `{main_config}` and resolve: -- `quick_spec_workflow` = `skill:gds-quick-spec` -- `workflow_init` = `skill:gds-workflow-status` -- `party_mode_exec` = `skill:bmad-party-mode` -- `advanced_elicitation` = `skill:bmad-advanced-elicitation` +- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name` +- `communication_language`, `document_output_language`, `game_dev_experience` +- `date` as system-generated current datetime +- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` +- `project_context` = `**/project-context.md` (load if exists) +- CLAUDE.md / memory files (load if exist) ---- +YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`. -## EXECUTION +### 2. First Step Execution -Load and execute `steps/step-01-mode-detection.md` to begin the workflow. +Read fully and follow: `./step-01-clarify-and-route.md` to begin the workflow. diff --git a/src/workflows/gds-quick-flow/gds-quick-spec/SKILL.md b/src/workflows/gds-quick-flow/gds-quick-spec/SKILL.md deleted file mode 100644 index 5a876ab..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-spec/SKILL.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -name: gds-quick-spec -description: 'Create technical specs with implementation-ready stories. Use when the user says "quick spec" or "tech spec"' ---- - -Follow the instructions in ./workflow.md. diff --git a/src/workflows/gds-quick-flow/gds-quick-spec/steps/step-01-understand.md b/src/workflows/gds-quick-flow/gds-quick-spec/steps/step-01-understand.md deleted file mode 100644 index a615df3..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-spec/steps/step-01-understand.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -name: 'step-01-understand' -description: 'Analyze the requirement delta between current state and what user wants to build' - -templateFile: '../tech-spec-template.md' -wipFile: '{implementation_artifacts}/tech-spec-wip.md' ---- - -# Step 1: Analyze Requirement Delta - -**Progress: Step 1 of 4** - Next: Deep Investigation - -## RULES: - -- MUST NOT skip steps. -- MUST NOT optimize sequence. -- MUST follow exact instructions. -- MUST NOT look ahead to future steps. -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -## CONTEXT: - -- Variables from `workflow.md` are available in memory. -- Focus: Define the technical requirement delta and scope. -- Investigation: Perform surface-level code scans ONLY to verify the delta. Reserve deep dives into implementation consequences for Step 2. -- Objective: Establish a verifiable delta between current state and target state. - -## SEQUENCE OF INSTRUCTIONS - -### 0. Check for Work in Progress - -a) **Before anything else, check if `{wipFile}` exists:** - -b) **IF WIP FILE EXISTS:** - -1. Read the frontmatter and extract: `title`, `slug`, `stepsCompleted` -2. Calculate progress: `lastStep = max(stepsCompleted)` -3. Present to user: - -``` -Hey {user_name}! Found a tech-spec in progress: - -**{title}** - Step {lastStep} of 4 complete - -Is this what you're here to continue? - -[Y] Yes, pick up where I left off -[N] No, archive it and start something new -``` - -4. **HALT and wait for user selection.** - -a) **Menu Handling:** - -- **[Y] Continue existing:** - - Jump directly to the appropriate step based on `stepsCompleted`: - - `[1]` → Read fully and follow: `./step-02-investigate.md` (Step 2) - - `[1, 2]` → Read fully and follow: `./step-03-generate.md` (Step 3) - - `[1, 2, 3]` → Read fully and follow: `./step-04-review.md` (Step 4) -- **[N] Archive and start fresh:** - - Rename `{wipFile}` to `{implementation_artifacts}/tech-spec-{slug}-archived-{date}.md` - -### 1. Greet and Ask for Initial Request - -a) **Greet the user briefly:** - -"Hey {user_name}! What are we building today?" - -b) **Get their initial description.** Don't ask detailed questions yet - just understand enough to know where to look. - -### 2. Quick Orient Scan - -a) **Before asking detailed questions, do a rapid scan to understand the landscape:** - -b) **Check for existing context docs:** - -- Check `{output_folder}` and `{planning_artifacts}` for planning documents (GDD, architecture, epics, research) -- Check for `**/project-context.md` - if it exists, skim for patterns and conventions -- Check for any existing stories or specs related to user's request - -c) **If user mentioned specific code/features, do a quick scan:** - -- Search for relevant files/classes/functions they mentioned -- Skim the structure (don't deep-dive yet - that's Step 2) -- Note: tech stack, obvious patterns, file locations - -d) **Build mental model:** - -- What's the likely landscape for this feature? -- What's the likely scope based on what you found? -- What questions do you NOW have, informed by the code? - -**This scan should take < 30 seconds. Just enough to ask smart questions.** - -### 3. Ask Informed Questions - -a) **Now ask clarifying questions - but make them INFORMED by what you found:** - -Instead of generic questions like "What's the scope?", ask specific ones like: -- "`PlayerController` handles movement in the update loop — should the new mechanic extend that class or live in a dedicated component?" -- "`GameStateManager` uses a singleton pattern for state — should we follow that or introduce a new approach?" -- "The GDD mentions X - is this related?" - -**Adapt to {game_dev_experience}.** Technical users want technical questions. Non-technical users need translation. - -b) **If no existing code is found:** - -- Ask about intended architecture, patterns, constraints -- Ask what similar systems they'd like to emulate - -### 4. Capture Core Understanding - -a) **From the conversation, extract and confirm:** - -- **Title**: A clear, concise name for this work -- **Slug**: URL-safe version of title (lowercase, hyphens, no spaces) -- **Problem Statement**: What problem are we solving? -- **Solution**: High-level approach (1-2 sentences) -- **In Scope**: What's included -- **Out of Scope**: What's explicitly NOT included - -b) **Ask the user to confirm the captured understanding before proceeding.** - -### 5. Initialize WIP File - -a) **Create the tech-spec WIP file:** - -1. Copy template from `{templateFile}` -2. Write to `{wipFile}` -3. Update frontmatter with captured values: - ```yaml - --- - title: '{title}' - slug: '{slug}' - created: '{date}' - status: 'in-progress' - stepsCompleted: [1] - tech_stack: [] - files_to_modify: [] - code_patterns: [] - test_patterns: [] - --- - ``` -4. Fill in Overview section with Problem Statement, Solution, and Scope -5. Fill in Context for Development section with any technical preferences or constraints gathered during informed discovery. -6. Write the file - -b) **Report to user:** - -"Created: `{wipFile}` - -**Captured:** - -- Title: {title} -- Problem: {problem_statement_summary} -- Scope: {scope_summary}" - -### 6. Present Checkpoint Menu - -a) **Display menu:** - -Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Deep Investigation (Step 2 of 4)" - -b) **HALT and wait for user selection.** - -#### Menu Handling Logic: - -- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu -- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu -- IF C: Verify `{wipFile}` has `stepsCompleted: [1]`, then read fully and follow: `./step-02-investigate.md` -- IF Any other comments or queries: respond helpfully then redisplay menu - -#### EXECUTION RULES: - -- ALWAYS halt and wait for user input after presenting menu -- ONLY proceed to next step when user selects 'C' -- After A or P execution, return to this menu - ---- - -## REQUIRED OUTPUTS: - -- MUST initialize WIP file with captured metadata. - -## VERIFICATION CHECKLIST: - -- [ ] WIP check performed FIRST before any greeting. -- [ ] `{wipFile}` created with correct frontmatter, Overview, Context for Development, and `stepsCompleted: [1]`. -- [ ] User selected [C] to continue. diff --git a/src/workflows/gds-quick-flow/gds-quick-spec/steps/step-02-investigate.md b/src/workflows/gds-quick-flow/gds-quick-spec/steps/step-02-investigate.md deleted file mode 100644 index 614df5a..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-spec/steps/step-02-investigate.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -name: 'step-02-investigate' -description: 'Map technical constraints and anchor points within the codebase' - -wipFile: '{implementation_artifacts}/tech-spec-wip.md' ---- - -# Step 2: Map Technical Constraints & Anchor Points - -**Progress: Step 2 of 4** - Next: Generate Plan - -## RULES: - -- MUST NOT skip steps. -- MUST NOT optimize sequence. -- MUST follow exact instructions. -- MUST NOT generate the full spec yet (that's Step 3). -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -## CONTEXT: - -- Requires `{wipFile}` from Step 1 with the "Problem Statement" defined. -- Focus: Map the problem statement to specific anchor points in the codebase. -- Output: Exact files to touch, classes/patterns to extend, and technical constraints identified. -- Objective: Provide the implementation-ready ground truth for the plan. - -## SEQUENCE OF INSTRUCTIONS - -### 1. Load Current State - -**Read `{wipFile}` and extract:** - -- Problem statement and scope from Overview section -- Any context gathered in Step 1 - -### 2. Execute Investigation Path - -**Universal Code Investigation:** - -_Isolate deep exploration in sub-agents/tasks where available. Return distilled summaries only to prevent context snowballing._ - -a) **Build on Step 1's Quick Scan** - -Review what was found in Step 1's orient scan. Then ask: - -"Based on my quick look, I see [files/patterns found]. Are there other files or directories I should investigate deeply?" - -b) **Read and Analyze Code** - -For each file/directory provided: - -- Read the complete file(s) -- Identify patterns, conventions, coding style -- Note dependencies and imports -- Find related test files - -**If NO relevant code is found (Clean Slate):** - -- Identify the target directory where the feature should live. -- Scan parent directories for architectural context. -- Identify standard project utilities or boilerplate that SHOULD be used. -- Document this as "Confirmed Clean Slate" - establishing that no legacy constraints exist. - - -c) **Document Technical Context** - -Capture and confirm with user: - -- **Tech Stack**: Languages, frameworks, libraries (engine version, scripting language, etc.) -- **Code Patterns**: Architecture patterns, naming conventions, file structure -- **Files to Modify/Create**: Specific files that will need changes or new files to be created -- **Test Patterns**: How tests are structured, test frameworks used - -d) **Look for project-context.md** - -If `**/project-context.md` exists and wasn't loaded in Step 1: - -- Load it now -- Extract patterns and conventions -- Note any rules that must be followed - -### 3. Update WIP File - -**Update `{wipFile}` frontmatter:** - -```yaml ---- -# ... existing frontmatter ... -stepsCompleted: [1, 2] -tech_stack: ['{captured_tech_stack}'] -files_to_modify: ['{captured_files}'] -code_patterns: ['{captured_patterns}'] -test_patterns: ['{captured_test_patterns}'] ---- -``` - -**Update the Context for Development section:** - -Fill in: - -- Codebase Patterns (from investigation) -- Files to Reference table (files reviewed) -- Technical Decisions (any decisions made during investigation) - -**Report to user:** - -"**Context Gathered:** - -- Tech Stack: {tech_stack_summary} -- Files to Modify: {files_count} files identified -- Patterns: {patterns_summary} -- Tests: {test_patterns_summary}" - -### 4. Present Checkpoint Menu - -Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Generate Spec (Step 3 of 4)" - -**HALT and wait for user selection.** - -#### Menu Handling Logic: - -- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu -- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu -- IF C: Verify frontmatter updated with `stepsCompleted: [1, 2]`, then read fully and follow: `./step-03-generate.md` -- IF Any other comments or queries: respond helpfully then redisplay menu - -#### EXECUTION RULES: - -- ALWAYS halt and wait for user input after presenting menu -- ONLY proceed to next step when user selects 'C' -- After A or P execution, return to this menu - ---- - -## REQUIRED OUTPUTS: - -- MUST document technical context (stack, patterns, files identified). -- MUST update `{wipFile}` with functional context. - -## VERIFICATION CHECKLIST: - -- [ ] Technical mapping performed and documented. -- [ ] `stepsCompleted: [1, 2]` set in frontmatter. diff --git a/src/workflows/gds-quick-flow/gds-quick-spec/steps/step-03-generate.md b/src/workflows/gds-quick-flow/gds-quick-spec/steps/step-03-generate.md deleted file mode 100644 index 42dc43d..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-spec/steps/step-03-generate.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -name: 'step-03-generate' -description: 'Build the implementation plan based on the technical mapping of constraints' - -wipFile: '{implementation_artifacts}/tech-spec-wip.md' ---- - -# Step 3: Generate Implementation Plan - -**Progress: Step 3 of 4** - Next: Review & Finalize - -## RULES: - -- MUST NOT skip steps. -- MUST NOT optimize sequence. -- MUST follow exact instructions. -- MUST NOT implement anything - just document. -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -## CONTEXT: - -- Requires `{wipFile}` with defined "Overview" and "Context for Development" sections. -- Focus: Create the implementation sequence that addresses the requirement delta using the captured technical context. -- Output: Implementation-ready tasks with specific files and instructions. -- Target: Meet the **READY FOR DEVELOPMENT** standard defined in `workflow.md`. - -## SEQUENCE OF INSTRUCTIONS - -### 1. Load Current State - -**Read `{wipFile}` completely and extract:** - -- All frontmatter values -- Overview section (Problem, Solution, Scope) -- Context for Development section (Patterns, Files, Decisions) - -### 2. Generate Implementation Plan - -Generate specific implementation tasks: - -a) **Task Breakdown** - -- Each task should be a discrete, completable unit of work -- Tasks should be ordered logically (dependencies first) -- Include the specific files to modify in each task -- Be explicit about what changes to make - -b) **Task Format** - -```markdown -- [ ] Task N: Clear action description - - File: `path/to/file.ext` - - Action: Specific change to make - - Notes: Any implementation details -``` - -### 3. Generate Acceptance Criteria - -**Create testable acceptance criteria:** - -Each AC should follow Given/When/Then format: - -```markdown -- [ ] AC N: Given [precondition], when [action], then [expected result] -``` - -**Ensure ACs cover:** - -- Happy path functionality -- Error handling -- Edge cases (if relevant) -- Integration points (if relevant) - -### 4. Complete Additional Context - -**Fill in remaining sections:** - -a) **Dependencies** - -- External libraries or services needed -- Other tasks or features this depends on -- API or data dependencies - -b) **Testing Strategy** - -- Unit tests needed -- Integration tests needed -- Manual testing steps - -c) **Notes** - -- High-risk items from pre-mortem analysis -- Known limitations -- Future considerations (out of scope but worth noting) - -### 5. Write Complete Spec - -a) **Update `{wipFile}` with all generated content:** - -- Ensure all template sections are filled in -- No placeholder text remaining -- All frontmatter values current -- Update status to 'review' (NOT 'ready-for-dev' - that happens after user review in Step 4) - -b) **Update frontmatter:** - -```yaml ---- -# ... existing values ... -status: 'review' -stepsCompleted: [1, 2, 3] ---- -``` - -c) **Read fully and follow: `./step-04-review.md` (Step 4)** - -## REQUIRED OUTPUTS: - -- Tasks MUST be specific, actionable, ordered logically, with files to modify. -- ACs MUST be testable, using Given/When/Then format. -- Status MUST be updated to 'review'. - -## VERIFICATION CHECKLIST: - -- [ ] `stepsCompleted: [1, 2, 3]` set in frontmatter. -- [ ] Spec meets the **READY FOR DEVELOPMENT** standard. diff --git a/src/workflows/gds-quick-flow/gds-quick-spec/steps/step-04-review.md b/src/workflows/gds-quick-flow/gds-quick-spec/steps/step-04-review.md deleted file mode 100644 index 5e2149e..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-spec/steps/step-04-review.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -name: 'step-04-review' -description: 'Review and finalize the tech-spec' - -wipFile: '{implementation_artifacts}/tech-spec-wip.md' ---- - -# Step 4: Review & Finalize - -**Progress: Step 4 of 4** - Final Step - -## RULES: - -- MUST NOT skip steps. -- MUST NOT optimize sequence. -- MUST follow exact instructions. -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -## CONTEXT: - -- Requires `{wipFile}` from Step 3. -- MUST present COMPLETE spec content. Iterate until user is satisfied. -- **Criteria**: The spec MUST meet the **READY FOR DEVELOPMENT** standard defined in `workflow.md`. - -## SEQUENCE OF INSTRUCTIONS - -### 1. Load and Present Complete Spec - -**Read `{wipFile}` completely and extract `slug` from frontmatter for later use.** - -**Present to user:** - -"Here's your complete tech-spec. Please review:" - -[Display the complete spec content - all sections] - -"**Quick Summary:** - -- {task_count} tasks to implement -- {ac_count} acceptance criteria to verify -- {files_count} files to modify" - -**Present review menu:** - -Display: "**Select:** [C] Continue [E] Edit [Q] Questions [A] Advanced Elicitation [P] Party Mode" - -**HALT and wait for user selection.** - -#### Menu Handling Logic: - -- IF C: Proceed to Section 3 (Finalize the Spec) -- IF E: Proceed to Section 2 (Handle Review Feedback), then return here and redisplay menu -- IF Q: Answer questions, then redisplay this menu -- IF A: Read fully and follow: `{advanced_elicitation}` with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu -- IF P: Read fully and follow: `{party_mode_exec}` with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu -- IF Any other comments or queries: respond helpfully then redisplay menu - -#### EXECUTION RULES: - -- ALWAYS halt and wait for user input after presenting menu -- ONLY proceed to finalize when user selects 'C' -- After other menu items execution, return to this menu - -### 2. Handle Review Feedback - -a) **If user requests changes:** - -- Make the requested edits to `{wipFile}` -- Re-present the affected sections -- Ask if there are more changes -- Loop until user is satisfied - -b) **If the spec does NOT meet the "Ready for Development" standard:** - -- Point out the missing/weak sections (e.g., non-actionable tasks, missing ACs). -- Propose specific improvements to reach the standard. -- Make the edits once the user agrees. - -c) **If user has questions:** - -- Answer questions about the spec -- Clarify any confusing sections -- Make clarifying edits if needed - -### 3. Finalize the Spec - -**When user confirms the spec is good AND it meets the "Ready for Development" standard:** - -a) Update `{wipFile}` frontmatter: - - ```yaml - --- - # ... existing values ... - status: 'ready-for-dev' - stepsCompleted: [1, 2, 3, 4] - --- - ``` - -b) **Rename WIP file to final filename:** - - Using the `slug` extracted in Section 1 - - Rename `{wipFile}` → `{implementation_artifacts}/tech-spec-{slug}.md` - - Store this as `finalFile` for use in menus below - -### 4. Present Final Menu - -a) **Display completion message and menu:** - -``` -**Tech-Spec Complete!** - -Saved to: {finalFile} - ---- - -**Next Steps:** - -[A] Advanced Elicitation - refine further -[R] Adversarial Review - critique of the spec (highly recommended) -[B] Begin Development - start implementing now (not recommended) -[D] Done - exit workflow -[P] Party Mode - get expert feedback before dev - ---- - -Once you are fully satisfied with the spec (ideally after **Adversarial Review** and maybe a few rounds of **Advanced Elicitation**), it is recommended to run implementation in a FRESH CONTEXT for best results. - -Copy this prompt to start dev: - -\`\`\` -quick-dev {finalFile} -\`\`\` - -This ensures the dev agent has clean context focused solely on implementation. -``` - -b) **HALT and wait for user selection.** - -#### Menu Handling Logic: - -- IF A: Read fully and follow: `{advanced_elicitation}` with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu -- IF B: Read fully and follow: `{quick_dev_workflow}` with the final spec file (warn: fresh context is better) -- IF D: Exit workflow - display final confirmation and path to spec -- IF P: Read fully and follow: `{party_mode_exec}` with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu -- IF R: Execute Adversarial Review (see below) -- IF Any other comments or queries: respond helpfully then redisplay menu - -#### EXECUTION RULES: - -- ALWAYS halt and wait for user input after presenting menu -- After A, P, or R execution, return to this menu - -#### Adversarial Review [R] Process: - -1. **Invoke Adversarial Review Task**: - > With `{finalFile}` constructed, invoke the review task. If possible, use information asymmetry: run this task, and only it, in a separate subagent or process with read access to the project, but no context except the `{finalFile}`. - <invoke-task>Review {finalFile} using skill:bmad-review-adversarial-general</invoke-task> - > **Platform fallback:** If skill invocation not available, execute the adversarial review instructions inline, passing `{finalFile}` as the content. - > The task should: review `{finalFile}` and return a list of findings. - - 2. **Process Findings**: - > Capture the findings from the task output. - > **If zero findings:** HALT - this is suspicious. Re-analyze or request user guidance. - > Evaluate severity (Critical, High, Medium, Low) and validity (real, noise, undecided). - > DO NOT exclude findings based on severity or validity unless explicitly asked to do so. - > Order findings by severity. - > Number the ordered findings (F1, F2, F3, etc.). - > If TodoWrite or similar tool is available, turn each finding into a TODO, include ID, severity, validity, and description in the TODO; otherwise present findings as a table with columns: ID, Severity, Validity, Description - - 3. Return here and redisplay menu. - -### 5. Exit Workflow - -**When user selects [D]:** - -"**All done!** Your tech-spec is ready at: - -`{finalFile}` - -When you're ready to implement, run: - -``` -quick-dev {finalFile} -``` - -Ship it!" - ---- - -## REQUIRED OUTPUTS: - -- MUST update status to 'ready-for-dev'. -- MUST rename file to `tech-spec-{slug}.md`. -- MUST provide clear next-step guidance and recommend fresh context for dev. - -## VERIFICATION CHECKLIST: - -- [ ] Complete spec presented for review. -- [ ] Requested changes implemented. -- [ ] Spec verified against **READY FOR DEVELOPMENT** standard. -- [ ] `stepsCompleted: [1, 2, 3, 4]` set and file renamed. diff --git a/src/workflows/gds-quick-flow/gds-quick-spec/tech-spec-template.md b/src/workflows/gds-quick-flow/gds-quick-spec/tech-spec-template.md deleted file mode 100644 index 8d20114..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-spec/tech-spec-template.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: '{title}' -slug: '{slug}' -created: '{date}' -status: 'in-progress' -stepsCompleted: [] -tech_stack: [] -files_to_modify: [] -code_patterns: [] -test_patterns: [] ---- - -# Tech-Spec: {title} - -**Created:** {date} - -## Overview - -### Problem Statement - -{problem_statement} - -### Solution - -{solution} - -### Scope - -**In Scope:** -{in_scope} - -**Out of Scope:** -{out_of_scope} - -## Context for Development - -### Codebase Patterns - -{codebase_patterns} - -### Files to Reference - -| File | Purpose | -| ---- | ------- | - -{files_table} - -### Technical Decisions - -{technical_decisions} - -## Implementation Plan - -### Tasks - -{tasks} - -### Acceptance Criteria - -{acceptance_criteria} - -## Additional Context - -### Dependencies - -{dependencies} - -### Testing Strategy - -{testing_strategy} - -### Notes - -{notes} diff --git a/src/workflows/gds-quick-flow/gds-quick-spec/workflow.md b/src/workflows/gds-quick-flow/gds-quick-spec/workflow.md deleted file mode 100644 index 438c4b7..0000000 --- a/src/workflows/gds-quick-flow/gds-quick-spec/workflow.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -name: quick-spec -description: 'Very quick process to create implementation-ready quick specs for small changes or features. Use when the user says "create a quick spec" or "generate a quick tech spec"' -main_config: '{module_config}' -web_bundle: true - -# Checkpoint handler references -advanced_elicitation: 'skill:gds-advanced-elicitation' -party_mode_exec: 'skill:bmad-party-mode' -quick_dev_workflow: 'skill:gds-quick-dev' ---- - -# Quick-Spec Workflow - -**Goal:** Create implementation-ready technical specifications through conversational discovery, code investigation, and structured documentation. - -**READY FOR DEVELOPMENT STANDARD:** - -A specification is considered "Ready for Development" ONLY if it meets the following: - -- **Actionable**: Every task has a clear file path and specific action. -- **Logical**: Tasks are ordered by dependency (lowest level first). -- **Testable**: All ACs follow Given/When/Then and cover happy path and edge cases. -- **Complete**: All investigation results from Step 2 are inlined; no placeholders or "TBD". -- **Self-Contained**: A fresh agent can implement the feature without reading the workflow history. - ---- - -**Your Role:** You are an elite developer and spec engineer. You ask sharp questions, investigate existing code thoroughly, and produce specs that contain ALL context a fresh dev agent needs to implement the feature. No handoffs, no missing context - just complete, actionable specs. - ---- - -## WORKFLOW ARCHITECTURE - -This uses **step-file architecture** for disciplined execution: - -### Core Principles - -- **Micro-file Design**: Each step is a self-contained instruction file that must be followed exactly -- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until directed -- **Sequential Enforcement**: Sequence within step files must be completed in order, no skipping or optimization -- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array -- **Append-Only Building**: Build the tech-spec by updating content as directed - -### Step Processing Rules - -1. **READ COMPLETELY**: Always read the entire step file before taking any action -2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate -3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection -4. **CHECK CONTINUATION**: Only proceed to next step when user selects [C] (Continue) -5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step -6. **LOAD NEXT**: When directed, read fully and follow the next step file - -### Critical Rules (NO EXCEPTIONS) - -- **NEVER** load multiple step files simultaneously -- **ALWAYS** read entire step file before execution -- **NEVER** skip steps or optimize the sequence -- **ALWAYS** update frontmatter of output file when completing a step -- **ALWAYS** follow the exact instructions in the step file -- **ALWAYS** halt at menus and wait for user input -- **NEVER** create mental todo lists from future steps - ---- - -## INITIALIZATION SEQUENCE - -### 1. Configuration Loading - -Load and read full config from `{main_config}` and resolve: - -- `project_name`, `output_folder`, `planning_artifacts`, `implementation_artifacts`, `user_name` -- `communication_language`, `document_output_language`, `game_dev_experience` -- `date` as system-generated current datetime -- `project_context` = `**/project-context.md` (load if exists) -- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}` - -### 2. First Step Execution - -Read fully and follow: `./step-01-understand.md` to begin the workflow.