MonoMind project-context

Docs · The records

Three core summaries, each answering one question.

The core profile starts with three Markdown summaries. The full profile adds five writer-backed operational kinds: decisions, questions, tasks, designs, and incidents. This page shows what belongs in each layer and how agents keep it current.

  • NOW.md
  • DECISIONS.md
  • LEARNINGS.md
01 what a stock install lands

Nineteen files, three core summaries you can read at a glance

A core install adds one readable directory, the protocol that maintains it, and the wiring that delivers the protocol into a session. The three summaries at the top are the starting point; the writer and checks below keep them and the full profile's operational records honest.

your-project/ 19 files 
your-project/
├── AGENTS.md                        ← managed block added, or refreshed in an existing file
├── CLAUDE.md                        ← the same block; install creates whichever is missing
├── project-context/
│   ├── NOW.md
│   ├── DECISIONS.md
│   ├── LEARNINGS.md
│   ├── SKILL.md                     ← the operating protocol, readable in place
│   ├── README.md
│   └── .project-context.json
├── .agents/skills/project-context/
│   ├── SKILL.md                     ← same protocol text; the two can never disagree
│   ├── VERSION                      ← the one version number, read by the doctor
│   ├── agents/openai.yaml
│   └── scripts/
│       ├── context_packet.py        ← assembles the packet an agent reads first
│       ├── context_capture.py       ← writes one capsule into inbox/, nothing else
│       ├── context_record.py        ← safely writes decisions, questions, tasks, designs, and incidents
│       ├── context_review.py        ← lists what is waiting on a person
│       ├── context_triggers.py      ← detects the window where a record is owed
│       ├── context_index.py         ← regenerates the derived registry indexes
│       └── context_doctor.py        ← the read-only health check
└── .claude/skills/project-context/
    └── SKILL.md                     ← pointer so Claude Code discovers the skill

core profile · zero runtime dependencies · stdlib Python 3.10+

The full profile adds PLAN.md and QUESTIONS.md, and the decisions/, questions/, tasks/, inbox/, designs/ and incidents/ subfolders, each with a README and a template — thirty-three files in all. Agents use project-context record to create the five operational kinds with stable IDs and provenance; inbox/ holds capsules whose classification can wait. The three core summaries stay the same either way. Two more folders appear only when an owner pushes to you — global/ and blueprint/, the read-only pushed set, authored elsewhere and never edited here. Project Hub →

02 NOW.md

What is true now, what is active, and what happens next?

The first thing the next person or agent reads. It holds exactly the state a stranger would need to act — nothing that git history already knows.

project-context/NOW.md real example

Current Project State

Last reviewed: 2026-08-26

Snapshot

Area Current state Evidence
Evidence scope The report uses public studies published through 2025-12-31. D-001

Active work

Initiative Status Next action Evidence
Findings synthesis in-progress Resolve three claims that lack page-level citations. L-001

Blockers

None.

from the shipped example — a research report, not code

not a changelog

Git already records what changed and when. NOW.md records what a next contributor would act on: what is in flight, what is blocked, and the next concrete step. If a line only describes the past, it belongs in a commit message.

How it changes over time

It is replaced, not appended to. When work lands, stale state is removed once its durable result is linked, and Last reviewed is set to today. The file stays around a screenful forever; its history lives in version control.

a good entry

Active work

Findings synthesis: in-progress

Next: resolve three claims that lack page-level citations. L-001

State a stranger could act on: what is in flight, and the next concrete step, with a pointer at the evidence.

a bad entry

Updates

14:20 fixed typos in the intro

15:05 reran the bibliography export

16:40 more edits, see commit log

A changelog of edits. Git already knows all of this, and none of it says what happens next.

03 DECISIONS.md

Which accepted choices constrain future work, and why?

The choices already made and the reasoning behind them, so later work builds on them instead of quietly undoing them. Every entry has a stable ID other records can point at.

project-context/DECISIONS.md real example

D-001: Set an evidence cutoff

Status: accepted

Date: 2026-08-05

Decision: Include public studies published on or before 2025-12-31.

Rationale: Keep the review reproducible while the first report is drafted.

Consequences: Newer evidence is logged for the next review rather than silently added.

Evidence: docs/research-protocol.md@8c41f2e

ID · status · date · decision · rationale · consequences · evidence

not a design doc

The registry holds the constraint and the reason, and points at the design. The full architecture, the rejected alternatives, the diagrams — those live in a design document the entry links to. An entry a future contributor may freely change is not a decision at all; leave implementation details out.

How it changes over time

Decisions are superseded, not deleted. Reversing or narrowing one means a new entry with a supersession link; the old entry keeps its ID, its status becomes superseded, and it remains readable as historical evidence. History is corrected through status, never rewritten.

a good entry

D-001: Set an evidence cutoff

Decision: include public studies published on or before 2025-12-31.

Rationale: keep the review reproducible while the first report is drafted.

The constraint and the reason. Anyone can now tell whether new work violates it — and whether the reason still holds.

a bad entry

D-002: Report generator architecture

The generator runs three passes. Pass one tokenises the corpus into…

(forty more lines of design)

A design doc pasted into the registry. Record the constraint, give the reason, and link the design instead.

04 LEARNINGS.md

Which verified lessons should future collaborators reuse?

What was tried and what it actually taught you — kept separate from what everyone merely believes to be true. An entry earns its place by being reusable and verified; evidence is required.

project-context/LEARNINGS.md real example

L-001: Capture claim-level provenance

Status: accepted

Scope: evidence synthesis and collaborative editing

Learning: A bibliography entry alone does not show which source supports a specific claim.

Action: Record a page, section, table, or dataset locator for every material claim.

Evidence: Editorial review found three claims that could not be traced from the bibliography alone.

verified once, reused by every later session

not a diary

Not a log of what a session did, and not a place for hunches. An entry earns its place by being reusable beyond the task that produced it and verified by evidence — an observed result, a reproduced failure, a review finding. If nobody verified it, it is a belief, and beliefs do not go in the registry.

How it changes over time

An entry stands while its evidence holds. When the cited material changes — the doctor flags this as drift — the lesson is re-verified, then re-anchored to the current state or superseded. Like decisions, learnings are never silently rewritten.

a good entry

L-001: Capture claim-level provenance

Learning: a bibliography entry alone does not show which source supports a claim.

Evidence: editorial review found three claims that could not be traced.

Verified by a real finding, and reusable on every future claim — not just the three that triggered it.

a bad entry

L-002: Long day on the export bug

Spent most of Tuesday chasing the export bug. Frustrating.

Might be the encoding? Will look again tomorrow.

A diary entry: no evidence, nothing verified, nothing the next person can reuse.

05 writer-backed operational records

Five kinds agents write when the work earns them

These are not empty filing cabinets people must remember to fill. The installed protocol names seven trigger families, and project-context record handles stable IDs, frontmatter, provenance, filenames, and registry links for every operational kind.

decisions/ — a choice constrains future work

Written when one viable option wins over another. The writer also adds the durable link to DECISIONS.md.

questions/ — work depends on an unresolved answer

Written before a silent assumption turns into implementation. The writer also adds the question to QUESTIONS.md.

tasks/ — substantial work has a lifecycle

Created when work gains a plan, progress, validation, or outcome, then updated through proposed, active, and a terminal state.

designs/ — a proposal needs alternatives and validation

Written before implementation makes a structure or interaction implicit, with the accepted direction linked to the decision it produced.

incidents/ — a material failure needs correction

Starts with impact and evidence, then accumulates root cause, recovery, prevention, and verification as they become known.

one supported write path

project-context record --kind decision|question|task|design|incident is what agents call after a trigger fires. The command is create-only and idempotent; the doctor reports missing-record-writer if a full install has these folders but lost the writer.

06 capture and the inbox

When classification can wait

A choice worth recording almost always surfaces mid-task, and stopping to write an entry with an ID, a rationale and consequences is exactly the interruption a person declines. So project-context capture writes one short, dated note into project-context/inbox/ and stops. Deciding what it is happens at promotion, where it is cheap.

project-context/inbox/ one capsule

kind: capsule

status: proposed

created: 2026-08-26

asserted_by: agent:claude-code

We standardise on pnpm; npm workspaces could not hoist the native dependencies.

Evidence: commit:git:8c41f2e

at most 200 words · the command refuses a longer one

not a fourth registry

Every capsule is kind: capsule; --kind — decision, learning, question, assumption, constraint, proposal — only says what the note is about. Provenance is recorded without being asked for: the actor from your git identity, the harness and model where the tool knows them, and the current commit as evidence. The same text twice on the same day writes once.

How it changes over time

A capsule is promoted or dropped, never left. Write the registry entry it earns and set the capsule to accepted with a link to what it became, or rejected when it belongs nowhere. Leaving it proposed is the only outcome that is not a resolution — and project-context review keeps raising it until somebody decides.

07 evidence anchors

Pinning a citation to a point in history

Decisions and learnings cite evidence. When that evidence lives in the repository, the citation can be pinned to the exact commit it was verified at — so a later session can tell whether the justification still holds.

docs/research-protocol.md@8c41f2e

The anchor form is path/to/file@commit — a repository-root-relative path at the commit where the evidence was verified. It goes on an Evidence: line inside the entry it supports, or as the target of a Markdown link; the doctor reads both, and checks a linked path with the pin stripped off.

drift

The doctor verifies every anchor. evidence-drift warns when the cited path has changed since the pinned commit — the justification may no longer hold; re-verify, then re-anchor or supersede. evidence-unverifiable warns when the commit is unknown. Anchors are optional and Git-gated: warnings only, never errors.

08 next

Now make it a habit

You know what the three core summaries hold and where the five operational kinds live. The next page is the day-2 ritual: what agents read, which triggers create durable records, and what should exist by the end of week one.

next Operate — the session loop back Docs — getting started

Clarity comes with context.