New edakit project¶

A source

This page is a source of edakit – a concept, a prompt or the rules of a session –, shown as it is in the repository. Read it as such; the guides say what edakit does.

Set up an edakit project in the current repository from an interview instead of the example's defaults – a new project, or one that moves to edakit with hardware files, scripts or agents of its own (then first the inventory by the agents project-surveyor and requirements-engineer, and the interview with their proposals as answers to confirm). Asks for boards, bought boards, the schematic's drawing, variants, the maker, assembly, order, money, purpose, requirements, firmware, documents and the project's own tools, proposes every file and key with its reason and writes edakit.toml, graph, parts, simulation config, board file, sign-offs, decision log, git hook, CI and Claude Code settings only after the user's OK. Use when the user starts a new board ("new PCB", "set up edakit", "use the EasyEDA workflow here") or a project without edakit.toml moves to edakit ("move this project to edakit").

Project: $ARGUMENTS. The approach and why: ${CLAUDE_PLUGIN_ROOT}/handbook/01-approach.md; every key: 10-reference.md (10.1). A complete small example to copy from: ${CLAUDE_PLUGIN_ROOT}/tests/fixtures/led-bar/ (shipped with the plugin); a real one, taken through EasyEDA to the gate, with variants: https://github.com/tgd1975/automatic_christmas_bell. Where the session does not find edakit on the PATH, it is ${CLAUDE_PLUGIN_ROOT}/bin/edakit.

You set the project up the way this project needs it: every file and key from an answer, none left at the example's value unasked. You propose each with its reason and write only after the user's OK – no silent change. You delete none of the project's own skills or agents; a file of the project you change or remove – its hook, an MCP server of its own – is a proposal like any other.

0. Which way¶

The repository has	Way
no `edakit.toml` and no hardware of its own	new: the interview (section 2), then the files
no `edakit.toml`, but hardware files, scripts or agents – a graph or netlist, parts, a board, gate runs, `.claude/agents/`, scripts that drive EasyEDA	moving: the inventory first (section 1), then the interview with its proposals as answers to confirm, then the files
an `edakit.toml`	not this skill: the project is set up – `edakit check 2>&1 \\| cat` shows where it stands, and a key it lacks is a change of its own (handbook 10.1)

One repository per project – a project spread over several repositories is not covered; say so and set up the one at hand.

1. Inventory (moving)¶

Two agents, each in its own context and side by side – both change nothing:

project-surveyor – its prompt: "inventory", the repository, what the user said about the project. It returns numbered lists per place – hardware data, the EasyEDA project and released runs, scripts, agents, skills, documents with values, decisions, guard rails, the interview's answers, the documents with requirements – each candidate with where it was found, the proposal and its reason; at the end the contradictions, what it could not read and a count per place.
requirements-engineer – its prompt: "inventory", what the user wants, the documents with requirements (the surveyor names them; start both at once with the ones you know). Its candidates are for the skill requirements (section 5), which starts from this inventory instead of making it again.

Read both before the interview. Each contradiction is a question of the interview, never resolved silently.

2. Interview¶

All topics in one round, in the order of the table. Where the tool offers a form – in Claude Code AskUserQuestion, up to four questions per call – ask with it: the table's options as the choices, the recommended one first, the user's own words for everything else; the names and numbers below as free text. Otherwise one decision round in text (skill decision-round): one numbered item per topic with the options as a, b, c, the recommendation first. Leave out what an earlier answer makes moot: assembly and order without a PCB.

New: the recommended option is what the user already said, else the first of the table.
Moving: the recommended option is the inventory's answer, its source in the option's text ("found: docs/order.md – Economic, top side"); a confirmation is enough. Where the inventory found two answers, both are options with their places.

Topic	Question	Options – the first is the default	What it sets
board	A PCB, or a development board with wiring?	a PCB · a development board with wiring, no PCB	with a PCB `[boards.<name>]` with its EasyEDA documents (`template`, `schematic`, `pcb`, `file`, named after the board) and the board file; without one only a `title`, no board file and no EasyEDA (section 5)
tool chain	Drawn in EasyEDA Pro or in KiCad? (only with a PCB)	EasyEDA Pro – the default: the tool chain edakit was built on, JLCPCB's library, the project created once by hand · KiCad 10 – the other choice: open files, no bridge and no click, no noncommercial licence in the chain (handbook 16.1)	`[project] toolchain`: without the key EasyEDA; `"kicad"` – every board a KiCad project edakit writes, no EasyEDA document names in `[boards.<name>]`, no EasyEDA project to create by hand (handbook 16)
boards	How many boards? Which are made, which bought on a cable, which wired by hand?	one made board · several made boards · besides, a bought board on a cable (a breakout, a module in the enclosure) · parts wired by hand without a PCB (a front panel's LEDs, footswitches, jacks, pots, a strip on a cable)	one `[boards.<name>]` each; `bought = true` for a bought one, `wired = true` for a hand-wired one – no `template`, `schematic`, `pcb` or `file` (handbook 4.5)
drawing	How is each board's schematic drawn – with labels, or every connection a wire?	labels – stubs and net flags, for a board of any size · wires through – every connection a wire, for a maker-size circuit or a hand-wired board · mixed – wires, labels for the pass-throughs and buses, for a module with headers	`style` in `hardware/schematic.toml`: one word for every board, a table by board where they differ (`style = {main = "labels", panel = "wires"}`); written for `"labels"` too, so the file records that it was asked. The SVG of `edakit schematic draw` only – EasyEDA's and KiCad's schematics keep their labels (handbook 6.5, 10.3)
variants	Several builds of one circuit – another MCU, SMD or through-hole, assembled or not?	one build · several builds	per further build a project of its own, `variants/<v>/edakit.toml`, with its own graph, parts, simulation config, board file and sign-offs, its own board in the same EasyEDA project, reading the main project's files – the requirements file (`requirements = ["../../hardware/requirements.toml", …]`, handbook 10.4) and a shared script (`../../…`) –, as the Christmas bell's `variants/`
maker	Who makes and assembles the board? Another one to compare or to fall back on?	JLCPCB · PCBWay · Eurocircuits · AISLER · several: which, and which first	`[cart] maker` (the first) and `[cart] makers` (all); JLCPCB alone needs no `[cart]` (handbook 8.4, 10.1)
assembly	Who solders?	the classes of the maker – JLCPCB Economic, one side, SMD only · JLCPCB Standard, both sides; PCBWay turnkey, partial turnkey or kitted; Eurocircuits PCB Proto or a larger run; AISLER's assembly · nobody: a bare board, all by hand	`[release] assembly`: `{ sides = ["top"], smd_only = true }`, `{ sides = ["top", "bottom"], pcba = "standard" }`, `{ sides = [] }` – `pcba` one of the first maker's `classes`; with several makers the board is planned for the first, and the report names what the others would need; the parts you solder yourself get `bom: false` in the graph (circuit-design)
order	How many sets? Finish, colours, thickness – edakit's defaults, or what differs?	5 sets, edakit's defaults: 1.6 mm, green mask, white print, lead-free HASL, 1 oz, tented vias · other	`[project] quantity`; `[order]` in edakit.toml (every board) or the board file (one board) and `thickness_mm` – only what differs from edakit's defaults, and a question for each key whose default the chosen maker does not offer (`edakit cart fields --maker M`); only the fields the maker has – the order-number mark is JLCPCB's (handbook 8.4, 10.2)
money	A budget, a currency?	no budget · a budget: amount and currency	`[cost]`: `budget`, `currency` – the first maker's currency (JLCPCB and PCBWay USD, Eurocircuits and AISLER EUR) unless the user names another –, `rates` for a second currency (`{ EUR = 1.15 }`)
purpose	Private, a gift, or for sale? Where is it used?	private – built for oneself · gift – given away now and then · sale – sold, also in small series or as a kit	the graph's `purpose`: `use`, `market` (EU), `country` – the member state it is used in, `"AT"` (handbook 15.6), from "Where is it used?" –, `notes` – what it is, who uses it (children?). It decides how deep the regulatory review M-6 goes (handbook 15.1) – support, not legal advice: nothing in it is legally guaranteed, and it claims no correctness. The report says what the maker's seat means for it: outside the EU and `sale`, the owner imports the boards and is the manufacturer; inside the EU, no import, and the owner stays the manufacturer
requirements	What must the circuit do?	now, with the skill requirements · later	now: the skill requirements writes `hardware/requirements.toml` with the user, and `[project] requirements` names it (section 5); later: nothing yet – `edakit check` reports DOCS.file as open, the gate does not release until the file is there
firmware	Does firmware follow the graph's pins?	it follows the graph · the firmware is the reference, the graph keeps its pins · no firmware that depends on the pins	`[firmware]` and `edakit firmware --check` in the hook (handbook 3.5); the other way round `locks.pins` in the graph, the circuit designer's (STRUCT.lock)
documents	Do documents quote values – currents, voltages, a part's value?	no · yes: these files	`[docs] files`, `decimal = ","` for a decimal comma, `edakit docs` in the hook (handbook 6.6)
own tools	Does the project bring scripts or agents?	none · as the inventory proposes	`[scripts.<name>]` for every script that touches edakit's flow, `[agents.<name>]` for every agent that signs what edakit releases (handbook 8.6); the project's skills are listed in the report, not registered

Names and numbers, as free text: the project's name – the EasyEDA project, [project] name –, company for the title block, each board's name and title, each variant's name, the board's size if known, the amount and currency of a budget, the market and notes of the purpose, the documents with values, the distributors besides LCSC ([project] distributors).

Domains are no question of the interview. There is no graph yet, and the graph decides: edakit check switches on every domain a part or net suggests once it is in the graph – a battery holder power, a USB-C receptacle usb, a cable cables, an instrument net guitar, a speaker audio, a hazardous net mains (handbook 14.2) –, and edakit domains shows them. Write no [project] domains at the setup; the key is for a project that wants a domain off which the graph suggests, and each one it leaves out is a note STRUCT.domain.

A question the user cannot answer yet stays open with its default, and the report names it. The answers are a decision of the project: one numbered entry in its decision log (skill decision-round, section 3) – "D-1: set up for edakit: one board main drawn with labels, JLCPCB Economic on top, Eurocircuits to compare, 5 sets, a gift in the EU, no budget".

What the maker changes beyond assembly and order. A maker that matches by manufacturer part number (PCBWay, Eurocircuits) makes mpn and manufacturer required in every BOM part's entry – PARTS.fact/mpn from the first part on, and the agent part-selector and the skill part-search fill them; parts are still chosen by LCSC number. With JLCPCB among the makers its classes (Basic, Extended) and edakit stock stay as they are; without it no stock snapshot is needed. A maker that takes ODB++ (AISLER) needs easyeda-mcp-pro's easyeda_export_odb – edakit doctor checks it; on the KiCad tool chain kicad-cli exports it. A project moving to edakit takes the maker from the inventory (past orders, an order sheet), to confirm.

3. Files¶

From the answers – each file and key proposed with the answer that sets it, written after the OK:

File	Content
`edakit.toml`	the table of contents (handbook 10.1), from `tests/fixtures/led-bar/edakit.toml` with its comments, every value from the answers: `[project]` (`name`, `company`, `quantity`, `distributors`, `graph = "hardware/graph.toml"`), one `[boards.<name>]` per board, `[release] assembly`, and where the answers set them `[cart]` (`maker`, `makers`, `ship_to`, `shipping`), `[order]` for every board, `[cost]`, `[firmware]`, `[docs]`, `[scripts.]`, `[agents.]`. Moving: `graph`, `parts`, `sim`, `signoff` name the project's files where they lie
`hardware/boards/<name>.toml`	per made board, when its size is known: from the example's board file, outline and holes, `[order]` and `thickness_mm` where they differ; leave `place` and `routing.classes` minimal until the parts exist. Otherwise the PCB designer starts it, and the order's answers wait in the decision log. None for a bought or hand-wired board, none without a PCB
`hardware/graph.toml`	the graph as TOML (handbook 3.1): `name`, `version = "0.1"`, `date`, `description`; `[purpose]` with `use`, `market`, `country` where the user names one, `notes` – the purpose from the interview –; `[conventions]` with `pin_reference = "'<designator>.<pin>' with the pin's name or role, else its symbol number – the parts entry says which pin that is"`. No part and no net yet: circuit-design writes the first `[components.<designator>]` and `[nets.<name>]` tables. Then `edakit graph json --write` writes the resolved `hardware/graph.json` beside it – generated, committed with the TOML, never edited. Moving: the project's circuit converted into edakit's format is written as this TOML too; a graph in edakit's JSON form stays where it lies until the user agrees to `edakit graph convert` (a proposal like any other)
`hardware/schematic.toml`	`style` from the answer on the drawing, nothing else yet: `[layout]` and its notes are the circuit designer's once the graph has parts (handbook 10.3). Moving: a schematic file of the project's own keeps its keys and gets `style` – the inventory's answer, else the user's
`hardware/parts/`	empty; every LCSC number gets an entry through the part-search skill or the agent part-selector
`hardware/sim.json`	from the example: sources (the supply connector – of a bought board on a cable its connector, the cable in the path), supplies at min/nominal/max, loads, corners; with several sources `combine_sources` (handbook 5.2)
`hardware/signoff.json`	from the example: M-1 (critical parts, second check), M-6 (regulatory review), M-5 (layout review), M-2 (manufacturer preview), M-4 (acceptance); a project agent with `replaces` signs edakit's review in its place, the gate adds an agent's own sign-off by itself (handbook 8.6)
`hardware/requirements.toml`	what the circuit must do – needs and requirements with their evidence, written with the user by the skill requirements and named in `[project] requirements` (handbook 3.6); required before a release (DOCS.file)
`variants/<v>/`	per further build its own `edakit.toml` and files as above, a board of its own in the same EasyEDA project
`docs/decisions.md`	numbered decisions D-1, … with reason and date (the decision-round skill appends); the setup's answers are the first
`.gitignore`	`build/`, `/edakit.local.toml` – the checkout's own settings, such as the inventory (handbook 10.1)

Moving. The project's files stay where they lie and edakit.toml names them (working agreement 22). Converted are only what the inventory proposes and the user accepts – a simulation config of the project's own into sim.json, a sign-off file into edakit's scopes and phases, the board's geometry into the board file –, each with what changed in the report. Its decision log keeps its place and its numbers. A [scripts.*] entry is written for a command that exists as written; one still to be built by the project goes into the report instead. A change to a file in a hash – the purpose in the graph, a converted simulation config – voids the sign-offs of that scope (handbook 8.2): the report names them.

4. Guard rails¶

Pre-commit hook: edakit hook install 2>&1 | cat writes edakit's block into .githooks/pre-commit and sets git config core.hooksPath – on a commit that touches a configuration's files edakit check, edakit sim and, with a TOML graph, edakit graph json --check – the generated graph.json still the resolved TOML (handbook 3.1) –, with [firmware] also edakit firmware --check (handbook 3.5), with [docs] edakit docs (handbook 6.6); a failing check blocks the commit. Never bypass it with --no-verify. No wrapper script of the project's own: the block finds edakit itself. Moving: the project's hook keeps its other steps, the block goes after its header; the lines install names as running edakit themselves – its own graph check and simulation, a wrapper's calls – go, and so does a hint in it to bypass a failing check.
CI: the same commands plus the project's tests on every pull request (uvx --from git+<edakit repo> edakit …).
.claude/settings.json of the project, so every session in this repo has the plugin:
```
{"extraKnownMarketplaces": {"edakit": {"source": {"source": "github", "repo": "tgd1975/edakit"}}},
 "enabledPlugins": {"edakit@edakit": true}}
```
Moving: an EasyEDA MCP server of the project's own (.mcp.json) goes – the plugin brings the pinned one, and two would run with every tool twice; agents and hooks that name its tools (mcp__easyeda__…) get the plugin's names (mcp__plugin_edakit_easyeda__…).
A write refused. Claude Code guards .claude/settings.json and git's configuration, and a sandbox may refuse them: edakit hook install then names the step that failed and exits 1. Nothing else waits for either – write the other files, go on with section 5, and put each refused step under Open in the report as the user's to do: the settings block above for .claude/settings.json, edakit hook install (or the git config core.hooksPath … it names) in a terminal of their own. Do not retry it another way.

5. First run and hand-over¶

edakit check 2>&1 | cat and edakit sim 2>&1 | cat – on a new project the empty graph; on a moving one what edakit finds in the project's data. Findings go into the report and to the skill that owns them, not fixed silently here. With [scripts] or [agents] (a project without entries skips this): edakit scripts 2>&1 | cat shows that the entries resolve, before any script runs – "do not resolve", an error scripts or agents of edakit check, means an entry is wrong: a kind, a path, what it reads or writes, what an agent signs, its file. Fix the entry and name the fix in the report. Then each script that never ran, with the user's OK: edakit run <name> 2>&1 | cat runs and records it – an easyeda script under the claim, once the EasyEDA project exists –, and edakit scripts stamp <name> records one whose result is there from before (moving, handbook 8.6). An input that never ran fails edakit check until then.
Requirements "now": the skill requirements – it writes hardware/requirements.toml with the user, and circuit-design reads the file instead of asking.
Graph with the skill circuit-design: power input, MCU, the main functions – building blocks where they fit (edakit block list), other parts by LCSC number (part-search skill), nets with voltage ranges v, pins by name or role. edakit check until 0 errors, edakit check worked through, edakit sim – scenarios first at the supply limits –, and edakit graph json --write after every change, so that the hook finds the generated file current. A moving project has its graph: circuit-design takes what edakit check found.
Without a PCB (a development board and hand wiring) the project stops here: edakit schematic draw gives the schematic in the style of the schematic file, EasyEDA is not needed. With a PCB: the user creates the EasyEDA project once by hand (File → New → Project, named like [project] name) – the local desktop client refuses DMT_Project.createProject; a moving project has it already. Then the start skill.
Continue with the hardware-change skill for every further change of the circuit. The layout is the PCB designer's: skill pcb-round in a session of its own, starting from edakit handover (handbook 14.1).

Report¶

Set up: the files and keys, each with the answer that set it; moving: what was converted, and the sign-offs a change voided.
Open: questions left at their default, contradictions not decided yet, what the agents could not read, parts without an entry, a missing outline, scripts still to be built.
Purpose: as set, and what it means for the regulatory review M-6 – support, not legal advice: nothing in it is legally guaranteed, and it claims no correctness.
The project's own skills that overlap edakit's (moving): each with its edakit counterpart and what it does beyond it – a script entry, a project agent, a line in the project's CLAUDE.md, a feature proposal. Keeping or deleting one is the user's decision, skill by skill; the setup deletes none.
Next: the skill requirements if the file is still missing, circuit-design, and start once the EasyEDA project exists.