firmware-port

---
name: firmware-port
description: >
  This skill ports an existing open-source firmware to Attaky modular
  hardware. Use it when a user wants firmware that already runs on other
  devices to run on their Attaky: "port X to my Attaky", "make this
  open-source firmware run on Attaky hardware", "bring this project over
  to my Attaky device". It surveys the upstream code first (feature
  inventory, which Attaky modules each feature needs, and whether each
  module is truly required), pins an exact upstream version, checks the
  license and its publish obligations, then locates the upstream's own
  board-abstraction seam and writes a port plan — both artifacts are
  reviewed and approved by the user before any code changes. The
  implementation phase may be delegated to agents, targets the smallest
  possible diff against upstream, and hands off to firmware-build and
  firmware-deploy for milestone-gated real-hardware bring-up, exactly
  like the from-scratch chain.
---

# Firmware Port

This is the **alternate entry lane** of the `attaky-firmware-builder`
chain. The from-scratch lane goes brainstorm → spec → (ui) → codegen;
this lane goes **survey → plan → implement** over an existing
open-source firmware, then joins the SAME downstream pair —
`firmware-build` + `firmware-deploy` — for milestone-gated
real-hardware bring-up. Nothing downstream is special-cased for you
beyond what those skills already know about port workspaces.

The user here is often somewhat technical — they found an upstream
project they like and can name it. That changes the conversation tone,
not the division of labor: **all Attaky hardware decisions stay with
the skill**, drawn from the public catalog, and the user approves two
artifacts (the survey, then the plan) before any code changes.

## Operating Principles (non-negotiable)

1. **Two artifact gates.** `port/survey.md` first, `port/plan.md`
   second, each shown to the user in full and explicitly approved
   before the next phase starts. Never touch code before plan
   approval — read-only inspection of the upstream tree is fine at
   any time; edits are not.

2. **Use the upstream's own board-abstraction seam. Never
   re-architect.** Every mature upstream has a place where new
   hardware is meant to plug in — a variants directory, a board
   class, a Kconfig choice, a build-flag config header. Find it and
   add the Attaky target there, the way upstream's own targets are
   added. If you catch yourself redesigning upstream's HAL, stop —
   that's a fork, not a port.

3. **Smallest possible diff.** New variant/board files beat edits to
   shared code. When a core edit is genuinely unavoidable, write it
   generally enough that it could be sent upstream as a PR (an
   optional hook, a new branch in an existing board `#if` chain) —
   never an Attaky-only hack in shared code.

4. **Hardware facts come only from the public catalog.** Read
   `../../shared/hardware-catalog.md` before mapping features to
   modules. Module names are written as the catalog's canonical IDs
   in backticks in the parts list / parsed fields (e.g.
   `` `Core_ESP32_1.0` ``, `` `Expand_LoRa-GPS_1.0` ``) — exact-match
   parseable, same rule as the rest of the chain; use the Display name
   in prose to the user. If upstream code or a user claim disagrees
   with a catalog pin, address, or chip fact, surface the
   disagreement to the user; never silently patch either side.

5. **License first, factually.** Identify the upstream's SPDX license
   before planning anything. State the redistribution obligations in
   plain language: permissive licenses allow rebranding and closed
   redistribution with attribution; copyleft (GPL-family) requires
   publishing the modified source if binaries are distributed; LGPL
   sub-components offer source-provision or build-time gate-out
   options. Say explicitly that this is a factual summary, not legal
   advice. Never ship copyrighted OS images, BIOS blobs, proprietary
   fonts, or media files — build from source; the user supplies their
   own media.

6. **The chain-integration shim is mandatory.** The ported firmware's
   init must emit the chain's boot banner pair and (for milestone
   builds) the milestone marker — that is what lets `firmware-build`
   §7 and `firmware-deploy` §3.5c gate the port unchanged:

   ```
   [INFO] [APP] <firmware-name> v<version> on <build-SKU>
   [INFO] [APP] Build: <build timestamp> / toolchain: <PlatformIO|ESP-IDF>
   ```

   and, as a separate line, never inside the banner:

   ```
   [INFO] [APP] milestone: M<N> (<short name>)
   ```

   **Version normalization rule**: `<version>` is the upstream version
   normalized to its numeric `x.y.z` core (drop extra dotted segments,
   hashes, and pre-release tags) with `-A<NNN>` appended — e.g.
   upstream `2.7.4.c1f4f79` becomes `2.7.4-A001`. `A<NNN>` counts
   Attaky port releases of that upstream version, starting at `A001`.
   The full un-normalized upstream version string is recorded in
   `port/survey.md` §1, not in the banner — `firmware-deploy`'s boot
   regex accepts exactly `x.y.z` or `x.y.z-A<NNN>`, nothing looser.

7. **Milestone exits are serial/behavior evidence on real hardware,
   never "it flashed".** The plan's milestone ladder gives every
   milestone a serial-verifiable exit gate, and the downstream skills
   enforce it. Toolchain pins are project-local (the pinned platform /
   IDF version lives in the project, not in a shared install) — never
   mutate a shared toolchain to suit one port.

## Workflow

### 1. Capture the ask and set up the workspace

The user names an upstream project, a link, or a description ("port
X", "make X run on my Attaky"). Get two things settled, one question
at a time, only as needed:

- **The upstream repo** — if they gave a name but no URL, locate the
  canonical repository and confirm it with them in one line ("That's
  `<host>/<org>/<repo>`, right?"). Don't guess between forks
  silently; if several candidates exist, ask which.
- **The workspace folder** — same ask-once convention as the rest of
  the chain. Derive a slug from the upstream name (lowercase,
  kebab-case), determine the current working directory, and ask:

  > "Setting up the port workspace at `<cwd>/<slug>/` — confirm, or
  > give a different path."

  Wait for confirmation or an alternative absolute path.

If `<workspace>/references/` exists, scan it — user-dropped notes
("make it behave like this"), datasheets, and durable findings from
earlier runs are input context for the survey. Scratch by-products of
this skill's run (probe output, clone logs) go to `<workspace>/tmp/`,
which must stay safe to delete wholesale.

The port workspace looks like this when the lane has run end to end:

```
<workspace>/
├── port/
│   ├── survey.md     ← this skill, phase A (gated)
│   └── plan.md       ← this skill, phase B (gated)
├── references/       ← optional reference library (user + skills)
├── source/           ← upstream clone + the port work (phase C)
├── build/            ← written by firmware-build
├── deploy/           ← used by firmware-deploy
└── tmp/              ← optional scratch space — safe to delete
```

There is no `concept.md` and no `spec/` here — that's the other lane.
The downstream skills know a port workspace by `port/plan.md`.

### 2. Fetch and pin the upstream

Clone the upstream into `<workspace>/source/` at an **exact tag or
commit SHA** — never a moving branch:

- Default to the latest stable release tag. If the user wants a
  specific version or `HEAD` of a dev branch, honor it, but record
  the resolved SHA either way. The pin goes in `survey.md` §1.
- If the upstream splits across coupled repositories (a core repo
  plus a UI library, a companion protocol repo), record each repo's
  exact SHA. When the port later pins one repo from another (e.g. a
  `lib_deps` entry), pin the **real published SHA** — never a
  placeholder to fill in later.
- Detect the upstream's build system from the tree, same shapes as
  `firmware-build` §2: PlatformIO (`platformio.ini`) or ESP-IDF
  (top-level `CMakeLists.txt` + `main/`). If it is **neither**, warn
  the user once, before the survey:

  > "This project uses a build system `firmware-build` can't drive
  > (`<what you found>`). I can still survey and plan the port, but
  > the plan must either wrap the build in a PlatformIO/ESP-IDF
  > project or you accept building manually outside the chain. OK to
  > continue on that basis?"

Note the clone in one line to the user ("Pinned `<repo>` at
`<tag>` = `<short-SHA>`."). Keep the clone pristine until phase C —
survey and plan are read-only phases.

### Choose collaboration mode

Read `../../shared/collaboration-mode.md` — the mode contract shared
across the chain. Before drafting the survey, ask the mode question
once:

> "Want me to build this end-to-end and show you a working first version,
> then refine it together — or check in with you at each step (screens,
> hardware, code) before moving on? (Default: I'll build the first
> version and we iterate.)"

Record the answer — `autonomous` (default) or `step-by-step` — in
`port/survey.md`'s **Collaboration mode** field, and carry the same
value into `port/plan.md` when it's written in §4. This is a one-time
choice for the whole run: don't ask again later in this skill, and if
you're re-entering on a workspace that already has a recorded mode (in
`survey.md` or `plan.md`), reuse it instead of re-asking. Same
non-negotiable as the rest of the chain: this is the only mode
question asked — never a technical (chips / pins / libraries /
memory) question in either mode.

### 3. Survey (gated artifact 1)

Tell the user in one short sentence what you're doing ("I'll survey
what's in this firmware and what Attaky hardware it needs — you'll
get a doc to react to."). Then:

- Read `../../shared/hardware-catalog.md` (modules, Complete Builds,
  recommended libraries).
- Read `references/survey-template.md` for the section structure.
- Walk the upstream tree: build configs, the boards/variants
  mechanism, the feature surface (menus, protocol handlers, drivers,
  storage, connectivity).

Write `port/survey.md` with all seven sections — your prose, the
user reacts:

1. **Upstream identity & baseline pin** — project name, repo URL,
   license file location, pinned tag + resolved SHA, coupled-repo
   SHAs, the full upstream version string.
2. **License & publish posture** — SPDX ID, plain-language
   obligations, copyleft / LGPL sub-component flags with the standard
   options, the copyrighted-media rule, the not-legal-advice line.
3. **Toolchain check** — PlatformIO / ESP-IDF / neither (with the §2
   warning outcome if neither).
4. **Feature inventory → module mapping → necessity triage** — the
   entry artifact of the whole lane: one table row per upstream
   feature; the catalog module (canonical ID) each needs; verdict
   **required / optional / droppable** with a one-line reason tied to
   the feature. "Required" means the port is pointless without it;
   "optional" works if the module is present; "droppable" is not
   worth porting (say why).
5. **Board-abstraction seam** — where upstream expects a new target
   (variants dir / board class / Kconfig choice / build-flag config),
   named concretely (paths), plus the nearest existing ESP32-S3
   target to use as the M0 template.
6. **MVP bar** — what "believable demo" means for this port, and the
   explicit not-ported list. Anything that needs upstream core
   changes goes post-MVP by default.
7. **Risks & unknowns** — radio/audio module datasheet parameters
   still needed, display driver/rotation questions, PSRAM/partition
   budget, input-stack mismatches — anything that could invalidate
   the plan.

Show the full doc inline. Iterate the way the chain always does:
apply changes, re-show the full doc, mark this round's edits
(strikethrough for replaced text, bold for additions). Stay decisive
on "what do you think?" questions.

**Approval gate.** Watch for the chain's explicit approval signals —
"looks good", "approve", "ship it", "let's go", "ready", "next",
"done", "good", "yes", "OK" (equivalents in the user's language
count). On approval, write `port/survey.md` to disk and move to §4.

### 4. Port plan (gated artifact 2)

Read `references/plan-template.md` and
`references/porting-pitfalls.md` before drafting — the pitfalls doc
exists so known traps land in the plan, not in the debugger. Write
`port/plan.md`:

1. **Identity block** — `firmware-name`, `version` (the normalized
   `x.y.z` core + `-A<NNN>`, per Operating Principle 6), and
   `build-SKU` (the catalog Complete Build the port targets, or
   `Custom build`). `firmware-build` §7 reads these three fields to
   resolve the boot-banner contract, so this block is load-bearing.
2. **File-level change list** — every file to add or edit at the
   seam, with one line each on what and why. New files first, core
   edits last (each core edit justified per Operating Principle 3).
3. **Chain-integration shim** — where the banner pair and milestone
   marker are emitted (variant init / app entry, after serial is up),
   with the exact strings resolved for this port.
4. **Milestone ladder** — mapped onto the standard bring-up order:
   M0 toolchain sanity (nearest existing target builds) → target
   compiles → display → storage/first-boot → input → radio/audio →
   power. Each milestone names its **serial-verifiable exit gate**
   ("M2 passes when the boot log shows `<line>` and the panel shows
   `<effect>`") — flashing without evidence is never an exit.
5. **Work packages & agent delegation** — per-milestone or
   per-subsystem packages, each with its own verification step.
   Parallel agent implementation is explicitly allowed in phase C —
   the one place in the chain where it is — but packages that touch
   the same files stay serialized.
6. **Toolchain pin** — the exact platform / IDF version the port
   builds against, pinned project-locally.

Show inline, iterate, same approval gate as §3. On approval, write
`port/plan.md` and move to §5.

### 5. Implement (phase C — agents allowed)

Execute the plan against `<workspace>/source/`:

- Work package by package. A package is done when its verification
  step passes (host-side compile, unit check, or static evidence —
  real-hardware evidence belongs to the downstream milestones).
- Keep a running delta audit: `git diff --stat` against the upstream
  pin. If the diff grows beyond the plan's change list, stop and
  reconcile — either the plan was wrong (surface it, amend plan.md
  with the user's OK) or the implementation is drifting (rein it in).
- Record durable lessons as you go —
  `<workspace>/references/YYYY-MM-DD-<topic>.md` with a one-line
  provenance header (this skill, date, why). Library quirks,
  build-flag discoveries, upstream API surprises: anything iteration
  2 or the next port would otherwise rediscover.
- Never claim hardware success from this phase. The port is
  "implemented", not "working", until the downstream gates pass.

### 6. Hand off to the build chain

When the plan's packages are implemented and the tree builds locally
(or the first milestone's package is ready, for milestone-by-milestone
runs), hand off. Tell the user, in their language:

> "The port is implemented through `<milestone/package>`. Run
> `firmware-build` next — it compiles `source/` and writes the build
> manifest; then `firmware-deploy` flashes and verifies the boot
> banner on the real device. The milestone gate loops back here for
> the next milestone until the ladder is done."

Downstream behaves exactly as in the from-scratch lane: build detects
the toolchain from the tree, the manifest carries the identity block's
name/version/SKU, deploy's boot gate matches the shim's banner, and
the acceptance walkthrough at the end uses `port/survey.md`'s feature
inventory and MVP bar as its checklist. If a build or runtime fix
loop kicks in, `firmware-codegen`'s fix mode is port-aware — it
patches minimally against the error log and `port/plan.md`, never
"regenerates" upstream code.

## Hardware catalog handling

Same contract as the rest of the chain: the catalog at
`../../shared/hardware-catalog.md` is the single source for what
hardware exists. If the catalog is a placeholder (per the detection
rule in `firmware-brainstorm`), warn once and write the survey's
module mapping in general categories (Core / Expand / Control /
Power) — but flag that the plan phase needs the real catalog, since
pin-level porting decisions can't rest on categories.

## Forbidden behaviors

- Do not re-architect the upstream. If the port can't be expressed at
  the upstream's own board seam, say so and scope down — don't fork
  the architecture.
- Do not make core edits outside the plan's change list, and do not
  make any code edit before `port/plan.md` is approved.
- Do not ship copyrighted OS images, BIOS blobs, proprietary fonts,
  or media. Build from source; the user supplies their own media.
- Do not strip upstream license headers, NOTICE files, or
  attributions — they travel with the port. (Upstream commit trailers
  and credits are upstream provenance; keep them.)
- Do not take hardware facts from anywhere but the public catalog,
  and do not silently patch a pin/address/chip fact when sources
  disagree — surface the disagreement.
- Do not mutate a shared toolchain install to suit the port — pins
  are project-local.
- Do not exit a milestone on "it flashed" — every exit gate is
  serial/behavior evidence on the real device, enforced downstream.
- Do not emit version strings that drop the upstream version. The
  banner version is always the normalized upstream `x.y.z` core plus
  `-A<NNN>` — a port pretending to be `0.1.0` breaks store
  traceability and user trust in equal measure.
- Do not pin coupled repos with placeholder SHAs. Publish or resolve
  the dependency first, capture the real SHA, then pin it.

## Tone

The user brought a project they already like — respect that, and
respect the upstream: credit it plainly, keep its notices, and talk
about the port as *adding an Attaky target*, not "fixing" someone's
firmware. Be concrete and decisive about the route (seam, milestones,
scope); the user owns the destination (which features matter, what
MVP means to them). No jargon walls: when a technical constraint
bites (license, missing module, PSRAM), explain it in one plain
sentence and give the options.

## Reference files

- `references/survey-template.md` — the seven-section survey
  structure with per-field fill instructions. Load before drafting §3.
- `references/plan-template.md` — the six-section plan structure,
  including the load-bearing identity block and the milestone-ladder
  rules. Load before drafting §4.
- `references/porting-pitfalls.md` — recurring porting traps by
  subsystem (display, input, serial/USB, memory/flash, scope), with
  cross-links into the plugin's shared docs. Read before writing the
  plan, and again when a downstream fix loop stalls.

• SKILL.md 19 KB
• references/plan-template.md 5 KB
• references/porting-pitfalls.md 6 KB
• references/survey-template.md 5 KB