codebase-trio

name	codebase-trio
description	Two-agent codebase journal (writer + reviewer) over a deterministically pre-computed context bundle
capabilities	["shell"]

Codebase Trio (reformed 2026-04-27)

Produces one journal entry about a codebase via:

1. Phase 0 — context bundle (deterministic shell, no LLM): prepare_context.sh emits $WS/context.md with the file tree, last 30 commits, last 5 commit diffs, function/class definitions across src/, pattern grep over concurrency / caching / IPC / TODO / design-doc markers, and a LOC summary. ~7K tokens.

2. Phase 1 — writer agent: reads the bundle, picks ONE non-obvious thing, drafts a ~200-word note to $WS/draft.md. Signals reviewer via $WS/wr2rv FIFO.

3. Phase 2 — reviewer agent: blocks on the FIFO; reads the bundle plus the writer's draft; validates every substantive claim; writes the final entry to $WS/final.md. Combines the original critic and editor into one LLM conversation — no second handoff.

The skill name still says "trio" because the bundled-context phase functionally substitutes for the third role: pre-computed deterministic work used to be done redundantly by all three agents; now it's done once, by the shell, before any LLM runs.

Why the reform

The original three-agent design (writer → critic → editor with two FIFO handoffs and live codebase exploration via every agent) was anti-amortizing — exercising the skill cost ~2× more than letting a single tmuxllm agent figure out the journal task from scratch.

Diagnosis (in docs/plans/2026-04-26-skills-architecture.md §"Phase 1 verification gate — result and reframe"):

• Three agents pay the system-prompt + tool-def setup tax three times, with no cross-process cache benefit.
• Each handoff serialised context that was free in-conversation.
• Phase rigidity (no editor ↔ writer back-and-forth) prevented the multi-agent design from buying anything beyond what one agent does.
• Specialisation was prompt-shaped, not capability-shaped: all three agents had identical tool surfaces (the tmuxllm reasoner).

The reform moves deterministic plumbing into shell, collapses the two LLM personas with no capability difference (critic + editor) into one, and keeps a single FIFO handoff (the irreducible synchronisation).

Run

tmuxllm-skill run codebase-trio

Env vars (override defaults):

• TMUXLLM_PROFILE — provider profile (default: openrouter-gemini-3.1-flash-lite)
• REPO — codebase to analyse (default: $PWD)
• WS — workspace dir (default: /tmp/codebase-trio)
• JOURNAL — journal output dir (default: $HOME/.local/share/tmuxllm/journal)

What this skill encapsulates

• The pre-computed context bundle (prepare_context.sh) that lifts deterministic codebase enumeration out of every agent loop
• The 1-FIFO writer → reviewer handoff with the "echo signaled" / "echo published" visible-completion cue (avoids the reviewer-exits- too-eagerly deadlock)
• Per-agent session logs at $WS/{writer,reviewer}.jsonl
• Idempotent journal output to $JOURNAL/$(date +%Y-%m-%d).md

Pitfalls

• Cost: ~$0.20–0.50 per run with openrouter-sonnet; multiply by 3 for opus.
• Codebase scope: pointing at a multi-million-line monorepo will burn budget on find / grep without producing a focused note. Scope REPO to a subdirectory if needed.
• Idempotency: a second run on the same day overwrites today's journal entry. Bump the journal-path template if you want history.

Daily scheduling

Use launchd (macOS) or cron (Linux). Example launchd plist that runs at 09:00:

<plist version="1.0">
<dict>
  <key>Label</key><string>com.user.tmuxllm-codebase-trio</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>-lc</string>
    <string>cd /path/to/repo && tmuxllm-skill run codebase-trio</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>TMUXLLM_PROFILE</key><string>openrouter-sonnet</string>
    <key>OPENROUTER_API_KEY</key><string>...</string>
  </dict>
  <key>StartCalendarInterval</key>
  Hour9Minute0

Linux scheduling (cron)

0 9 * * * cd /path/to/repo && TMUXLLM_PROFILE=openrouter-sonnet OPENROUTER_API_KEY=... tmuxllm-skill run codebase-trio >> /tmp/codebase-trio.log 2>&1

Either way, expect ~/.local/share/tmuxllm/journal/YYYY-MM-DD.md to accumulate one entry per day.

Channel

$WS/context.md    ← prepare_context.sh writes; both agents read
$WS/draft.md      ← writer writes; reviewer reads
$WS/final.md      ← reviewer writes (the journal entry)
$WS/wr2rv (FIFO)  ← writer signals "draft ready"

Topology: linear handoff. Writer → reviewer → exit. The trailing && echo signaled (writer) and && echo published (reviewer) cues keep the LLM from exiting before the FIFO write or final-file write actually lands.

What this exercises that 2-agent IPC doesn't

• Hybrid deterministic + LLM pipeline. Phase 0 is pure shell; phases 1-2 are LLM-driven. The amortization win comes from the shell phase doing work that's free for the shell and expensive for the LLM (file enumeration, git log, pattern grep).
• Asymmetric roles via prompt alone. Same model and profile; the system prompts make them act as writer / reviewer. The framework doesn't know about "roles."
• Code-as-evidence loop. The reviewer's value-add is checking the writer's claims against the bundle and source files — exactly the shell-driving capability tmuxllm exists for, applied to a meta task.

Variations

• Add a revision loop. Reviewer writes REVISE: <reason> to a feedback file instead of finalising; writer reads it, revises, re-signals the reviewer. Cap rounds in each prompt.
• Different specialisations. Swap "reviewer" for a "documentation reviewer" (checks against README/CLAUDE.md), or add a third "summariser" agent that produces a one-line tweet from the final entry.
• Restore the third role. If the validate vs. synthesize phases benefit from separate conversations (e.g. for very large drafts), split reviewer back into critic + editor with a second FIFO.

Operational note for scheduled runs

Wrap with timeout 600 so a misbehaving agent doesn't deadlock the orchestrator (e.g. writer exits without signalling wr2rv, leaving the reviewer blocked on read):

timeout 600 tmuxllm-skill run codebase-trio