diff --git a/formats/agent-instructions.md b/formats/agent-instructions.md index 910ba37..26cd8cc 100644 --- a/formats/agent-instructions.md +++ b/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 + \, 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 — + STATUS: In progress + NEXT: Phase N+1 — (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 diff --git a/templates/author-agent-instructions.md b/templates/author-agent-instructions.md index 254e066..161552e 100644 --- a/templates/author-agent-instructions.md +++ b/templates/author-agent-instructions.md @@ -147,6 +147,28 @@ Plan a `.github/skills//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