hardware-flow

What this skill does

# Hardware Flow -- Pipeline Orchestrator

## Design Principle: Hardware Team Delivery with Validation Gates and Physical-World Integration

This skill is the ORCHESTRATOR. It coordinates the hardware delivery team through a
structured 8-stage pipeline but NEVER produces domain artifacts directly. All domain
work -- requirements, schematics, layout reviews, DFM reports, compliance packages,
test procedures -- is delegated to worker skills that operate as sub-agents with
isolated context.

> **Disclaimer -- AI Scope Limitations**: This pipeline coordinates AI-assisted design
> review and documentation. It does NOT replace physical testing, lab measurements,
> certified compliance testing, or professional engineering sign-off. Human-execution
> stages (Prototype, Pilot Run, Production Release) require physical work that AI
> cannot perform. All compliance outputs are pre-compliance assessments only -- formal
> certification requires accredited test labs.

### Core Principles

1. **Delegation, not execution (Prime Directive).** The orchestrator manages flow,
   routing, and validation. Worker skills (hw-product-owner, electrical-engineer,
   pcb-layout-engineer, manufacturing-engineer, compliance-engineer, test-engineer)
   produce ALL domain artifacts. Workers are invoked as sub-agents using the Agent tool.

   **The orchestrator NEVER writes domain content.** This is non-negotiable.
   Explicit anti-patterns (any of these is a Prime Directive violation):
   - Writing a requirements doc, schematic review, DFM report, compliance analysis,
     or test procedure with Write or Edit because "it's simple"
   - Drafting a short artifact inline and saving it to skip an Agent dispatch
   - Writing a compound prompt that asks one sub-agent to act as multiple roles
     (see "One Role = One Sub-Agent" below)
   - Collapsing two review passes into one by pasting prior findings into
     the next reviewer's prompt
   - Forwarding artifact content (not paths) between sub-agents through the
     orchestrator

   The orchestrator's ONLY write paths are `.hardware/state.md`,
   `.hardware/state.tmp.md`, `.hardware/config.yml`, `.hardware/memory/**`, and
   `stage-summary.md` files under each stage namespace. Everything else is
   produced by a dispatched sub-agent.

2. **Multi-perspective validation.** Every artifact is validated by MULTIPLE roles
   (Team Definition of Done) before a stage gate passes. No single perspective gates
   quality -- the team decides collectively.

3. **Self-correction with bounds.** When validation fails, the pipeline corrects itself
   by routing feedback to the responsible agent. Every correction loop has a counter
   (max 3 iterations) to prevent infinite cycles.

4. **Dynamic escalation.** Escalation to the human can happen at ANY point -- not just
   at scheduled checkpoints. Low confidence, repeated failures, deadlocks, and
   cross-cutting conflicts all trigger escalation immediately.

5. **Learning from every run.** The pipeline writes memory files after every execution
   (including aborts). Past lessons are loaded at the start of each run and passed to
   agents as context, so the pipeline improves over time.

6. **Human-physical integration.** Three stages (Prototype, Pilot Run, Production
   Release) involve physical work that AI cannot perform. The pipeline prepares
   documentation, pauses for human action, then validates results on resumption.

7. **Context isolation.** Worker sub-agents receive ONLY the upstream artifacts and
   lessons relevant to their task. The orchestrator selects the relevant subset --
   agents do not see the full pipeline state.

8. **kicad-happy consumption, not reimplementation.** Hardware roles invoke kicad-happy
   skills for component sourcing, fabrication validation, analysis, and documentation.
   The orchestrator does NOT invoke kicad-happy directly -- role skills own that decision.

---

## Phase 0: Setup Wizard

Before the pipeline executes, check for project configuration:

### State Detection (Resume Check)

Before checking config, check for an existing pipeline state:

1. **Check for `.hardware/state.md`** in the current working directory.
2. **If state exists with `status: in_progress` or `status: paused`**:
   - Read the YAML frontmatter to load pipeline state.
   - Announce: `> Existing pipeline found: [pipeline_id], started [date], last completed Stage [N] ([name]). Currently at Stage [N+1].`
   - **Validate**: verify all artifact files in the `artifacts` map exist on disk. If any are missing, announce which and offer: Restart from that stage / Abandon.
   - **Semantic validation**: current_stage in range 1-8, not in stages_completed, no gaps in completed+skipped.
   - **Config divergence check**: compute SHA-256 of current `.hardware/config.yml` and compare against `config_hash` in state. If different, warn: "Config has changed since this pipeline started. Resume uses the original config snapshot. Choose Restart to apply new config."
   - Offer the user: **Resume** / **Restart** / **Abandon**
   - Resume: load config from snapshot file, skip completed stages, start at current_stage.
   - Restart: archive state file to `.hardware/archived/state-<timestamp>.md` (cap at 5, delete oldest), start fresh.
   - Abandon: delete state file, no pipeline runs.
3. **If state exists with `status: paused_dispatch_error`**:
   - Announce: `> Pipeline paused due to dispatch error at Stage [N]. Error: [error_type].`
   - Offer: **Retry** / **Restart** / **Abandon**
4. **If state exists with `status: aborted`**:
   - Announce: `> Aborted pipeline found from [date], stopped at Stage [N]. Artifacts from stages [list] are preserved.`
   - Offer: Resume / Restart / Abandon.
5. **If state exists with `status: completed`**: ignore (previous run finished normally).
6. **If no state file exists**: proceed to config check (normal flow).

### Config Check

1. **Check for `.hardware/config.yml`** in the current working directory.
2. **If config exists and is valid**:
   - Read the YAML configuration to load all project settings.
   - **Version check**: Compare `schema_version` to the current schema version (v1.0).
     If the config uses an older schema, apply defaults for missing keys and announce:
     `> Config upgraded from v[old] to v[current]. New settings applied with defaults: [list]`
   - Announce: `> Config loaded from .hardware/config.yml (v[version])`
   - Apply settings: target_fab, compliance_regions, bom_budget, production_volume,
     board_layers, rework limits, gate_strictness, review config.
   - For any key missing from the config, use the default from `references/config-schema.md`.
   - Proceed to Phase 1.

3. **If config exists but has invalid fields**:
   - Warn per-field with expected type/values. Use defaults for invalid fields.
   - Never fail the pipeline due to config errors.

4. **If no config exists**:
   - **STOP. Do NOT proceed to Phase 1.** The setup wizard MUST run before the pipeline can execute.
   - Run the setup wizard. Reference `references/setup-wizard.md` for the full protocol.
   - The wizard asks 9 questions sequentially:
     - Q1: Project name
     - Q2: Target fabrication house (jlcpcb / pcbway / other)
     - Q3: Target compliance regions (FCC, CE, UL, none)
     - Q4: BOM budget target (USD per unit, or no limit)
     - Q5: Production volume target (prototype / small-batch / production)
     - Q6: Board layer count (1 / 2 / 4 / 6 / 8+)
     - Q7: Minimum kicad-happy version (default: >=1.2.0)
     - Q8: Rework iteration limit per path (default: 3)
     - Q9: Total rework limit per pipeline run (default: 10)
   - Generate `.hardware/config.yml` with schema_version: "1.0"
   - Create directory structure: `.hardware/`, `.hardware/memory/`, `.hardware/artifacts/`
   - Validate config against schema
   - After the wizard completes, `.hardware/config.yml` MUST exist before proceeding.

5. **User can re-run the wizard at any time** with the `hw-setup` command.

### Quic