Skip to content

No single inventory of built vs. planned subsystems — agents code against integration points that don't exist yet #299

Description

@ooloth

Current state

An agent implementing a feature adjacent to dispatch, session tracking, or task fold-back reads architecture docs that describe a complete, coherent system. Those docs contain "not yet built" notices scattered across individual ADRs and architecture files — there is no single file that lists what actually exists today vs. what is described but unimplemented. The result: agents write code against integration points that don't exist, or skip implementing pieces that are already present.

Observable facts:

  • docs/architecture/tasks.md, docs/architecture/task-dispatch.md, and individual ADRs (005, 006, 009, 010, 012, 013, 014, 016, 017, 018) each contain their own "not yet built" or "not yet implemented" notices inline.
  • No file in docs/ or CLAUDE.md aggregates these into a cross-cutting built/planned inventory.
  • CLAUDE.md references the agents/ Rust crate described in Decision 005 but notes it "has not been built yet" — this is representative of a pattern repeated across the docs with no single authoritative view.

Ideal state

  • A docs/status.md file exists and lists every major subsystem (dispatch, session tracking, task fold-back, mining loop, verdict signal, agents crate, etc.) with a binary built / planned marker, a one-line description, and a link to the relevant ADR or issue.
  • An agent dropped in cold reads docs/status.md and immediately knows which code paths are real and which are planned.
  • CLAUDE.md links to docs/status.md in the "Docs by Area" table so it is discoverable at the start of any session.
  • The file is updated whenever a subsystem transitions from planned to built (or is descoped).

Starting points

  • /docs/architecture/tasks.md — contains inline "not yet built" notices representative of the gap
  • /docs/decisions/005-agents-and-prompts.md — references the unbuilt agents/ crate
  • /CLAUDE.md — "Docs by Area" table is where docs/status.md should be linked

QA plan

  1. Open docs/status.md — expect a table or list covering every major subsystem mentioned across the architecture docs, each with a built or planned label and a link to its ADR or issue.
  2. Search docs/architecture/ and docs/decisions/ for "not yet built" — expect every hit to correspond to a planned entry in docs/status.md.
  3. Open CLAUDE.md "Docs by Area" table — expect a row for docs/status.md with a brief description.
  4. Confirm the file is accurate against the actual codebase: pick three built entries and verify their corresponding source files exist; pick two planned entries and verify no corresponding source exists.

Done when

docs/status.md exists, covers all major subsystems with accurate built/planned markers, and is linked from CLAUDE.md.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions