Skip to main content
Use this workflow to turn a board, schematic, or part selection into a small firmware milestone that you can build and observe on the intended target. Embedder combines project hardware context, repository instructions, agent modes, and bench tools; you still choose the architecture and define what proves the prototype works.

​
Define the first observable milestone

Choose one behavior that exercises the smallest useful path through the hardware. A good milestone identifies:
  • the intended board and populated peripherals;
  • the interface, pins, and operating conditions;
  • the firmware behavior to implement;
  • the exact build configuration;
  • an observable pass condition, such as a UART line, GPIO waveform, sensor value, or current range.
Avoid starting with a broad request such as “bring up the board.” A bounded milestone gives Embedder a finish line and makes failures easier to localize.

​
Establish the hardware context

1

Select or create the project

Run:
Select the project associated with the workspace, or create one from a catalog platform, a custom platform, or a complete schematic source set.
2

Confirm the target platform

Choose the exact board or MCU from the project setup picker. The catalog available to your team is the source of truth.If the platform is not in the catalog, choose Add a platform when your account permits custom components, or create the project from schematics.
3

Add populated peripherals

Run /peripheral and attach the exact catalog parts fitted to the board. For an off-catalog part, add its PDF documentation as a custom peripheral when that feature is available.Adding a peripheral supplies identity and indexed documentation. It does not generate a driver, assign pins, or prove that the part is populated.
4

Review schematic evidence

When schematics are available, compare the active project components with the parsed design. Use references such as @sch:component:U4, @sch:net:I2C1_SDA, and @sch:power_domain:VDD_IO to attach the relevant connectivity to a prompt.
Catalog recommendations and schematic part matches are useful starting evidence, not a verified bill of materials. Check the board revision, package, fitted option, power domain, and connector routing before implementation.

​
Initialize the repository workflow

Run /init after selecting the project:
Embedder inspects the repository, selected hardware, build files, tests, debugger configuration, connected equipment, and project rules. It asks you to verify target hardware, build and test commands, deployment, bench setup, and quality requirements before it creates or refreshes the managed section in EMBEDDER.md. The resulting guide should record:
  • the exact target, toolchain, build configuration, and artifact path;
  • test, flash, debug, and observation commands;
  • connected probes, serial settings, and bench constraints;
  • generated or vendored code boundaries;
  • the expected result and evidence status for each workflow.
Discovery alone does not verify a command. A workflow is verified only when it ran successfully or when existing evidence was explicitly confirmed. /init does not flash hardware or install dependencies unless you approve that optional validation.

​
Ground the implementation in the design

Ask Embedder to inspect source, indexed component documents, and parsed schematics before it chooses registers or pins:
Use the evidence sources for different questions: If a required fact remains ambiguous, resolve it before implementation. Do not substitute documentation from a nearby MCU, board revision, or peripheral variant.

​
Choose Plan or Act

Use Plan mode when the prototype changes architecture, spans several modules, introduces a new driver boundary, or depends on unresolved hardware choices:
Plan mode can research code, documentation, schematics, diagnostics, and saved hardware output. It can modify only the session plan. Review the proposed files, hardware assumptions, failure handling, and verification sequence before approving it. Approval starts implementation in Act mode. For a small, fully specified change, start directly in Act mode:

​
Implement and verify in layers

Treat each layer as separate evidence. A later success does not repair a missing earlier result.
1

Run the smallest host check

Add or run the focused unit test, simulator check, or static diagnostic that covers the changed code. Fix the first useful failure before broadening the test scope.
2

Build the intended firmware

Run the exact command recorded for the project. Confirm the configuration and identify the resulting ELF, HEX, or BIN artifact.
3

Confirm the physical target

Check the board, MCU, probe or bridge, serial transport, and power state. Require an explicit choice when more than one target is connected.
4

Flash and capture early output

Use the dedicated flash workflow so target arbitration, programming verification, reset handling, and early serial capture apply.
5

Observe the real interface

Verify the behavior at the layer that matters. Read serial or RTT output for a software-visible result. Use a logic analyzer, oscilloscope, power analyzer, or debugger when the pass condition depends on pins, timing, current, or target state.

​
Escalate a hardware failure to Debug

Switch to Debug mode when source inspection, host tests, and ordinary serial output cannot explain the target:
Debug mode adds managed GDB, hardware scripts, coverage, instruction trace, and instrument providers. Start with the least invasive observation and state what the investigation must preserve:
Use hardware_status to confirm which probes and instruments are ready. A custom platform entry provides context; it does not create a new flasher, debugger backend, or instrument provider.

​
Keep the prototype reproducible

Before calling the milestone complete:
  1. Record the exact build, test, flash, and observation workflows in EMBEDDER.md.
  2. Keep the pin choice, board revision, and required jumpers with the project instructions.
  3. Save reusable hardware checks under .embedder/hardware/.
  4. Report which evidence was observed and which assumptions remain inferred.
  5. Rerun the narrow pass condition from a clean build or known target state.

Common firmware workflows

Follow the project, plan, build, flash, and debug sequence in detail.

Schematics

Upload complete designs and reference parsed components, nets, and pins.

Configure EMBEDDER.md

Record verified commands, artifacts, equipment, and safety rules.

Supported hardware

Check catalog platforms, probes, transports, and instrument boundaries.
Last modified on August 21, 2026