PCB workflow

For installation, compatibility and public-release limits, read references/README.md and references/RELEASE.md. Licensing is in references/LICENSE; contribution guidance is in references/CONTRIBUTING.md.

1. Route the conversational request. Treat messages starting with the word pcb as this workflow (not a shell command). Use native model skill discovery; do not install a shell alias. Bare pcb: ask exactly "What should the board do? Describe its purpose and any power, connection, or size requirements you already know." Stop for the answer after quiet preflight. pcb <description>: extract all supplied facts and ask only consequential gaps. pcb modify <project> <change>: inspect and preserve existing work, then implement the change. pcb resume <project>: read requirements/status and resume the first incomplete stage. pcb reprice <project>: refresh eligibility, stock and Economic costs without changing CAD. pcb package <project>: validate saved design and produce/revalidate its release, without redesign except necessary fixes. Resolve paths with spaces from context; clarify ambiguous project selection. Done: mode, target and supplied facts are identified.

2. Load defaults and perform stage-specific preflight. Read references/environment.md and assets/defaults.json. On first use, initialize the human-editable ~/pcb-projects/pcb-defaults.json from that asset only if absent; inspect and preserve an existing file. Resolve precedence: explicit current task > existing project requirements > user defaults > bundled fallbacks. Merge nested settings; record effective settings in the project, never persist one-project overrides globally. Run python3 {baseDir}/scripts/pcb_helpers.py preflight <stage> for a diagnostic; inspect CLI help for actual needed operations. Check only dependencies needed now; install missing tools from verified official sources within available permission. Prefer working supported stable KiCad over upgrades. Read standards/templates under ~/pcb-projects/, especially standards/JLCPCB.md and templates/jlcpcb-2layer/; verify template is empty/general and rules correct. Done: necessary tools work or the exact blocker is documented; no real board is created during skill installation/testing.

3. Interview and checkpoint. Follow references/design.md and references/execution.md. Ask a small related group of unanswered consequential questions, not a technical questionnaire. Never guess critical voltage/current, polarity, battery chemistry, connector pinout, isolation/safety or mechanical fit. Offer defaults for noncritical choices; choose practical dimensions if unconstrained. Ask about factory programming when programmable devices are central; assembly does not imply programming. Create requirements.md and status.json before CAD; record requirements, assumptions, overrides, unresolved questions, stage/completed/pending/blockers, saved artifacts, validation and next action. Done: critical requirements are resolved, architecture/calculations recorded, consequential unresolved choices confirmed.

4. Verify sourcing and libraries. Read references/design.md; research authoritative manufacturer documents and current JLCPCB assembly catalog. Verify every distinct MPN, package, rating/derating, pinout, LCSC, service-specific stock/classification, price tiers, MOQ and attrition. Prefer suitable Basic/current fee-waived parts; never quietly relax sourcing or change assembly service. Maintain components.csv with all fields in the reference. Prove function → symbol pin → footprint pad → physical terminal; document physical polarity markings and view. Standard library names alone prove nothing. Package custom libraries/tables locally. Done: each fitted part is verified or explicitly blocked, with sources/timestamps and no invented identifiers or availability.

5. Create or modify editable CAD. Inspect open editor state and existing files before external edits. Make a verified backup/checkpoint before consequential changes. Use validated template for suitable new projects; no demonstration circuitry. Follow architecture, create full schematic/support circuitry, annotations, footprints and fields. Use deterministic supported APIs/CLI where reliable; use GUI for useful CAD editing/visual checks. Preserve correct existing work. Route and place per references/design.md; refill zones. Use one computer-control owner; follow busy recovery in references/environment.md. Done: saved schematic/PCB/libraries open correctly, routing complete and metadata coherent.

6. Independently verify design and eligibility. Run installed kicad-cli sch erc and pcb drc, using supported failure-on-violation, all-severity and schematic-parity flags; read actual reports. Target zero errors, unexplained warnings and unintended unconnected items; justify intentional exceptions, never hide them. Independently inspect electrical calculations, geometry, pinouts, polarity, mechanical fit, mask/paste/silk, thermal/return paths and generated-view consistency. Verify current Economic PCBA eligibility before final layout commitment and again before release. If ineligible explain why and ask before consequential redesign/service change; Economic pricing stays unavailable unless explicitly overridden. Done: saved evidence supports design status; prototype-only tests and all remaining uncertainties are named.

7. Automatically generate local manufacturing deliverables. Read references/release.md and references/costs.md; for authorized supplier/cart work follow references/supplier.md. Successful design validation authorizes local exports and packaging without another permission request. This invocation supplies explicit local-generation authorization where older standards say "unless explicitly requested"; do not silently overwrite standards. Supersede any inherited process gate that requires supplier upload before local candidate generation: preserve polarity checks and gate final order/production instead. Never bypass an unresolved actual orientation problem. Generate a versioned manufacturing/<release>/ using installed, help-verified KiCad export commands. Check generated Gerbers/drills/BOM/CPL/PDF, not just source files. Separate local readiness from the later supplier preview; no claim of a preview that was never accessed. Done: verified artifacts, editable source archive, manifests/checklist and clear READY FOR JLCPCB UPLOAD / REVIEW REQUIRED / BLOCKED status exist.

8. Recheck stock and price the requested scope. Follow references/costs.md: MINIMUM/MIDDLE/MAXIMUM of verified valid Economic assembled-finished-board quantities, midpoint tie goes lower. Keep these default comparisons Economic-only; explicit requested quantities/services override the report scope as specified in the reference. Never redefine service maximum by stock. Use same design/BOM/options; distinguish fabricated/assembled/panels. Include quantity breaks, MOQ/attrition, all predictable fees; unknown is not zero. Prefer live quote only with authorized upload/access; otherwise supported public estimate with limitations. Run cost helper only on verified inputs; do not treat it as a live quote engine. Done: CSV/readable costs with sources, currency, timestamp, quote/estimate, unknowns, exclusions and stock limits are included.

9. Package, deliver and persist. Use references/release.md final response structure. Include fabrication ZIP and separate BOM/CPL inside a complete delivery bundle, source/libraries, reports and evidence. Verify ZIP contents/hashes and paths, exclude credentials/backups/cache. Deliver actual attachments or confirmed accessible paths/retrieval method. Missing Git identity leaves commits pending, not design blocked; never invent author identity or publish without authorization. For authorized GitHub delivery and first-ordered snapshots follow references/github-delivery.md. Update status/checkpoint at each durable stage and on failure. Inspect failure and preserve partial artifacts; resume rather than duplicate long failed runs. Done: the user has real files and accurate limitations. Local work/research/export are authorized; uploading private files/BOM, publication, orders, payment and chargeable reservations require separate explicit authorization.

Helpers and validation

Read scripts/pcb_helpers.py --help via Python; the script provides read-only stage preflight, verified backup, BOM/CPL reference cross-check, deterministic Economic quantity/cost calculation and safe ZIP packaging. It does not design, quote live, verify electronics or upload. Run python3 {baseDir}/scripts/test_helpers.py after helper changes. Consult references/validation.md for dry-run fixtures and installation coverage. Use the configured capable model; delegation only through supported tools when appropriate, never invented model IDs or claimed billing savings from tool choice.