diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 29fe990..48ff166 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,12 +1,23 @@ { "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.6.0", + "version": "5.9.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 822742e..b92beb2 100644 --- a/.gitignore +++ b/.gitignore @@ -19,8 +19,10 @@ blob-report/ # Local configuration / session files *.local.* -# STATE.md — current state-of-play. TRACKED continuity per ~/.claude/CLAUDE.md -# (overrides the polyrepo gitignore convention); pushed to private Forgejo, never public. +# 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 # Local planning docs (briefs, design notes, observations) — never committed. # Existing tracked files in docs/ predate this rule; new planning docs stay local. @@ -30,7 +32,7 @@ docs/ultracontinue-design-notes.md # Ultraplan project directories — briefs, research, plans, progress all local. .claude/projects/ -# --- session/local state (gitignored) — STATE.md er nå tracked, se ~/.claude/CLAUDE.md --- +# --- session/local state (gitignored) — STATE.md is LOCAL-ONLY (open/ = public), se ~/.claude/CLAUDE.md --- REMEMBER.md ROADMAP.md TODO.md diff --git a/CHANGELOG.md b/CHANGELOG.md index ab89630..21b08e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,117 @@ 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. + +### Reference/dormant agents now carry one-line descriptions + +- **The 3 `*-orchestrator` reference docs** (`planning-/research-/review-orchestrator`) and the **dormant `synthesis-agent`** carried multi-paragraph `description:` frontmatter (full rationale + CC-2.1.172 history + a usage example) that Claude Code injects into every session — despite none of them being spawnable from the live `/trek*` pipeline. Their `description:` is now a single line; the full rationale already lives, and remains, in each file's body. **~700 tokens trimmed** from the always-loaded agent listing, no capability change. +- The three orchestrators retain the self-declaration **"reference document, not a spawnable capability"** (pinned by `doc-consistency.test.mjs`); `synthesis-agent` retains its **DORMANT / not-wired** flag and the `docs/T1-synthesis-poc-results.md` pointer. +- Surfaced via dogfooding with `config-audit`'s always-loaded token audit. Canonical `node --test`: **754 pass, 0 fail** (756 total, 2 skipped); the agent-inventory + frontmatter pins stay green. + +### Version sync + +- `plugin.json`, `package.json`, `package-lock.json`, the README badge, and the CHANGELOG top entry all at `5.6.1`, guarded by the version-consistency test in `tests/lib/doc-consistency.test.mjs`. + ## v5.6.0 — 2026-06-20 — `/trekexecute` loop hardening: machine-verifiable completion + bounded recovery Additive — no breaking change. Hardens the `/trekexecute` execution loop so termination is *machine-verifiable* and recovery is *bounded by an explicit budget*, closing the "runs forever" and "declares done without proof" failure modes. Five focused changes; canonical `node --test` 744 → **756** (0 fail). diff --git a/CLAUDE.md b/CLAUDE.md index 9c1c22e..ffac6fb 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 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.) +**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`). -> **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. +> **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). -> **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). +> **Trinity context (informational).** Voyage is Tier 1 (per-task) of a three-tier architecture. **Asymmetry is a hard invariant:** Voyage stays unaware of Tier 2/3; Handover 1 (brief format) is the only integration point, no producer is privileged, and brief-schema changes are breaking for downstream consumers (formalized as a public contract in v5.5.0). Tier 2/3 producer detail + the public contract → `docs/HANDOVER-CONTRACTS.md` §Handover 1 (PUBLIC CONTRACT). -> **Cross-cutting invariant: brief framing must match operator intent (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. +> **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). ## 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 | +| `/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 | | `/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 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). +> **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. -> **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. +> **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. ## Reference docs (read on demand) - **Architecture, workflows, project-directory contract, state, terminology:** `docs/architecture.md` - **Quality infrastructure (`lib/` validators, parsers, autonomy primitives, hooks):** `docs/architecture.md` §Quality infrastructure - **Autonomy gates (`--gates`), Path A/B/C decision:** `docs/operations.md` -- **Profile system (`--profile economy/balanced/premium`), lookup order, custom profiles:** `docs/operations.md` +- **Profile system (`--profile economy/balanced/premium/fable`), lookup order, custom profiles:** `docs/operations.md` - **Observability (Stop hook, OTLP/textfile export, SSRF mitigation):** `docs/operations.md` - **Handover contracts (the 7 pipeline handovers):** `docs/HANDOVER-CONTRACTS.md` diff --git a/README.md b/README.md index 6ba7e19..1cb5546 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.6.0-blue) +![Version](https://img.shields.io/badge/version-5.9.1-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![Platform](https://img.shields.io/badge/platform-Claude%20Code-purple) @@ -10,26 +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 in v5.6.0 — `/trekexecute` loop hardening** — execution-loop termination is now **machine-verifiable** and recovery is **bounded by an explicit budget**: -> - **Machine-verifiable completion gate** — a session reports `completed` only when the Phase 7.5 manifest audit PASSes, the stop signal exits 0, and the success criteria are green (**Hard Rule 18**, promoted from prose to an enforced stop-signal contract anchored in the audit, not the model's self-assessment). -> - **Bounded recovery** — a global `TREKEXECUTE_MAX_RECOVERY_ITERATIONS` budget (default **25**, env-overridable) sits atop the per-step caps as a three-axis cap hierarchy (**Hard Rule 20**), with an `iterations_remaining` signal in the progress + summary JSON and a deterministic cross-check that catches a never-decremented counter. -> Additive — no breaking change. Full detail in [CHANGELOG.md](CHANGELOG.md). -> -> **What's new in v5.5.0 — brief framing enforcement (`brief_version 2.2`) + narrow wins** — `/trekbrief` now opens with a **framing declaration** (Phase 2.5): every brief records `framing: preserve | refine | replace | new-direction` *before* any prose is written, so the plan can't quietly polish a wrong premise. Three version-gated layers ship at `brief_version ≥ 2.2`: -> - **Framing field** — a required `framing` enum in frontmatter; enum-checked on any version, and a missing value at `≥ 2.2` is a blocker. Collected in Phase 2.5 before prose, non-skippable even in `--quick`. -> - **Memory alignment** — a new `brief-reviewer` dimension compares the brief's Intent/Goal + framing against operator memory and flags *explicit* contradictions (a no-op that scores N/A when no memory is supplied). -> - **Obligatory `## TL;DR`** — a ≤ 5-line, framing-anchored summary at the top of every brief, so a wrong premise is caught at a glance. -> Existing `2.0`/`2.1` briefs stay valid (forward + backward compatible), mirroring the `phase_signals ≥ 2.1` gate. This is a **schema-axis** change — the plugin version badge bumped to **v5.5.0** at this coordinated release; see [docs/HANDOVER-CONTRACTS.md](docs/HANDOVER-CONTRACTS.md) §Handover 1 for the contract evolution. -> **Also in v5.5.0:** a reviewer-output **schema contract** for `/trekreview` (validates each reviewer's JSON, re-asks on schema failure); an opt-in **`--workflow`** path for `/trekreview` Phase 5–6 (bake-off POSITIVE; default stays prose to preserve the 2.1.154+ portability floor); **Opus 4.8** baseline with native `effort:` on 8 agents; exec-form hooks + enforced `disallowed-tools` on `/trekexecute`. Full arc in [CHANGELOG.md](CHANGELOG.md). -> -> **What's new in v5.1.1** — Remediation patch closing 11 of 12 findings from the v5.1.0 review (SC8 dogfood gate scheduled for sesjon 8). Lukker: -> - **Bug fixes (load-bearing):** YAML-number bypass in `brief-validator` (#8) + doc-consistency pin lock-in (#11) so the gate fires for both quoted and unquoted `brief_version`. -> - **Wiring:** `phase-signal-resolver` helper wired into all 4 downstream commands (#9) with TDD pair `resolvePhaseModel` + profile-resolver non-interference test (#4 SC5); `brief-validator` gate required uniformly in `/trekresearch` + `/trekexecute` (#12). -> - **Test refactor:** runtime SC1 walk for trekbrief (#1) + per-tier resolver-output + missing-signals falsification for `/trekplan`/`/trekresearch`/`/trekreview`/`/trekexecute` (#2 #3 #6 #10) + dedicated SC5 test (#7). -> - **Documentation:** Dogfood-gate scheduling in REMEMBER (#5, sesjon 8 manual) + Decision B high-effort behavior per command + brief Non-Goal/SC1 amendments + coordinator high-effort normalization. -> v5.1.1 is additive — no breaking changes against v5.1.0. -> -> **What v5.1 introduced** — `/trekbrief` Phase 3.5 commits per-phase `phase_signals` (effort + optional model for `research`/`plan`/`execute`/`review`) to `brief.md` frontmatter. `brief_version: 2.1` activates a validator-side sequencing gate (`BRIEF_V51_MISSING_SIGNALS`) so downstream commands halt with a friendly hint when signals are missing. Composition rule per downstream command: brief signal wins per-phase, profile fills gaps. `effort == low` activates the existing `--quick`-equivalent code-path in each command (`/trekexecute` low-effort = `--gates open` + sequential). Additive — no breaking changes; pre-2.1 briefs still validate. +> **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).** | Command | What it does | |---------|-------------| @@ -170,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` / ``. See [Profile system](#profile-system-v410) below. | +| **Profile** | `/trekbrief --profile ` | (v4.1.0) Pin model profile for the brief phase: `economy` / `balanced` / `premium` / `fable` / ``. See [Profile system](#profile-system-v410) below. | `/trekbrief` is **always interactive**. There is no foreground/background mode — the interview requires user input. @@ -214,6 +195,7 @@ 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`. @@ -604,24 +586,65 @@ Claude never pre-generates suggestions in this flow. ## The full pipeline +Six commands, one pipeline — each step hands a structured artifact to the next (the seven [handover contracts](docs/HANDOVER-CONTRACTS.md)): + +```mermaid +flowchart LR + B["/trekbrief"] + R["/trekresearch"] + P["/trekplan"] + X["/trekexecute"] + V["/trekreview"] + C["/trekcontinue"] + A["architect plugin
(opt-in, not bundled)"] + + B -->|"H1 · brief.md · PUBLIC"| R + R -->|"H2 · research/NN-*.md"| P + A -.->|"H3 · architecture/overview.md"| P + P -->|"H4 · plan.md"| X + X -.->|"H5 · progress.json (--resume)"| X + X -->|"H7 · .session-state.local.json"| C + C -->|"next session"| X + X -.->|"git diff"| V + V -->|"H6 · review.md (loop back)"| P ``` - /trekbrief /trekresearch /trekplan /trekexecute - ┌──────────────┐ ┌───────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ - │ Interview │ │ 5 local agents │ │ brief-reviewer │ │ Parse plan │ - │ ↓ │ │ 4 external agents │ │ ↓ │ │ ↓ │ - │ Intent/Goal │ │ + Gemini bridge │ │ 6-8 exploration │ │ Detect sessions │ - │ ↓ │ │ ↓ │ │ agents (parallel) │ │ ↓ │ - │ Research │ │ Triangulation │ │ ↓ │ │ Execute steps │ - │ topics │ │ ↓ │ │ Opus planning │ │ (verify + manifest │ - │ ↓ │ → brief → → → → → → → → → → → ↓ │→ │ + checkpoint) │ - │ brief.md │ │ research/*.md │ │ plan-critic + │ │ ↓ │ - └──────────────┘ └───────────────────┘ │ scope-guardian │ │ Phase 7.5 manifest │ - │ ↓ │ │ audit + 7.6 recovery│ - │ plan.md │ │ ↓ │ - └─────────────────────┘ │ progress.json + done│ - └─────────────────────┘ + +Solid arrows are the forward pipeline; dashed are conditional/internal edges (`--resume`, the git-diff that feeds review, the opt-in architect input). **H1 (`brief.md`) is the only PUBLIC contract** — the single integration point for any upstream brief producer. + +### Agents per phase + +Every command orchestrates its agents inline from the main context (all sub-agents are `model: opus`-pinned). `/trekexecute` is the exception — it spawns **no** sub-agents. + +```mermaid +flowchart TB + subgraph BR["/trekbrief"] + BRG["brief-reviewer (gate · ≤3 iter)"] + end + subgraph RES["/trekresearch · Phase 4 — parallel"] + RL["LOCAL: architecture-mapper · dependency-tracer
task-finder · git-historian · convention-scanner*"] + RE["EXTERNAL: docs-researcher · community-researcher
security-researcher* · contrarian-researcher* · gemini-bridge*"] + end + subgraph PL["/trekplan"] + PLG["Phase 4b · brief-reviewer (gate)"] + PLS["Phase 5 — parallel (6 + 2*): architecture-mapper · dependency-tracer
risk-assessor · task-finder · test-strategist · git-historian
convention-scanner* · research-scout*"] + PLC["Phase 9 — parallel · plan-critic · scope-guardian"] + PLG --> PLS --> PLC + end + subgraph EX["/trekexecute · no sub-agents"] + EXI["inline step-loop + claude -p worktrees
+ Phase 7.5/7.6 manifest audit (deterministic)"] + end + subgraph RV["/trekreview"] + RVR["Phase 5 — parallel · code-correctness-reviewer · brief-conformance-reviewer*"] + RVJ["Phase 6 · review-coordinator (Judge)"] + RVR --> RVJ + end + BR --> RES --> PL --> EX --> RV ``` +`* = conditional`: convention-scanner / test-strategist on medium+ codebases (50+ files); research-scout for unknown external tech; security-/contrarian-researcher + gemini-bridge when a leading recommendation forms (or always at `effort=high`); brief-conformance-reviewer skipped under `--quick`. + +> **Which Claude Code primitive each phase uses — and the alternatives considered (Workflow substrate, delegated orchestrator, dormant synthesis-agent)** → see [docs/architecture.md §Primitives per step](docs/architecture.md#primitives-per-step-decision-matrix). + All artifacts live under `.claude/projects/{YYYY-MM-DD}-{slug}/`. An opt-in upstream architect plugin (not bundled) can insert a Claude-Code-specific architecture-matching step between research and plan — `/trekplan` auto-discovers its `architecture/overview.md` output as priors when present. @@ -756,13 +779,14 @@ An optional architect step between research and plan was previously available vi ## Profile system (v4.1.0) -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. +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. | 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: @@ -787,9 +811,9 @@ Default JSONL stats stream (`${CLAUDE_PLUGIN_DATA}/trek*-stats.jsonl`) is unchan ## Cost profile -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 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 `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. +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. 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 448f7e1..9a5e6ad 100644 --- a/agents/architecture-mapper.md +++ b/agents/architecture-mapper.md @@ -3,24 +3,6 @@ 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 @@ -104,3 +86,23 @@ 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 1eead8d..e129fda 100644 --- a/agents/brief-reviewer.md +++ b/agents/brief-reviewer.md @@ -5,24 +5,6 @@ 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"] @@ -302,3 +284,23 @@ 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 6317d86..89eb8b6 100644 --- a/agents/community-researcher.md +++ b/agents/community-researcher.md @@ -4,26 +4,6 @@ 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"] @@ -133,3 +113,25 @@ 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 5411ec2..a1027b1 100644 --- a/agents/contrarian-researcher.md +++ b/agents/contrarian-researcher.md @@ -4,26 +4,6 @@ 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 @@ -152,3 +132,25 @@ 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 686715f..3f6f868 100644 --- a/agents/convention-scanner.md +++ b/agents/convention-scanner.md @@ -5,24 +5,6 @@ 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"] @@ -159,3 +141,23 @@ 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 ed0f90e..25c9d57 100644 --- a/agents/dependency-tracer.md +++ b/agents/dependency-tracer.md @@ -3,24 +3,6 @@ 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 @@ -93,3 +75,23 @@ 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 364a3e8..6a99790 100644 --- a/agents/docs-researcher.md +++ b/agents/docs-researcher.md @@ -3,26 +3,6 @@ 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"] @@ -119,3 +99,25 @@ 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 a15de55..1a3c964 100644 --- a/agents/gemini-bridge.md +++ b/agents/gemini-bridge.md @@ -5,25 +5,6 @@ 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"] @@ -147,3 +128,24 @@ 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 a28230e..2c90a51 100644 --- a/agents/git-historian.md +++ b/agents/git-historian.md @@ -3,24 +3,6 @@ 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 @@ -122,3 +104,23 @@ 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 5c08407..b2aa6ed 100644 --- a/agents/plan-critic.md +++ b/agents/plan-critic.md @@ -3,24 +3,6 @@ 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 @@ -297,3 +279,23 @@ 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/planning-orchestrator.md b/agents/planning-orchestrator.md index 1603930..a7c3511 100644 --- a/agents/planning-orchestrator.md +++ b/agents/planning-orchestrator.md @@ -1,18 +1,6 @@ --- name: planning-orchestrator -description: | - Inline reference (v2.4.0) — documents the planning workflow that - /trekplan executes in main context. - This file is a reference document, not a spawnable capability. - Historically not spawned as a sub-agent: before Claude Code 2.1.172 - the harness did not expose the - Agent tool to sub-agents, so a background orchestrator could not spawn - the exploration swarm (architecture-mapper, task-finder, plan-critic, - etc.). As of CC 2.1.172 sub-agents can spawn sub-agents (up to 5 levels - deep), so a delegated-orchestration redesign is under evaluation (see - docs/cc-upgrade-2.1.181-decision-matrix.md, W1/CC-26). Until then the - /trekplan command orchestrates the phases below directly in the main - session. +description: Reference document, not a spawnable capability — documents the /trekplan planning workflow that runs inline in main context (full rationale, CC-2.1.172 history, and phase map in body). model: opus color: cyan tools: ["Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate", "TaskUpdate"] diff --git a/agents/research-orchestrator.md b/agents/research-orchestrator.md index 04603c2..a31b950 100644 --- a/agents/research-orchestrator.md +++ b/agents/research-orchestrator.md @@ -1,17 +1,6 @@ --- name: research-orchestrator -description: | - Inline reference (v2.4.0) — documents the research workflow that - /trekresearch executes in main context. - This file is a reference document, not a spawnable capability. - Historically not spawned as a sub-agent: before Claude Code 2.1.172 - the harness did not expose the - Agent tool to sub-agents, so a background orchestrator could not spawn - the research swarm. As of CC 2.1.172 sub-agents can spawn sub-agents - (up to 5 levels deep), so a delegated-orchestration redesign is under - evaluation (see docs/cc-upgrade-2.1.181-decision-matrix.md, W1/CC-26). - Until then the /trekresearch command orchestrates the phases below - directly in the main session. +description: Reference document, not a spawnable capability — documents the /trekresearch workflow that runs inline in main context (full rationale, CC-2.1.172 history, and phase map in body). model: opus color: cyan tools: ["Read", "Glob", "Grep", "Write", "Edit", "Bash"] diff --git a/agents/research-scout.md b/agents/research-scout.md index 09efc9a..9f3e8e8 100644 --- a/agents/research-scout.md +++ b/agents/research-scout.md @@ -3,24 +3,6 @@ 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"] @@ -118,3 +100,23 @@ 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/review-orchestrator.md b/agents/review-orchestrator.md index 0751191..b94d0cc 100644 --- a/agents/review-orchestrator.md +++ b/agents/review-orchestrator.md @@ -1,19 +1,6 @@ --- name: review-orchestrator -description: | - Inline reference (v3.2.0) — documents the review workflow that - /trekreview executes in main context. - This file is a reference document, not a spawnable capability. - Historically not spawned as a sub-agent: before Claude Code 2.1.172 - the harness did not expose - the Agent tool to sub-agents, so a background orchestrator could not - spawn the reviewer swarm (brief-conformance-reviewer, - code-correctness-reviewer, review-coordinator). As of CC 2.1.172 - sub-agents can spawn sub-agents (up to 5 levels deep), so a - delegated-orchestration redesign is under evaluation (see - docs/cc-upgrade-2.1.181-decision-matrix.md, W1/CC-26). Until then the - /trekreview command orchestrates the phases below directly in the main - session. +description: Reference document, not a spawnable capability — documents the /trekreview workflow that runs inline in main context (full rationale, CC-2.1.172 history, and phase map in body). model: opus color: red tools: ["Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate", "TaskUpdate"] diff --git a/agents/risk-assessor.md b/agents/risk-assessor.md index 16a2531..7fd14a2 100644 --- a/agents/risk-assessor.md +++ b/agents/risk-assessor.md @@ -3,24 +3,6 @@ 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 @@ -106,3 +88,23 @@ 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 bd3f425..c36fd3a 100644 --- a/agents/scope-guardian.md +++ b/agents/scope-guardian.md @@ -3,24 +3,6 @@ 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"] @@ -144,3 +126,23 @@ 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 d960c0d..a4516ca 100644 --- a/agents/security-researcher.md +++ b/agents/security-researcher.md @@ -3,26 +3,6 @@ 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"] @@ -140,3 +120,25 @@ 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 fb82457..96526ab 100644 --- a/agents/session-decomposer.md +++ b/agents/session-decomposer.md @@ -4,24 +4,6 @@ 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"] @@ -310,3 +292,23 @@ 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/synthesis-agent.md b/agents/synthesis-agent.md index 39629d9..89bdab3 100644 --- a/agents/synthesis-agent.md +++ b/agents/synthesis-agent.md @@ -1,28 +1,6 @@ --- name: synthesis-agent -description: | - Synthesises the trekplan Phase-5/7 exploration outputs (architecture-mapper, - dependency-tracer, task-finder, risk-assessor, test-strategist, git-historian, - convention-scanner, research) into the structured findings DIGEST that Phase 7 - currently builds inline. Reads the outputs from disk and returns a single - schema-conformant digest — it never spawns sub-agents and never writes files. - - STATUS — DORMANT (NW3 / S12). Built and measured as the CC-26 §6 synthesis-agent - PoC, then DECLINED per measurement: delegating only Phase 7 yields Δ main-context - ≈ 0 because the Phase-5 swarm runs foreground, so its outputs are already resident - in main before synthesis. This agent is therefore NOT wired into /trekplan. It is - kept as a documented, schema-conformant building block so a future Phase-5 - redesign (swarm-writes-to-disk / nested orchestrator) can be re-measured cheaply. - See docs/T1-synthesis-poc-results.md and docs/T1-cc26-delegated-orchestration.md §6. - - - Context: A future Phase-5-writes-to-disk redesign wants to re-test delegated synthesis. - user: "Synthesise the exploration outputs in .claude/projects/X/exploration/ into a digest" - assistant: "Launching synthesis-agent to read those outputs and return a findings digest." - - Only reachable deliberately (PoC / future re-measurement) — not from the live pipeline. - - +description: DORMANT PoC (NW3/S12), NOT wired into /trekplan — a schema-conformant agent that distills the Phase-5/7 exploration outputs into one findings digest; kept as a re-measurable building block (see docs/T1-synthesis-poc-results.md). model: opus color: cyan tools: ["Read", "Glob", "Grep"] diff --git a/agents/task-finder.md b/agents/task-finder.md index 81ef3a3..fee90ea 100644 --- a/agents/task-finder.md +++ b/agents/task-finder.md @@ -4,24 +4,6 @@ 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 @@ -146,3 +128,23 @@ 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 b95e0cb..756b7f1 100644 --- a/agents/test-strategist.md +++ b/agents/test-strategist.md @@ -3,24 +3,6 @@ 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"] @@ -95,3 +77,23 @@ 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 c9f02d8..acbb9c4 100644 --- a/commands/trekbrief.md +++ b/commands/trekbrief.md @@ -2,7 +2,6 @@ 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 --- @@ -367,13 +366,14 @@ 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 3 options: +issue one `AskUserQuestion` with 4 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,6 +384,15 @@ 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 @@ -891,7 +900,7 @@ Never let stats failures block the workflow. ## Profile (v4.1) Accepts `--profile ` where `` is one of `economy`, `balanced`, -`premium`, or a custom profile under `voyage-profiles/`. Default: `premium`. +`premium`, `fable`, 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 f71f947..7267fd9 100644 --- a/commands/trekcontinue.md +++ b/commands/trekcontinue.md @@ -2,7 +2,6 @@ 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 122fbb8..f395b35 100644 --- a/commands/trekendsession.md +++ b/commands/trekendsession.md @@ -2,7 +2,6 @@ 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 @@ -91,16 +90,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 `/.session-state.local.json` with the schema-v1 object: +Write `{project_dir}/.session-state.local.json` with the schema-v1 object: ```json { "schema_version": 1, - "project": "", - "next_session_brief_path": "", - "next_session_label": "", + "project": "{project_dir}", + "next_session_brief_path": "{arg 1}", + "next_session_label": "{arg 2}", "status": "in_progress", - "updated_at": "" + "updated_at": "{now, ISO-8601}" } ``` @@ -115,14 +114,22 @@ Under `node --input-type=module -e "