Kjell Tore Guttormsen
219e40cd91
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>
60 lines
2.3 KiB
Markdown
60 lines
2.3 KiB
Markdown
# 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
|