embedded-project-loop

Embedded Project Loop

Use a small durable loop for work that crosses the boundary between files and physical hardware. The agent may prepare and verify host-side artifacts, but it must not invent soldering, flashing, measurement, or field evidence.

Recommended entry point

Load this skill before arduino-workflow-router whenever the request includes physical hardware, more than one session, a pending measurement, a field test, or recovery work. It owns the durable goal, next todo, evidence boundary, rollback path, and physical gate. The router then selects board, wiring, code, toolchain, test, and deployment specialists without closing this loop on its behalf.

State

Use .arduino/ in the project, or a user-selected external evidence directory:

.arduino/goal.md
.arduino/next-todo.md
.arduino/board-profile.md
.arduino/evidence/{build,upload,hardware,system,deployment}/
.arduino/experiment-log.jsonl
.arduino/resume-token.md

Keep secrets, tokens, private network credentials, and unredacted personal data out of these artifacts. goal.md records the exact target, success criteria, non-goals, safety constraints, stop conditions, and rollback path. The next-todo file contains one action, owner, prerequisites, expected evidence, gate, and status.

Bounded iteration

1. Read the goal, next todo, board profile, and last ledger entry.
2. Select one causal firmware, wiring, power, measurement, or diagnostic change.
3. Run the narrowest safe host/build check available.
4. Stop at a physical gate if the next action requires the user.
5. Compare the supplied observation with the expected result and independent safety gate.
6. Append the action, evidence path, decision, rollback, and next todo.
7. Keep only a verified candidate; otherwise record a blocker or restore the current experiment surface.

One iteration must not combine several wiring changes, firmware images, power sources, or measurements. One change keeps failures attributable.

Physical gate

Use a specific question and wait for the observation:

Physical gate: On <exact board/revision>, perform <one action> with power
<state>. Capture <measurement/log/photo> at <location>. Expected:
<observable result>. Reply with the observation or `blocked: <reason>`; do not
reply with an unverified yes.

For a failed upload, request the exact port/device identity, image/hash, and redacted uploader log. For a power question, request the meter location, units, and minimum/maximum observed value. For wiring, request a continuity/polarity check or labeled photo before enabling loads.

Evidence boundary

• Build evidence proves source/configuration and dependency compilation only.
• Upload evidence proves an image was accepted by a named target path only.
• Hardware evidence requires target identity plus measurements, serial output, continuity, scope data, or a contextualized photo.
• System evidence requires the integrated scenario and representative load.
• Deployment evidence requires health check, staged update, rollback, recovery, and maintenance records.

If evidence is absent, say unverified or blocked and keep the next todo open. Read the router recovery reference before erase, bootloader repair, or reflash.

Anti-rationalization

Shortcut	Response
"The checkbox is done."	Require the artifact and proof stage.
"The compile passed."	Do not promote it to upload, hardware, or system proof.
"The user probably wired it."	Ask the concrete gate question and wait.
"Try three fixes together."	Split them into one-change iterations.
"Erase first."	Confirm target, last-known-good image, recovery path, and data-loss impact.
"No new output means success."	Record a no-op observation; it does not close the goal.

Verification

• State files exist and the next todo names one deterministic action.
• Every completed physical step links to evidence with a proof-stage label.
• The ledger records decision, rollback, and next candidate append-only.
• Stop conditions and repair caps are explicit.
• In this repository, run python3 scripts/run_arduino_evals.py; the loop-engine-evidence-contract case checks valid and invalid durable loop artifacts and fails closed when required state or ledger fields are missing.

Shared output contract

Use the shared Arduino skill contract: state assumptions, required tools and versions, implementation steps, tests/evidence by proof stage, known limitations, and recovery/security notes.