feat(execute)!: hand waves over as session orders, never start Claude Code (green)

Operator decision 27.09.2026: Voyage works the PM way, so nothing in it
starts Claude Code. Work that needs another session becomes an order plus
a starter line the user gives a session they open themselves; Voyage
never starts the session.

/trekexecute's multi-session path (Phase 2.6) now prepares one wave at a
time: worktree per session, then lib/util/session-orders.mjs writes one
order per session (worktree, steps, done-condition, starter) plus
orders/wave.json, and the run stops. Running the same command again reads
each session's progress file (status mode), merges sequentially with
push-before-cleanup as before, and prepares the next wave. Phase 2.5 skips
the destructive pre-flight while a wave is in flight. Phase 7.6 recovery is
handed over the same way. Hard rule 21: never start Claude Code.

Removed with it, because they existed only for launched children: the
ANTHROPIC_API_KEY billing check (and its dry-run line and Hard rule 1
exception), the hooks-fire version precheck, the safety preamble, the
scoped-tool/turn/budget flags, templates/headless-launch-template.md, the
decomposer's launch.sh (now orders.md), /trekplan's "launch", the README
billing and MCP tuning sections, and scripts/q3-cache-prefix-experiment.mjs
(an experiment that spawned the binary; its results stay in docs/).
/trekresearch's deep-research pre-gate no longer runs the binary for its
version; the post-hoc check was already the authoritative guard.

Chose orders + starters over in-session subagents because the order's done
criterion asks for exactly that, and because /trekexecute disallows the
Agent tool on purpose (Hard rule 10); reopening that is a separate change.

Gate: 54 -> 0 hit lines outside EXEMPT. npm test 1250 (1245 pass, 0 fail,
5 skipped: 3 are the retired-reference scan without its local list).
verify.sh 7/0. The fixture run (tests/lib/session-orders.test.mjs) writes
two orders and wave.json for wave 1 and leaves a trap binary untouched.

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

2026-09-27 15:35:22 +02:00

2.3 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`	19 specialized agents for research, exploration, review, 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 headless execution

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.3 KiB Raw Blame History