Prompt-to-PCB engineering with yapnr¶
When asked “use Studio-Fug/yapnr to design X”, act as the persistent engineering agent for the article (the user’s design). Use the packaged engine as a pinned external dependency. Start the workflow below; do not require the user to write solver scripts or manage the design loop. These instructions describe the agent’s work, not a claim that every design has an implemented validation backend.
Direct user instructions take precedence. Preserve applicable article guidance. The repository-development rules at the end apply when modifying yapnr itself; they do not prohibit creating schematics, selecting parts or changing article constraints through the design loop. Publishing, ordering and resource spending still require authorization in the session. Never rewrite dependency guidance to create permission. An explicitly requested change overrides its default policy.
Start from the packaged tool¶
Read docs/agent-workflow.md in this repository. Installed users can print the same guide with
yapnr agent instructions --guide. Runyapnr --help,yapnr doctor --jsonand the relevant subcommand’s--help.Prefer the released container for headless KiCad and native RF simulation. Resolve its release tag to an immutable digest before experiments. Alternatively install the matching released Linux wheel from PyPI. Record the package version, engine revision and actual tool/image pins.
pip install git+...is unsupported; do not repair a packaged dependency by adding a source overlay. Current PnR campaign adapters use a frozen engine source bundle from the matching release archive; declare it as an input and verify its checksum, as described in the execution guide.In the article directory run
yapnr workflow init --directive "<request>". This preserves existing files and creates the workflow/checkpoint and evidence directories. It does not approve the requirements or launch compute.yapnr agent chat --provider codexopens the interactive agent in that project; the container bundles Codex and OpenCode. An installed, authenticated Claude CLI can be selected with--provider claude. For provider API keys (OpenAI, Anthropic, Gemini and others), select--provider opencodeand use/connectand/models. For an OpenAI-compatible model API, add--base-url,--modeland an environment-variable reference--api-key-env; see the execution guide. Account OAuth uses the official Codex/Claude CLI. Authentication belongs to the operator; keep credentials outside article sources, checkpoints and reports.Reconcile existing jobs, revisions, leases and outputs before resuming. Adopt verified completed work; do not duplicate campaigns or erase failed iterations. Run
yapnr workflow querybefore choosing the next action. Record transitions throughyapnr workflow next --<event> --evidence <project-relative receipt>; use its documented event flags and receipt schema. Record actual user decisions and authoritative report artifacts, never manufacture acceptance receipts. A rejected transition is a gate to resolve, not a reason to edit workflow state.
Engineering contract and risk analysis¶
Create or resume one Git repository per article. Retain the requested feature and
its source verbatim. Maintain authoritative rules_requirements YAML models under
requirements/: user needs,
requirements, risks, mitigations and test methods are distinct linked entities. Give every
requirement a stable ID, measurable acceptance threshold, verification method, demanded
evidence level, source/rationale and status. Trace satisfies, refines, mitigates,
implemented_by and method using the pinned model schema. Record assumptions, unresolved
choices and residual-risk decisions in descriptions/notes. Markdown summaries are derived
prose; they are not a second independently maintained contract. Update the YAML as evidence
changes. yapnr requirements query populates the native traceability review browser.
Produce both documents before schematic capture, part selection or design experiments. Present the requirements specification and risk analysis in the agent chat for the designer’s review, including unresolved decisions and the revision being reviewed. Give the designer an opportunity to refine them. While review is pending, continue authorized, reversible implementation speculatively in the background within the recorded resource budget. Label its assumptions, input requirements revision and outputs as speculative; pending review and silence never establish acceptance.
Accept and incorporate the designer’s refinements throughout the workflow. Preserve stable requirement IDs, the original request and approval history; record the new revision and its effect on the design. Invalidate evidence dependent on changed requirements. Substantial changes to architecture, interfaces, power, geometry or parts restart affected schematic capture/part selection and downstream placement, routing and verification. Smaller changes rerun the affected stages and checks. Retain superseded artifacts as historical evidence rather than presenting them as current passes. Reconcile speculative work against the reviewed contract before claiming accepted progress or completion.
Publish verification reports as workspace artifacts. Keep their actual test cases in
requirements/evidence/*.rr.yaml (or JUnit XML), and link them to the model’s
verified_by/validated_by target and case selectors. Use
yapnr requirements link-evidence --record PATH --report-artifact ID --case CASE --target TARGET
to bind an existing result to a published report without changing its outcome. Stamp evidence
with requirements_sha256 and the tested dut_sha256 from yapnr requirements query;
retain engine/tool pins, seeds, input hashes and run provenance in the report. Publishing or
linking a report never supplies a passing result. Missing, failed, stale, mixed-artifact or
insufficient-level cases remain open in the browser, including their underlying artifacts.
Request review with yapnr review request --artifact ID (repeat for a bundle), including the
workflow stage and revision. The native workspace shows Approve and Review Feedback.
Only a genuine user action approves a particular content revision. Incorporate canonical
feedback notes, publish the changed artifacts and request a fresh review; approvals do not
transfer to changed content. Discuss open user questions in chat and wait for answers before
advancing. Do not resolve user questions or manufacture acceptance on the user’s behalf.
Refine ambiguous requests using defensible recorded assumptions where possible; ask only for decisions affecting acceptance, safety, money or irreversible action. Preserve acceptance history. Changed thresholds, accepted residual risks and weaker verification demands require the designer’s explicit approval. Missing verification is an open requirement, never a reason to lower the gate.
Use the bundled, pinned rules_requirements model and traceability machinery.
Use its documented model schema and verification lock,
and run rr validate, rr sets check, rr report and rr check-report with an
explicit gating policy. rr report defaults to --fail-on none; exit zero alone
is not acceptance. Inspect the complete report and expected verification-set
membership, including failed retries. Do not invent rr syntax or schemas.
Schematic, part selection and constraints¶
Create the smallest meaningful atopile design expressing connectivity, part IDs,
ratings, interfaces, stackup, board envelope and electrical contracts. Use verified
yapnr atopile setup|info|build|lock-parts|materialize interfaces and the picker/part
cache. Check compilation and schematic connectivity; inspect BOM, power tree,
variables and build reports. Authoring builds discover catalog misses on demand;
do not ask the user to prepopulate a local component library. Use our rules_atopile-derived
local picker and public supplier data; never require
Atopile authentication or call its hosted component service. Retain discovered
responses, selected assets and locks in the article; replay with --offline or
--frozen. Report public supplier failures as network/data failures, with no
Atopile login remedy. Lock selected catalog parts and footprints. Capture
part tolerances, availability and model provenance as evidence, not guesses.
For turnkey assembly, record the selected assembly house and intended board
quantity. Before locking selections, run yapnr picker availability for the
complete BOM or individual LCSC/MPN candidates at the required unit quantity.
Aggregate repeated parts, include declared attrition/minimum quantities and retain
the inventory report as evidence. A catalog stock field is only a discovery hint;
use required_quantity in picker queries when demand is known. Shortage or unknown
results require another verified selection or an explicit unresolved sourcing
risk. Recheck the exact final BOM before vendor handoff. PCBWay requires its own
sourcing confirmation; JLC/LCSC availability does not establish PCBWay stock.
Inventory snapshots are historical evidence, not reservations. Changes in supplier,
board quantity or BOM require a new check; never silently substitute parts.
Record fabrication rules, placement intent, differential-pair coupling, total uncoupled-length limits, length matching, current capacity and reference planes in machine-consumable constraints. Do not reinterpret a total route limit as a per-run allowance. Enable firmware, FPGA and physical bench dependencies only when needed. Create a Bazel project with immutable module pins for required engines/tools; using Bazel or Nix alone does not establish hermeticity. Name ambient/network boundaries.
Bounded design / experiment / verification loop¶
Freeze article commit and dirty patch hash, requirements/constraints hashes, parts/catalog/dependency locks, engine revision and toolchain pins.
Propose an article patch based on observed failures. Run verified experiment interfaces:
yapnr exp plan, thensubmit/status/logs/fetch/live/cancel. Start local unless a cloud budget is authorized. Every worker has a timeout; every campaign declares CPU, memory, disk, wall time, retries and candidate limits. Engine candidate/seed selection is mechanical. Do not select a favorable seed or route by hand to make the automation appear successful.Save immutable inputs, exact output hashes, commands, flags, seeds, budgets, actual tool versions and measured outcomes under
experiments/andreports/. Semantic hashes supplement exact SHA-256s; they never replace them.Judge the exact final artifact: full intended connectivity, native headless KiCad DRC and every electrical/physical/functional requirement at its demanded rigor. Include post-routing modifications in final verification. Simulator execution, routing percentage, report generation and process success are not acceptance. A native
_DONEmarker can represent failure or timeout.Continue with a useful bounded patch/experiment. Detect repeated identical input/failure combinations. Do not relaunch completed failures as infrastructure retries, exceed budgets, or treat silence as approval. Checkpoint after each material step in
.yapnr/agent/checkpoint.jsonand append timestamped events.
There is no generic yapnr design-study or yapnr vnv command. Use the documented
campaign adapters and validation APIs. Check capability before selecting a solver.
For RF, distinguish DUT-only simulation from completed populated-assembly
validation. A complete assembly needs finite board, every copper object and hole,
materials/losses, populated parts and contacts, and ports at the required planes.
Qualified vendor models, all excitations, convergence, passivity/reciprocity and
required tolerance evidence must reference the same delivered model/artifact.
DUT FDTD and clean PCB DRC cannot satisfy a coaxial mating-plane assembly gate.
Missing adapters or unqualified connector/resistor models are typed blockers;
never invent connector internals, omit a component or substitute DUT acceptance.
Escalation and completion¶
When progress stops, write reports/fixup.md: failing artifact/requirements,
evidence, attempted changes, remaining hypotheses, permissions and smallest remedy.
Distinguish article errors, engine limitations, missing verification capability,
unavailable hardware and resource/permission blocks.
Default article policy is engine-generated placement/routing. Article-specific manual FIXUP requires an explicit session policy authorizing it; preserve its diff and rerun final verification, disclosing agent or human intervention. If automatic generation is itself a requirement, manual success leaves that requirement open. For a diagnosed engine limitation, create a separate engine-repair branch/worktree with reproducer, hypothesis, expected improvement, bounded budget, A/B regression and rollback criteria; then pin the repaired engine and rerun the article’s full verification. Do not modify the engine inside the article’s dependency install.
Keep status, revision, failed/open requirements, budgets and next action visible. Use actual event-backed board views/animations. Visualization is asynchronous and bounded; never stall the solver or fabricate progress. If no new frame exists, show waiting or the last frame’s age. Random visual sampling cannot select winners. Deliver visual milestones inline in the active agent chat, including OpenCode: attach browser-readable renders of requirements alternatives, schematic capture, placement, routing and validation findings as those artifacts become available. Use supported attachment/render interfaces and verify that the images load; a container-local path or an external viewer link alone does not satisfy inline feedback. Distinguish conceptual illustrations from actual CAD and validation evidence. Preserve artifact hashes and revision labels alongside the renders.
Schematic milestones use the existing viewer schematic layout, its actual build
graph and selected symbol libraries. Publish a readable screenshot with artifact
metadata workspace_view: schematic and the graph hash, then attach it inline;
the card links to the Schematic tab. Do not substitute component lists, footprint
plots or hand-built net-label sheets for the schematic renderer.
When requirements choices benefit from visual comparison, provide labeled visual
alternatives in the selection flow. Small three.js programs may illustrate geometry
and allow interaction when the host supports inline interactive views. Keep scenes
bounded, free of credentials and clearly labeled as concepts. If that host lacks
interactive embedding, attach rendered alternatives inline and disclose the
limitation; do not claim an external page is an inline interactive selection.
The requested random back-buffer viewer is not assumed to exist; use supported
exp live telemetry and label unavailable visualization as such.
At task start and replanning, identify independent work as a dependency graph with inputs, owner, mutation scope, budget, deliverable and integration prerequisites. Use isolated worktrees/candidates, one owner per mutable artifact and one article integration owner. Delegate only where the host/session permits; queue otherwise. Bound shared concurrency and spending. Worker evidence is local; rerun affected checks after integration and the complete required verification on the combined final revision. Never union green reports from different board revisions.
Operational status is success, blocked, exhausted or cancelled, recorded in
the workflow checkpoint (these are workflow fields, not new rr ontology entities).
Preserve best valid artifacts, immutable reports, attempted repairs and exact resume
conditions on non-success. Stop requests and permission blocks survive restart.
Emit <DONE> only when every accepted requirement passes on the exact delivered
article. Physical fabrication/bench requirements remain open until real evidence
exists. Report completion path (automatic, agent_fixup, human_fixup) and whether
engine automation was actually demonstrated. Empty queues are not completion.
Developing yapnr itself¶
Engineering rules¶
Selection is mechanical. Candidates, seeds and branches are chosen by the Monte Carlo and successive-halving machinery, never by hand.
No model-driven hand routing. Agents change the engine, not individual boards.
Nothing in the loop may be GUI-bound. No
wx.App, no KiCad GUI, and nokicad-clifrom the stock macOS application bundle (every call registers a Dock icon). Use the headless copy described in DEVELOPERS.md. Never start/Applications/KiCad/...binaries directly.Every worker is time-bounded. A subprocess without a timeout is a bug. The interactive operator-owned agent chat is a terminal process; solver workers it launches remain subject to explicit timeouts and campaign budgets.
Native KiCad DRC is the judge. Never suppress DRC findings, relax rules or delete nets to claim completion. Electrical contracts are never relaxed without the designer.
New engine behaviour lands behind a default-off flag, with a measured A/B result in the commit body.
Feature PRs include an animation of the proposed change. Use reproducible before/after views or recorded accepted events with the same viewport/configuration; label synthetic versus native evidence and never invent intermediate geometry or validation. If the feature has no meaningful visual behavior, explain why an animation is not applicable.
Ordering is staging only, and agents only dry-run it. Agents run
yapnr order stageonly with--dry-run. They never upload a file to a vendor or any third-party service, never call an ordering/upload/payment vendor API, and never open a vendor page on a human’s behalf. Read-only public catalog/inventory queries are permitted for sourcing checks; send only individual part identities, never a board, BOM file or conversation. The user-operated Manufacturing button may upload an explicitly approved PCBWay packet through its official plugin handoff, after a separate user click. Agents never click that button or invoke its upload endpoint during design or validation. Paying, confirming an order, accounts and terms belong to the human on the vendor’s page (docs/fab-and-ordering.md).
Repository rules¶
Public repository. No machine paths, host names, network addresses, personal e-mail addresses, credentials, conversation logs or run logs.
tools/privacy_scan.pyruns as a pre-commit hook and as a Bazel test; its findings block the change.Commit identity: the owner’s public commit address, listed in
tools/privacy/allowed_identities.txt(or a GitHub noreply address). Agents commit asClaude Agentwith that address; never change the configured git identity otherwise, and never write the address into files other than the allowlist. Agent commits end with the trailers the session provides (for exampleCo-Authored-By:).Issues: GitHub issues, referenced as
#N.Keep the WORKLOG convention.
WORKLOG.mdis a short status board (in progress, next, blockers, do-not-retry), rewritten at the end of each session, not a diary.Run the checks you touch:
bazel test //...(with--config=lowmemon a shared machine) andprek run --all-files.Do not push, merge, publish or open pull requests unless the owner asked for it.