MonoMind AI Lab · The builder's deck

Project Context

One small folder that keeps builders and agents on the same page over time. Don't work in moments — work in continuity: the state, the decisions and the lessons stay in the repository, in plain Markdown, long after the chat that produced them is gone.

v0.10.0 What it is · What you get · How it works · How to use it github.com/monomind-ai-lab/project-context

Part 1 · Why

A collaborator returning after three weeks should not rebuild the project from stale chats.

Four questions decide whether they can start work or have to reconstruct it. The repository itself should answer all four.

Q1

What is true now?

Active state, blockers, and the next action.

Q2

Which decisions constrain the work?

Accepted choices, with the rationale intact.

Q3

What has already been learned?

Verified lessons worth reusing rather than re-paying for.

Q4

Where is the evidence?

A pinned link to the commit, review, or record that proves it.

↻ Project Context does not copy your project into a second knowledge base. Primary artifacts stay exactly where they belong.

Part 2 · What it is

Not documentation. The record of what the code cannot say.

Documentation explains what the code does — the code already does that. This holds why this approach and not the obvious one, what was tried and failed, and what is in flight right now.

Plain files in your repo

No database, no server, no account. git log is the history and grep is the search. Markdown and Git are the whole storage contract.

Zero runtime dependencies

Python standard library only, 3.10 and later. A repository that adopts this product does not acquire a dependency by doing so.

Nothing is ever rewritten

Every write is create-only. The tool refuses before it overwrites a record you wrote, and history is corrected by superseding it, never by editing it.

It works for software, document, research, writing and mixed projects — anywhere a folder of Markdown can live beside the work.

Part 2 · What it is

Where the context lives.

One durable layer inside the repository it describes. People and agents both read it before substantial work and write to it at a milestone; the artifacts it cites never move.

People & agents

Read the records before substantial work. Write at a milestone or a handoff.

read first · write at milestones

project-context/ — inside your repository

NOW.md

DECISIONS.md

LEARNINGS.md

cites, never copies

Primary artifacts

Source, tests, documents, commits, reviews — pinned as path@commit, so a citation names the state it cites.

↻ The records point at the evidence, never become a second copy of it — and a primary artifact always outranks the note about it. Plain Markdown · Git-tracked · create-only · no network call.

Part 3 · What you get

What lands in the repository.

One small directory, plus a managed block in both CLAUDE.md and AGENTS.md — creating whichever is missing, so no harness is left with rules it never reads.

your-repository/
project-context/
- .project-context.jsonThe marker: schema, version, project id, stamps
- SKILL.md · README.mdThe protocol, and what this folder is
- NOW.md · DECISIONS.md · LEARNINGS.mdThe core profile
- PLAN.md · QUESTIONS.mdThe milestone in flight — full profile
- decisions/ questions/ inbox/Detail records, and capsules awaiting promotion
- tasks/ designs/ incidents/Full profile only
- global/ blueprint/The pushed set — read-only, and absent unless an owner runs a Hub

Everything above global/ is authored here; the last row is pushed by an owner and read-only.

Part 3 · What you get

Three files, one question each.

File	What it answers	When you write it
NOW.md	What is true now, what is active, and what happens next?	The state a next contributor would act on changed. Replace stale state rather than appending; keep it under 400 words.
DECISIONS.md	Which accepted choices constrain future work, and why?	A choice now constrains future work. Reverse one by superseding it — never by rewriting what it meant.
LEARNINGS.md	Which verified lessons should future collaborators reuse?	Evidence changed what is believed, and it will recur beyond this one task. Evidence is required.

The test for a decision is not "was this hard". It is: would someone six months from now redo this badly without knowing? If no, leave it out — you pay for every record on every session.

Part 4 · How it works

Install once, then it runs inside the work.

Install
once

1

The user prompts the agent

One command, or a short prompt pointing at the canonical initializer skill.

2

The agent reviews and classifies

Asks the onboarding question, identifies the project type, finds overlapping context.

3

The user approves the plan

Profile and the exact file changes, proposed before a single write.

4

The agent installs the pipeline

Creates only approved files, preserves existing material, verifies idempotency.

Operate
every session

5

Agents read before later work

The managed block and the installed skill route them into the records first.

6

Agents promote at milestones

Changed state, durable decisions, verified learnings — and nothing else.

7

The next collaborator inherits

Any later person or agent reads the same plain Markdown.

Work produces evidence → milestones promote durable context → the next collaborator starts from it instead of reconstructing it.

Part 4 · How it works

Agent-operated, human-readable.

People provide intent, answer the onboarding and opt-in questions, and approve proposed changes. Agents read the skills, run the tooling, and maintain the files. You are never expected to invoke a skill or run Python yourself.

Person	AI agent
Runs the one-line install, or pastes the short prompt	Loads and follows project-context-init/SKILL.md
Answers whether the project is brand-new and what it is for	Classifies the project type and reviews overlapping context
Approves the proposed plan before anything is written	Creates only approved files and verifies the result is idempotent
Decides what a decision or a learning actually is	Detects that the window is open and asks — it never judges for you
Reads, reviews, or edits the Markdown whenever they like	Maintains the records through later work and runs the checks

Part 5 · How to use it

Two ways in. Both show the plan before they write.

One command, with uvx or pipx

uvx --from git+https://github.com/monomind-ai-lab/project-context \ project-context init --target . --install-skills --dry-run pipx install git+https://github.com/monomind-ai-lab/project-context project-context init --target . --install-skills --apply

No Python tooling? Paste this instead

Install Project Context in the current repository or project folder using https://github.com/monomind-ai-lab/project-context. Read and follow `skills/project-context-init/SKILL.md`, starting with its required onboarding question. Show me the proposed plan and wait for my approval before making changes.

--dry-run

Prints the exact file plan. Nothing is written — read it first, every time

--apply

Creates only what the plan listed, and nothing else. Re-running is idempotent

Part 5 · How to use it

Two profiles, and the smaller one is the default.

Every record is read on every session. You pay for what you keep, so keep less — and take the full profile only when the project already has that much going on.

Flag	What it does
--profile core	The default. NOW.md, DECISIONS.md, LEARNINGS.md, decisions/, plus the protocol in place
--profile full	Adds PLAN.md, QUESTIONS.md and the tasks/, designs/, incidents/, inbox/ directories
--repo-type auto	Detected by default. Also code, document, research, writing, mixed, general — it shapes what the scaffold says
--install-skills	Installs the protocol skill so agents in this repository can find it
--install-hooks	Merges a SessionStart and a Stop hook into .claude/settings.json. Opt-in, implies --install-skills, and every other hook is preserved

Part 5 · How to use it

The loop you actually run.

Before substantial work · assemble the packet instead of reading the folder

During the work

1

project-context context --task "…" --files …

Ordered, not ranked: the owner's constraints, the current state, then the records whose anchors share a path prefix with your files. onboard is the preset for a first session.

2

Capture rather than stop

project-context capture --kind decision --text "…" --apply writes one dated, attributed note into inbox/ and gets out of your way.

3

Keep the authority ladder

Primary artifacts, then curated records, then candidate knowledge, then derived views. If an index disagrees with a record, regenerate the index.

At the end of the session

4

Evaluate the three triggers

Did the state a next contributor acts on change? Did a choice constrain future work? Did evidence change what is believed, in a way that will recur?

5

Write only what fired

Replace stale state in NOW.md and set its review date. Supersede rather than rewrite. Padding the registries is the exact failure they exist to prevent.

6

Say so when nothing fired

context_triggers.py ack --note "…" records an honest evaluation against the current commit — and the window reopens on the next one.

When state may be stale: context_triggers.py status for the window, project-context review --open-days 14 for what waits on a person, and the doctor for what is wrong. All read-only.

Part 6 · The record model

One lifecycle per kind.

One schema string, project-context/1, and one version per product. A detail record carries six frontmatter keys and nothing more is required — id, kind, status, title, created, asserted_by. Registries carry none and stay plain Markdown.

Kind

Its one lifecycle

decision · learning · capsule

→

proposed → accepted → superseded | rejected

question

→

open → answered → superseded

task

→

proposed → active → done | dropped

A status is checked against its own kind, because a question is not an assertion and a task is not a claim: accepted on a question is an error.

Part 6 · The record model

Pin evidence to the state it cites.

A repository path is anchored as src/auth/session.py@a1b2c3d — a reference to a moving file is a reference to nothing. Every form below is validated by shape, never by resolving it. Anchors are optional and Git-gated: drift is a warning, never an error.

Reference form → what it names

session:<harness>:<id>	The run it came from
commit:<binding>:<sha>	A commit
pr:<binding>#<number>	A pull request
review:<binding>#<pr>/<comment-id>	One review comment

…and the other four

ticket:<tracker>:<key>	An issue in a tracker
doc:<binding>:<path>@<commit>	A pinned document
url:https://…	Anything outside the repo
capsule:<id>	A capsule in inbox/

Part 7 · Keeping it honest

Eight families of checks, all read-only.

python3 .agents/skills/project-context/scripts/context_doctor.py --target . — it exits 1 on any error and 0 otherwise, so CI and a git hook can both use the exit status. Anchor findings are warnings; a modified pushed file is an error.

1 · Core files & markerpresent, and the installed version

2 · Record conformancesix keys, one status set per kind

3 · Registry navigabilityduplicate IDs, dead links, staleness

4 · Evidence anchorsevidence-drift, evidence-unverifiable

5 · The pushed seteach file against its stamp

6 · Plan conformancePLAN.md against EPIC.md, if pushed

7 · Legacy schemaa superseded context-hub/1 install

8 · Reachabilitywhether anything still loads them

Two are worth memorising. no-delivery-path — the records are intact but nothing loads them into a session, so fix that before trusting the rest. pushed-file-modified — the one error you can cause by editing a file you were handed; raise a question instead.

Part 7 · Keeping it honest

Cheap to write, ordered to read, honest about the backlog.

capture → inbox/

One short, dated, attributed note. At most 200 words — a longer one is refused, because that is the record it should become. The same text twice on the same day writes once. Provenance comes from your git identity, and the current commit is recorded for you.

context → the packet

Ordered rather than ranked: the owner's guardrails, the blueprint/ epic, NOW.md and the active plan items, then the records anchored to your files. Only accepted and answered records load; proposed ones and anything over budget come back as links.

review → what waits on a person

Proposed records, questions open past their window, unpromoted capsules, drifted anchors, a stale NOW.md. Oldest first, because latency is the failure this system is exposed to. It exits zero whatever it finds: a backlog is not a build failure.

↻ Retrieval is deliberately a path-prefix comparison and a token overlap over a few hundred small Markdown files. No embedding index, no database, no background service, nothing to keep warm.

Part 7 · Keeping it honest

What the tool will not do to your repository.

Create-only, always. Existing context files are preserved byte-for-byte, and no record is ever rewritten or deleted by tooling.
Preview, then apply. Every command takes --dry-run and --apply; the dry run prints the exact plan, and a file you may have edited is skipped and the skip reported.
We own our markers and nothing outside them. Everything outside project-context:start / :end in AGENTS.md and CLAUDE.md is yours — file mode and CRLF endings included.
Unsafe input stops the write. Malformed blocks, unsafe symlinks, non-file harness paths and non-UTF-8 instructions stop apply mode before anything is written.
No network call. Nothing here reaches out. The tool never creates a remote, never pushes, and never invites anyone — and no secret, home path, or machine name belongs in a tracked record.

Part 8 · Beyond this repository

Optional: the other half, Project Hub.

A Hub is one private repository an owner administers, holding what applies across every project. Nothing here requires it, or ever reaches out to it.

What arrives, and how

global/ — guardrails, workflows, shared records.
blueprint/EPIC.md — the high-level plan this project serves.
blueprint/ARCHITECTURE.md — the shape it keeps.
A push lands on a long-lived hub-sync branch as a pull request — never on your default branch.

Read-only here — and what to do instead

Each pushed file is stamped by hash, and the doctor reports an edit as pushed-file-modified.
Disagree with something pushed? Raise a question in your own records. An edit is not overwritten — it makes the owner's next push refuse, stopping the whole sync, and they still never learn what you objected to.
A proposal capsule is how you ask for a change to something pushed; it reaches the owner at their next pull.

No Hub means neither folder, and nothing about that is degraded. The owner's side has its own deck.

Part 8 · Beyond this repository

Designed, and honestly not built yet.

Named here so you do not go looking for them.

SessionEnd capsules

Writing a capsule automatically at the end of a session that produced none. capture is manual today, and the Stop gate offers it rather than doing it.

A promote command

Promotion is editing: write the registry entry the capsule earns and set its status. There is no one-liner for it yet.

Cross-project retrieval

Assembling context across several projects at once. That belongs to the Hub side and is deliberately not here: your packet sees this project and the global snapshot, which is the correct blast radius.

A guide that documents commands you cannot run is worse than one carrying a short, honest list like this.

Get started

Clarity comes with context.

Install it in one repository and read what the doctor says.

project-context init --target . --install-skills --dry-run

The documentation The builder's guide The repository

Made with Hi Ted, Meet Lisa