@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/SKILL.md

@@ -0,0 +1,401 @@
+---
+name: figma
+description: Figma-to-SwiftUI component implementation workflow. Takes a Figma URL and produces a production-ready SwiftUI component through 8 phases — data gathering, analysis, code generation, testing, Code Connect, and documentation.
+user-invocable: true
+argument-hint: <figma-url> | phase-<N> | status
+allowed-tools: Task, Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion
+status: wip-v5
+sourced-from: upstream/figma-to-swiftui
+---
+
+# /figma — Figma-to-SwiftUI Workflow Orchestrator
+
+## Parse Arguments
+
+`$ARGUMENTS` determines the mode:
+
+| Input | Mode | Action |
+|-------|------|--------|
+| `https://www.figma.com/design/...` | **Start** | Extract fileKey + nodeId, begin Phase 0 |
+| `phase-0` through `phase-6` | **Resume** | Read IMPLEMENTATION_HISTORY.md, dispatch that phase |
+| `phase-2a` through `phase-2d` | **Resume** | Dispatch specific Phase 2 sub-phase |
+| `phase-5a` through `phase-5d` | **Resume** | Dispatch specific Phase 5 sub-phase |
+| `phase-7` | **Resume** | Run Phase 7A (generate wiki markdown) |
+| `phase-7a` | **Resume** | Dispatch Phase 7A only (generate XHTML, no VPN needed) |
+| `phase-7a` | **Resume** | Dispatch Phase 7A only (generate wiki markdown) |
+| `status` | **Status** | Read and display IMPLEMENTATION_HISTORY.md |
+
+### URL Parsing
+
+Extract from Figma URL:
+```
+https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId}
+```
+Convert `-` to `:` in node-id (e.g., `9419-30700` → `9419:30700`).
+
+---
+
+## required PRE-READ
+
+Before dispatching any phase subagent, read:
+  .instructions/figma/figma-to-swiftui/reference/orchestrator-discipline.md
+
+These 6 rules govern orchestrator behavior. Violations have caused repeated failures. Follow them strictly.
+
+---
+
+## Phase Execution Order
+
+```
+0 (Init) → 1 (Gather) → 2A → 2B → 2C → 2D → 3 (Analysis) → 4 (Implementation) → 5A → 5B → 5C → 6 (Code Connect) → 7 (Wiki Markdown)
+```
+
+This skill dispatches Phase 2 and Phase 5 sub-phases directly — no orchestrator subagent.
+
+When `phase-7` is invoked:
+1. Dispatch `phase-7a` (generate two wiki pages: main + iOS, plus assets into wiki submodule).
+2. On COMPLETE, Phase 7 is done. No VPN required.
+3. Wiki changes are committed and pushed by the designated commit skill along with all other submodule changes.
+
+> **Confluence upload** is a separate standalone skill: `/figma-to-swift-ui-confluence-sync`.
+> It reads the wiki markdown, converts to XHTML, and uploads to Confluence (VPN required).
+
+---
+
+## Dispatch Table
+
+All instruction files are relative to this skill directory: `.instructions/figma/figma-to-swiftui/`
+
+| Phase | Instruction | Model | Max Turns | Tool Restrictions |
+|-------|-------------|-------|-----------|-------------------|
+| 0 | `phases/phase-0-init.md` | opus | 30 | No Edit |
+| 1 | `phases/phase-1-gathering.md` + `scripts/phase1-gather.py` | N/A (script) | N/A | Bash only |
+| 2A | `phases/phase-2a-testing-identifiers.md` | opus | 25 | No Edit |
+| 2B | `phases/phase-2b-localization.md` | sonnet | 25 | No Edit |
+| 2C | `phases/phase-2c-accessibility.md` | opus | 25 | No Edit |
+| 2D | `phases/phase-2d-analytics.md` | sonnet | 20 | No Edit, No Bash |
+| 3A | `phases/phase-3a-location.md` | sonnet | 20 | No Edit |
+| 3C | `phases/phase-3c-nested.md` | sonnet | 20 | No Edit |
+| 3H | `phases/phase-3h-variant-config.md` | opus | 25 | No Edit |
+| 3D | `phases/phase-3d-patterns.md` | opus | 30 | No Edit |
+| 4A | `phases/phase-4a-configuration.md` | opus | 30 | ALL allowed |
+| 4B | `phases/phase-4b-view.md` | opus | 40 | ALL allowed |
+| 4C | `phases/phase-4c-documentation.md` | sonnet | 20 | ALL allowed |
+| 4D | `phases/phase-4d-preview.md` | sonnet | 20 | ALL allowed |
+| 4E | `phases/phase-4e-modifiers.md` | sonnet | 20 | ALL allowed |
+| 5A | `phases/phase-5a-viewinspector.md` | sonnet | 40 | ALL allowed |
+| 5B | `phases/phase-5b-snapshot.md` | sonnet | 40 | ALL allowed |
+| 5C | `phases/phase-5c-unit.md` | sonnet | 30 | ALL allowed |
+| 6 | `phases/phase-6-code-connect.md` | opus | 30 | No Edit |
+| 7 | `phases/phase-7a-wiki-generate.md` | sonnet | 30 | No Edit |
+
+---
+
+## Reference Files
+
+Bundled in `.instructions/figma/figma-to-swiftui/reference/`. Include relevant paths in dispatch prompts so subagents can read them.
+
+| File | Used By Phases |
+|------|----------------|
+| `reference/tools.md` | 0, 1 |
+| `reference/code-connect.md` | 6 |
+| `reference/registry.md` | 0, 3 |
+| `reference/missing-tokens.md` | 3, 4 |
+| `reference/macros.md` | 4 |
+| `reference/figma-to-swiftui-effects.md` | 4 |
+| `reference/confluence-api.md` | standalone confluence skill |
+| `reference/confluence-xhtml.md` | standalone confluence skill |
+| `reference/wiki-to-confluence-mapping.md` | standalone confluence skill |
+| `reference/accessibility.md` | 2C |
+| `reference/localization-naming.md` | 2B |
+| `reference/testing-identifiers-naming.md` | 2A |
+| `reference/analytics-events.md` | 2D |
+| `reference/viewinspector.md` | 5A |
+| `reference/snapshot-testing.md` | 5D |
+
+---
+
+## Dispatch Procedure
+
+**CRITICAL: Do NOT read phase instruction files or reference docs in the main orchestrator context. Subagents read their own instructions by path. This prevents context bloat.**
+
+For each phase in order:
+
+### 1. Build the dispatch prompt (DO NOT read instruction files)
+
+```
+You are executing {Phase Name} of the Figma-to-SwiftUI workflow.
+
+## Context
+- Component: {componentName}
+- File Key: {fileKey}
+- Node ID: {nodeId}
+- Artifact Path: {artifactPath}
+- Component Location: {componentLocation}
+- GitHub Issue: {issueNumber} (omit if not available)
+- Wiki Path: {wikiPath} (Phase 7 only — `{repos.wiki.path}`)
+
+## Tool Restrictions
+{from dispatch table — e.g., "Do NOT use the Edit tool."}
+
+## Your Instructions
+Read and STRICTLY FOLLOW your phase instructions gate-by-gate from this file:
+  .instructions/figma/figma-to-swiftui/{instruction path from dispatch table}
+
+Execute every gate sequentially. Do not skip gates.
+
+Read the return protocol from:
+  .instructions/figma/figma-to-swiftui/reference/halt-return-protocol.md
+
+## Specs (if present)
+- {artifactPath}/pass0/specs.md
+Read and incorporate specs alongside phase instructions. Both are inputs you must follow — phase instructions define methodology and coding standards, specs define acceptance criteria and design intent. Neither overrides the other.
+
+## Reference Files (read during execution if needed)
+- .instructions/figma/figma-to-swiftui/{reference path}
+
+## Previous Phase Artifacts (read in this order)
+{use the Read-Order Table below — list file PATHS only, do not embed content}
+```
+
+### 2. Dispatch
+
+**Phase 1 (script):** Run directly via Bash — no subagent needed:
+
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/phase1-gather.py \
+  --file-key "{fileKey}" \
+  --node-id "{nodeId}" \
+  --artifact-path "{artifactPath}" \
+  --component-name "{componentName}"
+```
+
+Parse the JSON output from stdout. The script exits 0 on success, 1 on failure.
+The script tries remote MCP first, falls back to local MCP automatically.
+
+**If `status` = `COMPLETE_WITH_DEFERRED`:**
+Design context was deferred (too many sublayers). All other artifacts are present.
+Do NOT ask the user — dispatch a **Phase 1 subagent** for deferred resolution:
+
+```
+Agent(
+  subagent_type: "general-purpose",
+  model: opus,
+  max_turns: 25,
+  prompt: "You are executing Phase 1 Deferred Resolution...
+    Read instructions from: .instructions/figma/figma-to-swiftui/phases/phase-1-gathering.md (Section: Deferred Resolution)
+    Read halt-return from: .instructions/figma/figma-to-swiftui/reference/halt-return-protocol.md
+    Context: componentName={componentName}, fileKey={fileKey}, nodeId={nodeId}, artifactPath={artifactPath}
+    Previous artifacts: {artifactPath}/pass1/component_properties.json, {artifactPath}/pass1/design_context_deferred.json"
+)
+```
+
+The subagent handles smart selection (classifying axes, picking representatives) and calls `phase1-gather.py --fetch-deferred`. On COMPLETE → continue to Phase 2.
+
+**All other phases:** Dispatch via Agent tool:
+
+```
+Agent(
+  subagent_type: "general-purpose",
+  model: {from dispatch table},
+  max_turns: {from dispatch table},
+  prompt: {constructed prompt from step 1}
+)
+```
+
+### 3. Parse the return
+
+**STATUS: COMPLETE**
+→ Record gates and artifacts → Proceed to next phase
+
+**STATUS: HALT**
+→ Show user: GATE, REASON, USER_ACTION_REQUIRED via AskUserQuestion
+→ Options: "Fix and retry", "Skip this phase", "Abort workflow"
+→ Retry: re-dispatch same phase
+→ Skip: proceed, record skip in history
+→ Abort: stop workflow
+
+**STATUS: NEEDS_INPUT**
+→ Show user: QUESTION, OPTIONS, SUGGESTED via AskUserQuestion
+→ Re-dispatch same phase with user decision prepended:
+  ```
+  USER_DECISION:
+    GATE: {gate-id}
+    ANSWER: {user's choice}
+  ```
+
+### 4. Update history
+
+After each phase completes, update IMPLEMENTATION_HISTORY.md with phase status, gates, artifacts, timestamp.
+
+---
+
+## Phase 2 Routing (inline — do NOT read phase-2-orchestrator.md)
+
+**Do NOT read `phase-2-orchestrator.md`. All routing logic is here. Subagents read their own docs.**
+
+1. **PRE-CHECK**: Read `IMPLEMENTATION_HISTORY.md` (already in context). Verify `pass1/_index.md` exists.
+2. **NORMALIZE**: Check `pass1/design_context_response.json` — if `sublayers: true` and no `response` field, concatenate `responses` values into `response` field and write back.
+3. **REGISTRY_LOOKUP**: `cd {repos.common.path} && .build/debug/FigmaRegistryUtility utility-lookup --node-id '{nodeId}'` — pass result as `registryData` context to subagents.
+4. **Wave 1 (parallel)**: Dispatch 2A + 2B + 2C as subagents (each reads its own instruction doc by path).
+5. **Wave 2**: Dispatch 2D as subagent (depends on 2A output).
+6. **FINALIZE (script)**:
+   ```bash
+   python3 .instructions/figma/figma-to-swiftui/scripts/phase2-finalize.py \
+       --artifact-path '{artifactPath}' --node-id '{nodeId}' \
+       --file-key '{fileKey}' --component-name '{componentName}'
+   ```
+   Parse stdout JSON: `{"status":"ok","testing":N,"localization":N,"accessibility":N,"analytics":N,"registry":bool}`
+7. **UPDATE HISTORY**: Append Phase 2 summary using script output counts.
+
+---
+
+## Phase 3 Routing (inline — do NOT read phase-3-orchestrator.md)
+
+**Do NOT read `phase-3-orchestrator.md`. Subagents read their own docs. Scripts handle deterministic phases.**
+
+1. **PRE-CHECK**: Verify `pass2/_index.md` exists.
+2. **NORMALIZE**: Same sublayer check as Phase 2 (skip if already normalized).
+3. **Wave 1 (parallel)**: Launch ALL simultaneously:
+   - **Scripts**: `python3 .instructions/figma/figma-to-swiftui/scripts/phase3-scripts.py wave1 --artifact-path '{artifactPath}'` (runs 3B+3E+3F, ~5s)
+   - **Subagents**: 3A (`phase-3a-location.md`, sonnet, 20 turns), 3C (`phase-3c-nested.md`, sonnet, 20 turns), 3H (`phase-3h-variant-config.md`, opus, 25 turns)
+4. **MISSING TOKEN RESOLUTION**: After Wave 1, check `pass3/02_token_mapping.md` for missing tokens (lines with "⚠️ not found"). If any exist, dispatch a subagent:
+   - **Subagent** (`general-purpose`, opus, 25 turns) — reads `reference/missing-tokens.md` for procedure, resolves each missing token by:
+     - **Typography**: Adding alias entries to `typography-registry.json` (match font size + weight to existing Swift tokens)
+     - **Colors**: Adding to `Shared/UIAssets/Colors/*.json` (source), running `swift package plugin --allow-writing-to-package-directory generate-ui-assets`, adding to `ui-token-index.json`
+     - **Variables**: Using `FigmaRegistryUtility ui-token-lookup` / `ui-token-index` to verify
+   - Pass artifact path and token mapping path as context. Subagent updates token mapping after resolution.
+   - If 0 missing tokens, skip this step entirely.
+5. **Wave 2 (parallel)**: Launch simultaneously:
+   - **Subagent**: 3D (`phase-3d-patterns.md`, opus, 30 turns) — reads 3H output (`pass3/04c_variant_config_analysis.json`)
+6. **Wave 3**: `python3 .instructions/figma/figma-to-swiftui/scripts/phase3-scripts.py 3g --artifact-path '{artifactPath}'` (depends on 3D JSON output)
+7. **COLLECT**: Verify 12 artifacts exist in `pass3/` (10 original + 2 from 3H).
+8. **SPEC (script)**: `python3 .instructions/figma/figma-to-swiftui/scripts/phase3-scripts.py spec --artifact-path '{artifactPath}'`
+9. **WRITE INDEX**: Write `pass3/_index.md` (list the 12 files + spec).
+10. **UPDATE HISTORY**: Append Phase 3 summary.
+
+---
+
+## Phase 4 Routing (inline — do NOT read phase-4-orchestrator.md)
+
+**Do NOT read `phase-4-orchestrator.md`. Subagents read their own docs. Orchestrator stays lean.**
+
+1. **PRE-CHECK**: Verify `pass3/_index.md` exists.
+2. **LOAD_SPEC**: Read `pass3/07_implementation_spec.md` and `pass3/05_complexity.md` — extract `componentLocation`, `complexity` (SIMPLE/COMPLEX).
+3. **PREPARE_DIRECTORY**: `mkdir -p {componentLocation}`. Get `gitUser` via `git config user.name`. Get `date` in DD.MM.YYYY format.
+4. **Wave 1 (parallel)**: Dispatch subagents:
+   - **4A** (`phase-4a-configuration.md`, opus, 30 turns) — **COMPLEX only** (skip if SIMPLE). Writes `{ComponentName}Configuration.swift`.
+   - **4B** (`phase-4b-view.md`, opus, 40 turns) — **ALWAYS**. Writes `{ComponentName}.swift`.
+   - **4C** (`phase-4c-documentation.md`, sonnet, 20 turns) — **ALWAYS**. Writes `FIGMA.md`.
+   - Pass to each: componentName, componentLocation, artifactPath, nodeId, fileKey, complexity, gitUser, date, issueNumber (from IMPLEMENTATION_HISTORY.md `GitHub Issue` field — extract the number after `#`).
+5. **Wave 2 (parallel)**: Dispatch subagents that depend on 4A+4B:
+   - **4D** (`phase-4d-preview.md`, sonnet, 20 turns) — appends Preview to `{ComponentName}.swift`.
+   - **4E** (`phase-4e-modifiers.md`, sonnet, 20 turns) — **COMPLEX only** (skip if SIMPLE). Writes `{ComponentName}+Modifiers.swift`.
+6. **COLLECT**: Verify `{ComponentName}.swift`, `{ComponentName}Configuration.swift` (if COMPLEX), `{ComponentName}+Modifiers.swift` (if COMPLEX), `FIGMA.md` exist.
+7. **VALIDATE**: `bash .instructions/figma/figma-to-swiftui/scripts/validate-phase4.sh "{componentLocation}" "{ComponentName}" "{artifactPath}/pass3/00_property_coverage.json"` — fix violations if any.
+8. **BUILD**: `xcodebuild build -project "$(git rev-parse --show-toplevel)/{build.xcodeproj}" -scheme {build.scheme} -destination 'generic/platform=iOS' CODE_SIGNING_ALLOWED=NO -quiet` — fix compilation errors if any.
+9. **UPDATE HISTORY**: Append Phase 4 summary.
+
+---
+
+## Phase 5 Routing (inline — do NOT read phase-5-orchestrator.md)
+
+**Do NOT read `phase-5-orchestrator.md`. Subagents read their own docs.**
+
+1. **PRE-CHECK**: Verify Phase 4 complete (component Swift file exists at `{componentLocation}`).
+2. **Wave 1 (parallel)**: Dispatch subagents:
+   - **5A** (`phase-5a-viewinspector.md`, sonnet, 40 turns) — ViewInspector structure + accessibility tests.
+   - **5B** (`phase-5b-snapshot.md`, sonnet, 40 turns) — Snapshot tests for all Figma variants.
+3. **Wave 2 (conditional)**: **5C** (`phase-5c-unit.md`, sonnet, 30 turns) — Unit tests. Only if component has ViewModel/model logic. N/A for pure View + Configuration.
+4. **TEST EXECUTION**: Run all tests via script — sequentially, NOT parallel (shared DerivedData lock):
+   a. **Switch to local common dependency**: In `{repos.components.path}/Package.swift`, comment out the `.package(url: "...{project.slug}-common...", ...)` line and add `.package(path: "../{project.slug}-common"),` below it. This is needed because the SPM package resolves dependencies from remote git, but Phase 2 adds identifiers/keys to the local editable copy.
+   b. **Run tests**:
+      ```bash
+      REPO_ROOT=$(git rev-parse --show-toplevel)
+      bash "${REPO_ROOT}/.instructions/figma/figma-to-swiftui/scripts/run-uicomponents-tests.sh" --filter "{ComponentName}ViewInspectorTests"
+      bash "${REPO_ROOT}/.instructions/figma/figma-to-swiftui/scripts/run-uicomponents-tests.sh" --filter "{ComponentName}SnapshotTests"
+      ```
+      Both must exit 0 with zero warnings on component test files. Fix deprecated `Inspectable` conformance or other warnings before proceeding.
+   c. **Revert to remote dependency**: Uncomment the original `.package(url: ...)` line and remove the `.package(path: ...)` line in `Package.swift`.
+5. **UPDATE HISTORY**: Append Phase 5 summary with test counts.
+
+---
+
+## Phase 6 Routing
+
+Phase 6 is dispatched as a single subagent. After the subagent returns COMPLETE, run the finalization script as a safety net (idempotent — safe to run even if the subagent already ran it):
+
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/phase6-finalize.py \
+    --node-id '{nodeId}' \
+    --file-key '{fileKey}' \
+    --component-name '{componentName}' \
+    --platform ios
+```
+
+Parse stdout JSON. Verify `"status": "ok"`. Update IMPLEMENTATION_HISTORY.md with Phase 6 summary.
+
+---
+
+## Read-Order Table
+
+When building the `Previous Phase Artifacts` section of the dispatch prompt, list artifacts in this order. Compact artifacts go FIRST so the subagent establishes context before large files consume the context window.
+
+Every phase must be independently operable from a clean session — all artifacts remain accessible on disk. This table is a **read-ordering preference**, not a prohibition.
+
+| Phase | Read FIRST (compact) | Read SECOND (if detail needed) |
+|-------|---------------------|-------------------------------|
+| 2A-2D | `pass1/component_summary.json` | `pass1/design_context_response.json`, `pass1/component_properties.json` |
+| 3A | `pass1/component_summary.json`, `IMPLEMENTATION_HISTORY.md` | — |
+| 3B | `pass1/component_summary.json`, `pass1/variable_defs_response.json` | `pass1/design_context_response.json` (for binding context) |
+| 3C | `pass1/component_summary.json`, `pass1/code_connect_map_response.json` | — |
+| 3D | `pass1/component_summary.json`, `pass1/component_properties.json` | `pass1/design_context_response.json`, `pass1/metadata_response.xml` |
+| 3E | `pass1/component_summary.json`, `pass1/design_context_assets.txt` | — |
+| 3F | `pass1/component_summary.json`, `pass2/utility_*.md` | `pass1/design_context_response.json` |
+| 3G | `pass1/component_summary.json`, `pass3/04b_component_architecture.md` | — |
+| 4A | `pass3/04b_component_architecture.md`, `pass3/05_complexity.md`, `pass3/00_property_coverage.json` | `pass1/component_summary.json` |
+| 4B | `pass1/component_summary.json`, `pass3/00_property_coverage.json`, `pass3/07_implementation_spec.md`, `pass3/02_token_mapping.md`, `pass3/04b_component_architecture.md`, `pass3/04_patterns.md`, `pass3/03_nested_components.md`, `pass3/08_utility_integration.md`, `pass1/screenshot.png` | `pass1/design_context_response.json` (for complex layout detail) |
+| 4C | `pass3/07_implementation_spec.md`, `pass3/04b_component_architecture.md`, `pass3/00_property_coverage.json` | `pass1/component_summary.json` |
+| 4D | `{componentLocation}/{ComponentName}.swift`, `{componentLocation}/{ComponentName}Configuration.swift` (if exists) | `pass3/04_patterns.md` |
+| 4E | `{componentLocation}/{ComponentName}Configuration.swift`, `{componentLocation}/{ComponentName}.swift` | — |
+| 6 | `pass1/component_properties.json`, `{sourceLocation}/FIGMA.md`, `{sourceLocation}/{componentName}.swift` | — |
+
+---
+
+## Resume Mode
+
+When `$ARGUMENTS` is `phase-N`:
+
+1. Find IMPLEMENTATION_HISTORY.md by searching `{repos.packagesContainer}/{repos.artifactsRepo}/ImplementationArtifacts/Figma/Components/`
+2. Read it to get: componentName, fileKey, nodeId, artifactPath, componentLocation. Derive confluencePath: replace `Figma/Components` with `Confluence` in artifactPath.
+3. Verify prerequisite phase artifacts exist
+4. Dispatch the requested phase
+
+If prerequisites are missing, HALT and inform user.
+
+---
+
+## Status Mode
+
+When `$ARGUMENTS` is `status`:
+
+1. Search for all IMPLEMENTATION_HISTORY.md files in `{repos.packagesContainer}/{repos.artifactsRepo}/ImplementationArtifacts/`
+2. Display summary: component name, current phase, last gate, last updated
+
+---
+
+## Artifact Path Resolution
+
+Use FigmaRegistryUtility to resolve component paths:
+
+```bash
+CONFIG_PATH="{repos.common.path}"
+cd "$CONFIG_PATH" && .build/debug/FigmaRegistryUtility lookup --node-id '{nodeId}'
+```
+
+Returns:
+- `suggestedComponentName` → componentName
+- `suggestedComponentLocation` → componentLocation (under UIComponents/Sources/)
+- `suggestedArtifactPath` → artifactPath: `ImplementationArtifacts/Figma/Components/{Category}/{ComponentName}/`
+
+Derive confluencePath from artifactPath: replace `Figma/Components` with `Confluence` in the artifact path string.

package/pipeline/skills/figma-ios/figma-to-component/halt-return-protocol.md

@@ -0,0 +1,57 @@
+# RETURN PROTOCOL
+
+When you complete this phase, output EXACTLY one of these blocks as your FINAL message.
+
+---
+
+## On success:
+
+```
+STATUS: COMPLETE
+PHASE: phase-{N}
+GATES_PASSED: [list every gate ID that passed]
+ARTIFACTS_CREATED:
+  - {path}
+  - {path}
+SUMMARY: {one-line description of what was accomplished}
+```
+
+## On failure (tool error, missing file, validation fail):
+
+```
+STATUS: HALT
+PHASE: phase-{N}
+GATE: {gate-id that failed}
+REASON: {exact reason — copy from instruction if applicable}
+COMPLETED_GATES: [gates that passed before halt]
+ARTIFACTS_CREATED: [files written before halt, or "none"]
+USER_ACTION_REQUIRED: {what the user must fix before retry}
+```
+
+## On decision needed (user choice required):
+
+```
+STATUS: NEEDS_INPUT
+PHASE: phase-{N}
+GATE: {gate-id where decision is needed}
+QUESTION: {what needs to be decided}
+OPTIONS:
+  1) {choice}
+  2) {choice}
+  3) {choice}
+SUGGESTED: {your recommendation and why}
+COMPLETED_GATES: [gates passed so far]
+CONTEXT: {relevant data the user needs to make the decision}
+```
+
+---
+
+## Rules
+
+1. Output EXACTLY ONE block as your FINAL message.
+2. STOP after outputting the block. Do not call any more tools.
+3. Every gate you pass must appear in GATES_PASSED or COMPLETED_GATES.
+4. Every file you created must appear in ARTIFACTS_CREATED.
+5. Never output a STATUS block mid-execution — only at the very end.
+6. If you encounter multiple failures, report the FIRST one.
+7. If a HALT condition says to check for USER_DECISION in the prompt first, do so before halting.