ktg-plugin-marketplace/plugins/voyage/CLAUDE.md

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.

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), alle BLOCKER ved brudd når v5.5 shipper: (1) eksplisitt framing: preserve|refine|replace|new-direction i brief-frontmatter, AskUserQuestion-validert før brief-prosa skrives; (2) memory-alignment check som ny dimensjon i brief-reviewer — sammenlikner brief-prosa mot relevante memory-filer og rapporterer eksplisitte motsigelser; (3) obligatorisk ## TL;DR-seksjon (≤ 5 linjer) øverst i brief.md. Implementeres i v5.5 — se ROADMAP.md. Inntil shipping: operatør må manuelt sjekke at briefens framingord ikke motsier intent, særlig etter avvist iterasjon hvor "delta fra forrige" er en farlig default-ankring.

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 (5 dimensions: completeness, consistency, testability, scope clarity, research plan validity)
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)

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