Most installs die because nobody knows the day-2 ritual. There is exactly one loop, it has five 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.
read
capture
detect
update
verify
01the loop
Five steps, most of them automatic
You provide intent and approve proposals. Agents read the records, watch for the moments that produce a durable entry, and keep the files honest.
Before substantial work — the agent reads the record
It runs project-context context --task "<one line>" --files <paths> and reads the packet that comes back: the owner's constraints, the current state, then the decisions, learnings and questions whose evidence anchors share a path with the files it named — ordered rather than ranked, because a packet that led with a builder's own notes would bury the constraint that was not negotiable. Where the CLI is not available it falls back to reading NOW.md and PLAN.md, searching the registries, and following 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.
During work — whatever surfaces is captured, not judged
Whenever something worth keeping surfaces that is not yet a registry entry — a choice you are unsure constrains anything, a result you have not generalised, an assumption you proceeded on — the agent runs project-context capture rather than stopping to decide what it is. One short, dated, attributed note lands in project-context/inbox/, at most 200 words. Promoting or dropping those capsules is a milestone step, and project-context review lists the ones still waiting.
During work — trigger detection watches for durable records
The trigger script detects the window: work has landed since project context was last updated. The agent evaluates seven trigger families — current state, decisions, learnings, unresolved questions, task progress, design proposals, and incidents. When one fires, project-context record creates the durable operational entry; when nothing fired, ack records that honest outcome instead.
At the end — the record is brought up to date
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.
When state may be stale — the doctor runs
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.
02trigger detection, worked
One session where a trigger fires, one where nothing does
The script can only detect that work has landed since the context was last updated. Whether any of the seven trigger families actually fired is a judgement, and the judgement stays with the agent reading the protocol.
Check the window
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:
The session capped API retries at three with backoff, after unbounded retries took staging down. The window is open, and the agent walks all seven trigger families. A choice was taken over a viable alternative, so it runs project-context record --kind decision with the rationale and evidence. D-002 lands in decisions/, its registry link lands in DECISIONS.md, and NOW.md is updated. Writing the earned record closes the window — no ack involved.
Session two — nothing fires
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:
record an honest “nothing fired”scroll →
$python3.agents/skills/project-context/scripts/context_triggers.pyack--note"typo pass across docs; no decision or learning"
why ack cannot become a skip button
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.
03the doctor, in brief
Nine families of checks, all read-only
Run it when context looks stale, contradictory, or hard to navigate. Every check by name with its severity, the JSON shape, the exit codes and the CI wiring are settled and written down.The builder's guide →
The install itself
Required core files, and the marker beside them: its schema, the product that wrote it, and the one version number that product reads from its own VERSION. template-update-available warns when yours is behind the release, and names the command.
Records conform
A detail record carries six required frontmatter keys and nothing else required. Status is checked against that record's own kind rather than a union of every vocabulary, so a learning cannot borrow a task's status. References are parsed, not trusted: session:, commit: and pr: must be shaped the way the grammar says.
Every operational kind has a writer
A full install must carry context_record.py, the safe writer for decisions, questions, tasks, designs, and incidents. missing-record-writer means the folders exist but agents have lost their supported write path; update before trusting automatic maintenance.
The registries stay navigable
Freshness of NOW.md against --stale-days, duplicate decision and learning IDs, and broken relative links.
Evidence anchors
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 pushed set is still what was pushed
Where an owner pushes global/ and blueprint/ to you, each copy is verified against the digest the push stamped. pushed-file-modified is an error — and it is the one doctor error you can trigger by editing a file you were handed. If you disagree with something pushed to you, do not edit it: your change would be overwritten by the next sync without the owner ever learning you objected. Raise a question in your own project-context/, and it reaches them the next time they pull.
Plan and epic agree
Every PLAN.md item names the blueprint/EPIC.md item it serves. The pair is enforced asymmetrically on purpose: a plan item serving no epic item is an error, because the project is spending effort the epic never asked for; an epic item no plan item serves is only a warning, because an epic is allowed to run ahead of the current milestone. A repository with no blueprint/ has no epic, and PLAN.md stands alone.
Nothing half-upgraded is left silent
An install still carrying the older Context Hub marker or its instruction block is recognised and reported, rather than quietly passing as healthy.
Reachability
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.
The doctor tells you what is wrong. review tells you what is waiting — proposed records, questions open past their window, unpromoted capsules, assumptions nobody confirmed, drifted anchors, a stale NOW.md, a pushed snapshot the owner has not refreshed — oldest first, because latency is the failure mode of a system where nothing moves until someone looks. It exits zero whatever it finds: CI that breaks on an open question teaches people to stop filing them.
The registry indexes are derived tables — they let an agent find the entries that constrain a task without reading either registry end to end, and a stale one is worse than none, because it is trusted. A hand-edited index is overwritten; --check exits non-zero when they are stale, which is what lets CI hold the line.
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.
One real decision, with its reason
An entry in DECISIONS.md recording a choice this week actually made — with a rationale a stranger could evaluate, not just the verdict.
One learning, with evidence
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.
A NOW.md a stranger could act on
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.
One anchored evidence link
At least one path@commit anchor on a decision or learning that matters, so drift on that justification becomes visible instead of silent.
One clean doctor run
The doctor reporting healthy — documents intact, anchors verified, and at least one live route delivering the protocol into a session.
05next
Where to go from here
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.