Kjell Tore Guttormsen
6ba58fda9b
Truth-pass over the README/CLAUDE/contract docs the S14 audit flagged as
stale (findings #2/#6/#7/#8/#9). Re-grepped every count against the actual
files first — line numbers in the audit are S14 snapshots that had already
rotted. docs + tests only; lib/ runtime and all behaviour untouched.
Corrections:
- README architecture block: 23 → 24 agents; 5 → 7 hooks (add the two it
omitted: post-compact-flush, otel-export); dropped the rotting test-count
("109" — already wrong twice, 109→683→686) for "comprehensive node:test
suite" so the number can never drift again (operator choice).
- brief-reviewer five → six dimensions (+ memory alignment); plan-critic
9 → 10 dimensions (README ×2 + CLAUDE.md), matching the agent's 10 numbered
dims and the v5.5 flagship 6th brief dimension.
- phantom "v5.4" contract-freeze references → v5.5.0 (CLAUDE.md + HANDOVER-
CONTRACTS ×3). v5.2–5.4 never shipped; the formalization landed with 2.2 in
v5.5.0 (CHANGELOG:9), so line 46 got a prose tweak (one release both
established 2.1 and evolved it to 2.2). CHANGELOG history left intact — it
correctly explains the phantom.
- trekplan Phase-8 inline-sealing rationale "Opus 4.7" → 4.8.
- bonus (operator-approved): end-session helper name trekplan-end-session →
trekendsession (the actual command).
New doc-consistency pins (TDD red→green): README agent-count and hook-count
(file counts), plan-critic dim-count (computed from ### N. headers),
brief-reviewer dim-count (cross-file, excludes agent-list lines that
co-mention plan-critic's count). Updated the existing pin that guarded the
phantom "v5.4 froze 2.1" string to the corrected wording + a !/v5.4/ guard.
Version-string pins (Opus 4.8 / v5.5.0) deliberately omitted as S19 prose-bloat.
Tests 686 → 690 (688 pass / 2 skip / 0 fail). claude plugin validate passes
(1 accepted CLAUDE.md-at-root warning).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqBYc8Ltrk7LipyJmGxXiB
65 lines
7.9 KiB
Markdown
65 lines
7.9 KiB
Markdown
# trekplan
|
|
|
|
Voyage — a contract-driven Claude Code pipeline: brief, research, plan, execute, review, continue. Deep implementation planning and research with specialized agent swarms, external research, adversarial review, session decomposition, disciplined execution, and headless support.
|
|
|
|
**Design principle: Context Engineering** — build the right context by orchestrating specialized agents. Each step in the pipeline (brief → research → plan → execute) produces a structured artifact that the next step consumes.
|
|
|
|
> **v3.0.0 — architect step extracted from this plugin.** The plan command still auto-discovers `architecture/overview.md` if present, so any compatible producer (architect plugin no longer publicly distributed; the architecture/overview.md slot remains available for any compatible producer) plugs into the same slot. See [CHANGELOG.md](CHANGELOG.md) for migration history.
|
|
|
|
> **Trinity context (2026-05-13, informational).** Voyage is Tier 1 (per-task) of a three-tier architecture in active design under the author's private marketplace: Tier 2 `app-creator` (per-app — "what does the app need, what's the next brief?") produces briefs Voyage consumes; Tier 3 `app-factory` (per-portfolio — "which app needs me now?") aggregates state across multiple app-creator instances. Both are pre-implementation and will ship to Forgejo when ready. **Asymmetry is a hard invariant:** Voyage stays unaware of Tier 2/3. Handover 1 (brief format) is the only integration point — any compatible producer can feed Voyage, app-creator is not privileged. Brief-schema changes are therefore breaking changes for downstream consumers, formalized as a public contract in v5.5.0 — see `docs/HANDOVER-CONTRACTS.md` §Handover 1 (PUBLIC CONTRACT).
|
|
|
|
> **Cross-cutting invariant: brief framing must match operator intent (2026-05-15).** Etablert etter residiv. Briefen er pipelinens source of truth; operatørens intent lever i hodet + i memory-filer (`feedback_*`, `project_*`); pipelinen tvinger ikke alignment. Høyere reasoning-kraft polerer feil premiss istedenfor å utfordre det. **Tre lag av forsvar (input-siden), implementert i S6 som `brief_version 2.2`-gate (v5.5), alle BLOCKER ved brudd for briefer som deklarerer ≥ 2.2:** (1) eksplisitt `framing: preserve|refine|replace|new-direction` i brief-frontmatter, `AskUserQuestion`-validert i `/trekbrief` Phase 2.5 før brief-prosa skrives (ikke-skippbar, også i `--quick`); enum-feil → `BRIEF_INVALID_FRAMING` (alle versjoner), fravær ved ≥ 2.2 → `BRIEF_MISSING_FRAMING`; (2) memory-alignment som dimensjon 6 i `brief-reviewer` — sammenlikner brief-prosa + `framing` mot relevante memory-filer, rapporterer kun eksplisitte motsigelser (degraderer til score 5 N/A uten memory-kontekst), wired til Phase 4e-gate (`memory_alignment.score ≥ 4`); (3) obligatorisk `## TL;DR`-seksjon (≤ 5 linjer, soft-cap → `BRIEF_TLDR_TOO_LONG`) øverst i `brief.md`. Eksisterende 2.0/2.1-briefer forblir gyldige (forward+backward-compat, speiler `phase_signals ≥ 2.1`-presedensen); `trekreview`-briefer er unntatt. **Schema-akse bumpet (2.1→2.2); plugin-versjon-badge + CHANGELOG bumpes ved den koordinerte releasen (S10).** Kontrakt-evolusjon dokumentert i `docs/HANDOVER-CONTRACTS.md` §Handover 1. Den gamle manuelle stopgap-sjekken er dermed retired for ≥ 2.2-briefer.
|
|
|
|
## Commands
|
|
|
|
| Command | Description | Model |
|
|
|---------|-------------|-------|
|
|
| `/trekbrief` | Brief — interactive interview produces a task brief with explicit research plan; optionally orchestrates the pipeline | opus |
|
|
| `/trekresearch` | Research — deep local + external research, produces structured research brief | opus |
|
|
| `/trekplan` | Plan — brief-reviewer, explore, plan, review. Requires `--brief` or `--project`. Auto-discovers `architecture/overview.md` if present | opus |
|
|
| `/trekexecute` | Execute — disciplined plan/session-spec executor with failure recovery | opus |
|
|
| `/trekreview` | Review — independent post-hoc review of delivered code against the brief. Produces `review.md` with severity-tagged findings (Handover 6) | opus |
|
|
| `/trekcontinue` | Continue — resumes the next session of a multi-session voyage project. Reads `.session-state.local.json` (Handover 7) and immediately begins executing | opus |
|
|
| `/trekendsession` | End-session — mark the current session complete and write session-state pointing at the next session. Helper for informal multi-session flows | opus |
|
|
|
|
Full flag reference for each command (modes, `--gates`, `--profile`, breaking changes): see `docs/command-modes.md`.
|
|
|
|
## Agents
|
|
|
|
| Agent | Model | Role |
|
|
|-------|-------|------|
|
|
| planning-orchestrator | opus | Inline reference documentation for the planning pipeline workflow (brief-driven) |
|
|
| research-orchestrator | opus | Inline reference documentation for the research pipeline workflow |
|
|
| review-orchestrator | opus | Inline reference documentation for the review pipeline workflow |
|
|
| architecture-mapper | opus | Codebase structure, tech stack, patterns |
|
|
| dependency-tracer | opus | Import chains, data flow, side effects |
|
|
| task-finder | opus | Task-relevant files, functions, reuse candidates |
|
|
| risk-assessor | opus | Risks, edge cases, failure modes |
|
|
| test-strategist | opus | Test patterns, coverage gaps, strategy |
|
|
| git-historian | opus | Recent changes, ownership, hot files |
|
|
| research-scout | opus | External docs for unfamiliar tech (conditional, planning only) |
|
|
| convention-scanner | opus | Coding conventions: naming, style, error handling, test patterns |
|
|
| brief-reviewer | opus | Task brief quality (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 (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) |
|
|
|
|
> **Model & effort (CC 2.1.154+).** `opus` resolves to **Opus 4.8** (default reasoning effort `high`); `sonnet` to Sonnet 4.6. Select agents carry native `effort:` — retrieval agents (`task-finder`, `git-historian`, `dependency-tracer`, `architecture-mapper`) at `medium`, adversarial-reasoning agents (`plan-critic`, `risk-assessor`, `contrarian-researcher`, `review-coordinator`) at `high`. This native per-spawn **reasoning** effort is a different axis from brief `phase_signals.effort` (orchestration shape — which agents/passes run). See `docs/profiles.md` §Model & effort axes.
|
|
|
|
## Reference docs (read on demand)
|
|
|
|
- **Architecture, workflows, project-directory contract, state, terminology:** `docs/architecture.md`
|
|
- **Quality infrastructure (`lib/` validators, parsers, autonomy primitives, hooks):** `docs/architecture.md` §Quality infrastructure
|
|
- **Autonomy gates (`--gates`), Path A/B/C decision:** `docs/operations.md`
|
|
- **Profile system (`--profile economy/balanced/premium`), 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`
|