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.

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
/trekrevise	Revise — apply operator annotations from the playground back into brief/plan/review with audit trail (Handover 8). Requires --project	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	sonnet

/trekbrief modes

Flag	Behavior
(default)	Dynamic interview until quality gates pass → brief.md with research plan
--quick	Compact start; still escalates if required sections are weak or the brief-review gate fails → brief.md with research plan
--gates {open|closed|adaptive}	(v3.4.0) Autonomy-checkpoint policy. Default adaptive
--profile <name>	(v4.1.0) Model profile: economy / balanced / premium / <custom>. Sets phase_models for the brief phase. See ## Profile system below.

Always interactive. Phase 3 is a section-driven completeness loop (no hard cap on question count); Phase 4 runs a brief-reviewer stop-gate with max 3 review iterations. After writing the brief, asks the user to choose manual (print commands) or auto (Claude runs research + plan in foreground).

/trekresearch modes

Flag	Behavior
(default)	Interview + research (local + external) + synthesis + brief (foreground)
--project <dir>	Write brief to {dir}/research/{NN}-{slug}.md (auto-incremented)
--quick	Interview (short) + inline research (no agent swarm)
--local	Only codebase analysis agents (skip external + Gemini)
--external	Only external research agents (skip codebase analysis)
--fg	No-op alias (foreground is default since v2.4.0)
--gates {open|closed|adaptive}	(v3.4.0) Autonomy-checkpoint policy. Default adaptive
--profile <name>	(v4.1.0) Model profile for the research phase. See ## Profile system below.

Flags combine: --project <dir> --local, --external --quick.

/trekplan modes

Flag	Behavior
--project <dir>	Required path A — read {dir}/brief.md, auto-discover {dir}/research/*.md, write {dir}/plan.md
--brief <path>	Required path B — plan from a specific brief file; write to .claude/plans/trekplan-{date}-{slug}.md
--research <brief> [brief2]	Enrich with extra research briefs beyond what is in {project_dir}/research/
--fg	No-op alias (foreground is default since v2.4.0)
--quick	Plan directly (no agent swarm)
--export <pr|issue|markdown|headless> <plan>	Generate shareable output from existing plan
--decompose <plan>	Split plan into self-contained headless sessions
--gates {open|closed|adaptive}	(v3.4.0) Autonomy-checkpoint policy. Default adaptive
--profile <name>	(v4.1.0) Model profile for the plan phase (and others, since plan emits profile: to plan.md frontmatter). See ## Profile system below.

Breaking change (v2.0): one of --brief or --project is required. There is no interview inside /trekplan. The --spec flag has been removed — use /trekbrief to produce a brief instead.

If {project_dir}/architecture/overview.md exists (typically produced by an opt-in upstream architect plugin, not bundled), the plan command auto-discovers it and treats cc_features_proposed as priors. Missing file is fine — discovery is additive, not required.

/trekexecute modes

Flag	Behavior
(default)	Execute plan — auto-detects Execution Strategy for multi-session
--project <dir>	Read {dir}/plan.md, write {dir}/progress.json
--resume	Resume from last progress checkpoint
--dry-run	Validate plan structure without executing
--validate	Schema-only check — parse steps + manifests, report READY | FAIL, no execution
--step N	Execute only step N
--fg	Force foreground — run all steps sequentially, ignore Execution Strategy
--session N	Execute only session N from plan's Execution Strategy
--gates {open|closed|adaptive}	(v3.4.0) Autonomy-checkpoint policy. Default adaptive
--profile <name>	(v4.1.0) Model profile for the execute phase. Inherited from plan.md frontmatter profile: if present. See ## Profile system below.

/trekreview modes

Flag	Behavior
(default)	Run brief-conformance + code-correctness reviewers in parallel, coordinator dedup + verdict, write {project_dir}/review.md
--project <dir>	Required. Path to trekplan project folder containing brief.md. Review is written to {dir}/review.md
--since <ref>	Override "before" SHA for the diff range. Validated via git rev-parse --verify
--quick	Skip brief-conformance reviewer; skip coordinator's reasonableness filter — fast correctness-only pass
--validate	Schema-only check on existing {dir}/review.md. No LLM calls
--dry-run	Print discovered scope + triage map; skip writes
--fg	No-op alias (foreground is default)
--profile <name>	(v4.1.0) Model profile for the review phase. See ## Profile system below.

/trekcontinue modes

Flag	Behavior
(default)	Auto-discover active project's .session-state.local.json and resume
<project-dir>	Resume the next session of an explicit project directory
--profile <name>	(v4.1.0) Model profile for the resumed session. Inherited from the previous session's plan.md frontmatter when absent. See ## Profile system below.

The triage gate is deterministic — path-pattern classifier produces {file → deep-review|summary-only|skip}. Hard refuse-with-suggestion above 100 files / 100K diff tokens.

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	sonnet	Codebase structure, tech stack, patterns
dependency-tracer	sonnet	Import chains, data flow, side effects
task-finder	sonnet	Task-relevant files, functions, reuse candidates
risk-assessor	sonnet	Risks, edge cases, failure modes
test-strategist	sonnet	Test patterns, coverage gaps, strategy
git-historian	sonnet	Recent changes, ownership, hot files
research-scout	sonnet	External docs for unfamiliar tech (conditional, planning only)
convention-scanner	sonnet	Coding conventions: naming, style, error handling, test patterns
brief-reviewer	sonnet	Task brief quality (5 dimensions: completeness, consistency, testability, scope clarity, research plan validity)
brief-conformance-reviewer	sonnet	Brief conformance review (SC + Non-Goal traceability)
code-correctness-reviewer	sonnet	Code correctness review (7 dimensions)
review-coordinator	sonnet	Judge Agent — dedup + reasonableness filter + verdict
plan-critic	sonnet	Adversarial plan review (9 dimensions)
scope-guardian	sonnet	Scope alignment (creep + gaps)
session-decomposer	sonnet	Splits plans into headless sessions with dependency graph
docs-researcher	sonnet	Official documentation, RFCs, vendor docs (Tavily, MS Learn)
community-researcher	sonnet	Community experience: issues, blogs, discussions
security-researcher	sonnet	CVEs, audit history, supply chain risks
contrarian-researcher	sonnet	Counter-evidence, overlooked alternatives
gemini-bridge	sonnet	Gemini Deep Research second opinion (conditional)

Quality infrastructure (v3.4.0)

lib/ contains zero-dep validators, parsers, and autonomy primitives wired into the four commands:

• lib/util/{frontmatter,result,atomic-write,autonomy-gate}.mjs — shared YAML-frontmatter parser + Result helpers + atomicWriteJson(path, obj) for tmp+rename writes + autonomy-gate state machine (v3.4.0)
• lib/parsers/{plan-schema,manifest-yaml,project-discovery,arg-parser,bash-normalize,jaccard,finding-id}.mjs — pure parsers (no I/O), unit-tested. manifest-yaml extended in v3.4.0 with additive skip_commit_check + memory_write flags (forward-compat: unknown keys ignored)
• lib/review/{rule-catalogue,plan-review-dedup}.mjs — version-pinned rule catalogue (12 keys) + Phase 9 inline dedup helpers (v3.4.0)
• lib/stats/event-emit.mjs — single-source stats event emitter for autonomy-gate transitions and main-merge-gate (v3.4.0)
• lib/validators/{brief,research,plan,progress,session-state}-validator.mjs — schema validators with CLI shims (node lib/validators/X.mjs --json <path>)
• lib/validators/architecture-discovery.mjs — drift-WARN external-contract discovery for architecture/overview.md

Wiring points (replaces previous prose-grep instructions):

• /trekbrief Phase 4g → brief-validator (post-write sanity check)
• /trekplan Phase 1 → brief-validator --soft, research-validator --dir, architecture-discovery
• planning-orchestrator Phase 5.5 → plan-validator --strict (replaces 3 grep -cE calls)
• /trekexecute --validate → plan-validator --strict + progress-validator

Tests under tests/**/*.test.mjs (~290 tests, 0 deps). npm test is the fork-readiness gate. v3.4.0 adds: synthetic determinism fixtures (tests/synthetic/plan-run-*.md + review-run-*.md + companion *-determinism.test.mjs enforcing Jaccard ≥ 0.833 SC7 floor) and hook baseline regression pins (tests/hooks/{path-guard,bash-guard}.test.mjs exercising pre-write-executor.mjs + pre-bash-executor.mjs denylist BLOCK paths).

Doc-consistency test at tests/lib/doc-consistency.test.mjs pins agent-table count, command-table coverage, plan_version invariant, settings.json scope cleanliness, Handover 7 presence, and session-state-validator CLI shim.

docs/HANDOVER-CONTRACTS.md is the single source of truth for the 7 pipeline handovers (brief→research, research→plan, architecture→plan EXTERNAL, plan→execute, progress.json resume, review→plan, .session-state.local.json). Read it before changing any artifact format.

hooks/scripts/pre-compact-flush.mjs (PreCompact event, CC v2.1.105+) fixes the documented P0 in docs/trekexecute-v2-observations-from-config-audit-v4.md: keeps progress.json in sync with git history before context compaction so --resume works after long conversations. Atomic write, monotonic only, never blocks compaction.

hooks/scripts/session-title.mjs (UserPromptSubmit, CC v2.1.94+) sets sessionTitle to voyage:<command>:<slug> for voyage-command invocations. Helps multi-session headless runs identify themselves in process lists.

hooks/scripts/post-bash-stats.mjs (PostToolUse, CC v2.1.97+) appends duration_ms for each Bash call into ${CLAUDE_PLUGIN_DATA}/trekexecute-stats.jsonl. Useful for finding long-running verify or checkpoint commands.

hooks/scripts/post-compact-flush.mjs (PostCompact event, v3.4.0) re-injects .session-state.local.json after context compaction so multi-session work survives a compaction boundary. Companion to pre-compact-flush.mjs (which writes the state file before compaction); together they form the rehydrate cycle that keeps /trekcontinue reliable across long-running multi-session work.

Autonomy mode (--gates, v3.4.0)

All four pipeline commands accept --gates {open|closed|adaptive}:

Value	Behavior
open	Skip optional checkpoints; trust manifests + verify gates only
closed	Stop at every autonomy boundary; operator confirms each transition
adaptive (default)	Stop only at meaningful boundaries (manifest-audit FAIL, plan-critic BLOCKER, main-merge gate)

Under the hood: lib/util/autonomy-gate.mjs runs the state machine idle → approved → executing → merge-pending → main-merged. lib/stats/event-emit.mjs records each transition to ${CLAUDE_PLUGIN_DATA}/trek*-stats.jsonl. The main-merge gate is the final autonomy boundary before HEAD lands on main.

Path A/B/C decision (v3.4.0; Path C closed 2026-05-05)

Three architectural options were considered for the speedup work:

• Path A — cache-first (drop --allowedTools per child to recover cross-phase cache sharing): REJECTED. Inverts the security model; plugin hooks don't fire reliably in claude -p (research/06 GH #36071).
• Path B — sequential --no-ff parallel waves with manifest-driven failure recovery: CHOSEN. Ships in v3.4.0. Phase 2.6 of /trekexecute runs the wave executor with hardenings for plugin-in-monorepo + gitignored-state topology.
• Path C — hybrid (cache-warm sentinel + identical-tool parallel): CLOSED 2026-05-05. Q3 experiment measured median cache_creation_input_tokens = 163,903 across 3 fork-children at 186K parent context (CC v2.1.128, Sonnet 4.6). Master-plan thresholds: ≤ 1,500 POSITIVE / ≥ 3,500 NEGATIVE. Result is solidly NEGATIVE — CLAUDE_CODE_FORK_SUBAGENT does not preserve cache prefix across identical-tool children at our context size. Path C migration is deferred indefinitely; reassessment is appropriate when CC v2.2.xxx ships fork-cache-relevant features. Harness: scripts/q3-cache-prefix-experiment.mjs. Companion analyser: lib/stats/cache-analyzer.mjs.

A revived Path C (post-v2.2.xxx) would require: (1) re-architecting tool-list to be identical across all wave children, (2) cache-telemetry analysis confirming the new fork-cache behaviour holds, (3) prompt-level deny re-enablement to compensate for tool scoping rollback.

Profile system (--profile, v4.1.0)

Three built-in model profiles plus operator-defined <custom>.yaml. Each profile pins phase_models for the six pipeline phases (brief, research, plan, execute, review, continue). Profile is recorded in plan.md frontmatter as profile: <name> and emitted to ${CLAUDE_PLUGIN_DATA}/trek*-stats.jsonl for cost-attribution.

Profile	Brief	Research	Plan	Execute	Review	Continue	Use case
economy	sonnet	sonnet	sonnet	sonnet	sonnet	sonnet	Lowest cost; high-confidence small-scope tasks
balanced (default)	sonnet	sonnet	opus	sonnet	opus	sonnet	Default — opus where reasoning depth pays off
premium	opus	sonnet	opus	sonnet	opus	sonnet	Critical-path planning + review when budget allows

Lookup order

1. Explicit --profile <name> flag passed to the command
2. Plan-file frontmatter profile: (when resuming via /trekexecute --resume or /trekcontinue)
3. VOYAGE_PROFILE environment variable
4. Default balanced

Custom profiles

Create lib/profiles/<custom>.yaml to define a new tier. The validator (lib/validators/profile-validator.mjs) enforces: every phase_models[].phase must be a known phase enum; every phase_models[].model must match ^(opus|sonnet)(\b|-).* or one of the canonical short names. Custom profiles override built-ins of the same name (lookup is alphabetical with <custom> taking precedence).

Drift between plan-frontmatter profile: and step-manifest profile_used: emits a MANIFEST_PROFILE_DRIFT warning from plan-validator --strict (Step 20). Plan remains valid; the warning surfaces accidental tier-mismatch.

Observability (Stop hook, v4.1.0)

The Stop hook in hooks/hooks.json runs hooks/scripts/otel-export.mjs at session-end. The hook is opt-in — when VOYAGE_EXPORT_MODE is unset or off, no work is done.

Mode	Output	Endpoint env-var
off (default)	(no export)	—
textfile	voyage.prom (Prometheus exposition format)	VOYAGE_TEXTFILE_DIR
otlp	OTLP/JSON POST	VOYAGE_OTEL_ENDPOINT

Endpoint validation: VOYAGE_OTEL_ALLOW_PRIVATE=1 is required to send to loopback or RFC1918 destinations (CWE-918 SSRF mitigation). Allowlist lib/exporters/field-allowlist.mjs redacts records before export (CWE-212). Path validation (lib/exporters/path-validator.mjs) rejects symlink + traversal (CWE-22).

Local Docker Compose stack: examples/observability/. Operator docs: docs/observability.md. Both pin minimum versions per CVE history (prom/prometheus:v3.0.1, grafana/grafana:11.4.0, otel/opentelemetry-collector-contrib:0.115.0).

Architecture

Brief: 7-phase workflow: Parse mode → Create project dir → Phase 3 completeness loop (section-driven, no question cap) → Phase 4 draft/review/revise with brief-reviewer as stop-gate (max 3 iterations; gate = all dimensions ≥ 4 and research plan = 5) → Finalize (brief.md on pass, or brief_quality: partial on cap/force-stop) → Manual/auto opt-in → Stats. Always interactive. Auto mode runs research + plan inline in the main context (v2.4.0).

Research: Foreground workflow (v2.4.0): Parse mode → Interview → Parallel research swarm (5 local + 4 external + 1 bridge, spawned from main context) → Follow-ups → Triangulation → Synthesis + brief → Stats. With --project, writes to {dir}/research/NN-slug.md.

Plan: Foreground workflow (v2.4.0): Parse mode (validate brief input) → Codebase sizing → Brief review (brief-reviewer) → Parallel exploration (6-8 agents, spawned from main context) → Deep-dives → Synthesis (with architecture-note cross-reference if present) → Planning → Adversarial review (plan-critic + scope-guardian) → Present/refine → Handoff. With --project, writes to {dir}/plan.md and auto-detects {dir}/architecture/overview.md (produced by an opt-in upstream architect plugin if installed; not bundled).

Decompose: Parse plan → Analyze step dependencies → Group into sessions → Identify parallel waves → Generate session specs + dependency graph + launch script.

Execute: Parse plan → Security scan (Phase 2.4) → Detect Execution Strategy → Single-session (step loop) or multi-session (parallel waves via claude -p with scoped --allowedTools) → Phase 7.5 manifest audit → Phase 7.6 bounded recovery (if partial) → Phase 8 atomically writes progress.json + .session-state.local.json (Handover 7) → Report. With --project, reads {dir}/plan.md. Phase 2.55 (pre-flight stop) and Phase 4 (entry-condition stop) also write .session-state.local.json so /trekcontinue can surface the stop and prompt for next steps.

Continue: /trekcontinue reads {dir}/.session-state.local.json (Handover 7), validates schema-v1 via session-state-validator, narrates a 3-line summary (project / next-session-label / brief-path), and immediately begins executing the next session. Auto-discovers active project state files under .claude/projects/*/.session-state.local.json if no explicit <project-dir> argument. Operator-invoked only — never auto-loaded via SessionStart. The /trekendsession helper is the informal-flow producer: writes the same state file for ad-hoc multi-session handovers that don't run through /trekexecute.

Revise (v4.2): /trekrevise --project <dir> consumes a batch exported from playground/voyage-playground.html and folds operator annotations back into the source artifact (brief.md / plan.md / review.md). Phase 1 parse + validate, Phase 2 read source + rollback hygiene (*.local.bak via lib/util/revision-guard.mjs), Phase 3 parse anchors + validate placement (lib/parsers/anchor-parser.mjs — block-boundary discipline), Phase 4 compute revision diff + deterministic SHA-256 digest (lib/parsers/annotation-digest.mjs), Phase 5 atomic apply via lib/util/markdown-write.mjs, Phase 6 round-trip integrity (stripAnchors-of-written equals pre-write body), Phase 7 optional review-gate when target is plan and review.md exists, Phase 8 stats + report. Single-iteration MVP — each batch produces one revision: increment with source_annotations: audit trail. Handover 8 (docs/HANDOVER-CONTRACTS.md) — additive frontmatter; no *_version bump; artifacts written before v4.2 validate as revision: 0.

Playground (v4.3): playground/voyage-playground.html is the operator-facing surface for browsing voyage projects and editing annotations. v4.3 rebuilds the v4.2 playground from the ground up — dashboard-centric layout (fleet-grid of fleet-tile per artifact), file://-loader with three entry points (webkitdirectory directory-picker / drag-drop with webkitGetAsEntry recursive walk / URL-parameter ?project=/abs/path), block-boundary anchor placement matching browser-side parseAnchor to Node-side lib/parsers/anchor-parser.mjs regex, hidden-by-default sidebar-rail with J/K keyboard navigation, two-opacity pattern (active 100% / inactive 40% / resolved 30% strikethrough), A11Y panel built from DS-primitives, screenshots-spor convention via window.__voyage hooks (navigate / scheduleRender / getProjectArtifacts) + docs/screenshots/. Path-traversal + symlink/dotfile filter (isProjectPathSafe) blocks .. / node_modules/ / dist/ / build/ / hidden-paths with aria-live announces. DOMPurify ≥ 3.1.1 vendored for sanitizeAnnotation; HTML-comment indirect prompt-injection mitigation via parseAnchor-allowlist gate before md.render. Total bundle 388 KB / 460 KB HALT-gate. Test pyramid Groups A-D — Group A 17 static-HTML tests (SC1 10-element checklist + SC3 + SC6 + SC7 tag-level no-CDN), Group B 9 DS-token + theme-toggle + sidebar-tab + keyboard-pattern tests, Group C 7 export-bundle schema + annotation_digest SHA-256 validity tests, Group D 5 Playwright e2e specs (light/dark axe-core absolute zero-violation + pixel-diff smoke + inline-gallery + zero-external-network authoritative gate). See playground/README.md + docs/sc1-checklist-verification.md. A Sesjon 13–18 independent-review remediation cycle closed all 11 findings from the first /trekreview (DOMPurify on the artifact body, inline renderScreenshotGallery, absolute-zero-violation a11y spec, Phase 9 plan_critic injection, fleet-grid CSS parity). v4.3.0 ships with 3 new re-review findings deferred to v4.3.1: 87069b35 (renderScreenshotGallery interpolates screenshots[].dataUrl raw into an <img src> — defense-in-depth only, not exploitable from the operator file-load path, only via the window.__voyage.scheduleRender hook), 4cc3bfc9 (backtick template-literal ES-import specifier at commands/trekplan.md:745 Phase 9 — SyntaxError; documented fallback keeps plan.md valid, just without plan_critic), c6c64a58 (no test for the gallery dataUrl injection path). A plan-critic-reviewed Wave-4 remediation plan is ready; see CHANGELOG.md § "Known issues — deferred to v4.3.1".

Security: 4-layer defense-in-depth: plugin hooks (pre-bash-executor, pre-write-executor), prompt-level denylist (works in headless sessions), pre-execution plan scan (Phase 2.4), scoped --allowedTools replacing --dangerously-skip-permissions. Hard Rules 14-16 enforce verify command security, repo-boundary writes, and sensitive path protection.

Pipeline: /trekbrief produces the task brief. /trekresearch --project <dir> fills in {dir}/research/. /trekplan --project <dir> reads brief + research to produce {dir}/plan.md (and auto-discovers {dir}/architecture/overview.md if an opt-in upstream architect plugin produced one). /trekexecute --project <dir> executes and writes {dir}/progress.json. /trekreview --project <dir> produces {dir}/review.md. /trekrevise --project <dir> (v4.2) folds operator annotations back into any of the three artifacts in-place, with audit trail in frontmatter. All artifacts live in one project directory.

Project-directory contract (v3.0.0): trekplan owns the directory layout below. The architecture/ subdirectory is opt-in and produced by an opt-in upstream architect plugin (not bundled) — the architect plugin is no longer publicly distributed, but the architecture/overview.md slot remains available for any compatible producer.

.claude/projects/{YYYY-MM-DD}-{slug}/
  brief.md           ← trekbrief writes; everyone reads; trekrevise mutates in-place
  research/*.md      ← trekresearch writes; plan + architect read
  architecture/      ← OPT-IN, owned by an opt-in upstream architect plugin (not bundled)
    overview.md
    gaps.md
  plan.md            ← trekplan writes; trekexecute reads; trekrevise mutates in-place
  progress.json      ← trekexecute writes
  review.md          ← trekreview writes; trekplan reads (Handover 6); trekrevise mutates in-place

No code-level dependency between plugins — the contract is filesystem-level only.

State

All artifacts in one project directory (default):

• Project root: .claude/projects/{YYYY-MM-DD}-{slug}/
  • brief.md (task brief from /trekbrief)
  • research/{NN}-{slug}.md (research briefs from /trekresearch --project)
  • architecture/overview.md + architecture/gaps.md (opt-in, produced by an opt-in upstream architect plugin, not bundled)
  • plan.md (from /trekplan --project)
  • sessions/session-*.md (from --decompose)
  • progress.json (from /trekexecute --project)
  • review.md (from /trekreview --project)
  • .session-state.local.json (Handover 7 — gitignored via *.local.json; written by /trekexecute Phase 8/2.55/4 or /trekendsession; read by /trekcontinue)

Legacy paths (still work without --project):

• Research briefs: .claude/research/trekresearch-{date}-{slug}.md
• Plans: .claude/plans/trekplan-{date}-{slug}.md
• Sessions: .claude/trekplan-sessions/{slug}/session-*.md
• Launch scripts: .claude/trekplan-sessions/{slug}/launch.sh
• Progress: {plan-dir}/.trekexecute-progress-{slug}.json

Stats:

• Brief stats: ${CLAUDE_PLUGIN_DATA}/trekbrief-stats.jsonl
• Plan stats: ${CLAUDE_PLUGIN_DATA}/trekplan-stats.jsonl
• Exec stats: ${CLAUDE_PLUGIN_DATA}/trekexecute-stats.jsonl
• Research stats: ${CLAUDE_PLUGIN_DATA}/trekresearch-stats.jsonl
• Continue stats: ${CLAUDE_PLUGIN_DATA}/trekcontinue-stats.jsonl

Terminology

• Task brief — produced by /trekbrief. Declares intent, goal, and research plan. Drives planning.
• Research brief — produced by /trekresearch. Answers a specific research question. Feeds planning.
• Architecture note — opt-in, produced by an opt-in upstream architect plugin (not bundled; the architect plugin is no longer publicly distributed, but the architecture/overview.md filesystem slot remains available for any compatible producer). Proposes which Claude Code features fit the task with brief-anchored rationale + explicit gaps. When present, enriches planning.
• Review — produced by /trekreview. Independent post-hoc review of delivered code against the task brief. Handover 6 (review → plan) routes BLOCKER + MAJOR findings into /trekplan --brief review.md for a remediation plan. The plan's optional source_findings: frontmatter list is the audit trail back to the consumed findings. MINOR + SUGGESTION are skipped for v1.0 plan-input.
• Session state — .session-state.local.json per project. Handover 7 — produced by any session-end mechanism (/trekexecute Phase 8/2.55/4, /trekendsession helper, future graceful-handoff v2.2). Consumed by /trekcontinue to resume the next session in a fresh chat. Schema v1 is forward-compat (unknown top-level keys ignored). Never committed (gitignored via *.local.json).

A project typically has 1 task brief, 0–N research briefs, 0 or 1 architecture note, 0–N reviews (one per review iteration), and 0 or 1 session-state file (overwritten on every session-end).