Shared project context that outlives any one person, agent, or chat. A context pipeline you build straight into a repository or project folder — plain Markdown, Git-tracked, owned by the project.
A collaborator returning after three weeks should not rebuild the project from stale chats.
Project Context answers four questions through a small set of typed Markdown records and a maintenance protocol that works across repositories and agent harnesses.
Q1
What is true now?
Active state, blockers, and what happens next.
Q2
Which decisions constrain the work?
Accepted choices, with the rationale intact.
Q3
What has already been learned?
Verified lessons future collaborators should reuse.
Q4
Where is the evidence?
Links to the source, dataset, review, or record.
Unlike chat history, proprietary memory, or generated documentation, that context stays portable across collaborators and tools — and remains owned by the project.
Part 1 · Why
How the context pipeline works
Seven steps, from the first prompt to the next collaborator inheriting the result.
Install once
1
The user prompts the agent
A short installation prompt points to the canonical initializer skill.
↻ Project Context does not copy the whole project into a second knowledge base. Primary artifacts stay where they belong.
Part 2 · How it works
Agent-operated, human-readable
People provide intent and approve changes. Agents read the skills, run the tooling, and maintain the files. You are never expected to invoke skills or run Python yourself.
Person
AI agent
Pastes the short installation prompt
Loads and follows project-context-init/SKILL.md
Answers whether the project is new and what it is for
Classifies the project and reviews overlapping context
Approves the proposed plan and each eligible optional tool
Creates only approved files, installs opted-in tools, verifies the result
Optionally reads, reviews, or edits the Markdown
Uses and maintains the context automatically during later work
Part 3 · Install
Install with any AI agent
No skill launcher and no Python runtime are required for the agent-guided path. Copy this into an agent that can access the target repository or project folder.
Copy-paste prompt
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.
↓ the agent takes over from here
Installation creates two trigger paths
Agent Skills discovery
Harnesses that support the convention find the installed project-context and project-context-init skills directly.
Managed instruction block
A block added to AGENTS.md or CLAUDE.md routes any agent to project-context/SKILL.md — even with no skill launcher.
Part 3 · Install
What the initializer does
A seven-step protocol runs before anything is written to disk.
project-context-init/SKILL.md
Repository conversation — brand-new or existing?
Inspect & classify — software, document, research, writing, mixed, or general
Review consolidation — detect material that already serves the same purpose
Choose profile — core or full
Filter add-ons — by repository type and observed contents
Install/configure tools — only after an independent informed opt-in
Verify & hand off — confirm idempotency and report the result
↓ agent implementation reference
scripts/install.py
--dry-run
Inspect the exact changes first
--apply
Write the approved plan
--repository-stage
brand-new · existing
Installs both skills under .agents/skills/, creates the selected profile, preserves custom files, and refreshes only the managed instruction block. The CLI never stores the free-text purpose.
Part 4 · What you get
Two profiles
Start lightweight and grow, or begin with the full evidence structure. Every installation records its profile, repository type, and template version in .project-context.json.
core — lightweight
README.mdContext file read order
SKILL.mdAgent operating protocol
NOW.mdCurrent state & blockers
DECISIONS.mdConstraints & rationale
LEARNINGS.mdVerified lessons
Best for small repositories, evaluation, and first-time adoption.
full — evidence-rich
[ all core files ]Everything above
tasks/Plans, progress, outcomes
designs/Proposals & specifications
incidents/Root cause & prevention
.project-context.jsonProfile, type, version
Best for long-lived projects, teams, and evidence-rich workflows.
Part 4 · What you get
A routing and continuity layer
The context files summarize only the durable state and point collaborators to the evidence they need.
File
What it answers
NOW.md
What is true now, what is active, and what happens next?
DECISIONS.md
Which accepted choices constrain future work, and why?
LEARNINGS.md
Which verified lessons should future collaborators reuse?
Linked evidence
Which source, document, dataset, review, result, or record supports the context?
Part 5 · Operate
What agents do during project work
Start of meaningful work
At the start of work
1
Read project-context/NOW.md
Current state, active work, next actions
2
Search DECISIONS & LEARNINGS
For the task topic
3
Follow only relevant links
Into detailed evidence
4
Confirm important claims
Against current primary artifacts and evidence
At a milestone or handoff
5
Update the active task evidence
Progress and validation
6
Promote changed current state
Into NOW.md
7
Record constraining decisions only
Not every choice is durable
8
Supersede stale knowledge
Instead of silently rewriting history
The next collaborator inherits structured context — not chat history.
Part 5 · Operate
Existing context is reviewed, never migrated behind your back
For existing repositories the skill classifies the project, then looks for material that may already serve the same purpose.
Keep in place and link — the default for primary evidence
Copy selected knowledge — carrying provenance with it
Deliberately migrate — into the canonical structure
The review never moves, merges, rewrites, archives, or deletes automatically. Candidates are classified by likely role and confidence for your review.
Part 5 · Operate
When context may be stale, the agent runs the doctor
A read-only check that reports issues without rewriting your custom knowledge.
Read-only health check
python3 skills/project-context-init/scripts/project_context_init.py doctor --target /path/to/repository
↓ reports, never rewrites
What the doctor checks
Required core files
All expected records present
Scaffold version
Updates reported for deliberate review
NOW.md freshness
Flags current state going stale
Duplicate IDs
Across decisions and learnings
Broken links
Relative Markdown evidence links
Part 5 · Operate
Authority model
Knowing which layer wins is what keeps generated material from quietly becoming the source of truth.
Layer
Role
Authority
Primary artifacts
Actual project truth
Highest for factual claims
project-context/
Current state, decisions, learnings, evidence routing
Canonical project continuity
Agent instructions
Tell agents how to use context
Pointer and protocol only
Indexes & wikis
Discovery and explanation
Derived — never current-state authority
Part 6 · Extend
Advanced integrations
Project Context works without any of these. The initializer filters the list by repository type and observed contents, then requires a separate informed decision for every eligible tool.
Tool
Choose it when
GitNexus
A code or mixed repository contains a meaningful software system. Surfaces code symbols, relationships, impact, and execution flows.
Graphify
A substantial corpus needs cross-file or cross-format navigation across code, documents, research artifacts, and media.
OpenWiki
A stable, complex project has a clear audience for a maintained derived wiki.
It does not ask writing projects about code analysis, or present every add-on as a default checklist.
Opt-in · never required
Part 6 · Extend
Safety guarantees
What the installer promises never to do to a repository it does not own.
Existing context files are preserved byte-for-byte.
Existing AGENTS.md and CLAUDE.md content is preserved outside one managed block — including file mode and CRLF endings.
Unknown or overlapping memory is reviewed and classified, not migrated.
Malformed blocks, unsafe symlinks, non-file harness paths, and non-UTF-8 instructions stop apply mode before any write.
Add-ons are filtered by repository type, then installed only after an independent informed opt-in.
Secrets never belong in tracked context, prompts, logs, or commits.
Part 7 · Reference
Repository structure
An agent-facing installation and operating package: two reusable skills, a safe initializer, templates, prompts, and validation tests.
monomind-ai-lab/project-context/
skills/
project-context-init/
SKILL.mdInit protocol (7 steps)
scripts/project_context_init.pyinspect · review · doctor · init
examples/sample-project-context/Filled core-profile example
prompts/
install-project-context.mdCopy-paste installation
maintain-project-context.mdFollow-up maintenance
tests/Behavioral test suite
README.md · VERSION · LICENSEDocumentation · template version · MIT
Part 7 · Reference
From work to durable context
Every primary artifact leaves a citable trace — and stays exactly where it belongs.
Primary artifacts (source of truth)
Project context files (durable memory)
Source code
→
Evidence links in DECISIONS
Tests
→
Evidence links in LEARNINGS
Documents
→
Links in NOW.md & task records
Commits
→
Evidence citations
Reviews
→
Decision rationale & lessons
Markdown-based, version-controlled, human-readable, and portable across tools and collaborators.
Get started
Clarity comes with context.
Paste the installation prompt into any AI agent that can read and edit your repository. It will ask what it needs, show you the plan, and wait for your approval before writing a single file.
