Docs · Operate
Most installs die because nobody knows the day-2 ritual. There is exactly one loop, it has four steps, and agents run almost all of it. This page is the whole ritual — plus the five things worth having written down by the end of your first week.
You provide intent and approve proposals. Agents read the records, watch for the moments that produce a durable entry, and keep the files honest.
It reads project-context/NOW.md, searches DECISIONS.md and LEARNINGS.md for the task topic, and follows only relevant links into evidence. This happens automatically in harnesses that discover the installed skill; the managed block in AGENTS.md / CLAUDE.md routes every other agent to the same protocol.
The trigger script detects the window: work has landed since project context was last updated. Judging what fired stays with the agent, against three triggers — the state a next contributor would act on changed, a choice now constrains future work, or evidence changed what is believed and it will recur. The agent proposes the entry; when nothing fired, ack records that honest outcome instead.
NOW.md is updated to what is now true: stale state replaced, not appended to, and Last reviewed set. Decisions and learnings are appended only if they were earned — a real constraint with its reason, a verified lesson with its evidence. Reversals supersede the old entry; nothing is silently rewritten.
Read-only, always. It checks the documents, the evidence anchors, and whether the protocol can still reach an agent at all. It flags; it never rewrites. A doctor that edited your judgement would defeat the point of having one.
The script can only detect that work has landed since the context was last updated. Whether a decision or a learning actually fired is a judgement, and the judgement stays with the agent reading the protocol.
At session start and before a session ends, the agent checks whether work has landed that the context has not seen. A hook can run this automatically; it also runs by hand:
python3 .agents/skills/project-context/scripts/context_triggers.py status
The session capped API retries at three with backoff, after unbounded retries took staging down. The window is open, and the agent walks the triggers: a choice was taken over a viable alternative — that constrains future work. It proposes a decision entry with the rationale and the evidence; you approve; D-002 lands in DECISIONS.md and NOW.md is updated. Updating the record is what closes the window — no ack involved.
A typo pass across the docs. The window is open — work landed — but no state a next contributor acts on changed, no choice constrains anything, no evidence changed a belief. Silence is a valid outcome, and it gets recorded rather than papered over with a padded entry:
python3 .agents/skills/project-context/scripts/context_triggers.py ack --note "typo pass across docs; no decision or learning"
An ack stores what was acknowledged against the current commit. The window reopens on the next commit — and as soon as uncommitted work appears that the acknowledgement never saw. It can record an honest evaluation; it cannot become a standing way to skip one.
Run it when context looks stale, contradictory, or hard to navigate. A fuller doctor reference — every check by name, the JSON shape, exit codes, CI — is a page of its own, coming to this docs set.
Required core files, installed scaffold version, freshness of NOW.md, duplicate decision and learning IDs, broken relative links.
path@commit pins a citation. evidence-drift warns when the cited file changed since — the justification may no longer hold; re-verify, then re-anchor or supersede. evidence-unverifiable warns when the commit is unknown.
The managed instruction block, a harness skill pointer, or a working session hook must still deliver the protocol into a session. no-delivery-path is an error — perfect files that nothing ever loads would otherwise report healthy.
python3 .agents/skills/project-context/scripts/context_doctor.py --target .
Not aspirations — artifacts. A project that has these five by the end of week one has actually adopted the tool; the loop above produces all of them as a side effect of normal work.
An entry in DECISIONS.md recording a choice this week actually made — with a rationale a stranger could evaluate, not just the verdict.
Something verified the expensive way — a root cause, a failed approach, a disproved assumption — recorded with the evidence that proved it, so nobody pays for it twice.
Open it cold: can someone who was never in the room tell what is in flight, what is blocked, and what the next concrete step is? If yes, the handoff already works.
At least one path@commit anchor on a decision or learning that matters, so drift on that justification becomes visible instead of silent.
The doctor reporting healthy — documents intact, anchors verified, and at least one live route delivering the protocol into a session.
The loop is the same whether the folder holds source files, a manuscript, or a research corpus — see how it plays out beyond code, or head back to the docs hub.
Clarity comes with context.