Fix skill bugs: session state init, agent field cleanup, /start path, /sprint-plan phases

- Remove invalid `agent: Explore` frontmatter from read-only skills (asset-audit, design-review, project-stage-detect, reverse-document)
- Fix design-system and map-systems to create session-state/active.md if it does not exist before updating
- Fix gate-check to remove reference to non-existent bmad-bmm-check skill
- Expand /start recommended paths into phased roadmap (Concept → Architecture → Production)
- Restructure /sprint-plan into numbered phases with clearer next-steps section

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
2026-03-28 13:52:33 +11:00
parent 01722ad790
commit 167fb6c5f2
9 changed files with 68 additions and 22 deletions

View File

@@ -5,7 +5,7 @@ argument-hint: "[category|all]"
user-invocable: true user-invocable: true
allowed-tools: Read, Glob, Grep allowed-tools: Read, Glob, Grep
context: fork context: fork
agent: Explore # Read-only diagnostic skill — no specialist agent delegation needed
--- ---
## Phase 1: Read Standards ## Phase 1: Read Standards

View File

@@ -5,7 +5,7 @@ argument-hint: "[path-to-design-doc]"
user-invocable: true user-invocable: true
allowed-tools: Read, Glob, Grep allowed-tools: Read, Glob, Grep
context: fork context: fork
agent: Explore # Read-only diagnostic skill — no specialist agent delegation needed
--- ---
## Phase 1: Load Documents ## Phase 1: Load Documents

View File

@@ -268,7 +268,7 @@ Use the template structure from `.claude/docs/templates/game-design-document.md`
Ask: "May I create the skeleton file at `design/gdd/[system-name].md`?" Ask: "May I create the skeleton file at `design/gdd/[system-name].md`?"
After writing, update `production/session-state/active.md` with: After writing, create `production/session-state/active.md` if it does not exist, then update it with:
- Task: Designing [system-name] GDD - Task: Designing [system-name] GDD
- Current section: Starting (skeleton created) - Current section: Starting (skeleton created)
- File: design/gdd/[system-name].md - File: design/gdd/[system-name].md
@@ -602,7 +602,7 @@ Use `AskUserQuestion`:
If yes, invoke the design-review skill on the completed file. If yes, invoke the design-review skill on the completed file.
### 5c: Update Systems Index ### 5d: Update Systems Index
After the GDD is complete (and optionally reviewed): After the GDD is complete (and optionally reviewed):

View File

@@ -144,8 +144,8 @@ The project progresses through these stages:
- [ ] Architecture document has no unresolved open questions in Foundation or Core layers - [ ] Architecture document has no unresolved open questions in Foundation or Core layers
- [ ] All ADRs have Engine Compatibility sections stamped with the engine version - [ ] All ADRs have Engine Compatibility sections stamped with the engine version
- [ ] All ADRs have ADR Dependencies sections (even if all fields are "None") - [ ] All ADRs have ADR Dependencies sections (even if all fields are "None")
- [ ] `/bmad-bmm-check-implementation-readiness` has been run or equivalent manual - [ ] Manual validation confirms GDDs + architecture + epics are coherent
validation confirms GDDs + architecture + epics are coherent (run `/review-all-gdds` and `/architecture-review` if not done recently)
- [ ] **Core fantasy is delivered** — at least one playtester independently described an experience that matches the Player Fantasy section of the core system GDDs (without being prompted). - [ ] **Core fantasy is delivered** — at least one playtester independently described an experience that matches the Player Fantasy section of the core system GDDs (without being prompted).
**Vertical Slice Validation** (FAIL if any item is NO): **Vertical Slice Validation** (FAIL if any item is NO):

View File

@@ -202,7 +202,7 @@ Wait for approval. Write the file only after "yes."
### Step 5c: Update Session State ### Step 5c: Update Session State
After writing, update `production/session-state/active.md` with: After writing, create `production/session-state/active.md` if it does not exist, then update it with:
- Task: Systems decomposition - Task: Systems decomposition
- Status: Systems index created - Status: Systems index created
- File: design/gdd/systems-index.md - File: design/gdd/systems-index.md

View File

@@ -6,7 +6,7 @@ user-invocable: true
allowed-tools: Read, Glob, Grep, Bash, Write allowed-tools: Read, Glob, Grep, Bash, Write
context: fork context: fork
model: haiku model: haiku
agent: Explore # Read-only diagnostic skill — no specialist agent delegation needed
--- ---
# Project Stage Detection # Project Stage Detection

View File

@@ -5,7 +5,7 @@ argument-hint: "<type> <path> (e.g., 'design src/gameplay/combat' or 'architectu
user-invocable: true user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash allowed-tools: Read, Glob, Grep, Write, Edit, Bash
context: fork context: fork
agent: Explore # Read-only diagnostic skill — no specialist agent delegation needed
--- ---
# Reverse Documentation # Reverse Documentation

View File

@@ -8,7 +8,7 @@ context: |
!ls production/sprints/ 2>/dev/null !ls production/sprints/ 2>/dev/null
--- ---
When this skill is invoked: ## Phase 1: Gather Context
1. **Read the current milestone** from `production/milestones/`. 1. **Read the current milestone** from `production/milestones/`.
@@ -20,9 +20,13 @@ When this skill is invoked:
4. **Check the risk register** at `production/risk-register/`. 4. **Check the risk register** at `production/risk-register/`.
---
## Phase 2: Generate Output
For `new`: For `new`:
5. **Generate a sprint plan** following this format and present it to the user. Ask: "May I write this sprint plan to `production/sprints/sprint-[N].md`?" If yes, write the file, creating the directory if needed. Verdict: **COMPLETE** — sprint plan created. If no: Verdict: **BLOCKED** — user declined write. **Generate a sprint plan** following this format and present it to the user. Ask: "May I write this sprint plan to `production/sprints/sprint-[N].md`?" If yes, write the file, creating the directory if needed. Verdict: **COMPLETE** — sprint plan created. If no: Verdict: **BLOCKED** — user declined write.
```markdown ```markdown
# Sprint [N] -- [Start Date] to [End Date] # Sprint [N] -- [Start Date] to [End Date]
@@ -70,7 +74,7 @@ For `new`:
For `status`: For `status`:
5. **Generate a status report**: **Generate a status report**:
```markdown ```markdown
# Sprint [N] Status -- [Date] # Sprint [N] Status -- [Date]
@@ -101,7 +105,9 @@ For `status`:
- [Any new risks identified this sprint] - [Any new risks identified this sprint]
``` ```
### Sprint Status File ---
## Phase 3: Write Sprint Status File
After generating a new sprint plan, also write `production/sprint-status.yaml`. After generating a new sprint plan, also write `production/sprint-status.yaml`.
This is the machine-readable source of truth for story status — read by This is the machine-readable source of truth for story status — read by
@@ -142,16 +148,27 @@ Initialize each story from the sprint plan's task tables:
For `update`: read the existing `sprint-status.yaml`, carry over statuses for For `update`: read the existing `sprint-status.yaml`, carry over statuses for
stories that haven't changed, add new stories, remove dropped ones. stories that haven't changed, add new stories, remove dropped ones.
### Scope Reminder ---
## Phase 4: Scope and Risk Check
After presenting the sprint plan, add: After presenting the sprint plan, add:
> **Scope check:** If this sprint includes stories added beyond the original epic scope, run `/scope-check [epic]` to detect scope creep before implementation begins. > **Scope check:** If this sprint includes stories added beyond the original epic scope, run `/scope-check [epic]` to detect scope creep before implementation begins.
When reviewing stories during selection (step 3 above), note any stories that appear outside the original epic goals. If any are uncertain, flag them inline: "Are these stories within the original epic scope? If unsure, `/scope-check` can verify." When reviewing stories during selection, note any stories that appear outside the original epic goals. If any are uncertain, flag them inline: "Are these stories within the original epic scope? If unsure, `/scope-check` can verify."
### Agent Consultation
For comprehensive sprint planning, consider consulting: For comprehensive sprint planning, consider consulting:
- `producer` agent for capacity planning, risk assessment, and cross-department coordination - `producer` agent for capacity planning, risk assessment, and cross-department coordination
- `game-designer` agent for feature prioritization and design readiness assessment - `game-designer` agent for feature prioritization and design readiness assessment
---
## Phase 5: Next Steps
After the sprint plan is written, recommend:
- `/sprint-status` — check progress mid-sprint
- `/scope-check [epic]` — verify no scope creep before implementation begins
- `/dev-story [story-file]` — begin implementing the first story
- `/story-readiness [story-file]` — validate a story is ready before starting it

View File

@@ -61,10 +61,20 @@ The user needs creative exploration before anything else.
2. Briefly explain what `/brainstorm` does (guided ideation using professional frameworks — MDA, player psychology, verb-first design) 2. Briefly explain what `/brainstorm` does (guided ideation using professional frameworks — MDA, player psychology, verb-first design)
3. Recommend running `/brainstorm open` as the next step 3. Recommend running `/brainstorm open` as the next step
4. Show the recommended path: 4. Show the recommended path:
**Concept phase:**
- `/brainstorm` — discover your game concept - `/brainstorm` — discover your game concept
- `/setup-engine` — configure the engine (brainstorm will recommend one) - `/setup-engine` — configure the engine (brainstorm will recommend one)
- `/map-systems` — decompose the concept into systems and plan GDD writing order - `/map-systems` — decompose the concept into systems
- `/prototype` — test the core mechanic - `/design-system` — author a GDD for each MVP system
- `/review-all-gdds` — cross-system consistency check
- `/gate-check` — validate readiness before architecture work
**Architecture phase:**
- `/architecture-decision` — record key technical decisions (one per system)
- `/create-control-manifest` — compile decisions into an actionable rules sheet
- `/architecture-review` — validate architecture coverage
**Production phase:**
- `/create-epics` — map systems to epics
- `/create-stories` — break epics into implementable stories
- `/sprint-plan` — plan the first sprint - `/sprint-plan` — plan the first sprint
#### If B: Vague idea #### If B: Vague idea
@@ -73,10 +83,20 @@ The user needs creative exploration before anything else.
2. Validate the idea as a starting point (don't judge or redirect) 2. Validate the idea as a starting point (don't judge or redirect)
3. Recommend running `/brainstorm [their hint]` to develop it 3. Recommend running `/brainstorm [their hint]` to develop it
4. Show the recommended path: 4. Show the recommended path:
**Concept phase:**
- `/brainstorm [hint]` — develop the idea into a full concept - `/brainstorm [hint]` — develop the idea into a full concept
- `/setup-engine` — configure the engine - `/setup-engine` — configure the engine
- `/map-systems` — decompose the concept into systems - `/map-systems` — decompose the concept into systems
- `/prototype` — test the core mechanic - `/design-system` — author a GDD for each MVP system
- `/review-all-gdds` — cross-system consistency check
- `/gate-check` — validate readiness before architecture work
**Architecture phase:**
- `/architecture-decision` — record key technical decisions (one per system)
- `/create-control-manifest` — compile decisions into an actionable rules sheet
- `/architecture-review` — validate architecture coverage
**Production phase:**
- `/create-epics` — map systems to epics
- `/create-stories` — break epics into implementable stories
- `/sprint-plan` — plan the first sprint - `/sprint-plan` — plan the first sprint
#### If C: Clear concept #### If C: Clear concept
@@ -89,11 +109,20 @@ The user needs creative exploration before anything else.
- **Formalize first**: Run `/brainstorm` to structure the concept into a proper game concept document - **Formalize first**: Run `/brainstorm` to structure the concept into a proper game concept document
- **Jump to engine setup**: Go straight to `/setup-engine` and write the GDD manually afterward - **Jump to engine setup**: Go straight to `/setup-engine` and write the GDD manually afterward
3. Show the recommended path: 3. Show the recommended path:
**Concept phase:**
- `/brainstorm` or `/setup-engine` (their pick) - `/brainstorm` or `/setup-engine` (their pick)
- `/design-review` — validate the concept doc - `/design-review` — validate the concept doc
- `/map-systems` — decompose the concept into individual systems - `/map-systems` — decompose the concept into individual systems
- `/design-system` — author per-system GDDs - `/design-system` — author a GDD for each MVP system
- `/architecture-decision` — make first technical decisions - `/review-all-gdds` — cross-system consistency check
- `/gate-check` — validate readiness before architecture work
**Architecture phase:**
- `/architecture-decision` — record key technical decisions (one per system)
- `/create-control-manifest` — compile decisions into an actionable rules sheet
- `/architecture-review` — validate architecture coverage
**Production phase:**
- `/create-epics` — map systems to epics
- `/create-stories` — break epics into implementable stories
- `/sprint-plan` — plan the first sprint - `/sprint-plan` — plan the first sprint
#### If D: Existing work #### If D: Existing work