LOGBOOK
LOGBOOK is an open markdown convention for organizing project context, specs, decisions, and learnings so that any AI coding agent (Claude Code, Cursor, Aider, Goose, and others) can read and maintain them. It replaces the messy mix of TODO.md, AGENTS.md, CLAUDE.md, scattered specs/, and ad-hoc notes that accumulate in mature codebases.
Structure
LOGBOOK.md project conventions, reading order, stack, non-goals
LOGBOOK/
ideas.md human-owned inbox, append-only, dated entries
candidates.md agent-surfaced thoughts, append-only, triage feeds ideas.md
notes.md codebase learnings, patterns, anti-patterns
features/
INDEX.md optional auto-generated dashboard
feat-<slug>.md one feature per file, frontmatter: status + branch
archive/ shipped >90 days or abandoned
CLAUDE.md, AGENTS.md one-line aliases pointing to LOGBOOK.md
Roles
- Humans own intent (
ideas.md).
- Agents own execution logs (per-feature
## Decisions) and their own inbox (candidates.md).
- Both contribute to learnings (
notes.md).
- Status frontmatter (
draft | active | shipped | abandoned) drives lifecycle.
Lifecycle
Three inboxes feed the feature pipeline, each with a different owner and a different level of commitment:
| Layer | File | Owner | How entries arrive | How entries leave |
|---|
| Candidates | LOGBOOK/candidates.md | Agent inbox | Auto-surfaced silently when a trigger fires (deferred, alternative, out-of-scope, out-of-band) | Triage promotes to ideas.md, or drops |
| Ideas | LOGBOOK/ideas.md | Human inbox | Human captures explicitly, or triage promotes from candidates | Promotion creates a draft feature |
| Draft features | LOGBOOK/features/feat-<slug>.md with status: draft | Joint (human intent, agent maintenance) | Promotion from an idea, or directly from a focused conversation | Status flips to active once work begins |
Why three layers and not two:
- Candidates exist so agents can think out loud without interrupting you. During real work, agents form passing thoughts (a struck plan item, a rejected alternative, an out-of-scope reminder). Surfacing each one would destroy flow, so they go silently into
candidates.md with their trigger and source. A session-end summary reports what was added.
- Ideas stay sacred. Agents never read
ideas.md proactively and never modify it without your ask. Triage is the gate where you decide which candidate deserves a place in your canonical inbox.
- Draft is committed scope, not committed work. A draft has a slug, an Intent, a placeholder plan. It does not yet say "in flight". Status flips to
active only when a branch is cut.
End-to-end flow:
agent thought during work → candidates.md (silent, automatic)
↓ triage (human decides)
ideas.md (canonical human inbox)
↓ promote (slug + Intent committed)
feat-<slug>.md status: draft
↓ branch cut, work begins
feat-<slug>.md status: active
↓ shipped or abandoned
archive/
The append-only rule across candidates.md, ideas.md, and feature ## Decisions logs is what makes the chain trustworthy. The one exception, triage moving an entry off candidates.md, leaves a dated trail in ideas.md.
Repo layout
spec/ the LOGBOOK convention spec (authoritative reference)
skills/ harness-specific implementations
examples/ sample LOGBOOK trees from real and fictional projects
scripts/ shared tooling, including index generators
docs/ long-form articles, design notes, FAQ
Spec
The current spec version is 0.1. See spec/ for the canonical document. Any LOGBOOK implementation must declare which spec version it targets.
Implementations
Claude Code
The reference implementation lives at skills/claude-code/. It supports bootstrap, migration, daily use, capture/promote/ship/archive flows, and index regeneration. See its README for installation and usage.
Contributions for other harnesses (Cursor, Aider, Goose, etc.) are welcome; see CONTRIBUTING.md.
Universal conventions
obra
affaan-m
anthropics
sickn33
ChromeDevTools