From faa382d8f0384c004e46c609319fb528bdf8da30 Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Wed, 8 Apr 2026 13:16:04 -0700 Subject: [PATCH 1/8] feat: add multi-phase workflow enforcement rules for skill generation The agent-instructions format and author-agent-instructions template had no guidance for multi-phase interactive workflows with explicit gating. Skills generated from complex pipelines (e.g., a 7-pass PCB design workflow) would describe the pipeline architecturally but not behaviorally constrain the agent, causing it to skip intermediate steps and jump directly to final output generation. Add 'Multi-phase workflow rules' to the agent-instructions format covering four required enforcement mechanisms: - Critical constraints block (prohibited output types, self-correction) - Phase gate directives (explicit stop at each phase boundary) - Pass tracking block (observable state announcement) - Anti-shortcut warning (failure mode rationale) Update the author-agent-instructions template to: - Detect multi-phase source templates and apply the new rules - Preserve phase gating logic instead of condensing it away - Add Critical Rule blocks at each phase boundary Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Alan Jowett --- formats/agent-instructions.md | 54 ++++++++++++++++++++++++++ templates/author-agent-instructions.md | 24 ++++++++++++ 2 files changed, 78 insertions(+) diff --git a/formats/agent-instructions.md b/formats/agent-instructions.md index 910ba37..1ab12e4 100644 --- a/formats/agent-instructions.md +++ b/formats/agent-instructions.md @@ -183,6 +183,60 @@ 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 +(multiple 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"). + +These rules apply to skills generated from multi-phase templates +(templates with `mode: interactive` and more than two sequential phases, +or templates that define explicit 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..7ee910f 100644 --- a/templates/author-agent-instructions.md +++ b/templates/author-agent-instructions.md @@ -147,6 +147,16 @@ 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 multiple sequential + phases, pipeline passes, or `mode: interactive` with explicit gates): + - Add a `## Critical Constraints` section at the top (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 + - Do NOT condense the phase structure — it is the behavioral contract ### Step 3: Condense and Adapt the Content @@ -163,6 +173,20 @@ 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) + 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 From b586850fc7741b1ecfad804bb24f87bade3a106a Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Wed, 8 Apr 2026 13:54:09 -0700 Subject: [PATCH 2/8] feat: add IR consumption rule for generated scripts in multi-phase workflows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Scripts produced by post-binding tool steps (e.g., schematic renderers, PCB layout generators) were hardcoding design data as Python dicts instead of reading from the IR files that earlier passes produced. This defeats the purpose of the IR architecture — the IRs exist but are ignored. Add rule 5 (IR consumption rule) to the multi-phase workflow rules: - Generated code MUST read component lists, net names, values, and library mappings from IR files at runtime - Only format-specific syntax constants are permitted as hardcoded values - Self-check: if deleting the IR files would not change the script's output, the script is hardcoding data — rewrite it Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Alan Jowett --- formats/agent-instructions.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/formats/agent-instructions.md b/formats/agent-instructions.md index 1ab12e4..6adf2e8 100644 --- a/formats/agent-instructions.md +++ b/formats/agent-instructions.md @@ -232,6 +232,25 @@ agent from short-circuiting the pipeline. Specifically: 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 + - 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 `mode: interactive` and more than two sequential phases, or templates that define explicit pipeline passes). Single-phase or From 5c39b82e595f346451fdef42c52d074bc25f7a53 Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Wed, 8 Apr 2026 13:56:22 -0700 Subject: [PATCH 3/8] feat: propagate IR consumption rule to author-agent-instructions template The template's Step 2 (skill planning) and Step 3 (condense) referenced the multi-phase workflow rules but didn't mention the IR consumption rule added in the previous commit. Both locations now include the directive: generated code must read from artifacts at runtime, never hardcode data, with the self-check. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Alan Jowett --- templates/author-agent-instructions.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/templates/author-agent-instructions.md b/templates/author-agent-instructions.md index 7ee910f..7db5e6d 100644 --- a/templates/author-agent-instructions.md +++ b/templates/author-agent-instructions.md @@ -156,6 +156,12 @@ Plan a `.github/skills//SKILL.md` file containing: - 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, and include the + self-check ("if deleting the artifacts wouldn't change the + script's output, it's hardcoding data — rewrite it") - Do NOT condense the phase structure — it is the behavioral contract ### Step 3: Condense and Adapt the Content @@ -185,6 +191,9 @@ Transform the loaded components into agent instruction prose: - 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. From 735030150b432321bddba238226144cd38ae79ed Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Wed, 8 Apr 2026 14:02:34 -0700 Subject: [PATCH 4/8] feat: add fail-stop backstop to IR consumption rule If generated code cannot read or parse a required artifact (file missing, malformed YAML, missing fields), it MUST raise an error and halt. It MUST NOT fall back to generating data from memory, prior context, or hardcoded defaults. A missing artifact means an earlier pass needs re-execution, not a workaround. This closes the last loophole: without this rule, an agent hitting a friction point reading an IR file could silently fall back to inlining the data from conversation context, which is how hardcoding starts. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Alan Jowett --- formats/agent-instructions.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/formats/agent-instructions.md b/formats/agent-instructions.md index 6adf2e8..d4635bc 100644 --- a/formats/agent-instructions.md +++ b/formats/agent-instructions.md @@ -247,6 +247,12 @@ agent from short-circuiting the pipeline. Specifically: - **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. - Include this rule as an explicit directive in any phase that produces scripts or code that transforms artifacts into downstream outputs From 4e6d0024aaddc956da46812d8daf0261da6ca127 Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Wed, 8 Apr 2026 14:55:31 -0700 Subject: [PATCH 5/8] feat: add field-level mapping and gate-driven iteration rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two additions to the IR consumption rule: 1. Field-level mapping: Tool steps that produce scripts must enumerate which specific artifact fields the script reads (e.g., connector positions from connector_placement[].position.x_mm), not just generic references like 'read from IR-3'. Generic references produce scripts that ignore detailed fields. 2. Gate-driven iteration: When a tool step has a validation gate (e.g., DRC zero violations) and the gate fails, the agent must iterate on the script to fix violations — not ask the user whether to proceed. The agent only presents output for user approval after gate criteria are satisfied. Asking the user to accept a failing gate is itself a gate violation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Alan Jowett --- formats/agent-instructions.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/formats/agent-instructions.md b/formats/agent-instructions.md index d4635bc..60369d9 100644 --- a/formats/agent-instructions.md +++ b/formats/agent-instructions.md @@ -253,6 +253,21 @@ agent from short-circuiting the pipeline. Specifically: 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 From 71fcb5b390e28464d91ba74d2965d25dba475455 Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Wed, 8 Apr 2026 15:35:24 -0700 Subject: [PATCH 6/8] =?UTF-8?q?fix:=20address=20PR=20review=20comments=20?= =?UTF-8?q?=E2=80=94=20consistency=20and=20formatting?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Convert 'Multi-phase workflow rules' from bold text to ### heading for stable anchor linking - Align multi-phase trigger criteria between format and template: '3+ sequential phases' or 'interactive with explicit gates/passes' - Fix fenced code block indentation in list items 2 and 3 for correct GitHub Markdown rendering (4-space indent + blank line separation) - Align Critical Constraints placement wording: 'immediately after the opening task description, before architecture/methodology content' Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Alan Jowett --- formats/agent-instructions.md | 34 ++++++++++++++------------ templates/author-agent-instructions.md | 10 +++++--- 2 files changed, 25 insertions(+), 19 deletions(-) diff --git a/formats/agent-instructions.md b/formats/agent-instructions.md index 60369d9..7f81cd6 100644 --- a/formats/agent-instructions.md +++ b/formats/agent-instructions.md @@ -183,12 +183,12 @@ files. | Format | Output structure instructions | | Template | Task instructions and workflow | -**Multi-phase workflow rules:** +### Multi-phase workflow rules When the source template defines a multi-phase or multi-pass workflow -(multiple 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: +(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 @@ -208,21 +208,25 @@ agent from short-circuiting the pipeline. Specifically: 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 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) - ``` + + ``` + 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. @@ -273,8 +277,8 @@ agent from short-circuiting the pipeline. Specifically: downstream outputs These rules apply to skills generated from multi-phase templates -(templates with `mode: interactive` and more than two sequential phases, -or templates that define explicit pipeline passes). Single-phase or +(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 diff --git a/templates/author-agent-instructions.md b/templates/author-agent-instructions.md index 7db5e6d..2f8dcaf 100644 --- a/templates/author-agent-instructions.md +++ b/templates/author-agent-instructions.md @@ -147,10 +147,12 @@ 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 multiple sequential - phases, pipeline passes, or `mode: interactive` with explicit gates): - - Add a `## Critical Constraints` section at the top (see the - `agent-instructions` format's "Multi-phase workflow rules") +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` 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 From a14287d97b0b61093f6910ae2747db47cd963028 Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Wed, 8 Apr 2026 16:03:45 -0700 Subject: [PATCH 7/8] fix: align Critical Constraints heading with format spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use the full heading text 'Critical Constraints — Read Before Doing Anything' as recommended by the format spec to maximize salience and reduce variability in generated skills. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Alan Jowett --- templates/author-agent-instructions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/templates/author-agent-instructions.md b/templates/author-agent-instructions.md index 2f8dcaf..80d1a3e 100644 --- a/templates/author-agent-instructions.md +++ b/templates/author-agent-instructions.md @@ -149,10 +149,10 @@ Plan a `.github/skills//SKILL.md` file containing: - 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` section immediately after the - opening task description, before any architecture/methodology - content (see the `agent-instructions` format's "Multi-phase - workflow rules") + - 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 From 86113fb74997426a32c24043bd43e20bcd5bfbf4 Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Wed, 8 Apr 2026 16:16:07 -0700 Subject: [PATCH 8/8] fix: address round 4 review comments - Demote Multi-phase workflow rules from ### to #### so it nests under section 4 (CLI Skill) and preserves the document outline - Expand the IR consumption rule checklist in the template's Step 2 to include all sub-requirements: fail-stop, field-level mapping, self-check, and gate-driven iteration Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Alan Jowett --- formats/agent-instructions.md | 2 +- templates/author-agent-instructions.md | 8 ++++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/formats/agent-instructions.md b/formats/agent-instructions.md index 7f81cd6..26cd8cc 100644 --- a/formats/agent-instructions.md +++ b/formats/agent-instructions.md @@ -183,7 +183,7 @@ files. | Format | Output structure instructions | | Template | Task instructions and workflow | -### Multi-phase workflow rules +#### 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 diff --git a/templates/author-agent-instructions.md b/templates/author-agent-instructions.md index 80d1a3e..161552e 100644 --- a/templates/author-agent-instructions.md +++ b/templates/author-agent-instructions.md @@ -161,9 +161,13 @@ Plan a `.github/skills//SKILL.md` file containing: - 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, and include the + 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") + 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