64 lines
8.0 KiB
Markdown
64 lines
8.0 KiB
Markdown
---
|
||
name: spec-pipeline
|
||
description: "Stickman Studio feature workflow: UI/UX and architecture specs, implementation, agent-run behavior verification, then user verification."
|
||
---
|
||
|
||
## Execution Logic
|
||
|
||
### Feature branch and worktree setup
|
||
|
||
For every new feature or phase that will produce project files, use one dedicated feature branch and worktree from the first persistent artifact through implementation and verification. Read-only proposals can happen before the worktree is created; create or reuse it before the first UI spec, architecture spec, design brief, asset candidate, code change, or other feature file is written.
|
||
|
||
Follow the `Feature branches and worktrees` rules in `AGENTS.md`: inspect the current branch and worktree list, reuse a matching feature worktree when present, otherwise create `.worktrees/<feature-slug>` on `feature/<feature-slug>` from the integration branch. Include the phase number in the slug when known. Do not switch the user's shared checkout, transfer uncommitted changes without direction, or merge automatically.
|
||
|
||
Pass the absolute worktree path and branch name to every delegated agent, and tell each agent to use that path for all repository reads, writes, Godot runs, and visual checks. If a delegated agent cannot target the supplied worktree, stop its file-writing work and report the issue to the orchestrator.
|
||
|
||
1. **Phase 0a: UI/UX Proposal & Alternative Ideas (User-Facing Features Only)**
|
||
- `@uiux` analyzes the user's initial idea for cognitive friction, accessibility, and kid-friendliness.
|
||
- Before proposing, mocking, reviewing, or suggesting UI/UX changes, `@uiux` reads `docs/guides/editor_visual_style_guide.md` and checks the relevant implemented controls/specs. Treat the guide as the current visual baseline; distinguish implemented behavior from recommendations and explain intentional departures. This also applies to direct `@uiux` requests outside the pipeline.
|
||
- For an in-stage selected-object inspector, `@uiux` first reviews `docs/specs/stage_panel_ui_system.md` and the current shared controls under `scripts/shared/stage_ui/`; proposals should build on that system unless the interaction needs justify a specific exception.
|
||
- Follow the concept-count and visual-mockup protocol in `.codex/agents/uiux.toml`; it also applies when the user asks `@uiux` for ideas outside a formal pipeline run.
|
||
- `@uiux` **STOP:** Waits for user feedback/selection before writing the UI spec.
|
||
- _Bypass Rule:_ If the feature is strictly internal engine/backend logic (e.g., physics, serialization, scanning), skip directly to Phase 1a.
|
||
|
||
2. **Phase 0b: UI Spec Generation**
|
||
- User approves an option or provides feedback.
|
||
- `@uiux` outputs the UI/UX specification (control layouts, widget behaviors, visual feedback states, and cursor logic).
|
||
- Carry forward the style guide's applicable patterns and token ownership. If the approved direction departs from them, record the reason and the specific difference in the spec.
|
||
- For Stage inspector work, name which shared components and theme tokens the design uses or proposes to extend. Treat dialogs and other editor panels as separate workflows unless their interaction model fits the inspector kit.
|
||
|
||
3. **Phase 1a: Architecture Proposal & Clarification**
|
||
- `@architect` analyzes existing patterns and the Phase 0b UI/UX specification.
|
||
- For Stage inspector work, `@architect` inspects the shared panel implementation and theme as well as the design spec, and identifies reuse or justified extension before proposing new controls.
|
||
- `@architect` pitches 1–3 Godot best-practice implementation options and asks up to 3 clarification questions with `[Recommended]` choices.
|
||
- `@architect` stops without writing the spec file yet.
|
||
|
||
4. **Phase 1b: User Feedback & Spec Generation**
|
||
- User approves, modifies, or selects choices from `@architect`'s proposal.
|
||
- `@architect` writes the finalized specification to `docs/specs/[feature-name].md` and logs decisions in `docs/architecture/tech_debt_and_optimizations.md`.
|
||
- The spec states observable acceptance outcomes and the user path that produces each one. For interactions involving physics, timing, saving/loading, or multiple systems, name a small repeatable runtime scenario and what to measure; do not prescribe a test implementation unless it is needed to protect a specific behavior.
|
||
- **STOP:** Wait for final user sign-off on the spec before invoking developer.
|
||
|
||
5. **Phase 1c: Conditional Art Production & Approval**
|
||
- After spec sign-off, inspect the accepted specification for explicit new graphical or animation deliverables. Skip this phase when none are required.
|
||
- Invoke `$asset-creation`, which delegates to `@artist`, with the signed-off specification, supplied reference images, intended asset type, and integration constraints.
|
||
- `@artist` creates validated candidates under `content/review/artist/<request-slug>/`, including a preview and `review.md`; it does not modify gameplay/runtime architecture or promote the candidates yet.
|
||
- Present the review bundle and **STOP** for user approval or revision. Do not invoke developer while required artwork remains unapproved.
|
||
- After explicit approval, promote the selected assets to their production locations and pass their paths plus integration notes to developer.
|
||
|
||
6. **Phase 2: Implementation & Agent Verification**
|
||
- `@developer` updates code and scenes using targeted diffs based on `docs/specs/[feature-name].md`.
|
||
- When Phase 1c ran, `@developer` consumes the approved asset paths and Artist integration notes; it does not silently replace approved artwork.
|
||
- `@developer` runs Godot syntax/import checks and focused existing regression suites, then fixes failures.
|
||
- `@developer` adds focused automated coverage where it can meaningfully verify the feature's observable acceptance outcomes. For cross-system or runtime behavior, construct a small repeatable scene or fixture (in memory or as a saved scene), use the real production spawning/input/action paths where practical, advance frames or physics ticks, and assert the resulting state. A check that nodes, signals, layers, or helper calls exist is insufficient when the requirement concerns what actually happens during play.
|
||
- For visual or interactive acceptance criteria, establish the verification route before concluding Phase 2: run the affected scene in a render-capable GUI session, capture the states named in the spec, and inspect the rendered pixels. Record the scene/state, capture location, and what was observed. A successful launch, headless run, or screenshot command/file by itself does not prove visual correctness.
|
||
- For interactive acceptance criteria, exercise the real production input path through the scene and controls where practical. Advance frames or physics ticks as needed, then assert the resulting world/UI state and relevant cleanup or cancellation behavior. Signal/helper checks alone do not verify the user interaction.
|
||
- If the environment may not support rendering or input, try to establish whether a GUI, capture, or input-automation route is available; do not infer that it is unavailable from a headless run alone. If verification still cannot be performed, record what was attempted and the specific limitation, mark the affected acceptance outcomes unverified, and leave a focused, reproducible user check. Do not report the feature as fully agent-verified while required outcomes remain unverified.
|
||
- `@developer` reruns the relevant checks after fixes and reports commands, pass/fail results, the measured behavior, and any unverified acceptance outcome. Do not claim a feature is verified from syntax checks or debug prints alone.
|
||
|
||
7. **Phase 3: User Hand-off (Stop)**
|
||
- Present the implementation and agent verification evidence. Give the user only the remaining visual, usability, or environment-dependent checks to perform in the Godot Editor; clearly identify any acceptance outcome the agent could not verify.
|
||
|
||
8. **Phase 4: Documentation (Triggered manually by user)**
|
||
- Only call `@writer` after the user confirms: "Feature verified and working."
|