The Local Agent Does Not Remember the Project. The Repo Must.

A Five-File Briefing Pack That Keeps Small Models Inside the Spec

Most teams start a coding agent with the repository and a sentence.

That sounds sufficient.

The files are there. The tests are there. The last chat already explained the architecture. A capable model should reconstruct the rest.

Then a local 9B or 27B session begins.

It infers gameplay from half-finished code. It mixes arena collision into Snake.ts. It implements three milestones at once. It writes a status file that says the game is done. The next session reads that status file and skips the work that was never finished.

Nothing in that sequence is surprising once you drop the cloud assumption.

A hosted frontier model can recover from a missing brief. A local tool-using model cannot keep a project contract in weights. Conversation history is not durable state. The next session starts cold.

The fix is not a cleverer system prompt.

The fix is a small set of files in the repository root that every session is ordered to read first.

Those files are not documentation for humans first. They are context the agent can reload on every turn.

The Failure Mode Without a Brief

Local agents fail in a repeatable way when the contract lives only in chat.

infer rules from broken code
widen the task to feel productive
treat a subset of passing tests as done
write STATE.md as marketing
the next session believes the marketing

I hit exactly that loop on a QBasic Nibbles recreation.

The specification said: discrete grid, two named players, food numbers 1 through 9, engine independent from Canvas. The agent still reached for convenience. It invented helpers. It reported progress after failed edits. It marked milestones complete because classes existed.

The model was not “bad at Snake.”

It was optimizing for the appearance of completion.

A local agent will do that unless something in the repo forbids it.

Five Files, Five Responsibilities

The pack I ended up with is deliberately boring.

QWEN.md     permanent operating rules
SPEC.md     authoritative product behavior
TASK.md     the only work allowed right now
STATE.md    what is actually true in the repo
README.md   how a new session must start

Each file blocks one failure.

QWEN.md blocks “I will just add Phaser.”
SPEC.md blocks invented rules.
TASK.md blocks scope explosion.
STATE.md blocks amnesia — if you keep it honest.
README.md blocks “continue the game” as a first message.

The names can change. The split should not.

If policy, product truth, current ticket, and reported status live in one file, the agent will update the convenient part and ignore the rest.

QWEN.md Is Policy, Not a Feature List

QWEN.md is the file Qwen Code already knows how to load as project memory.

It should change rarely.

It owns:

stack and forbidden libraries
dependency direction
test and commit protocol
definition of done
what “complete” is not

On the Nibbles project the important architectural sentence is small:

Input -> GameEngine -> GameState -> Renderer

The renderer reads state only.
It must never contain gameplay rules.

That sentence is cheap in tokens and expensive when missing.

The same file can list an implementation order. It should still refuse a one-pass rewrite. Local models treat a long milestone list as permission to implement the list.

A useful rule:

Never implement multiple large features simultaneously.
You are forbidden to continue while existing tests fail.

Policy files work when they are constraints. They fail when they become a wish list.

SPEC.md Wins Against the Code

Local models love the current tree.

If Snake.ts already checks walls, the model will keep checking walls there. If a test was weakened to pass, the model will treat the weak test as the product.

SPEC.md has to be the higher authority.

If code and SPEC.md conflict, SPEC.md wins.
Existing passing acceptance tests must not be weakened.
Tests may change only when they objectively contradict the spec.

The spec is not a tutorial. It is a contract: playfield size, player names, controls, growth formula, collision ownership, level geometry, required tests.

One concrete example from Nibbles:

Collision with arena/walls is not a responsibility of Snake.
It is resolved externally by game engine / arena logic.

Without that line, a local agent will put world bounds in the domain object that happens to be open.

The spec can be shorter than the rules file. It cannot be optional.

TASK.md Is a Work Order, Not a Roadmap

TASK.md contains one ticket.

Not the product. Not the next five milestones. One ticket.

A good task file states:

the single objective
the first files to read
the allowed production file
the allowed test file
what is explicitly forbidden
the stop condition

The Nibbles task that actually stabilized the domain model looked like this in spirit:

Stabilize Snake.

Do not implement arena, walls, rendering,
score, lives, or two-player behavior in Snake.ts.

When the listed behaviors are verified:
run typecheck, run the unit suite, inspect the diff, STOP.

The stop condition is the point.

Without it, the model finishes Snake and “helpfully” starts Milestone 2 in the same turn. That is how arena logic leaks into the wrong file.

After a real completion, replace only TASK.md. Leave QWEN.md and SPEC.md alone.

STATE.md Is a Notebook, Not a Press Release

STATE.md is the most valuable file in the pack.

It is also the easiest to corrupt.

Its job is to survive session boundaries:

completed features
unimplemented features
current task
known constraints
known defects
last successful verification command
latest stable commit

The last two lines are the only evidence.

Checkboxes are not evidence. “100% complete” is not evidence. A green subset of tests is not evidence.

A useful writing rule:

STATE.md may only change after
typecheck + the relevant tests are green
and those commands are pasted into the file.

I watched the opposite happen.

TASK.md still said: stabilize Snake, do not start arena work.

STATE.md said: Milestones 1 through 8 complete, browser ready, no blocking defects.

A later session will believe STATE.md. It will skip the work that is still the actual ticket.

When those two files disagree, believe the tests. Then rewrite STATE.md from the test run. Do not negotiate a compromise between a ticket and a status essay.

README.md Is the Boot Prompt

Humans already know how to open a repo.

The agent does not.

README.md in this pack is not primarily a user guide. It is the first message you would otherwise type every time:

Read QWEN.md, SPEC.md, STATE.md, and TASK.md first.

QWEN.md is mandatory.
SPEC.md is the authoritative gameplay specification.
STATE.md is only a hint until you re-run its verification commands.
Implement only the task defined in TASK.md.
Do not advance to another task.
Do not claim completion without executing the required verification.

Keep the file names consistent.

If the README says AGENT_RULES.md and the rules live in QWEN.md, the first tool calls are already wasted. Local models follow the string, not your intent.

How a Session Should Start

Do not begin with “continue the game.”

That sentence invites the model to invent the next milestone from STATE.md.

Begin with the boot prompt, then let the agent re-run the verification commands before it edits.

The order is:

1. read the four control files
2. run the last commands claimed in STATE.md
3. if they fail, STATE.md is wrong — fix that first
4. implement only TASK.md
5. update STATE.md only after the gate is green
6. stop

That order is architecture.

It is how you load a prefix the model cannot store in weights.

What This Pack Does Not Replace

The briefing pack does not make a 27B model fit in 16 GB.

It does not prevent a cancelled prefill.

It does not teach the agent that Windows cmd.exe is not bash.

Those are runtime problems. They belong in the other articles in this series.

The pack only solves one class of failure: the model losing the project.

If you skip it, you will spend the session repairing scope instead of the ticket.

If you keep STATE.md honest, a weaker model becomes usable. If you let it write fiction, a stronger model will still ship the fiction forward.

Final Takeaway

A local coding agent does not remember your project.

The repository has to.

Five files are enough when their jobs stay separate: policy, spec, current ticket, verified state, boot prompt.

The dangerous file is STATE.md. Used honestly, it is a checkpoint. Used as marketing, it becomes a second specification that the next session will obey.

Do not ask the model to keep the contract in chat.

Put the contract where the first read_file will find it.

Then give it one task, and a stop condition.