logbook

LOGBOOK

LOGBOOK is an open markdown convention that organizes project context, specs, decisions, and learnings so any AI agent (Claude Code, Cursor, Aider, Goose) 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. Humans own intent (ideas.md); agents own execution logs (feature decisions); both contribute to learnings (notes.md). Status frontmatter on feature files drives lifecycle.

Structure

LOGBOOK.md              project conventions, reading order, stack, non-goals
LOGBOOK/
  ideas.md              human-owned inbox, append-only, dated entries
  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

On activation

1. Check whether LOGBOOK.md exists at the repo root.
2. If yes, read LOGBOOK.md first. Project conventions there override this skill.
3. If the current git branch matches feat-<slug>, read LOGBOOK/features/feat-<slug>.md.
4. Read LOGBOOK/notes.md if it exists and the work is non-trivial.
5. Never read LOGBOOK/ideas.md proactively. It is human inbox; only read on explicit request.
6. If LOGBOOK.md does not exist, ask whether to bootstrap before doing anything else.

Decision tree

User intent	Workflow file
No LOGBOOK in the repo, user wants to start	workflows/bootstrap.md
Repo has scattered TODO/AGENTS/CLAUDE/specs to consolidate	workflows/migrate.md
LOGBOOK exists, user is coding a feature	workflows/daily-use.md
"I have an idea / log this idea"	workflows/capture-idea.md
"Turn idea X into a feature / start spec for X"	workflows/promote-idea.md
"Mark X shipped / X is done"	workflows/ship-feature.md
"Archive old features"	workflows/archive-feature.md
"Refresh / regenerate the index"	workflows/regenerate-index.md
"What features are active / find feature about X"	workflows/search-logbook.md
Agent surfaces a candidate (auto, on trigger fire; per spec v0.3 §12.4)	workflows/surface-candidate.md
"Triage candidates / what did agents surface"	workflows/triage-candidates.md

When intent is ambiguous, ask the user before touching files. Never guess between bootstrap and migrate.

Universal conventions

These apply to every LOGBOOK project, regardless of stack.

• Markdown only. No HTML, no extra formats.
• No em-dashes. Replace with commas, parentheses, or middle dots (·). This applies to every file written under LOGBOOK, including the root LOGBOOK.md.
• Dates: YYYY-MM-DD. Always absolute. Never "yesterday", "last week", "next sprint".
• Slugs: lowercase, dash-separated, no spaces. Feature filenames are feat-<slug>.md.
• Frontmatter on feature files: two REQUIRED fields, plus one OPTIONAL recognized field.
  • status: draft | active | shipped | abandoned
  • branch: feat-<slug> (must match the filename slug)
  • parent: feat-<other-slug> (OPTIONAL on independent features; REQUIRED on revivals of abandoned parents, follow-ups on shipped parents, or deliberate iterations. See spec v0.4 §4.3, §6.4.)
• Append-only: ideas.md, candidates.md, and feature ## Decisions logs are append-only. Never rewrite history; add a new dated entry that supersedes the prior one. Triage promotion is the one allowed removal from candidates.md (see spec v0.3 §12.7).
• Aliases: CLAUDE.md and AGENTS.md at the repo root contain one line: Read LOGBOOK.md.
• Candidate channel (REQUIRED since v0.3 §12): LOGBOOK/candidates.md MUST exist in every conforming LOGBOOK and MUST be auto-populated when triggers fire (deferred, alternative, out-of-scope, out-of-band). Bootstrap creates it; v0.2 projects are upgraded with notification. Surfacing is silent (no per-entry confirmation); a per-session batch summary at session end is REQUIRED.

Project-specific rules (stack, style, non-goals, custom sections) live in the project's own LOGBOOK.md. When project conventions conflict with anything here, the project wins.

Guardrails

• Never modify ideas.md without an explicit user request. It is human-owned. Capturing a new idea on user request is allowed; rewording, deleting, or reorganizing existing entries is not. To capture a passing thought without interrupting the user, agents auto-surface candidates to LOGBOOK/candidates.md per workflows/surface-candidate.md (REQUIRED since spec v0.3).
• Always show a diff before destructive changes (deleting files, mass renames, archive moves). Wait for confirmation.
• Use git mv for renames and archive moves. Preserve history.
• Never delete a feature file without explicit confirmation. Move to archive/ instead.
• Never write to LOGBOOK.md root without showing the proposed change first; it encodes project conventions and is human-curated.
• Decisions logs are append-only. Never edit prior entries; add a new dated entry that supersedes.
• Never mix workflows. If the user asks to ship while you are mid-migration, finish or pause migration first and confirm.

Reference

• Templates: templates/ (LOGBOOK.md, ideas.md, notes.md, feature.md, INDEX.md, CLAUDE-alias.md, AGENTS-alias.md)
• Workflows: workflows/ (one file per scenario in the decision tree)
• Index scripts: scripts/logbook_index.{exs,py,sh} (pick the one matching the project stack; behavior is identical)
• Examples: examples/ (a realistic active and shipped feature, a sample root, a sample notes file)