Skip to content

ADR-0001: Plans Discipline — Project-Local Ephemeral Working Memory

Status

Accepted

Context

Planning artifacts — architecture sketches, work-breakdown structures, refactor strategies, debugging journals, exploration notes, prompt drafts, AI-conversation transcripts kept for later use — are transient working memory: documents written to think with, not to ship. Where these artifacts live materially shapes whether they help or harm the project they belong to.

Three plausible homes were available:

  1. Centralized global root — every project's plans hosted under the harness configuration directory (e.g. ~/.claude/plans/ for Claude Code) or an equivalent global notes folder.
  2. Per-machine personal scratch — every plan lives under ~/notes/ or a desktop folder, indexed by the operator's own conventions.
  3. Project-local working memory — every plan lives at <project-root>/plans/, scoped to the project it serves, gitignored so the working memory does not pollute the project's durable history.

The centralized global root produces four operational pathologies that compound across sessions:

  • Cross-project pollution. Plans for project A surface during work on project B, biasing reasoning with foreign context.
  • Sync leakage. Cross-machine sync of the harness configuration directory (e.g. ~/.claude for Claude Code — the operator's typical pattern) leaks the working memory of every project the operator has touched onto every machine — including machines that have no business with that project.
  • Blurred ownership. A plan that lives outside its project loses its provenance edge; the natural consumer (the project's contributors, the project's CI, the project's history) cannot reach it.
  • No version-control discipline. Plans hosted globally have no per-project commit history and no per-project review cadence; their evolution is invisible to the project's own audit trail.

Per-machine personal scratch addresses the cross-project-pollution pathology but introduces a different one: plans are not project-bound, so the second-machine view of "what was being planned" requires the operator to reconstruct the bridge between the scratch folder and the project tree. The reconstruction step is friction the discipline is supposed to eliminate.

The recursive case (the ecosystem-as-its-own-project — the apothem repository, materialized into a harness configuration directory such as ~/.claude/ for Claude Code, IS a project that itself plans about itself) introduces a third tension. If the discipline forbids a harness-internal plans/ directory categorically, the recursive case is unrepresentable — yet the ecosystem demonstrably plans about itself.

Decision

Plans are project-local working memory. Every planning artifact lives at <project-root>/plans/, gitignored per the canonical snippet at docs/plans-discipline.md §2.6 / Spec §2.6. The published apothem ecosystem (regardless of which harness destination it materializes into) MUST NOT contain a plans/ folder in the published tree; every contributing surface (CLAUDE.md, copilot-instructions.md, agent prompts, default output-style, the dedicated /plan slash command, the plan-write-guard PreToolUse hook, CI validators, pre-commit hooks) collectively enforces the discipline.

The recursive case (the ecosystem as its own project) is resolved by gitignoring the harness-internal plans/ directory (e.g. ~/.claude/plans/ for the Claude Code adapter) per the §2.6 downstream pattern applied recursively. The folder may exist on the operator's local working tree (where the ecosystem's own plans live, exactly as the discipline prescribes for any project), but it never enters the published tree. The ecosystem ships with its own plans gitignored, exemplifying the discipline it teaches.

Consequences

  • Locality is correctness. A plan reaches the people, code, and history it serves — and only those.
  • Per-project version-control discipline is enforced. Plans evolve under the project's own gitignore boundary; promotion to ADRs (the only path by which plan content becomes durable) flows through the project's normal review cadence.
  • Cross-machine sync of the harness configuration directory (e.g. ~/.claude for Claude Code) no longer leaks plans. The dotfiles surface ships behavioral configuration, not working memory.
  • Self-enforcement is mechanical. The no-global-plans validator fails CI if plans/ reappears in the published tree; the plans-discipline-language validator fails CI if the canonical directive drops out of CLAUDE.md, the default output-style, or copilot-instructions.md; the plan-write-guard PreToolUse hook intercepts any tool call that targets a global plans path and surfaces an AskUserQuestion redirecting the write to the project-local destination.
  • Promotion path is visible. When a plan converges to a durable decision, the decision is extracted into an ADR at <project-root>/docs/adr/NNNN-*.md; the plan's promotes-to frontmatter field points at the ADR; the plan itself archives or discards.
  • The ecosystem dogfoods its own discipline. The harness-internal plans/ directory (e.g. ~/.claude/plans/ for Claude Code) is gitignored on the operator's local tree; the published tree carries none of it.

Alternatives Considered

  • Centralized harness-internal plans/ (e.g. ~/.claude/plans/ for Claude Code) — rejected: produces cross-project pollution, sync leakage, blurred ownership, and forfeits per-project version-control discipline. Every pathology compounds across sessions.
  • Per-machine ~/notes/ (or equivalent personal scratch root) — rejected: not project-bound; the second-machine reconstruction friction defeats the discipline's locality goal.
  • Promotes-only ADRs (no plan layer) — rejected: planning needs a scratch surface separate from durable decisions. Requiring every exploratory thought to immediately reach ADR-grade rigor either suppresses the exploration or pollutes the ADR canon with half-formed work.
  • In-IDE-only ephemeral notes (no filesystem persistence) — rejected: planning state benefits from cross-session durability; volatile notes lose the multi-session reasoning thread the discipline is designed to preserve.

Cross-references: docs/plans-discipline.md, Spec §3, Spec §0.4.