Flow Guide

---
name: flow-guide
description: "Methodology guide for the zero-hardware, simulation-only PCB + firmware seven-step workflow (does NOT drive execution). Use when the user asks about this workflow, asks why one of its steps works the way it does, or starts a no-hardware hardware project — in that last case route them to the step skills instead of executing steps yourself. Triggers on: zero-hardware PCB workflow, simulation-only bring-up, 无实物开发, 零硬件开发, 全仿真做板, 零实物打样. Do not trigger on ordinary PCB questions unrelated to this workflow."
---

# Flow Guide (explains, never executes)

This skill answers "what is this workflow and why is it designed this way".

**Execution is driven exclusively by the user invoking the step skills, one step per session.** You (the model) must not advance any step without its skill being invoked, must not decide to enter the next step on the user's behalf, and must not skip ahead just because the user says "continue". User wants to start → point them to **step1-onboard** (Claude Code: `/boardless-pcb:step1-onboard`); user lost track → **status** (Claude Code: `/boardless-pcb:status`).

**Language**: always interact in the user's language, and generate project documents in the user's language. Only the flow-state status tokens stay as canonical English strings (see below) so any later session can parse them reliably.

## The seven steps

```
1  onboarding (context interview → dev plan → toolchain → state init)
2  firmware skeleton, freeze the pin map   ← firmware exists here to produce pin constraints
3  schematic design (incl. component selection)
4  placement                               ← hard gate: board outline/structure is the user's call
5  routing
6  per-module simulation verification      ← amnesia subagent; autonomous local-fix loop
7  full firmware integration               ← closing hard gate: human visual inspection
```

One skill per step: `step1-onboard` … `step7-integrate`, plus `status` to locate yourself from any new session. On Claude Code they are invoked as `/boardless-pcb:<name>`; on Codex as `$<name>`; on Cursor as `/<name>`.

## Why one step per session

- **Self-sufficient deliverables are the goal; fresh sessions are the means.** Every command rebuilds context exclusively from files on disk (`docs/flow-state.md` + the previous step's deliverables), never from conversation memory. If the next step cannot start from disk alone, the previous step's deliverables were incomplete — exposed immediately.
- **Session boundaries follow "entering a step", not step numbers.** Step 6 is the structural exception: once entered, the verify → autonomous-fix → re-verify loop stays in one session. Context purity is carried by the amnesia subagent's mechanical isolation (every re-verification is a brand-new instance), not by session boundaries. Only **structural rework** (board outline / assembly mode / layer count — requires user approval) moves to the corresponding step command in a new session.

## Single source of truth for state

`docs/flow-state.md` (steps table / open-issues table / verification-rounds table), maintained by the commands, is the only cross-session handoff. Shared numbers need a single owner — that discipline applies to flow state itself.

Canonical machine-parsed values (English regardless of the user's language) — step status: `not-started / in-progress / done / rework / waiting / parked` (`waiting` = blocked on upstream work, resumes without interrogation; `parked` = deliberately stopped by user decision, not fab-ready); issue status: `open / fixed-pending-verify / closed / deferred`; issue severity: `nondeferrable / major / minor`; issue target step: `2` `3` `4` `5` `step6`; plus the flow-state header line itself, which is how commands recognize the file.

**Rework-log numbering** (one convention, both halves of the flow): `docs/rework-log-N.md` — **N is the verification round that will VERIFY these fixes**, never the round that found them. Steps 2–5 fix modes and step 5's in-loop self-help journal: N = last row of the verification-rounds table + 1. Step 6's in-loop fixes: N = the re-audit round that pass opens (current round + 1). The orphan-fix scans reconcile against these files, so a drifting N breaks re-entry.

## Three human gates (the AI must never wave itself through)

1. Before step 4: board outline / component side / orientation (enclosure decisions belong to the user)
2. During step 6: module table + per-module verification plan review (execution starts only after user confirmation)
3. Before fab-out: silkscreen and routing visual inspection

## Rollback rule (hard rule, enforced by a hook)

Hardware design problems found in steps 6/7 must be fixed upstream in steps 2–5, on the hardware side; compensating, loosening, or masking in firmware, tests, or reports is forbidden. Structural decisions (board outline / assembly mode / layer count) belong to the user at **every** discovery point — placement, routing, and verification each escalate when they hit one; they differ only in machinery (steps 4–5 ask in-session since the user is present; step 6 parks and batches since its loop is autonomous). (At step 7 the priority inverts: bugs default to firmware attribution and firmware-side fixes are exhausted first — that step's own job — and only evidence-backed hardware defects hand off to step 6.) Local fixes run **autonomously** inside the step-6 session without consulting the user (bounds: no structural decisions, no layer-count change, no swapping "do-not-substitute" parts, no breaking top-priority budget lines; rejected candidates must be logged). Only when local options are exhausted does it escalate to structural rework, which **requires user approval**. A fix counts as resolved only after re-verification by the amnesia subagent.

**Ledger rule**: issues being worked inside step 6 are NOT written to the flow-state issues table — unfixed problems resurface on the next amnesia audit anyway, while stale entries would misroute the user back into upstream fix modes after an aborted session. The issues table only holds: user-approved structural rework (only then does an entry get a target step), deferred items, step-7 integration handoffs (target step6), and user-confirmed step-7 release findings (target 2–5). The working record lives in the verification files and rework logs (including rejected candidates).

## About process bookkeeping

The flow does **not** require decisions/prompts style bookkeeping files — those were the author's instruments for distilling this plugin, not necessities for building a board. **Do not proactively ask users to create them.** All required state lives in `docs/flow-state.md`, the rework logs, and each step's deliverables. Users who want to suggest improvements to this plugin should use whatever channel they prefer (repo issues/PRs).

## Answering "why" questions

The step commands are self-contained and carry their own rules inline. When the user asks why a rule or a step is shaped the way it is, answer from this guide and the commands themselves; design-decision history lives in the repo's CHANGELOG.md.