A conversation that produces a repository's agent instructions: a small verified block inside . The user brings rules they want followed — governance, security, standards — and the repository supplies the rest, verified.

Conversational always; the user approves every write.

Args: intent ( | | | | ); a target repo or path; extra source paths or URLs.

No writes until step 5!

Read , harness or agent specific rule files, docs folders, and any notes carrying lessons. Report what exists and how it measures up, per .

Existing instructions are the baseline being improved, never raw material to discard. Open a ledger: one entry per existing section and per independently meaningful instruction, opened at or , carrying what an agent would get wrong without it. Entries settle as evidence arrives in steps 2–4 — , each with its reason, its evidence, the risk if it goes, a destination for a relocation, and an approval flag. Deletion needs one of the four grounds in , and a relocation destination must itself be loaded or sit behind an observable trigger — a move into a file nothing reads is a deletion and needs its ground. Setup has nothing to map and opens no ledger; refresh opens entries for the lines it proposes to change or remove, the block's own included. A lesson found outside the instruction files — a warning in a README, a notes file — is an ordinary candidate, not a ledger entry.

If the target contains separable units — a workspace manifest listing members, or directories carrying their own build manifest — name them and ask whether this run covers the root only, all of them, or which. Absent that evidence, do not ask. Sibling repositories are not children; each is its own target, offered in turn.

Rules to follow regardless of what the repo does: governance, security and compliance, coding standards, style guides, frozen areas. Ask for outside documents too — handbooks, wikis, architecture docs, MCP knowledgebases. Note the paths; do not read them yet.

Greenfield: this is the whole content. Brownfield: it is the half no scan reaches.

Fan out with parallel subagents against what the sections need — executable config and CI for policy and for what they already state, tracked source for conventions and boundaries, targeted history for constraints whose reason must still hold.

, a , , contribution guides, pull request templates, and CI config are read to know what the block must not repeat. Their caveats come from the human in step 4. Path-check every claim naming a file. For every claim the block will make about what a command does, read the target or script that runs it and verify the claim.

Each child agreed in step 1 is scanned as its own scope, against its own manifests.

Only what no scan reaches: what agents keep getting wrong here, what is off limits, what a domain term means, why a constraint exists.

Compose against . For each candidate, ask first whether a hook, lint rule, or CI check enforces it better than prose; if so propose the check, and the line becomes the fallback if they decline. A ledger entry marked keeps its instruction until its check is in place (a later run deletes the line under ground 2 once the check is live).

Show the complete block before writing it, and every child block alongside it — one approval covers the set. Present the settled ledger with it: replacement text alone is an incomplete proposal, because it shows what the user gains and hides what they lose. Every existing instruction appears with its decision and reason. Retains and rewrites that keep the full rule may be grouped. If a rewrite weakens, narrows, or drops part of a rule, treat the lost part as a deletion and list it separately. Keep the rule itself; examples may explain it but cannot replace it. Every relocation, automation, and deletion is itemized. A deletion resting on none of the first three grounds is held for line-item approval — approving the block never approves it — and a declined deletion, relocation, or automation reverts to retain. On approval, splice between the markers — the splice itself touches nothing outside them. Text outside the markers changes only through a settled ledger entry or a proposed fix the user has seen, never as a side effect of the splice. Fill each provenance line with today's date and the verified SHA.

Where an instruction elsewhere contradicts the block in a way that changes behavior — a stale line, a retired command — propose the fix to that file. Two live contradictory instructions is a defect.

Never commit.

Same steps, step 1 as a diff. Read the provenance line, re-verify every path and every caveat, and run since the recorded SHA against every line — update or remove lines whose evidence is gone. Every proposed removal is a ledger entry shown in step 5, never a silent edit, and handwritten instructions outside the block are treated as in adoption — any proposal touching them enters the ledger. Never re-ask what a prior run settled; the interview shrinks to what changed about how the team works. The block grows only on new evidence.

Refresh against instructions this skill has never touched. Nothing was settled by a prior run, so the full interview applies — and the file itself is maintainer testimony, so the ledger is the run's main output: the user should be able to read it and see where each of their instructions went.

The proposal states what remains of every file instructions were moved out of — commonly a reduced to , once that import is verified for every harness in use, like any loading mechanism. No instruction lives in two loaded files, where it is paid for twice; a duplicate, verbatim or reworded, is kept once — the block keeps the survivor — and that settles both entries.

Seeded from a spec or planning document, or interview alone. Commands that do not exist yet are written as explicit TODOs naming the decided stack, never a guessed invocation stated as fact, and verified on the first refresh after code exists. A genuinely contested design decision — real tradeoffs, multiple viable shapes — goes to .

If the target has a from the retired skills, commonly under , read it in step 1 and offer to absorb its content. Do not delete it without agreement, and do not silently orphan it.

Capture one observed agent mistake as it happens — the only admissible source for a pitfall.

Take the task, the mistake, the correction, and its evidence. Check the block for a line already covering it. One occurrence is noted; a recurring or costly mistake earns a line now — an exact invocation under Running and verifying when it is a command error, otherwise a pitfall. Write it and show the diff. If it is mechanically preventable, propose the hook, lint rule, or CI check instead.

Re-check every caveat, path-check every file, follow every pointer, and ask of every line whether removing it would change agent behavior. Verify each command claim against the target or script that runs it. Check for contradictions with other instruction files.

Failing lines get fixed, move behind an observable trigger, or become ledger entries: a removal needs one of the four grounds in , presented and settled as in step 5 before anything is removed. A policy or pitfall goes only when the thing it guards is gone or the user retires it; nothing failing lately is not grounds. Audit ends smaller or equal.

A component, nested repository, or extracted rules file gets its own file under the same shape when work keeps landing there and every condition holds: its rules are subtree-exclusive, they are substantial (a handful of rules is not a file), the split materially reduces the parent block, the loading mechanism is verified for every harness in use — checked, never assumed — and the user approves the split. Even with verified loading, keep a rule at the root when it must apply before a session enters that directory or when breaking it can affect work outside the child. Otherwise the rules stay in the parent block as path-qualified lines ("in : ..."), which cost less than a file nobody loads. Why the loading check: .

Use a linked file only when the trigger is not a path.

A chosen child that ends with nothing its parent does not already say gets no file. Say so and move on.

List every child in the parent's Where things are with one line and its path. Discovery never depends on the harness finding it.