Core Concepts

Best practices

Flash is only as good as the context it works from. A few habits — mostly about grounding and scope — make the difference between a generic answer and one that's right for your board.

Run /init first

Every answer is sharper once the board model and FLASH.md exist. Before asking anything substantial, run /init so the agent reasons over your real pin map, SDK, and build system instead of guessing. Re-run it (or /init --force) after big structural changes.

Keep FLASH.md tight

FLASH.mdis injected into every session, so it's the highest-leverage file you have. Put in what Flash can't guess and leave out what it can:

• Include— build/flash commands, board quirks and errata, project conventions, and any "always/never do X" rules.
• Leave out — self-evident practices and things already obvious from the code or the board model.

Be specific

Scope the task and name the concrete parts. Compare:

# vagueconfigure the timer# specificconfigure Timer 3 for a 10 ms interrupt using the 16 MHz HSI clock

Point at files with @path, reference existing patterns to follow, and describe symptoms precisely (the exact log line, not "it crashes").

Explore in plan mode, then act

For anything touching multiple files, switch to plan mode first so Flash investigates and proposes before it edits:

/mode plan     # explore & propose# review the plan, then:/mode normal   # execute

Pick the right agent

• Understanding a codebase? Use the read-only architecture or component agent — reproducible reports with citations, and no accidental edits.
• Making a change? general (the default) reads, edits, and runs.
• Chasing a hardware bug? The debug agent closes the build → flash → verify loop — give it a success criterion.

Match the agent to the task and you'll get sharper, safer results.

Help Flash verify its work

Give it a way to check itself. For firmware that means a build that must pass and a serial marker that must appear (or stop). The debug agent uses exactly this — a concrete success criterion — to confirm a fix on-target rather than declaring victory blind.

Use presets & config

Invest in setup once. Persist a fast local model, a stronger one for synthesis, and any per-project conventions, then bundle them as a preset:

/config set llm.model qwen2.5-coder:32b/model fast qwen2.5-coder:7b/config save            # to .flash_ai/config.toml (project)/preset apply fast      # switch bundles later

Save to your project with /config save, or add --user for a machine-wide default.

Keep write approvals on

By default Flash asks before it modifies files ([tools] confirm_writes). Leave it on until you trust a workflow — you'll see every diff before it lands, and can approve for the session when you're ready to move faster.

What's next