project-docs: the framework that gives your AI agents memory and structure

The real problem isn’t capability

If you use Claude Code or Codex to write code, you’ve probably experienced this: the agent is technically capable of solving the problem, but solves it poorly because it doesn’t understand the context. It guesses at architecture. It ignores project conventions. It loses continuity between sessions. It generates a class component in a hooks-only project, or touches a module that was explicitly out of scope.

The problem isn’t that the agent is dumb. The problem is that it’s missing a map.

project-docs is that map. A satellite documentation system that installs into any repo and gives AI agents structured context about your project: what it is, how it’s built, what conventions to follow, what not to touch, and what to do when there’s ambiguity.

What project-docs is

It’s a documentation directory with a fixed structure that you clone into your project. It has 8 themed folders covering everything from product vision to a recurring error log. But the interesting part isn’t the documentation itself — it’s the agent and rule system that consumes it.

The core premise: agents don’t need more freedom, they need a better map. Instead of giving the agent full access and hoping it figures everything out, you give it well-defined documents that tell it exactly what it needs to know for each type of task.

Two-layer architecture

The smartest design decision in project-docs is its two-layer architecture. The problem it solves is concrete: Claude Code autodiscovers its configuration from the repo root (CLAUDE.md, .claude/agents/), but project-docs lives in a subdirectory. If the config stays inside project-docs/, agents never find it.

The solution:

Layer 1 — Documentation content lives inside project-docs/. This is the knowledge base agents read:

project-docs/
├── product/          # Vision, scope, roadmap
├── architecture/     # System overview, modules, ADRs, dependencies
├── context/          # Tech stack, conventions, current state, known issues
├── references/       # Repo map, key files, critical flows
├── plans/            # Implementation plans
├── sessions/         # Work session logs
├── handoffs/         # Agent-to-agent transfers
└── memory/           # Recurring mistakes, changelog with impact tracking

Layer 2 — Agent configuration lives at the host repo root. The bootstrap script copies templates from project-docs/scaffold/ to the root, replacing placeholders like {{PROJECT_NAME}} and {{PROJECT_DOCS_PATH}} with actual project values.

After running bootstrap, your repo looks like this:

my-project/
├── CLAUDE.md              # Master instructions for Claude Code (generated)
├── AGENTS.md              # Routing policy for Codex (generated)
├── .claude/agents/        # 6 subagent definitions (generated)
├── .claude/rules/         # 4 rule sets (generated)
├── .agents/skills/        # 6 Codex skills (generated)
└── project-docs/          # The actual project documentation

Context loading: the token trick

One of the most underestimated problems when working with agents is token waste. If you feed the agent all the documentation, it drowns in noise and forgets what matters. If you give it nothing, it guesses.

project-docs solves this with an explicit context loading policy:

Every documentation file has a read_policy field in its YAML frontmatter that makes this policy machine-readable. The generated CLAUDE.md translates this policy into concrete agent instructions.

The 6 agent roles

The system defines 6 roles with exact responsibilities, defined output formats, and explicit constraints. Each role exists as a Claude Code subagent (.claude/agents/) and as a Codex skill (.agents/skills/):

Planner — Converts goals into implementation plans. It’s read-only: writing and editing files is explicitly forbidden. Its output is a structured plan with scope, risks, ordered tasks, and human checkpoints.

Implementer — Executes scoped code changes based on the active plan. It has one fundamental rule: make the smallest coherent change possible. Expanding scope without documenting the reason is forbidden. Silently refactoring unrelated files is forbidden.

Tester — Defines the minimum sufficient validation strategy. It uses a 4-level depth model: no tests (trivial changes), unit, integration, and E2E. Also read-only.

Reviewer — Reviews completed work. Issues one of three verdicts: Approved, Approved With Changes, or Rejected. Automatically rejects if behavior changes without validation, if there are unrelated refactors, or if architecture is violated without an ADR.

Docs Maintainer — Keeps documentation synchronized with code reality. Creates session notes, handoffs, and updates project state.

Bootstrapper — Initializes documentation interactively. Asks questions about the project and generates the 3 always-read files. Has one key rule: it does not invent information. If it doesn’t know something, it leaves a NEEDS_HUMAN_INPUT marker instead of hallucinating content.

Task routing: not everything needs the full pipeline

The system has three complexity tiers:

Fast path:     Implementer only
               → Typo fixes, formatting, config with no behavior impact

Standard path: Planner → Implementer → Tester → Reviewer
               → Features, bug fixes, refactors

Full path:     All roles + human checkpoints
               → Architecture, security, migrations, destructive operations

Routing isn’t automatic — the agent decides based on rules defined in CLAUDE.md. The golden rule: when in doubt, use the standard path.

Conflict resolution

This is where project-docs sets itself apart from most multi-agent systems. Instead of letting agents resolve conflicts among themselves (spoiler: they can’t), it defines explicit escalation rules:

• If the implementer deviates from the plan, it documents the deviation and pauses for human review
• If the reviewer rejects the same work twice, it escalates to the human
• If there’s ambiguity, the agent pauses and requests human intervention
• Architectural disagreements are never resolved between agents

The human is always the final arbiter. This sounds obvious but is surprisingly rare in agent frameworks.

How to install it in your project

Installation is a two-step process:

Step 1 — Mechanical. Clone the repo and run bootstrap:

# Inside your project
git clone https://github.com/lea2696/project-docs.git project-docs/

# Run bootstrap (generates CLAUDE.md, AGENTS.md, agent configs)
node project-docs/scripts/bootstrap.mjs

# Or with options
node project-docs/scripts/bootstrap.mjs --dry-run         # Preview without writing
node project-docs/scripts/bootstrap.mjs --non-interactive  # Use defaults

The script automatically detects the project name (from package.json or the directory name) and the test directory (probes tests/, test/, __tests__/, spec/). It asks you to confirm or change these values.

Step 2 — Conversational. Ask the bootstrapper agent to fill in the documentation:

# In Claude Code
"Use the bootstrapper agent to initialize project docs"

# In Codex
"Use the bootstrap skill to initialize project docs"

The bootstrapper asks about project purpose, target users, tech stack, conventions, and current state. It generates the always-read files and optionally the reference files. What it can’t complete gets marked with NEEDS_HUMAN_INPUT.

The memory system

One of the most useful features is the error memory in memory/RECURRING_MISTAKES.md. Each entry follows a formal structure:

### MIS-001: Tests passed with mocks but failed in prod
- Date: 2026-03-15
- Category: testing
- What happened: Tests mocked the DB and passed, but the real migration failed
- Root cause: Divergence between mock and actual schema
- Resolution: Migrate to integration tests with real DB
- Prevention rule: Don't mock the database in integration tests

This is gold for agents. Instead of repeating the same mistake, they read the error log and adjust their approach.

The CHANGELOG_NOTES.md has an Agent Impact column that describes not just what changed, but what agents need to do differently as a result.

CI/CD included

The repo ships with three GitHub Actions:

• docs-lint — Validates documentation structure on every push (8 directories, 19 files, valid frontmatter)
• structure-check — Verifies the scaffold has exactly 18 files and agent configs exist
• scaffold-smoke — Runs bootstrap in a temporary repo and verifies no unresolved placeholders remain

Why this matters

The current trend is to give agents more capability: more tools, more context, more autonomy. project-docs goes in the opposite direction. It gives the agent less freedom but better information. It tells it exactly what to read, what not to touch, when to stop, and who to ask.

The result is that agents produce more predictable work, better aligned with project decisions, and requiring less human correction. Not because they’re smarter, but because they’re better informed.

If you’re using Claude Code or Codex on real projects, give it a look. It’s open source, installs in 5 minutes, and the difference in output quality is noticeable from the first session.

Repo: github.com/lea2696/project-docs