From fc7cd9bf001b94520f55b091a97675786b82c8c9 Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Mon, 6 Apr 2026 13:15:56 -0700 Subject: [PATCH 1/6] Add design-pcb-layout interactive template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add an interactive template that guides users through complete PCB layout — from layout requirements through placement, automated routing, and DRC validation. This is Step 6 of 9 in the hardware design workflow. The template composes 4 protocols into an 8-phase workflow: 1. Layout requirements gathering (interactive — board size, connector edges, mechanical constraints) 2. Board definition and design rules (stackup, net classes, fab minimums) 3. Component placement (Python pcbnew script generation) 4. User review of placement (gate — loop back if REVISE) 5. Routing and DRC loop (FreeRouting + kicad-cli DRC, max 5 iterations) 6. Layout audit (layout-design-review protocol, PASS/FAIL verdict) 7. User review of layout (gate — loop back to 3, 5, or SCHEMATIC FEEDBACK) 8. Deliver artifacts (routed .kicad_pcb, Python script, DRC report) Key design decisions: - Schematic feedback loop: Phase 7 can trigger schematic revisions when layout reveals issues (different package needed, bus split, additional decoupling). User updates schematic, runs Update PCB, then returns to Phase 3. - format: null (interactive template pattern, consistent with design-schematic and engineering-workflow) - Input contract requires a populated .kicad_pcb from schematic - Python script with configuration section for user adjustability Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- manifest.yaml | 9 + templates/design-pcb-layout.md | 320 +++++++++++++++++++++++++++++++++ 2 files changed, 329 insertions(+) create mode 100644 templates/design-pcb-layout.md diff --git a/manifest.yaml b/manifest.yaml index 29e6910..c350c4d 100644 --- a/manifest.yaml +++ b/manifest.yaml @@ -1269,6 +1269,15 @@ templates: persona: electrical-engineer protocols: [anti-hallucination, self-verification, component-selection, component-selection-audit, schematic-design, schematic-compliance-audit] + - name: design-pcb-layout + path: templates/design-pcb-layout.md + description: > + Interactive PCB layout session. Guides the user from a completed + schematic through placement, automated routing, and DRC + validation with layout-to-schematic feedback loop. + persona: electrical-engineer + protocols: [anti-hallucination, self-verification, pcb-layout-design, layout-design-review] + testing: - name: discover-tests-for-changes path: templates/discover-tests-for-changes.md diff --git a/templates/design-pcb-layout.md b/templates/design-pcb-layout.md new file mode 100644 index 0000000..0f0962b --- /dev/null +++ b/templates/design-pcb-layout.md @@ -0,0 +1,320 @@ + + + +--- +name: design-pcb-layout +mode: interactive +description: > + Interactive PCB layout session. Guides the user from a completed + schematic through layout requirements, component placement, automated + routing, and DRC validation. Composes pcb-layout-design and + layout-design-review protocols with user review gates. Handles + the schematic-to-layout feedback loop when layout constraints + force schematic revisions. +persona: electrical-engineer +protocols: + - guardrails/anti-hallucination + - guardrails/self-verification + - reasoning/pcb-layout-design + - analysis/layout-design-review +format: null +params: + project_name: "Name of the hardware project or product" + schematic_path: "Path to the KiCad schematic (.kicad_sch) and board (.kicad_pcb) files" + context: "Additional context — target fab service, board size constraints, enclosure fit, layer count preference, special routing requirements" +input_contract: + type: artifact-set + description: > + A completed KiCad schematic with footprint assignments and a + .kicad_pcb file populated via 'Update PCB from Schematic'. + Optionally, a component selection report from the design-schematic + template. +output_contract: + type: artifact-set + description: > + A routed, DRC-clean KiCad PCB file (.kicad_pcb), the Python + layout script (for reproducibility), a DRC report, and a layout + audit report. If schematic revisions were required, an updated + schematic is included. +--- + +# Task: Interactive PCB Layout Design + +You are tasked with guiding the user through a **complete PCB layout +session** — from gathering layout requirements through component +placement, automated routing, and DRC validation to a routed, +DRC-clean board. + +This is a multi-phase, interactive workflow with a feedback loop: +layout constraints may force schematic revisions, which feed back +into the layout. + +## Inputs + +**Project**: {{project_name}} + +**Schematic / Board Files**: +{{schematic_path}} + +**Additional Context**: +{{context}} + +--- + +## Workflow Overview + +``` +Phase 1: Layout Requirements Gathering (interactive) + ↓ +Phase 2: Board Definition and Design Rules + ↓ +Phase 3: Component Placement (generates Python script) + ↓ +Phase 4: User Review of Placement + ↓ ← loop back to Phase 3 if REVISE +Phase 5: Routing and DRC Loop (FreeRouting + kicad-cli DRC) + ↓ +Phase 6: Layout Audit (layout-design-review protocol) + ↓ +Phase 7: User Review of Layout + ↓ ← loop back to Phase 3, 5, or SCHEMATIC FEEDBACK +Phase 8: Deliver Artifacts +``` + +--- + +## Phase 1 — Layout Requirements Gathering + +**Goal**: Gather the user's spatial, mechanical, and manufacturing +requirements before any layout decisions. + +Apply the **pcb-layout-design protocol Phase 2** (Layout Requirements +Gathering) in full: + +1. **Board form factor**: Ask about dimensions, shape, mounting + method, and mounting hole locations. +2. **Connector placement**: For each connector — which edge, + position along the edge, orientation. +3. **Component placement preferences**: MCU position, battery + connector, antenna keepout, display/LED placement, programming + header accessibility, top vs. bottom side preferences. +4. **Mechanical constraints**: Enclosure fit, height clearance, + keep-out zones, cable routing clearances. +5. **Fabrication service**: Confirm JLCPCB, PCBWay, or other, + and their design rule minimums. + +### Critical Rule + +**Do NOT proceed to Phase 2 until the user explicitly confirms the +layout requirements** (e.g., "READY", "proceed", "looks good"). + +### Output + +A layout requirements summary table for user confirmation. + +--- + +## Phase 2 — Board Definition and Design Rules + +**Goal**: Define the board structure and configure design rules. + +Apply the **pcb-layout-design protocol Phases 3–4**: + +1. **Board outline** on Edge.Cuts (dimensions, corner radii, + cutouts). +2. **Layer stackup** (2-layer or 4-layer with layer assignments). +3. **Mounting holes** at user-specified locations. +4. **Copper zones** (ground pour, power pours, antenna keepout). +5. **Design rules**: Default trace width, clearance, via size per + fab house minimums. +6. **Net classes**: Power (wider traces), High-Speed (impedance + controlled), Default (standard signals). + +### Output + +Board definition specification and design rule configuration. + +--- + +## Phase 3 — Component Placement + +**Goal**: Place all components following the user's requirements +and engineering best practices. + +Apply the **pcb-layout-design protocol Phases 5–7**: + +1. **Placement priority**: Fixed-position components first + (connectors, mounting holes, antenna), then MCU, power section, + high-speed peripherals, remaining ICs, decoupling caps, + passives. +2. **Generate the Python script** using the pcbnew API: + - Load the `.kicad_pcb` (with footprints from schematic) + - Apply board outline, design rules, net classes + - Place components per the specification + - Export `.dsn` for FreeRouting +3. **Placement verification**: Before routing, check that signal + flow is logical, power flows from source to loads, high-speed + signals have short paths, and no courtyards overlap. + +### Output + +- Python layout script (with configuration section at top for + user adjustment) +- Placement specification (component positions and rationale) + +--- + +## Phase 4 — User Review of Placement + +**Goal**: Get user approval of component placement before investing +in routing. + +1. Present the placement plan (component positions, grouping + rationale). +2. Present any placement tradeoffs (e.g., "moved sensor to back + side to fit board dimensions"). +3. Ask: "Do you approve this placement, or do you want to adjust + component positions?" + +### Transition Rules + +- **Approved**: Proceed to Phase 5. +- **Revise**: Adjust placement in the script configuration and + return to Phase 3. + +--- + +## Phase 5 — Routing and DRC Loop + +**Goal**: Route the board and achieve DRC-clean status. + +Apply the **pcb-layout-design protocol Phases 8–9**: + +1. **Run the Python script**: Execute placement, export `.dsn`. +2. **Run FreeRouting** headlessly: + `java -jar freerouting.jar -de board.dsn -do board.ses -mp 20` +3. **Import routing result**: `pcbnew.ImportSpecctraSES(board, "board.ses")` +4. **Fill copper zones**. +5. **Run DRC**: `kicad-cli pcb drc -o drc-report.json --format json --severity-all board.kicad_pcb` +6. **Classify violations**: Clearance, unconnected nets, track + width, courtyard overlap, edge clearance. +7. **Automated fix loop**: Adjust design rules or placement, re-run. + Maximum 5 iterations before escalating to user. + +### Transition Rules + +- **DRC clean** (zero violations): Proceed to Phase 6. +- **DRC violations persist after 5 iterations**: Present remaining + violations to the user with analysis (placement issue vs. routing + issue vs. design rule issue) and ask for guidance. + +--- + +## Phase 6 — Layout Audit + +**Goal**: Adversarially verify the layout is correct. + +Apply the **layout-design-review protocol** in full: + +1. DRC report review (violations vs. warnings). +2. Trace width and current capacity (IPC-2221 verification). +3. Impedance and signal integrity (USB differential pairs, + controlled impedance, return path continuity). +4. Component placement review (decoupling cap proximity, antenna + keepout, connector accessibility, thermal placement). +5. Ground plane and power integrity (ground plane continuity, + power pour adequacy, star grounding if applicable). +6. Manufacturing constraint compliance (minimum features, board + outline, panelization, assembly constraints). +7. Conclude with an explicit audit verdict: + - **PASS**: No blocking issues; proceed. + - **FAIL**: Blocking issues found; must be corrected. + +### Transition Rules + +- **PASS verdict**: Proceed to Phase 7. +- **FAIL verdict**: Fix blocking issues. If the fix requires + placement changes, return to Phase 3. If routing-only, return + to Phase 5. + +--- + +## Phase 7 — User Review of Layout + +**Goal**: Get user approval of the routed layout. + +1. Present the board overview (top and bottom views, layer + utilization). +2. Present key layout decisions (routing strategy, ground plane + design, impedance-controlled traces). +3. Present the DRC summary and audit verdict. +4. Present any remaining warnings with justification. +5. Ask: "Do you approve this layout, or do you want to make + changes?" + +### Transition Rules + +- **Approved**: Proceed to Phase 8. +- **Revise placement**: Return to Phase 3. +- **Revise routing only**: Return to Phase 5. +- **Schematic feedback required**: If the layout revealed issues + that require schematic changes (e.g., need a different package, + need to split a bus, need additional decoupling), document the + required schematic changes and inform the user that the schematic + must be updated before continuing. The user should: + 1. Update the schematic + 2. Run "Update PCB from Schematic" in KiCad + 3. Return to Phase 3 with the updated board file + +--- + +## Phase 8 — Deliver Artifacts + +**Goal**: Present all deliverables and next steps. + +1. **Deliver the following artifacts**: + - Routed KiCad PCB file (`.kicad_pcb`) + - Python layout script (for reproducibility and future + modifications) + - DRC report (clean) + - Layout audit report + - Updated schematic (if schematic feedback occurred) + +2. **Next steps**: Inform the user of the next stage: + - Manufacturing artifact generation (Gerbers, BOM, pick-and- + place files for fab submission) + - Or a full end-to-end hardware design workflow, if available + in the library + +--- + +## Non-Goals + +- This template handles **layout and routing only** — schematic + design is handled by the `design-schematic` template. +- This template does NOT generate **manufacturing artifacts** + (Gerbers, drill files, BOM) — that is a separate step. +- This template does NOT perform **simulation** (SPICE, thermal) + — use `validate-simulation` for that. +- This template does NOT design the **enclosure** — use + `review-enclosure` for enclosure audit. + +## Quality Checklist + +Before delivering artifacts in Phase 8, verify: + +- [ ] DRC passes with zero violations +- [ ] All nets are routed (no ratsnest lines remaining) +- [ ] Power trace widths are adequate for current loads +- [ ] USB differential pairs are length-matched and impedance- + controlled +- [ ] Decoupling capacitors are within 3mm of IC power pins +- [ ] Ground plane is continuous under signal traces +- [ ] Antenna keepout zones are respected +- [ ] All components meet fab house minimum spacing +- [ ] Board outline is within specified dimensions +- [ ] Mounting holes are at correct positions +- [ ] Connectors are at user-specified board edges +- [ ] No warnings remain without documented justification +- [ ] Python script configuration section matches the delivered + board (positions are in sync) From 4405ce2c306ca6338cffdc9f32238b1096eb8b2f Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Mon, 6 Apr 2026 13:25:59 -0700 Subject: [PATCH 2/6] Split path params, add Input Validation phase, fix numbering MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. Split ambiguous schematic_path into separate schematic_path and board_path params so scripts have concrete file paths. 2. Added Phase 1 (Input Validation) applying pcb-layout-design protocol Phase 1 — verifies ERC, footprint assignments, board population, fab service. Prevents starting layout on an incomplete board. 3. Renumbered all phases (1-9) and updated all internal cross- references in transition rules to match. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- templates/design-pcb-layout.md | 104 +++++++++++++++++++++------------ 1 file changed, 67 insertions(+), 37 deletions(-) diff --git a/templates/design-pcb-layout.md b/templates/design-pcb-layout.md index 0f0962b..a7401d5 100644 --- a/templates/design-pcb-layout.md +++ b/templates/design-pcb-layout.md @@ -20,15 +20,16 @@ protocols: format: null params: project_name: "Name of the hardware project or product" - schematic_path: "Path to the KiCad schematic (.kicad_sch) and board (.kicad_pcb) files" + schematic_path: "Path to the KiCad schematic file (.kicad_sch)" + board_path: "Path to the KiCad board file (.kicad_pcb), populated via Update PCB from Schematic" context: "Additional context — target fab service, board size constraints, enclosure fit, layer count preference, special routing requirements" input_contract: type: artifact-set description: > - A completed KiCad schematic with footprint assignments and a - .kicad_pcb file populated via 'Update PCB from Schematic'. - Optionally, a component selection report from the design-schematic - template. + A completed KiCad schematic file (.kicad_sch) with footprint + assignments and a corresponding .kicad_pcb file populated via + 'Update PCB from Schematic'. Optionally, a component selection + report from the design-schematic template. output_contract: type: artifact-set description: > @@ -53,8 +54,9 @@ into the layout. **Project**: {{project_name}} -**Schematic / Board Files**: -{{schematic_path}} +**Schematic**: {{schematic_path}} + +**Board**: {{board_path}} **Additional Context**: {{context}} @@ -64,26 +66,54 @@ into the layout. ## Workflow Overview ``` -Phase 1: Layout Requirements Gathering (interactive) +Phase 1: Input Validation (pcb-layout-design protocol Phase 1) + ↓ +Phase 2: Layout Requirements Gathering (interactive) ↓ -Phase 2: Board Definition and Design Rules +Phase 3: Board Definition and Design Rules ↓ -Phase 3: Component Placement (generates Python script) +Phase 4: Component Placement (generates Python script) ↓ -Phase 4: User Review of Placement - ↓ ← loop back to Phase 3 if REVISE -Phase 5: Routing and DRC Loop (FreeRouting + kicad-cli DRC) +Phase 5: User Review of Placement + ↓ ← loop back to Phase 4 if REVISE +Phase 6: Routing and DRC Loop (FreeRouting + kicad-cli DRC) ↓ -Phase 6: Layout Audit (layout-design-review protocol) +Phase 7: Layout Audit (layout-design-review protocol) ↓ -Phase 7: User Review of Layout - ↓ ← loop back to Phase 3, 5, or SCHEMATIC FEEDBACK -Phase 8: Deliver Artifacts +Phase 8: User Review of Layout + ↓ ← loop back to Phase 4, 6, or SCHEMATIC FEEDBACK +Phase 9: Deliver Artifacts ``` --- -## Phase 1 — Layout Requirements Gathering +## Phase 1 — Input Validation + +**Goal**: Verify all prerequisites before beginning layout design. + +Apply the **pcb-layout-design protocol Phase 1** (Input Validation): + +1. **Schematic completeness**: Verify all components have footprint + assignments, all nets are named, and ERC passes. +2. **Board file**: Verify the `.kicad_pcb` contains footprints and + nets from the schematic (user must have run "Update PCB from + Schematic"). +3. **Design constraints from upstream**: Extract power dissipation, + high-speed signals, RF clearance requirements, and current- + carrying trace needs. +4. **Target fab service**: Confirm fab house and design rule + minimums. + +### Transition Rules + +- **All prerequisites met**: Proceed to Phase 2. +- **Missing prerequisites**: Stop and inform the user what needs + to be fixed (e.g., "Run Update PCB from Schematic first", + "Assign footprints to U3 and U5"). + +--- + +## Phase 2 — Layout Requirements Gathering **Goal**: Gather the user's spatial, mechanical, and manufacturing requirements before any layout decisions. @@ -105,7 +135,7 @@ Gathering) in full: ### Critical Rule -**Do NOT proceed to Phase 2 until the user explicitly confirms the +**Do NOT proceed to Phase 3 until the user explicitly confirms the layout requirements** (e.g., "READY", "proceed", "looks good"). ### Output @@ -114,7 +144,7 @@ A layout requirements summary table for user confirmation. --- -## Phase 2 — Board Definition and Design Rules +## Phase 3 — Board Definition and Design Rules **Goal**: Define the board structure and configure design rules. @@ -136,7 +166,7 @@ Board definition specification and design rule configuration. --- -## Phase 3 — Component Placement +## Phase 4 — Component Placement **Goal**: Place all components following the user's requirements and engineering best practices. @@ -164,7 +194,7 @@ Apply the **pcb-layout-design protocol Phases 5–7**: --- -## Phase 4 — User Review of Placement +## Phase 5 — User Review of Placement **Goal**: Get user approval of component placement before investing in routing. @@ -178,13 +208,13 @@ in routing. ### Transition Rules -- **Approved**: Proceed to Phase 5. +- **Approved**: Proceed to Phase 6. - **Revise**: Adjust placement in the script configuration and - return to Phase 3. + return to Phase 4. --- -## Phase 5 — Routing and DRC Loop +## Phase 6 — Routing and DRC Loop **Goal**: Route the board and achieve DRC-clean status. @@ -203,14 +233,14 @@ Apply the **pcb-layout-design protocol Phases 8–9**: ### Transition Rules -- **DRC clean** (zero violations): Proceed to Phase 6. +- **DRC clean** (zero violations): Proceed to Phase 7. - **DRC violations persist after 5 iterations**: Present remaining violations to the user with analysis (placement issue vs. routing issue vs. design rule issue) and ask for guidance. --- -## Phase 6 — Layout Audit +## Phase 7 — Layout Audit **Goal**: Adversarially verify the layout is correct. @@ -232,14 +262,14 @@ Apply the **layout-design-review protocol** in full: ### Transition Rules -- **PASS verdict**: Proceed to Phase 7. +- **PASS verdict**: Proceed to Phase 8. - **FAIL verdict**: Fix blocking issues. If the fix requires - placement changes, return to Phase 3. If routing-only, return - to Phase 5. + placement changes, return to Phase 4. If routing-only, return + to Phase 6. --- -## Phase 7 — User Review of Layout +## Phase 8 — User Review of Layout **Goal**: Get user approval of the routed layout. @@ -254,9 +284,9 @@ Apply the **layout-design-review protocol** in full: ### Transition Rules -- **Approved**: Proceed to Phase 8. -- **Revise placement**: Return to Phase 3. -- **Revise routing only**: Return to Phase 5. +- **Approved**: Proceed to Phase 9. +- **Revise placement**: Return to Phase 4. +- **Revise routing only**: Return to Phase 6. - **Schematic feedback required**: If the layout revealed issues that require schematic changes (e.g., need a different package, need to split a bus, need additional decoupling), document the @@ -264,11 +294,11 @@ Apply the **layout-design-review protocol** in full: must be updated before continuing. The user should: 1. Update the schematic 2. Run "Update PCB from Schematic" in KiCad - 3. Return to Phase 3 with the updated board file + 3. Return to Phase 4 with the updated board file --- -## Phase 8 — Deliver Artifacts +## Phase 9 — Deliver Artifacts **Goal**: Present all deliverables and next steps. @@ -301,7 +331,7 @@ Apply the **layout-design-review protocol** in full: ## Quality Checklist -Before delivering artifacts in Phase 8, verify: +Before delivering artifacts in Phase 9, verify: - [ ] DRC passes with zero violations - [ ] All nets are routed (no ratsnest lines remaining) From 2a7dc2bb1a028c26f30dffedea436c1a3be60ef9 Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Mon, 6 Apr 2026 13:36:25 -0700 Subject: [PATCH 3/6] Add missing protocol phase steps to template 1. Phase 1: Added component footprint inventory step (protocol Phase 1 item 2) which was missing. Covers footprint confirmation, physical dimensions, mounting type, and layout carry-forward notes. 2. Phase 7: Added findings summary step (protocol Phase 7) which was omitted. Documents each finding with severity classification and produces a coverage summary. PASS/FAIL verdict now gates on Critical/High findings specifically rather than vague 'blocking issues'. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- templates/design-pcb-layout.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/templates/design-pcb-layout.md b/templates/design-pcb-layout.md index a7401d5..ec60d69 100644 --- a/templates/design-pcb-layout.md +++ b/templates/design-pcb-layout.md @@ -95,13 +95,17 @@ Apply the **pcb-layout-design protocol Phase 1** (Input Validation): 1. **Schematic completeness**: Verify all components have footprint assignments, all nets are named, and ERC passes. -2. **Board file**: Verify the `.kicad_pcb` contains footprints and +2. **Component footprint inventory**: For each component, confirm + the assigned footprint, physical dimensions, mounting type + (SMD/through-hole), and any placement requirements from the + schematic (layout carry-forward notes). +3. **Board file**: Verify the `.kicad_pcb` contains footprints and nets from the schematic (user must have run "Update PCB from Schematic"). -3. **Design constraints from upstream**: Extract power dissipation, +4. **Design constraints from upstream**: Extract power dissipation, high-speed signals, RF clearance requirements, and current- carrying trace needs. -4. **Target fab service**: Confirm fab house and design rule +5. **Target fab service**: Confirm fab house and design rule minimums. ### Transition Rules @@ -256,9 +260,13 @@ Apply the **layout-design-review protocol** in full: power pour adequacy, star grounding if applicable). 6. Manufacturing constraint compliance (minimum features, board outline, panelization, assembly constraints). -7. Conclude with an explicit audit verdict: - - **PASS**: No blocking issues; proceed. - - **FAIL**: Blocking issues found; must be corrected. +7. Findings summary: document each finding with severity + (Critical / High / Medium / Low / Informational), affected + area, and remediation. Produce a coverage summary (phases + checked, areas examined). +8. Conclude with an explicit audit verdict: + - **PASS**: No Critical or High findings; proceed. + - **FAIL**: Critical or High findings remain; must be corrected. ### Transition Rules From 08615f16df3cae891c7efa54d032df15e0c4d323 Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Mon, 6 Apr 2026 13:44:07 -0700 Subject: [PATCH 4/6] Fix protocol phase references and feedback loop target 1. Phase 4 cited 'pcb-layout-design protocol Phases 5-7' but only covers placement (Phase 5) and script generation (Phase 7). Routing strategy (Phase 6) is applied in the template's Phase 6. Fixed reference to cite Phases 5 and 7 specifically. 2. Schematic feedback loop returned to Phase 4 but should return to Phase 3 (Board Definition) since package/footprint changes from schematic revisions may affect board dimensions, stackup, or design rules. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- templates/design-pcb-layout.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/templates/design-pcb-layout.md b/templates/design-pcb-layout.md index ec60d69..5f60e88 100644 --- a/templates/design-pcb-layout.md +++ b/templates/design-pcb-layout.md @@ -81,7 +81,7 @@ Phase 6: Routing and DRC Loop (FreeRouting + kicad-cli DRC) Phase 7: Layout Audit (layout-design-review protocol) ↓ Phase 8: User Review of Layout - ↓ ← loop back to Phase 4, 6, or SCHEMATIC FEEDBACK + ↓ ← loop back to Phase 4, 6, or SCHEMATIC FEEDBACK (→ Phase 3) Phase 9: Deliver Artifacts ``` @@ -175,7 +175,8 @@ Board definition specification and design rule configuration. **Goal**: Place all components following the user's requirements and engineering best practices. -Apply the **pcb-layout-design protocol Phases 5–7**: +Apply the **pcb-layout-design protocol Phase 5** (Component Placement +Strategy) and **Phase 7** (Python Script Generation): 1. **Placement priority**: Fixed-position components first (connectors, mounting holes, antenna), then MCU, power section, @@ -302,7 +303,9 @@ Apply the **layout-design-review protocol** in full: must be updated before continuing. The user should: 1. Update the schematic 2. Run "Update PCB from Schematic" in KiCad - 3. Return to Phase 4 with the updated board file + 3. Return to Phase 3 with the updated board file (board + definition and design rules may need revision if footprints + or packages changed) --- From c64a69ba10d1595700773047a2a5622360d26acf Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Mon, 6 Apr 2026 14:07:51 -0700 Subject: [PATCH 5/6] Update applicable_to, separate verdict gate, conditional checklist 1. Updated applicable_to on pcb-layout-design (was []) and layout-design-review (was [review-layout]) to include design-pcb-layout, per CONTRIBUTING.md convention that applicable_to lists templates that always include the protocol. Removed standalone composition note from pcb-layout-design. 2. Separated template-specific PASS/FAIL verdict gate from the layout-design-review protocol steps. The verdict is a template addition, not part of the protocol itself. 3. Quality checklist items for USB differential pairs and antenna keepout zones were unconditional but not all boards have these. Added '(if any)' / '(if used)' qualifiers matching the style used in review-layout. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- protocols/analysis/layout-design-review.md | 1 + protocols/reasoning/pcb-layout-design.md | 6 ++---- templates/design-pcb-layout.md | 19 ++++++++++++------- 3 files changed, 15 insertions(+), 11 deletions(-) diff --git a/protocols/analysis/layout-design-review.md b/protocols/analysis/layout-design-review.md index dcc6b75..9527306 100644 --- a/protocols/analysis/layout-design-review.md +++ b/protocols/analysis/layout-design-review.md @@ -11,6 +11,7 @@ description: > placement, thermal design, and manufacturing constraints. applicable_to: - review-layout + - design-pcb-layout --- # Protocol: Layout Design Review diff --git a/protocols/reasoning/pcb-layout-design.md b/protocols/reasoning/pcb-layout-design.md index 6ca6d0b..817f83a 100644 --- a/protocols/reasoning/pcb-layout-design.md +++ b/protocols/reasoning/pcb-layout-design.md @@ -11,7 +11,8 @@ description: > and automated execution via Python pcbnew API with FreeRouting autorouter and KiCad DRC validation loop. Supports 2-layer and 4-layer stackups. -applicable_to: [] +applicable_to: + - design-pcb-layout --- # Protocol: PCB Layout Design @@ -23,9 +24,6 @@ for board setup and component placement, FreeRouting for automated trace routing, and `kicad-cli` for design rule validation. Execute all phases in order. -**Composition note**: This protocol is intended for standalone/manual -composition and is not currently required by any template. - **Input**: A completed KiCad schematic (`.kicad_sch`) with a netlist, component footprint assignments, and the component selection report from upstream phases. If footprints have not been assigned in the diff --git a/templates/design-pcb-layout.md b/templates/design-pcb-layout.md index 5f60e88..d1298c0 100644 --- a/templates/design-pcb-layout.md +++ b/templates/design-pcb-layout.md @@ -265,9 +265,13 @@ Apply the **layout-design-review protocol** in full: (Critical / High / Medium / Low / Informational), affected area, and remediation. Produce a coverage summary (phases checked, areas examined). -8. Conclude with an explicit audit verdict: - - **PASS**: No Critical or High findings; proceed. - - **FAIL**: Critical or High findings remain; must be corrected. + +**Template-specific verdict gate**: + +After completing the protocol review, conclude with an explicit +audit verdict: +- **PASS**: No Critical or High findings; proceed. +- **FAIL**: Critical or High findings remain; must be corrected. ### Transition Rules @@ -347,11 +351,12 @@ Before delivering artifacts in Phase 9, verify: - [ ] DRC passes with zero violations - [ ] All nets are routed (no ratsnest lines remaining) - [ ] Power trace widths are adequate for current loads -- [ ] USB differential pairs are length-matched and impedance- - controlled +- [ ] Controlled-impedance or differential nets (if any) are + length-matched and impedance-controlled as required - [ ] Decoupling capacitors are within 3mm of IC power pins -- [ ] Ground plane is continuous under signal traces -- [ ] Antenna keepout zones are respected +- [ ] Ground plane coverage (if used) is continuous under signal + traces where required +- [ ] RF/antenna keepout zones (if any) are respected - [ ] All components meet fab house minimum spacing - [ ] Board outline is within specified dimensions - [ ] Mounting holes are at correct positions From 7a1cee1adba85358d74278f6151b7f5ba44eb75b Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Mon, 6 Apr 2026 14:19:36 -0700 Subject: [PATCH 6/6] Add routing strategy phase and scope DRC fix loop MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. Phase 6 skipped protocol Phase 6 (Routing Strategy) — pre-routing critical nets, autorouter config, and ground/power strategy. Added as the first step before automated routing. Protocol reference updated to 'Phases 6, 8-9'. 2. DRC automated fix loop allowed placement changes without user approval, bypassing the Phase 5 gate. Scoped to routing and design-rule changes only. Placement changes now route back through Phase 4 -> Phase 5 for user re-approval. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- templates/design-pcb-layout.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/templates/design-pcb-layout.md b/templates/design-pcb-layout.md index d1298c0..c9322c3 100644 --- a/templates/design-pcb-layout.md +++ b/templates/design-pcb-layout.md @@ -223,22 +223,32 @@ in routing. **Goal**: Route the board and achieve DRC-clean status. -Apply the **pcb-layout-design protocol Phases 8–9**: +Apply the **pcb-layout-design protocol Phases 6, 8–9** in order: -1. **Run the Python script**: Execute placement, export `.dsn`. +1. **Define routing strategy** (protocol Phase 6): Pre-route + critical nets (USB differential pairs, crystal traces, analog + signals), set autorouter configuration and net priorities, and + establish ground/power routing strategy before automated routing. +2. **Run the Python script**: Execute placement, export `.dsn`. 2. **Run FreeRouting** headlessly: `java -jar freerouting.jar -de board.dsn -do board.ses -mp 20` 3. **Import routing result**: `pcbnew.ImportSpecctraSES(board, "board.ses")` 4. **Fill copper zones**. 5. **Run DRC**: `kicad-cli pcb drc -o drc-report.json --format json --severity-all board.kicad_pcb` -6. **Classify violations**: Clearance, unconnected nets, track +7. **Classify violations**: Clearance, unconnected nets, track width, courtyard overlap, edge clearance. -7. **Automated fix loop**: Adjust design rules or placement, re-run. - Maximum 5 iterations before escalating to user. +8. **Automated fix loop**: Adjust routing and design-rule settings + only, then re-run. If resolving a violation requires a component + placement change, stop the loop and return to Phase 4 for + updated placement, then Phase 5 for user re-approval before + resuming. Maximum 5 routing/design-rule-only iterations before + escalating to user. ### Transition Rules - **DRC clean** (zero violations): Proceed to Phase 7. +- **Placement change required**: Return to Phase 4, then Phase 5 + for user re-approval before continuing with Phase 6. - **DRC violations persist after 5 iterations**: Present remaining violations to the user with analysis (placement issue vs. routing issue vs. design rule issue) and ask for guidance.