feat(plan): plan 1.8, the plan gate, the design part and the plan-side checks

Wave 1, order 3 (P3 plan mode as the start, P2 design as its own part, P9
plan side). Contracts K3-K6 for the later merges.

- plan_version 1.8 (1.7 plans stay valid): Test first on every step, one
  End-to-end ("run the thing") step, optional Interface in / Interface out /
  Review focus fields, a ceremony class in the header (absent =
  architectural), and for architectural plans a ## Design part: module map
  without cycles, architecture rules that name their enforcer and the step
  that proves them, a requirements check asked as keep / change.
- K3 lib/validators/plan-gate.mjs: the critic verdict is recorded INSIDE the
  plan (Claude Code's plan approval hands a hook only the plan file's text),
  bound to the hash taken before the reviewers read it; 0 go / 1 stop / 2
  could not run; at most 3 critic rounds, then stop and ask.
- K5 lib/verification/arch-rules.mjs: runs the target repo's own
  dependency-cruiser or import-linter (installs nothing; 2 = not measured,
  never green); --prove --rule shows pass -> fail on a planted violation of
  that rule -> pass. Verified against dependency-cruiser 18.5.0 and
  import-linter 2.15; madge 8.0.0 left out (missed a planted .mjs cycle).
- K6 lib/verification/plan-scope-sweep.mjs: changed files no step names.
- /trekplan Phases 8-10: design part, bounded critic loop, the gate before
  "execute", a plan-mode path through ExitPlanMode (not yet run end to end
  inside plan mode). plan-critic 10 -> 12 dimensions; scope-guardian checks
  the ceremony.
- Fixed on the way: plan-validator and plan-review-dedup used the
  file://argv[1] main guard (no-op under a symlink or a space); CRLF plans
  failed every manifest; the dedup dropped finding severity.

Borrowed, credited in place: obra/superpowers, Kiro (docs), addyosmani/
agent-skills, mattpocock/skills, GitHub Spec Kit, bashebr/ai-native-sdlc,
Boris Cherny's public threads.

Suite 1497 (1495 / 0 / 2), 86 new tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-06 20:10:57 +02:00

9.6 KiB

Raw Blame History

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.

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. Plan 1.8: `Test first:` per step + one `End-to-end:` step; a design part for `ceremony: architectural` (absent = architectural); critic loop of max 3 rounds, recorded in the plan, and `plan-gate.mjs` (0 go / 1 stop / 2 could not run) decides	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.

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 (12 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

9.6 KiB Raw Blame History Unescape Escape

trekplan

Commands

Agents

Reference docs (read on demand)

9.6 KiB

Raw Blame History