feat(execute): one fresh helper per step, a controller on the diff, proof by command

/trekexecute no longer builds steps itself. Each plan step is built by one
fresh helper (new agent step-implementer: opus, effort high, no Agent tool)
and judged by one controller (a general helper on opus) that reads the
diff from a recorded start_sha and gives two verdicts, spec and quality.
Fix rounds go up, maximum 5: three fixes by a fresh helper, then back to
the plan, then to the operator. No cheaper-model ladder.

Proof is a command, never the model's word:
- lib/verification/red-proof.mjs: the step's test must fail at the start
  point and pass at the result (exit 0/1/2; 2 is never green). Reproduces
  the 02243c6 red-first measurement (6 of 55) through the shim fixture.
- lib/verification/test-integrity.mjs: the floor guard on the diff
  (removed asserts, skipped/deleted tests, muted checks, stubs, loosened
  thresholds). Over the last 150 commits: 149 clean, 1 real finding.
- lib/verification/done-line.mjs: DONE step N only when the test command
  exits 0.

Test first is required from plan_version 1.8. The test lock (K8) is used
through its CLI and reported as not-locked while it is missing. A run
stops only on a closed list of four classes; every other call goes into a
decision log with its cost if wrong. Without a passing run-the-thing
criterion the result is not verified end to end, never green.

Handover 5 gains optional per-step start_sha, report_path, red_proof,
test_lock, fix_rounds (0-5) and run-level decisions and end_to_end; old
progress files still validate and resume.

No isolation on the helper: measured, a worktree-isolated subagent
branches from the default branch (02f320f), not the executor's HEAD
(2c89a6b), so it would miss the earlier steps.

Borrowings credited in commands/trekexecute.md ## Credits (Superpowers,
ai-native-sdlc, Kiro, GitHub Spec Kit, agent-skills, Cherny).

Tests: 1411 -> 1457 (1455 pass, 0 fail, 2 skipped).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-06 19:58:18 +02:00

2.4 KiB

Raw Blame History

Contributing to trekplan

This is a solo project. Issues are welcome. PRs may be considered but are not expected.

Reporting bugs

Open an issue with:

Plugin version (from .claude-plugin/plugin.json)
Claude Code version
What you did, what you expected, what happened instead
Whether it fails consistently or occasionally

Suggesting features or improvements

Open an issue describing:

The problem you ran into
What you think would solve it
Any alternatives you considered

Design principles

Changes to this plugin must preserve:

Pure markdown — no scripts, no dependencies, no platform-specific code
Cross-platform — must work identically on Mac, Linux, and Windows
Cost-aware — Sonnet for exploration, Opus only for planning
Privacy-first — never read files outside the repo, never log secrets
Honest — if a task is trivial, say so instead of inflating the plan

Architecture

File	Purpose
`.claude-plugin/plugin.json`	Plugin manifest
`commands/trekresearch.md`	The `/trekresearch` slash command — research orchestration
`commands/trekplan.md`	The `/trekplan` slash command — planning orchestration
`commands/trekexecute.md`	The `/trekexecute` slash command — execution orchestration
`agents/*.md`	24 agent files (21 spawnable + 3 orchestrator reference docs) for research, exploration, review, execution, and orchestration
`templates/plan-template.md`	Structured plan output format
`templates/research-brief-template.md`	Research brief format with triangulation and confidence
`templates/spec-template.md`	Spec file format
`templates/session-spec-template.md`	Session spec format for a session the user opens

The command files are the core. All logic lives in markdown.

Testing locally

Start a Claude Code session yourself with this checkout loaded as a local plugin (Claude Code's plugin-directory option; see its plugin docs). Voyage never starts a session for you. Then, in that session:

/trekresearch <research question>
/trekplan <describe a task>
/trekexecute <path to plan>

Verify:

/trekresearch: Research agents spawn, brief written to .claude/research/
/trekplan: Exploration agents spawn in parallel, plan follows template, plan written to .claude/plans/, adversarial review runs
/trekexecute: Steps execute with verify + checkpoint per step

2.4 KiB Raw Blame History