CircuitSmith forges schematics. PartsLedger keeps the record CircuitSmith reads.
CircuitSmith generates circuit schematics from declarative YAML, validates them against electrical rules, and exports both a bill of materials and a KiCad-compatible netlist — all driven by a Claude Code skill so that contributors describe what they want in natural language rather than writing Schemdraw code.
Status: concept stage. The full design dossier was copied from
AwesomeStudioPedal's IDEA-027
companion files, archived on conversion to EPIC-001..006, and now lives in
docs/developers/ideas/archived/idea-001-circuit-skill.md.
Predecessor artefacts the dossier references —
scripts/generate-schematic.py,
data/config.json,
docs/builders/wiring/ —
live in that repo, not here. Implementation has not started.
The project this skill grew out of generates schematics from hand-authored Python (Schemdraw). Adding a sensor means knowing Schemdraw's API. There is no validation that the drawn circuit is electrically safe, no machine-readable component list, and no path from the diagram to PCB tools.
CircuitSmith answers four questions the current pipeline cannot:
- How does a contributor add a sensor without learning Schemdraw or electronics?
- How does a reviewer know the circuit is electrically sound without reading code?
- Where does the shopping list come from?
- How does the schematic feed a PCB tool when IDEA-011 starts?
A single .circuit.yml is the source of truth. The pipeline emits:
| Artifact | Purpose |
|---|---|
main-circuit.svg |
Schematic, rendered via Schemdraw |
erc-report.md |
Electrical rule check findings, with rationale + source links |
bom.md / bom.csv |
Bill of materials |
main-circuit.net |
KiCad-compatible netlist |
meta.yml |
Layout provenance + readability rubric scores |
.circuit.yml
→ schema validation (rejects unknown components / pins)
→ ERC (structural S1–S3 + electrical E1–E10)
→ layout kernel (canonical-slot placement)
→ Manhattan router (wire geometry)
→ Schemdraw render (SVG emission)
→ rubric + meta.yml (readability scoring + sidecar)
ERC runs strictly pre-layout: a malformed circuit never reaches the router.
Status: the architecture below describes the target state. None of the product code exists yet — Phase 1 (EPIC-001) starts the scaffolding. Today the repo holds only the design dossier and the task-system infra.
Everything ships inside .claude/skills/circuit/ — a self-contained,
path-agnostic Claude Code skill. The same directory is the library that
the CI script imports, so there is no duplication between "the skill" and
"the project's generator".
Key decoupling: bom_exporter.py walks components directly;
netlist_exporter.py walks NetGraph. They never reach into each other.
The one-page top-down view, including the pipeline mermaid, module
boundaries, component table, decoupling seams, AI-containment property,
and ADR cross-references, lives at
docs/developers/ARCHITECTURE.md.
The skill instructs Claude to act as an electronics engineer who:
- Resolves all component types from
components/— never invents pin names. - Writes and edits YAML, not Python.
- Enforces layout conventions (signal left → right, VCC top, GND bottom).
- Applies best practices grounded in the rule catalog — every default traces back to a
source_of_truthlink; no free-form runtime generation of hardware rules. - Batches ambiguous-pin questions into a single message rather than looping.
- Runs ERC before declaring a circuit done.
- Can add new component profiles and reports which ERC checks they activate.
Phase 0 Project bootstrap (pyproject.toml, pytest config, CI workflow)
Phase 1 Component library + schema
Phase 2a Renderer + v0.1 deterministic kernel + cutover from legacy generator
Phase 2b AI placer (contingent on observed kernel-failure modes)
Phase 3 ERC engine + rule catalog
Phase 4 BOM + netlist exporters
Phase 5 Markdown ``` ```circuit ``` ``` integration
Phase 6 The Claude Code skill itself
Phase 7 Extract `.claude/skills/circuit/` into a standalone repo
Phase 0 (EPIC-007) is a hard prerequisite of Phase 1 — the prose-only dependency declaration in the skill-packaging dossier becomes machine-readable, the test runner gets configured, and CI gets a workflow, all before EPIC-001 produces real Python code. Phases 1–7 then follow the staging described above.
Phase 2b is gated on real failure data, not a calendar — the v0.1 kernel ships first and stays in production until concrete escalations justify the AI placer. See the phase plan for prerequisites and acceptance criteria.
| Audience | Where |
|---|---|
| Users — tutorial and example gallery | docs/users/ |
| Builders — per-target wiring artefacts (BOM, netlist, SVG) | docs/builders/ |
| Developers — architecture, ADRs, task system, ERC internals | docs/developers/ |
Each module has its own companion specification:
| Companion | Covers |
|---|---|
| Skill packaging | SKILL.md frontmatter, dependencies, layout, install paths, acceptance tests |
| YAML format | pins / path / bus connection forms, schema validation |
| Layout engine | Slot vocabulary, kernel, incremental placer, rubric, sidecar, CI contract |
| ERC engine | Three-level config, structural + electrical checks, report format |
| Rule catalog | Format, licensing, 30–50-rule scope, authoring workflow |
| Components | Profile format, pin aliasing, adding a component |
| Exporters | BOM markdown/CSV, KiCad .net flattening rules |
| Project | Relationship |
|---|---|
| PartsLedger | Parts inventory; CircuitSmith reads from it |
AwesomeStudioPedal — IDEA-027 |
Spiritual predecessor; CircuitSmith generalises that idea |
| IDEA-011 (PCB design) | Consumes CircuitSmith's .net file as the KiCad seed |
| IDEA-022 (MkDocs site) | Renders circuit blocks via pymdownx.superfences |
- Audio signal conditioning (no analog path in the current target).
- Title block / branding overlay inside the SVG.
- PNG conversion as a dedicated pipeline step.
- General-purpose auto-layout (force-directed, hierarchical, etc.).
- An in-repo electronics textbook — the rule catalog links out for theory.
- Runtime LLM generation of hardware rules. The catalog is authoritative; the LLM is only used to understand the maker's natural-language request.
See CONTRIBUTING.md for the first-time-setup steps —
in particular bash scripts/install_git_hooks.sh to install the
pre-commit wrapper and the security-review hooks
(pre-merge-commit, post-merge, pre-rebase) that scan incoming
changes from pulls/merges/rebases.
Participation is governed by the project Code of Conduct.
MIT (planned, alongside the standalone-skill repo in Phase 7).