Skip to content

Observability: document agenttrail as the recommended live lane view; evaluate PLAN.md as the plan-context format #435

Description

@jeffhuber

Owner review + trial 2026-08-28 of https://github.com/sodiumsun/agenttrail (MIT, local-only observability board for Claude Code/Codex/Cursor: fs watcher + optional Claude hooks + a PLAN.md convention; 127.0.0.1 only, no telemetry, dependency-free ~780-line daemon).

Why it complements Code Mower: it is the live 'what are the lanes doing right now' pane Code Mower lacks (Code Mower judges at merge time; agenttrail observes at run time). Its declared-vs-observed drift signal (a done card lights up when its files change again) is the live analogue of the plan-conformance audit lens.

Trial evidence (owner's Mac): ran the reviewed local clone in observe-only mode (no init/hooks) against two Code Mower builder-lane workspaces; boards served on 127.0.0.1:5330/5331; a touched file appeared in /model within ~2 s; /fleet lists boards for the tab switcher.

Scope:

  1. docs/build-loop.md + docs/build-loop-in-30-minutes.md: a short 'Watching the lanes live' subsection recommending agenttrail run in each lane workspace (observe-only mode is enough; agenttrail init writes repo-local Claude hooks and edits CLAUDE.md/AGENTS.md, so keep it out of any Code Mower defaults and note it as opt-in). Pin the guidance to a reviewed version; it is a week-old v0.2 project, so 'recommended, not depended on'.
  2. Evaluate adopting its PLAN.md convention (stable {#id}s, files: globs, [~]/[x]/[!] statuses, needs:/links:, decisions log) as the recognized structured format for Code Mower's plan-context packs and the plan-conformance lens; today plan context is free prose.
  3. Optional later: its Claude hook relay events as additional builder-provenance evidence for builder_runs.

Not release-blocking; candidate 'pairs well with' line for the announcement.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions