mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-10-16 10:17:06 +00:00
Release 1.1.0 — one config file, and a process weight you choose
`project.yaml` at the repo root is now the single source of truth for a project's configuration, replacing `production/stage.txt`, `production/review-mode.txt` and `.claude/docs/technical-preferences.md` (all three still read as a fallback; nothing is force-deleted). **`modes.rigor` — one question instead of six.** `minimal`, `standard` or `full` fronts six knobs: `modes.workflow`, `docs.density`, `qa.level`, `modes.story_granularity`, `modes.review_mode` and `team.size`. It defaults to `minimal`, which is a change from 1.0's behaviour: the heavier tier was measured costing several times more to reach working code without producing a better result, and returning nothing when a fresh developer inherited the project. Pin `modes.rigor: standard` to keep 1.0's process level. Also in this release: - `/settings` to view or change any setting, and `project.local.yaml` for per-developer preferences that should not be committed. - `system_overrides` to hold one system to a higher standard than the rest of the project, and `testing.strict` to set per test type whether missing evidence blocks a story or warns. - A story that changes anything the player sees is not closed until the game has been launched, observed, and a screenshot retained in `production/qa/evidence/`. A parse check is not a run. This holds at every rigor level, including `minimal`, where automated tests are waived but the look is not. - The code root is engine-specific and enforced as such: Godot `src/`, Unity `Assets/`, Unreal `Source/<Module>/`. Two of the three will not build a project laid out any other way. - Migration tooling for existing projects: `.claude/scripts/migrate-v1-config.sh` converts a 1.0 layout, non-destructively by default, with a report to review before `--finalize` deletes anything. - Ask-before-write holds regardless of personal automation settings. Upgrading from 1.0 or earlier: see UPGRADING.md. Full list of changes: CHANGELOG.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016xvzG3i7pWQg4LjyDwWMXd
This commit is contained in:
Donchitos
co-authored by
Claude Opus 5
Claude Opus 5
parent
984023ddac
commit
d05699707f
@@ -0,0 +1,120 @@
|
||||
> Section-authoring guidance, loaded by `/ux-design` for the ACTIVE MODE ONLY.
|
||||
> Never load the other two — one mode applies per invocation.
|
||||
|
||||
# Section Guidance — HUD Design Mode
|
||||
|
||||
|
||||
HUD design follows a different order from UX spec mode. Begin with philosophy;
|
||||
do not touch layout until the information architecture is complete.
|
||||
|
||||
#### Section A: HUD Philosophy
|
||||
|
||||
Ask the user to describe the game's relationship with on-screen information in
|
||||
1-2 sentences.
|
||||
|
||||
Offer framing examples to help:
|
||||
- "Nearly HUD-free — atmosphere requires unobstructed immersion (e.g., Hollow Knight, Firewatch)"
|
||||
- "Minimal but present — only critical information visible, everything else contextual (e.g., Dark Souls)"
|
||||
- "Information-dense — all decision-relevant data always visible (e.g., Diablo IV, StarCraft II)"
|
||||
- "Adaptive — HUD density responds to combat state, exploration mode, menus (e.g., God of War)"
|
||||
|
||||
This philosophy becomes the design constraint for every subsequent HUD decision.
|
||||
If a proposed element conflicts with the stated philosophy, surface that conflict.
|
||||
|
||||
---
|
||||
|
||||
#### Section B: Information Architecture
|
||||
|
||||
Complete this before any layout work. Do not skip it.
|
||||
|
||||
**Step 1 — Full information inventory**:
|
||||
Pull all information from GDD UI Requirements sections gathered in Phase 2.
|
||||
Present the full list: "These are all the things your game systems say they need
|
||||
to communicate to the player on screen."
|
||||
|
||||
**Step 2 — Categorization**:
|
||||
For each item, ask the user to categorize it:
|
||||
|
||||
| Category | Description |
|
||||
|----------|-------------|
|
||||
| **Must Show** | Always visible, player needs it for core decisions |
|
||||
| **Contextual** | Visible only when relevant (in combat, near interactable, etc.) |
|
||||
| **On Demand** | Player must actively request it (toggle, hold button) |
|
||||
| **Hidden** | Communicated through world/audio, never on-screen text |
|
||||
|
||||
Use `AskUserQuestion` to step through items in groups of 3-4, not all at once.
|
||||
This is the most consequential design decision in the HUD — do not rush it.
|
||||
|
||||
**Conflict check**: If the information philosophy (Section A) says "nearly HUD-free"
|
||||
but the Must Show list is growing long, surface the conflict explicitly:
|
||||
> "The current Must Show list has [N] items. That may conflict with the HUD-free
|
||||
> philosophy. Options: reduce the Must Show list, revise the philosophy, or define
|
||||
> a hybrid approach where HUD is absent in exploration and present in combat."
|
||||
|
||||
---
|
||||
|
||||
#### Section C: Layout Zones
|
||||
|
||||
Only after the information architecture is approved, design layout zones.
|
||||
|
||||
Base layout on:
|
||||
- Which items are Must Show (they drive the permanent zone decisions)
|
||||
- Where player attention naturally goes during gameplay (center-screen for action games,
|
||||
corners for strategy games)
|
||||
- Platform and aspect ratio targets
|
||||
|
||||
Offer 2-3 zone arrangements. Include rationale based on the HUD philosophy and the
|
||||
categorization from Section B.
|
||||
|
||||
---
|
||||
|
||||
#### Section D: HUD Elements
|
||||
|
||||
For each element in the layout, specify:
|
||||
- Element name and category (Must Show / Contextual / On Demand)
|
||||
- Content displayed
|
||||
- Visual form (bar, number, icon, counter, map)
|
||||
- Update behavior (real-time, event-driven, player-queried)
|
||||
- Contextual trigger (if not always visible)
|
||||
- Animation behavior (does it pulse when low? Fade in? Slam in?)
|
||||
|
||||
Work element by element. Reference the interaction pattern library if relevant patterns
|
||||
exist for status displays, resource bars, or cooldown indicators.
|
||||
|
||||
---
|
||||
|
||||
#### Sections E, F, G: Dynamic Behaviors, Platform Variants, Accessibility
|
||||
|
||||
These parallel the UX spec's States, Interaction, and Accessibility sections.
|
||||
The guidance you need is below — **do not load `sections-ux-spec.md`; one mode
|
||||
file applies per invocation.** For the HUD, apply it as follows.
|
||||
|
||||
**Dynamic Behaviors (states over time).** Beyond the happy path, capture what
|
||||
changes the HUD mid-gameplay and present it as a table for approval:
|
||||
|
||||
| State / Variant | Trigger | What Changes |
|
||||
|-----------------|---------|--------------|
|
||||
| Default | Normal play | — |
|
||||
| Low-resource | Health/ammo/etc. below threshold | [element pulses, recolors, …] |
|
||||
| Empty / no-data | Element has nothing to show | [hidden, or placeholder] |
|
||||
| [etc.] | [trigger] | [changes] |
|
||||
|
||||
Ask specifically: what causes the HUD to change density mid-gameplay
|
||||
(combat vs. exploration), and what fades, pulses, or slams in on each transition?
|
||||
|
||||
**Platform Variants.** Does mobile/console require different element sizes or
|
||||
positions? Note per-platform overrides — touch targets, safe-area insets, and
|
||||
whether any element moves or is dropped on a given platform.
|
||||
|
||||
**Accessibility.** Cross-reference `design/accessibility-requirements.md` if it
|
||||
exists, then walk this checklist for the HUD:
|
||||
- Gamepad/keyboard focus order for any interactive HUD element
|
||||
- Text contrast and minimum readable font sizes at gameplay distance
|
||||
- Color-independent communication (no state conveyed by color alone — a
|
||||
low-health cue must not be red-only)
|
||||
- Reduced-motion alternative for any pulsing/flashing HUD animation
|
||||
- Screen-reader considerations for non-text indicators
|
||||
|
||||
If no accessibility tier has been defined for this project, note the gap in the
|
||||
HUD design's Open Questions section (WCAG-AA is a reasonable baseline) and
|
||||
continue without stopping.
|
||||
@@ -0,0 +1,63 @@
|
||||
> Section-authoring guidance, loaded by `/ux-design` for the ACTIVE MODE ONLY.
|
||||
> Never load the other two — one mode applies per invocation.
|
||||
|
||||
# Section Guidance — Interaction Pattern Library Mode
|
||||
|
||||
|
||||
Pattern library authoring is additive and catalog-driven, not linear.
|
||||
|
||||
#### Phase 1: Catalog Existing Patterns
|
||||
|
||||
Glob `design/ux/*.md` (excluding `interaction-patterns.md`) and read the Component
|
||||
Inventory and Interaction Map sections of each spec. Extract every interaction
|
||||
pattern used.
|
||||
|
||||
Present the extracted list: "Based on existing UX specs, these patterns are already
|
||||
in use in the game:"
|
||||
- [Pattern name]: used in [screen], [screen]
|
||||
- [etc.]
|
||||
|
||||
Ask: "Are there patterns you know exist but aren't in existing specs yet? List any
|
||||
additional ones now."
|
||||
|
||||
---
|
||||
|
||||
#### Phase 2: Formalize Each Pattern
|
||||
|
||||
For each pattern (existing or new), document:
|
||||
|
||||
```markdown
|
||||
### [Pattern Name]
|
||||
|
||||
**Category**: Navigation / Input / Feedback / Data Display / Modal / Overlay / [other]
|
||||
**Used In**: [list of screens]
|
||||
|
||||
**Description**: [One paragraph explaining what this pattern is and when to use it]
|
||||
|
||||
**Specification**:
|
||||
- [Component behavior]
|
||||
- [Input mapping]
|
||||
- [Visual/audio feedback]
|
||||
- [Accessibility requirements for this pattern]
|
||||
|
||||
**When to Use**: [Conditions where this pattern is appropriate]
|
||||
**When NOT to Use**: [Conditions where another pattern is more appropriate]
|
||||
|
||||
**Reference**: [Screenshot path or ASCII example, if available]
|
||||
```
|
||||
|
||||
Work through patterns in groups. Use `AskUserQuestion`:
|
||||
- "How do you want to work through these patterns?"
|
||||
- Options: "Draft the first batch from existing specs (faster)", "Define them one by one (more control)", "Start with the most-used pattern first"
|
||||
|
||||
---
|
||||
|
||||
#### Phase 3: Identify Gaps
|
||||
|
||||
After cataloging known patterns, ask:
|
||||
- "Are there screens or interactions planned that would need patterns not yet
|
||||
in this library?"
|
||||
- "Are there any patterns in existing specs that feel inconsistent with each
|
||||
other and should be consolidated?"
|
||||
|
||||
Document gaps in the Gaps section for follow-up.
|
||||
@@ -0,0 +1,257 @@
|
||||
> Section-authoring guidance, loaded by `/ux-design` for the ACTIVE MODE ONLY.
|
||||
> Never load the other two — one mode applies per invocation.
|
||||
|
||||
# Section Guidance — UX Spec Mode
|
||||
|
||||
|
||||
#### Section A: Purpose & Player Need
|
||||
|
||||
This section is the foundation. Every other decision flows from it.
|
||||
|
||||
**Questions to ask**:
|
||||
- "What player goal does this screen serve? What is the player trying to DO here?"
|
||||
- "What would go wrong if this screen didn't exist or was hard to use?"
|
||||
- "Complete this sentence: 'The player arrives at this screen wanting to ___.' "
|
||||
|
||||
Cross-reference the player journey context gathered in Phase 2. The stated purpose
|
||||
must align with the journey phase and emotional state.
|
||||
|
||||
---
|
||||
|
||||
#### Section B: Player Context on Arrival
|
||||
|
||||
**Questions to ask**:
|
||||
- "When in the game does a player first encounter this screen?"
|
||||
- "What were they just doing immediately before reaching this screen?"
|
||||
- "What emotional state should the design assume? (calm, stressed, curious, time-pressured)"
|
||||
- "Do players arrive at this screen voluntarily, or are they sent here by the game?"
|
||||
|
||||
Offer to map this against the journey phases if the player journey doc exists.
|
||||
|
||||
---
|
||||
|
||||
#### Section B2: Navigation Position
|
||||
|
||||
Where does this screen sit in the game's navigation hierarchy? This is a one-paragraph orientation map — not a full flow diagram.
|
||||
|
||||
**Questions to ask**:
|
||||
- "Is this screen accessed from the main menu, from pause, from within gameplay, or from another screen?"
|
||||
- "Is it a top-level destination (always reachable) or a context-dependent one (only accessible in certain states)?"
|
||||
- "Can the player reach this screen from more than one place in the game?"
|
||||
|
||||
Present as: "This screen lives at: [root] → [parent] → [this screen]" plus any alternate entry paths.
|
||||
|
||||
---
|
||||
|
||||
#### Section B3: Entry & Exit Points
|
||||
|
||||
Map every way the player can arrive at and leave this screen.
|
||||
|
||||
**Questions to ask**:
|
||||
- "What are all the ways a player can reach this screen?" (List each trigger: button press, game event, redirect from another screen, etc.)
|
||||
- "What can the player do to exit? What happens when they do?" (Back button, confirm action, timeout, game event)
|
||||
- "Are there any exits that are one-way — where the player cannot return to this screen without starting over?"
|
||||
|
||||
Present as two tables:
|
||||
|
||||
| Entry Source | Trigger | Player carries this context |
|
||||
|---|---|---|
|
||||
| [screen/event] | [how] | [state/data they arrive with] |
|
||||
|
||||
| Exit Destination | Trigger | Notes |
|
||||
|---|---|---|
|
||||
| [screen/event] | [how] | [any irreversible state changes] |
|
||||
|
||||
---
|
||||
|
||||
#### Section C: Layout Specification
|
||||
|
||||
This is the largest and most interactive section. Work through it in sub-sections:
|
||||
|
||||
**Sub-section 1 — Information Hierarchy** (establish this before any layout):
|
||||
- Ask the user to list every piece of information this screen must communicate.
|
||||
- Then ask them to rank the items: "What is the single most important thing a player
|
||||
needs to see first? What is second? What can be discovered rather than immediately visible?"
|
||||
- Present the resulting hierarchy for approval before moving to zones.
|
||||
|
||||
**Sub-section 2 — Layout Zones**:
|
||||
- Based on the information hierarchy, propose rough screen zones (header, content
|
||||
area, action bar, sidebar, etc.).
|
||||
- Offer 2-3 zone arrangements with rationale for each. Reference platform and
|
||||
input context gathered from game concept.
|
||||
- Use `AskUserQuestion` to capture the choice:
|
||||
- "Which zone arrangement fits best?"
|
||||
- Options: [the 2-3 named arrangements you just presented] + "None — build a custom arrangement"
|
||||
|
||||
**Sub-section 3 — Component Inventory**:
|
||||
- For each zone, list the UI components it contains. For each component, note:
|
||||
- Component type (button, list, card, stat display, input field, etc.)
|
||||
- Content it displays
|
||||
- Whether it is interactive
|
||||
- If it uses an existing pattern from the library (reference by pattern name)
|
||||
- If it introduces a new pattern (flag for later addition to the library)
|
||||
|
||||
**Sub-section 4 — ASCII Wireframe**:
|
||||
- Offer to generate an ASCII wireframe based on the zone layout and component list.
|
||||
- Use `AskUserQuestion`: "Want an ASCII wireframe as part of this spec?"
|
||||
- Options: "Yes, include one", "No, I'll attach a separate file"
|
||||
- If yes, produce the wireframe in conversation first. Ask for feedback before
|
||||
writing it to file.
|
||||
|
||||
---
|
||||
|
||||
#### Section D: States & Variants
|
||||
|
||||
Guide the user to think beyond the happy path.
|
||||
|
||||
**Questions to ask** (work through these one at a time):
|
||||
- "What does this screen look like the very first time a player sees it, when there
|
||||
is no data yet? (empty state)"
|
||||
- "What happens when something goes wrong — an error, a failed action, a missing
|
||||
resource? (error state)"
|
||||
- "Is there ever a loading wait on this screen? If so, what does it show? (loading state)"
|
||||
- "Are there any player progression states that change what this screen shows? For
|
||||
example, locked content, premium content, or tutorial-mode overlays?"
|
||||
- "Does this screen behave differently on any supported platform? (platform variant)"
|
||||
|
||||
Present the collected states as a table for approval:
|
||||
|
||||
| State / Variant | Trigger | What Changes |
|
||||
|-----------------|---------|--------------|
|
||||
| Default | Normal load | — |
|
||||
| Empty | No data available | [content area description] |
|
||||
| [etc.] | [trigger] | [changes] |
|
||||
|
||||
---
|
||||
|
||||
#### Section E: Interaction Map
|
||||
|
||||
For each interactive component identified in the Layout Specification, define:
|
||||
- The action (tap, click, press, hold, scroll, drag)
|
||||
- The platform input(s) that trigger it (mouse click, gamepad A, keyboard Enter)
|
||||
- The immediate feedback (visual, audio, haptic)
|
||||
- The outcome (navigation target, state change, data write)
|
||||
|
||||
Use the input methods resolved in Phase 2h — do
|
||||
not ask the user again. State them upfront: "Mapping interactions for:
|
||||
[Input Methods resolved in Phase 2h]. Covering [Gamepad Support] gamepad support."
|
||||
|
||||
Work through components one at a time rather than asking for all at once.
|
||||
For navigation actions (going to another screen), verify the target matches
|
||||
an existing UX spec or note it as a spec dependency.
|
||||
|
||||
---
|
||||
|
||||
#### Section E2: Events Fired
|
||||
|
||||
For every player action in the Interaction Map, document the corresponding event the game or analytics system should fire — or explicitly note "no event" if none applies.
|
||||
|
||||
**Questions to ask**:
|
||||
- "For each action, should the game fire an analytics event, trigger a game-state change, or both?"
|
||||
- "Are there any actions that should NOT fire an event — and is that a deliberate choice?"
|
||||
|
||||
Present as a table alongside the Interaction Map:
|
||||
|
||||
| Player Action | Event Fired | Payload / Data |
|
||||
|---|---|---|
|
||||
| [action] | [EventName] or none | [data passed with event] |
|
||||
|
||||
Flag any action that modifies persistent game state (save data, progress, economy) — these need explicit attention from the architecture team.
|
||||
|
||||
---
|
||||
|
||||
#### Section E3: Transitions & Animations
|
||||
|
||||
Specify how the screen enters and exits, and how it responds to state changes.
|
||||
|
||||
**Questions to ask**:
|
||||
- "How does this screen appear? (fade in, slide from right, instant pop, scale from button)"
|
||||
- "How does it dismiss? (fade out, slide back, cut)"
|
||||
- "Are there any in-screen state transitions that need animation? (loading spinner, success state, error flash)"
|
||||
- "Is there any animation that could cause motion sickness — and does the game have a reduced-motion option?"
|
||||
|
||||
Minimum required:
|
||||
- Screen enter transition
|
||||
- Screen exit transition
|
||||
- At least one state-change animation if the screen has multiple states
|
||||
|
||||
---
|
||||
|
||||
#### Section F: Data Requirements
|
||||
|
||||
Cross-reference the GDD UI Requirements sections gathered in Phase 2.
|
||||
|
||||
For each piece of information the screen displays, ask:
|
||||
- "Where does this data come from? Which system owns it?"
|
||||
- "Does this screen need to write data back, or is it read-only?"
|
||||
- "Is any of this data time-sensitive or real-time? (health bars, cooldown timers)"
|
||||
|
||||
Flag any case where the UI would need to own or manage game state as an architectural
|
||||
concern. UX specs define what the UI needs; they do not dictate how the data is
|
||||
delivered. That is an architecture decision.
|
||||
|
||||
Present the data requirements as a table:
|
||||
|
||||
| Data | Source System | Read / Write | Notes |
|
||||
|------|--------------|--------------|-------|
|
||||
| [item] | [system] | Read | — |
|
||||
| [item] | [system] | Write | [concern if any] |
|
||||
|
||||
---
|
||||
|
||||
#### Section G: Accessibility
|
||||
|
||||
Cross-reference `design/accessibility-requirements.md` if it exists.
|
||||
|
||||
Walk through the ux-designer agent's standard checklist for this screen:
|
||||
- Keyboard-only navigation path through all interactive elements
|
||||
- Gamepad navigation order (if applicable)
|
||||
- Text contrast and minimum readable font sizes
|
||||
- Color-independent communication (no information conveyed by color alone)
|
||||
- Screen reader considerations for any non-text elements
|
||||
- Any motion or animation that needs a reduced-motion alternative
|
||||
|
||||
If no accessibility tier has been defined for this project, note the gap in the UX spec's Open Questions section:
|
||||
> "Accessibility tier not yet defined — consider WCAG-AA as a baseline. Run `/gate-check` to see whether this blocks any phase gates."
|
||||
Then continue to the next section without stopping.
|
||||
|
||||
---
|
||||
|
||||
#### Section H: Localization Considerations
|
||||
|
||||
Document constraints that affect how this screen behaves when text is translated.
|
||||
|
||||
**Questions to ask**:
|
||||
- "Which text elements on this screen are the longest? What is the maximum character count that fits the layout?"
|
||||
- "Are there any elements where text length is layout-critical — e.g., a button label that must stay on one line?"
|
||||
- "Are there any elements that display numbers, dates, or currencies that need locale-specific formatting?"
|
||||
|
||||
Note: aim to flag any element where a 40% text expansion (common in translations from English to German or French) would break the layout. Mark those as HIGH PRIORITY for the localization engineer.
|
||||
|
||||
---
|
||||
|
||||
#### Section I: Acceptance Criteria
|
||||
|
||||
Write at least 5 specific, testable criteria that a QA tester can verify without reading any other design document. These become the pass/fail conditions for `/story-done`.
|
||||
|
||||
**Format**: Use checkboxes. Each criterion must be verifiable by a human tester:
|
||||
|
||||
```
|
||||
- [ ] Screen opens within [X]ms from [trigger]
|
||||
- [ ] [Element] displays correctly at [minimum] and [maximum] values
|
||||
- [ ] [Navigation action] correctly routes to [destination screen]
|
||||
- [ ] Error state appears when [condition] and shows [specific message or icon]
|
||||
- [ ] Keyboard/gamepad navigation reaches all interactive elements in logical order
|
||||
- [ ] [Accessibility requirement] is met — e.g., "all interactive elements have focus indicators"
|
||||
```
|
||||
|
||||
**Minimum required**:
|
||||
- 1 performance criterion (load/open time)
|
||||
- 1 navigation criterion (at least one entry or exit path verified)
|
||||
- 1 error/empty state criterion
|
||||
- 1 accessibility criterion (per committed tier)
|
||||
- 1 criterion specific to this screen's core purpose
|
||||
|
||||
Use `AskUserQuestion` to confirm:
|
||||
- "Do these acceptance criteria cover what would make this screen 'done' for your QA process?"
|
||||
- Options: "Yes — these are solid", "Add one more criterion", "Remove or rephrase one"
|
||||
Reference in New Issue
Block a user