stickman/.codex/skills/spec-pipeline/SKILL.md

name, description

name	description
spec-pipeline	Stickman Studio feature workflow: UI/UX and architecture specs, implementation, agent-run behavior verification, then user verification.

Execution Logic

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.
   • 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.
   • @uiux pitches 1–3 alternative interaction approaches (e.g., comparing floating tooltips vs. top-center banners, custom cursor reticles, or streamlined dialogs).
   • @uiux highlights the most intuitive option with [Recommended] and asks up to 3 clarification questions.
   • @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).
   • 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 2: Implementation & Agent Verification

   • @developer updates code and scenes using targeted diffs based on docs/specs/[feature-name].md.
   • @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.
   • When the outcome is visual or interactive, run the affected scene and inspect rendered output or a capture where the environment permits. Record what was observed; a headless launch or successful screenshot command alone does not prove visual correctness. If rendering or GUI access is unavailable, report that limit explicitly and leave a focused visual check for the user.
   • @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.

6. 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.

7. Phase 4: Documentation (Triggered manually by user)

   • Only call @writer after the user confirms: "Feature verified and working."