diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 957ce0e..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.1.1", + "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 b494b59..b92beb2 100644 --- a/.gitignore +++ b/.gitignore @@ -19,7 +19,9 @@ blob-report/ # Local configuration / session files *.local.* -# STATE.md — current state-of-play (overskrives ved sesjonsslutt, gitignored per ~/.claude/CLAUDE.md). +# 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. @@ -29,3 +31,14 @@ 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 --- +REMEMBER.md +ROADMAP.md +TODO.md +NEXT-SESSION-PROMPT*.local.md +*.local.md +*.local.json +*.local.sh +.DS_Store +.claude/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 54cd59a..21b08e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,188 @@ 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). + +### Machine-verifiable completion gate (the headline) + +- **Stop-signal contract** — `/trekexecute` reports `completed` only when a machine-checkable contract holds: the Phase 7.5 manifest audit PASSes, the stop signal exits 0, and the success criteria are green. **Hard Rule 18** is promoted from prose guidance to an enforced gate, anchored in the Phase 7.5 audit rather than the model's self-assessment. + +### Bounded recovery — cap hierarchy + global budget + +- **`TREKEXECUTE_MAX_RECOVERY_ITERATIONS`** — a global recovery-iteration budget (default **25**, env-overridable) sits above the per-step caps as a three-axis cap hierarchy (recovery depth · per-step retry · global budget), codified as **Hard Rule 20**. Stops an unbounded recover→retry→recover spiral that the per-step caps alone could not bound. +- **`iterations_remaining` signal** — surfaced in the progress schema and the summary JSON, with a deterministic gate cross-check (`iterations_remaining == cap − (recovery_depth + Σ attempts-beyond-first)`) that catches a never-decremented counter. Shape-validated in `lib/.../progress-validator.mjs` (`PROGRESS_ITERATIONS_REMAINING_INVALID`: non-negative integer, additive-optional — never required at top level). + +### Doc consistency + +- **Fan-out hedge harmonized** — the `CLAUDE.md` design-principle line is aligned to the measured claim (parallel wall-clock + structured artifact handoffs as the load-bearing benefit; main-context relief stays explicitly *not demonstrated*), with a banned-phrase **forward-guard** in `tests/lib/doc-consistency.test.mjs` so the over-claim cannot reappear. + +### Release hygiene + +- **Version sync** — `plugin.json`, `package.json`, `package-lock.json`, the README badge, and the CHANGELOG top entry all at `5.6.0`, guarded by the version-consistency test in `tests/lib/doc-consistency.test.mjs`. + +## v5.5.0 — 2026-06-18 — Coordinated release: brief framing enforcement (2.2) + W1–W3 narrow wins + +The coordinated release held since the framing work. Supersedes the unreleased internal milestones **v5.2–v5.4** (W2 model/effort alignment, W3 guardrail hardening, the Handover-1 public-contract formalization), landing them together with the `brief_version 2.2` schema badge and the W1 narrow wins. **Additive — no breaking change for existing consumers:** every `2.0`/`2.1` brief still validates; the new requirements gate only on briefs that *declare* `brief_version: "2.2"`. + +### Brief framing enforcement — `brief_version 2.2` (the headline) + +Three version-gated layers ship at `brief_version ≥ 2.2`, implementing the `CLAUDE.md` cross-cutting invariant "brief framing must match operator intent": + +- **`framing` enum** (`preserve | refine | replace | new-direction`) — required in frontmatter, collected in `/trekbrief` Phase 2.5 *before* any prose is written, non-skippable even in `--quick`. Enum-checked on any version (`BRIEF_INVALID_FRAMING`); missing at ≥ 2.2 → `BRIEF_MISSING_FRAMING`. +- **Memory-alignment dimension** — new `brief-reviewer` dimension 6 compares brief Intent/Goal + framing against operator memory, flagging *explicit* contradictions only (scores N/A when no memory is supplied); wired to the Phase 4e gate (`memory_alignment.score ≥ 4`). Emits a `status` field (`verified | n_a | contradictions`) so a score-5 N/A (no memory available) is distinguishable from a score-5 verified-aligned brief — the gate passes in both cases, and `status` is what tells the operator whether the wrong-premise defense actually ran. +- **Obligatory `## TL;DR`** — ≤ 5 content lines at the top of every 2.2 brief (soft cap → `BRIEF_TLDR_TOO_LONG`). +- **Opt-in version floor** — `--min-brief-version ` on `/trekplan` + `/trekresearch` (forwarded to the validator as `--min-version`) raises a `BRIEF_VERSION_BELOW_MINIMUM` *warning* — never a block — when a brief declares a version below the floor. Closes the producer-elective hole where a `2.0`/`2.1` brief silently sidesteps framing enforcement; `docs/HANDOVER-CONTRACTS.md` §Handover 1 now documents pre-2.2 = zero framing enforcement and the two remedies (require `2.2` upstream, or pass the floor flag). + +Existing `2.0`/`2.1` briefs stay valid (forward + backward compatible), mirroring the `phase_signals ≥ 2.1` precedent. `trekreview` briefs are exempt. + +### Public contract formalization (Handover 1) + +`docs/HANDOVER-CONTRACTS.md` §Handover 1 (`brief.md` → research) is now labeled **PUBLIC CONTRACT** — the only public integration boundary of the pipeline. Froze `brief_version 2.1` as the baseline, then evolved it to `2.2` under the breaking-change protocol. Any conforming producer (not just `/trekbrief`) may feed Voyage; brief-schema changes are breaking for every downstream consumer. + +### Model & effort alignment (W2) + +- **Opus 4.8 baseline** — the `opus` alias resolves to Opus 4.8 (default reasoning effort `high`). +- **Native `effort:` frontmatter** (additive, static) on 8 agents: retrieval (`task-finder`, `git-historian`, `dependency-tracer`, `architecture-mapper`) → `medium`; adversarial-reasoning (`plan-critic`, `risk-assessor`, `contrarian-researcher`, `review-coordinator`) → `high`. The other 15 agents inherit the Opus-4.8 default. +- **Resolver model-gate fix** — `lib/profiles/phase-signal-resolver.mjs` now gates `model` against `BASE_ALLOWED_MODELS` (mirrors the existing `effort` gate); out-of-allowlist models are dropped rather than handed to a spawn. +- **Axis distinction documented** — `docs/profiles.md` §Model & effort axes separates orchestration `phase_signals.effort` (which agents/passes run) from native reasoning `effort:` (per-spawn budget) — different axes that happen to share the name `effort`. + +### Guardrails & hooks hardening (W3) + +- **Exec-form hooks** (CC-14) — all 7 hooks in `hooks/hooks.json` migrated to `{command:"node", args:["${CLAUDE_PLUGIN_ROOT}/…"]}`, removing a class of path-quoting bugs for consumers who install Voyage under a path containing spaces. +- **`disallowed-tools` enforcement** (CC-11) — `disallowed-tools: Agent, TeamCreate` added to `/trekexecute`, promoting its documented no-delegation rule from prose to enforcement (`allowed-tools` grants auto-approval but does not remove a tool from the pool; `disallowed-tools` does). +- **Universal safety executors** (CC-15) — `pre-bash-executor.mjs` / `pre-write-executor.mjs` confirmed universal by design (session-agnostic safety; narrowing to execute-only sessions would only weaken protection). + +### Narrow wins (W1 — NW1–NW3) + +- **NW1 — reviewer-output schema contract** (ungated, shipped). `lib/review/findings-schema.mjs` validates each `/trekreview` Phase 5 reviewer's JSON against a schema; on *schema* failure main re-asks for conforming JSON (bounded N=2), retiring the fragile "collect trailing JSON / re-ask on parse error" contract. +- **NW2 — trekreview Workflow port as opt-in `--workflow` flag.** Phase 5–6 (`parallel([conformance, correctness])` → plain-JS dedup-by-`(file,line,rule_key)` → `agent(coordinator)`) ported to a Workflow script, reachable via `--workflow` (default stays prose, preserving the 2.1.154+ portability floor). Bake-off verdict **opt-in-defensible** (POSITIVE on the measured axes — fidelity-equivalent `review.md`, zero classifier interference at 9-agent concurrency, ≈ +4.4% tokens — but on a single un-archived run: the raw per-run data was never committed, so the numbers cannot be re-derived; see `docs/T2-bakeoff-results.md` §Reproducibility caveat). +- **NW3 — synthesis-agent shipped dormant (declined per measurement).** Built + measured deterministically: Δ main-context = **0%** at all realistic BASE — delegating only trekplan Phase 7 evicts nothing, since the Phase-5 foreground reads make the outputs resident first. Not wired; re-measurement is cheap via `scripts/synthesis-measure.mjs`. See `docs/T1-synthesis-poc-results.md`. + +### CC 2.1.130→181 verification dispositions + +- **Verified clean (no regression):** CC-29 (`subagent_type` matching now case/separator-insensitive; no Voyage agent declares multiple `Agent(...)` types), CC-31 (the tightened background worktree-isolation guard aligns with Voyage's intent — `/trekplan` `TeamCreate isolation:"worktree"` with sequential fallback, `/trekexecute` Phase 2.6 worktree waves). +- **CC-08 — GH #36071 (hooks in headless `claude -p`) closed as NOT PLANNED, not fixed.** The in-prompt safety preamble is retained as the headless defense. +- **Deferred (recorded, no code):** CC-07 (`fallbackModel`), CC-12 (Stop/SubagentStop `additionalContext`), CC-13 (`background_tasks`/`session_crons` in hook input). Triggers noted in `docs/cc-upgrade-2.1.181-decision-matrix.md` §S13. + +### Release hygiene + +- **Version sync** — `plugin.json`, `package.json`, README badge, and the CHANGELOG top entry all at `5.5.0`, guarded by a new version-consistency test in `tests/lib/doc-consistency.test.mjs`. +- **Honest test count (S19)** — `lib/util/test-census.mjs` + `tests/lib/test-census.test.mjs` report the behavior-test count separately from the doc-consistency prose-pin count, so the cited total no longer oversells behavior coverage. Pruned 3 redundant/tautological prose-pins from `doc-consistency.test.mjs` (each provably subsumed by a structural invariant or behavior test). Devil's-advocate audit §Top changes #8. +- **`claude plugin validate` passes.** The single advisory warning (root `CLAUDE.md` not loaded as consumer project context) is **accepted by design**: it is universal across all marketplace plugins, validation still passes, and the root `CLAUDE.md` is repo/maintainer context — consumer context ships via README + command/agent frontmatter. + ## v5.1.1 — 2026-05-14 — Remediation patch (11/12 review findings closed) Additive. No breaking changes against v5.1.0. Closes 11 of 12 BLOCKER/MAJOR/MINOR findings from the v5.1.0 review (sesjon 5, review.md SHA range `8cbb33e..8f4b79c`). SC8 dogfood gate (#5) is scheduled for sesjon 8 as a fresh-CC-session operator action — its closure cannot happen inside the v5.1.1 execute session. diff --git a/CLAUDE.md b/CLAUDE.md index dad4d5c..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. +**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.4. +> **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), alle BLOCKER ved brudd når v5.5 shipper:** (1) eksplisitt `framing: preserve|refine|replace|new-direction` i brief-frontmatter, `AskUserQuestion`-validert før brief-prosa skrives; (2) memory-alignment check som ny dimensjon i `brief-reviewer` — sammenlikner brief-prosa mot relevante memory-filer og rapporterer eksplisitte motsigelser; (3) obligatorisk `## TL;DR`-seksjon (≤ 5 linjer) øverst i `brief.md`. Implementeres i v5.5 (tracket i `STATE.md` § NESTE STEG når aktivt). Inntil shipping: operatør må manuelt sjekke at briefens framingord ikke motsier intent, særlig etter avvist iterasjon hvor "delta fra forrige" er en farlig default-ankring. +> **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 | @@ -39,24 +39,29 @@ Full flag reference for each command (modes, `--gates`, `--profile`, breaking ch | git-historian | opus | Recent changes, ownership, hot files | | research-scout | opus | External docs for unfamiliar tech (conditional, planning only) | | convention-scanner | opus | Coding conventions: naming, style, error handling, test patterns | -| brief-reviewer | opus | Task brief quality (5 dimensions: completeness, consistency, testability, scope clarity, research plan validity) | +| brief-reviewer | opus | Task brief quality (6 dimensions: completeness, consistency, testability, scope clarity, research plan validity, memory alignment) | | brief-conformance-reviewer | opus | Brief conformance review (SC + Non-Goal traceability) | | code-correctness-reviewer | opus | Code correctness review (7 dimensions) | | review-coordinator | opus | Judge Agent — dedup + reasonableness filter + verdict | -| plan-critic | opus | Adversarial plan review (9 dimensions) | +| plan-critic | opus | Adversarial plan review (10 dimensions) | | scope-guardian | opus | Scope alignment (creep + gaps) | | session-decomposer | opus | Splits plans into headless sessions with dependency graph | +| synthesis-agent | opus | Distills Phase-5/7 exploration outputs into a findings digest (NW3 PoC — **dormant**, not wired; delegating Phase 7 alone yields Δ main-context ≈ 0, see `docs/T1-synthesis-poc-results.md`) | | docs-researcher | opus | Official documentation, RFCs, vendor docs (Tavily, MS Learn) | | community-researcher | opus | Community experience: issues, blogs, discussions | | security-researcher | opus | CVEs, audit history, supply chain risks | | contrarian-researcher | opus | Counter-evidence, overlooked alternatives | | gemini-bridge | opus | Gemini Deep Research second opinion (conditional) | +> **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.** `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 30eea85..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.1.1-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,14 +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.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 | |---------|-------------| @@ -148,7 +141,7 @@ Concrete capabilities, observable in the code — not aspirations. Interactive requirements-gathering command. Runs a **dynamic, quality-gated interview** and produces a **task brief** with an explicit research plan. Optionally orchestrates the rest of the pipeline. -A section-driven interview loop fills required brief sections (Intent / Goal / Success Criteria / Research Plan) until each shows initial signal, then `brief-reviewer` scores the draft on five dimensions (completeness, consistency, testability, scope clarity, research-plan validity) and gates publication. Max 3 review iterations; force-stop yields a `brief_quality: partial` brief with the failing dimensions documented. +A section-driven interview loop fills required brief sections (Intent / Goal / Success Criteria / Research Plan) until each shows initial signal, then `brief-reviewer` scores the draft on six dimensions (completeness, consistency, testability, scope clarity, research-plan validity, memory alignment) and gates publication. Max 3 review iterations; force-stop yields a `brief_quality: partial` brief with the failing dimensions documented. Output: `.claude/projects/{YYYY-MM-DD}-{slug}/brief.md` @@ -158,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. @@ -185,7 +178,7 @@ If you say "stop" or "enough" during Phase 4, the current review findings are su Deep, multi-phase research that combines local codebase analysis with external knowledge. Uses specialized agent swarms to investigate multiple dimensions in parallel, then triangulates findings. -A parallel swarm of up to 5 local + 4 external Sonnet agents investigates 3–8 research dimensions, with optional Gemini Deep Research as an independent second opinion. Findings are triangulated (local vs. external, confidence per dimension, contradictions flagged) and synthesized into a structured research brief. +A parallel swarm of up to 5 local + 4 external agents investigates 3–8 research dimensions, with optional Gemini Deep Research as an independent second opinion. Findings are triangulated (local vs. external, confidence per dimension, contradictions flagged) and synthesized into a structured research brief. Output: - With `--project `: `{dir}/research/{NN}-{slug}.md` (auto-incremented index) @@ -202,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`. @@ -213,7 +207,7 @@ Research uses up to 5 local agents (architecture-mapper, dependency-tracer, task Produces an implementation plan detailed enough for autonomous execution. **v2.0 breaking change:** requires `--brief` or `--project`. There is no longer an interview inside `/trekplan` — use `/trekbrief` first. -After `brief-reviewer` validates the input brief, 6–8 Sonnet exploration agents analyze the codebase in parallel and merge findings into a synthesis. Optional research briefs (`--research`, or auto-discovered in `{project_dir}/research/`) enrich the plan; `architecture/overview.md` priors are loaded if an opt-in upstream architect plugin (not bundled) produced one. Opus then writes the plan with per-step YAML manifests, which `plan-critic` (9 dimensions) and `scope-guardian` adversarially review before handoff. +After `brief-reviewer` validates the input brief, 6–8 exploration agents analyze the codebase in parallel and merge findings into a synthesis. Optional research briefs (`--research`, or auto-discovered in `{project_dir}/research/`) enrich the plan; `architecture/overview.md` priors are loaded if an opt-in upstream architect plugin (not bundled) produced one. Opus then writes the plan with per-step YAML manifests, which `plan-critic` (10 dimensions) and `scope-guardian` adversarially review before handoff. Output: - With `--project `: `{dir}/plan.md` @@ -229,7 +223,7 @@ Output: | **Foreground** | `/trekplan --project --fg` | No-op alias (foreground is default since v2.4.0) | | **Quick** | `/trekplan --project --quick` | No agent swarm, lightweight scan only | | **Decompose** | `/trekplan --decompose plan.md` | Split plan into headless session specs | -| **Export** | `/trekplan --export pr plan.md` | PR description, issue comment, or clean markdown | +| **Export** | `/trekplan --export headless plan.md` | Legacy alias for `--decompose` (the only remaining export format) | | **Profile** | `/trekplan --profile --project ` | (v4.1.0) Pin model profile; emitted as `profile:` in plan.md frontmatter. See [Profile system](#profile-system-v410). | `--brief` or `--project` is **required**. `/trekplan` with no brief exits with an error and a pointer to `/trekbrief`. @@ -256,7 +250,7 @@ Every implementation step includes: - **Checkpoint:** — git commit after success - **Manifest:** — the objective completion predicate (Hard Rule 17) -Exploration uses 6–8 Sonnet agents in parallel (architecture-mapper, dependency-tracer, task-finder, test-strategist, git-historian, risk-assessor, plus convention-scanner on medium+ codebases and research-scout when unfamiliar tech is detected). Adversarial review then runs `brief-reviewer`, `plan-critic` (9 dimensions, no-placeholder enforcement, manifest audit), and `scope-guardian` (creep + gap detection). Per-agent details in [`agents/`](agents/). +Exploration uses 6–8 agents in parallel (architecture-mapper, dependency-tracer, task-finder, test-strategist, git-historian, risk-assessor, plus convention-scanner on medium+ codebases and research-scout when unfamiliar tech is detected). Adversarial review then runs `brief-reviewer`, `plan-critic` (10 dimensions, no-placeholder enforcement, manifest audit), and `scope-guardian` (creep + gap detection). Per-agent details in [`agents/`](agents/). --- @@ -592,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. @@ -744,20 +779,21 @@ 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 | Lowest cost; high-confidence small-scope tasks | -| `balanced` (default) | sonnet | sonnet | opus | sonnet | opus | sonnet | Default — opus where reasoning depth pays off | -| `premium` | opus | sonnet | opus | sonnet | opus | sonnet | Critical-path planning + review when budget allows | +| `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: 1. Explicit `--profile ` flag passed to the command 2. Plan-file frontmatter `profile:` (when resuming via `/trekexecute --resume` or `/trekcontinue`) 3. `VOYAGE_PROFILE` environment variable -4. Default `balanced` +4. Default `premium` See [`docs/profiles.md`](docs/profiles.md) for the decision tree, custom-profile authoring, and cost estimation disclaimer (the per-profile cost numbers are *anslag*, not contractual SLAs). @@ -775,7 +811,9 @@ Default JSONL stats stream (`${CLAUDE_PLUGIN_DATA}/trek*-stats.jsonl`) is unchan ## Cost profile -Opus runs the orchestrators (one per command) and the executor (one per plan session). Sonnet runs the exploration and review swarms (5–10 agents per command, with effort/turn limits). The pipeline front-loads cheap Sonnet work so Opus only does synthesis and execution. Typical total: comparable to a long single Claude Code session — the 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`), `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). @@ -792,12 +830,13 @@ Top-level layout: ``` trekplan/ -├── agents/ 23 specialized agents (sonnet for exploration + review, opus for orchestration) -├── commands/ 6 slash commands (trekbrief, trekresearch, trekplan, trekexecute, trekreview, trekcontinue) + trekplan-end-session helper +├── agents/ 24 specialized agents (all `model: opus`-pinned; per-phase model set by `--profile`) +│ └ 21 spawnable (1 dormant: synthesis-agent, Δ≈0) + 3 orchestrator reference docs (not spawned) +├── commands/ 6 slash commands (trekbrief, trekresearch, trekplan, trekexecute, trekreview, trekcontinue) + trekendsession helper ├── templates/ Frontmatter templates for brief, research, plan, session, launch -├── hooks/ 5 hooks (pre-bash, pre-write, session-title, post-bash-stats, pre-compact-flush) +├── hooks/ 7 hooks (pre-bash, pre-write, session-title, post-bash-stats, pre-compact-flush, post-compact-flush, otel-export) ├── lib/ Zero-dep parsers and validators (CLI shims under lib/validators/) -├── tests/ 109 node:test cases — `npm test` is the fork-readiness gate +├── tests/ comprehensive node:test suite — `npm test` is the fork-readiness gate ├── docs/ HANDOVER-CONTRACTS.md + architect-bridge-test.md └── examples/ 01-add-verbose-flag/ — calibrated end-to-end pipeline demo ``` @@ -835,7 +874,7 @@ synthesis. The default for `/trekbrief`, `/trekresearch`, `/trekplan`, and `/trekexecute` is `opus` (deep reasoning). To run on Sonnet for cost or latency, search-and-replace -the frontmatter in three files: +the frontmatter in these four command files: ```bash sed -i.bak 's/^model: opus$/model: sonnet/' \ @@ -845,7 +884,9 @@ sed -i.bak 's/^model: opus$/model: sonnet/' \ commands/trekexecute.md ``` -The exploration agents stay on Sonnet — only the orchestrator is bumped. +This flips only the four command orchestrators. The exploration and review +sub-agents in `agents/*.md` are separately `opus`-pinned — flip those too, or +just run `--profile economy`, to put the whole pipeline on Sonnet. ### Disable external research diff --git a/agents/architecture-mapper.md b/agents/architecture-mapper.md index 2fafd05..9a5e6ad 100644 --- a/agents/architecture-mapper.md +++ b/agents/architecture-mapper.md @@ -3,25 +3,8 @@ 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 tools: ["Read", "Glob", "Grep", "Bash"] --- @@ -103,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 bd1f3b1..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"] @@ -35,8 +17,12 @@ missing, vague, or contradictory. ## Input -You receive the path to a brief file (trekbrief v2.0 format, produced by -`/trekbrief`). Read it and evaluate its quality across five dimensions. +You receive the path to a brief file (trekbrief format, produced by +`/trekbrief`). Read it and evaluate its quality across six dimensions. + +The caller may also supply **operator memory context** (paths or excerpts of +`feedback_*` / `project_*` facts) in your prompt for the memory-alignment +dimension. If none is supplied, that dimension scores 5 (N/A) — see dimension 6. A brief has these sections (see template for full structure): - `## Intent` — why the work matters (load-bearing) @@ -148,6 +134,39 @@ Flag as **research-plan invalid** if: - `research_topics` count in frontmatter does not match section count - `research_status: complete` but research files are missing on disk +### 6. Memory alignment (NEW in v5.5) + +The brief is the pipeline's source of truth, but the operator's *real* intent +also lives in memory facts (`feedback_*`, `project_*`). When the two diverge, +downstream reasoning power polishes a wrong premise instead of challenging it. +This dimension is the second layer of the framing-alignment defense. + +The caller MAY supply operator memory excerpts or file paths in your prompt. + +- **If memory context IS supplied:** compare the brief — especially `## Intent`, + `## Goal`, and the frontmatter `framing:` value — against those facts. Report + **EXPLICIT contradictions only** (a brief claim that a memory fact directly + negates), never vibes or soft mismatches. With no contradiction found, set + `status: "verified"`; with one or more, set `status: "contradictions"`. +- **If NO memory context is supplied:** score `5`, set `contradictions: []`, + `status: "n_a"`, and note "no memory context supplied". Do not speculate or + invent contradictions. + +The `status` field is load-bearing: a `score: 5` alone is ambiguous because it is +emitted both when memory was checked and aligned (`verified`) and when no memory +was available to check (`n_a`). Downstream gates that read `memory_alignment.score +≥ 4` therefore pass in *both* cases — `status` is what tells the operator whether +the wrong-premise defense actually ran or was simply absent. + +Flag as **memory-misaligned** if: +- The frontmatter `framing:` value contradicts memory (e.g. `framing: preserve` + but memory records the prior direction was explicitly abandoned) +- `## Intent` or `## Goal` asserts a premise a memory fact directly negates +- A Constraint or Preference contradicts a recorded operator preference + +For each contradiction, capture: the brief claim (quoted), the memory fact +(quoted), and the source file. These feed `/trekbrief` Phase 4e follow-ups. + ## Rating Rate each dimension on two parallel scales: @@ -193,6 +212,7 @@ find it by reading the last `json` code fence. | Testability | {Pass/Weak/Fail} | {brief summary or "None"} | | Scope clarity | {Pass/Weak/Fail} | {brief summary or "None"} | | Research Plan | {Pass/Weak/Fail} | {brief summary or "None"} | +| Memory alignment | {Pass/Weak/Fail} | {brief summary, "None", or "N/A — no memory"} | ### Findings @@ -224,6 +244,13 @@ information that would strengthen the brief. List only if actionable.} { "topic": "{topic title}", "issue": "{what is missing or wrong}" } ] }, + "memory_alignment": { + "score": 1-5, + "status": "verified | n_a | contradictions", + "contradictions": [ + { "brief_claim": "{quoted brief text}", "memory_fact": "{quoted memory fact}", "file": "{source file}" } + ] + }, "verdict": "PROCEED | PROCEED_WITH_RISKS | REVISE" } ``` @@ -257,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 b0b9f95..a1027b1 100644 --- a/agents/contrarian-researcher.md +++ b/agents/contrarian-researcher.md @@ -4,27 +4,8 @@ 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 tools: ["WebSearch", "WebFetch", "mcp__tavily__tavily_search", "mcp__tavily__tavily_research"] --- @@ -151,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 7185894..25c9d57 100644 --- a/agents/dependency-tracer.md +++ b/agents/dependency-tracer.md @@ -3,25 +3,8 @@ 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 tools: ["Read", "Glob", "Grep", "Bash"] --- @@ -92,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 9971a41..2c90a51 100644 --- a/agents/git-historian.md +++ b/agents/git-historian.md @@ -3,25 +3,8 @@ 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 tools: ["Bash", "Read", "Glob", "Grep"] --- @@ -121,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 ac382d9..b2aa6ed 100644 --- a/agents/plan-critic.md +++ b/agents/plan-critic.md @@ -3,25 +3,8 @@ 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 tools: ["Read", "Glob", "Grep"] --- @@ -272,5 +255,47 @@ quality is not scored and Headless readiness returns to 0.15. - Verdict: [APPROVE | APPROVE_WITH_NOTES | REVISE | REPLAN] ``` +### Machine-readable findings block (REQUIRED) + +After the human-readable markdown above, emit **one** fenced `json` block as the +**last thing in your response**. The /trekplan orchestrator extracts it verbatim +and pipes it (with scope-guardian's) into +`lib/review/plan-review-dedup.mjs --stdin`. You have **no Write tool** — returning +this block inline *is* the hand-off; do not attempt to write a file. + +```json +{ + "agent": "plan-critic", + "findings": [ + { "file": "", "line": 0, "rule_key": "", "severity": "blocker|major|minor", "text": "" } + ] +} +``` + +One object per finding. `file`/`line` point at the plan section (use the plan +path + the step's line) or the source the finding concerns; `rule_key` is a +short, stable id for the finding class (used for exact-match dedup). Emit +`"findings": []` when the plan is clean. + 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 50afa89..a7c3511 100644 --- a/agents/planning-orchestrator.md +++ b/agents/planning-orchestrator.md @@ -1,17 +1,9 @@ --- name: planning-orchestrator -description: | - Inline reference (v2.4.0) — documents the planning workflow that - /trekplan executes in main context. This file is NOT spawned as a - sub-agent anymore. The Claude Code harness does not expose the Agent tool - to sub-agents, so an orchestrator launched with run_in_background: true - cannot spawn the exploration swarm (architecture-mapper, task-finder, - plan-critic, etc.) and would degrade to single-context reasoning. The - /trekplan command now 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: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate", "TaskUpdate"] +tools: ["Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate", "TaskUpdate"] ---