mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-10-16 10:17:06 +00:00
Release 1.1.2 — the default path works end to end
Fix release for 1.1.1: the minimal path end to end, engine commands that run on Godot, Unity and Unreal, hook warnings you can see, and verdicts that say when they could not check. Details in CHANGELOG.md; upgrade steps in UPGRADING.md (v1.1.1 → v1.1.2). Fixes #67 Fixes #131 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WuJn2FdynEybfL5KC697nJ
This commit is contained in:
Donchitos
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
7ed2c3e9c4
commit
b21fa0f7f2
@@ -2,175 +2,215 @@
|
||||
|
||||
## Skill Summary
|
||||
|
||||
`/quick-design` produces a lightweight design spec for features too small to
|
||||
warrant a full 8-section GDD. The target scope is under 4 hours of design time
|
||||
for a single-system feature. Instead of the full 8-section GDD format, the
|
||||
quick-design spec uses a streamlined 3-section format: Overview, Rules, and
|
||||
Acceptance Criteria.
|
||||
`/quick-design [brief description of the change]` produces a lightweight Quick
|
||||
Design Spec for a change too small for a full GDD. It first classifies the
|
||||
change as **Tuning**, **Tweak**, **Addition** or **New Small System** and
|
||||
confirms the classification with an `AskUserQuestion` whose option `[F]`
|
||||
redirects to `/design-system`. A change that introduces a system with
|
||||
significant cross-system dependencies, needs more than about a week of work, or
|
||||
alters a system's core rules is redirected to `/design-system` instead (verdict
|
||||
`REDIRECTED`).
|
||||
|
||||
The skill has no director gates — adding gate overhead would defeat the purpose
|
||||
of a lightweight design tool. The skill asks "May I write" before writing the
|
||||
design note to `design/quick-notes/[name].md`. If the feature scope is too large
|
||||
for a quick-design, the skill redirects to `/design-system` instead.
|
||||
It then scans context (the relevant GDD in `design/gdd/`, the systems index if
|
||||
present, prior specs in `design/quick-specs/` — each named, whether it agrees or
|
||||
conflicts — and `assets/data/` for Tuning),
|
||||
drafts the spec in the format for its category, presents it in full with
|
||||
Approve / Revise / redirect options, and on approval asks "May I write this
|
||||
Quick Design Spec to `design/quick-specs/[kebab-case-title]-[YYYY-MM-DD].md`?".
|
||||
Any GDD edit the spec requires is asked for separately, showing old vs. new
|
||||
text. It ends with a handoff block and verdict `COMPLETE`.
|
||||
|
||||
The skill has no director gates and does not resolve `review_mode`; quick specs
|
||||
bypass `/design-review` and `/review-all-gdds` by design.
|
||||
|
||||
---
|
||||
|
||||
## Static Assertions (Structural)
|
||||
|
||||
Verified automatically by `/skill-test static` — no fixture needed.
|
||||
Checked against the SKILL.md by `/skill-test spec` — no fixture needed.
|
||||
|
||||
- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
|
||||
- [ ] Has ≥2 phase headings
|
||||
- [ ] Contains verdict keywords: CREATED, BLOCKED, REDIRECTED
|
||||
- [ ] Contains "May I write" collaborative protocol language (for quick-note file)
|
||||
- [ ] Contains verdict keywords: `COMPLETE`, `REDIRECTED`
|
||||
- [ ] Contains "May I write" collaborative protocol language (for the quick spec file, and separately for any GDD update)
|
||||
- [ ] Has a next-step handoff at the end
|
||||
- [ ] Explicitly notes: no director gates (lightweight skill by design)
|
||||
- [ ] Mentions scope check: redirects to `/design-system` if scope exceeds sub-4h threshold
|
||||
- [ ] States that quick specs bypass `/design-review` and `/review-all-gdds` by design, and lists when to redirect to the full pipeline
|
||||
- [ ] Documents the scope check that redirects oversized changes to `/design-system`
|
||||
|
||||
---
|
||||
|
||||
## Director Gate Checks
|
||||
|
||||
No director gates — this skill spawns no director gate agents. The lightweight
|
||||
nature of quick-design means director gate overhead is intentionally absent.
|
||||
Full GDD review is not needed for sub-4-hour single-system features.
|
||||
None. The skill resolves only `automation` and `workflow` (not `review_mode`),
|
||||
has no `Agent` tool in `allowed-tools`, and spawns no director or specialist
|
||||
agent. The review mode setting has no effect on it.
|
||||
|
||||
---
|
||||
|
||||
## Test Cases
|
||||
|
||||
### Case 1: Happy Path — Small UI change produces a 3-section spec
|
||||
### Case 1: Happy Path — Tweak to an existing system
|
||||
|
||||
**Fixture:**
|
||||
- No existing quick-note for the target feature
|
||||
- Feature is clearly scoped: a single UI element change with no cross-system impact
|
||||
- `design/gdd/movement.md` exists and describes dash invincibility in its Detailed Rules
|
||||
- `design/gdd/systems-index.md` exists
|
||||
- `design/quick-specs/dash-cooldown-tuning-[earlier-date].md` tuned the dash cooldown in movement and does not touch invincibility
|
||||
|
||||
**Input:** `/quick-design [feature-name]`
|
||||
**Input:** `/quick-design make dash invincible on frame 1`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill asks scoping questions: what system, what change, what is the acceptance signal
|
||||
2. Skill determines scope is within the sub-4h threshold
|
||||
3. Skill drafts a 3-section spec: Overview, Rules, Acceptance Criteria
|
||||
4. Draft is shown to user
|
||||
5. "May I write `design/quick-notes/[name].md`?" is asked
|
||||
6. File is written after approval
|
||||
1. The skill classifies the change as Tweak and asks "I've classified this as **Tweak** — [reason]. Is that correct?" with options `[A]`–`[F]`
|
||||
2. The context scan reads the relevant section of `design/gdd/movement.md`, the systems index and `design/quick-specs/`, and reports "Found GDD at `design/gdd/movement.md`. Relevant section: [section]. Prior quick specs for this system: `design/quick-specs/dash-cooldown-tuning-[earlier-date].md` — agrees."
|
||||
3. It drafts the Tweak/Addition format: Change Summary, Motivation, Design Delta (quoting the current GDD rule), New Rules / Values, Affected Systems, Acceptance Criteria, GDD Update Required?
|
||||
4. It presents the full draft, then asks with `[A] Approve — write it as shown` / `[B] Revise — I'll describe what to change` / `[C] This grew too large — redirect to /design-system instead`
|
||||
5. On `[A]`: "May I write this Quick Design Spec to `design/quick-specs/dash-invincibility-tweak-[YYYY-MM-DD].md`?" — on yes, creates `design/quick-specs/` if needed and writes the file
|
||||
6. Because the spec changes a rule in `movement.md`, it then asks separately "May I update `design/gdd/movement.md` — specifically the [section] section?", showing old vs. new text first
|
||||
7. It prints the handoff block (path, type, system, GDD update status) and "Verdict: **COMPLETE**"
|
||||
|
||||
**Assertions:**
|
||||
- [ ] Spec contains exactly 3 sections: Overview, Rules, Acceptance Criteria
|
||||
- [ ] Draft is shown to user before "May I write" ask
|
||||
- [ ] "May I write `design/quick-notes/[name].md`?" is asked before writing
|
||||
- [ ] File is written to the correct path: `design/quick-notes/[name].md`
|
||||
- [ ] Verdict is CREATED after successful write
|
||||
- [ ] The classification is confirmed via `AskUserQuestion` before any context scan or drafting
|
||||
- [ ] The prior dash-cooldown spec is named in the context report even though it does not conflict
|
||||
- [ ] The draft uses the Tweak/Addition format, and its Design Delta quotes the current GDD text
|
||||
- [ ] The full draft is shown before the write approval is asked
|
||||
- [ ] The file path is `design/quick-specs/[kebab-case-title]-[YYYY-MM-DD].md` with today's date
|
||||
- [ ] The GDD edit is asked for separately, after the quick spec is written, with old vs. new text shown
|
||||
- [ ] The run ends with the handoff block and verdict `COMPLETE`
|
||||
|
||||
---
|
||||
|
||||
### Case 2: Failure Path — Scope check fails; redirected to /design-system
|
||||
### Case 2: Failure Path — Scope too large; redirected to /design-system
|
||||
|
||||
**Fixture:**
|
||||
- Feature described spans multiple systems or would take more than 4 hours of design time
|
||||
(e.g., "redesign the entire combat system" or "new progression mechanic affecting all classes")
|
||||
- Scenario (a): the request is "redesign the entire combat system"
|
||||
- Scenario (b): a Tweak is drafted, and at the approval step the user picks `[C] This grew too large — redirect to /design-system instead`
|
||||
|
||||
**Input:** `/quick-design [large-feature]`
|
||||
**Input:** (a) `/quick-design redesign the entire combat system` (b) `/quick-design allow combo to cancel into roll`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill asks scoping questions
|
||||
2. Skill determines scope exceeds the sub-4h / single-system threshold
|
||||
3. Skill outputs: "This feature is too large for a quick-design. Use `/design-system [name]` for a full GDD."
|
||||
4. Skill does NOT write a quick-note file
|
||||
5. Verdict is REDIRECTED
|
||||
1. (a) The change alters a system's core rules, so the skill stops before drafting and redirects to `/design-system` — directly, or via option `[F]` of the classification prompt
|
||||
2. (b) The skill stops at the approval step
|
||||
3. In both scenarios: "Verdict: **REDIRECTED** — use `/design-system` for this change."
|
||||
4. No file is written under `design/quick-specs/`
|
||||
|
||||
**Assertions:**
|
||||
- [ ] Skill detects the scope excess and stops before drafting
|
||||
- [ ] Message explicitly names `/design-system` as the correct alternative
|
||||
- [ ] No quick-note file is written
|
||||
- [ ] Verdict is REDIRECTED (not CREATED or BLOCKED)
|
||||
- [ ] (a) The scope excess is detected and the skill stops before drafting
|
||||
- [ ] (a) The verdict line is printed even when the skill stops before the classification widget, not only via `[F]`
|
||||
- [ ] The message names `/design-system` as the alternative
|
||||
- [ ] No quick spec file is written
|
||||
- [ ] The verdict is `REDIRECTED`, not `COMPLETE`
|
||||
|
||||
---
|
||||
|
||||
### Case 3: Edge Case — File already exists; offered to update
|
||||
### Case 3: Edge Case — Tuning change outside the documented knob range
|
||||
|
||||
**Fixture:**
|
||||
- `design/quick-notes/[name].md` already exists from a previous session
|
||||
- `design/gdd/player-controller.md` has a Tuning Knobs entry `jump_height` with documented range 3–5
|
||||
- `assets/data/player.json` holds `jump_height: 5`
|
||||
- An earlier quick spec, `design/quick-specs/jump-height-tuning-[earlier-date].md`, previously set `jump_height` to 5
|
||||
|
||||
**Input:** `/quick-design [name]`
|
||||
**Input:** `/quick-design increase jump height from 5 to 6 units`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill detects existing quick-note file and reads its current content
|
||||
2. Skill asks: "[name].md already exists. Update it, or create a new version?"
|
||||
3. User selects update
|
||||
4. Skill shows the existing spec and asks which section to revise
|
||||
5. Updated spec is shown, "May I write?" asked, file updated after approval
|
||||
1. The skill classifies the change as Tuning and confirms it
|
||||
2. The context scan also checks `assets/data/` for the data file holding the value, and names the prior quick spec that touched this parameter, marked as conflicting — it set the value this change replaces
|
||||
3. The draft uses the Tuning format: a single Change table (Parameter, Old Value, New Value, Rationale), a Tuning Knob Mapping, and Acceptance Criteria
|
||||
4. The Tuning Knob Mapping states the new value is outside the documented range and explains why the range should be extended
|
||||
5. The acceptance criteria reference reading the value from `assets/data/[file]`
|
||||
|
||||
**Assertions:**
|
||||
- [ ] Skill detects and reads the existing file before offering to update
|
||||
- [ ] User is offered update or create-new options — not auto-overwritten
|
||||
- [ ] Only the revised section is updated (or the whole spec if user chooses full rewrite)
|
||||
- [ ] "May I write" is asked before overwriting the existing file
|
||||
- [ ] `assets/data/` is checked for the data file because the change is Tuning
|
||||
- [ ] The prior quick spec touching `jump_height` is reported, not silently contradicted
|
||||
- [ ] The draft uses the single-table Tuning format, not the Tweak/Addition sections
|
||||
- [ ] The Tuning Knob Mapping says the value is outside the documented range and explains the extension
|
||||
|
||||
---
|
||||
|
||||
### Case 4: Edge Case — No argument provided
|
||||
### Case 4: Edge Case — No argument and no systems index
|
||||
|
||||
**Fixture:**
|
||||
- `design/quick-notes/` directory may or may not exist
|
||||
- No `design/gdd/systems-index.md`
|
||||
- `design/quick-specs/` may or may not exist
|
||||
|
||||
**Input:** `/quick-design` (no argument)
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill detects no argument is provided
|
||||
2. Skill outputs a usage error: "No feature name specified. Usage: /quick-design [feature-name]"
|
||||
3. Skill provides an example: `/quick-design pause-menu-settings`
|
||||
4. No file is created
|
||||
1. The skill asks the user to describe the change with a plain-text prompt
|
||||
2. It does not show the classification widget, pick a change, or write anything until the user has described the change
|
||||
3. After the description, it classifies and confirms as usual
|
||||
4. The context scan notes "No systems index found — skipping dependency tier check." and continues
|
||||
|
||||
**Assertions:**
|
||||
- [ ] Skill outputs a usage error when no argument is given
|
||||
- [ ] A usage example is shown with the correct format
|
||||
- [ ] No quick-note file is written
|
||||
- [ ] Skill does NOT silently pick a feature name or default to any action
|
||||
- [ ] With no argument, the skill asks for a description in plain text rather than guessing a change
|
||||
- [ ] Classification happens only after the user describes the change
|
||||
- [ ] The missing systems index is noted with the documented line, and the run continues
|
||||
- [ ] No file is written before the approval step
|
||||
|
||||
---
|
||||
|
||||
### Case 5: Director Gate — No gate spawned; explicitly noted for sub-4h features
|
||||
### Case 5: No Director Gates — Review mode has no effect
|
||||
|
||||
**Fixture:**
|
||||
- Feature is within scope for quick-design
|
||||
- `production/session-state/review-mode.txt` exists with `full`
|
||||
- The change is within scope (an Addition: "add a parry window to the block mechanic")
|
||||
- `design/gdd/combat.md` exists (a GDD written voluntarily at this tier) and describes the block mechanic
|
||||
- `project.yaml` has `modes.review_mode: full` and `modes.workflow: minimal`
|
||||
|
||||
**Input:** `/quick-design [feature-name]`
|
||||
**Input:** `/quick-design add a parry window to the block mechanic`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Skill asks scoping questions and determines scope is within threshold
|
||||
2. Skill does NOT read `production/session-state/review-mode.txt`
|
||||
3. Skill does NOT spawn any director gate agent
|
||||
4. Spec is drafted, "May I write" asked, file written after approval
|
||||
5. Output explicitly notes: "No director gate review — quick-design is for sub-4h features"
|
||||
1. The skill runs its normal flow; `review_mode` is not among the keys it resolves, and nothing branches on it
|
||||
2. No agent of any kind is spawned (the skill has no `Agent` tool)
|
||||
3. The spec is drafted, approved and written after "May I write"
|
||||
4. The Pipeline Notes state that quick specs bypass `/design-review` and `/review-all-gdds` by design, and list when to redirect to `/design-system`
|
||||
5. At `workflow: minimal`, the handoff says to go straight to `/dev-story` rather than `/story-readiness`
|
||||
|
||||
**Assertions:**
|
||||
- [ ] No director gate agents are spawned (no CD-, TD-, PR-, AD- prefixed gates)
|
||||
- [ ] Skill does NOT read `production/session-state/review-mode.txt`
|
||||
- [ ] Output contains a note explaining why no gate review is needed
|
||||
- [ ] Review mode has no effect on this skill's behavior
|
||||
- [ ] Full GDD review path (`/design-system`) is mentioned as the alternative for larger features
|
||||
- [ ] No director gate or other agent is spawned
|
||||
- [ ] `modes.review_mode: full` does not change the skill's behavior
|
||||
- [ ] The output explains that quick specs bypass `/design-review` and `/review-all-gdds`, and names `/design-system` for larger changes
|
||||
- [ ] The handoff points to `/dev-story` directly at `workflow: minimal`
|
||||
|
||||
---
|
||||
|
||||
### Case 6: Edge Case — No GDD for the system (the default tier)
|
||||
|
||||
**Fixture:**
|
||||
- `project.yaml` has `modes.rigor: minimal`; `design/gdd/` holds no system GDD
|
||||
- `design/game-brief.md` describes the jump; `production/epics/movement/story-002-jump.md` implements it with a jump height of 5
|
||||
|
||||
**Input:** `/quick-design increase jump height from 5 to 6 units`
|
||||
|
||||
**Expected behavior:**
|
||||
1. Classified as Tuning and confirmed
|
||||
2. The context scan finds no GDD and reports "No GDD for movement — using the brief and `production/epics/movement/story-002-jump.md`"
|
||||
3. The spec is drafted with `design/game-brief.md` as its GDD Reference, shown, and written after "May I write"
|
||||
4. No GDD update is proposed (there is no GDD to update); the handoff goes to `/dev-story`
|
||||
|
||||
**Assertions:**
|
||||
- [ ] The skill does not stop, and does not redirect to `/design-system`, because there is no GDD
|
||||
- [ ] The report names the brief and the story it used in place of a GDD
|
||||
- [ ] The spec's GDD Reference is `design/game-brief.md`
|
||||
- [ ] Nothing is written before the "May I write" approval
|
||||
|
||||
---
|
||||
|
||||
## Protocol Compliance
|
||||
|
||||
- [ ] Scope check runs before drafting (redirects to `/design-system` if scope too large)
|
||||
- [ ] 3-section format used (Overview, Rules, Acceptance Criteria) — NOT the 8-section GDD format
|
||||
- [ ] Draft shown to user before "May I write" ask
|
||||
- [ ] "May I write `design/quick-notes/[name].md`?" asked before writing
|
||||
- [ ] No director gates — no review-mode.txt read
|
||||
- [ ] Ends with next-step handoff (e.g., proceed to implementation or `/dev-story`)
|
||||
- [ ] The change is classified and confirmed before drafting; oversized changes redirect to `/design-system`
|
||||
- [ ] The spec format matches the confirmed category (Tuning table; Tweak/Addition sections; New Small System trimmed GDD)
|
||||
- [ ] The full draft is shown before the "May I write" ask
|
||||
- [ ] "May I write this Quick Design Spec to `design/quick-specs/[kebab-case-title]-[YYYY-MM-DD].md`?" is asked before writing
|
||||
- [ ] GDD edits are asked for separately, with old vs. new text, and never made without approval
|
||||
- [ ] No director gates; review mode is not read
|
||||
- [ ] Ends with the handoff block and next steps (`/story-readiness`, or `/dev-story` at `minimal`)
|
||||
|
||||
---
|
||||
|
||||
## Coverage Notes
|
||||
|
||||
- The scope threshold heuristic (sub-4h, single-system) is a judgment call —
|
||||
the skill's internal check is the authoritative definition and is not
|
||||
independently tested by counting hours.
|
||||
- The `design/quick-notes/` directory is created automatically if it does not
|
||||
exist — this filesystem behavior is not independently tested here.
|
||||
- Integration with the story pipeline (can a quick-design generate a story
|
||||
directly?) is out of scope for this spec — quick-designs are standalone.
|
||||
- The New Small System format (Overview, Core Rules, Tuning Knobs, Acceptance
|
||||
Criteria, Systems Index) is not fixture-tested.
|
||||
- The `[B] Revise` loop at the approval step is not individually tested.
|
||||
- `guided` and `autonomous` automation modes are not tested.
|
||||
- The scope threshold is a judgment call; the skill's category definitions and
|
||||
redirect list are the authoritative definition and are not tested by
|
||||
counting hours.
|
||||
|
||||
Reference in New Issue
Block a user