feat: add multi-phase workflow enforcement rules for skill generation

formats/agent-instructions.md

@@ -183,6 +183,104 @@ files.
 | Format | Output structure instructions |
 | Template | Task instructions and workflow |
 
+#### Multi-phase workflow rules
+
+When the source template defines a multi-phase or multi-pass workflow
+(three or more sequential phases where each phase's output feeds the
+next), the skill file MUST include behavioral enforcement that prevents
+the agent from short-circuiting the pipeline. Specifically:
+
+1. **Critical constraints block** — Place a prominent section immediately
+   after the opening task description (before the architecture or
+   methodology sections) titled `## Critical Constraints — Read Before
+   Doing Anything` (or similar). This section MUST contain:
+   - An explicit statement that phases execute one at a time, in order
+   - A list of **prohibited output types per phase** — name the specific
+     file types, languages, or formats the agent MUST NOT produce during
+     earlier phases (e.g., "You MUST NOT generate Python, KiCad
+     S-expressions, or any EDA-tool-specific files during front-end
+     passes — only structured YAML IRs")
+   - A self-correction directive: "If you find yourself producing
+     \<prohibited output\>, STOP and return to the current phase"
+   - A brief explanation of **why the pipeline exists** — what failure
+     mode it prevents (e.g., "A previous monolithic approach failed
+     because…"). This gives the agent a concrete reason to comply.
+
+2. **Phase gate directives** — Each phase MUST end with a `### Critical
+   Rule` subsection containing an explicit stop instruction:
+
+       ```
+       **Do NOT proceed to Phase N+1 until the user explicitly approves.**
+       Present the output artifact, ask for approval, and WAIT.
+       ```
+
+   Do NOT bury gate logic in a summary table or an appendix — it must
+   appear inline at the end of the phase it gates.
+
+3. **Pass tracking block** — Include a section (e.g., `## Current Pass
+   Tracking`) instructing the agent to announce its current state at the
+   start of the workflow and after each phase transition:
+
+       ```
+       CURRENT PHASE: Phase N — <Name>
+       STATUS: In progress
+       NEXT: Phase N+1 — <Name> (blocked until Phase N gate passes)
+       ```
+
+   This creates an observable invariant that both the agent and the user
+   can monitor.
+
+4. **Anti-shortcut warning** — If the workflow has phases that produce
+   intermediate artifacts (not final deliverables), explicitly state that
+   the intermediate artifact is the ONLY permitted output of that phase.
+   Name the artifact type (e.g., "IR-2 is a YAML netlist, NOT Python
+   code, NOT a schematic file").
+
+5. **IR consumption rule** — If the workflow produces intermediate
+   artifacts (IRs, specs, data files) that later phases or tool steps
+   consume, any code generated by the pipeline (scripts, renderers,
+   generators) MUST read its data from those artifacts at runtime. The
+   code MUST NOT hardcode, inline, or duplicate data that exists in the
+   artifacts. Specifically:
+   - Component lists, net names, pin assignments, values, and library
+     mappings MUST be read from IR files (e.g., `yaml.safe_load()`),
+     not embedded as Python dicts, JSON literals, or string constants
+   - The only constants permitted in generated code are format-specific
+     syntax (e.g., S-expression structure, coordinate math, file
+     headers) and configuration defaults (e.g., font sizes, grid snap)
+   - **Self-check**: If the generated code would produce the same output
+     even if the IR files were deleted, the code is hardcoding data
+     instead of consuming the IRs — this is a violation
+   - **Fail-stop**: If the code cannot read or parse a required artifact
+     (file missing, malformed YAML, missing expected fields), it MUST
+     raise an error and halt. It MUST NOT fall back to generating the
+     data from memory, prior conversation context, or hardcoded
+     defaults. A missing artifact means an earlier pass needs to be
+     re-executed, not worked around.
+   - **Field-level mapping**: For each tool step that produces a script
+     consuming artifacts, the skill MUST enumerate which specific
+     artifact fields the script reads — not just "read from IR-3" but
+     "connector positions → `connector_placement[].position.x_mm`,
+     component courtyard sizes → `IR-1e.components[].courtyard_mm`."
+     Generic references like "read placement constraints from IR-3"
+     produce scripts that ignore the detailed fields. The mapping
+     must be specific enough that the script author knows exactly which
+     YAML paths to traverse.
+   - **Gate-driven iteration**: If a tool step has a validation gate
+     (e.g., DRC with zero violations), and the gate fails, the agent
+     MUST iterate on the script to fix the violations — not ask the
+     user whether to proceed. The agent only presents the output for
+     user approval after the gate criteria are satisfied. Asking the
+     user to accept a failing gate is a gate violation.
+   - Include this rule as an explicit directive in any phase that
+     produces scripts or code that transforms artifacts into
+     downstream outputs
+
+These rules apply to skills generated from multi-phase templates
+(templates with multiple sequential phases, or interactive templates
+that define explicit phase gates or pipeline passes). Single-phase or
+simple analysis skills do not require these enforcement mechanisms.
+
 ### 5. File Content — Claude Code and Cursor
 
 For Claude Code (`CLAUDE.md`) and Cursor (`.cursorrules`), produce a

templates/author-agent-instructions.md

@@ -147,6 +147,28 @@ Plan a `.github/skills/<name>/SKILL.md` file containing:
    - The protocol methodology as step-by-step instructions
    - Clear input/output expectations
    - Any file or tool requirements
+3. **For multi-phase workflows** (source template has pipeline passes, or
+   is `mode: interactive` with more than two phases or explicit gates):
+   - Add a `## Critical Constraints — Read Before Doing Anything`
+     section immediately after the opening task description, before
+     any architecture/methodology content (see the
+     `agent-instructions` format's "Multi-phase workflow rules")
+   - Add `### Critical Rule` stop directives at each phase boundary
+   - Add a `## Current Pass Tracking` section with a status template
+   - Explicitly name prohibited output types per phase
+   - Include the anti-shortcut rationale explaining what failure mode
+     the pipeline prevents
+   - If any phase produces code that consumes artifacts from earlier
+     phases (e.g., a renderer script that reads IR files), add the
+     IR consumption rule: the code MUST read data from artifacts at
+     runtime, MUST NOT hardcode it as literals, MUST fail-stop if
+     required artifacts are missing or malformed, MUST map consumed
+     values from explicit field-level YAML paths, MUST include the
+     self-check ("if deleting the artifacts wouldn't change the
+     script's output, it's hardcoding data — rewrite it"), and MUST
+     iterate when a validation gate fails rather than asking the user
+     to accept the failure
+   - Do NOT condense the phase structure — it is the behavioral contract
 
 ### Step 3: Condense and Adapt the Content
 
@@ -163,6 +185,23 @@ Transform the loaded components into agent instruction prose:
    - Omit meta-commentary about the protocol's structure
    - Rewrite in second person ("When you encounter X, always Y")
    - If multiple protocols overlap, merge the redundant parts
+   - **Exception for multi-phase workflows**: If the source template
+     defines a multi-phase pipeline (multiple sequential phases where
+     each phase's output feeds the next), do NOT condense away the
+     phase gating logic. The sequential structure, explicit stop points,
+     and prohibited-output rules ARE the critical behavioral constraints.
+     Preserve them as imperative directives, not architectural
+     descriptions. Specifically:
+     - Keep each phase's gate rule as a `### Critical Rule` block
+     - Keep the prohibited-output-type list per phase
+     - Add a pass tracking block so the agent announces its current state
+     - Include the anti-shortcut rationale (why the pipeline exists,
+       what failure mode it prevents)
+     - For phases that produce code consuming earlier artifacts, include
+       the IR consumption rule: generated code reads data from artifacts
+       at runtime, never hardcodes it, with the self-check directive
+     See the `agent-instructions` format's "Multi-phase workflow rules"
+     for the complete set of required enforcement mechanisms.
 
 3. **Incorporate the additional behaviors** from `{{behaviors}}`:
    - Add any domain-specific or project-specific instructions