Kjell Tore Guttormsen
abc3083c1e
/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 the02243c6red-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>
60 lines
2.4 KiB
Markdown
60 lines
2.4 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` | 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
|