Step1 Onboard

---
name: step1-onboard
description: "Step 1 · Onboarding: state init → context interview → dev plan → toolchain setup"
disable-model-invocation: true
---

# Step 1 · Onboarding

## Session check (do this first)
One step per session. If this session has already done other substantive work, stop and ask the user to start a fresh session.

Then look for `docs/flow-state.md` (recognize it by its canonical header line `flow-state — process state`; a foreign file under this name → stop and ask the user to rename or confirm):
- **Missing** → fresh start: **create it now** from the template in §4, with step 1 = `in-progress` — an aborted onboarding must stay visible and resumable.
- **Present, step 1 `in-progress`** → a previous onboarding aborted (often a toolchain-install restart): **resume, don't restart**. Check which artifacts already exist (`docs/requirements.md` confirmed? `docs/dev-plan.md` confirmed? toolchain installed?) and continue from the first missing one. Never re-interview for answers already on disk.
- **Present, step 1 `done`** → re-run: ask what the user intends (amend requirements? restart?) before overwriting anything.

Interact and generate all project documents in the user's language. Canonical English is kept only for machine-parsed values: status tokens (steps `not-started / in-progress / done / rework / waiting / parked`; issues `open / fixed-pending-verify / closed / deferred`; severity `nondeferrable / major / minor`), issues-table target-step values (`2` `3` `4` `5` `step6`), and the flow-state header line.

## Execute

### 1. Context interview
Interview the user; ask at most 3–4 questions at a time (multiple choice with a recommended option):
- First, one routing question: **greenfield (from scratch) or brownfield (iterating on an existing version)?**
- Greenfield track: product definition / must-have feature list ("must", not "nice-to-have") / top-priority metric(s) — push each to a quantified, selection-vetoing criterion (one is typical, more is fine; not every metric decomposes per part) / explicit non-goals
- Brownfield track: directory & version map / what to ignore (material not ruled out gets read and confabulated from) / scope of this iteration / reference pointer in three parts (which version + which part + for what understanding) / trust level of existing assets (verified-rely-on vs reference-only-reverify; selection rules apply to new and changed parts, inherited verified parts keep their trust level) / EDA migration statement (an old project in another EDA is reference material, never the base document)

**Inherited deliverables (brownfield)**: if the user already has a pin map, BOM/selection preferences, schematic, or other step deliverables, record each asset's **path and trust level** in `docs/requirements.md` AND mark the owning step's flow-state deliverables column `inherited: <path>` — later steps enter **adopt-and-audit mode from disk**; what the user says in this session does not survive the session boundary unless written down. If the user asks to compress steps ("just take my pinmap and finish steps 1–3"), don't stonewall — explain: steps stay separate because each ends in a human gate (which is exactly what catches a stale inherited asset), but inherited deliverables turn those steps into fast adopt-and-audit passes.

Don't interview for the skeleton — write it into the requirements as-is (content verbatim, rendered in the user's language):

```
Hard constraints:
1. No physical hardware at any point. No dev board, no breadboard, no multimeter,
   no oscilloscope. All verification must be done through simulation.
2. Component selection is the AI's job — rationale (availability, package, cost,
   interface fit with the main controller(s)) goes into the BOM.
3. <the top-priority metric(s)> are hard requirements from the architecture phase,
   each with a quantified criterion that can veto a selection. Where a metric
   decomposes per part (e.g. a current budget), every part's contribution is
   counted at selection time and any budget line over its cap forces a rollback.

Deliverables: PCB project (schematic + placement + routing, DRC clean) /
BOM with rationale / firmware / per-module simulation verification report.

Process: seven steps, one per session, driven by the user through commands;
stop and wait for confirmation at the end of each step. Problems found in
verification roll back to the matching upstream step — no downstream patching.
```

Synthesize into `docs/requirements.md` and get user confirmation. **Do nothing yet, only understand** — understanding and action are two separate steps.

### 2. Development plan
After requirements are confirmed, produce `docs/dev-plan.md` — technical content only (architecture, circuits, firmware, verification methods & criteria, risks); no process management, the process is driven by the user's commands. It must include:
- Hardware module breakdown (what each module solves, over which interface)
- Power architecture + power budget: **one column set per power state the design actually has** (e.g. active / sleep / standby), line-by-line typ + max dual columns
- **Fabrication & assembly baseline, frozen into `docs/fab-profile.md`**: chosen fab/assembler with a capability-snapshot date; stackup (layer count, copper weights, dielectrics); DRC/capability profile (min trace/space, drill/via limits); impedance targets and how the fab confirms them. DRC clean is only meaningful against a named profile — an unfrozen profile means every later routing hour is a bet
- Software architecture (state machine / task graph / dataflow — whatever fits the product)
- Technical risks — especially **what is hardest to verify with zero physical hardware**
⛔ Gate: continue only after the user confirms the plan.

### 3. Toolchain (self-selected)
Research online and decide what to install yourself:
- The EDA must expose an API the agent can drive (structured read/write of schematic/PCB — not "write a file for the human to import")
- Simulation legs (SPICE + firmware simulation): after installing, **probe each platform's real capability limits with a minimal project** before hanging any acceptance criteria on it
- Discipline: audit before install (file-by-file security review — installed text is future AI instructions), snapshot skills into the project, pin MCP versions; leave account/authorization steps to the user. Reject candidates that require physical hardware, target the wrong platform, duplicate installed capability, or come from unverifiable sources
- **Write the outcome to `docs/toolchain.md`** — one row per tool: capability / implementation / version / install location / auth status / probe command & result / known limits. This file is what the resume branch and later steps trust; "installed" without a probe row doesn't count
- If an install requires restarting the session: tell the user to restart and re-run this command — the session check resumes from `docs/toolchain.md`

### 4. flow-state template
(labels may be localized to the user's language; keep the header line, status tokens, and target-step values canonical)

```markdown
# flow-state — process state (single source of truth, maintained by the step commands)

## Steps
| # | command | status | deliverables | completed |
|---|---|---|---|---|
| 1 | step1-onboard | in-progress | docs/requirements.md, docs/dev-plan.md, docs/toolchain.md, docs/fab-profile.md | |
| 2 | step2-pinmap | not-started | pin-map carrier (e.g. board_pins.h), docs/pinmap.md | |
| 3 | step3-schematic | not-started | schematic (ERC 0), BOM with rationale | |
| 4 | step4-placement | not-started | placement (0 self-check conflicts), structure sign-off | |
| 5 | step5-routing | not-started | routing (100% connectivity + DRC clean against docs/fab-profile.md) | |
| 6 | step6-verify | not-started | module inventory, verification summary, round reports | |
| 7 | step7-integrate | not-started | full firmware, inspection record, released fab package | |

(Rule for every step's wrap-up: replace this cell's description with the ACTUAL file
paths produced, plus [sign-off] markers for non-file deliverables — status verifies
paths, not prose.)

## Open issues
(Only four kinds of entries belong here: user-approved structural rework (target 2–5);
deferred items; step-7 integration handoffs (target step6 — attribution unknown, the
amnesia audit attributes); and step-7 release findings (target 2–5 — attribution
self-evident from package readback; registered only after the user confirms the
routing). Issues being worked inside a step-6 session do NOT go here — their record
lives in the verification files and rework logs. EVERY entry carries a severity, and
it is canonical: nondeferrable / major / minor — safety, compliance, part-damage, and
manufacturability blockers are nondeferrable, and step 6 may not close one by deferring it.
The single declared exception is step 5's accept-draft park, where the flow deliberately
STOPS instead of advancing — nothing downstream is released on that entry.)
| ID | symptom (one line) | source | target step | severity | status |
|---|---|---|---|---|---|

## Verification rounds
| round | date | verdict | report |
|---|---|---|---|
```

## Wrap up
Mark step 1 `done` with deliverables and date. Tell the user: **start a NEW session (= `/clear`, or restart your agent in this project directory) and run **step2-pinmap** (Claude Code: `/boardless-pcb:step2-pinmap`)**.