open/voyage
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
voyage/CLAUDE.md
Kjell Tore Guttormsen 736ae55d66 feat(voyage): S6 — v5.5 brief framing enforcement (brief_version 2.2) 
Implements the CLAUDE.md cross-cutting invariant "brief framing must match
operator intent" as a controlled brief_version 2.1->2.2 bump (operator option A1).
Three defense layers, version-gated at >=2.2 so existing 2.0/2.1 briefs stay
valid (forward + backward compatible), mirroring the phase_signals >=2.1 gate:

- L1 framing: enum field (preserve|refine|replace|new-direction). Enum-checked
  on any version when present (BRIEF_INVALID_FRAMING); missing at >=2.2 ->
  BRIEF_MISSING_FRAMING. /trekbrief Phase 2.5 collects it BEFORE any brief prose
  (non-skippable, even in --quick).
- L2 memory alignment: new brief-reviewer dimension 6 comparing brief Intent/Goal
  + framing against operator memory for explicit contradictions; degrades to
  score 5 (N/A) when no memory context is supplied. Wired into Phase 4e gate
  (memory_alignment.score >= 4).
- L3 obligatory ## TL;DR (<=5 content lines) at >=2.2; soft cap ->
  BRIEF_TLDR_TOO_LONG warning.

trekreview briefs are exempt from the framing/TL;DR gate. Handover 1 PUBLIC
CONTRACT doc, README "What's new", and the CLAUDE.md invariant + agents table
(brief-reviewer 5->6 dimensions) updated to 2.2 (schema axis only; plugin
version badge + CHANGELOG remain S10).

Iron Law followed: validator tests red->green first. Tests 586 -> 606
(+20, 604 pass / 2 skip). claude plugin validate passes (pre-existing
CLAUDE.md root-context warning unchanged).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqBYc8Ltrk7LipyJmGxXiB
2026-06-18 13:09:50 +02:00

7.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.

v3.0.0 — architect step extracted from this plugin. The plan command still auto-discovers architecture/overview.md if present, so any compatible producer (architect plugin no longer publicly distributed; the architecture/overview.md slot remains available for any compatible producer) plugs into the same slot. See CHANGELOG.md for migration history.

Trinity context (2026-05-13, informational). Voyage is Tier 1 (per-task) of a three-tier architecture in active design under the author's private marketplace: Tier 2 app-creator (per-app — "what does the app need, what's the next brief?") produces briefs Voyage consumes; Tier 3 app-factory (per-portfolio — "which app needs me now?") aggregates state across multiple app-creator instances. Both are pre-implementation and will ship to Forgejo when ready. Asymmetry is a hard invariant: Voyage stays unaware of Tier 2/3. Handover 1 (brief format) is the only integration point — any compatible producer can feed Voyage, app-creator is not privileged. Brief-schema changes are therefore breaking changes for downstream consumers, formalized as a public contract in v5.4 — see docs/HANDOVER-CONTRACTS.md §Handover 1 (PUBLIC CONTRACT).

Cross-cutting invariant: brief framing must match operator intent (2026-05-15). Etablert etter residiv. Briefen er pipelinens source of truth; operatørens intent lever i hodet + i memory-filer (feedback_*, project_*); pipelinen tvinger ikke alignment. Høyere reasoning-kraft polerer feil premiss istedenfor å utfordre det. Tre lag av forsvar (input-siden), implementert i S6 som brief_version 2.2-gate (v5.5), alle BLOCKER ved brudd for briefer som deklarerer ≥ 2.2: (1) eksplisitt framing: preserve|refine|replace|new-direction i brief-frontmatter, AskUserQuestion-validert i /trekbrief Phase 2.5 før brief-prosa skrives (ikke-skippbar, også i --quick); enum-feil → BRIEF_INVALID_FRAMING (alle versjoner), fravær ved ≥ 2.2 → BRIEF_MISSING_FRAMING; (2) memory-alignment som dimensjon 6 i brief-reviewer — sammenlikner brief-prosa + framing mot relevante memory-filer, rapporterer kun eksplisitte motsigelser (degraderer til score 5 N/A uten memory-kontekst), wired til Phase 4e-gate (memory_alignment.score ≥ 4); (3) obligatorisk ## TL;DR-seksjon (≤ 5 linjer, soft-cap → BRIEF_TLDR_TOO_LONG) øverst i brief.md. Eksisterende 2.0/2.1-briefer forblir gyldige (forward+backward-compat, speiler phase_signals ≥ 2.1-presedensen); trekreview-briefer er unntatt. Schema-akse bumpet (2.1→2.2); plugin-versjon-badge + CHANGELOG bumpes ved den koordinerte releasen (S10). Kontrakt-evolusjon dokumentert i docs/HANDOVER-CONTRACTS.md §Handover 1. Den gamle manuelle stopgap-sjekken er dermed retired for ≥ 2.2-briefer.

Commands

Command Description Model
/trekbrief Brief — interactive interview produces a task brief with explicit research plan; optionally orchestrates the pipeline opus
/trekresearch Research — deep local + external research, produces structured research brief opus
/trekplan Plan — brief-reviewer, explore, plan, review. Requires --brief or --project. Auto-discovers architecture/overview.md if present opus
/trekexecute Execute — disciplined plan/session-spec executor with failure recovery opus
/trekreview Review — independent post-hoc review of delivered code against the brief. Produces review.md with severity-tagged findings (Handover 6) opus
/trekcontinue Continue — resumes the next session of a multi-session voyage project. Reads .session-state.local.json (Handover 7) and immediately begins executing opus
/trekendsession End-session — mark the current session complete and write session-state pointing at the next session. Helper for informal multi-session flows opus

Full flag reference for each command (modes, --gates, --profile, breaking changes): see docs/command-modes.md.

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 (9 dimensions)
scope-guardian opus Scope alignment (creep + gaps)
session-decomposer opus Splits plans into headless sessions with dependency graph
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
gemini-bridge opus Gemini Deep Research second opinion (conditional)

Model & effort (CC 2.1.154+). opus resolves to Opus 4.8 (default reasoning effort high); sonnet to Sonnet 4.6. Select agents carry native effort: — retrieval agents (task-finder, git-historian, dependency-tracer, architecture-mapper) at medium, adversarial-reasoning agents (plan-critic, risk-assessor, contrarian-researcher, review-coordinator) at high. This native per-spawn reasoning effort is a different axis from brief phase_signals.effort (orchestration shape — which agents/passes run). See 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), 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