---
name: spec-pipeline
description: "Lean implementation loop: UI/UX (Ideas -> Spec) -> Architect (Clarify -> Spec) -> Developer -> 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.
   - `@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).

3. **Phase 1a: Architecture Proposal & Clarification**
   - `@architect` analyzes existing patterns and the Phase 0b UI/UX specification.
   - `@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 `specs/[feature-name].md` and logs decisions in `docs/tech_debt_and_optimizations.md`.
   - **STOP:** Wait for final user sign-off on the spec before invoking developer.

5. **Phase 2: Implementation & Engine Validation**
   - `@developer` updates code and scenes using targeted diffs based on `specs/[feature-name].md`.
   - `@developer` runs headless syntax verification.
   - If static check fails, `@developer` fixes the code immediately.

6. **Phase 3: User Hand-off (Stop)**
   - Present the changes to the user to test inside the Godot Editor.

7. **Phase 4: Documentation (Triggered manually by user)**
   - Only call `@writer` after the user confirms: "Feature verified and working."