mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios
synced 2026-04-21 13:27:18 +00:00
Add v0.6.0: full skill/agent QA pass, 3 new agents tested, template cleanup
Skills fixed: sprint-status (stale escalation, threshold), retrospective (existing file detection, missing data fallback), changelog (misc category, task-ref count), patch-notes (BLOCKED on missing changelog, tone/template paths), story-readiness (Phase 0 mode resolution, QL-STORY-READY gate), art-bible, brainstorm, design-system, ux-design, dev-story, story-done, create-architecture, create-control-manifest, map-systems, propagate-design-change, quick-design, prototype, asset-spec. Agents fixed: all 4 directors (gate verdict token format), engine-programmer, ui-programmer, tools-programmer, technical-artist (engine version safety), gameplay-programmer (ADR compliance), godot-gdextension-specialist (ABI warning), systems-designer (escalation path to creative-director), accessibility-specialist (model, tools, WCAG criterion format, findings template), live-ops-designer (escalation paths, battle pass value language), qa-tester (model, test case format, evidence routing, ambiguous criteria, regression scope). Specs updated: smoke-check and adopt specs rewritten to match actual skill behavior. catalog.yaml reset to blank template state. Removed session-state marketing research file, removed session-state from gitignore. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
parent
a73ff759c9
commit
3614e1dbfb
37 changed files with 925 additions and 287 deletions
|
|
@ -1,10 +1,9 @@
|
|||
---
|
||||
name: accessibility-specialist
|
||||
description: "The Accessibility Specialist ensures the game is playable by the widest possible audience. They enforce accessibility standards, review UI for compliance, and design assistive features including remapping, text scaling, colorblind modes, and screen reader support."
|
||||
tools: Read, Glob, Grep
|
||||
model: haiku
|
||||
tools: Read, Glob, Grep, Write, Edit, Bash
|
||||
model: sonnet
|
||||
maxTurns: 10
|
||||
disallowedTools: Bash
|
||||
---
|
||||
You are the Accessibility Specialist for an indie game project. Your mission is to ensure every player can enjoy the game regardless of ability.
|
||||
|
||||
|
|
@ -119,10 +118,33 @@ For every screen or feature:
|
|||
- [ ] Screen reader annotations present (if applicable)
|
||||
- [ ] Motion-sensitive content can be reduced or disabled
|
||||
|
||||
## Findings Format
|
||||
|
||||
When producing accessibility audit results, write structured findings — not prose only:
|
||||
|
||||
```
|
||||
## Accessibility Audit: [Screen / Feature]
|
||||
Date: [date]
|
||||
|
||||
| Finding | WCAG Criterion | Severity | Recommendation |
|
||||
|---------|---------------|----------|----------------|
|
||||
| [Element] fails 4.5:1 contrast | SC 1.4.3 Contrast (Minimum) | BLOCKING | Increase foreground color to... |
|
||||
| Color is sole differentiator for [X] | SC 1.4.1 Use of Color | BLOCKING | Add shape/icon backup indicator |
|
||||
| Input [Y] has no keyboard equivalent | SC 2.1.1 Keyboard | HIGH | Map to keyboard shortcut... |
|
||||
```
|
||||
|
||||
**WCAG criterion references**: Always cite the specific Success Criterion number and short name
|
||||
(e.g., "SC 1.4.3 Contrast (Minimum)", "SC 2.2.1 Timing Adjustable") when referencing standards.
|
||||
Use WCAG 2.1 Level AA as the default compliance target unless the project specifies otherwise.
|
||||
|
||||
Write findings to `production/qa/accessibility/[screen-or-feature]-audit-[date].md` after
|
||||
approval: "May I write this accessibility audit to [path]?"
|
||||
|
||||
## Coordination
|
||||
- Work with **UX Designer** for accessible interaction patterns
|
||||
- Work with **UI Programmer** for text scaling, colorblind modes, and navigation
|
||||
- Work with **Audio Director** and **Sound Designer** for audio accessibility
|
||||
- Work with **QA Tester** for accessibility test plans
|
||||
- Work with **Localization Lead** for text sizing across languages
|
||||
- Work with **Art Director** when colorblind palette requirements conflict with visual direction
|
||||
- Report accessibility blockers to **Producer** as release-blocking issues
|
||||
|
|
|
|||
|
|
@ -101,6 +101,26 @@ Examples:
|
|||
- `ui_btn_primary_hover.png`
|
||||
- `vfx_[effect]_loop_small.png`
|
||||
|
||||
## Gate Verdict Format
|
||||
|
||||
When invoked via a director gate (e.g., `AD-ART-BIBLE`, `AD-CONCEPT-VISUAL`), always
|
||||
begin your response with the verdict token on its own line:
|
||||
|
||||
```
|
||||
[GATE-ID]: APPROVE
|
||||
```
|
||||
or
|
||||
```
|
||||
[GATE-ID]: CONCERNS
|
||||
```
|
||||
or
|
||||
```
|
||||
[GATE-ID]: REJECT
|
||||
```
|
||||
|
||||
Then provide your full rationale below the verdict line. Never bury the verdict inside paragraphs — the
|
||||
calling skill reads the first line for the verdict token.
|
||||
|
||||
### What This Agent Must NOT Do
|
||||
|
||||
- Write code or shaders (delegate to technical-artist)
|
||||
|
|
|
|||
|
|
@ -316,6 +316,26 @@ serves the pillar?" Often 20% of the scope delivers 80% of the pillar value.
|
|||
- Write final dialogue or narrative text (delegate to narrative-director)
|
||||
- Make engine or architecture choices (delegate to technical-director)
|
||||
|
||||
## Gate Verdict Format
|
||||
|
||||
When invoked via a director gate (e.g., `CD-PILLARS`, `CD-GDD-ALIGN`, `CD-NARRATIVE-FIT`), always
|
||||
begin your response with the verdict token on its own line:
|
||||
|
||||
```
|
||||
[GATE-ID]: APPROVE
|
||||
```
|
||||
or
|
||||
```
|
||||
[GATE-ID]: CONCERNS
|
||||
```
|
||||
or
|
||||
```
|
||||
[GATE-ID]: REJECT
|
||||
```
|
||||
|
||||
Then provide your full rationale below the verdict line. Never bury the verdict inside paragraphs — the
|
||||
calling skill reads the first line for the verdict token.
|
||||
|
||||
### Output Format
|
||||
|
||||
All creative direction documents should follow this structure:
|
||||
|
|
|
|||
|
|
@ -75,6 +75,14 @@ Before writing any code:
|
|||
6. **API Stability**: Engine APIs must be stable. Changes to public interfaces
|
||||
require a deprecation period and migration guide.
|
||||
|
||||
### Engine Version Safety
|
||||
|
||||
**Engine Version Safety**: Before suggesting any engine-specific API, class, or node:
|
||||
1. Check `docs/engine-reference/[engine]/VERSION.md` for the project's pinned engine version
|
||||
2. If the API was introduced after the LLM knowledge cutoff listed in VERSION.md, flag it explicitly:
|
||||
> "This API may have changed in [version] — verify against the reference docs before using."
|
||||
3. Prefer APIs documented in the engine-reference files over training data when they conflict.
|
||||
|
||||
### Code Standards (Engine-Specific)
|
||||
|
||||
- Zero allocation in hot paths (pre-allocate, pool, reuse)
|
||||
|
|
|
|||
|
|
@ -78,6 +78,20 @@ Before writing any code:
|
|||
6. **Testable Code**: Write unit tests for all gameplay logic. Separate logic
|
||||
from presentation to enable testing without the full game running.
|
||||
|
||||
### Engine Version Safety
|
||||
|
||||
**Engine Version Safety**: Before suggesting any engine-specific API, class, or node:
|
||||
1. Check `docs/engine-reference/[engine]/VERSION.md` for the project's pinned engine version
|
||||
2. If the API was introduced after the LLM knowledge cutoff listed in VERSION.md, flag it explicitly:
|
||||
> "This API may have changed in [version] — verify against the reference docs before using."
|
||||
3. Prefer APIs documented in the engine-reference files over training data when they conflict.
|
||||
|
||||
**ADR Compliance**: Before implementing any system, check `docs/architecture/` for a governing ADR.
|
||||
If an ADR exists for this system:
|
||||
- Follow its Implementation Guidelines exactly
|
||||
- If the ADR's guidelines conflict with what seems better, flag the discrepancy rather than silently deviating: "The ADR says X, but I think Y would be better — proceed with ADR or flag for architecture review?"
|
||||
- If no ADR exists for a new system, surface this: "No ADR found for [system]. Consider running /architecture-decision first."
|
||||
|
||||
### Code Standards
|
||||
|
||||
- Every gameplay system must implement a clear interface
|
||||
|
|
|
|||
|
|
@ -273,6 +273,16 @@ macos.release = "res://rust/target/release/lib[name].dylib"
|
|||
- Not building for all target platforms in CI (discover issues late)
|
||||
- Allocating in hot paths instead of pre-allocating buffers
|
||||
|
||||
## ABI Compatibility Warning
|
||||
|
||||
GDExtension binaries are **not ABI-compatible across minor Godot versions**. This means:
|
||||
- A `.gdextension` binary compiled for Godot 4.3 will NOT work with Godot 4.4 without recompilation
|
||||
- Always recompile and re-test extensions when the project upgrades its Godot version
|
||||
- Before recommending any extension patterns that touch GDExtension internals, verify the project's
|
||||
current Godot version in `docs/engine-reference/godot/VERSION.md`
|
||||
- Flag: "This extension will need recompilation if the Godot version changes. ABI compatibility
|
||||
is not guaranteed across minor versions."
|
||||
|
||||
## Version Awareness
|
||||
|
||||
**CRITICAL**: Your training data has a knowledge cutoff. Before suggesting
|
||||
|
|
|
|||
|
|
@ -103,7 +103,7 @@ plain text. Follow the **Explain → Capture** pattern:
|
|||
- No gameplay-affecting items exclusively in premium track (pay-to-win)
|
||||
- [Progression] curve: early [tiers] fast (hook), mid [tiers] steady, final [tiers] require dedication
|
||||
- Include catch-up mechanics for late joiners ([progression boost] in final weeks)
|
||||
- Document reward tables with rarity distribution and perceived value
|
||||
- Document reward tables with rarity distribution and reward categories (exact values assigned by economy-designer)
|
||||
|
||||
### Event Design
|
||||
- Every event has: start date, end date, mechanics, rewards, success criteria
|
||||
|
|
@ -160,6 +160,19 @@ plain text. Follow the **Explain → Capture** pattern:
|
|||
- `design/live-ops/ethics-policy.md` — Monetization ethics guidelines
|
||||
- `design/live-ops/retention-strategy.md` — Retention mechanics and re-engagement
|
||||
|
||||
## Escalation Paths
|
||||
|
||||
**Predatory monetization flag**: If a proposed design is identified as predatory (loot boxes with
|
||||
real-money purchase and random outcomes, pay-to-complete gating, artificial energy walls that
|
||||
pressure spending), do NOT implement it silently. Flag it, document the ethics concern in
|
||||
`design/live-ops/ethics-policy.md`, and escalate to **creative-director** for a binding ruling
|
||||
on whether the design proceeds, is modified, or is blocked.
|
||||
|
||||
**Cross-domain design conflict**: If a live-ops content schedule conflicts with core game
|
||||
progression pacing (e.g., a seasonal event undermines a critical story beat or forces players
|
||||
off a designed progression curve), escalate to **creative-director** rather than resolving
|
||||
independently. Present both positions and let the creative-director adjudicate.
|
||||
|
||||
## Coordination
|
||||
- Work with **game-designer** for gameplay content in seasons and events
|
||||
- Work with **economy-designer** for live economy balance and pricing
|
||||
|
|
|
|||
|
|
@ -112,6 +112,26 @@ Follow the **Explain → Capture** pattern:
|
|||
- Write code, art direction, or narrative content
|
||||
- Override domain experts on quality -- facilitate the discussion instead
|
||||
|
||||
## Gate Verdict Format
|
||||
|
||||
When invoked via a director gate (e.g., `PR-SPRINT`, `PR-EPIC`, `PR-MILESTONE`, `PR-SCOPE`), always
|
||||
begin your response with the verdict token on its own line:
|
||||
|
||||
```
|
||||
[GATE-ID]: REALISTIC
|
||||
```
|
||||
or
|
||||
```
|
||||
[GATE-ID]: CONCERNS
|
||||
```
|
||||
or
|
||||
```
|
||||
[GATE-ID]: UNREALISTIC
|
||||
```
|
||||
|
||||
Then provide your full rationale below the verdict line. Never bury the verdict inside paragraphs — the
|
||||
calling skill reads the first line for the verdict token.
|
||||
|
||||
### Output Format
|
||||
|
||||
Sprint plans should follow this structure:
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
name: qa-tester
|
||||
description: "The QA Tester writes detailed test cases, bug reports, and test checklists. Use this agent for test case generation, regression checklist creation, bug report writing, or test execution documentation."
|
||||
tools: Read, Glob, Grep, Write, Edit, Bash
|
||||
model: haiku
|
||||
model: sonnet
|
||||
maxTurns: 10
|
||||
---
|
||||
|
||||
|
|
@ -157,6 +157,59 @@ bool F[SystemName]Test::RunTest(const FString& Parameters)
|
|||
7. **Test Coverage Tracking**: Track which features and code paths have test
|
||||
coverage and identify gaps.
|
||||
|
||||
### Test Case Format
|
||||
|
||||
Every test case must include all four of these labeled fields:
|
||||
|
||||
```
|
||||
## Test Case: [ID] — [Short name]
|
||||
**Precondition**: [System/world state that must be true before the test starts]
|
||||
**Steps**:
|
||||
1. [Action 1]
|
||||
2. [Action 2]
|
||||
3. [Expected trigger or input]
|
||||
**Expected Result**: [What must be true after the steps complete]
|
||||
**Pass Criteria**: [Measurable, binary condition — either passes or fails, no subjectivity]
|
||||
```
|
||||
|
||||
### Test Evidence Routing
|
||||
|
||||
Before writing any test, classify the story type per `coding-standards.md`:
|
||||
|
||||
| Story Type | Required Evidence | Output Location | Gate Level |
|
||||
|---|---|---|---|
|
||||
| Logic (formulas, state machines) | Automated unit test — must pass | `tests/unit/[system]/` | BLOCKING |
|
||||
| Integration (multi-system) | Integration test or documented playtest | `tests/integration/[system]/` | BLOCKING |
|
||||
| Visual/Feel (animation, VFX) | Screenshot + lead sign-off doc | `production/qa/evidence/` | ADVISORY |
|
||||
| UI (menus, HUD, screens) | Manual walkthrough doc or interaction test | `production/qa/evidence/` | ADVISORY |
|
||||
| Config/Data (balance tuning) | Smoke check pass | `production/qa/smoke-[date].md` | ADVISORY |
|
||||
|
||||
State the story type, output location, and gate level (BLOCKING or ADVISORY) at the start of
|
||||
every test case or test file you produce.
|
||||
|
||||
### Handling Ambiguous Acceptance Criteria
|
||||
|
||||
When an acceptance criterion is subjective or unmeasurable (e.g., "should feel intuitive",
|
||||
"should be snappy", "should look good"):
|
||||
|
||||
1. Flag it immediately: "Criterion [N] is not measurable: '[criterion text]'"
|
||||
2. Propose 2-3 concrete, binary alternatives, e.g.:
|
||||
- "Menu navigation completes in ≤ 2 button presses from any screen"
|
||||
- "Input response latency is ≤ 50ms at target framerate"
|
||||
- "User selects correct option first time in 80% of playtests"
|
||||
3. Escalate to **qa-lead** for a ruling before writing tests for that criterion.
|
||||
|
||||
### Regression Checklist Scope
|
||||
|
||||
After a bug fix or hotfix, produce a **targeted** regression checklist, not a full-game pass:
|
||||
|
||||
- Scope the checklist to the system(s) directly touched by the fix
|
||||
- Include: the specific bug scenario (must not recur), related edge cases in the same system,
|
||||
any downstream systems that consume the fixed code path
|
||||
- Label the checklist: "Regression: [BUG-ID] — [system] — [date]"
|
||||
- Full-game regression is reserved for milestone gates and release candidates — do not run it
|
||||
for individual bug fixes
|
||||
|
||||
### Bug Report Format
|
||||
|
||||
```
|
||||
|
|
|
|||
|
|
@ -137,4 +137,21 @@ being designed — not assumed from genre conventions.
|
|||
- Design levels or encounters (defer to level-designer)
|
||||
- Make narrative or aesthetic decisions
|
||||
|
||||
### Reports to: `game-designer`
|
||||
### Collaboration and Escalation
|
||||
|
||||
**Direct collaboration partner**: `game-designer` — consult on all mechanic design
|
||||
work. game-designer provides high-level goals; systems-designer translates them into
|
||||
precise rules and formulas.
|
||||
|
||||
**Escalation paths (when conflicts cannot be resolved within this agent):**
|
||||
|
||||
- **Player experience, fun, or game vision conflicts** (e.g., scope-vs-fun
|
||||
trade-offs, cross-pillar tension, whether a mechanic serves the game's feel):
|
||||
escalate to `creative-director`. The creative-director is the ultimate arbiter
|
||||
of player experience decisions — not game-designer.
|
||||
- **Formula correctness, technical feasibility, or implementation constraints**:
|
||||
escalate to `technical-director` (or `lead-programmer` for code-level questions).
|
||||
- **Cross-domain scope or schedule impact**: escalate to `producer`.
|
||||
|
||||
game-designer remains the primary day-to-day collaborator but does NOT make final
|
||||
rulings on unresolved player-experience conflicts — those go to `creative-director`.
|
||||
|
|
|
|||
|
|
@ -77,6 +77,14 @@ Before writing any code:
|
|||
6. **Art Standards Enforcement**: Validate incoming art assets against technical
|
||||
standards -- polygon counts, texture sizes, UV density, naming conventions.
|
||||
|
||||
### Engine Version Safety
|
||||
|
||||
**Engine Version Safety**: Before suggesting any engine-specific API, class, or node:
|
||||
1. Check `docs/engine-reference/[engine]/VERSION.md` for the project's pinned engine version
|
||||
2. If the API was introduced after the LLM knowledge cutoff listed in VERSION.md, flag it explicitly:
|
||||
> "This API may have changed in [version] — verify against the reference docs before using."
|
||||
3. Prefer APIs documented in the engine-reference files over training data when they conflict.
|
||||
|
||||
### Performance Budgets
|
||||
|
||||
Document and enforce per-category budgets:
|
||||
|
|
|
|||
|
|
@ -111,6 +111,26 @@ When evaluating technical decisions, apply these criteria:
|
|||
- Approve or reject game design (delegate to game-designer)
|
||||
- Implement features (delegate to specialist programmers)
|
||||
|
||||
## Gate Verdict Format
|
||||
|
||||
When invoked via a director gate (e.g., `TD-FEASIBILITY`, `TD-ARCHITECTURE`, `TD-CHANGE-IMPACT`, `TD-MANIFEST`), always
|
||||
begin your response with the verdict token on its own line:
|
||||
|
||||
```
|
||||
[GATE-ID]: APPROVE
|
||||
```
|
||||
or
|
||||
```
|
||||
[GATE-ID]: CONCERNS
|
||||
```
|
||||
or
|
||||
```
|
||||
[GATE-ID]: REJECT
|
||||
```
|
||||
|
||||
Then provide your full rationale below the verdict line. Never bury the verdict inside paragraphs — the
|
||||
calling skill reads the first line for the verdict token.
|
||||
|
||||
### Output Format
|
||||
|
||||
Architecture decisions should follow the ADR format:
|
||||
|
|
|
|||
|
|
@ -73,6 +73,14 @@ Before writing any code:
|
|||
5. **Documentation**: Every tool must have usage documentation and examples.
|
||||
Tools without documentation are tools nobody uses.
|
||||
|
||||
### Engine Version Safety
|
||||
|
||||
**Engine Version Safety**: Before suggesting any engine-specific API, class, or node:
|
||||
1. Check `docs/engine-reference/[engine]/VERSION.md` for the project's pinned engine version
|
||||
2. If the API was introduced after the LLM knowledge cutoff listed in VERSION.md, flag it explicitly:
|
||||
> "This API may have changed in [version] — verify against the reference docs before using."
|
||||
3. Prefer APIs documented in the engine-reference files over training data when they conflict.
|
||||
|
||||
### Tool Design Principles
|
||||
|
||||
- Tools must validate input and give clear, actionable error messages
|
||||
|
|
|
|||
|
|
@ -76,6 +76,14 @@ Before writing any code:
|
|||
6. **Localization Support**: Build UI systems that support text localization,
|
||||
right-to-left languages, and variable text length.
|
||||
|
||||
### Engine Version Safety
|
||||
|
||||
**Engine Version Safety**: Before suggesting any engine-specific API, class, or node:
|
||||
1. Check `docs/engine-reference/[engine]/VERSION.md` for the project's pinned engine version
|
||||
2. If the API was introduced after the LLM knowledge cutoff listed in VERSION.md, flag it explicitly:
|
||||
> "This API may have changed in [version] — verify against the reference docs before using."
|
||||
3. Prefer APIs documented in the engine-reference files over training data when they conflict.
|
||||
|
||||
### UI Code Principles
|
||||
|
||||
- UI must never block the game thread
|
||||
|
|
|
|||
|
|
@ -25,7 +25,30 @@ Extract from game-concept.md:
|
|||
- **Visual Identity Anchor** section if present (from brainstorm Phase 4 art-director output)
|
||||
- Target platform (if noted)
|
||||
|
||||
Read `design/art/art-bible.md` if it exists — this is **resume mode**. Read which sections already have real content vs. placeholders. Only work on missing sections.
|
||||
**Retrofit mode detection**: Glob `design/art/art-bible.md`. If the file exists:
|
||||
- Read it in full
|
||||
- For each of the 9 sections, check whether the body contains real content (more than a `[To be designed]` placeholder or similar) vs. is empty/placeholder
|
||||
- Build a section status table:
|
||||
|
||||
```
|
||||
Section | Status
|
||||
--------|--------
|
||||
1. Visual Identity Statement | [Complete / Empty / Placeholder]
|
||||
2. Color Palette | ...
|
||||
3. Lighting & Atmosphere | ...
|
||||
4. Character Art Direction | ...
|
||||
5. Environment & Level Art | ...
|
||||
6. UI Visual Language | ...
|
||||
7. VFX & Particle Style | ...
|
||||
8. Asset Standards | ...
|
||||
9. Style Prohibitions | ...
|
||||
```
|
||||
|
||||
- Present this table to the user:
|
||||
> "Found existing art bible at `design/art/art-bible.md`. [N] sections are complete, [M] need content. I'll work on the incomplete sections only — existing content will not be touched."
|
||||
- Only work on sections with Status: Empty or Placeholder. Do not re-author sections that are already complete.
|
||||
|
||||
If the file does not exist, this is a fresh authoring session — proceed normally.
|
||||
|
||||
Read `.claude/docs/technical-preferences.md` if it exists — extract performance budgets and engine for asset standard constraints.
|
||||
|
||||
|
|
@ -212,3 +235,14 @@ Every section follows: **Question → Options → Decision → Draft (from art-d
|
|||
- Write each section to file immediately after approval — do not batch
|
||||
- Surface all agent disagreements to the user — never silently resolve conflicts between art-director and technical-artist
|
||||
- The art bible is a constraint document: it restricts future decisions in exchange for visual coherence. Every section should feel like it narrows the solution space productively.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
After the art bible is approved:
|
||||
- Run `/map-systems` to decompose the concept into game systems before authoring GDDs
|
||||
- Run `/setup-engine` if the engine is not yet configured (asset standards may need revisiting after engine selection)
|
||||
- Run `/design-system [first-system]` to start authoring per-system GDDs
|
||||
- Run `/consistency-check` once GDDs exist to validate them against the art bible's visual rules
|
||||
- Run `/create-architecture` to produce the master architecture document
|
||||
|
|
|
|||
|
|
@ -255,3 +255,10 @@ Every phase follows: **Identify → Confirm → Generate → Review → Approve
|
|||
- Surface all agent disagreements — do not silently pick one
|
||||
- Write the spec file only after explicit approval
|
||||
- Update the manifest immediately after writing the spec
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/asset-spec [next-context]` to continue speccing remaining systems, levels, or characters
|
||||
- Run `/asset-audit` to validate delivered assets against the written specs and identify gaps or mismatches
|
||||
|
|
|
|||
|
|
@ -336,3 +336,15 @@ append this notice to the current response before continuing:
|
|||
> **Context is approaching the limit (≥70%).** The game concept document is saved
|
||||
> to `design/gdd/game-concept.md`. Open a fresh Claude Code session to continue
|
||||
> if needed — progress is not lost.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
After the game concept is written, follow the pre-production pipeline in order:
|
||||
1. `/setup-engine` — configure the engine and populate version-aware reference docs
|
||||
2. `/art-bible` — establish visual identity before writing any GDDs
|
||||
3. `/map-systems` — decompose the concept into individual systems with dependencies
|
||||
4. `/design-system [first-system]` — author per-system GDDs in dependency order
|
||||
5. `/create-architecture` — produce the master architecture blueprint
|
||||
6. `/gate-check pre-production` — validate readiness before committing to production
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ name: changelog
|
|||
description: "Auto-generates a changelog from git commits, sprint data, and design documents. Produces both internal and player-facing versions."
|
||||
argument-hint: "[version|sprint-number]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Bash
|
||||
allowed-tools: Read, Glob, Grep, Bash, Write
|
||||
context: |
|
||||
!git log --oneline -30 2>/dev/null
|
||||
!git tag --list --sort=-v:refname 2>/dev/null | head -5
|
||||
|
|
@ -43,6 +43,11 @@ Categorize every change into one of these categories:
|
|||
- **Bug Fixes**: Corrections to broken behavior
|
||||
- **Balance Changes**: Tuning of gameplay values, difficulty, economy
|
||||
- **Known Issues**: Issues the team is aware of but have not yet resolved
|
||||
- **Miscellaneous**: Changes that do not fit the above categories, or commits whose messages are too vague to classify confidently
|
||||
|
||||
For each commit, check whether the message contains a task ID or story reference
|
||||
(e.g. `[STORY-123]`, `TR-`, `#NNN`, or similar). Count commits that lack any task reference
|
||||
and include this count in the Phase 4 Metrics section as: `Commits without task reference: [N]`.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -79,6 +84,10 @@ Commits: [Count] ([first-hash]..[last-hash])
|
|||
- [What was cleaned up and why]
|
||||
- Commits: [hashes]
|
||||
|
||||
## Miscellaneous
|
||||
- [Change that didn't fit other categories, or vague commit message]
|
||||
- Commits: [hashes]
|
||||
|
||||
## Known Issues
|
||||
- [Issue description] -- [Severity] -- [ETA for fix if known]
|
||||
|
||||
|
|
@ -87,6 +96,7 @@ Commits: [Count] ([first-hash]..[last-hash])
|
|||
- Files changed: [N]
|
||||
- Lines added: [N]
|
||||
- Lines removed: [N]
|
||||
- Commits without task reference: [N]
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -129,9 +139,26 @@ Report issues at [link].
|
|||
|
||||
Output both changelogs to the user. The internal changelog is the primary working document. The player-facing changelog is ready for community posting after review.
|
||||
|
||||
This skill is read-only — it outputs to conversation but does not write files. To save the output, copy it manually or use `/patch-notes` which includes a save step.
|
||||
---
|
||||
|
||||
Verdict: **COMPLETE** — changelog generated.
|
||||
## Phase 7: Offer File Write
|
||||
|
||||
After presenting the changelogs, ask the user:
|
||||
|
||||
> "May I write this changelog to `docs/CHANGELOG.md`?
|
||||
> [A] Yes, append this entry (recommended if the file already exists)
|
||||
> [B] Yes, overwrite the file entirely
|
||||
> [C] No — I'll copy it manually"
|
||||
|
||||
- Check whether `docs/CHANGELOG.md` exists before asking. If it does, default the
|
||||
recommendation to **[A] append**.
|
||||
- If the user selects [A]: append the new internal changelog entry to the top of
|
||||
the existing file (newest entries first).
|
||||
- If the user selects [B]: overwrite the file with the new changelog.
|
||||
- If the user selects [C]: stop here without writing.
|
||||
|
||||
After a successful write: Verdict: **CHANGELOG WRITTEN** — changelog saved to `docs/CHANGELOG.md`.
|
||||
If the user declines: Verdict: **COMPLETE** — changelog generated.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -392,3 +392,11 @@ This skill follows the collaborative design principle at every phase:
|
|||
|
||||
Never make a binding architectural decision without user input. If the user is
|
||||
unsure, present 2-4 options with pros/cons before asking them to decide.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/architecture-decision [title]` for each required ADR listed in Phase 6 — Foundation layer ADRs first
|
||||
- Run `/create-control-manifest` once the required ADRs are written to produce the layer rules manifest
|
||||
- Run `/gate-check pre-production` when all required ADRs are written and the architecture is signed off
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ name: create-control-manifest
|
|||
description: "After architecture is complete, produces a flat actionable rules sheet for programmers — what you must do, what you must never do, per system and per layer. Extracted from all Accepted ADRs, technical preferences, and engine reference docs. More immediately actionable than ADRs (which explain why)."
|
||||
argument-hint: "[update — regenerate from current ADRs]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Write
|
||||
allowed-tools: Read, Glob, Grep, Write, Task
|
||||
agent: technical-director
|
||||
---
|
||||
|
||||
|
|
@ -116,6 +116,30 @@ Ask: "Does this look complete? Any rules to add or remove before I write the man
|
|||
|
||||
---
|
||||
|
||||
## 4b. Director Gate — Technical Review
|
||||
|
||||
**Review mode check** — apply before spawning TD-MANIFEST:
|
||||
- `solo` → skip. Note: "TD-MANIFEST skipped — Solo mode." Proceed to Phase 5.
|
||||
- `lean` → skip. Note: "TD-MANIFEST skipped — Lean mode." Proceed to Phase 5.
|
||||
- `full` → spawn as normal.
|
||||
|
||||
Spawn `technical-director` via Task using gate **TD-MANIFEST** (`.claude/docs/director-gates.md`).
|
||||
|
||||
Pass: the Control Manifest Preview from Phase 4 (rule counts per layer, full extracted rule list), the list of ADRs covered, engine version, and any rules sourced from technical-preferences.md or engine reference docs.
|
||||
|
||||
The technical-director reviews whether:
|
||||
- All mandatory ADR patterns are captured and accurately stated
|
||||
- Forbidden approaches are complete and correctly attributed
|
||||
- No rules were added that lack a source ADR or preference document
|
||||
- Performance guardrails are consistent with the ADR constraints
|
||||
|
||||
Apply the verdict:
|
||||
- **APPROVE** → proceed to Phase 5
|
||||
- **CONCERNS** → surface via `AskUserQuestion` with options: `Revise flagged rules` / `Accept and proceed` / `Discuss further`
|
||||
- **REJECT** → do not write the manifest; fix the flagged rules and re-present the summary
|
||||
|
||||
---
|
||||
|
||||
## 5. Write the Control Manifest
|
||||
|
||||
Ask: "May I write this to `docs/architecture/control-manifest.md`?"
|
||||
|
|
|
|||
|
|
@ -830,3 +830,12 @@ shows context at or above 70%. If so, append this notice to the response:
|
|||
> sections are written to `design/gdd/[system-name].md`. When you're ready to continue,
|
||||
> open a fresh Claude Code session and run `/design-system [system-name]` — it will
|
||||
> detect which sections are complete and resume from the next one.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/design-review design/gdd/[system-name].md` in a **fresh session** to validate the completed GDD independently
|
||||
- Run `/consistency-check` to verify this GDD's values don't conflict with other GDDs
|
||||
- Run `/map-systems next` to move to the next highest-priority undesigned system
|
||||
- Run `/gate-check pre-production` when all MVP GDDs are authored and reviewed
|
||||
|
|
|
|||
|
|
@ -94,6 +94,27 @@ If [A]: edit the story file's `Manifest Version:` field to the current manifest
|
|||
If [B]: read the manifest carefully for new rules anyway, and note the version mismatch in the Phase 6 summary under "Deviations".
|
||||
If [C]: stop. Do not spawn any agent. Let the user review and re-run `/dev-story`.
|
||||
|
||||
### Dependency validation
|
||||
|
||||
After extracting the **Dependencies** list from the story file, validate each:
|
||||
|
||||
1. Glob `production/epics/**/*.md` to find each dependency story file.
|
||||
2. Read its `Status:` field.
|
||||
3. If any dependency has Status other than `Complete` or `Done`:
|
||||
- Use `AskUserQuestion`:
|
||||
- Prompt: "Story '[current story]' depends on '[dependency title]' which is currently [status], not Complete. How do you want to proceed?"
|
||||
- Options:
|
||||
- `[A] Proceed anyway — I accept the dependency risk`
|
||||
- `[B] Stop — I'll complete the dependency first`
|
||||
- `[C] The dependency is done but status wasn't updated — mark it Complete and continue`
|
||||
- If [B]: set story status to **BLOCKED** in session state and stop. Do not spawn any programmer agent.
|
||||
- If [C]: ask "May I update [dependency path] Status to Complete?" before continuing.
|
||||
- If [A]: note in Phase 6 summary under "Deviations": "Implemented with incomplete dependency: [dependency title] — [status]."
|
||||
|
||||
If a dependency file cannot be found: warn "Dependency story not found: [path]. Verify the path or create the story file."
|
||||
|
||||
---
|
||||
|
||||
### Engine reference
|
||||
Read `.claude/docs/technical-preferences.md`:
|
||||
- `Engine:` value — determines which programmer agents to use
|
||||
|
|
@ -292,3 +313,11 @@ Common blockers:
|
|||
- **Ask before large structural decisions** — if the story requires an
|
||||
architectural pattern not covered by the ADR, surface it before implementing:
|
||||
"The ADR doesn't specify how to handle [case]. My plan is [X]. Proceed?"
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/code-review [file1] [file2]` to review the implementation before closing the story
|
||||
- Run `/story-done [story-path]` to verify acceptance criteria and mark the story complete
|
||||
- After all sprint stories are done: run `/team-qa sprint` for the full QA cycle before advancing the project stage
|
||||
|
|
|
|||
|
|
@ -352,3 +352,12 @@ If context reaches or exceeds 70% at any point, append this notice:
|
|||
> **Context is approaching the limit (≥70%).** The systems index is saved to
|
||||
> `design/gdd/systems-index.md`. Open a fresh Claude Code session to continue
|
||||
> designing individual GDDs — run `/map-systems next` to pick up where you left off.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/design-system [first-system-in-order]` to author the first GDD (use design order from the index)
|
||||
- Run `/map-systems next` to always pick the highest-priority undesigned system automatically
|
||||
- Run `/design-review design/gdd/[system].md` in a fresh session after each GDD is authored
|
||||
- Run `/gate-check pre-production` when all MVP GDDs are authored and reviewed
|
||||
|
|
|
|||
|
|
@ -20,11 +20,44 @@ If no version is provided, ask the user before proceeding.
|
|||
## Phase 2: Gather Change Data
|
||||
|
||||
- Read the internal changelog at `production/releases/[version]/changelog.md` if it exists
|
||||
- Run `git log` between the previous release tag and current tag/HEAD
|
||||
- Also check `docs/CHANGELOG.md` for the relevant version entry
|
||||
- Run `git log` between the previous release tag and current tag/HEAD as a fallback
|
||||
- Read sprint retrospectives in `production/sprints/` for context
|
||||
- Read any balance change documents in `design/balance/`
|
||||
- Read bug fix records from QA if available
|
||||
|
||||
**If no changelog data is available** (neither `production/releases/[version]/changelog.md`
|
||||
nor a `docs/CHANGELOG.md` entry for this version exists, and git log is empty or unavailable):
|
||||
|
||||
> "No changelog data found for [version]. Run `/changelog [version]` first to generate the
|
||||
> internal changelog, then re-run `/patch-notes [version]`."
|
||||
|
||||
Verdict: **BLOCKED** — stop here without generating notes.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2b: Detect Tone Guide and Template
|
||||
|
||||
**Tone guide detection** — before drafting notes, check for writing style guidance:
|
||||
|
||||
1. Check `.claude/docs/technical-preferences.md` for any "tone", "voice", or "style"
|
||||
fields or sections.
|
||||
2. Check `docs/PATCH-NOTES-STYLE.md` if it exists.
|
||||
3. Check `design/community/tone-guide.md` if it exists.
|
||||
4. If any source contains tone/voice/style instructions, extract them and apply
|
||||
them to the language and framing of the generated notes.
|
||||
5. If no tone guidance is found anywhere, default to:
|
||||
player-friendly, non-technical language; enthusiastic but not hyperbolic;
|
||||
focus on what the player experiences, not what the developer changed.
|
||||
|
||||
**Template detection** — check whether a patch notes template exists:
|
||||
|
||||
1. Glob for `docs/patch-notes-template.md` and `.claude/docs/templates/patch-notes-template.md`.
|
||||
2. If found at either location, read it and use it as the output structure for Phase 4
|
||||
instead of the built-in style templates (Brief / Detailed / Full). Fill in the
|
||||
template's sections with the categorized data.
|
||||
3. If not found, use the built-in style templates as defined in Phase 4.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Categorize and Translate
|
||||
|
|
@ -137,9 +170,11 @@ Check the generated notes for:
|
|||
|
||||
Present the completed patch notes to the user along with: a count of changes by category, and any internal changes that were excluded (for review).
|
||||
|
||||
Ask: "May I write this to `production/releases/[version]/patch-notes.md`?"
|
||||
Ask: "May I write these patch notes to `docs/patch-notes/[version].md`?"
|
||||
|
||||
If yes, write the file, creating the directory if needed.
|
||||
If yes, write the file to `docs/patch-notes/[version].md`, creating the directory
|
||||
if needed. Also write to `production/releases/[version]/patch-notes.md` as the
|
||||
internal archive copy.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ name: propagate-design-change
|
|||
description: "When a GDD is revised, scans all ADRs and the traceability index to identify which architectural decisions are now potentially stale. Produces a change impact report and guides the user through resolution."
|
||||
argument-hint: "[path/to/changed-gdd.md]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Write, Bash
|
||||
allowed-tools: Read, Glob, Grep, Write, Bash, Task
|
||||
agent: technical-director
|
||||
---
|
||||
|
||||
|
|
@ -145,6 +145,29 @@ ADRs referencing this GDD: [M]
|
|||
|
||||
---
|
||||
|
||||
## 6b. Director Gate — Technical Impact Review
|
||||
|
||||
**Review mode check** — apply before spawning TD-CHANGE-IMPACT:
|
||||
- `solo` → skip. Note: "TD-CHANGE-IMPACT skipped — Solo mode." Proceed to Phase 7.
|
||||
- `lean` → skip. Note: "TD-CHANGE-IMPACT skipped — Lean mode." Proceed to Phase 7.
|
||||
- `full` → spawn as normal.
|
||||
|
||||
Spawn `technical-director` via Task using gate **TD-CHANGE-IMPACT** (`.claude/docs/director-gates.md`).
|
||||
|
||||
Pass: the full Design Change Impact Report from Phase 6 (change summary, all affected ADRs with their Still Valid / Needs Review / Likely Superseded classifications, and recommended actions).
|
||||
|
||||
The technical-director reviews whether:
|
||||
- The impact classifications are correct (no ADRs under-classified)
|
||||
- The recommended actions are architecturally sound
|
||||
- Any cascading effects on other ADRs or systems were missed
|
||||
|
||||
Apply the verdict:
|
||||
- **APPROVE** → proceed to Phase 7 resolution workflow
|
||||
- **CONCERNS** → surface the specific ADRs or recommendations flagged; use `AskUserQuestion` with options: `Revise the impact assessment` / `Accept with noted concerns` / `Discuss further`
|
||||
- **REJECT** → do not proceed to resolution; re-analyze the impact before continuing
|
||||
|
||||
---
|
||||
|
||||
## 7. Resolution Workflow
|
||||
|
||||
For each ADR marked "Needs Review" or "Likely Superseded", ask the user what to do:
|
||||
|
|
|
|||
|
|
@ -146,3 +146,12 @@ Verdict: **COMPLETE** — prototype finished. Recommendation is PROCEED, PIVOT,
|
|||
- If the recommendation is PROCEED, the production implementation must be written from scratch — prototype code is not refactored into production
|
||||
- Total prototype effort should be timeboxed to 1-3 days equivalent of work
|
||||
- If the prototype scope starts growing, stop and reassess whether the question can be simplified
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- **If PROCEED**: Run `/design-system [mechanic]` to author the production GDD, or `/architecture-decision` to record key technical decisions before implementation
|
||||
- **If PIVOT**: Run `/prototype [revised-concept]` to test the adjusted direction
|
||||
- **If KILL**: No further action required — the prototype report is the deliverable
|
||||
- Run `/playtest-report` to formally document any playtest sessions conducted during prototyping
|
||||
|
|
|
|||
|
|
@ -264,3 +264,11 @@ Redirect to the full pipeline if any of the following are true:
|
|||
|
||||
In those cases: "This change has grown beyond quick-spec scope. I recommend
|
||||
using `/design-system` to author a full GDD for this."
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/story-readiness [story-path]` to validate the story before implementation begins — reference this spec in the story's GDD Reference field
|
||||
- Run `/dev-story [story-path]` to implement once the story passes readiness checks
|
||||
- If the change is larger than expected, run `/design-system [system-name]` to author a full GDD instead
|
||||
|
|
|
|||
|
|
@ -14,6 +14,28 @@ Determine whether this is a sprint retrospective (`sprint-N`) or a milestone ret
|
|||
|
||||
---
|
||||
|
||||
## Phase 1b: Check for Existing Retrospective
|
||||
|
||||
Before loading any data, glob for an existing retrospective file:
|
||||
|
||||
- For sprint retrospectives: `production/retrospectives/retro-[sprint-slug]-*.md`
|
||||
(also check `production/sprints/sprint-[N]-retrospective.md` as an alternate location)
|
||||
- For milestone retrospectives: `production/retrospectives/retro-[milestone-name]-*.md`
|
||||
|
||||
If a matching file is found, present the user with:
|
||||
|
||||
```
|
||||
An existing retrospective was found: [filename]
|
||||
|
||||
[A] Update existing retrospective — load it and add/revise sections
|
||||
[B] Start fresh — generate a new retrospective, archiving the old one
|
||||
```
|
||||
|
||||
Wait for user selection before continuing. If updating, read the existing file and
|
||||
carry its content forward into the generation phase, revising sections with new data.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Load Sprint or Milestone Data
|
||||
|
||||
Read the sprint or milestone plan from the appropriate location:
|
||||
|
|
@ -21,6 +43,20 @@ Read the sprint or milestone plan from the appropriate location:
|
|||
- Sprint plans: `production/sprints/`
|
||||
- Milestone definitions: `production/milestones/`
|
||||
|
||||
**If the file does not exist or is empty**, output:
|
||||
|
||||
> "No sprint data found for [sprint/milestone]. Run `/sprint-status` to generate
|
||||
> sprint data first, or provide the sprint details manually."
|
||||
|
||||
Then use `AskUserQuestion` to present two options:
|
||||
|
||||
- **[A] Provide data manually** — ask the user to paste or describe the sprint
|
||||
tasks, dates, and outcomes; use that as the source of truth for the retrospective.
|
||||
- **[B] Stop** — abort the skill. Verdict: **BLOCKED** — no sprint data available.
|
||||
|
||||
If the user chooses [A], collect the data and continue to Phase 3 using what they provide.
|
||||
If the user chooses [B], stop here.
|
||||
|
||||
Extract: planned tasks, estimated effort, owners, and goals.
|
||||
|
||||
Read the git log for the period covered by the sprint or milestone to understand what was actually committed and when.
|
||||
|
|
|
|||
|
|
@ -78,6 +78,27 @@ Optionally (fast check only — do not do a deep scan): grep `src/` for a
|
|||
directory or file name that matches the story's system slug to check for
|
||||
implementation evidence. This is a hint only, not a definitive status.
|
||||
|
||||
### Stale Story Detection
|
||||
|
||||
After collecting status for all stories, check each IN PROGRESS story for staleness:
|
||||
|
||||
- For each story that has a referenced file, read the file and look for a
|
||||
`Last Updated:` field in the frontmatter or header (e.g., `Last Updated: 2026-04-01`
|
||||
or `updated: 2026-04-01`). Accept any reasonable date field name: `Last Updated`,
|
||||
`Updated`, `last-updated`, `updated_at`.
|
||||
- Calculate days since that date using today's date.
|
||||
- If the date is more than 2 days ago, flag the story as **STALE**.
|
||||
- If no date field is found in the story file, note "no timestamp — cannot check staleness."
|
||||
- If the story has no referenced file (inline task), note "inline task — cannot check staleness."
|
||||
|
||||
STALE stories are included in the output table and collected into an "Attention Needed"
|
||||
section (see Phase 5 output format).
|
||||
|
||||
**Stale story escalation**: If any IN PROGRESS story is flagged STALE, the burndown verdict
|
||||
is upgraded to at least **At Risk** — even if the completion percentage is within the normal
|
||||
On Track window. Record this escalation reason: "At Risk — [N] story(ies) with no progress in
|
||||
[N] days."
|
||||
|
||||
---
|
||||
|
||||
## 4. Burndown Assessment
|
||||
|
|
@ -118,6 +139,13 @@ Keep the total output to 30 lines or fewer. Use this format:
|
|||
| [title] | Must Have | BLOCKED | [owner] | [brief reason] |
|
||||
| [title] | Should Have| NOT STARTED | [owner] | |
|
||||
|
||||
### Attention Needed
|
||||
| Story / Task | Status | Last Updated | Days Stale | Note |
|
||||
|----------------------|-------------|----------------|------------|----------------|
|
||||
| [title] | IN PROGRESS | [date or N/A] | [N days] | [STALE / no timestamp — cannot check staleness / inline task — cannot check staleness] |
|
||||
|
||||
*(Omit this section entirely if no IN PROGRESS stories are stale or have timestamp concerns.)*
|
||||
|
||||
### Burndown: [On Track / At Risk / Behind]
|
||||
[1-2 sentences. If behind: which Must Haves are at risk. If on track: confirm
|
||||
and note any Should Haves the team could pull.]
|
||||
|
|
|
|||
|
|
@ -418,3 +418,11 @@ If no more stories are ready but Must Have stories are still In Progress (not Co
|
|||
anyway; document the risk explicitly if they do.
|
||||
- Use `AskUserQuestion` for the code review prompt and for batching manual
|
||||
criteria confirmations.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/story-readiness [next-story-path]` to validate the next story before starting implementation
|
||||
- If all Must Have stories are complete: run `/smoke-check sprint` → `/team-qa sprint` → `/gate-check`
|
||||
- If tech debt was logged: track it via `/tech-debt` to keep the register current
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ name: story-readiness
|
|||
description: "Validate that a story file is implementation-ready. Checks for embedded GDD requirements, ADR references, engine notes, clear acceptance criteria, and no open design questions. Produces READY / NEEDS WORK / BLOCKED verdict with specific gaps. Use when user says 'is this story ready', 'can I start on this story', 'is story X ready to implement'."
|
||||
argument-hint: "[story-file-path or 'all' or 'sprint']"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, AskUserQuestion
|
||||
allowed-tools: Read, Glob, Grep, AskUserQuestion, Task
|
||||
model: haiku
|
||||
---
|
||||
|
||||
|
|
@ -21,6 +21,18 @@ gap list for each non-ready story.
|
|||
|
||||
---
|
||||
|
||||
## Phase 0: Resolve Review Mode
|
||||
|
||||
Resolve the review mode once at startup (store for all gate spawns this run):
|
||||
|
||||
1. If skill was called with `--review [full|lean|solo]` → use that value
|
||||
2. Else read `production/review-mode.txt` → use that value
|
||||
3. Else → default to `lean`
|
||||
|
||||
See `.claude/docs/director-gates.md` for the full check pattern and mode definitions.
|
||||
|
||||
---
|
||||
|
||||
## 1. Parse Arguments
|
||||
|
||||
**Scope:** `$ARGUMENTS[0]` (blank = ask user via AskUserQuestion)
|
||||
|
|
@ -276,3 +288,61 @@ in conversation. Do not use Write or Edit tools — the user (or
|
|||
- If a story's scope has grown beyond its original sizing: "This story appears
|
||||
to have expanded in scope. Consider splitting it or escalating to the producer
|
||||
before implementation begins."
|
||||
|
||||
---
|
||||
|
||||
## 7. Next-Story Handoff
|
||||
|
||||
After completing a single-story readiness check (not `all` or `sprint` scope):
|
||||
|
||||
1. Read the current sprint file from `production/sprints/` (most recent).
|
||||
2. Find stories that are:
|
||||
- Status: READY or NOT STARTED
|
||||
- Not the story just checked
|
||||
- Not blocked by incomplete dependencies
|
||||
- In the Must Have or Should Have tier
|
||||
|
||||
If any are found, surface up to 3:
|
||||
|
||||
```
|
||||
### Other Ready Stories in This Sprint
|
||||
|
||||
1. [Story name] — [1-line description] — Est: [X hrs]
|
||||
2. [Story name] — [1-line description] — Est: [X hrs]
|
||||
|
||||
Run `/story-readiness [path]` to validate before starting.
|
||||
```
|
||||
|
||||
If no sprint file exists or no other ready stories are found, skip this section silently.
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: Director Gate — Story Readiness Review
|
||||
|
||||
Apply the review mode resolved in Phase 0 before spawning QL-STORY-READY:
|
||||
|
||||
- `solo` → skip. Note: "QL-STORY-READY skipped — Solo mode." Proceed to close.
|
||||
- `lean` → skip. Note: "QL-STORY-READY skipped — Lean mode." Proceed to close.
|
||||
- `full` → spawn as normal.
|
||||
|
||||
Spawn `qa-lead` via Task using gate **QL-STORY-READY** (`.claude/docs/director-gates.md`).
|
||||
|
||||
Pass the following context:
|
||||
- Story title
|
||||
- Acceptance criteria list (all items from the story's acceptance criteria section)
|
||||
- Dependency status (all dependencies listed and their current state: exist / DRAFT / missing)
|
||||
- Overall verdict (READY / NEEDS WORK / BLOCKED) from Phase 4
|
||||
|
||||
Handle the verdict per standard rules in `director-gates.md`:
|
||||
- **ADEQUATE** → story is cleared. Proceed to close.
|
||||
- **GAPS [list]** → surface the specific gaps to the user via `AskUserQuestion`:
|
||||
options: `Update story with suggested gaps` / `Accept and proceed anyway` / `Discuss further`.
|
||||
- **INADEQUATE** → surface the specific gaps; ask user whether to update the story or proceed anyway.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/dev-story [story-path]` to begin implementation once the story is READY
|
||||
- Run `/story-readiness sprint` to check all stories in the current sprint at once
|
||||
- Run `/create-stories [epic-slug]` if a story file is missing entirely
|
||||
|
|
|
|||
|
|
@ -126,6 +126,41 @@ Then ask: "Anything else I should read before we start, or shall we proceed?"
|
|||
|
||||
---
|
||||
|
||||
## 2b. Retrofit Mode Detection
|
||||
|
||||
Before creating a skeleton, check if the target output file already exists.
|
||||
|
||||
Glob `design/ux/[filename].md` (where `[filename]` is the resolved output path from Phase 1).
|
||||
|
||||
**If the file exists — retrofit mode:**
|
||||
- Read the file in full
|
||||
- For each expected section, check whether the body has real content (more than a `[To be designed]` placeholder) or is empty/placeholder
|
||||
- Present a section status summary to the user:
|
||||
|
||||
> "Found existing UX spec at `design/ux/[filename].md`. Here's what's already done:
|
||||
>
|
||||
> | Section | Status |
|
||||
> |---------|--------|
|
||||
> | Overview & Context | [Complete / Empty / Placeholder] |
|
||||
> | Player Journey Integration | ... |
|
||||
> | Screen Layout & Information Architecture | ... |
|
||||
> | Interaction Model | ... |
|
||||
> | Feedback & State Communication | ... |
|
||||
> | Accessibility | ... |
|
||||
> | Edge Cases & Error States | ... |
|
||||
> | Open Questions | ... |
|
||||
>
|
||||
> I'll work on the [N] incomplete sections only — existing content will not be overwritten."
|
||||
|
||||
- Skip Section 3 (skeleton creation) — the file already exists
|
||||
- In Phase 4 (Section Authoring), only work on sections with Status: Empty or Placeholder
|
||||
- Use `Edit` to fill placeholders in-place rather than creating a new skeleton
|
||||
|
||||
**If the file does not exist — fresh authoring mode:**
|
||||
Proceed to Phase 3 (Create File Skeleton) as normal.
|
||||
|
||||
---
|
||||
|
||||
## 3. Create File Skeleton
|
||||
|
||||
Once the user confirms, **immediately** create the output file with empty section
|
||||
|
|
@ -930,3 +965,11 @@ a requirement. Never silently expand the layout without flagging it.
|
|||
**Always** show where decisions come from (GDD requirements, player journey, user choices).
|
||||
|
||||
Verdict: **COMPLETE** — UX spec written and approved section by section.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Next Steps
|
||||
|
||||
- Run `/ux-review [filename]` to validate this spec before it enters the implementation pipeline
|
||||
- Run `/ux-design [next-screen]` to continue designing remaining screens or flows
|
||||
- Run `/gate-check pre-production` once all key screens have approved UX specs
|
||||
|
|
|
|||
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -13,7 +13,6 @@ Desktop.ini
|
|||
.claude/settings.local.json
|
||||
CLAUDE.local.md
|
||||
production/session-logs/
|
||||
production/session-state/*.md
|
||||
|
||||
# === Internal Planning (not for public) ===
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
version: 2
|
||||
last_updated: "2026-04-06"
|
||||
last_updated: ""
|
||||
skills:
|
||||
# Critical — gate skills that control phase transitions
|
||||
- name: gate-check
|
||||
|
|
@ -801,32 +801,24 @@ agents:
|
|||
# Tier 1 Directors (Opus)
|
||||
- name: creative-director
|
||||
spec: CCGS Skill Testing Framework/agents/directors/creative-director.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: director
|
||||
|
||||
- name: technical-director
|
||||
spec: CCGS Skill Testing Framework/agents/directors/technical-director.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: director
|
||||
|
||||
- name: producer
|
||||
spec: CCGS Skill Testing Framework/agents/directors/producer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: director
|
||||
|
||||
- name: art-director
|
||||
spec: CCGS Skill Testing Framework/agents/directors/art-director.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: director
|
||||
|
|
@ -834,56 +826,42 @@ agents:
|
|||
# Tier 2 Leads (Sonnet)
|
||||
- name: lead-programmer
|
||||
spec: CCGS Skill Testing Framework/agents/leads/lead-programmer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: lead
|
||||
|
||||
- name: qa-lead
|
||||
spec: CCGS Skill Testing Framework/agents/leads/qa-lead.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: lead
|
||||
|
||||
- name: narrative-director
|
||||
spec: CCGS Skill Testing Framework/agents/leads/narrative-director.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: lead
|
||||
|
||||
- name: audio-director
|
||||
spec: CCGS Skill Testing Framework/agents/leads/audio-director.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: lead
|
||||
|
||||
- name: game-designer
|
||||
spec: CCGS Skill Testing Framework/agents/leads/game-designer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: lead
|
||||
|
||||
- name: systems-designer
|
||||
spec: CCGS Skill Testing Framework/agents/leads/systems-designer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: lead
|
||||
|
||||
- name: level-designer
|
||||
spec: CCGS Skill Testing Framework/agents/leads/level-designer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: lead
|
||||
|
|
@ -891,96 +869,72 @@ agents:
|
|||
# Core Specialists (Sonnet)
|
||||
- name: gameplay-programmer
|
||||
spec: CCGS Skill Testing Framework/agents/specialists/gameplay-programmer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: specialist
|
||||
|
||||
- name: ai-programmer
|
||||
spec: CCGS Skill Testing Framework/agents/specialists/ai-programmer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: specialist
|
||||
|
||||
- name: technical-artist
|
||||
spec: CCGS Skill Testing Framework/agents/specialists/technical-artist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: specialist
|
||||
|
||||
- name: sound-designer
|
||||
spec: CCGS Skill Testing Framework/agents/specialists/sound-designer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: specialist
|
||||
|
||||
- name: engine-programmer
|
||||
spec: CCGS Skill Testing Framework/agents/specialists/engine-programmer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: specialist
|
||||
|
||||
- name: tools-programmer
|
||||
spec: CCGS Skill Testing Framework/agents/specialists/tools-programmer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: specialist
|
||||
|
||||
- name: network-programmer
|
||||
spec: CCGS Skill Testing Framework/agents/specialists/network-programmer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: specialist
|
||||
|
||||
- name: security-engineer
|
||||
spec: CCGS Skill Testing Framework/agents/qa/security-engineer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: qa
|
||||
|
||||
- name: accessibility-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/qa/accessibility-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: qa
|
||||
|
||||
- name: ux-designer
|
||||
spec: CCGS Skill Testing Framework/agents/specialists/ux-designer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: specialist
|
||||
|
||||
- name: ui-programmer
|
||||
spec: CCGS Skill Testing Framework/agents/specialists/ui-programmer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: specialist
|
||||
|
||||
- name: performance-analyst
|
||||
spec: CCGS Skill Testing Framework/agents/specialists/performance-analyst.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: specialist
|
||||
|
|
@ -988,40 +942,30 @@ agents:
|
|||
# Engine Specialists — Godot
|
||||
- name: godot-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/engine/godot/godot-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: engine
|
||||
|
||||
- name: godot-gdscript-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/engine/godot/godot-gdscript-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: engine
|
||||
|
||||
- name: godot-csharp-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/engine/godot/godot-csharp-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: engine
|
||||
|
||||
- name: godot-shader-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/engine/godot/godot-shader-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: engine
|
||||
|
||||
- name: godot-gdextension-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/engine/godot/godot-gdextension-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: engine
|
||||
|
|
@ -1029,40 +973,30 @@ agents:
|
|||
# Engine Specialists — Unity
|
||||
- name: unity-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/engine/unity/unity-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: engine
|
||||
|
||||
- name: unity-ui-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/engine/unity/unity-ui-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: engine
|
||||
|
||||
- name: unity-shader-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/engine/unity/unity-shader-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: engine
|
||||
|
||||
- name: unity-dots-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/engine/unity/unity-dots-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: engine
|
||||
|
||||
- name: unity-addressables-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/engine/unity/unity-addressables-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: engine
|
||||
|
|
@ -1070,40 +1004,30 @@ agents:
|
|||
# Engine Specialists — Unreal
|
||||
- name: unreal-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/engine/unreal/unreal-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: engine
|
||||
|
||||
- name: ue-blueprint-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/engine/unreal/ue-blueprint-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: engine
|
||||
|
||||
- name: ue-gas-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/engine/unreal/ue-gas-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: engine
|
||||
|
||||
- name: ue-umg-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/engine/unreal/ue-umg-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: engine
|
||||
|
||||
- name: ue-replication-specialist
|
||||
spec: CCGS Skill Testing Framework/agents/engine/unreal/ue-replication-specialist.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: engine
|
||||
|
|
@ -1111,56 +1035,42 @@ agents:
|
|||
# Operations
|
||||
- name: devops-engineer
|
||||
spec: CCGS Skill Testing Framework/agents/operations/devops-engineer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: operations
|
||||
|
||||
- name: release-manager
|
||||
spec: CCGS Skill Testing Framework/agents/operations/release-manager.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: operations
|
||||
|
||||
- name: live-ops-designer
|
||||
spec: CCGS Skill Testing Framework/agents/operations/live-ops-designer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: operations
|
||||
|
||||
- name: community-manager
|
||||
spec: CCGS Skill Testing Framework/agents/operations/community-manager.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: operations
|
||||
|
||||
- name: analytics-engineer
|
||||
spec: CCGS Skill Testing Framework/agents/operations/analytics-engineer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: operations
|
||||
|
||||
- name: economy-designer
|
||||
spec: CCGS Skill Testing Framework/agents/operations/economy-designer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: operations
|
||||
|
||||
- name: localization-lead
|
||||
spec: CCGS Skill Testing Framework/agents/operations/localization-lead.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: operations
|
||||
|
|
@ -1168,32 +1078,24 @@ agents:
|
|||
# QA & Creative
|
||||
- name: qa-tester
|
||||
spec: CCGS Skill Testing Framework/agents/qa/qa-tester.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: qa
|
||||
|
||||
- name: prototyper
|
||||
spec: CCGS Skill Testing Framework/agents/specialists/prototyper.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: specialist
|
||||
|
||||
- name: writer
|
||||
spec: CCGS Skill Testing Framework/agents/specialists/writer.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: specialist
|
||||
|
||||
- name: world-builder
|
||||
spec: CCGS Skill Testing Framework/agents/specialists/world-builder.md
|
||||
last_static: ""
|
||||
last_static_result: ""
|
||||
last_spec: ""
|
||||
last_spec_result: ""
|
||||
category: specialist
|
||||
|
|
|
|||
|
|
@ -32,33 +32,42 @@ auto-advancing stage and must respect the three review modes.
|
|||
|
||||
**Skills**: design-review, architecture-review, review-all-gdds
|
||||
|
||||
Review skills read documents and produce structured verdicts. They are strictly
|
||||
read-only and must never trigger director gates themselves.
|
||||
Review skills read documents and produce structured verdicts. They are primarily
|
||||
read-only and must not trigger director gates during the analysis phase.
|
||||
|
||||
| Metric | PASS criteria |
|
||||
|---|---|
|
||||
| **R1 — Read-only enforcement** | `allowed-tools` does not include `Write` or `Edit`; skill never offers to modify the reviewed document |
|
||||
| **R1 — Read-only enforcement** | Skill does not modify the reviewed document without explicit user approval; any write operations (review logs, index updates) are gated behind "May I write" |
|
||||
| **R2 — 8-section check** | Skill evaluates all 8 required GDD sections (or equivalent architectural sections) explicitly |
|
||||
| **R3 — Correct verdict vocabulary** | Verdict is exactly one of: APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED (design) or PASS / CONCERNS / FAIL (architecture) |
|
||||
| **R4 — No director gates** | Skill does not spawn any director gate regardless of review mode; it IS the review |
|
||||
| **R4 — No director gates during analysis** | Skill does not spawn director gates during its analysis phases; post-analysis director review (as in architecture-review) is acceptable when the skill's scope and stakes warrant it |
|
||||
| **R5 — Structured findings** | Output contains a per-section status table or checklist before the final verdict |
|
||||
|
||||
> **Exceptions:**
|
||||
> - `design-review`: Has `Write, Edit` in allowed-tools to support an optional "Revise now" path (all writes gated behind user approval) and to write review logs. R1 is satisfied because the reviewed document is never silently modified.
|
||||
> - `architecture-review`: Spawns TD-ARCHITECTURE and LP-FEASIBILITY gates after its analysis is complete. This is intentional — architecture review is high-stakes and benefits from director sign-off. R4 is satisfied because the gates run post-analysis, not during it.
|
||||
|
||||
---
|
||||
|
||||
### `authoring`
|
||||
|
||||
**Skills**: design-system, quick-design, architecture-decision, ux-design, ux-review, art-bible, create-architecture
|
||||
|
||||
Authoring skills create or update design documents section by section. They must
|
||||
collaborate before writing and handle both new and existing (retrofit) documents.
|
||||
Authoring skills create or update design documents collaboratively. Full GDD/UX
|
||||
authoring skills use a section-by-section cycle; lightweight authoring skills use
|
||||
a single-draft pattern appropriate to their smaller scope.
|
||||
|
||||
| Metric | PASS criteria |
|
||||
|---|---|
|
||||
| **A1 — Section-by-section cycle** | Skill authors one section at a time, presenting content for approval before proceeding to the next |
|
||||
| **A2 — May-I-write per section** | Skill asks "May I write this to [filepath]?" before each section write, not just once at the end |
|
||||
| **A3 — Retrofit mode** | Skill detects if the target file already exists and offers to update specific sections rather than overwriting the whole document |
|
||||
| **A1 — Section-by-section cycle** | Full authoring skills (design-system, ux-design, art-bible) author one section at a time, presenting content for approval before proceeding to the next. Lightweight skills (quick-design, architecture-decision, create-architecture) may draft the complete document then ask for approval — single-draft is acceptable for documents under ~4 hours of implementation scope. |
|
||||
| **A2 — May-I-write per section** | Full authoring skills ask "May I write this to [filepath]?" before each section write. Lightweight skills ask once for the complete document. |
|
||||
| **A3 — Retrofit mode** | Skill detects if the target file already exists and offers to update specific sections rather than overwriting the whole document. Lightweight skills (quick-design) that always create new files are exempt. |
|
||||
| **A4 — Director gate at correct tier** | If a director gate is defined for this skill (e.g., CD-GDD-ALIGN, TD-ADR), it runs at the correct mode threshold (full/lean) — NOT in solo |
|
||||
| **A5 — Skeleton-first** | Skill creates a file skeleton with all section headers before filling content, to preserve progress on session interruption |
|
||||
| **A5 — Skeleton-first** | Full authoring skills create a file skeleton with all section headers before filling content, to preserve progress on session interruption. Lightweight skills are exempt. |
|
||||
|
||||
> **Full authoring skills** (must pass all 5 metrics): `design-system`, `ux-design`, `art-bible`
|
||||
> **Lightweight authoring skills** (A1, A2, A5 use single-draft pattern; A3 exempt for new-file-only skills): `quick-design`, `architecture-decision`, `create-architecture`
|
||||
> **Review-mode skill** (evaluated against review metrics): `ux-review`
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -2,17 +2,16 @@
|
|||
|
||||
## Skill Summary
|
||||
|
||||
`/adopt` performs brownfield onboarding: it reads an existing non-Claude-Code
|
||||
project's source files, detects the engine and language, and generates a
|
||||
matching CLAUDE.md stub plus a populated `technical-preferences.md` to bring
|
||||
the project under the Claude Code Game Studios framework. It may also produce
|
||||
skeleton GDD files if enough design intent can be inferred from the code.
|
||||
`/adopt` audits an existing project's artifacts — GDDs, ADRs, stories, infrastructure
|
||||
files, and `technical-preferences.md` — for format compliance with the template's
|
||||
skill pipeline. It classifies every gap by severity (BLOCKING / HIGH / MEDIUM / LOW),
|
||||
composes a numbered, ordered migration plan, and writes it to `docs/adoption-plan-[date].md`
|
||||
after explicit user approval via `AskUserQuestion`.
|
||||
|
||||
Each generated file is gated behind a "May I write" ask. If an existing CLAUDE.md
|
||||
or `technical-preferences.md` is detected, the skill offers to merge rather than
|
||||
overwrite. The skill has no director gates. Verdicts: COMPLETE (full analysis done
|
||||
and files written), PARTIAL (analysis complete but some fields are ambiguous),
|
||||
or BLOCKED (cannot proceed — no source code found or user declined all writes).
|
||||
This skill is distinct from `/project-stage-detect` (which checks what exists).
|
||||
`/adopt` checks whether what exists will actually work with the template's skills.
|
||||
|
||||
No director gates apply. The skill does NOT invoke any director agents.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -22,149 +21,194 @@ Verified automatically by `/skill-test static` — no fixture needed.
|
|||
|
||||
- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
|
||||
- [ ] Has ≥2 phase headings
|
||||
- [ ] Contains verdict keywords: COMPLETE, PARTIAL, BLOCKED
|
||||
- [ ] Contains "May I write" collaborative protocol language before each file creation
|
||||
- [ ] Has a next-step handoff at the end (e.g., `/setup-engine` to refine or `/brainstorm`)
|
||||
- [ ] Contains severity tier keywords: BLOCKING, HIGH, MEDIUM, LOW
|
||||
- [ ] Contains "May I write" or `AskUserQuestion` language before writing the adoption plan
|
||||
- [ ] Has a next-step handoff at the end (e.g., offering to fix the highest-priority gap immediately)
|
||||
|
||||
---
|
||||
|
||||
## Director Gate Checks
|
||||
|
||||
None. `/adopt` is a brownfield onboarding utility. No director gates apply.
|
||||
None. `/adopt` is a brownfield audit utility. No director gates apply.
|
||||
|
||||
---
|
||||
|
||||
## Test Cases
|
||||
|
||||
### Case 1: Happy Path — Existing Unity project with C# code detected
|
||||
### Case 1: Happy Path — All GDDs compliant, no gaps, COMPLIANT
|
||||
|
||||
**Fixture:**
|
||||
- `src/` contains `.cs` files with Unity-specific namespaces (`using UnityEngine;`)
|
||||
- No CLAUDE.md overrides, no `technical-preferences.md` beyond placeholders
|
||||
- Project has a recognizable folder structure (Assets/, Scripts/)
|
||||
- `design/gdd/` contains 3 GDD files; each has all 8 required sections with content
|
||||
- `docs/architecture/adr-0001.md` exists with `## Status`, `## Engine Compatibility`,
|
||||
and all other required sections
|
||||
- `production/stage.txt` exists
|
||||
- `docs/architecture/tr-registry.yaml` and `docs/architecture/control-manifest.md` exist
|
||||
- Engine configured in `technical-preferences.md`
|
||||
|
||||
**Input:** `/adopt`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill scans `src/` and detects C# files with Unity API imports
|
||||
2. Skill identifies engine as Unity, language as C#
|
||||
3. Skill produces a draft `technical-preferences.md` with engine/language fields populated
|
||||
4. Skill produces a draft CLAUDE.md stub with detected project structure
|
||||
5. Skill asks "May I write `technical-preferences.md`?" and then "May I write CLAUDE.md?"
|
||||
6. Files are written after approval; verdict is COMPLETE
|
||||
1. Skill emits "Scanning project artifacts..." then reads all artifacts silently
|
||||
2. Reports detected phase, GDD count, ADR count, story count
|
||||
3. Phase 2 audit: all 3 GDDs have all 8 sections, Status field present and valid
|
||||
4. ADR audit: all required sections present
|
||||
5. Infrastructure audit: all critical files exist
|
||||
6. Phase 3: zero BLOCKING, zero HIGH, zero MEDIUM, zero LOW gaps
|
||||
7. Summary reports: "No blocking gaps — this project is template-compatible"
|
||||
8. Uses `AskUserQuestion` to ask about writing the plan; user selects write
|
||||
9. Adoption plan is written to `docs/adoption-plan-[date].md`
|
||||
10. Phase 7 offers next action: no blocking gaps, offers options for next steps
|
||||
|
||||
**Assertions:**
|
||||
- [ ] Engine detected as Unity (not Godot or Unreal)
|
||||
- [ ] Language detected as C#
|
||||
- [ ] Draft is shown to user before any "May I write" ask
|
||||
- [ ] "May I write" is asked separately for each file
|
||||
- [ ] Verdict is COMPLETE after both files are written
|
||||
- [ ] Skill reads silently before presenting any output
|
||||
- [ ] "Scanning project artifacts..." appears before the silent read phase
|
||||
- [ ] Gap counts show 0 BLOCKING, 0 HIGH, 0 MEDIUM (or only LOW)
|
||||
- [ ] `AskUserQuestion` is used before writing the adoption plan
|
||||
- [ ] Adoption plan file is written to `docs/adoption-plan-[date].md`
|
||||
- [ ] Phase 7 offers a specific next action (not just a list)
|
||||
|
||||
---
|
||||
|
||||
### Case 2: Mixed Languages — Partial analysis, asks user to clarify
|
||||
### Case 2: Non-Compliant Documents — GDDs missing sections, NEEDS MIGRATION
|
||||
|
||||
**Fixture:**
|
||||
- `src/` contains both `.gd` (GDScript) and `.cs` (C#) files
|
||||
- Engine cannot be definitively identified from the mix
|
||||
- `design/gdd/` contains 2 GDD files:
|
||||
- `combat.md` — missing `## Acceptance Criteria` and `## Formulas` sections
|
||||
- `movement.md` — all 8 sections present
|
||||
- One ADR (`adr-0001.md`) is missing `## Status` section
|
||||
- `docs/architecture/tr-registry.yaml` does not exist
|
||||
|
||||
**Input:** `/adopt`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill scans source and detects conflicting language signals
|
||||
2. Skill reports: "Mixed language signals detected (GDScript + C#) — cannot auto-identify engine"
|
||||
3. Skill presents the ambiguous findings and asks the user to confirm: Godot with C# or Unity?
|
||||
4. After user clarifies, skill resumes analysis with confirmed engine
|
||||
5. Produces a PARTIAL analysis noting fields that required manual clarification
|
||||
1. Skill scans all artifacts
|
||||
2. Phase 2 audit finds:
|
||||
- `combat.md`: 2 missing sections (Acceptance Criteria, Formulas)
|
||||
- `adr-0001.md`: missing `## Status` — BLOCKING impact
|
||||
- `tr-registry.yaml`: missing — HIGH impact
|
||||
3. Phase 3 classifies:
|
||||
- BLOCKING: `adr-0001.md` missing `## Status` (story-readiness silently passes)
|
||||
- HIGH: `tr-registry.yaml` missing; `combat.md` missing Acceptance Criteria (can't generate stories)
|
||||
- MEDIUM: `combat.md` missing Formulas
|
||||
4. Phase 4 builds ordered migration plan:
|
||||
- Step 1 (BLOCKING): Add `## Status` to `adr-0001.md` — command: `/architecture-decision retrofit`
|
||||
- Step 2 (HIGH): Run `/architecture-review` to bootstrap tr-registry.yaml
|
||||
- Step 3 (HIGH): Add Acceptance Criteria to `combat.md` — command: `/design-system retrofit`
|
||||
- Step 4 (MEDIUM): Add Formulas to `combat.md`
|
||||
5. Gap Preview shows BLOCKING items as bullets (actual file names), HIGH/MEDIUM as counts
|
||||
6. `AskUserQuestion` asks to write the plan; writes after approval
|
||||
7. Phase 7 offers to fix the highest-priority gap (ADR Status) immediately
|
||||
|
||||
**Assertions:**
|
||||
- [ ] Skill does NOT guess or silently pick an engine when signals conflict
|
||||
- [ ] Ambiguous findings are reported to the user explicitly
|
||||
- [ ] User choice is incorporated into the generated config
|
||||
- [ ] Verdict is PARTIAL (not COMPLETE) when manual clarification was required
|
||||
- [ ] BLOCKING gaps are listed as explicit file-name bullets in the Gap Preview
|
||||
- [ ] HIGH and MEDIUM shown as counts in Gap Preview
|
||||
- [ ] Migration plan items are in BLOCKING-first order
|
||||
- [ ] Each plan item includes the fix command or manual steps
|
||||
- [ ] `AskUserQuestion` is used before writing
|
||||
- [ ] Phase 7 offers to immediately retrofit the first BLOCKING item
|
||||
|
||||
---
|
||||
|
||||
### Case 3: CLAUDE.md Already Exists — Offers merge rather than overwrite
|
||||
### Case 3: Mixed State — Some docs compliant, some not, partial report
|
||||
|
||||
**Fixture:**
|
||||
- `CLAUDE.md` exists with custom content (project name, existing imports)
|
||||
- `technical-preferences.md` exists with some fields populated
|
||||
- 4 GDD files: 2 fully compliant, 2 with gaps (one missing Tuning Knobs, one missing Edge Cases)
|
||||
- ADRs: 3 files — 2 compliant, 1 missing `## ADR Dependencies`
|
||||
- Stories: 5 files — 3 have TR-ID references, 2 do not
|
||||
- Infrastructure: all critical files present; `technical-preferences.md` fully configured
|
||||
|
||||
**Input:** `/adopt`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill reads existing CLAUDE.md and detects it is already populated
|
||||
2. Skill reports: "CLAUDE.md already exists — offering to merge, not overwrite"
|
||||
3. Skill presents a diff of new fields vs. existing content
|
||||
4. Skill asks "May I merge new fields into CLAUDE.md?" (not "May I write")
|
||||
5. If user approves: only new or changed fields are added; existing content preserved
|
||||
1. Skill audits all artifact types
|
||||
2. Audit summary shows totals: "4 GDDs (2 fully compliant, 2 with gaps); 3 ADRs
|
||||
(2 fully compliant, 1 with gaps); 5 stories (3 with TR-IDs, 2 without)"
|
||||
3. Gap classification:
|
||||
- No BLOCKING gaps
|
||||
- HIGH: 1 ADR missing `## ADR Dependencies`
|
||||
- MEDIUM: 2 GDDs with missing sections; 2 stories missing TR-IDs
|
||||
- LOW: none
|
||||
4. Migration plan lists HIGH gap first, then MEDIUM gaps in order
|
||||
5. Note included: "Existing stories continue to work — do not regenerate stories
|
||||
that are in progress or done"
|
||||
6. `AskUserQuestion` to write plan; writes after approval
|
||||
|
||||
**Assertions:**
|
||||
- [ ] Skill does NOT overwrite existing CLAUDE.md without explicit user approval for a full replace
|
||||
- [ ] Merge option is offered when the file already exists
|
||||
- [ ] Diff is shown before the merge ask
|
||||
- [ ] Existing custom content is preserved in the merged output
|
||||
- [ ] Per-artifact compliance tallies are shown (N compliant, M with gaps)
|
||||
- [ ] Existing story compatibility note is included in the plan
|
||||
- [ ] No BLOCKING gaps results in no BLOCKING section in migration plan
|
||||
- [ ] HIGH gap precedes MEDIUM gaps in plan ordering
|
||||
- [ ] `AskUserQuestion` is used before writing
|
||||
|
||||
---
|
||||
|
||||
### Case 4: No Source Code Found — Stops with error
|
||||
### Case 4: No Artifacts Found — Fresh project, guidance to run /start
|
||||
|
||||
**Fixture:**
|
||||
- Repository has only documentation files (`.md`) and no source code in `src/`
|
||||
- No engine-identifiable files anywhere in the repo
|
||||
- Repository has no files in `design/gdd/`, `docs/architecture/`, `production/epics/`
|
||||
- `production/stage.txt` does not exist
|
||||
- `src/` directory does not exist or has fewer than 10 files
|
||||
- No game-concept.md, no systems-index.md
|
||||
|
||||
**Input:** `/adopt`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill scans `src/` and all likely code locations — finds nothing
|
||||
2. Skill outputs: "No source code detected — cannot perform brownfield analysis"
|
||||
3. Skill suggests alternatives: run `/start` for a new project, or point to a
|
||||
different directory if source is located elsewhere
|
||||
4. No files are written
|
||||
1. Phase 1 existence check finds no artifacts
|
||||
2. Skill infers "Fresh" — no brownfield work to migrate
|
||||
3. Uses `AskUserQuestion`:
|
||||
- "This looks like a fresh project — no existing artifacts found. `/adopt` is for
|
||||
projects with work to migrate. What would you like to do?"
|
||||
- Options: "Run `/start`", "My artifacts are in a non-standard location", "Cancel"
|
||||
4. Skill stops — does not proceed to audit regardless of user selection
|
||||
|
||||
**Assertions:**
|
||||
- [ ] Verdict is BLOCKED
|
||||
- [ ] Error message explicitly states no source code was found
|
||||
- [ ] Alternatives (`/start` or directory guidance) are provided
|
||||
- [ ] No "May I write" prompts appear (nothing to write)
|
||||
- [ ] `AskUserQuestion` is used (not a plain text message) when no artifacts are found
|
||||
- [ ] `/start` is presented as a named option
|
||||
- [ ] Skill stops after the question — no audit phases run
|
||||
- [ ] No adoption plan file is written
|
||||
|
||||
---
|
||||
|
||||
### Case 5: Director Gate Check — No gate; adopt is a utility onboarding skill
|
||||
### Case 5: Director Gate Check — No gate; adopt is a utility audit skill
|
||||
|
||||
**Fixture:**
|
||||
- Existing project with detectable source code
|
||||
- Project with a mix of compliant and non-compliant GDDs
|
||||
|
||||
**Input:** `/adopt`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill completes full brownfield analysis and produces config files
|
||||
1. Skill completes full audit and produces migration plan
|
||||
2. No director agents are spawned at any point
|
||||
3. No gate IDs (CD-*, TD-*, AD-*, PR-*) appear in output
|
||||
4. No `/gate-check` is invoked during the skill run
|
||||
|
||||
**Assertions:**
|
||||
- [ ] No director gate is invoked
|
||||
- [ ] No gate skip messages appear
|
||||
- [ ] Skill reaches COMPLETE or PARTIAL without any gate verdict
|
||||
- [ ] Skill reaches plan-writing or cancellation without any gate verdict
|
||||
|
||||
---
|
||||
|
||||
## Protocol Compliance
|
||||
|
||||
- [ ] Scans source before generating any config content
|
||||
- [ ] Shows draft config to user before asking to write
|
||||
- [ ] Asks "May I write" (or "May I merge") before each file operation
|
||||
- [ ] Detects existing files and offers merge path rather than silent overwrite
|
||||
- [ ] Ends with COMPLETE, PARTIAL, or BLOCKED verdict
|
||||
- [ ] Emits "Scanning project artifacts..." before silent read phase
|
||||
- [ ] Reads all artifacts silently before presenting any results
|
||||
- [ ] Shows Adoption Audit Summary and Gap Preview before asking to write
|
||||
- [ ] Uses `AskUserQuestion` before writing the adoption plan file
|
||||
- [ ] Adoption plan written to `docs/adoption-plan-[date].md` — not to any other path
|
||||
- [ ] Migration plan items ordered: BLOCKING first, HIGH second, MEDIUM third, LOW last
|
||||
- [ ] Phase 7 always offers a single specific next action (not a generic list)
|
||||
- [ ] Never regenerates existing artifacts — only fills gaps in what exists
|
||||
- [ ] Does not invoke director gates at any point
|
||||
|
||||
---
|
||||
|
||||
## Coverage Notes
|
||||
|
||||
- The Unreal Engine + Blueprint detection case (`.uasset`, `.umap` files)
|
||||
follows the same happy path pattern as Case 1 and is not separately tested.
|
||||
- Multi-directory source layouts (monorepo style) are not tested; the skill
|
||||
assumes a conventional single-project structure.
|
||||
- GDD skeleton generation from inferred design intent is noted as a capability
|
||||
but not fixture-tested here — it follows from the PARTIAL analysis pattern.
|
||||
- The `gdds`, `adrs`, `stories`, and `infra` argument modes narrow the audit scope;
|
||||
each follows the same pattern as the full audit but limited to that artifact type.
|
||||
Not separately fixture-tested here.
|
||||
- The systems-index.md parenthetical status value check (BLOCKING) is a special case
|
||||
that triggers an immediate fix offer before writing the plan; not separately tested.
|
||||
- The review-mode.txt prompt (Phase 6b) runs after plan writing if `production/review-mode.txt`
|
||||
does not exist; not separately tested here.
|
||||
|
|
|
|||
|
|
@ -2,15 +2,18 @@
|
|||
|
||||
## Skill Summary
|
||||
|
||||
`/smoke-check` runs the critical path smoke test checklist for a build. It reads
|
||||
the QA plan from `production/qa/` and checks each critical path item against the
|
||||
acceptance criteria defined in the current sprint's stories. Items that can be
|
||||
evaluated analytically are assessed; items that require runtime verification or
|
||||
visual inspection are flagged as NEEDS MANUAL CHECK.
|
||||
`/smoke-check` is the gate between implementation and QA hand-off. It detects the
|
||||
test environment, runs the automated test suite (via Bash), scans test coverage
|
||||
against sprint stories, and uses `AskUserQuestion` to batch-verify manual smoke
|
||||
checks with the developer. It writes a report to `production/qa/smoke-[date].md`
|
||||
after explicit user approval.
|
||||
|
||||
The skill produces no file writes — output is conversational. No director gates
|
||||
apply. Verdicts: PASS (all critical items verified), FAIL (at least one critical
|
||||
item fails), or NEEDS MANUAL CHECK (critical items exist that require human verification).
|
||||
Verdicts: PASS (tests pass, all smoke checks pass, no missing test evidence),
|
||||
PASS WITH WARNINGS (tests pass or NOT RUN, all critical checks pass, but advisory
|
||||
gaps exist such as missing test coverage), or FAIL (any automated test failure or
|
||||
any Batch 1/Batch 2 smoke check returns FAIL).
|
||||
|
||||
No director gates apply. The skill does NOT invoke any director agents.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -20,150 +23,171 @@ Verified automatically by `/skill-test static` — no fixture needed.
|
|||
|
||||
- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
|
||||
- [ ] Has ≥2 phase headings
|
||||
- [ ] Contains verdict keywords: PASS, FAIL, NEEDS MANUAL CHECK
|
||||
- [ ] Does NOT contain "May I write" language (skill is read-only)
|
||||
- [ ] Has a next-step handoff (e.g., `/bug-report` on FAIL, `/release-checklist` on PASS)
|
||||
- [ ] Contains verdict keywords: PASS, PASS WITH WARNINGS, FAIL
|
||||
- [ ] Contains "May I write" collaborative protocol language before writing the report
|
||||
- [ ] Has a next-step handoff (e.g., `/bug-report` on FAIL, QA hand-off guidance on PASS)
|
||||
|
||||
---
|
||||
|
||||
## Director Gate Checks
|
||||
|
||||
None. `/smoke-check` is a QA utility skill. No director gates apply.
|
||||
None. `/smoke-check` is a pre-QA utility skill. No director gates apply.
|
||||
|
||||
---
|
||||
|
||||
## Test Cases
|
||||
|
||||
### Case 1: Happy Path — All critical path items verifiable, PASS
|
||||
### Case 1: Happy Path — Automated tests pass, manual items confirmed, PASS
|
||||
|
||||
**Fixture:**
|
||||
- `production/qa/qa-plan-sprint-005.md` exists with 4 critical path items
|
||||
- All 4 items are logic or integration type (analytically assessable)
|
||||
- Corresponding story ACs are defined and met per sprint stories
|
||||
- `tests/` directory exists with a GDUnit4 runner script
|
||||
- Engine detected as Godot from `technical-preferences.md`
|
||||
- `production/qa/qa-plan-sprint-005.md` exists
|
||||
- Automated test runner reports 12 tests, 12 passing, 0 failing
|
||||
- Developer confirms all Batch 1 and Batch 2 smoke checks as PASS
|
||||
- All sprint stories have matching test files (no MISSING coverage)
|
||||
|
||||
**Input:** `/smoke-check`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill reads the QA plan and identifies 4 critical path items
|
||||
2. Skill evaluates each item against the story's acceptance criteria
|
||||
3. All 4 items pass
|
||||
4. Skill outputs a checklist: each item with a PASS marker
|
||||
5. Verdict is PASS with summary: "4/4 critical path items verified"
|
||||
1. Skill detects test directory and engine, notes QA plan found
|
||||
2. Runs `godot --headless --script tests/gdunit4_runner.gd` via Bash
|
||||
3. Parses output: 12/12 passing
|
||||
4. Scans test coverage — all stories COVERED or EXPECTED
|
||||
5. Uses `AskUserQuestion` for Batch 1 (core stability) and Batch 2 (sprint mechanics)
|
||||
6. Developer selects PASS for all items
|
||||
7. Report assembled: automated tests PASS, all smoke checks PASS, no MISSING coverage
|
||||
8. Asks "May I write this smoke check report to `production/qa/smoke-[date].md`?"
|
||||
9. Writes report after approval
|
||||
10. Delivers verdict: PASS
|
||||
|
||||
**Assertions:**
|
||||
- [ ] All 4 items appear in the checklist output
|
||||
- [ ] Each item is marked PASS
|
||||
- [ ] Automated test runner is invoked via Bash
|
||||
- [ ] `AskUserQuestion` is used for manual smoke check batches
|
||||
- [ ] "May I write" is asked before writing the report file
|
||||
- [ ] Report is written to `production/qa/smoke-[date].md`
|
||||
- [ ] Verdict is PASS
|
||||
- [ ] No files are written
|
||||
|
||||
---
|
||||
|
||||
### Case 2: Failure Path — One critical item fails, FAIL verdict
|
||||
### Case 2: Failure Path — Automated test fails, FAIL verdict
|
||||
|
||||
**Fixture:**
|
||||
- QA plan has 3 critical path items
|
||||
- Item 2 ("Player health does not go below 0") fails — story AC indicates
|
||||
clamping logic was not implemented
|
||||
- `tests/` directory exists, engine is Godot
|
||||
- Automated test runner reports 10 tests run: 8 passing, 2 failing
|
||||
- Failing tests: `test_health_clamp_at_zero`, `test_damage_calculation_negative`
|
||||
- QA plan exists
|
||||
|
||||
**Input:** `/smoke-check`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill evaluates all 3 items
|
||||
2. Item 1 and Item 3 pass; Item 2 fails
|
||||
3. Skill outputs checklist with specific failure: "Item 2 FAIL — Health clamping not verified"
|
||||
4. Verdict is FAIL
|
||||
5. Skill suggests running `/bug-report` for the failing item
|
||||
1. Skill runs automated tests via Bash
|
||||
2. Parses output — 2 failures detected
|
||||
3. Records failing test names
|
||||
4. Proceeds through manual smoke check batches
|
||||
5. Report shows automated tests as FAIL with failing test names listed
|
||||
6. Asks to write report; writes after approval
|
||||
7. Delivers FAIL verdict with message: "The smoke check failed. Do not hand off to
|
||||
QA until these failures are resolved." Lists failing tests and suggests fixing
|
||||
then re-running `/smoke-check`
|
||||
|
||||
**Assertions:**
|
||||
- [ ] Verdict is FAIL (not PARTIAL or NEEDS MANUAL CHECK)
|
||||
- [ ] Failing item is identified by name/description
|
||||
- [ ] Passing items are also shown (not hidden)
|
||||
- [ ] `/bug-report` is suggested for the failure
|
||||
- [ ] Failing test names are listed in the report
|
||||
- [ ] Verdict is FAIL
|
||||
- [ ] Post-verdict message directs developer to fix failures before QA hand-off
|
||||
- [ ] `/smoke-check` re-run is suggested after fixing
|
||||
|
||||
---
|
||||
|
||||
### Case 3: Visual Item Cannot Be Auto-Verified — NEEDS MANUAL CHECK
|
||||
### Case 3: Manual Confirmation — AskUserQuestion used, PASS WITH WARNINGS
|
||||
|
||||
**Fixture:**
|
||||
- QA plan has 3 items: 2 logic items (PASS) and 1 visual item
|
||||
("Explosion VFX triggers correctly on enemy death" — ADVISORY, visual type)
|
||||
- `tests/` directory exists, engine is Godot
|
||||
- Automated test runner reports all tests passing (8/8)
|
||||
- One Logic story has no matching test file (MISSING coverage)
|
||||
- Developer confirms all Batch 1 and Batch 2 smoke checks as PASS
|
||||
|
||||
**Input:** `/smoke-check`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill evaluates the 2 logic items — both pass
|
||||
2. Skill evaluates the visual item — cannot be verified analytically
|
||||
3. Visual item is marked NEEDS MANUAL CHECK with a note: "Visual quality requires
|
||||
human verification — see production/qa/evidence/"
|
||||
4. Verdict is NEEDS MANUAL CHECK (not PASS, because human action is required)
|
||||
5. Guidance on how to perform manual check is provided
|
||||
1. Automated tests PASS
|
||||
2. Coverage scan finds 1 MISSING entry for a Logic story
|
||||
3. `AskUserQuestion` is used for Batch 1 and Batch 2 — developer confirms all PASS
|
||||
4. Report shows: automated tests PASS, manual checks all PASS, 1 MISSING coverage entry
|
||||
5. Verdict is PASS WITH WARNINGS — build ready for QA, but MISSING entry must be
|
||||
resolved before `/story-done` closes the affected story
|
||||
6. Asks to write report; writes after approval
|
||||
|
||||
**Assertions:**
|
||||
- [ ] Verdict is NEEDS MANUAL CHECK (not PASS or FAIL)
|
||||
- [ ] Visual item is marked with explicit NEEDS MANUAL CHECK tag
|
||||
- [ ] Guidance for manual verification process is included
|
||||
- [ ] Logic items are still shown as PASS
|
||||
- [ ] `AskUserQuestion` is used for manual smoke check batches (not inline text prompts)
|
||||
- [ ] MISSING test coverage entry appears in the report
|
||||
- [ ] Verdict is PASS WITH WARNINGS (not PASS, not FAIL)
|
||||
- [ ] Advisory note explains MISSING entry must be resolved before `/story-done`
|
||||
- [ ] Report file is written to `production/qa/smoke-[date].md`
|
||||
|
||||
---
|
||||
|
||||
### Case 4: No Smoke Test Plan — Guidance to run /qa-plan
|
||||
### Case 4: No Test Directory — Skill stops with guidance
|
||||
|
||||
**Fixture:**
|
||||
- `production/qa/` directory exists but contains no QA plan file for the
|
||||
current sprint
|
||||
- Current sprint is sprint-006
|
||||
- `tests/` directory does not exist
|
||||
- Engine is configured as Godot
|
||||
|
||||
**Input:** `/smoke-check`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill looks for QA plan for the current sprint — not found
|
||||
2. Skill outputs: "No smoke test plan found for sprint-006"
|
||||
3. Skill suggests running `/qa-plan sprint-006` first
|
||||
4. No checklist is produced
|
||||
1. Phase 1 checks for `tests/` directory — not found
|
||||
2. Skill outputs: "No test directory found at `tests/`. Run `/test-setup` to
|
||||
scaffold the testing infrastructure, or create the directory manually if
|
||||
tests live elsewhere."
|
||||
3. Skill stops — no automated tests run, no manual smoke checks, no report written
|
||||
|
||||
**Assertions:**
|
||||
- [ ] Error message names the missing sprint's plan
|
||||
- [ ] `/qa-plan` is suggested with the correct sprint argument
|
||||
- [ ] Skill does not produce a checklist with no plan
|
||||
- [ ] Verdict is not PASS (error state, no checklist evaluated)
|
||||
- [ ] Error message references the missing `tests/` directory
|
||||
- [ ] `/test-setup` is suggested as the remediation step
|
||||
- [ ] Skill stops after this message (no further phases run)
|
||||
- [ ] No report file is written
|
||||
|
||||
---
|
||||
|
||||
### Case 5: Director Gate Check — No gate; smoke-check is a QA utility
|
||||
### Case 5: Director Gate Check — No gate; smoke-check is a QA pre-check utility
|
||||
|
||||
**Fixture:**
|
||||
- Valid QA plan with assessable items
|
||||
- Valid test setup, automated tests pass, manual smoke checks confirmed
|
||||
|
||||
**Input:** `/smoke-check`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill runs the smoke check and produces a verdict
|
||||
2. No director agents are spawned
|
||||
3. No gate IDs appear in output
|
||||
1. Skill runs all phases and produces a PASS or PASS WITH WARNINGS verdict
|
||||
2. No director agents are spawned at any point
|
||||
3. No gate IDs (CD-*, TD-*, AD-*, PR-*) appear in output
|
||||
4. No `/gate-check` is invoked
|
||||
|
||||
**Assertions:**
|
||||
- [ ] No director gate is invoked
|
||||
- [ ] No write tool is called
|
||||
- [ ] Verdict is PASS, FAIL, or NEEDS MANUAL CHECK — no gate verdict involved
|
||||
- [ ] No gate skip messages appear
|
||||
- [ ] Verdict is PASS, PASS WITH WARNINGS, or FAIL — no gate verdict involved
|
||||
|
||||
---
|
||||
|
||||
## Protocol Compliance
|
||||
|
||||
- [ ] Reads QA plan before evaluating any items
|
||||
- [ ] Evaluates each item explicitly (no silent skips)
|
||||
- [ ] Visual/feel items are always flagged NEEDS MANUAL CHECK (not auto-passed)
|
||||
- [ ] FAIL verdict triggers on first critical failure (not advisory)
|
||||
- [ ] Verdict is PASS, FAIL, or NEEDS MANUAL CHECK — no other verdicts
|
||||
- [ ] Uses `AskUserQuestion` for all manual smoke check batches (Batch 1, Batch 2, Batch 3)
|
||||
- [ ] Runs automated tests via Bash before asking any manual questions
|
||||
- [ ] Asks "May I write" before creating the report file — never writes without approval
|
||||
- [ ] Verdict vocabulary is strictly PASS / PASS WITH WARNINGS / FAIL — no other verdicts
|
||||
- [ ] FAIL is triggered by automated test failures or Batch 1/Batch 2 FAIL responses
|
||||
- [ ] PASS WITH WARNINGS is triggered when MISSING test coverage exists but no critical failures
|
||||
- [ ] NOT RUN (engine binary unavailable) is recorded as a warning, not a FAIL
|
||||
- [ ] Does not invoke director gates at any point
|
||||
|
||||
---
|
||||
|
||||
## Coverage Notes
|
||||
|
||||
- The case where the QA plan exists but has no critical path items (all items
|
||||
are ADVISORY) is not tested; PASS would be returned with a note that no
|
||||
critical items were checked.
|
||||
- The distinction between BLOCKING and ADVISORY gate levels from coding-standards.md
|
||||
is relied upon to determine which items can produce a FAIL.
|
||||
- Build-specific failures (runtime crashes) that occur during manual testing are
|
||||
outside the scope of this skill — use `/bug-report` for those.
|
||||
- The `quick` argument (skips Phase 3 coverage scan and Batch 3) is not separately
|
||||
fixture-tested; it follows the same pattern as Case 1 with a coverage-skip note in output.
|
||||
- The `--platform` argument adds platform-specific AskUserQuestion batches and a
|
||||
per-platform verdict table; not separately tested here.
|
||||
- The case where the engine binary is not on PATH (NOT RUN) follows the PASS WITH
|
||||
WARNINGS pattern and is covered by the protocol compliance assertions above.
|
||||
|
|
|
|||
Loading…
Reference in a new issue