diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 48ff166..bc9c396 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,23 +1,12 @@ { "name": "voyage", "description": "Voyage — brief, research, plan, execute, review, continue. Contract-driven Claude Code pipeline. /trekbrief, /trekplan, and /trekreview each end by building a self-contained operator-annotation HTML (scripts/annotate.mjs, modelled on claude-code-100x): select text or click any element, pick intent (Fiks/Endre/Spørsmål), write comment, copy structured prompt, paste back, Claude revises the .md.", - "version": "5.9.1", + "version": "5.6.1", "author": { "name": "Kjell Tore Guttormsen" }, "homepage": "https://git.fromaitochitta.com/open/ktg-plugin-marketplace/src/branch/main/plugins/voyage", "repository": "https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git", "license": "MIT", - "keywords": [ - "voyage", - "trek", - "planning", - "implementation", - "research", - "context-engineering", - "agents", - "adversarial-review", - "headless", - "execution" - ] + "keywords": ["voyage", "trek", "planning", "implementation", "research", "context-engineering", "agents", "adversarial-review", "headless", "execution"] } diff --git a/.gitignore b/.gitignore index b92beb2..822742e 100644 --- a/.gitignore +++ b/.gitignore @@ -19,10 +19,8 @@ blob-report/ # Local configuration / session files *.local.* -# STATE.md — current state-of-play. LOCAL-ONLY per ~/.claude/CLAUDE.md: -# origin is open/ (an OFFENTLIG/public mirror) → STATE must NEVER be pushed there. -# Kept local for continuity only. History scrubbed 2026-06-26 (was wrongly tracked 23 commits). -STATE.md +# STATE.md — current state-of-play. TRACKED continuity per ~/.claude/CLAUDE.md +# (overrides the polyrepo gitignore convention); pushed to private Forgejo, never public. # Local planning docs (briefs, design notes, observations) — never committed. # Existing tracked files in docs/ predate this rule; new planning docs stay local. @@ -32,7 +30,7 @@ docs/ultracontinue-design-notes.md # Ultraplan project directories — briefs, research, plans, progress all local. .claude/projects/ -# --- session/local state (gitignored) — STATE.md is LOCAL-ONLY (open/ = public), se ~/.claude/CLAUDE.md --- +# --- session/local state (gitignored) — STATE.md er nå tracked, se ~/.claude/CLAUDE.md --- REMEMBER.md ROADMAP.md TODO.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 21b08e3..e5f539b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,103 +4,6 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). -## v5.9.1 — 2026-07-03 — Fix /trekendsession load-time crash (eager-exec placeholders) - -Patch, no functional additions. - -### Fixed - -- `/trekendsession` was unusable in every invocation: two of its three `` !`...` `` eager-exec blocks (Phase 3 atomic-write, Phase 4 validator call) contained unresolved runtime placeholders (`` etc.). The harness executes eager-exec blocks at command LOAD time, so zsh parsed `` as input redirection and the command aborted before the model saw a single instruction. Both blocks are now plain runtime Bash fences with the `{curly}` placeholder convention (shell-inert), matching `trekplan.md`/`trekresearch.md`. The Phase 1 discovery block (self-contained) keeps its legitimate eager-exec prefix; `trekcontinue.md`'s discovery block was runtime-verified unaffected. -- Latent secondary bug in the same blocks: cwd-relative plugin paths (`lib/validators/...`, `./lib/util/atomic-write.mjs`) would have failed with `ERR_MODULE_NOT_FOUND` even after substitution, since the Bash cwd is the user's repo. Both now use absolute `${CLAUDE_PLUGIN_ROOT}` paths per the existing command convention (Node ESM accepts absolute-path import specifiers — verified on Node 18+). - -### Added - -- Regression guard `tests/commands/trekendsession.test.mjs`: scans every `` !` ``-block in `commands/*.md` for unresolved ``/`{curly}` placeholders (this bug class is silent until first invocation), plus structure tests pinning Phase 3/4 as runtime Bash with `${CLAUDE_PLUGIN_ROOT}` paths and exactly one surviving eager block. Suite baseline 828 → 832 (830 pass / 0 fail / 2 skip). - -## v5.9.0 — 2026-07-02 — Fable model tier + deep-research engine - -Additive, plus one behavior alignment: profile `phase_models` now reach sub-agent spawn sites (previously documented but never wired), and the seven command orchestrators no longer pin `model: opus` — frontmatter omits `model:`, so the orchestrator follows the session model. - -### Fable model tier - -- `fable` (→ Claude Fable 5, Mythos-class, positioned above Opus) is an accepted model value throughout the validation chain: `BASE_ALLOWED_MODELS` widened to `['sonnet', 'opus', 'fable']` in `lib/validators/profile-validator.mjs` — the single source imported by brief-validator and phase-signal-resolver (two-layer gate preserved; accept-fable AND reject-unknown-model covered at both layers). No env gate — haiku's `VOYAGE_ALLOW_HAIKU` opt-in stays as-is. -- `/trekbrief` Phase 3.5 tier loop offers a 4th option: `fable → {effort: high, model: fable}`. AskUserQuestion's 4-option maximum is now fully used — a 5th tier requires a loop redesign. The fable tier reuses `effort: high` orchestration semantics; `EFFORT_LEVELS` is unchanged. -- New built-in profile `lib/profiles/fable.yaml` (all six phases on `fable`, modeled on premium; registered in `BUILTIN_NAMES` with a `loadProfile('fable')` canary test so a registry regression fails loudly instead of silently resolving premium). Premium stays the default. -- Reasoning effort is inherited from the session: Fable 5's default effort is `high`, NOT xhigh, and switching model resets effort — set xhigh at session level (`/effort xhigh`, the `effortLevel` setting, or `CLAUDE_CODE_EFFORT_LEVEL`). Documented canonically in `docs/profiles.md` §Model & effort axes. -- `claude-fable-5` added to the cost `PRICE_TABLE` ($10/MTok input, $50/MTok output; cache write 5m $12.50 / 1h $20; cache read $1 — verified 2026-07-02 against the official platform pricing docs). `PRICE_TABLE_VERSION` bumped to `2026-07-02`. Without the entry, every fable run would report `cost_usd: null` in the observability export. -- Profile tables + allowlist prose updated across README, `docs/profiles.md`, `docs/operations.md`, `docs/HANDOVER-CONTRACTS.md`, `docs/architecture.md`, `docs/command-modes.md`, templates, and CLAUDE.md; the S15 doc pins now machine-check the fable row cell-for-cell against `fable.yaml`. The `^(opus|sonnet)…` regex claim in two docs was corrected — validation is an exact string match against `BASE_ALLOWED_MODELS`; the regex never existed in code. - -### Behavior alignment: profile `phase_models` now reach sub-agent spawns - -- Pre-existing wiring gap (found in exploration): all four pipeline commands invoked only the brief-only `phase-signal-resolver.mjs`, so the `?? profile.phase_models[]` half of the documented composition rule never executed — `--profile ` never reached sub-agent spawns. -- Fixed with a single composed resolver: `resolver.mjs --resolve-phase-model` now returns `{effort, model, source}` (brief > profile > default, with effort passed through atomically) and is the one CLI the four pipeline commands invoke. A doc-consistency pin requires the composed invocation and forbids the brief-only CLI in command Bash blocks. -- **Behavior change (contract alignment):** `--profile economy/balanced` now genuinely reaches sub-agent spawn sites for the first time — behavior aligns with what the docs have long claimed. The premium default is unaffected in practice (premium resolves `opus`, which equals the frontmatter fallback). -- Command frontmatter: the `model: opus` line is DELETED from all seven commands — omission (not the disputed `inherit` literal) is the spelling both official surfaces document as session-inheritance, guarded by a frontmatter-absence doc pin. Accepted tradeoff: in a sonnet session the orchestrator runs on sonnet; re-add a frontmatter pin for deterministic orchestrator choice. The 24 `agents/*.md` `model: opus` pins are untouched (spawn-time injection wins; frontmatter is the fallback). `/trekcontinue`/`/trekendsession` spawn no exploration swarm and get no spawn-site injection; the continue phase is covered at resolver level and follows the session model. - -### Bundled unreleased work (since v5.8.0) - -- `/trekresearch --engine {swarm|deep-research}` (`581489a..9374820`): opt-in delegation of the external research phase to Claude Code's built-in `/deep-research` workflow, with in-context adapter + self-check, availability fallback to swarm (never hard-fails), and doc-consistency pins across surfaces. -- brief-validator CLI no-flag invocation fix (`926b768`). -- Deep-research engine research notes + docs (`60e9e7a`, `9d8e043`). - -### Operator + consume-side notes - -- The operator-global CLAUDE.md policy "Opus 4.8 default for all subagents" predates the fable tier; updating it is an operator action outside this repo. -- `/plugin update` compares against a stale local marketplace clone and can report "already at the latest version" after this release (Claude Code issues #35752 / #38271, both closed-not-planned). Reliable refresh: remove + re-add the marketplace, or `git pull --ff-only` in the marketplace clone. Cross-version skew consequence: a stale cached v5.8 brief-validator REJECTS fable-bearing briefs with `BRIEF_INVALID_MODEL` — enum widening is safe for new readers of old data, not old readers of new data. -- Org `availableModels` with `enforceAvailableModels: true` can make an inheriting orchestrator silently fall back to the first allowed model. - -### Release hygiene - -- Suite (measured with bare `npm test` at release): **828 (826 pass / 0 fail / 2 skipped)** — +17 over the pre-release ground-truth baseline of 811 measured 2026-07-02 (allowlist/gate coverage, fable profile pins, composed-resolver + frontmatter-absence doc pins, PRICE_TABLE case). -- Version sync: `plugin.json`, `package.json`, `package-lock.json`, README badge, CHANGELOG top entry all at `5.9.0`, guarded by `doc-consistency.test.mjs`. - -## v5.8.0 — 2026-06-30 — offline gold-scored output eval (SKAL-1·4b) - -Additive — no behavior change, no breaking change. Internal eval infrastructure only (`lib/` + `tests/` + docs); no command, agent, profile, or Handover contract touched. - -### Gold-scored output eval (SKAL-1·4b) - -- The review-coordinator self-eval gains its **scoring run**, building on the deterministic coordinator contract + golden corpus shipped as the 4a foundation in v5.7.0. -- `lib/review/gold-scorer.mjs`: `scoreFindings(runFindings, goldFindings)` matches at **`(file, rule_key)` granularity** (line + severity deliberately ignored) → `{ tp, fp, fn, precision, recall, f1, matched, missed, spurious }`; `scoreVerdict` checks exact verdict match. Pure — no I/O, no LLM, no network. Vacuous-set conventions (empty run → recall 0; empty gold → precision 0; f1 collapses to 0) are documented in the module header. -- `tests/fixtures/bakeoff-rich/runs/run-perfect.json`: the first **committed run** — reviewer payloads that, fed through `runContract`, reproduce all 5 seeded gold findings. The regression guard: any future contract change that silently suppresses or skips a seeded finding breaks the eval. -- `tests/lib/gold-eval.test.mjs`: the **scoring run**, wired into `node --test`. Asserts `run-perfect` scores precision/recall/f1 = 1.0 and `verdict == expected_verdict` (BLOCK). Offline: committed payloads, no live agent spawn (the LLM-in-the-loop grading is the separate 4c tier). -- **Third test-census category.** `lib/util/test-census.mjs` now reports a `goldEval` bucket (matched by `GOLD_EVAL_FILE_RE`) separately from `behavior` and `docPins` — a scoring run is neither behavior coverage nor a prose pin, so the honest-count invariant is a 3-way sum. -- `docs/eval-corpus/README.md`: SKAL-1·4b moved from "Future hardening" to an implemented section documenting the scorer, run format, and census category. -- Suite: **822 (820 pass / 0 fail / 2 skip)**, up from 809 (+10 scorer behavior tests, +3 eval scoring-run tests). The scorer test covers the discriminating paths (false negatives + false positives) and the degenerate empty-run / empty-gold cases, not merely the all-match case. -- Version sync: `plugin.json`, `package.json`, `package-lock.json`, README badge, CHANGELOG top entry all at `5.8.0`, guarded by `doc-consistency.test.mjs`. - -## v5.7.1 — 2026-06-29 — relocate agent `` blocks to body (always-loaded token trim) - -Performance/packaging change — no behavior change, no breaking change. (M4) - -### Always-loaded token trim - -- The 17 example-bearing agents each carried two `` blocks (34 total) inside their `description:` frontmatter. voyage launches its agents **by name** from the orchestrator commands, so those auto-selection examples were paying a per-turn token tax for a path the pipeline never uses. They are now relocated **verbatim** into each agent's body under a `## When to use — examples` section — preserved, not deleted. -- Frontmatter `description` chars across all 24 agents: **17,672 → 4,945** — roughly **3,180 fewer always-loaded tokens per turn** for every session with voyage enabled. The 7 zero-example agents are untouched; no system prompt, tools, model, or `name` changed. -- New invariant test in `tests/lib/agent-frontmatter.test.mjs`: no `` in any frontmatter `description`, and ≥ 34 `` retained across agent bodies (relocation moves, never deletes). Suite: **807 pass / 0 fail / 2 skip**. -- **The saving only reaches a machine after `/plugin marketplace update` + reload** — the delta is not instant on the machine that ships the release. -- Version sync: `plugin.json`, `package.json`, `package-lock.json`, README badge, CHANGELOG top entry all at `5.7.1`, guarded by `doc-consistency.test.mjs`. - -## v5.7.0 — 2026-06-26 — opt-in token/cost metering (SKAL-2) + eval foundation (SKAL-1·4a) - -Additive — no breaking change. Two unreleased work-streams land together. - -### Opt-in token/cost metering (SKAL-2) — the headline - -- Pure token-usage parser + cache-aware USD cost (`lib/stats/token-usage.mjs`): parses MAIN-CONTEXT usage from the transcript, dedups by requestId (last-wins, streaming-placeholder mitigation), excludes sidechain records, and REFUSES to estimate (`cost_usd:null, is_estimate:true`) for models absent from the frozen PRICE_TABLE. -- CWE-212 export boundary: token-usage schema allowlist in the OTLP exporter; `session_id`/`transcript_path`/`cwd` stripped at export, asserted both ways. -- Cross-session aggregation in `cache-analyzer` (total tokens + cost). -- Capture folded into the EXISTING `otel-export.mjs` Stop hook, gated behind the `VOYAGE_TOKEN_METER` env var (default off), fail-open. v1 scope = main-context only; sub-agent turns are a documented v2 follow-on. - -### Eval foundation (SKAL-1·4a) - -- `gold.json` golden corpus + loader/validator; review-coordinator contract reference impl + deterministic test; two-sided gate coverage for the `BRIEF_*` BLOCKERs; eval-corpus frozen-failure home. - -### Release hygiene - -- Version sync: `plugin.json`, `package.json`, `package-lock.json`, README badge, CHANGELOG top entry all at `5.7.0`, guarded by `doc-consistency.test.mjs`. -- Canonical `node --test`: **807** (805 pass / 0 fail / 2 skipped). - ## v5.6.1 — 2026-06-24 — leaner always-loaded agent listing (reference/dormant agent descriptions trimmed) Additive — no breaking change, **no runtime behavior change**. Trims the always-loaded token cost of the agent listing that Claude Code injects into every session. diff --git a/CLAUDE.md b/CLAUDE.md index ffac6fb..9c1c22e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,20 +2,20 @@ 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`). +**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 claim that fanning out to a swarm *relieves* the main context is asserted-by-design, not measured end-to-end: the one delegation actually measured — the Phase-7 synthesis PoC — found Δ main-context ≈ 0, see `docs/T1-synthesis-poc-results.md`. The parallel wall-clock + structured artifact handoffs are the load-bearing benefit; main-context relief is not yet demonstrated.) -> **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). +> **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](CHANGELOG.md) for migration history. -> **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). +> **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.5.0 — see `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). +> **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. Opt-in `--engine {swarm\|deep-research}` delegates the external phase to Claude Code's built-in `/deep-research` workflow (swarm default) | 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 | @@ -53,15 +53,15 @@ Full flag reference for each command (modes, `--gates`, `--profile`, breaking ch | contrarian-researcher | opus | Counter-evidence, overlooked alternatives | | gemini-bridge | opus | Gemini Deep Research second opinion (conditional) | -> **Inventory (S33 reconcile).** 24 agent files = **21 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 24 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. +> **Inventory (S33 reconcile).** 24 agent files = **21 spawnable** (one of which, `synthesis-agent`, ships **dormant** — Δ≈0, wired to nothing, see `docs/T1-synthesis-poc-results.md`) **+ 3 orchestrator reference docs** (`planning-/research-/review-orchestrator` document the inline `/trek*` workflow; they are reference documentation, not spawnable capabilities). All 24 stay `model: opus` (operator pin `40d8742`); the glue/mechanical/retrieval/dormant roles (V09 gemini-bridge, V16 session-decomposer, V11 retrieval agents, V08 researchers, V35 synthesis) were reconsidered for a sonnet downgrade and **kept opus** — document-only, no frontmatter change (the decision record lives in `docs/voyage-vs-cc-balance-analysis.md` §10). -> **Model & effort.** `opus` = Opus 4.8 (default reasoning effort `high`); `sonnet` = Sonnet 4.6; `fable` = Fable 5 (Mythos-class, above Opus — reasoning effort inherits from the session; xhigh requires a session-level setting). Select agents carry native per-spawn `effort:` (retrieval → `medium`, adversarial-reasoning → `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. +> **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/fable`), lookup order, custom profiles:** `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` diff --git a/README.md b/README.md index 1cb5546..f95ce45 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # trekplan — Brief, Research, Plan, Execute, Review, Continue -![Version](https://img.shields.io/badge/version-5.9.1-blue) +![Version](https://img.shields.io/badge/version-5.6.1-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![Platform](https://img.shields.io/badge/platform-Claude%20Code-purple) @@ -10,7 +10,7 @@ A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, autonomous execution, independent post-hoc review, and zero-friction multi-session resumption. Six commands, one pipeline: -> **What's new — v5.8.0: offline gold-scored output eval (SKAL-1·4b).** The review-coordinator self-eval gains a scoring run: `lib/review/gold-scorer.mjs` grades a committed agent-run fixture against the golden corpus at `(file, rule_key)` granularity (precision/recall/f1 + verdict match), and the suite census gains a third category (`goldEval`) so a scoring run is counted apart from behavior coverage and doc-pins. Offline + deterministic — committed reviewer payloads, no live agent spawn (the LLM-in-the-loop tier is the separate 4c). Internal eval infrastructure; no command/agent/Handover change. **v5.7.1:** leaner always-loaded agent listing — `` blocks relocated to agent bodies (~3,180 tok/turn, no behavior change). **v5.7.0:** opt-in per-session token/cost metering (SKAL-2) + eval foundation (SKAL-1·4a). **v5.6.1:** one-line `description:` for the four reference/dormant agents (~700 tok). **v5.5.0:** brief **framing** enforcement (`brief_version 2.2`) + a `/trekreview` reviewer-schema contract. Additive — no breaking changes. **Full version history → [CHANGELOG.md](CHANGELOG.md).** +> **What's new — v5.6.1: leaner always-loaded agent listing.** The four reference/dormant agents (the three `*-orchestrator` reference docs + the dormant `synthesis-agent`) now carry one-line `description:` frontmatter — their full rationale already lives in each file's body — trimming ~700 tokens from the agent listing injected into every session, with no behavior change. **v5.6.0: `/trekexecute` loop hardening.** Execution-loop termination is now machine-verifiable (completion gate, Hard Rule 18) and recovery is bounded by an explicit `TREKEXECUTE_MAX_RECOVERY_ITERATIONS` budget (default 25, Hard Rule 20). The prior coordinated release **v5.5.0** added brief **framing** enforcement (`brief_version 2.2`) + a `/trekreview` reviewer-schema contract. Additive — no breaking changes. **Full version history → [CHANGELOG.md](CHANGELOG.md).** | Command | What it does | |---------|-------------| @@ -151,7 +151,7 @@ Output: `.claude/projects/{YYYY-MM-DD}-{slug}/brief.md` |------|-------|----------| | **Default** | `/trekbrief ` | Dynamic interview until quality gates pass. No question cap. | | **Quick** | `/trekbrief --quick ` | Starts compact (optional sections get at most one probe), still escalates on weak required sections or failed review gate. | -| **Profile** | `/trekbrief --profile ` | (v4.1.0) Pin model profile for the brief phase: `economy` / `balanced` / `premium` / `fable` / ``. See [Profile system](#profile-system-v410) below. | +| **Profile** | `/trekbrief --profile ` | (v4.1.0) Pin model profile for the brief phase: `economy` / `balanced` / `premium` / ``. See [Profile system](#profile-system-v410) below. | `/trekbrief` is **always interactive**. There is no foreground/background mode — the interview requires user input. @@ -195,7 +195,6 @@ Output: | **External** | `/trekresearch --external ` | Only external research agents (skip codebase analysis) | | **Foreground** | `/trekresearch --fg ` | No-op alias (foreground is default since v2.4.0) | | **Profile** | `/trekresearch --profile ` | (v4.1.0) Pin model profile for the research phase. See [Profile system](#profile-system-v410). | -| **Engine** | `/trekresearch --external --engine deep-research ` | Delegate the external phase to Claude Code's built-in `/deep-research` workflow; falls back to `swarm` if unavailable. Default `swarm`. | Flags combine: `--project --external`. @@ -779,14 +778,13 @@ An optional architect step between research and plan was previously available vi ## Profile system (v4.1.0) -Four built-in model profiles plus operator-defined `.yaml` (drop in `lib/profiles/`). Each profile pins `phase_models` for the six pipeline phases. The active profile is recorded in plan.md frontmatter as `profile: ` and emitted to JSONL stats for cost-attribution. +Three built-in model profiles plus operator-defined `.yaml` (drop in `lib/profiles/`). Each profile pins `phase_models` for the six pipeline phases. The active profile is recorded in plan.md frontmatter as `profile: ` and emitted to JSONL stats for cost-attribution. | Profile | Brief | Research | Plan | Execute | Review | Continue | Use case | |---------|-------|----------|------|---------|--------|----------|----------| | `economy` | sonnet | sonnet | sonnet | sonnet | sonnet | sonnet | ⚠ **Experimental** (uncalibrated Jaccard floor) — lowest cost; high-confidence small-scope tasks (opt-in via `--profile economy`) | | `balanced` | sonnet | sonnet | opus | sonnet | opus | sonnet | Mixed — opus where reasoning depth pays off (opt-in via `--profile balanced`) | | `premium` (default) | opus | opus | opus | opus | opus | opus | Maximum quality — Opus on every phase (default since the 2026-05-13 operator decision) | -| `fable` | fable | fable | fable | fable | fable | fable | Max quality — Fable 5 (Mythos-class, above Opus) on every phase (opt-in via `--profile fable`); reasoning effort inherits from the session | Lookup order: @@ -811,9 +809,9 @@ Default JSONL stats stream (`${CLAUDE_PLUGIN_DATA}/trek*-stats.jsonl`) is unchan ## Cost profile -The default `premium` profile runs **Opus on every phase** of the pipeline's agent work — the exploration and review swarms (5–10 sub-agents per command; spawn sites inject the composed brief > profile > frontmatter resolution, with `agents/*.md` `model: opus` pins as the fallback) and the executor (one per plan session). The command orchestrator itself is not profile-controlled: as of v5.9, command frontmatter omits `model:`, so the orchestrator follows the session model. For cheaper runs, opt into `--profile balanced` (Sonnet on brief/research/execute/continue, Opus on plan + review) or `--profile economy` (Sonnet everywhere); for maximum quality, `--profile fable` (Fable 5 on every phase). Per-command cost is published in `${CLAUDE_PLUGIN_DATA}/trek*-stats.jsonl` if you want exact numbers. +The default `premium` profile runs **Opus on every phase** — the orchestrator (one per command), the exploration and review swarms (5–10 sub-agents per command, all `model: opus`-pinned in `agents/*.md`), and the executor (one per plan session). The model is **uniform per phase**: there is no "Opus orchestrates, Sonnet runs the swarms" split — a phase resolves to one model and both the orchestrator and its sub-agents use it. For cheaper runs, opt into `--profile balanced` (Sonnet on brief/research/execute/continue, Opus on plan + review) or `--profile economy` (Sonnet everywhere). Per-command cost is published in `${CLAUDE_PLUGIN_DATA}/trek*-stats.jsonl` if you want exact numbers. -The `opus` alias resolves to **Opus 4.8** (default reasoning effort `high`), `sonnet` to Sonnet 4.6, and `fable` to **Fable 5** (Mythos-class, above Opus; default reasoning effort `high` — xhigh requires a session-level setting, see [`docs/profiles.md`](docs/profiles.md)). Note two distinct effort axes that share the word "effort": brief `phase_signals.effort` (low/standard/high) tunes *orchestration shape* — how many agents and passes run — while native `effort:` on selected agents (retrieval at `medium`, adversarial-reasoning at `high`) tunes the *per-spawn reasoning budget*. See [`docs/profiles.md`](docs/profiles.md) § Model & effort axes. +The `opus` alias resolves to **Opus 4.8** (default reasoning effort `high`) and `sonnet` to Sonnet 4.6. Note two distinct effort axes that share the word "effort": brief `phase_signals.effort` (low/standard/high) tunes *orchestration shape* — how many agents and passes run — while native `effort:` on selected agents (retrieval at `medium`, adversarial-reasoning at `high`) tunes the *per-spawn reasoning budget*. See [`docs/profiles.md`](docs/profiles.md) § Model & effort axes. For per-profile cost estimates, see [`docs/profiles.md`](docs/profiles.md). diff --git a/agents/architecture-mapper.md b/agents/architecture-mapper.md index 9a5e6ad..448f7e1 100644 --- a/agents/architecture-mapper.md +++ b/agents/architecture-mapper.md @@ -3,6 +3,24 @@ name: architecture-mapper description: | Use this agent when you need deep architecture analysis of a codebase — structure, tech stack, patterns, anti-patterns, and key abstractions. + + + Context: Voyage exploration phase needs architecture overview + user: "/trekplan Add authentication to the API" + assistant: "Launching architecture-mapper to analyze codebase structure and patterns." + + Phase 5 of trekplan triggers this agent for every codebase size. + + + + + Context: User wants to understand an unfamiliar codebase + user: "Map out the architecture of this project" + assistant: "I'll use the architecture-mapper agent to analyze the codebase structure." + + Direct architecture analysis request triggers the agent. + + model: opus effort: medium color: cyan @@ -86,23 +104,3 @@ Structure your report with clear sections matching the 7 areas above. Include: - A brief "Architecture Summary" paragraph at the top (3-4 sentences) Do NOT include raw file listings — synthesize and organize the information. - -## When to use — examples - - -Context: Voyage exploration phase needs architecture overview -user: "/trekplan Add authentication to the API" -assistant: "Launching architecture-mapper to analyze codebase structure and patterns." - -Phase 5 of trekplan triggers this agent for every codebase size. - - - - -Context: User wants to understand an unfamiliar codebase -user: "Map out the architecture of this project" -assistant: "I'll use the architecture-mapper agent to analyze the codebase structure." - -Direct architecture analysis request triggers the agent. - - diff --git a/agents/brief-reviewer.md b/agents/brief-reviewer.md index e129fda..1eead8d 100644 --- a/agents/brief-reviewer.md +++ b/agents/brief-reviewer.md @@ -5,6 +5,24 @@ description: | checks completeness, consistency, testability, scope clarity, and research-plan validity. Catches problems early to avoid wasting tokens on exploration with a flawed brief. + + + Context: Voyage runs brief review before exploration + user: "/trekplan --project .claude/projects/2026-04-18-notifications" + assistant: "Reviewing brief quality before launching exploration agents." + + Orchestrator Phase 1b triggers this agent after the brief is available. + + + + + Context: User wants to validate a brief before planning + user: "Review this brief for completeness" + assistant: "I'll use the brief-reviewer agent to check brief quality." + + Brief review request triggers the agent. + + model: opus color: magenta tools: ["Read", "Glob", "Grep"] @@ -284,23 +302,3 @@ information that would strengthen the brief. List only if actionable.} files or technologies exist, but deep code analysis is not your job. - **Research-plan checks are load-bearing.** A brief with `research_status: pending` and missing research files is a scope hazard — flag it as a major risk. - -## When to use — examples - - -Context: Voyage runs brief review before exploration -user: "/trekplan --project .claude/projects/2026-04-18-notifications" -assistant: "Reviewing brief quality before launching exploration agents." - -Orchestrator Phase 1b triggers this agent after the brief is available. - - - - -Context: User wants to validate a brief before planning -user: "Review this brief for completeness" -assistant: "I'll use the brief-reviewer agent to check brief quality." - -Brief review request triggers the agent. - - diff --git a/agents/community-researcher.md b/agents/community-researcher.md index 89eb8b6..6317d86 100644 --- a/agents/community-researcher.md +++ b/agents/community-researcher.md @@ -4,6 +4,26 @@ description: | Use this agent when the research task requires practical, real-world experience rather than official documentation — community sentiment, production war stories, known gotchas, and what developers actually encounter when using a technology. + + + Context: trekresearch needs real-world experience data on a database migration + user: "/trekresearch What's the real-world experience with migrating from MongoDB to PostgreSQL?" + assistant: "Launching community-researcher to find migration stories, GitHub discussions, and community experience reports." + + Official docs won't cover migration regrets or production war stories. community-researcher + targets GitHub issues, blog posts, and discussions where real experience lives. + + + + + Context: trekresearch is building a technology comparison + user: "/trekresearch Research community sentiment around adopting SvelteKit vs Next.js" + assistant: "I'll use community-researcher to find discussions, blog posts, and community reports on both frameworks." + + Framework comparisons live in community discourse, not official docs. community-researcher + finds the practical signal that helps teams make adoption decisions. + + model: opus color: green tools: ["WebSearch", "WebFetch", "mcp__tavily__tavily_search", "mcp__tavily__tavily_research"] @@ -113,25 +133,3 @@ End with a summary table: Do not pick a side — report the split. - **Flag if a "problem" has since been fixed.** Check if the issue/complaint references a version that has since been patched or superseded. - -## When to use — examples - - -Context: trekresearch needs real-world experience data on a database migration -user: "/trekresearch What's the real-world experience with migrating from MongoDB to PostgreSQL?" -assistant: "Launching community-researcher to find migration stories, GitHub discussions, and community experience reports." - -Official docs won't cover migration regrets or production war stories. community-researcher -targets GitHub issues, blog posts, and discussions where real experience lives. - - - - -Context: trekresearch is building a technology comparison -user: "/trekresearch Research community sentiment around adopting SvelteKit vs Next.js" -assistant: "I'll use community-researcher to find discussions, blog posts, and community reports on both frameworks." - -Framework comparisons live in community discourse, not official docs. community-researcher -finds the practical signal that helps teams make adoption decisions. - - diff --git a/agents/contrarian-researcher.md b/agents/contrarian-researcher.md index a1027b1..5411ec2 100644 --- a/agents/contrarian-researcher.md +++ b/agents/contrarian-researcher.md @@ -4,6 +4,26 @@ description: | Use this agent when the research task has an emerging conclusion that needs adversarial stress-testing — find counter-evidence, overlooked alternatives, and reasons the leading answer might be wrong. + + + Context: trekresearch has found evidence favoring a technology and needs the other side + user: "/trekresearch We're leaning toward adopting Kafka for our event streaming needs" + assistant: "Launching contrarian-researcher to find the strongest arguments against Kafka and what alternatives might serve better." + + The research equivalent of plan-critic. When one option is emerging as the answer, + contrarian-researcher actively seeks disconfirming evidence to pressure-test the conclusion. + + + + + Context: trekresearch is comparing options and needs the downsides of the leading candidate + user: "/trekresearch Compare Redis vs Memcached — initial research favors Redis" + assistant: "I'll use contrarian-researcher to find the strongest case against Redis and scenarios where Memcached wins." + + Contrarian-researcher finds the downsides of the leading option — not to be negative, + but to ensure the final recommendation is genuinely considered. + + model: opus effort: high color: red @@ -132,25 +152,3 @@ Followed by a **Verdict** section: apply to a read-heavy workload. Assess relevance before reporting. - **Check recency.** A problem from 2019 that the project fixed in 2021 is not current counter-evidence. Flag whether issues are current or historical. - -## When to use — examples - - -Context: trekresearch has found evidence favoring a technology and needs the other side -user: "/trekresearch We're leaning toward adopting Kafka for our event streaming needs" -assistant: "Launching contrarian-researcher to find the strongest arguments against Kafka and what alternatives might serve better." - -The research equivalent of plan-critic. When one option is emerging as the answer, -contrarian-researcher actively seeks disconfirming evidence to pressure-test the conclusion. - - - - -Context: trekresearch is comparing options and needs the downsides of the leading candidate -user: "/trekresearch Compare Redis vs Memcached — initial research favors Redis" -assistant: "I'll use contrarian-researcher to find the strongest case against Redis and scenarios where Memcached wins." - -Contrarian-researcher finds the downsides of the leading option — not to be negative, -but to ensure the final recommendation is genuinely considered. - - diff --git a/agents/convention-scanner.md b/agents/convention-scanner.md index 3f6f868..686715f 100644 --- a/agents/convention-scanner.md +++ b/agents/convention-scanner.md @@ -5,6 +5,24 @@ description: | Produces a structured conventions report covering naming, directory layout, import style, error handling, test patterns, git commit style, and documentation patterns. Uses concrete examples from the codebase. + + + Context: Voyage exploration phase for a medium+ codebase + user: "/trekplan Add authentication to the API" + assistant: "Launching convention-scanner to discover coding patterns." + + Phase 5 of trekplan triggers this agent for medium+ codebases (50+ files). + + + + + Context: User wants to understand a project's conventions before contributing + user: "What are the coding conventions in this project?" + assistant: "I'll use the convention-scanner agent to analyze the codebase." + + Direct convention discovery request triggers the agent. + + model: opus color: yellow tools: ["Read", "Glob", "Grep", "Bash"] @@ -141,23 +159,3 @@ Based on existing conventions, new code should: than scanning everything. - **Stay focused.** This is about conventions — not architecture, dependencies, or risks. Those are handled by other agents. - -## When to use — examples - - -Context: Voyage exploration phase for a medium+ codebase -user: "/trekplan Add authentication to the API" -assistant: "Launching convention-scanner to discover coding patterns." - -Phase 5 of trekplan triggers this agent for medium+ codebases (50+ files). - - - - -Context: User wants to understand a project's conventions before contributing -user: "What are the coding conventions in this project?" -assistant: "I'll use the convention-scanner agent to analyze the codebase." - -Direct convention discovery request triggers the agent. - - diff --git a/agents/dependency-tracer.md b/agents/dependency-tracer.md index 25c9d57..ed0f90e 100644 --- a/agents/dependency-tracer.md +++ b/agents/dependency-tracer.md @@ -3,6 +3,24 @@ name: dependency-tracer description: | Use this agent when you need to trace import chains, map data flow, or understand how modules connect and what side effects they produce. + + + Context: Voyage needs to understand module relationships for a task + user: "/trekplan Refactor the payment processing pipeline" + assistant: "Launching dependency-tracer to map module connections and data flow." + + Phase 5 of trekplan triggers this agent to trace dependencies relevant to the task. + + + + + Context: User needs to understand impact of changing a module + user: "What would break if I change the User model?" + assistant: "I'll use the dependency-tracer agent to trace all dependents of the User model." + + Impact analysis request triggers the agent. + + model: opus effort: medium color: blue @@ -75,23 +93,3 @@ Structure as: 6. **Risk Flags** — circular deps, tight coupling, hidden side effects Include file paths and line numbers for every finding. - -## When to use — examples - - -Context: Voyage needs to understand module relationships for a task -user: "/trekplan Refactor the payment processing pipeline" -assistant: "Launching dependency-tracer to map module connections and data flow." - -Phase 5 of trekplan triggers this agent to trace dependencies relevant to the task. - - - - -Context: User needs to understand impact of changing a module -user: "What would break if I change the User model?" -assistant: "I'll use the dependency-tracer agent to trace all dependents of the User model." - -Impact analysis request triggers the agent. - - diff --git a/agents/docs-researcher.md b/agents/docs-researcher.md index 6a99790..364a3e8 100644 --- a/agents/docs-researcher.md +++ b/agents/docs-researcher.md @@ -3,6 +3,26 @@ name: docs-researcher description: | Use this agent when the research task requires authoritative information from official documentation, RFCs, vendor specifications, or Microsoft/Azure documentation. + + + Context: trekresearch needs to ground an OAuth2 implementation in official specs + user: "/trekresearch Research OAuth2 PKCE flow for our SPA" + assistant: "Launching docs-researcher to find the official RFC and vendor documentation for OAuth2 PKCE." + + docs-researcher targets authoritative sources — RFCs, specs, official vendor docs — + not community opinions. This is the right agent for protocol and standards questions. + + + + + Context: trekresearch encounters an Azure-specific technology + user: "/trekresearch How should we configure Azure Service Bus for our event pipeline?" + assistant: "I'll use docs-researcher with Microsoft Learn to get authoritative Azure Service Bus documentation." + + Microsoft/Azure technologies have dedicated MCP tools (microsoft_docs_search, + microsoft_docs_fetch) that docs-researcher uses for higher-quality results. + + model: opus color: blue tools: ["WebSearch", "WebFetch", "Read", "mcp__tavily__tavily_search", "mcp__tavily__tavily_research", "mcp__microsoft-learn__microsoft_docs_search", "mcp__microsoft-learn__microsoft_docs_fetch"] @@ -99,25 +119,3 @@ End with a summary table: - **Flag conflicts between official sources.** When vendor docs and the spec disagree, report both. - **Stay focused.** Research only what the research question asks. Do not explore tangentially. - **Official sources only.** If you cannot find an official source, say so — do not substitute a blog post. - -## When to use — examples - - -Context: trekresearch needs to ground an OAuth2 implementation in official specs -user: "/trekresearch Research OAuth2 PKCE flow for our SPA" -assistant: "Launching docs-researcher to find the official RFC and vendor documentation for OAuth2 PKCE." - -docs-researcher targets authoritative sources — RFCs, specs, official vendor docs — -not community opinions. This is the right agent for protocol and standards questions. - - - - -Context: trekresearch encounters an Azure-specific technology -user: "/trekresearch How should we configure Azure Service Bus for our event pipeline?" -assistant: "I'll use docs-researcher with Microsoft Learn to get authoritative Azure Service Bus documentation." - -Microsoft/Azure technologies have dedicated MCP tools (microsoft_docs_search, -microsoft_docs_fetch) that docs-researcher uses for higher-quality results. - - diff --git a/agents/gemini-bridge.md b/agents/gemini-bridge.md index 1a3c964..a15de55 100644 --- a/agents/gemini-bridge.md +++ b/agents/gemini-bridge.md @@ -5,6 +5,25 @@ description: | needed on a technology choice, architectural question, or complex research topic. Provides triangulation value by running a completely independent research path that can confirm or challenge findings from other agents. + + + Context: trekresearch launches gemini-bridge for an independent second opinion on a technology choice + user: "/trekplan Should we use Kafka or NATS for our event streaming layer?" + assistant: "Launching gemini-bridge for an independent second opinion on Kafka vs NATS." + + Technology choice with significant architectural implications triggers gemini-bridge + to provide an independent research path alongside local exploration agents. + + + + + Context: user wants deep research via Gemini on a complex architectural question + user: "Get me a Gemini deep research on event sourcing patterns for distributed systems" + assistant: "I'll use the gemini-bridge agent to run a deep research on event sourcing patterns." + + Direct request for Gemini research on a complex architectural question triggers the agent. + + model: opus color: magenta tools: ["mcp__gemini-mcp__gemini_deep_research", "mcp__gemini-mcp__gemini_get_research_status", "mcp__gemini-mcp__gemini_get_research_result", "mcp__gemini-mcp__gemini_research_followup"] @@ -128,24 +147,3 @@ and other external agents:* - **Graceful degradation at every step.** Unavailable tool, failed research, timeout — all are handled with a clear status message and immediate return. Never leave the pipeline hanging. - -## When to use — examples - - -Context: trekresearch launches gemini-bridge for an independent second opinion on a technology choice -user: "/trekplan Should we use Kafka or NATS for our event streaming layer?" -assistant: "Launching gemini-bridge for an independent second opinion on Kafka vs NATS." - -Technology choice with significant architectural implications triggers gemini-bridge -to provide an independent research path alongside local exploration agents. - - - - -Context: user wants deep research via Gemini on a complex architectural question -user: "Get me a Gemini deep research on event sourcing patterns for distributed systems" -assistant: "I'll use the gemini-bridge agent to run a deep research on event sourcing patterns." - -Direct request for Gemini research on a complex architectural question triggers the agent. - - diff --git a/agents/git-historian.md b/agents/git-historian.md index 2c90a51..a28230e 100644 --- a/agents/git-historian.md +++ b/agents/git-historian.md @@ -3,6 +3,24 @@ name: git-historian description: | Use this agent to analyze git history for planning context — recent changes, code ownership, hot files, and active branches relevant to the task. + + + Context: Voyage exploration phase needs git context + user: "/trekplan Refactor the database layer" + assistant: "Launching git-historian to check recent changes and ownership of DB code." + + Phase 2 of trekplan triggers this agent for every codebase size. + + + + + Context: User wants to understand change history before modifying code + user: "Who has been changing the auth module recently?" + assistant: "I'll use the git-historian agent to analyze ownership and change patterns." + + Git history analysis request triggers the agent. + + model: opus effort: medium color: yellow @@ -104,23 +122,3 @@ Run `git status --short` to check for: are risks the planner needs to know about. - **Use relative time.** "2 days ago" is more useful than a raw timestamp. - **Never expose email addresses.** Use author names only. - -## When to use — examples - - -Context: Voyage exploration phase needs git context -user: "/trekplan Refactor the database layer" -assistant: "Launching git-historian to check recent changes and ownership of DB code." - -Phase 2 of trekplan triggers this agent for every codebase size. - - - - -Context: User wants to understand change history before modifying code -user: "Who has been changing the auth module recently?" -assistant: "I'll use the git-historian agent to analyze ownership and change patterns." - -Git history analysis request triggers the agent. - - diff --git a/agents/plan-critic.md b/agents/plan-critic.md index b2aa6ed..5c08407 100644 --- a/agents/plan-critic.md +++ b/agents/plan-critic.md @@ -3,6 +3,24 @@ name: plan-critic description: | Use this agent when an implementation plan needs adversarial review — it finds problems, never praises. + + + Context: Voyage adversarial review phase + user: "/trekplan Implement WebSocket real-time updates" + assistant: "Launching plan-critic to stress-test the implementation plan." + + Phase 9 of trekplan triggers this agent to review the generated plan. + + + + + Context: User wants a plan reviewed before execution + user: "Review this plan and find problems" + assistant: "I'll use the plan-critic agent to perform adversarial review." + + Plan review request triggers the agent. + + model: opus effort: high color: red @@ -279,23 +297,3 @@ short, stable id for the finding class (used for exact-match dedup). Emit Be specific. Reference exact plan sections, step numbers, and file paths. Never use "generally" or "usually" — cite the specific problem in this specific plan. - -## When to use — examples - - -Context: Voyage adversarial review phase -user: "/trekplan Implement WebSocket real-time updates" -assistant: "Launching plan-critic to stress-test the implementation plan." - -Phase 9 of trekplan triggers this agent to review the generated plan. - - - - -Context: User wants a plan reviewed before execution -user: "Review this plan and find problems" -assistant: "I'll use the plan-critic agent to perform adversarial review." - -Plan review request triggers the agent. - - diff --git a/agents/research-scout.md b/agents/research-scout.md index 9f3e8e8..09efc9a 100644 --- a/agents/research-scout.md +++ b/agents/research-scout.md @@ -3,6 +3,24 @@ name: research-scout description: | Use this agent when the implementation task involves unfamiliar technologies, external APIs, or libraries where official documentation and known issues should be checked. + + + Context: Voyage detects external technology in the task + user: "/trekplan Integrate Stripe payment processing" + assistant: "Launching research-scout to find Stripe documentation and best practices." + + Phase 5 of trekplan conditionally triggers this agent when external tech is detected. + + + + + Context: User needs research before implementation + user: "Research the best approach for WebSocket scaling" + assistant: "I'll use the research-scout agent to find documentation and best practices." + + Research request for external technology triggers the agent. + + model: opus color: blue tools: ["WebSearch", "WebFetch", "Read"] @@ -100,23 +118,3 @@ End with a summary table: - **Date everything.** Documentation ages — the reader needs to judge freshness. - **Flag conflicts.** If official docs and community advice disagree, report both. - **Stay focused.** Research only what the task needs. Do not explore tangentially. - -## When to use — examples - - -Context: Voyage detects external technology in the task -user: "/trekplan Integrate Stripe payment processing" -assistant: "Launching research-scout to find Stripe documentation and best practices." - -Phase 5 of trekplan conditionally triggers this agent when external tech is detected. - - - - -Context: User needs research before implementation -user: "Research the best approach for WebSocket scaling" -assistant: "I'll use the research-scout agent to find documentation and best practices." - -Research request for external technology triggers the agent. - - diff --git a/agents/risk-assessor.md b/agents/risk-assessor.md index 7fd14a2..16a2531 100644 --- a/agents/risk-assessor.md +++ b/agents/risk-assessor.md @@ -3,6 +3,24 @@ name: risk-assessor description: | Use this agent when you need to identify risks, edge cases, failure modes, and technical debt that could affect an implementation task. + + + Context: Voyage exploration phase identifies potential risks + user: "/trekplan Migrate database from PostgreSQL to MongoDB" + assistant: "Launching risk-assessor to identify failure modes and edge cases for this migration." + + Phase 5 of trekplan triggers this agent to find risks before planning begins. + + + + + Context: User wants to understand risks before a change + user: "What could go wrong with this refactor?" + assistant: "I'll use the risk-assessor agent to map risks and failure modes." + + Risk analysis request triggers the agent. + + model: opus effort: high color: yellow @@ -88,23 +106,3 @@ Produce a prioritized risk list: **Low** = minor concerns worth noting Follow with a narrative section expanding on each Critical and High risk. - -## When to use — examples - - -Context: Voyage exploration phase identifies potential risks -user: "/trekplan Migrate database from PostgreSQL to MongoDB" -assistant: "Launching risk-assessor to identify failure modes and edge cases for this migration." - -Phase 5 of trekplan triggers this agent to find risks before planning begins. - - - - -Context: User wants to understand risks before a change -user: "What could go wrong with this refactor?" -assistant: "I'll use the risk-assessor agent to map risks and failure modes." - -Risk analysis request triggers the agent. - - diff --git a/agents/scope-guardian.md b/agents/scope-guardian.md index c36fd3a..bd3f425 100644 --- a/agents/scope-guardian.md +++ b/agents/scope-guardian.md @@ -3,6 +3,24 @@ name: scope-guardian description: | Use this agent when you need to verify that an implementation plan matches its requirements — catches scope creep and scope gaps. + + + Context: Voyage adversarial review phase checks scope alignment + user: "/trekplan Add caching to the API layer" + assistant: "Launching scope-guardian to verify plan matches requirements." + + Phase 9 of trekplan triggers this agent alongside plan-critic. + + + + + Context: User wants to verify plan doesn't do too much or too little + user: "Does this plan match what I asked for?" + assistant: "I'll use the scope-guardian agent to check scope alignment." + + Scope verification request triggers the agent. + + model: opus color: magenta tools: ["Read", "Glob", "Grep"] @@ -126,23 +144,3 @@ One object per scope-creep / gap / dependency finding. `file`/`line` point at th plan step (or the brief requirement) the finding concerns; `rule_key` is a short, stable id for the finding class (used for exact-match dedup against plan-critic). Emit `"findings": []` when the plan is fully aligned. - -## When to use — examples - - -Context: Voyage adversarial review phase checks scope alignment -user: "/trekplan Add caching to the API layer" -assistant: "Launching scope-guardian to verify plan matches requirements." - -Phase 9 of trekplan triggers this agent alongside plan-critic. - - - - -Context: User wants to verify plan doesn't do too much or too little -user: "Does this plan match what I asked for?" -assistant: "I'll use the scope-guardian agent to check scope alignment." - -Scope verification request triggers the agent. - - diff --git a/agents/security-researcher.md b/agents/security-researcher.md index a4516ca..d960c0d 100644 --- a/agents/security-researcher.md +++ b/agents/security-researcher.md @@ -3,6 +3,26 @@ name: security-researcher description: | Use this agent when the research task requires security investigation of a technology, dependency, or library — CVEs, audit history, supply chain risks, and OWASP relevance. + + + Context: trekresearch is evaluating whether a dependency is safe to adopt + user: "/trekresearch Research whether we should trust the `node-fetch` library" + assistant: "Launching security-researcher to check CVE history, supply chain risk, and audit reports for node-fetch." + + Before adopting a dependency, security-researcher checks the attack surface: known + vulnerabilities, maintainer health, and whether past issues were handled responsibly. + + + + + Context: trekresearch is assessing the security posture of a technology choice + user: "/trekresearch Evaluate the security implications of using JWT for session management" + assistant: "I'll use security-researcher to check known JWT vulnerabilities, OWASP guidance, and community security reports." + + Technology choices have security tradeoffs. security-researcher maps the threat surface + using CVE databases, OWASP categories, and verified audit reports. + + model: opus color: red tools: ["WebSearch", "WebFetch", "mcp__tavily__tavily_search", "mcp__tavily__tavily_research"] @@ -120,25 +140,3 @@ End with an overall security summary table: risks from incomplete information. - **Severity matters.** A CVSS 9.8 is not equivalent to a CVSS 3.2 — report scores and distinguish between critical and low-severity findings. - -## When to use — examples - - -Context: trekresearch is evaluating whether a dependency is safe to adopt -user: "/trekresearch Research whether we should trust the `node-fetch` library" -assistant: "Launching security-researcher to check CVE history, supply chain risk, and audit reports for node-fetch." - -Before adopting a dependency, security-researcher checks the attack surface: known -vulnerabilities, maintainer health, and whether past issues were handled responsibly. - - - - -Context: trekresearch is assessing the security posture of a technology choice -user: "/trekresearch Evaluate the security implications of using JWT for session management" -assistant: "I'll use security-researcher to check known JWT vulnerabilities, OWASP guidance, and community security reports." - -Technology choices have security tradeoffs. security-researcher maps the threat surface -using CVE databases, OWASP categories, and verified audit reports. - - diff --git a/agents/session-decomposer.md b/agents/session-decomposer.md index 96526ab..fb82457 100644 --- a/agents/session-decomposer.md +++ b/agents/session-decomposer.md @@ -4,6 +4,24 @@ description: | Use this agent to decompose an trekplan into self-contained headless sessions. Reads a plan file, analyzes step dependencies, groups steps into sessions, identifies parallelism, and generates session specs + dependency graph + launch script. + + + Context: User wants to run a plan across multiple headless sessions + user: "/trekplan --decompose .claude/plans/trekplan-2026-04-06-auth-refactor.md" + assistant: "Launching session-decomposer to split the plan into headless sessions." + + The --decompose flag triggers this agent to analyze and split the plan. + + + + + Context: User has a large plan and wants parallel execution + user: "Split this plan into sessions I can run in parallel" + assistant: "I'll use the session-decomposer to identify parallel session groups." + + Plan decomposition request for parallel headless execution. + + model: opus color: green tools: ["Read", "Glob", "Grep", "Write"] @@ -292,23 +310,3 @@ After all sessions complete, run: wrong sequentiality only costs time. - **Verify file existence.** Use Glob to confirm that files referenced in the plan actually exist before assigning them to sessions. - -## When to use — examples - - -Context: User wants to run a plan across multiple headless sessions -user: "/trekplan --decompose .claude/plans/trekplan-2026-04-06-auth-refactor.md" -assistant: "Launching session-decomposer to split the plan into headless sessions." - -The --decompose flag triggers this agent to analyze and split the plan. - - - - -Context: User has a large plan and wants parallel execution -user: "Split this plan into sessions I can run in parallel" -assistant: "I'll use the session-decomposer to identify parallel session groups." - -Plan decomposition request for parallel headless execution. - - diff --git a/agents/task-finder.md b/agents/task-finder.md index fee90ea..81ef3a3 100644 --- a/agents/task-finder.md +++ b/agents/task-finder.md @@ -4,6 +4,24 @@ description: | Use this agent to find all files, functions, types, and interfaces directly related to the planning task. Replaces generic Explore agents with targeted, structured code discovery. + + + Context: Voyage exploration phase needs task-relevant code + user: "/trekplan Add authentication to the API" + assistant: "Launching task-finder to locate auth-related code, endpoints, and models." + + Phase 2 of trekplan triggers this agent for every codebase size. + + + + + Context: User wants to find code related to a specific feature + user: "Find all code related to payment processing" + assistant: "I'll use the task-finder agent to locate payment-related code." + + Direct code discovery request triggers the agent. + + model: opus effort: medium color: green @@ -128,23 +146,3 @@ Structure your report using three tiers: - **Stay focused on the task.** Do not inventory the entire codebase — only what is relevant to implementing the specific task. - **Never read file contents that look like secrets or credentials.** - -## When to use — examples - - -Context: Voyage exploration phase needs task-relevant code -user: "/trekplan Add authentication to the API" -assistant: "Launching task-finder to locate auth-related code, endpoints, and models." - -Phase 2 of trekplan triggers this agent for every codebase size. - - - - -Context: User wants to find code related to a specific feature -user: "Find all code related to payment processing" -assistant: "I'll use the task-finder agent to locate payment-related code." - -Direct code discovery request triggers the agent. - - diff --git a/agents/test-strategist.md b/agents/test-strategist.md index 756b7f1..b95e0cb 100644 --- a/agents/test-strategist.md +++ b/agents/test-strategist.md @@ -3,6 +3,24 @@ name: test-strategist description: | Use this agent when you need to design a test strategy for an implementation task — discovers existing patterns, maps coverage gaps, and recommends what tests to write. + + + Context: Voyage exploration phase for medium+ codebase + user: "/trekplan Add rate limiting to the API" + assistant: "Launching test-strategist to analyze existing test patterns and design test coverage." + + Phase 5 of trekplan triggers this agent for medium and large codebases. + + + + + Context: User wants to know how to test a feature + user: "What tests should I write for this new feature?" + assistant: "I'll use the test-strategist agent to analyze existing patterns and recommend tests." + + Test planning request triggers the agent. + + model: opus color: green tools: ["Read", "Glob", "Grep", "Bash"] @@ -77,23 +95,3 @@ For each test, provide: 5. **Test Dependencies** — fixtures, mocks, or setup code to create first Do NOT write test code. Describe what each test should verify and which patterns to follow. - -## When to use — examples - - -Context: Voyage exploration phase for medium+ codebase -user: "/trekplan Add rate limiting to the API" -assistant: "Launching test-strategist to analyze existing test patterns and design test coverage." - -Phase 5 of trekplan triggers this agent for medium and large codebases. - - - - -Context: User wants to know how to test a feature -user: "What tests should I write for this new feature?" -assistant: "I'll use the test-strategist agent to analyze existing patterns and recommend tests." - -Test planning request triggers the agent. - - diff --git a/commands/trekbrief.md b/commands/trekbrief.md index acbb9c4..c9f02d8 100644 --- a/commands/trekbrief.md +++ b/commands/trekbrief.md @@ -2,6 +2,7 @@ name: trekbrief description: Interactive interview that produces a task brief with explicit research plan. Feeds /trekresearch and /trekplan. Optionally orchestrates the full pipeline end-to-end. argument-hint: "[--quick] " +model: opus allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion --- @@ -366,14 +367,13 @@ in the question body so the operator sees why it was picked. ### The loop — 4 tier-coupled AskUserQuestion calls Loop over `[research, plan, execute, review]` in order. For each phase, -issue one `AskUserQuestion` with 4 options: +issue one `AskUserQuestion` with 3 options: | Option | Maps to phase_signals entry | |--------|----------------------------| | **Low effort** | `{phase: , effort: low, model: sonnet}` | | **Standard (default)** | `{phase: , effort: standard}` *(model omitted — composition falls through to profile)* | | **High effort** | `{phase: , effort: high, model: opus}` | -| **Fable (max quality)** | `{phase: , effort: high, model: fable}` | The proposed tier per phase (from the default-derivation heuristic) MUST be labelled `(default)` in the option list so the operator can one-click @@ -384,15 +384,6 @@ The mapping table is canonical: - `low → {effort: low, model: sonnet}` (force sonnet for the low-cost path) - `standard → {effort: standard}` (model omitted; composition rule resolves via profile) - `high → {effort: high, model: opus}` (force opus for the high-confidence path) -- `fable → {effort: high, model: fable}` (force Fable 5 for the max-quality path) - -The fable tier reuses `effort: high` semantics — full swarm, contrarian + -gemini always-on; `EFFORT_LEVELS` is unchanged (Voyage effort is orchestration -shape, not model reasoning effort). Model reasoning effort is inherited from -the session: Fable 5's default effort is `high`, NOT xhigh. To run xhigh, the -operator sets it at session level via `/effort xhigh`, the `effortLevel` -setting, or `CLAUDE_CODE_EFFORT_LEVEL` — switching model resets effort to the -model default, so it does not follow the model. ### Force-stop handling @@ -900,7 +891,7 @@ Never let stats failures block the workflow. ## Profile (v4.1) Accepts `--profile ` where `` is one of `economy`, `balanced`, -`premium`, `fable`, or a custom profile under `voyage-profiles/`. Default: `premium`. +`premium`, or a custom profile under `voyage-profiles/`. Default: `premium`. Resolution order (per `lib/profiles/resolver.mjs`): 1. `--profile` flag (source: `flag`) diff --git a/commands/trekcontinue.md b/commands/trekcontinue.md index 7267fd9..f71f947 100644 --- a/commands/trekcontinue.md +++ b/commands/trekcontinue.md @@ -2,6 +2,7 @@ name: trekcontinue description: Resume the next session in a multi-session trekplan project. Reads .session-state.local.json and immediately begins the next session. argument-hint: "[ | --help]" +model: opus --- # Ultracontinue Local v1.0 diff --git a/commands/trekendsession.md b/commands/trekendsession.md index f395b35..122fbb8 100644 --- a/commands/trekendsession.md +++ b/commands/trekendsession.md @@ -2,6 +2,7 @@ name: trekendsession description: Mark the current session as complete and write session-state pointing at the next session. Helper for informal multi-session flows. argument-hint: " | --help" +model: opus --- # Voyage End-Session Local v1.0 @@ -90,16 +91,16 @@ want an interactive flow, use `/trekcontinue --help` to see the full pipeline. ## Phase 3 — Atomically write `.session-state.local.json` + sibling NEXT-SESSION-PROMPT.local.md -Write `{project_dir}/.session-state.local.json` with the schema-v1 object: +Write `/.session-state.local.json` with the schema-v1 object: ```json { "schema_version": 1, - "project": "{project_dir}", - "next_session_brief_path": "{arg 1}", - "next_session_label": "{arg 2}", + "project": "", + "next_session_brief_path": "", + "next_session_label": "", "status": "in_progress", - "updated_at": "{now, ISO-8601}" + "updated_at": "" } ``` @@ -114,22 +115,14 @@ Under `node --input-type=module -e "