Agent Project Template

Short sessions create a continuity problem

01

Context stays in a chat

Project facts become tied to one tool, one thread, or one person's memory.

02

The session ends

The next contributor inherits code, but not the reasoning, limits, or unfinished path.

03

Work gets rediscovered

Choices are re-litigated, checks are repeated, and stale claims quietly survive.

The repository becomes durable project memory

Instead of asking an agent to remember, the template makes the project itself carry the memory.

Current state, enduring design, planned work, verification, and history are separated so every fact has one authoritative home.

Human and robotic hands holding a shared archive of project files

Every kind of truth has one home

AGENTS.md

Canonical working rules, authority, maintainer preferences, protected areas, and repository map.

HANDOFF.md

What is true now and what happens next.

ARCHITECTURE.md

System shape, interfaces, boundaries, and invariants.

ROADMAP.md

Stable work IDs, status, scope, and evidence.

DECISIONS.md

Accepted choices, alternatives, consequences, and reversals.

TESTING.md

Commands, proof boundaries, limitations, and pitfalls.

SECURITY.md

Sensitive assets, trust boundaries, safe defaults, and reporting.

Truth stays current without erasing history

Rewrite the present

Handoff and architecture describe the repository now. When reality changes, these documents change with it.

  • Current state fits on a screen
  • Architecture stays readable in minutes
  • Unverified assumptions are labeled

Append the past

Decisions, releases, and session entries preserve why a project moved from one state to another.

  • Roadmap IDs never renumber
  • Reversals supersede; they do not delete
  • Old context moves to the archive

Each session follows the same recoverable loop

1Read the handoff, roadmap, architecture, and testing guidance.
2Scope one reviewable change and protect existing work.
3Build while recording durable choices and new risks.
4Verify with the checks that match the change.
5Hand off the current truth, evidence, and next action.
A human and an agent sharing a structured project archive

The documentation has its own consistency test

$ python3 tools/check_docs.py
Scanning project memory…
0 error(s) across linked documents
Exit status: pass
✓

Finds leftover placeholders and broken relative links.

✓

Checks roadmap, decision, question, and session identifiers for drift.

✓

Warns when the handoff or session log has grown beyond its useful size.

✓

Turns critical documentation conventions into executable enforcement.

The cool part is not more documentation — it is less ambiguity

One

Source of truth

Each fact has an owner, so documents link rather than compete.

One

Resumption view

The next session can see what works, what is unproved, and what comes next.

One

Verification path

Claims name their evidence, limits, and the command that can check them again.

The same pattern scales across real software work

Connected software work across solo, team, community, and operations settings

Solo products

Resume a side project after days or months without reconstructing every choice.

Multi-agent teams

Give different coding tools one shared protocol and one current state.

Open source

Separate contributor workflow, durable design rationale, and user-facing changes.

Services and platforms

Add runbooks, data notes, incident reviews, and service objectives only when needed.

Let the repository remember so the next session can act.