# AI Firmware as an agent boot layer

Consult when setting up a new agent repo, or when deciding where a durable lesson should live so
every future project inherits it instead of relearning it. AI Firmware is a portable boot layer:
a small always-loaded kernel, on-demand skills, committed reference memory, session hooks, and
sync scripts. Distilled from the CoreWise guide `firmware-not-folklore`. Template lives at
`github.com/ryanportfolio/AI-Firmware`.

## The five layers and where each thing goes

Each kind of knowledge gets the cheapest home that still works. Always-loaded instructions are a
tax paid on every request, so keep the kernel small.

| Layer | When it loads | What belongs there |
| --- | --- | --- |
| Kernel | Every turn, so it stays small | Safety and process rules that apply everywhere, only |
| Skills | On demand, when a task triggers them | Long playbooks and repeatable procedures |
| Reference memory | When consulted, committed to the repo | Project quirks, pitfalls, commands |
| Session hooks | At boot | Cheap startup checks and drift nudges |
| Sync scripts | When you run them | Improvements moving between projects |

## Sort every durable lesson before saving it

When a lesson proves durable, decide its layer first:

- Discipline that applies everywhere goes in the kernel. Rarely.
- A repeatable procedure becomes a skill.
- A project quirk goes to reference memory.

Getting this wrong costs both ways: always-loaded rules you rarely need bloat every turn, and
on-demand files the agent forgets to consult go unread. Auditing and shrinking the always-loaded
weight is the job of the `stop-hitting-your-token-limit` guide; the template ships a script that
measures that weight so a fat kernel shows up as a number.

## Why committed memory, not chat transcripts

Lessons in transcripts stay on one machine and vanish when the session ends. The next session,
the next repo, and the cloud sandbox all start over. Committed reference files travel with every
clone and get read by whichever agent opens the project next. Route durable knowledge with the
`recall` skill.

## What ships in the template

Skills are the installable playbooks. The load-bearing ones:

- `recall`: routes durable project knowledge (pitfalls, commands, architecture) into committed
  reference files and consults them before unfamiliar work.
- `verification-before-completion`: demands evidence before any claim that something works.
- `systematic-debugging`: forces reproduction before fixes.
- `caveman`: the token-saving prose mode.
- `init-project`: guided setup for a fresh project.

Session hooks re-assert active defaults at boot and check whether the template has improved since
the repo was spawned.

## Two agents, one hard boundary

Claude Code gets the full system: kernel, hooks, skills, automation. Codex gets its own
instruction file and thin adapters pointing at the same master skill files, generated by a sync
script, not hand-maintained. Share the playbooks; do not share the automation. Auto-commit and
hook rules that are safe under Claude Code become unsafe if another runtime inherits them blindly.

## Spawn and initialize

Create a repo from the template, open it, run the initializer, be working inside about 5 minutes.
The initializer detects languages and tools, asks a short round of questions about verification
and deployment, seeds reference files, prunes skills that do not apply, and commits. The project
starts with the full discipline installed.

## Keep spawned repos in sync both ways

Spawned projects freeze the template at spawn date. A hook checks every 7 days whether the shared
setup has drifted. The sync skill closes the gap in both directions:

- Pull the template's improvements into the project.
- Push a lesson that proved generic back up to the template, where every future spawn and every
  synced sibling inherits it.

A gotcha hit once in one repo becomes shared setup everywhere.

Source guide: site/src/content/guides/firmware-not-folklore.mdx