Kjell Tore Guttormsen
2ee8137e7c
Wave-1 order 4 (P7, P12, the P9 test lock, the P3 plan-approval guard). All command hooks; none runs a model. - P12: pre-bash-executor answers permissionDecision "ask" before merge into main, push, tag/publish and destructive git (holds in auto mode). post-approval-log writes exactly what the person was asked to the K2 approval log: merge/push to main as `merge`, tag/publish as `release`, with a one-hour expiry; nothing when no person was asked. - P3: pre-plan-gate runs the K3 plan gate on a Voyage plan leaving plan mode and sends a refused plan back; "not measured" asks, never passes. - P9: lib/util/test-lock.mjs (K8). pre-write-executor refuses edits to locked test files; stop-test-lock refuses "done" for the locking session (stop_hook_active guarded). - P7: post-edit-check runs the target repo's own formatter/linter per edit, only during a Voyage plan run or after opt-in (.claude/voyage-guards.json); lib/verification/step-check.mjs (K9) fails the step on findings; no tool reads "not measured", never green. - STORM cap matcher also names `Agent` (the tool's name since 2.1.63). - Mod precondition stated in README, SECURITY.md and every PreToolUse stop guard: Voyage's guards are deterministic only when no installed mod handles `tool.check`. K2, K3 and K5 are stubbed in tests until orders 2 and 3 are merged. Two independent review rounds; every finding has a regression test. Suite 1600 (1598 pass / 0 fail / 2 skipped). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
106 lines
10 KiB
Markdown
106 lines
10 KiB
Markdown
# trekplan
|
||
|
||
Voyage — a contract-driven Claude Code pipeline: brief, research, plan, execute, review, continue. Deep implementation planning and research with specialized agent swarms, external research, adversarial review, session decomposition, disciplined execution, and headless support.
|
||
|
||
**Design principle: Context Engineering** — build the right context by orchestrating specialized agents. Each step in the pipeline (brief → research → plan → execute) produces a structured artifact that the next step consumes. The load-bearing benefit is the parallel wall-clock + structured artifact handoffs; main-context relief is asserted-by-design, not measured (Δ ≈ 0 in the one PoC — see `docs/T1-synthesis-poc-results.md`).
|
||
|
||
> **Architecture slot.** The plan command auto-discovers `architecture/overview.md` if present — any compatible producer plugs in (the architect plugin is no longer publicly distributed). Migration history (v3.0.0 extraction) → [CHANGELOG.md](CHANGELOG.md).
|
||
|
||
> **Trinity context (informational).** Voyage is Tier 1 (per-task) of a three-tier architecture. **Asymmetry is a hard invariant:** Voyage stays unaware of Tier 2/3; Handover 1 (brief format) is the only integration point, no producer is privileged, and brief-schema changes are breaking for downstream consumers (formalized as a public contract in v5.5.0). Tier 2/3 producer detail + the public contract → `docs/HANDOVER-CONTRACTS.md` §Handover 1 (PUBLIC CONTRACT).
|
||
|
||
> **Cross-cutting invariant: brief framing must match operator intent.** The brief is the pipeline's source of truth; operator intent lives in memory files — the pipeline must not polish a wrong premise. Enforced as the `brief_version 2.2` gate (v5.5), all BLOCKER for briefs declaring ≥ 2.2: (1) explicit `framing: preserve|refine|replace|new-direction` frontmatter, `AskUserQuestion`-validated in `/trekbrief` Phase 2.5; (2) memory-alignment as `brief-reviewer` dimension 6; (3) mandatory `## TL;DR`. Existing 2.0/2.1 briefs stay valid; `trekreview` briefs are exempt. Full implementation + contract evolution → `docs/HANDOVER-CONTRACTS.md` §Handover 1 (PUBLIC CONTRACT).
|
||
|
||
> **Binding rule (operator decision, 2026-09-27): Voyage never starts Claude Code.**
|
||
> Nothing Voyage ships may start a Claude Code session or model run: no `claude`
|
||
> CLI line, no Agent SDK, no spawned binary, no launch script. Work that needs
|
||
> another session becomes an order plus a starter line the user gives a session
|
||
> they open themselves (`/trekexecute` Phase 2.6, `lib/util/session-orders.mjs`);
|
||
> parallel work inside one session uses subagents. Enforced by
|
||
> `tests/lib/no-claude-code-launch.test.mjs`; its exemption list holds historical
|
||
> mentions plus one operator instrument (operator decision, 2026-10-02:
|
||
> `docs/proevesett.md` tells a person how to run Anthropic's plugin eval tool on
|
||
> the fixed test set; Voyage itself starts nothing), each with a reason and an
|
||
> exact count.
|
||
|
||
## Commands
|
||
|
||
| Command | Description | Orchestrator model |
|
||
|---------|-------------|--------------------|
|
||
| `/trekbrief` | Brief — interactive interview produces a task brief with explicit research plan; ends with the operator approving `## Intent` + `## Goal` (`--approve <dir>` does only that, then writes the trekbrief record); optionally orchestrates the pipeline | session |
|
||
| `/trekresearch` | Research — deep local + external research, produces structured research brief. Opt-in `--engine {swarm\|deep-research}` delegates the external phase to Claude Code's built-in `/deep-research` workflow (swarm default) | session |
|
||
| `/trekplan` | Plan — brief-reviewer, explore, plan, review. Requires `--brief` or `--project`; halts unless the brief's intent is approved (hash-bound, stale on edit). Auto-discovers `architecture/overview.md` if present | session |
|
||
| `/trekexecute` | Execute — disciplined plan/session-spec executor with failure recovery | session |
|
||
| `/trekreview` | Review — independent post-hoc review of delivered code against the brief. Produces `review.md` with severity-tagged findings (Handover 6) | session |
|
||
| `/trekcontinue` | Continue — resumes the next session of a multi-session voyage project. Reads `.session-state.local.json` (Handover 7) and immediately begins executing | session |
|
||
| `/trekendsession` | End-session — mark the current session complete and write session-state pointing at the next session. Helper for informal multi-session flows | session |
|
||
|
||
`session` = command frontmatter pins no `model:` (since v5.9.0), so the orchestrator follows the session model; sub-agent models come from the profile (see Model & effort below).
|
||
|
||
Full flag reference for each command (modes, `--gates`, `--profile`, breaking changes): see `docs/command-modes.md`.
|
||
|
||
> **STORM bounded loop — default-off, env-gated.** `/trekresearch` Phase 4.5
|
||
> (dimension discovery, under the existing `maxDimensions: 8` ceiling) and
|
||
> Phase 5 (bounded multi-turn follow-up) run only at `effort: high` **and** only
|
||
> when `VOYAGE_STORM_ENABLED=1`; unset, both are inert — Phase 5 because
|
||
> `lib/util/research-loop-cap.mjs` grants a budget of 0, Phase 4.5 because its
|
||
> skip-guard reads the flag directly (it never calls the cap). `TREKRESEARCH_MAX_CONV_TURNS` (default `3`,
|
||
> invalid values fall back to `3`) sets turns per dimension; the budget is that
|
||
> × `maxDimensions`. `VOYAGE_DISABLE_CAP_HOOK=1` switches off
|
||
> `hooks/scripts/pre-agent-cap.mjs`, the `PreToolUse` gate that enforces the
|
||
> budget in the harness rather than trusting prose. The cap counts turns from
|
||
> its own append-only ledger. Adoption as a default is gated on the
|
||
> pre-registered measurement in `docs/storm-measurement.md` — decline is a
|
||
> no-op, adopt is one constant.
|
||
|
||
> **Guards (P3/P7/P9/P12).** Command hooks only, wired for every session.
|
||
> `pre-bash-executor` answers `ask` (holds in auto mode) before merge into
|
||
> main, push, tag/publish and destructive git; `post-approval-log` writes
|
||
> approvals to the K2 log. `pre-plan-gate` runs the K3 plan gate on a Voyage
|
||
> plan leaving plan mode. `pre-write-executor` + `stop-test-lock` enforce the
|
||
> K8 test lock (`lib/util/test-lock.mjs`). `post-edit-check` runs the target
|
||
> repo's own format/lint only during a Voyage plan run or after opt-in
|
||
> (`.claude/voyage-guards.json`); `lib/verification/step-check.mjs` (K9) fails
|
||
> the step on findings. A missing contract CLI reads "not measured"/"not
|
||
> logged", never green. Voyage's guards are deterministic only when no
|
||
> installed mod handles `tool.check`.
|
||
|
||
## Agents
|
||
|
||
| Agent | Model | Role |
|
||
|-------|-------|------|
|
||
| planning-orchestrator | opus | Inline reference documentation for the planning pipeline workflow (brief-driven) |
|
||
| research-orchestrator | opus | Inline reference documentation for the research pipeline workflow |
|
||
| review-orchestrator | opus | Inline reference documentation for the review pipeline workflow |
|
||
| architecture-mapper | opus | Codebase structure, tech stack, patterns |
|
||
| dependency-tracer | opus | Import chains, data flow, side effects |
|
||
| task-finder | opus | Task-relevant files, functions, reuse candidates |
|
||
| risk-assessor | opus | Risks, edge cases, failure modes |
|
||
| test-strategist | opus | Test patterns, coverage gaps, strategy |
|
||
| git-historian | opus | Recent changes, ownership, hot files |
|
||
| research-scout | opus | External docs for unfamiliar tech (conditional, planning only) |
|
||
| convention-scanner | opus | Coding conventions: naming, style, error handling, test patterns |
|
||
| brief-reviewer | opus | Task brief quality (6 dimensions: completeness, consistency, testability, scope clarity, research plan validity, memory alignment) |
|
||
| brief-conformance-reviewer | opus | Brief conformance review (SC + Non-Goal traceability) |
|
||
| code-correctness-reviewer | opus | Code correctness review (7 dimensions) |
|
||
| review-coordinator | opus | Judge Agent — dedup + reasonableness filter + verdict |
|
||
| plan-critic | opus | Adversarial plan review (10 dimensions) |
|
||
| scope-guardian | opus | Scope alignment (creep + gaps) |
|
||
| session-decomposer | opus | Splits plans into headless sessions with dependency graph |
|
||
| synthesis-agent | opus | Distills Phase-5/7 exploration outputs into a findings digest (NW3 PoC — **dormant**, not wired; delegating Phase 7 alone yields Δ main-context ≈ 0, see `docs/T1-synthesis-poc-results.md`) |
|
||
| docs-researcher | opus | Official documentation, RFCs, vendor docs (Tavily, MS Learn) |
|
||
| community-researcher | opus | Community experience: issues, blogs, discussions |
|
||
| security-researcher | opus | CVEs, audit history, supply chain risks |
|
||
| contrarian-researcher | opus | Counter-evidence, overlooked alternatives |
|
||
|
||
> **Inventory (S33 reconcile, updated v5.10.1).** 23 agent files = **20 spawnable** (one, `synthesis-agent`, ships **dormant** — Δ≈0, wired to nothing) **+ 3 orchestrator reference docs** (`planning-/research-/review-orchestrator` document the inline `/trek*` workflow, not spawnable capabilities). All 23 stay `model: opus` (operator pin `40d8742`); the glue/mechanical/retrieval/dormant roles were reconsidered for a sonnet downgrade and **kept opus** — decision record: `docs/voyage-vs-cc-balance-analysis.md` §10.
|
||
|
||
> **Model & effort.** On the Anthropic API, `opus` = Opus 5.5 and `sonnet` = Sonnet 5.5 (both default reasoning effort `medium`); `fable` = Fable 5.1 (the most capable model in Claude Code; default `high`, so xhigh must be chosen explicitly). An agent without `effort:` inherits the session level. Eight agents pin native per-spawn `effort: high` and the rest follow the session; none pins below `high` — a different axis from brief `phase_signals.effort` (orchestration shape: which agents/passes run). Per-agent table + axes → `docs/profiles.md` §Model & effort axes.
|
||
|
||
## Reference docs (read on demand)
|
||
|
||
- **Architecture, workflows, project-directory contract, state, terminology:** `docs/architecture.md`
|
||
- **Quality infrastructure (`lib/` validators, parsers, autonomy primitives, hooks):** `docs/architecture.md` §Quality infrastructure
|
||
- **Autonomy gates (`--gates`), Path A/B/C decision:** `docs/operations.md`
|
||
- **Profile system (`--profile economy/balanced/premium/fable`), lookup order, custom profiles:** `docs/operations.md`
|
||
- **Observability (Stop hook, OTLP/textfile export, SSRF mitigation):** `docs/operations.md`
|
||
- **Handover contracts (the 7 pipeline handovers):** `docs/HANDOVER-CONTRACTS.md`
|