open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

feat(voyage)!: bulk content rewrite ultra -> voyage/trek prose [skip-docs]

Browse source 
Sed-pipeline (16 patterns, longest-match-first) sweeper residuelle ultra*-treff
i prose, command-narrativ, agent-prompts, hook-kommentarer, doc-prosa.

Pipeline-utvidelser fra V4-prompten:
- BSD-syntax [[:<:]]ultra[[:>:]] istedenfor \bultra\b (BSD sed mangler \b)
- 6 compound-patterns for ultraplan/ultraexecute/ultraresearch/ultrabrief/
  ultrareview/ultracontinue uten -local-suffiks
- ultra*-stats glob -> trek*-stats glob
- Linje-eksklusjon redusert til ultra-cc-architect (Q8); session-state-
  eksklusjonen var over-protektiv
- File-eksklusjon utvidet til settings.json, package.json, plugin.json,
  hele .claude/-treet (gitignored + V5-territorium)

Q8-undantak holdt: architecture-discovery.mjs + project-discovery.mjs urort.
Filnavn-konvensjon holdt: .session-state.local.json + *.local.* preservert.

Manuell narrative-fix: tests/lib/agent-frontmatter.test.mjs linje 10
mangled "/ultra*-local" til "/voyage*-local" (ingen slik kommando finnes);
korrigert til "/trek*".

Residualer utenfor scope (V5 handterer): package.json + .claude-plugin/
plugin.json (Step 12-14 versjons-bump). .claude/* er gitignored
spec-historikk med tilsiktet BEFORE/AFTER-narrativ.

Part of voyage-rebrand session 3 (Wave 4 / Step 10).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-05-05 15:08:20 +02:00
commit 14ecda886c
81 changed files with 672 additions and 672 deletions
Download patch file Download diff file Expand all files Collapse all files

80
plugins/ultraplan-local/CLAUDE.md
View file

@ -1,4 +1,4 @@
# ultraplan-local
# 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.
@ -18,7 +18,7 @@ Voyage — a contract-driven Claude Code pipeline: brief, research, plan, execut
| `/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 | sonnet |
### /ultrabrief-local modes
### /trekbrief modes
| Flag | Behavior |
|------|----------|
@ -28,7 +28,7 @@ Voyage — a contract-driven Claude Code pipeline: brief, research, plan, execut
Always interactive. Phase 3 is a section-driven completeness loop (no hard cap on question count); Phase 4 runs a `brief-reviewer` stop-gate with max 3 review iterations. After writing the brief, asks the user to choose manual (print commands) or auto (Claude runs research + plan in foreground).
### /ultraresearch-local modes
### /trekresearch modes
| Flag | Behavior |
|------|----------|
@ -42,12 +42,12 @@ Always interactive. Phase 3 is a section-driven completeness loop (no hard cap o
Flags combine: `--project <dir> --local`, `--external --quick`.
### /ultraplan-local modes
### /trekplan modes
| Flag | Behavior |
|------|----------|
| `--project <dir>` | **Required path A** — read `{dir}/brief.md`, auto-discover `{dir}/research/*.md`, write `{dir}/plan.md` |
| `--brief <path>` | **Required path B** — plan from a specific brief file; write to `.claude/plans/ultraplan-{date}-{slug}.md` |
| `--brief <path>` | **Required path B** — plan from a specific brief file; write to `.claude/plans/trekplan-{date}-{slug}.md` |
| `--research <brief> [brief2]` | Enrich with extra research briefs beyond what is in `{project_dir}/research/` |
| `--fg` | No-op alias (foreground is default since v2.4.0) |
| `--quick` | Plan directly (no agent swarm) |
@ -55,11 +55,11 @@ Flags combine: `--project <dir> --local`, `--external --quick`.
| `--decompose <plan>` | Split plan into self-contained headless sessions |
| `--gates {open\|closed\|adaptive}` | (v3.4.0) Autonomy-checkpoint policy. Default `adaptive` |
**Breaking change (v2.0):** one of `--brief` or `--project` is required. There is no interview inside `/ultraplan-local`. The `--spec` flag has been removed — use `/ultrabrief-local` to produce a brief instead.
**Breaking change (v2.0):** one of `--brief` or `--project` is required. There is no interview inside `/trekplan`. The `--spec` flag has been removed — use `/trekbrief` to produce a brief instead.
If `{project_dir}/architecture/overview.md` exists (typically produced by an opt-in upstream architect plugin, not bundled), the plan command auto-discovers it and treats `cc_features_proposed` as priors. Missing file is fine — discovery is additive, not required.
### /ultraexecute-local modes
### /trekexecute modes
| Flag | Behavior |
|------|----------|
@ -73,12 +73,12 @@ If `{project_dir}/architecture/overview.md` exists (typically produced by an opt
| `--session N` | Execute only session N from plan's Execution Strategy |
| `--gates {open\|closed\|adaptive}` | (v3.4.0) Autonomy-checkpoint policy. Default `adaptive` |
### /ultrareview-local modes
### /trekreview modes
| Flag | Behavior |
|------|----------|
| _(default)_ | Run brief-conformance + code-correctness reviewers in parallel, coordinator dedup + verdict, write `{project_dir}/review.md` |
| `--project <dir>` | **Required.** Path to ultraplan-local project folder containing `brief.md`. Review is written to `{dir}/review.md` |
| `--project <dir>` | **Required.** Path to trekplan project folder containing `brief.md`. Review is written to `{dir}/review.md` |
| `--since <ref>` | Override "before" SHA for the diff range. Validated via `git rev-parse --verify` |
| `--quick` | Skip brief-conformance reviewer; skip coordinator's reasonableness filter — fast correctness-only pass |
| `--validate` | Schema-only check on existing `{dir}/review.md`. No LLM calls |
@ -127,10 +127,10 @@ The triage gate is deterministic — path-pattern classifier produces `{file →
- `lib/validators/architecture-discovery.mjs` — drift-WARN external-contract discovery for `architecture/overview.md`
Wiring points (replaces previous prose-grep instructions):
- `/ultrabrief-local` Phase 4g → `brief-validator` (post-write sanity check)
- `/ultraplan-local` Phase 1 → `brief-validator --soft`, `research-validator --dir`, `architecture-discovery`
- `/trekbrief` Phase 4g → `brief-validator` (post-write sanity check)
- `/trekplan` Phase 1 → `brief-validator --soft`, `research-validator --dir`, `architecture-discovery`
- `planning-orchestrator` Phase 5.5 → `plan-validator --strict` (replaces 3 `grep -cE` calls)
- `/ultraexecute-local --validate` → `plan-validator --strict` + `progress-validator`
- `/trekexecute --validate` → `plan-validator --strict` + `progress-validator`
Tests under `tests/**/*.test.mjs` (~290 tests, 0 deps). `npm test` is the fork-readiness gate. v3.4.0 adds: synthetic determinism fixtures (`tests/synthetic/plan-run-*.md` + `review-run-*.md` + companion `*-determinism.test.mjs` enforcing Jaccard ≥ 0.833 SC7 floor) and hook baseline regression pins (`tests/hooks/{path-guard,bash-guard}.test.mjs` exercising `pre-write-executor.mjs` + `pre-bash-executor.mjs` denylist BLOCK paths).
@ -138,13 +138,13 @@ Doc-consistency test at `tests/lib/doc-consistency.test.mjs` pins agent-table co
`docs/HANDOVER-CONTRACTS.md` is the single source of truth for the 7 pipeline handovers (brief→research, research→plan, architecture→plan EXTERNAL, plan→execute, progress.json resume, review→plan, `.session-state.local.json`). Read it before changing any artifact format.
`hooks/scripts/pre-compact-flush.mjs` (PreCompact event, CC v2.1.105+) fixes the documented P0 in `docs/ultraexecute-v2-observations-from-config-audit-v4.md`: keeps `progress.json` in sync with git history before context compaction so `--resume` works after long conversations. Atomic write, monotonic only, never blocks compaction.
`hooks/scripts/pre-compact-flush.mjs` (PreCompact event, CC v2.1.105+) fixes the documented P0 in `docs/trekexecute-v2-observations-from-config-audit-v4.md`: keeps `progress.json` in sync with git history before context compaction so `--resume` works after long conversations. Atomic write, monotonic only, never blocks compaction.
`hooks/scripts/session-title.mjs` (UserPromptSubmit, CC v2.1.94+) sets `sessionTitle` to `ultra:<command>:<slug>` for ultra-command invocations. Helps multi-session headless runs identify themselves in process lists.
`hooks/scripts/session-title.mjs` (UserPromptSubmit, CC v2.1.94+) sets `sessionTitle` to `voyage:<command>:<slug>` for voyage-command invocations. Helps multi-session headless runs identify themselves in process lists.
`hooks/scripts/post-bash-stats.mjs` (PostToolUse, CC v2.1.97+) appends `duration_ms` for each Bash call into `${CLAUDE_PLUGIN_DATA}/trekexecute-stats.jsonl`. Useful for finding long-running verify or checkpoint commands.
`hooks/scripts/post-compact-flush.mjs` (PostCompact event, v3.4.0) re-injects `.session-state.local.json` after context compaction so multi-session work survives a compaction boundary. Companion to `pre-compact-flush.mjs` (which writes the state file before compaction); together they form the rehydrate cycle that keeps `/ultracontinue-local` reliable across long-running multi-session work.
`hooks/scripts/post-compact-flush.mjs` (PostCompact event, v3.4.0) re-injects `.session-state.local.json` after context compaction so multi-session work survives a compaction boundary. Companion to `pre-compact-flush.mjs` (which writes the state file before compaction); together they form the rehydrate cycle that keeps `/trekcontinue` reliable across long-running multi-session work.
## Autonomy mode (`--gates`, v3.4.0)
@ -156,14 +156,14 @@ All four pipeline commands accept `--gates {open|closed|adaptive}`:
| `closed` | Stop at every autonomy boundary; operator confirms each transition |
| `adaptive` (default) | Stop only at meaningful boundaries (manifest-audit FAIL, plan-critic BLOCKER, main-merge gate) |
Under the hood: `lib/util/autonomy-gate.mjs` runs the state machine `idle → approved → executing → merge-pending → main-merged`. `lib/stats/event-emit.mjs` records each transition to `${CLAUDE_PLUGIN_DATA}/ultra*-stats.jsonl`. The main-merge gate is the final autonomy boundary before HEAD lands on `main`.
Under the hood: `lib/util/autonomy-gate.mjs` runs the state machine `idle → approved → executing → merge-pending → main-merged`. `lib/stats/event-emit.mjs` records each transition to `${CLAUDE_PLUGIN_DATA}/trek*-stats.jsonl`. The main-merge gate is the final autonomy boundary before HEAD lands on `main`.
### Path A/B/C decision (v3.4.0; Path C closed 2026-05-05)
Three architectural options were considered for the speedup work:
- **Path A — cache-first** (drop `--allowedTools` per child to recover cross-phase cache sharing): REJECTED. Inverts the security model; plugin hooks don't fire reliably in `claude -p` (research/06 GH #36071).
- **Path B — sequential `--no-ff` parallel waves with manifest-driven failure recovery**: CHOSEN. Ships in v3.4.0. Phase 2.6 of `/ultraexecute-local` runs the wave executor with hardenings for plugin-in-monorepo + gitignored-state topology.
- **Path B — sequential `--no-ff` parallel waves with manifest-driven failure recovery**: CHOSEN. Ships in v3.4.0. Phase 2.6 of `/trekexecute` runs the wave executor with hardenings for plugin-in-monorepo + gitignored-state topology.
- **Path C — hybrid (cache-warm sentinel + identical-tool parallel)**: **CLOSED 2026-05-05.** Q3 experiment measured median `cache_creation_input_tokens` = 163,903 across 3 fork-children at 186K parent context (CC v2.1.128, Sonnet 4.6). Master-plan thresholds: ≤ 1,500 POSITIVE / ≥ 3,500 NEGATIVE. Result is solidly NEGATIVE — `CLAUDE_CODE_FORK_SUBAGENT` does not preserve cache prefix across identical-tool children at our context size. Path C migration is deferred indefinitely; reassessment is appropriate when CC v2.2.xxx ships fork-cache-relevant features. Harness: `scripts/q3-cache-prefix-experiment.mjs`. Companion analyser: `lib/stats/cache-analyzer.mjs`.
A revived Path C (post-v2.2.xxx) would require: (1) re-architecting tool-list to be identical across all wave children, (2) cache-telemetry analysis confirming the new fork-cache behaviour holds, (3) prompt-level deny re-enablement to compensate for tool scoping rollback.
@ -178,25 +178,25 @@ A revived Path C (post-v2.2.xxx) would require: (1) re-architecting tool-list to
**Decompose:** Parse plan → Analyze step dependencies → Group into sessions → Identify parallel waves → Generate session specs + dependency graph + launch script.
**Execute:** Parse plan → Security scan (Phase 2.4) → Detect Execution Strategy → Single-session (step loop) or multi-session (parallel waves via `claude -p` with scoped `--allowedTools`) → Phase 7.5 manifest audit → Phase 7.6 bounded recovery (if partial) → Phase 8 atomically writes `progress.json` + `.session-state.local.json` (Handover 7) → Report. With `--project`, reads `{dir}/plan.md`. Phase 2.55 (pre-flight stop) and Phase 4 (entry-condition stop) also write `.session-state.local.json` so `/ultracontinue` can surface the stop and prompt for next steps.
**Execute:** Parse plan → Security scan (Phase 2.4) → Detect Execution Strategy → Single-session (step loop) or multi-session (parallel waves via `claude -p` with scoped `--allowedTools`) → Phase 7.5 manifest audit → Phase 7.6 bounded recovery (if partial) → Phase 8 atomically writes `progress.json` + `.session-state.local.json` (Handover 7) → Report. With `--project`, reads `{dir}/plan.md`. Phase 2.55 (pre-flight stop) and Phase 4 (entry-condition stop) also write `.session-state.local.json` so `/trekcontinue` can surface the stop and prompt for next steps.
**Continue:** `/ultracontinue-local` reads `{dir}/.session-state.local.json` (Handover 7), validates schema-v1 via `session-state-validator`, narrates a 3-line summary (project / next-session-label / brief-path), and immediately begins executing the next session. Auto-discovers active project state files under `.claude/projects/*/.session-state.local.json` if no explicit `<project-dir>` argument. Operator-invoked only — never auto-loaded via SessionStart. The `/ultraplan-end-session-local` helper is the informal-flow producer: writes the same state file for ad-hoc multi-session handovers that don't run through `/ultraexecute-local`.
**Continue:** `/trekcontinue` reads `{dir}/.session-state.local.json` (Handover 7), validates schema-v1 via `session-state-validator`, narrates a 3-line summary (project / next-session-label / brief-path), and immediately begins executing the next session. Auto-discovers active project state files under `.claude/projects/*/.session-state.local.json` if no explicit `<project-dir>` argument. Operator-invoked only — never auto-loaded via SessionStart. The `/trekendsession` helper is the informal-flow producer: writes the same state file for ad-hoc multi-session handovers that don't run through `/trekexecute`.
**Security:** 4-layer defense-in-depth: plugin hooks (pre-bash-executor, pre-write-executor), prompt-level denylist (works in headless sessions), pre-execution plan scan (Phase 2.4), scoped `--allowedTools` replacing `--dangerously-skip-permissions`. Hard Rules 14-16 enforce verify command security, repo-boundary writes, and sensitive path protection.
**Pipeline:** `/ultrabrief-local` produces the task brief. `/ultraresearch-local --project <dir>` fills in `{dir}/research/`. `/ultraplan-local --project <dir>` reads brief + research to produce `{dir}/plan.md` (and auto-discovers `{dir}/architecture/overview.md` if an opt-in upstream architect plugin produced one). `/ultraexecute-local --project <dir>` executes and writes `{dir}/progress.json`. All artifacts live in one project directory.
**Pipeline:** `/trekbrief` produces the task brief. `/trekresearch --project <dir>` fills in `{dir}/research/`. `/trekplan --project <dir>` reads brief + research to produce `{dir}/plan.md` (and auto-discovers `{dir}/architecture/overview.md` if an opt-in upstream architect plugin produced one). `/trekexecute --project <dir>` executes and writes `{dir}/progress.json`. All artifacts live in one project directory.
**Project-directory contract (v3.0.0):** ultraplan-local owns the directory layout below. The `architecture/` subdirectory is opt-in and produced by an opt-in upstream architect plugin (not bundled) — the architect plugin is no longer publicly distributed, but the `architecture/overview.md` slot remains available for any compatible producer.
**Project-directory contract (v3.0.0):** trekplan owns the directory layout below. The `architecture/` subdirectory is opt-in and produced by an opt-in upstream architect plugin (not bundled) — the architect plugin is no longer publicly distributed, but the `architecture/overview.md` slot remains available for any compatible producer.
```
.claude/projects/{YYYY-MM-DD}-{slug}/
brief.md ← ultrabrief-local writes; everyone reads
research/*.md ← ultraresearch-local writes; plan + architect read
brief.md ← trekbrief writes; everyone reads
research/*.md ← trekresearch writes; plan + architect read
architecture/ ← OPT-IN, owned by an opt-in upstream architect plugin (not bundled)
overview.md
gaps.md
plan.md ← ultraplan-local writes; ultraexecute reads
progress.json ← ultraexecute-local writes
plan.md ← trekplan writes; trekexecute reads
progress.json ← trekexecute writes
```
No code-level dependency between plugins — the contract is filesystem-level only.
@ -205,21 +205,21 @@ No code-level dependency between plugins — the contract is filesystem-level on
All artifacts in one project directory (default):
- Project root: `.claude/projects/{YYYY-MM-DD}-{slug}/`
- `brief.md` (task brief from `/ultrabrief-local`)
- `research/{NN}-{slug}.md` (research briefs from `/ultraresearch-local --project`)
- `brief.md` (task brief from `/trekbrief`)
- `research/{NN}-{slug}.md` (research briefs from `/trekresearch --project`)
- `architecture/overview.md` + `architecture/gaps.md` (opt-in, produced by an opt-in upstream architect plugin, not bundled)
- `plan.md` (from `/ultraplan-local --project`)
- `plan.md` (from `/trekplan --project`)
- `sessions/session-*.md` (from `--decompose`)
- `progress.json` (from `/ultraexecute-local --project`)
- `review.md` (from `/ultrareview-local --project`)
- `.session-state.local.json` (Handover 7 — gitignored via `*.local.json`; written by `/ultraexecute-local` Phase 8/2.55/4 or `/ultraplan-end-session-local`; read by `/ultracontinue`)
- `progress.json` (from `/trekexecute --project`)
- `review.md` (from `/trekreview --project`)
- `.session-state.local.json` (Handover 7 — gitignored via `*.local.json`; written by `/trekexecute` Phase 8/2.55/4 or `/trekendsession`; read by `/trekcontinue`)
Legacy paths (still work without `--project`):
- Research briefs: `.claude/research/ultraresearch-{date}-{slug}.md`
- Plans: `.claude/plans/ultraplan-{date}-{slug}.md`
- Sessions: `.claude/ultraplan-sessions/{slug}/session-*.md`
- Launch scripts: `.claude/ultraplan-sessions/{slug}/launch.sh`
- Progress: `{plan-dir}/.ultraexecute-progress-{slug}.json`
- Research briefs: `.claude/research/trekresearch-{date}-{slug}.md`
- Plans: `.claude/plans/trekplan-{date}-{slug}.md`
- Sessions: `.claude/trekplan-sessions/{slug}/session-*.md`
- Launch scripts: `.claude/trekplan-sessions/{slug}/launch.sh`
- Progress: `{plan-dir}/.trekexecute-progress-{slug}.json`
Stats:
- Brief stats: `${CLAUDE_PLUGIN_DATA}/trekbrief-stats.jsonl`
@ -230,10 +230,10 @@ Stats:
## Terminology
- **Task brief** — produced by `/ultrabrief-local`. Declares intent, goal, and research plan. Drives planning.
- **Research brief** — produced by `/ultraresearch-local`. Answers a specific research question. Feeds planning.
- **Task brief** — produced by `/trekbrief`. Declares intent, goal, and research plan. Drives planning.
- **Research brief** — produced by `/trekresearch`. Answers a specific research question. Feeds planning.
- **Architecture note** — opt-in, produced by an opt-in upstream architect plugin (not bundled; the architect plugin is no longer publicly distributed, but the `architecture/overview.md` filesystem slot remains available for any compatible producer). Proposes which Claude Code features fit the task with brief-anchored rationale + explicit gaps. When present, enriches planning.
- **Review** — produced by `/ultrareview-local`. Independent post-hoc review of delivered code against the task brief. **Handover 6 (review → plan)** routes BLOCKER + MAJOR findings into `/ultraplan-local --brief review.md` for a remediation plan. The plan's optional `source_findings:` frontmatter list is the audit trail back to the consumed findings. MINOR + SUGGESTION are skipped for v1.0 plan-input.
- **Session state** — `.session-state.local.json` per project. **Handover 7** — produced by any session-end mechanism (`/ultraexecute-local` Phase 8/2.55/4, `/ultraplan-end-session-local` helper, future graceful-handoff v2.2). Consumed by `/ultracontinue-local` to resume the next session in a fresh chat. Schema v1 is forward-compat (unknown top-level keys ignored). Never committed (gitignored via `*.local.json`).
- **Review** — produced by `/trekreview`. Independent post-hoc review of delivered code against the task brief. **Handover 6 (review → plan)** routes BLOCKER + MAJOR findings into `/trekplan --brief review.md` for a remediation plan. The plan's optional `source_findings:` frontmatter list is the audit trail back to the consumed findings. MINOR + SUGGESTION are skipped for v1.0 plan-input.
- **Session state** — `.session-state.local.json` per project. **Handover 7** — produced by any session-end mechanism (`/trekexecute` Phase 8/2.55/4, `/trekendsession` helper, future graceful-handoff v2.2). Consumed by `/trekcontinue` to resume the next session in a fresh chat. Schema v1 is forward-compat (unknown top-level keys ignored). Never committed (gitignored via `*.local.json`).
A project typically has 1 task brief, 0–N research briefs, 0 or 1 architecture note, 0–N reviews (one per review iteration), and 0 or 1 session-state file (overwritten on every session-end).

22
plugins/ultraplan-local/CONTRIBUTING.md
View file

@ -1,4 +1,4 @@
# Contributing to ultraplan-local
# Contributing to trekplan
This is a solo project. Issues are welcome. PRs may be considered but are not expected.
@ -31,9 +31,9 @@ Changes to this plugin must preserve:
| File | Purpose |
|------|---------|
| `.claude-plugin/plugin.json` | Plugin manifest |
| `commands/ultraresearch-local.md` | The `/ultraresearch-local` slash command — research orchestration |
| `commands/ultraplan-local.md` | The `/ultraplan-local` slash command — planning orchestration |
| `commands/ultraexecute-local.md` | The `/ultraexecute-local` slash command — execution orchestration |
| `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 |
@ -46,14 +46,14 @@ The command files are the core. All logic lives in markdown.
## Testing locally
```bash
claude --plugin-dir /path/to/ultraplan-local
claude --plugin-dir /path/to/trekplan
# Then in the session:
/ultraresearch-local <research question>
/ultraplan-local <describe a task>
/ultraexecute-local <path to plan>
/trekresearch <research question>
/trekplan <describe a task>
/trekexecute <path to plan>
```
Verify:
- `/ultraresearch-local`: Research agents spawn, brief written to `.claude/research/`
- `/ultraplan-local`: Exploration agents spawn in parallel, plan follows template, plan written to `.claude/plans/`, adversarial review runs
- `/ultraexecute-local`: Steps execute with verify + checkpoint per step
- `/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

176
plugins/ultraplan-local/README.md
View file

@ -1,4 +1,4 @@
# ultraplan-local — Brief, Research, Plan, Execute, Review, Continue
# trekplan — Brief, Research, Plan, Execute, Review, Continue
![Version](https://img.shields.io/badge/version-3.4.1-blue)
![License](https://img.shields.io/badge/license-MIT-green)
@ -29,15 +29,15 @@ Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{s
| `/trekresearch` | **Gather context** — code state, external docs, community, risk. Makes NO build decisions. | `research/NN-slug.md` (research brief) |
| `/trekplan` | **Transform intent into an executable contract** — per-step YAML manifest, regex-validated checkpoints, verifiable paths. Plan-critic is a hard gate. Auto-discovers `architecture/overview.md` as priors when an opt-in upstream architect plugin (not bundled) is installed. | `plan.md` with Manifest blocks + `plan_version: 1.7` |
| `/trekexecute` | **Execute the contract disciplined** — fresh verification, independent manifest audit, honest reporting. Does NOT compensate for weak plans — escalates. | `progress.json` + structured report + manifest-audit status |
| `/trekreview` | **Close the loop** — independent post-hoc reviewer reads `brief.md` and the diff produced by execute, runs brief-conformance + code-correctness reviewers in parallel, dedups via Judge Agent. Severity-tagged findings (Critical/High/Medium/Low/Info) feed back into planning via Handover 6. | `review.md` (`type: ultrareview`) with stable 40-char hex finding-IDs |
| `/trekreview` | **Close the loop** — independent post-hoc reviewer reads `brief.md` and the diff produced by execute, runs brief-conformance + code-correctness reviewers in parallel, dedups via Judge Agent. Severity-tagged findings (Critical/High/Medium/Low/Info) feed back into planning via Handover 6. | `review.md` (`type: trekreview`) with stable 40-char hex finding-IDs |
**Principle:** Each step consumes the previous step's structured artifact. If execute has to guess, the plan is weak and must be revised upstream — not patched downstream.
### Two kinds of briefs
Terminology matters:
- **Task brief** — produced by `/ultrabrief-local`. Captures *what we want and why*. Drives planning.
- **Research brief** — produced by `/ultraresearch-local`. Captures *what we learned about a topic*. Feeds planning.
- **Task brief** — produced by `/trekbrief`. Captures *what we want and why*. Drives planning.
- **Research brief** — produced by `/trekresearch`. Captures *what we learned about a topic*. Feeds planning.
A project typically has one task brief and zero-to-N research briefs.
@ -45,7 +45,7 @@ A project typically has one task brief and zero-to-N research briefs.
Every step in the plan ends with a YAML `manifest:` block declaring `expected_paths`, `commit_message_pattern`, `bash_syntax_check`, `forbidden_paths`, `must_contain`. The executor checks the manifest against the resulting commit — a step may not be marked passed if its manifest does not verify, regardless of the Verify command's exit code (Hard Rule 17).
After all steps complete, `/ultraexecute-local` runs **Phase 7.5 — Manifest audit (independent)**: re-verifies every expected path from git log + filesystem, ignoring the agent's own bookkeeping. Drift → status `partial`, **Phase 7.6** auto-dispatches a bounded recovery session with only the missing steps (`recovery_depth ≤ 2`). Step 0 pre-flight (`git push --dry-run`) runs inside every session sandbox before any real work — exit 77 sentinel catches sandbox push-denial before the agent wastes the whole budget.
After all steps complete, `/trekexecute` runs **Phase 7.5 — Manifest audit (independent)**: re-verifies every expected path from git log + filesystem, ignoring the agent's own bookkeeping. Drift → status `partial`, **Phase 7.6** auto-dispatches a bounded recovery session with only the missing steps (`recovery_depth ≤ 2`). Step 0 pre-flight (`git push --dry-run`) runs inside every session sandbox before any real work — exit 77 sentinel catches sandbox push-denial before the agent wastes the whole budget.
No cloud dependency. No GitHub requirement. Works on **Mac, Linux, and Windows**.
@ -59,7 +59,7 @@ All four pipeline commands accept `--gates {open|closed|adaptive}` to control ho
| `closed` | Stop at every checkpoint. The operator confirms each transition. Suitable for high-stakes work or unfamiliar repos. |
| `adaptive` (default) | Stop only when the autonomy-gate state machine reports a meaningful boundary (manifest-audit FAIL, plan-critic BLOCKER, main-merge gate). Best balance of velocity and safety. |
Under the hood, `lib/util/autonomy-gate.mjs` runs a small state machine (`idle → approved → executing → merge-pending → main-merged`) and `lib/stats/event-emit.mjs` records each transition to `${CLAUDE_PLUGIN_DATA}/ultra*-stats.jsonl`. The new `hooks/scripts/post-compact-flush.mjs` PostCompact hook re-injects `.session-state.local.json` after context compaction so multi-session work survives a compaction boundary.
Under the hood, `lib/util/autonomy-gate.mjs` runs a small state machine (`idle → approved → executing → merge-pending → main-merged`) and `lib/stats/event-emit.mjs` records each transition to `${CLAUDE_PLUGIN_DATA}/trek*-stats.jsonl`. The new `hooks/scripts/post-compact-flush.mjs` PostCompact hook re-injects `.session-state.local.json` after context compaction so multi-session work survives a compaction boundary.
## Quick start
@ -105,7 +105,7 @@ An optional architect step can sit between research and plan — `/trekplan` aut
- The task is a single-file change where the fix is obvious
- You already know exactly what to change and in what order
**Rule of thumb:** If you can describe the full implementation in one sentence and it touches 1-2 files, skip ultraplan and just implement. If you need to think about it, ultraplan earns its cost.
**Rule of thumb:** If you can describe the full implementation in one sentence and it touches 1-2 files, skip trekplan and just implement. If you need to think about it, trekplan earns its cost.
## What you get
@ -121,7 +121,7 @@ Concrete capabilities, observable in the code — not aspirations.
**Team (2–10).** Plan files are handover-ready — a colleague can pick up a project directory without re-asking "what did you mean here?". `--decompose` splits a plan into self-contained headless sessions with scoped `--allowedTools`. The plan-critic semantic rubric gives the team a shared definition of "this plan defers decisions to the executor".
**Virksomhet / regulated environment.** Defense-in-depth security across four layers (plugin hooks, prompt-level denylist, pre-execution plan scan, scoped tool access). `disableSkillShellExecution: true` recommendation for fork-ers handling untrusted briefs. No cloud dependency, no GitHub requirement. Validators are plain-Node CLIs — invocable from CI, custom hooks, or external tools, not just from ultra commands.
**Virksomhet / regulated environment.** Defense-in-depth security across four layers (plugin hooks, prompt-level denylist, pre-execution plan scan, scoped tool access). `disableSkillShellExecution: true` recommendation for fork-ers handling untrusted briefs. No cloud dependency, no GitHub requirement. Validators are plain-Node CLIs — invocable from CI, custom hooks, or external tools, not just from voyage commands.
**What it doesn't solve:**
- LLM output truthfulness. Validators check shape, not facts. A plan with hallucinated paths passes schema but fails in execute. Plan-critic catches some, not all.
@ -133,7 +133,7 @@ Concrete capabilities, observable in the code — not aspirations.
---
## `/ultrabrief-local` — Brief
## `/trekbrief` — Brief
Interactive requirements-gathering command. Runs a **dynamic, quality-gated interview** and produces a **task brief** with an explicit research plan. Optionally orchestrates the rest of the pipeline.
@ -148,7 +148,7 @@ Output: `.claude/projects/{YYYY-MM-DD}-{slug}/brief.md`
| **Default** | `/trekbrief <task>` | Dynamic interview until quality gates pass. No question cap. |
| **Quick** | `/trekbrief --quick <task>` | Starts compact (optional sections get at most one probe), still escalates on weak required sections or failed review gate. |
`/ultrabrief-local` is **always interactive**. There is no foreground/background mode — the interview requires user input.
`/trekbrief` is **always interactive**. There is no foreground/background mode — the interview requires user input.
### Force-stop
@ -163,13 +163,13 @@ If you say "stop" or "enough" during Phase 4, the current review findings are su
- **Non-Goals** — explicitly out of scope
- **Constraints / Preferences / NFRs** — technical, time, resource limits
- **Success Criteria** — 2-4 falsifiable commands/observations
- **Research Plan** — N topics, each with research question, scope (local/external/both), confidence needed, cost estimate, and a ready-to-run `/ultraresearch-local` command
- **Research Plan** — N topics, each with research question, scope (local/external/both), confidence needed, cost estimate, and a ready-to-run `/trekresearch` command
- **Open Questions / Assumptions** — from "I don't know" answers and implicit gaps
- **Prior Attempts** — what worked/failed before
---
## `/ultraresearch-local` — Research
## `/trekresearch` — Research
Deep, multi-phase research that combines local codebase analysis with external knowledge. Uses specialized agent swarms to investigate multiple dimensions in parallel, then triangulates findings.
@ -177,7 +177,7 @@ A parallel swarm of up to 5 local + 4 external Sonnet agents investigates 3–8
Output:
- With `--project <dir>`: `{dir}/research/{NN}-{slug}.md` (auto-incremented index)
- Without: `.claude/research/ultraresearch-{date}-{slug}.md`
- Without: `.claude/research/trekresearch-{date}-{slug}.md`
### Modes
@ -196,15 +196,15 @@ Research uses up to 5 local agents (architecture-mapper, dependency-tracer, task
---
## `/ultraplan-local` — Planning
## `/trekplan` — Planning
Produces an implementation plan detailed enough for autonomous execution. **v2.0 breaking change:** requires `--brief` or `--project`. There is no longer an interview inside `/ultraplan-local` — use `/ultrabrief-local` first.
Produces an implementation plan detailed enough for autonomous execution. **v2.0 breaking change:** requires `--brief` or `--project`. There is no longer an interview inside `/trekplan` — use `/trekbrief` first.
After `brief-reviewer` validates the input brief, 6–8 Sonnet exploration agents analyze the codebase in parallel and merge findings into a synthesis. Optional research briefs (`--research`, or auto-discovered in `{project_dir}/research/`) enrich the plan; `architecture/overview.md` priors are loaded if an opt-in upstream architect plugin (not bundled) produced one. Opus then writes the plan with per-step YAML manifests, which `plan-critic` (9 dimensions) and `scope-guardian` adversarially review before handoff.
Output:
- With `--project <dir>`: `{dir}/plan.md`
- With `--brief <path>`: `.claude/plans/ultraplan-{date}-{slug}.md`
- With `--brief <path>`: `.claude/plans/trekplan-{date}-{slug}.md`
### Modes
@ -218,7 +218,7 @@ Output:
| **Decompose** | `/trekplan --decompose plan.md` | Split plan into headless session specs |
| **Export** | `/trekplan --export pr plan.md` | PR description, issue comment, or clean markdown |
`--brief` or `--project` is **required**. `/ultraplan-local` with no brief exits with an error and a pointer to `/ultrabrief-local`.
`--brief` or `--project` is **required**. `/trekplan` with no brief exits with an error and a pointer to `/trekbrief`.
### What the plan contains
@ -246,9 +246,9 @@ Exploration uses 6–8 Sonnet agents in parallel (architecture-mapper, dependenc
---
## `/ultraexecute-local` — Execution
## `/trekexecute` — Execution
Reads a plan from `/ultraplan-local` and implements it with strict discipline. No guessing, no improvising — follows the plan exactly.
Reads a plan from `/trekplan` and implements it with strict discipline. No guessing, no improvising — follows the plan exactly.
Per step: apply Changes exactly as written → run Verify (exit code is truth) → manifest audit (expected paths, forbidden paths, commit pattern) → follow the plan's failure clause if anything fails (revert / retry / skip / escalate) → Checkpoint commit. After all steps: independent Phase 7.5 manifest audit from git log + filesystem (ignoring agent bookkeeping); drift triggers Phase 7.6 bounded recovery.
@ -267,7 +267,7 @@ Per step: apply Changes exactly as written → run Verify (exit code is truth)
### Session-aware parallel execution (worktree-isolated)
When a plan has an `## Execution Strategy` section (auto-generated by `/ultraplan-local` for plans with > 5 steps), `/ultraexecute-local` automatically:
When a plan has an `## Execution Strategy` section (auto-generated by `/trekplan` for plans with > 5 steps), `/trekexecute` automatically:
1. **Pre-flight checks** — validates clean working tree, plan file tracked in git, no scope fence overlaps between parallel sessions, no stale worktrees
2. **Creates git worktrees** — each parallel session gets its own isolated worktree and branch (`trek/{slug}/session-{N}`)
@ -290,7 +290,7 @@ Use `--fg` to force sequential execution even when a plan has an Execution Strat
### Billing safety
Before launching parallel `claude -p` sessions, `/ultraexecute-local` checks whether `ANTHROPIC_API_KEY` is set in your environment. If it is, parallel sessions will bill your **API account** (pay-per-token), not your Claude subscription (Max/Pro). This can be expensive — parallel Opus sessions can cost $50-100+ per run.
Before launching parallel `claude -p` sessions, `/trekexecute` checks whether `ANTHROPIC_API_KEY` is set in your environment. If it is, parallel sessions will bill your **API account** (pay-per-token), not your Claude subscription (Max/Pro). This can be expensive — parallel Opus sessions can cost $50-100+ per run.
When an API key is detected, you are asked how to proceed:
- **Use --fg instead** (recommended) — run sequentially in the current session using your subscription
@ -335,11 +335,11 @@ prompt-injection vector that the plugin's own hooks cannot fully mitigate
### Headless execution
`/ultraexecute-local` is designed for `claude -p` headless sessions:
`/trekexecute` is designed for `claude -p` headless sessions:
- **No questions asked** — all recovery decisions come from the plan
- **Progress file** — crash recovery via `{project_dir}/progress.json` (or `.ultraexecute-progress-{slug}.json` for legacy plans)
- **Progress file** — crash recovery via `{project_dir}/progress.json` (or `.trekexecute-progress-{slug}.json` for legacy plans)
- **Scope fence enforcement** — never touches files outside the session's scope
- **JSON summary** — machine-parseable `ultraexecute_summary` block for log parsing
- **JSON summary** — machine-parseable `trekexecute_summary` block for log parsing
#### Headless multi-session tuning (CC v2.1.89+)
@ -357,18 +357,18 @@ Without this, each child session can spend 1-3 s blocking on MCP
connect, multiplying across waves. Setting it lets MCP connect lazily
on first tool call.
### Session titles for ultra commands (CC v2.1.94+)
### Session titles for voyage commands (CC v2.1.94+)
A `UserPromptSubmit` hook (`hooks/scripts/session-title.mjs`) sets the
session title to `ultra:<command>:<slug>` whenever you invoke one of
the four ultra commands. This makes multi-session headless runs and
session title to `voyage:<command>:<slug>` whenever you invoke one of
the four voyage commands. This makes multi-session headless runs and
session-picker output trivially identifiable. Slug derivation:
| Invocation | Session title |
|-----------|---------------|
| `/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth` | `ultra:plan:jwt-auth` |
| `/ultrabrief-local --quick` | `ultra:brief:ad-hoc` |
| `/ultraexecute-local --project .claude/projects/2026-05-10-cleanup --resume` | `ultra:execute:cleanup` |
| `/trekplan --project .claude/projects/2026-04-18-jwt-auth` | `voyage:plan:jwt-auth` |
| `/trekbrief --quick` | `voyage:brief:ad-hoc` |
| `/trekexecute --project .claude/projects/2026-05-10-cleanup --resume` | `voyage:execute:cleanup` |
The hook is fail-open — any error → title is left untouched.
@ -376,19 +376,19 @@ The hook is fail-open — any error → title is left untouched.
A `PostToolUse` hook (`hooks/scripts/post-bash-stats.mjs`) appends
`duration_ms` from each Bash tool call to
`${CLAUDE_PLUGIN_DATA}/ultraexecute-stats.jsonl`. One line per Bash
`${CLAUDE_PLUGIN_DATA}/trekexecute-stats.jsonl`. One line per Bash
call; useful for identifying long-running verify or checkpoint commands
across executions.
---
## `/ultrareview-local` — Review
## `/trekreview` — Review
Independent post-hoc review of delivered code against the brief. Reads `brief.md`
from scratch and treats research/plan as supplementary context. The output
`review.md` is a new artifact type (`type: ultrareview`) with its own validator
`review.md` is a new artifact type (`type: trekreview`) with its own validator
and a contracted **Handover 6 (review → plan)** so findings can be fed back into
`/ultraplan-local --brief review.md` to produce a remediation plan — closing
`/trekplan --brief review.md` to produce a remediation plan — closing
the iteration loop without ad-hoc conventions.
### Modes
@ -431,17 +431,17 @@ The plan's optional `source_findings:` frontmatter list is the audit trail back
---
## `/ultracontinue-local` — Resume
## `/trekcontinue` — Resume
Zero-friction multi-session resumption. Type `/ultracontinue` in a fresh
Zero-friction multi-session resumption. Type `/trekcontinue` in a fresh
Claude Code session — the command reads the per-project state file
(`.claude/projects/<project>/.session-state.local.json`), prints a 3-line
summary, and immediately begins executing the next session.
The state file is the contract — any session-end mechanism may write it
(`/ultraexecute-local` Phase 8 / Phase 2.55 / Phase 4 do so automatically;
the `/ultraplan-end-session-local` helper writes it for informal flows;
`graceful-handoff` may converge on it in a future release). `/ultracontinue`
(`/trekexecute` Phase 8 / Phase 2.55 / Phase 4 do so automatically;
the `/trekendsession` helper writes it for informal flows;
`graceful-handoff` may converge on it in a future release). `/trekcontinue`
only reads. See **Handover 7** in `docs/HANDOVER-CONTRACTS.md` for the full
schema and producer/consumer contract.
@ -449,9 +449,9 @@ schema and producer/consumer contract.
| Mode | Command | Description |
|------|---------|-------------|
| **Default** | `/ultracontinue` | Auto-discover `.session-state.local.json` under cwd, validate, narrate, and begin executing the next session |
| **Explicit** | `/ultracontinue <project-dir>` | Use the named project directory; helpful when several active projects coexist under cwd |
| **Help** | `/ultracontinue --help` | Print usage block and the schema-v1 reference |
| **Default** | `/trekcontinue` | Auto-discover `.session-state.local.json` under cwd, validate, narrate, and begin executing the next session |
| **Explicit** | `/trekcontinue <project-dir>` | Use the named project directory; helpful when several active projects coexist under cwd |
| **Help** | `/trekcontinue --help` | Print usage block and the schema-v1 reference |
### Schema v1 — `.session-state.local.json`
@ -466,16 +466,16 @@ schema and producer/consumer contract.
Forward-compat: unknown top-level keys are ignored (no errors, no warnings) — the same drift-WARN principle as Handover 3, so future producers (e.g. graceful-handoff v2.2) can extend the schema additively.
### `/ultraplan-end-session-local` helper
### `/trekendsession` helper
For informal multi-session flows that don't run through `/ultraexecute-local`
For informal multi-session flows that don't run through `/trekexecute`
(ad-hoc release runs, manual handovers), use the helper to write the state
file at session-end:
```bash
/ultraplan-end-session-local .claude/projects/2026-05-01-feature/brief.md "Session 2 of 3"
/trekendsession .claude/projects/2026-05-01-feature/brief.md "Session 2 of 3"
# Writes .session-state.local.json with status=in_progress.
# Then in a fresh chat: /ultracontinue
# Then in a fresh chat: /trekcontinue
```
Both arguments are required. No interactive prompt — headless-safe.
@ -484,12 +484,12 @@ Both arguments are required. No interactive prompt — headless-safe.
```bash
# Session 1 (long-running formal pipeline)
/ultraplan-local --project .claude/projects/2026-05-01-feature
/ultraexecute-local --project .claude/projects/2026-05-01-feature
# ... ultraexecute Phase 8 writes .session-state.local.json on session-end ...
/trekplan --project .claude/projects/2026-05-01-feature
/trekexecute --project .claude/projects/2026-05-01-feature
# ... trekexecute Phase 8 writes .session-state.local.json on session-end ...
# (chat boundary — fresh Claude Code session)
/ultracontinue
/trekcontinue
# → reads state, prints 3-line summary, begins next session
```
@ -498,7 +498,7 @@ Both arguments are required. No interactive prompt — headless-safe.
## The full pipeline
```
/ultrabrief-local /ultraresearch-local /ultraplan-local /ultraexecute-local
/trekbrief /trekresearch /trekplan /trekexecute
┌──────────────┐ ┌───────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
│ Interview │ │ 5 local agents │ │ brief-reviewer │ │ Parse plan │
│ ↓ │ │ 4 external agents │ │ ↓ │ │ ↓ │
@ -517,69 +517,69 @@ Both arguments are required. No interactive prompt — headless-safe.
All artifacts live under `.claude/projects/{YYYY-MM-DD}-{slug}/`.
An opt-in upstream architect plugin (not bundled) can insert a Claude-Code-specific architecture-matching step between research and plan — `/ultraplan-local` auto-discovers its `architecture/overview.md` output as priors when present.
An opt-in upstream architect plugin (not bundled) can insert a Claude-Code-specific architecture-matching step between research and plan — `/trekplan` auto-discovers its `architecture/overview.md` output as priors when present.
### Example workflows
**Standard pipeline (manual control):**
```bash
/ultrabrief-local Add session caching with Redis
/trekbrief Add session caching with Redis
# → .claude/projects/2026-04-18-redis-session-caching/brief.md
# Interview identifies 2 research topics.
/ultraresearch-local --project .claude/projects/2026-04-18-redis-session-caching --external "What are Redis session-caching best practices?"
/ultraresearch-local --project .claude/projects/2026-04-18-redis-session-caching --local "How is caching currently handled in the codebase?"
/trekresearch --project .claude/projects/2026-04-18-redis-session-caching --external "What are Redis session-caching best practices?"
/trekresearch --project .claude/projects/2026-04-18-redis-session-caching --local "How is caching currently handled in the codebase?"
# → .claude/projects/2026-04-18-redis-session-caching/research/01-*.md, 02-*.md
/ultraplan-local --project .claude/projects/2026-04-18-redis-session-caching
/trekplan --project .claude/projects/2026-04-18-redis-session-caching
# → .claude/projects/2026-04-18-redis-session-caching/plan.md
/ultraexecute-local --project .claude/projects/2026-04-18-redis-session-caching
/trekexecute --project .claude/projects/2026-04-18-redis-session-caching
# → progress.json + code changes
```
**Auto-mode (Claude manages the pipeline):**
```bash
/ultrabrief-local Add session caching with Redis
/trekbrief Add session caching with Redis
# Interview identifies topics. Choose "Auto (managed by Claude Code)" when asked.
# Claude runs research in parallel, then planning in foreground.
# Returns when plan.md is ready.
/ultraexecute-local --project .claude/projects/2026-04-18-redis-session-caching
/trekexecute --project .claude/projects/2026-04-18-redis-session-caching
```
**Standalone research (no planning):**
```bash
/ultraresearch-local What are the security implications of using JWT for session management?
/trekresearch What are the security implications of using JWT for session management?
# Read the brief, share with team, use for decision-making.
```
**Quick plan for small tasks:**
```bash
/ultrabrief-local --quick Fix the login redirect bug
/ultraplan-local --project .claude/projects/2026-04-18-login-redirect-fix --quick
/ultraexecute-local --project .claude/projects/2026-04-18-login-redirect-fix
/trekbrief --quick Fix the login redirect bug
/trekplan --project .claude/projects/2026-04-18-login-redirect-fix --quick
/trekexecute --project .claude/projects/2026-04-18-login-redirect-fix
```
**Dry run + validate before executing:**
```bash
/ultraexecute-local --project <dir> --validate # schema check, no execution
/ultraexecute-local --project <dir> --dry-run # preview sessions and billing
/ultraexecute-local --project <dir> # execute
/trekexecute --project <dir> --validate # schema check, no execution
/trekexecute --project <dir> --dry-run # preview sessions and billing
/trekexecute --project <dir> # execute
```
**Review feedback loop (Handover 6):**
```bash
/ultrareview-local --project <dir>
/trekreview --project <dir>
# → review.md with severity-tagged findings + verdict (BLOCK / WARN / ALLOW)
# If verdict is BLOCK or WARN, feed findings back into a remediation plan:
/ultraplan-local --brief <dir>/review.md
/trekplan --brief <dir>/review.md
# → plan.md with source_findings: [<id>, ...] audit trail
/ultraexecute-local --project <dir> # execute the remediation plan
/trekexecute --project <dir> # execute the remediation plan
/ultrareview-local --project <dir> # re-review (overwrites review.md)
/trekreview --project <dir> # re-review (overwrites review.md)
```
---
@ -593,7 +593,7 @@ Migration notes for breaking changes (v1.x → v2.0, v2.x → v3.0) live in [CHA
The plugin ships with `node:test`-based unit tests and a `lib/` directory of pure-JS validators wired into the commands. Forking the plugin for internal use? Run `npm test` to confirm the parsers, validators, and doc-consistency invariants still hold:
```bash
cd plugins/ultraplan-local
cd plugins/trekplan
npm test # runs all tests under tests/**/*.test.mjs
```
@ -619,11 +619,11 @@ Borrowed pattern from `llm-security` (commit `97c5c9d`); extending the plugin sh
### PreCompact resume integrity (CC v2.1.105+)
The `pre-compact-flush.mjs` hook directly fixes the documented P0 in `docs/ultraexecute-v2-observations-from-config-audit-v4.md`: in skill-driven execution, `progress.json` could fall behind git reality before context compaction, breaking `/ultraexecute-local --resume` after long conversations. The hook fires on every PreCompact event, locates any `progress.json` under `.claude/projects/`, compares stored `current_step` against `git log --oneline {session_start_sha}..HEAD`, and atomically writes a fresh checkpoint (`tmp + rename`, monotonic only) when git is ahead. Never blocks compaction.
The `pre-compact-flush.mjs` hook directly fixes the documented P0 in `docs/trekexecute-v2-observations-from-config-audit-v4.md`: in skill-driven execution, `progress.json` could fall behind git reality before context compaction, breaking `/trekexecute --resume` after long conversations. The hook fires on every PreCompact event, locates any `progress.json` under `.claude/projects/`, compares stored `current_step` against `git log --oneline {session_start_sha}..HEAD`, and atomically writes a fresh checkpoint (`tmp + rename`, monotonic only) when git is ahead. Never blocks compaction.
## Known limitations
**Infrastructure-as-code (IaC) gets reduced value.** The exploration agents are designed for application code. Terraform, Helm, Pulumi, CDK projects will get a plan, but agents like `architecture-mapper` and `test-strategist` produce less useful output for IaC. Use ultraplan-local for the structural plan, then supplement IaC-specific steps manually.
**Infrastructure-as-code (IaC) gets reduced value.** The exploration agents are designed for application code. Terraform, Helm, Pulumi, CDK projects will get a plan, but agents like `architecture-mapper` and `test-strategist` produce less useful output for IaC. Use trekplan for the structural plan, then supplement IaC-specific steps manually.
## Installation
@ -638,16 +638,16 @@ Or enable directly in `~/.claude/settings.json`:
```json
{
"enabledPlugins": {
"ultraplan-local@ktg-plugin-marketplace": true
"trekplan@ktg-plugin-marketplace": true
}
}
```
An optional architect step between research and plan was previously available via a separate plugin; that architect plugin is no longer publicly distributed. The `architecture/overview.md` filesystem slot remains supported by `/ultraplan-local` for any compatible producer.
An optional architect step between research and plan was previously available via a separate plugin; that architect plugin is no longer publicly distributed. The `architecture/overview.md` filesystem slot remains supported by `/trekplan` for any compatible producer.
## Cost profile
Opus runs the orchestrators (one per command) and the executor (one per plan session). Sonnet runs the exploration and review swarms (5–10 agents per command, with effort/turn limits). The pipeline front-loads cheap Sonnet work so Opus only does synthesis and execution. Typical total: comparable to a long single Claude Code session — the per-command cost is published in `${CLAUDE_PLUGIN_DATA}/ultra*-stats.jsonl` if you want exact numbers.
Opus runs the orchestrators (one per command) and the executor (one per plan session). Sonnet runs the exploration and review swarms (5–10 agents per command, with effort/turn limits). The pipeline front-loads cheap Sonnet work so Opus only does synthesis and execution. Typical total: comparable to a long single Claude Code session — the per-command cost is published in `${CLAUDE_PLUGIN_DATA}/trek*-stats.jsonl` if you want exact numbers.
## Requirements
@ -661,9 +661,9 @@ Opus runs the orchestrators (one per command) and the executor (one per plan ses
Top-level layout:
```
ultraplan-local/
trekplan/
├── agents/ 23 specialized agents (sonnet for exploration + review, opus for orchestration)
├── commands/ 6 slash commands (ultrabrief, ultraresearch, ultraplan, ultraexecute, ultrareview, ultracontinue) + ultraplan-end-session helper
├── commands/ 6 slash commands (trekbrief, trekresearch, trekplan, trekexecute, trekreview, trekcontinue) + trekplan-end-session helper
├── templates/ Frontmatter templates for brief, research, plan, session, launch
├── hooks/ 5 hooks (pre-bash, pre-write, session-title, post-bash-stats, pre-compact-flush)
├── lib/ Zero-dep parsers and validators (CLI shims under lib/validators/)
@ -681,7 +681,7 @@ all of these are surface-level changes to commands, agents, or settings.
### Add a new exploration agent
Exploration agents run in parallel during `/ultraplan-local` Phase 5.
Exploration agents run in parallel during `/trekplan` Phase 5.
They read the codebase and contribute structured findings to plan
synthesis.
@ -702,26 +702,26 @@ synthesis.
### Switch the planning model
The default for `/ultrabrief-local`, `/ultraresearch-local`,
`/ultraplan-local`, and `/ultraexecute-local` is `opus` (deep
The default for `/trekbrief`, `/trekresearch`,
`/trekplan`, and `/trekexecute` is `opus` (deep
reasoning). To run on Sonnet for cost or latency, search-and-replace
the frontmatter in three files:
```bash
sed -i.bak 's/^model: opus$/model: sonnet/' \
commands/ultrabrief-local.md \
commands/ultraresearch-local.md \
commands/ultraplan-local.md \
commands/ultraexecute-local.md
commands/trekbrief.md \
commands/trekresearch.md \
commands/trekplan.md \
commands/trekexecute.md
```
The exploration agents stay on Sonnet — only the orchestrator is bumped.
### Disable external research
`/ultraresearch-local --local` skips Tavily, Microsoft Learn, and the
`/trekresearch --local` skips Tavily, Microsoft Learn, and the
Gemini bridge. To make `--local` the default, edit the front of
`commands/ultraresearch-local.md` Phase 1 and flip the default branch
`commands/trekresearch.md` Phase 1 and flip the default branch
of the `--local` argument check. Or just always pass `--local` and
document it in your team's CLAUDE.md.
@ -744,7 +744,7 @@ schema drift.
### Disable the architect bridge
`/ultraplan-local` auto-discovers `architecture/overview.md` if an
`/trekplan` auto-discovers `architecture/overview.md` if an
opt-in upstream architect plugin (not bundled) produced one. To
suppress this, leave the `architecture/` directory absent from your
project directory. Discovery is additive — missing file is fine, no

6
plugins/ultraplan-local/SECURITY.md
View file

@ -1,4 +1,4 @@
# Security Policy — ultraplan-local
# Security Policy — trekplan
## Reporting a vulnerability
@ -33,14 +33,14 @@ The plugin's security posture covers:
| `pre-bash-executor.mjs` | `PreToolUse` for Bash | BLOCKs known-dangerous shell patterns; WARNs on suspicious ones; fails open on parse errors |
| `pre-write-executor.mjs` | `PreToolUse` for Write | BLOCKs writes to `.git/hooks/`, `~/.ssh/`, `.env`, and other sensitive paths |
| `pre-compact-flush.mjs` | `PreCompact` | Flushes `progress.json` from git history before compaction (P0 drift fix); read-only beyond `progress.json` |
| `session-title.mjs` *(planned, F9)* | `UserPromptSubmit` | Sets session title `ultra:<command>:<slug>` for headless multiplexing |
| `session-title.mjs` *(planned, F9)* | `UserPromptSubmit` | Sets session title `voyage:<command>:<slug>` for headless multiplexing |
All hooks are zero-dependency Node.js (`.mjs`) scripts and are designed
to **fail open** — a hook crash never blocks the user's work. Hooks log
to stderr only; they never write to user files outside their declared
scope.
### Prompt-level denylist (`commands/ultraexecute-local.md`)
### Prompt-level denylist (`commands/trekexecute.md`)
The execute command embeds a denylist that takes effect even in headless
sessions where hooks may not fire. This is layer 4 of the defense-in-depth

6
plugins/ultraplan-local/agents/architecture-mapper.md
View file

@ -5,11 +5,11 @@ description: |
tech stack, patterns, anti-patterns, and key abstractions.
<example>
Context: Ultraplan exploration phase needs architecture overview
user: "/ultraplan-local Add authentication to the API"
Context: Voyage exploration phase needs architecture overview
user: "/trekplan Add authentication to the API"
assistant: "Launching architecture-mapper to analyze codebase structure and patterns."
<commentary>
Phase 5 of ultraplan triggers this agent for every codebase size.
Phase 5 of trekplan triggers this agent for every codebase size.
</commentary>
</example>

6
plugins/ultraplan-local/agents/brief-conformance-reviewer.md
View file

@ -1,7 +1,7 @@
---
name: brief-conformance-reviewer
description: |
Adversarial reviewer for /ultrareview-local. Compares delivered code
Adversarial reviewer for /trekreview. Compares delivered code
against the task brief — every Success Criterion must trace to delivered
code, every Non-Goal must remain unbuilt. Emits findings with rule_keys
from the canonical RULE_CATALOGUE. Never praises.
@ -44,7 +44,7 @@ You will receive a prompt containing:
changed files with per-file content excerpts when the diff is too
large).
- **Triage map** — `{file → deep-review|summary-only|skip}` from the
/ultrareview-local triage gate. Respect `skip` decisions; do NOT flag
/trekreview triage gate. Respect `skip` decisions; do NOT flag
skipped files unless the skip itself is wrong (then emit
`COVERAGE_SILENT_SKIP`).
- **Rule catalogue** — the 12-key catalogue in
@ -79,7 +79,7 @@ context is needed) and classify coverage:
| **Broken** | Code claims to implement the criterion but the verification fails or is structurally wrong | `BROKEN_SUCCESS_CRITERION` (BLOCKER) |
Cite the criterion text in `brief_ref` (e.g., `SC3 — "review.md is
parseable as input to /ultraplan-local"`).
parseable as input to /trekplan"`).
### 3. Trace each Non-Goal to delivered code

20
plugins/ultraplan-local/agents/brief-reviewer.md
View file

@ -7,8 +7,8 @@ description: |
exploration with a flawed brief.
<example>
Context: Ultraplan runs brief review before exploration
user: "/ultraplan-local --project .claude/projects/2026-04-18-notifications"
Context: Voyage runs brief review before exploration
user: "/trekplan --project .claude/projects/2026-04-18-notifications"
assistant: "Reviewing brief quality before launching exploration agents."
<commentary>
Orchestrator Phase 1b triggers this agent after the brief is available.
@ -35,8 +35,8 @@ missing, vague, or contradictory.
## Input
You receive the path to a brief file (ultrabrief v2.0 format, produced by
`/ultrabrief-local`). Read it and evaluate its quality across five dimensions.
You receive the path to a brief file (trekbrief v2.0 format, produced by
`/trekbrief`). Read it and evaluate its quality across five dimensions.
A brief has these sections (see template for full structure):
- `## Intent` — why the work matters (load-bearing)
@ -115,18 +115,18 @@ Flag as **unclear scope** if:
### 5. Research Plan validity (NEW in v2.0)
The `## Research Plan` section declares topics that must be answered before
`/ultraplan-local` can produce a high-confidence plan. Validate:
`/trekplan` can produce a high-confidence plan. Validate:
**Per topic:**
- **Research question:** phrased as a question, ends in `?`, answerable by
`/ultraresearch-local` (not "figure out the architecture" but "what are
`/trekresearch` (not "figure out the architecture" but "what are
the tradeoffs between library X and library Y for our use case?")
- **Required for plan steps:** names specific kinds of steps that consume
this answer (e.g., "migration strategy", "library selection", "threat model")
- **Confidence needed:** one of `high`, `medium`, `low`
- **Estimated cost:** one of `quick`, `standard`, `deep`
- **Scope hint:** one of `local`, `external`, `both`
- **Suggested invocation:** copy-paste-ready `/ultraresearch-local` command
- **Suggested invocation:** copy-paste-ready `/trekresearch` command
**Cross-check with frontmatter:**
- `research_topics: N` matches the actual count of `### Topic` headings
@ -165,7 +165,7 @@ Rate each dimension on two parallel scales:
- **1** — section is effectively missing or contradictory (maps to Fail)
Use both. The verbal rating drives the human-readable verdict. The numeric
score drives callers (such as `/ultrabrief-local` Phase 4) that use the
score drives callers (such as `/trekbrief` Phase 4) that use the
review as a quality gate and need per-dimension granularity.
## Output format
@ -174,7 +174,7 @@ Produce **two artifacts in this order**:
1. A prose report (for humans and for `planning-orchestrator` Phase 1b).
2. A final fenced `json` block with per-dimension numeric scores (for callers
that gate on machine-readable output, such as `/ultrabrief-local` Phase 4).
that gate on machine-readable output, such as `/trekbrief` Phase 4).
The JSON block MUST be the last fenced block in your output so parsers can
find it by reading the last `json` code fence.
@ -202,7 +202,7 @@ find it by reading the last `json` code fence.
- **Suggestion:** {how to fix it}
### Suggested additions
{Questions that should have been asked during the ultrabrief interview, or
{Questions that should have been asked during the trekbrief interview, or
information that would strengthen the brief. List only if actionable.}
### Verdict

4
plugins/ultraplan-local/agents/code-correctness-reviewer.md
View file

@ -1,7 +1,7 @@
---
name: code-correctness-reviewer
description: |
Adversarial reviewer for /ultrareview-local. Finds real bugs in
Adversarial reviewer for /trekreview. Finds real bugs in
delivered code across 7 dimensions: error handling, fragile assumptions,
cross-file regressions, test coverage gaps, placeholder code, security
surface, hidden dependencies. Cites file:line for every finding. Never
@ -41,7 +41,7 @@ problems — every claim is anchored to quoted code.
You will receive a prompt containing:
- **Diff text** — unified diff of the changes under review.
- **Triage map** — `{file → deep-review|summary-only|skip}` from the
/ultrareview-local triage gate. Respect `skip` decisions; only flag
/trekreview triage gate. Respect `skip` decisions; only flag
skipped files when the skip itself is wrong (then emit
`COVERAGE_SILENT_SKIP`). Files marked `summary-only` get a structural
pass — declared signatures, exports, top-level wiring — but no deep

8
plugins/ultraplan-local/agents/community-researcher.md
View file

@ -6,8 +6,8 @@ description: |
and what developers actually encounter when using a technology.
<example>
Context: ultraresearch-local needs real-world experience data on a database migration
user: "/ultraresearch-local What's the real-world experience with migrating from MongoDB to PostgreSQL?"
Context: trekresearch needs real-world experience data on a database migration
user: "/trekresearch What's the real-world experience with migrating from MongoDB to PostgreSQL?"
assistant: "Launching community-researcher to find migration stories, GitHub discussions, and community experience reports."
<commentary>
Official docs won't cover migration regrets or production war stories. community-researcher
@ -16,8 +16,8 @@ description: |
</example>
<example>
Context: ultraresearch-local is building a technology comparison
user: "/ultraresearch-local Research community sentiment around adopting SvelteKit vs Next.js"
Context: trekresearch is building a technology comparison
user: "/trekresearch Research community sentiment around adopting SvelteKit vs Next.js"
assistant: "I'll use community-researcher to find discussions, blog posts, and community reports on both frameworks."
<commentary>
Framework comparisons live in community discourse, not official docs. community-researcher

8
plugins/ultraplan-local/agents/contrarian-researcher.md
View file

@ -6,8 +6,8 @@ description: |
answer might be wrong.
<example>
Context: ultraresearch-local has found evidence favoring a technology and needs the other side
user: "/ultraresearch-local We're leaning toward adopting Kafka for our event streaming needs"
Context: trekresearch has found evidence favoring a technology and needs the other side
user: "/trekresearch We're leaning toward adopting Kafka for our event streaming needs"
assistant: "Launching contrarian-researcher to find the strongest arguments against Kafka and what alternatives might serve better."
<commentary>
The research equivalent of plan-critic. When one option is emerging as the answer,
@ -16,8 +16,8 @@ description: |
</example>
<example>
Context: ultraresearch-local is comparing options and needs the downsides of the leading candidate
user: "/ultraresearch-local Compare Redis vs Memcached — initial research favors Redis"
Context: trekresearch is comparing options and needs the downsides of the leading candidate
user: "/trekresearch Compare Redis vs Memcached — initial research favors Redis"
assistant: "I'll use contrarian-researcher to find the strongest case against Redis and scenarios where Memcached wins."
<commentary>
Contrarian-researcher finds the downsides of the leading option — not to be negative,

6
plugins/ultraplan-local/agents/convention-scanner.md
View file

@ -7,11 +7,11 @@ description: |
documentation patterns. Uses concrete examples from the codebase.
<example>
Context: Ultraplan exploration phase for a medium+ codebase
user: "/ultraplan-local Add authentication to the API"
Context: Voyage exploration phase for a medium+ codebase
user: "/trekplan Add authentication to the API"
assistant: "Launching convention-scanner to discover coding patterns."
<commentary>
Phase 5 of ultraplan triggers this agent for medium+ codebases (50+ files).
Phase 5 of trekplan triggers this agent for medium+ codebases (50+ files).
</commentary>
</example>

6
plugins/ultraplan-local/agents/dependency-tracer.md
View file

@ -5,11 +5,11 @@ description: |
how modules connect and what side effects they produce.
<example>
Context: Ultraplan needs to understand module relationships for a task
user: "/ultraplan-local Refactor the payment processing pipeline"
Context: Voyage needs to understand module relationships for a task
user: "/trekplan Refactor the payment processing pipeline"
assistant: "Launching dependency-tracer to map module connections and data flow."
<commentary>
Phase 5 of ultraplan triggers this agent to trace dependencies relevant to the task.
Phase 5 of trekplan triggers this agent to trace dependencies relevant to the task.
</commentary>
</example>

8
plugins/ultraplan-local/agents/docs-researcher.md
View file

@ -5,8 +5,8 @@ description: |
documentation, RFCs, vendor specifications, or Microsoft/Azure documentation.
<example>
Context: ultraresearch-local needs to ground an OAuth2 implementation in official specs
user: "/ultraresearch-local Research OAuth2 PKCE flow for our SPA"
Context: trekresearch needs to ground an OAuth2 implementation in official specs
user: "/trekresearch Research OAuth2 PKCE flow for our SPA"
assistant: "Launching docs-researcher to find the official RFC and vendor documentation for OAuth2 PKCE."
<commentary>
docs-researcher targets authoritative sources — RFCs, specs, official vendor docs —
@ -15,8 +15,8 @@ description: |
</example>
<example>
Context: ultraresearch-local encounters an Azure-specific technology
user: "/ultraresearch-local How should we configure Azure Service Bus for our event pipeline?"
Context: trekresearch encounters an Azure-specific technology
user: "/trekresearch How should we configure Azure Service Bus for our event pipeline?"
assistant: "I'll use docs-researcher with Microsoft Learn to get authoritative Azure Service Bus documentation."
<commentary>
Microsoft/Azure technologies have dedicated MCP tools (microsoft_docs_search,

4
plugins/ultraplan-local/agents/gemini-bridge.md
View file

@ -7,8 +7,8 @@ description: |
that can confirm or challenge findings from other agents.
<example>
Context: ultraresearch launches gemini-bridge for an independent second opinion on a technology choice
user: "/ultraplan-local Should we use Kafka or NATS for our event streaming layer?"
Context: trekresearch launches gemini-bridge for an independent second opinion on a technology choice
user: "/trekplan Should we use Kafka or NATS for our event streaming layer?"
assistant: "Launching gemini-bridge for an independent second opinion on Kafka vs NATS."
<commentary>
Technology choice with significant architectural implications triggers gemini-bridge

6
plugins/ultraplan-local/agents/git-historian.md
View file

@ -5,11 +5,11 @@ description: |
code ownership, hot files, and active branches relevant to the task.
<example>
Context: Ultraplan exploration phase needs git context
user: "/ultraplan-local Refactor the database layer"
Context: Voyage exploration phase needs git context
user: "/trekplan Refactor the database layer"
assistant: "Launching git-historian to check recent changes and ownership of DB code."
<commentary>
Phase 2 of ultraplan triggers this agent for every codebase size.
Phase 2 of trekplan triggers this agent for every codebase size.
</commentary>
</example>

10
plugins/ultraplan-local/agents/plan-critic.md
View file

@ -5,11 +5,11 @@ description: |
problems, never praises.
<example>
Context: Ultraplan adversarial review phase
user: "/ultraplan-local Implement WebSocket real-time updates"
Context: Voyage adversarial review phase
user: "/trekplan Implement WebSocket real-time updates"
assistant: "Launching plan-critic to stress-test the implementation plan."
<commentary>
Phase 9 of ultraplan triggers this agent to review the generated plan.
Phase 9 of trekplan triggers this agent to review the generated plan.
</commentary>
</example>
@ -168,7 +168,7 @@ cannot be decomposed into headless sessions).
### 10. Manifest quality (hard gate)
Manifests are the objective completion predicate. ultraexecute-local uses
Manifests are the objective completion predicate. trekexecute uses
them to determine whether a step is actually done — not just whether the
Verify command returned 0. A plan without valid manifests cannot drive
deterministic execution.
@ -199,7 +199,7 @@ Check plans with `plan_version: 1.7` (or later) against these rules:
**Backward compat:** For plans without `plan_version: 1.7` (legacy), emit
a single advisory note ("Plan is v1.6 legacy format — manifests will be
synthesized by ultraexecute with reduced audit precision") and skip this
synthesized by trekexecute with reduced audit precision") and skip this
dimension's scoring.
## Rating system

26
plugins/ultraplan-local/agents/planning-orchestrator.md
View file

@ -2,12 +2,12 @@
name: planning-orchestrator
description: |
Inline reference (v2.4.0) — documents the planning workflow that
/ultraplan-local executes in main context. This file is NOT spawned as a
/trekplan executes in main context. This file is NOT spawned as a
sub-agent anymore. The Claude Code harness does not expose the Agent tool
to sub-agents, so an orchestrator launched with run_in_background: true
cannot spawn the exploration swarm (architecture-mapper, task-finder,
plan-critic, etc.) and would degrade to single-context reasoning. The
/ultraplan-local command now orchestrates the phases below directly in the
/trekplan command now orchestrates the phases below directly in the
main session.
model: opus
color: cyan
@ -23,12 +23,12 @@ tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate",
Orchestrator Phase 5 = Command Phase 8 (Deep planning)
Orchestrator Phase 6 = Command Phase 9 (Adversarial review)
Orchestrator Phase 7 = Command Phase 10 (Completion)
As of v2.4.0, /ultraplan-local runs these phases inline in main context
As of v2.4.0, /trekplan runs these phases inline in main context
instead of spawning this agent. Keep this file as the canonical
reference for what those phases do. -->
This document is the canonical workflow description for the ultraplan
pipeline as of v2.4.0. The `/ultraplan-local` command reads it as reference
This document is the canonical workflow description for the trekplan
pipeline as of v2.4.0. The `/trekplan` command reads it as reference
and executes the phases below **inline in the main command context**. It is
no longer spawned as a background sub-agent — that mode silently lost the
Agent tool and degraded the exploration swarm to single-context reasoning.
@ -40,9 +40,9 @@ tool, collects their results, synthesizes the plan, and writes it to disk.
## Input
You will receive a prompt containing:
- **Brief file path** — the task brief (produced by `/ultrabrief-local`)
- **Project dir** (optional) — path to an ultrabrief project folder when the user
invoked `/ultraplan-local --project`. If set, the plan destination is
- **Brief file path** — the task brief (produced by `/trekbrief`)
- **Project dir** (optional) — path to an trekbrief project folder when the user
invoked `/trekplan --project`. If set, the plan destination is
`{project_dir}/plan.md` and any `{project_dir}/research/*.md` files are
pre-existing research briefs to read.
- **Task description** — one-line summary (matches the brief's frontmatter `task`)
@ -219,14 +219,14 @@ Write a comprehensive implementation plan including:
- **Estimated Scope** — file counts and complexity
**Plan-version header:** Include `plan_version: 1.7` in the metadata line below
the title. This signals to ultraexecute-local that the plan includes per-step
the title. This signals to trekexecute that the plan includes per-step
verification manifests and enables strict audit mode. Plans without this
marker are treated as legacy v1.6 with synthesized minimal manifests.
### Mandatory step format — copy this exactly
The Implementation Plan section MUST contain numbered steps using the EXACT
format shown below. The executor (`ultraexecute-local`) parses plans with
format shown below. The executor (`trekexecute`) parses plans with
strict regex matching. Any deviation breaks parsing and forces the user to
re-run planning.
@ -283,7 +283,7 @@ not skip fields. Do not nest steps under sub-headings.
Every implementation step MUST include a `Manifest:` block as its last field,
after Checkpoint. The manifest is the objective completion predicate — the
machine-checkable contract that ultraexecute-local will verify after the
machine-checkable contract that trekexecute will verify after the
Verify command passes. A step cannot be marked passed if its manifest does
not verify.
@ -427,7 +427,7 @@ After both complete:
- Address all blockers and major issues by revising the plan
- **Manifest quality is a hard gate:** any manifest-related `major` finding
must be fixed before the plan can be handed off. This enforces the
principle that ultraexecute-local relies on the plan being
principle that trekexecute relies on the plan being
machine-checkable — a plan without verifiable manifests cannot drive
deterministic execution.
- Add a "Revisions" note at the bottom documenting changes
@ -437,7 +437,7 @@ After both complete:
When done, your output message should contain:
```
## Ultraplan Complete (Background)
## Voyage Complete (Background)
**Task:** {task}
**Plan:** {plan path}

14
plugins/ultraplan-local/agents/research-orchestrator.md
View file

@ -2,11 +2,11 @@
name: research-orchestrator
description: |
Inline reference (v2.4.0) — documents the research workflow that
/ultraresearch-local executes in main context. This file is NOT spawned as
/trekresearch executes in main context. This file is NOT spawned as
a sub-agent anymore. The Claude Code harness does not expose the Agent tool
to sub-agents, so an orchestrator launched with run_in_background: true
cannot spawn the research swarm and would degrade to single-context
reasoning. The /ultraresearch-local command now orchestrates the phases
reasoning. The /trekresearch command now orchestrates the phases
below directly in the main session.
model: opus
color: cyan
@ -20,12 +20,12 @@ tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash"]
Orchestrator Phase 4 = Command Phase 7 (Triangulation)
Orchestrator Phase 5 = Command Phase 8 (Synthesis + write brief)
Orchestrator Phase 6 = Command Phase 9 (Completion)
As of v2.4.0, /ultraresearch-local runs these phases inline in main
As of v2.4.0, /trekresearch runs these phases inline in main
context instead of spawning this agent. Keep this file as the canonical
reference for what those phases do. -->
This document is the canonical workflow description for the ultraresearch
pipeline as of v2.4.0. The `/ultraresearch-local` command reads it as
This document is the canonical workflow description for the trekresearch
pipeline as of v2.4.0. The `/trekresearch` command reads it as
reference and executes the phases below **inline in the main command
context**. It is no longer spawned as a background sub-agent — that mode
silently lost the Agent tool and degraded the swarm to single-context
@ -140,7 +140,7 @@ If no gaps exist, skip: "Initial research sufficient — no follow-ups needed."
### Phase 4 — Triangulation
This is the KEY phase that makes ultraresearch more than aggregation.
This is the KEY phase that makes trekresearch more than aggregation.
For each dimension of the research question:
@ -208,7 +208,7 @@ When done, your output message should contain:
You can:
- Read the full brief at {brief path}
- Feed into planning: /ultraplan-local --research {brief path} <task>
- Feed into planning: /trekplan --research {brief path} <task>
- Ask follow-up questions
```

6
plugins/ultraplan-local/agents/research-scout.md
View file

@ -5,11 +5,11 @@ description: |
APIs, or libraries where official documentation and known issues should be checked.
<example>
Context: Ultraplan detects external technology in the task
user: "/ultraplan-local Integrate Stripe payment processing"
Context: Voyage detects external technology in the task
user: "/trekplan Integrate Stripe payment processing"
assistant: "Launching research-scout to find Stripe documentation and best practices."
<commentary>
Phase 5 of ultraplan conditionally triggers this agent when external tech is detected.
Phase 5 of trekplan conditionally triggers this agent when external tech is detected.
</commentary>
</example>

10
plugins/ultraplan-local/agents/review-coordinator.md
View file

@ -1,7 +1,7 @@
---
name: review-coordinator
description: |
Judge Agent for /ultrareview-local. Receives findings from independent
Judge Agent for /trekreview. Receives findings from independent
reviewers (brief-conformance-reviewer, code-correctness-reviewer) and
applies BOUNDED operations: deduplication, severity ranking, HubSpot
Judge filters, Cloudflare reasonableness filter, verdict computation.
@ -47,7 +47,7 @@ You will receive a prompt containing:
`brief-conformance-reviewer` and `code-correctness-reviewer` (in `quick`
mode, only the latter).
- **Triage map** — `{file → deep-review|summary-only|skip, reason}` from
the /ultrareview-local triage gate.
the /trekreview triage gate.
- **Brief metadata** — `task`, `slug`, `project_dir`, `brief_path` from
the brief frontmatter.
- **Scope SHA range** — `scope_sha_start`, `scope_sha_end`,
@ -128,7 +128,7 @@ trailing JSON block AND the Executive Summary's first sentence.
## Output: review.md content
Produce the full review.md content as your output. The
/ultrareview-local command writes it verbatim to disk.
/trekreview command writes it verbatim to disk.
### Frontmatter (block-style YAML, NOT flow-style)
@ -171,7 +171,7 @@ prefix). Flow-style `findings: [a, b]` breaks the frontmatter parser.
8. `## Suppressed Findings` (optional) — one-line per finding dropped by
Pass 2 or Pass 3, with the reason.
9. `## Remediation Summary` — bullet count per severity + 1 sentence on
what /ultraplan-local will consume.
what /trekplan will consume.
Each Findings subsection uses the `### {finding-id-40-char-hex}` heading
followed by these fields:
@ -208,7 +208,7 @@ The LAST fenced block in the file is a `json` block:
```
The JSON `findings[].id` array MUST match the frontmatter `findings:`
list. The downstream consumer (/ultraplan-local with
list. The downstream consumer (/trekplan with
`--brief review.md`) reads the JSON for full content and the frontmatter
for the ID list.

20
plugins/ultraplan-local/agents/review-orchestrator.md
View file

@ -2,13 +2,13 @@
name: review-orchestrator
description: |
Inline reference (v3.2.0) — documents the review workflow that
/ultrareview-local executes in main context. This file is NOT spawned
/trekreview executes in main context. This file is NOT spawned
as a sub-agent. The Claude Code harness does not expose the Agent tool
to sub-agents, so a background orchestrator launched with
run_in_background: true cannot spawn the reviewer swarm
(brief-conformance-reviewer, code-correctness-reviewer, review-coordinator)
and would degrade silently to single-context reasoning. The
/ultrareview-local command now orchestrates the phases below directly in
/trekreview command now orchestrates the phases below directly in
the main session.
model: opus
color: red
@ -24,12 +24,12 @@ tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate",
Orchestrator Phase 6 = Command Phase 6 (Coordinator dedup + verdict)
Orchestrator Phase 7 = Command Phase 7 (Write review.md)
Orchestrator Phase 8 = Command Phase 8 (Validate + stats)
As of v3.2.0, /ultrareview-local runs these phases inline in main
As of v3.2.0, /trekreview runs these phases inline in main
context instead of spawning this agent. Keep this file as the canonical
reference for what those phases do. -->
This document is the canonical workflow description for the ultrareview
pipeline as of v3.2.0. The `/ultrareview-local` command reads it as
This document is the canonical workflow description for the trekreview
pipeline as of v3.2.0. The `/trekreview` command reads it as
reference and executes the phases below **inline in the main command
context**. It is not spawned as a background sub-agent — that mode would
silently lose the Agent tool and degrade the reviewer swarm to
@ -50,7 +50,7 @@ explicitly forbidden in v1.0 (Judge Agent pattern).
## Input
You will receive a prompt containing:
- **Project dir** — path to the ultraplan-local project folder (the brief and
- **Project dir** — path to the trekplan project folder (the brief and
optional `progress.json` live here; the review will be written to
`{project_dir}/review.md`).
- **Brief path** — `{project_dir}/brief.md`. Read it; the brief is the
@ -77,7 +77,7 @@ Execute these phases in order. Do not skip phases.
Run the arg-parser via Bash:
```
node ${CLAUDE_PLUGIN_ROOT}/lib/parsers/arg-parser.mjs --command ultrareview "$@"
node ${CLAUDE_PLUGIN_ROOT}/lib/parsers/arg-parser.mjs --command trekreview "$@"
```
Pull the structured flags from its JSON output. Reject unknown flags. If
@ -94,7 +94,7 @@ node ${CLAUDE_PLUGIN_ROOT}/lib/validators/brief-validator.mjs --soft --json {bri
```
If `valid: false` with REQUIRED-field errors: stop, ask the user to
re-run `/ultrabrief-local` first.
re-run `/trekbrief` first.
### Phase 3 — Discover scope SHA range
@ -221,7 +221,7 @@ Append a stats line to `${CLAUDE_PLUGIN_DATA}/trekreview-stats.jsonl`:
a runnable sub-agent. Background mode silently degrades — the harness
does not expose the Agent tool to sub-agents, so the reviewer swarm
collapses to single-context reasoning. Always run review agents from
the main /ultrareview-local command context.
the main /trekreview command context.
- **Reviewers run independently.** No cross-feeding of findings. The
coordinator is the only place where reviewer outputs are combined.
- **Coordinator scope is bounded.** Dedup, severity ranking, reasonableness
@ -234,7 +234,7 @@ Append a stats line to `${CLAUDE_PLUGIN_DATA}/trekreview-stats.jsonl`:
the Coverage section, even if its treatment is `skip`. Hidden truncation
is COVERAGE_SILENT_SKIP (MAJOR).
- **Cost:** Use Sonnet for all sub-agents. The orchestrator (the
/ultrareview-local command itself) runs on Opus.
/trekreview command itself) runs on Opus.
- **Privacy:** Never log secrets, tokens, or credentials. Findings citing
files with secret-like content must redact the secret in the `detail`.
- **Honesty:** If the diff is trivially small or all-skip, say so. Do

6
plugins/ultraplan-local/agents/risk-assessor.md
View file

@ -5,11 +5,11 @@ description: |
technical debt that could affect an implementation task.
<example>
Context: Ultraplan exploration phase identifies potential risks
user: "/ultraplan-local Migrate database from PostgreSQL to MongoDB"
Context: Voyage exploration phase identifies potential risks
user: "/trekplan Migrate database from PostgreSQL to MongoDB"
assistant: "Launching risk-assessor to identify failure modes and edge cases for this migration."
<commentary>
Phase 5 of ultraplan triggers this agent to find risks before planning begins.
Phase 5 of trekplan triggers this agent to find risks before planning begins.
</commentary>
</example>

6
plugins/ultraplan-local/agents/scope-guardian.md
View file

@ -5,11 +5,11 @@ description: |
requirements — catches scope creep and scope gaps.
<example>
Context: Ultraplan adversarial review phase checks scope alignment
user: "/ultraplan-local Add caching to the API layer"
Context: Voyage adversarial review phase checks scope alignment
user: "/trekplan Add caching to the API layer"
assistant: "Launching scope-guardian to verify plan matches requirements."
<commentary>
Phase 9 of ultraplan triggers this agent alongside plan-critic.
Phase 9 of trekplan triggers this agent alongside plan-critic.
</commentary>
</example>

8
plugins/ultraplan-local/agents/security-researcher.md
View file

@ -5,8 +5,8 @@ description: |
dependency, or library — CVEs, audit history, supply chain risks, and OWASP relevance.
<example>
Context: ultraresearch-local is evaluating whether a dependency is safe to adopt
user: "/ultraresearch-local Research whether we should trust the `node-fetch` library"
Context: trekresearch is evaluating whether a dependency is safe to adopt
user: "/trekresearch Research whether we should trust the `node-fetch` library"
assistant: "Launching security-researcher to check CVE history, supply chain risk, and audit reports for node-fetch."
<commentary>
Before adopting a dependency, security-researcher checks the attack surface: known
@ -15,8 +15,8 @@ description: |
</example>
<example>
Context: ultraresearch-local is assessing the security posture of a technology choice
user: "/ultraresearch-local Evaluate the security implications of using JWT for session management"
Context: trekresearch is assessing the security posture of a technology choice
user: "/trekresearch Evaluate the security implications of using JWT for session management"
assistant: "I'll use security-researcher to check known JWT vulnerabilities, OWASP guidance, and community security reports."
<commentary>
Technology choices have security tradeoffs. security-researcher maps the threat surface

10
plugins/ultraplan-local/agents/session-decomposer.md
View file

@ -1,13 +1,13 @@
---
name: session-decomposer
description: |
Use this agent to decompose an ultraplan into self-contained headless sessions.
Use this agent to decompose an trekplan into self-contained headless sessions.
Reads a plan file, analyzes step dependencies, groups steps into sessions,
identifies parallelism, and generates session specs + dependency graph + launch script.
<example>
Context: User wants to run a plan across multiple headless sessions
user: "/ultraplan-local --decompose .claude/plans/ultraplan-2026-04-06-auth-refactor.md"
user: "/trekplan --decompose .claude/plans/trekplan-2026-04-06-auth-refactor.md"
assistant: "Launching session-decomposer to split the plan into headless sessions."
<commentary>
The --decompose flag triggers this agent to analyze and split the plan.
@ -27,15 +27,15 @@ color: green
tools: ["Read", "Glob", "Grep", "Write"]
---
You are a session decomposition specialist. You take a complete ultraplan implementation
You are a session decomposition specialist. You take a complete trekplan implementation
plan and split it into self-contained sessions optimized for headless execution.
## Input
You will receive:
- **Plan file path** — the ultraplan to decompose
- **Plan file path** — the trekplan to decompose
- **Plugin root** — for template access
- **Output directory** — where to write session specs (default: `.claude/ultraplan-sessions/`)
- **Output directory** — where to write session specs (default: `.claude/trekplan-sessions/`)
Read the plan file first. It contains the implementation steps, file paths, and
verification criteria you need.

6
plugins/ultraplan-local/agents/task-finder.md
View file

@ -6,11 +6,11 @@ description: |
structured code discovery.
<example>
Context: Ultraplan exploration phase needs task-relevant code
user: "/ultraplan-local Add authentication to the API"
Context: Voyage exploration phase needs task-relevant code
user: "/trekplan Add authentication to the API"
assistant: "Launching task-finder to locate auth-related code, endpoints, and models."
<commentary>
Phase 2 of ultraplan triggers this agent for every codebase size.
Phase 2 of trekplan triggers this agent for every codebase size.
</commentary>
</example>

6
plugins/ultraplan-local/agents/test-strategist.md
View file

@ -5,11 +5,11 @@ description: |
discovers existing patterns, maps coverage gaps, and recommends what tests to write.
<example>
Context: Ultraplan exploration phase for medium+ codebase
user: "/ultraplan-local Add rate limiting to the API"
Context: Voyage exploration phase for medium+ codebase
user: "/trekplan Add rate limiting to the API"
assistant: "Launching test-strategist to analyze existing test patterns and design test coverage."
<commentary>
Phase 5 of ultraplan triggers this agent for medium and large codebases.
Phase 5 of trekplan triggers this agent for medium and large codebases.
</commentary>
</example>

54
plugins/ultraplan-local/commands/trekbrief.md
View file

@ -1,6 +1,6 @@
---
name: trekbrief
description: Interactive interview that produces a task brief with explicit research plan. Feeds /ultraresearch-local and /ultraplan-local. Optionally orchestrates the full pipeline end-to-end.
description: Interactive interview that produces a task brief with explicit research plan. Feeds /trekresearch and /trekplan. Optionally orchestrates the full pipeline end-to-end.
argument-hint: "[--quick] <task description>"
model: opus
allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion
@ -10,18 +10,18 @@ allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion
Interactive requirements-gathering command. Produces a **task brief** — a
structured markdown file that declares intent, goal, constraints, and an
**explicit research plan** with copy-paste-ready `/ultraresearch-local` commands.
**explicit research plan** with copy-paste-ready `/trekresearch` commands.
Pipeline position:
```
/ultrabrief-local → brief.md (this command)
/ultraresearch-local --project <dir> → research/*.md
/ultraplan-local --project <dir> → plan.md
/ultraexecute-local --project <dir> → execution
/trekbrief → brief.md (this command)
/trekresearch --project <dir> → research/*.md
/trekplan --project <dir> → plan.md
/trekexecute --project <dir> → execution
```
The brief is the contract between the user's intent and `/ultraplan-local`.
The brief is the contract between the user's intent and `/trekplan`.
Every decision the plan makes must trace back to content in the brief.
**This command is always interactive.** There is no background mode — the
@ -55,17 +55,17 @@ Parse `$ARGUMENTS`:
If no task description is provided, output usage and stop:
```
Usage: /ultrabrief-local <task description>
/ultrabrief-local --quick <task description>
Usage: /trekbrief <task description>
/trekbrief --quick <task description>
Modes:
default Dynamic interview until quality gates pass — brief with research plan
--quick Compact start; still escalates on weak sections — brief with research plan
Examples:
/ultrabrief-local Add user authentication with JWT tokens
/ultrabrief-local --quick Add rate limiting to the API
/ultrabrief-local Migrate from Express to Fastify
/trekbrief Add user authentication with JWT tokens
/trekbrief --quick Add rate limiting to the API
/trekbrief Migrate from Express to Fastify
```
Report:
@ -292,7 +292,7 @@ Proceeding to draft and review.
Phase 4 runs a **draft → brief-reviewer → revise** loop. The draft is
not written to disk until the brief-review quality gate passes (or the
iteration cap is hit). This ensures the brief that reaches `/ultraplan-local`
iteration cap is hit). This ensures the brief that reaches `/trekplan`
has already survived a critical review.
Read the brief template first:
@ -502,8 +502,8 @@ Ask the user via `AskUserQuestion`:
| Option | Description |
|--------|-------------|
| **Manual (default)** | Print the commands. You run `/ultraresearch-local` and `/ultraplan-local` yourself, choosing depth per topic. |
| **Auto (managed by Claude Code)** | I run all {N} research topics sequentially in foreground, then automatically trigger `/ultraplan-local` when research completes. This session blocks until the plan is ready. |
| **Manual (default)** | Print the commands. You run `/trekresearch` and `/trekplan` yourself, choosing depth per topic. |
| **Auto (managed by Claude Code)** | I run all {N} research topics sequentially in foreground, then automatically trigger `/trekplan` when research completes. This session blocks until the plan is ready. |
### Manual path (default)
@ -519,13 +519,13 @@ Research topics: {N}
Next steps (run in order or parallel):
{For each topic:}
/ultraresearch-local --project {PROJECT_DIR} --external "{topic question}"
/trekresearch --project {PROJECT_DIR} --external "{topic question}"
Then:
/ultraplan-local --project {PROJECT_DIR}
/trekplan --project {PROJECT_DIR}
Then:
/ultraexecute-local --project {PROJECT_DIR}
/trekexecute --project {PROJECT_DIR}
```
Stop. Do not continue to Phase 6.
@ -549,7 +549,7 @@ answers no, fall back to the manual path output and stop. Otherwise
proceed to Phase 6.
If `gates_mode == false` (default in auto): proceed directly to Phase 6.
The chain stops only at the main-merge gate (see `commands/ultraexecute-local.md`
The chain stops only at the main-merge gate (see `commands/trekexecute.md`
Phase 8).
Proceed to Phase 6.
@ -578,11 +578,11 @@ If cancelled → fall back to manual path output and stop.
Set `research_status: in_progress` in the brief's frontmatter.
For each research topic (index i = 1 .. N), invoke `/ultraresearch-local`
For each research topic (index i = 1 .. N), invoke `/trekresearch`
inline in this main-context session:
```
/ultraresearch-local --project {PROJECT_DIR} {--external | --local | (none)} "{topic i question}"
/trekresearch --project {PROJECT_DIR} {--external | --local | (none)} "{topic i question}"
```
Pass the scope flag that matches the topic's scope hint. Wait for each
@ -617,7 +617,7 @@ Update brief frontmatter: `research_status: complete`.
Invoke the planning command inline in this session:
```
/ultraplan-local --project {PROJECT_DIR}
/trekplan --project {PROJECT_DIR}
```
The planning pipeline runs all phases (exploration, synthesis, review) in
@ -629,7 +629,7 @@ before continuing.
When the planning-orchestrator finishes, present:
```
## Ultrabrief + Ultraresearch + Ultraplan Complete (auto mode)
## Ultrabrief + Ultraresearch + Voyage Complete (auto mode)
**Project:** {PROJECT_DIR}/
**Brief:** {PROJECT_DIR}/brief.md
@ -645,11 +645,11 @@ When the planning-orchestrator finishes, present:
| Plan | Complete ({steps} steps, critic: {verdict}) |
Next:
/ultraexecute-local --project {PROJECT_DIR}
/trekexecute --project {PROJECT_DIR}
Or:
/ultraexecute-local --dry-run --project {PROJECT_DIR} # preview
/ultraexecute-local --validate --project {PROJECT_DIR} # schema check
/trekexecute --dry-run --project {PROJECT_DIR} # preview
/trekexecute --validate --project {PROJECT_DIR} # schema check
```
## Phase 7 — Stats tracking
@ -685,7 +685,7 @@ Never let stats failures block the workflow.
the user until motivation is clear — the plan and every review agent
will trace decisions back to this.
4. **Research topics must be answerable.** Each topic's research question
must be phrased so `/ultraresearch-local` can answer it. If a topic is
must be phrased so `/trekresearch` can answer it. If a topic is
too vague, split or reformulate before writing.
5. **Never invent research topics the user did not agree to.** Topics
come from the interview. If the user says "I know this", respect it.

58
plugins/ultraplan-local/commands/trekcontinue.md
View file

@ -1,6 +1,6 @@
---
name: trekcontinue
description: Resume the next session in a multi-session ultraplan project. Reads .session-state.local.json and immediately begins the next session.
description: Resume the next session in a multi-session trekplan project. Reads .session-state.local.json and immediately begins the next session.
argument-hint: "[<project-dir> | --help]"
model: opus
---
@ -8,22 +8,22 @@ model: opus
# Ultracontinue Local v1.0
Zero-friction multi-session resumption. In a fresh Claude Code session, type
`/ultracontinue` — the command reads the per-project state file
`/trekcontinue` — the command reads the per-project state file
(`.claude/projects/<project>/.session-state.local.json`), shows a 3-line summary,
and immediately begins executing the next session.
The state file is the contract. Any session-end mechanism may write it
(`/ultraexecute-local` Phase 8 / Phase 2.55 / Phase 4, the
`/ultraplan-end-session-local` helper, or — in the future — `graceful-handoff`).
(`/trekexecute` Phase 8 / Phase 2.55 / Phase 4, the
`/trekendsession` helper, or — in the future — `graceful-handoff`).
This command only reads.
Pipeline position:
```
/ultraplan-local → plan.md
/ultraexecute-local → progress.json + .session-state.local.json
/trekplan → plan.md
/trekexecute → progress.json + .session-state.local.json
... session boundary, fresh chat ...
/ultracontinue → reads .session-state.local.json, starts next session
/trekcontinue → reads .session-state.local.json, starts next session
```
See **Handover 7** in `docs/HANDOVER-CONTRACTS.md` for the full schema.
@ -43,14 +43,14 @@ the literal empty string `""`, or a positional project-dir — fall through to
Phase 1. Do NOT print the usage block on empty args.
```
/ultracontinue — Resume the next session in a multi-session ultraplan project.
/trekcontinue — Resume the next session in a multi-session trekplan project.
Usage:
/ultracontinue # auto-discover state file under cwd
/ultracontinue <project-dir> # explicit project directory
/ultracontinue --cleanup <project-dir> # dry-run: list stale files
/ultracontinue --cleanup --confirm <project-dir> # actually delete (requires status: completed)
/ultracontinue --help # this message
/trekcontinue # auto-discover state file under cwd
/trekcontinue <project-dir> # explicit project directory
/trekcontinue --cleanup <project-dir> # dry-run: list stale files
/trekcontinue --cleanup --confirm <project-dir> # actually delete (requires status: completed)
/trekcontinue --help # this message
Reads .claude/projects/<project>/.session-state.local.json (per-project,
gitignored). On a valid resumable state, prints a 3-line summary and begins
@ -67,11 +67,11 @@ State-file schema (v1):
(unknown top-level keys are tolerated — forward-compat for graceful-handoff v2.2)
Typical flow:
/ultrabrief-local # produces brief.md
/ultraplan-local --project ... # produces plan.md
/ultraexecute-local --project .. # writes session-state on session-end
/trekbrief # produces brief.md
/trekplan --project ... # produces plan.md
/trekexecute --project .. # writes session-state on session-end
... (fresh Claude chat) ...
/ultracontinue # reads session-state, runs next session
/trekcontinue # reads session-state, runs next session
```
## Phase 0.5 — Cleanup mode dispatch
@ -89,10 +89,10 @@ irreversible. If `positional[0]` is missing, empty, or starts with `-`,
print this usage block to stderr and exit non-zero:
```
Error: /ultracontinue-local --cleanup requires <project-dir>.
Error: /trekcontinue --cleanup requires <project-dir>.
Usage:
/ultracontinue-local --cleanup <project-dir> # dry-run: list stale files
/ultracontinue-local --cleanup --confirm <project-dir> # actually delete (status: completed)
/trekcontinue --cleanup <project-dir> # dry-run: list stale files
/trekcontinue --cleanup --confirm <project-dir> # actually delete (status: completed)
```
**Compute mode from parsed flags:**
@ -117,7 +117,7 @@ booleans above. The validator emits a `{valid, errors, warnings, parsed}`
JSON record. Print it to stdout. Exit with the validator's exit code.
**Cleanup is a terminal mode.** It must not fall through to Phase 1/2/3/4.
Operators who want to resume after cleanup must invoke `/ultracontinue`
Operators who want to resume after cleanup must invoke `/trekcontinue`
again without `--cleanup`.
## Phase 1 — Resolve project directory
@ -134,7 +134,7 @@ Print the following diagnostic to stderr and exit non-zero. Do NOT proceed.
```
Error: expected <project-dir>, got a markdown file path: <positional[0]>
Did you mean to paste the file path as a project directory?
Usage: /ultracontinue-local <project-dir>
Usage: /trekcontinue <project-dir>
```
### Step 1.b — Auto-discover candidates
@ -157,17 +157,17 @@ resumable state wins.
- **0 candidates and no explicit arg:** print SC-2 cold-start message and exit:
```
No active multi-session project here.
Start with /ultrabrief-local or /ultraplan-local.
Start with /trekbrief or /trekplan.
```
- **1 candidate (or explicit non-`.md` arg):** continue to Phase 2 with that path.
- **>1 candidates and no explicit arg:** with the Date.parse sort applied, the
newest resumable state wins automatically and the command continues to Phase 2
with that path. (Operators who want a different candidate re-invoke as
`/ultracontinue <project-dir>`.)
`/trekcontinue <project-dir>`.)
## Phase 1.5 — Frontmatter consistency check
Bug 3 contract: producers (`/ultraexecute-local`, `/ultraplan-end-session-local`)
Bug 3 contract: producers (`/trekexecute`, `/trekendsession`)
write `NEXT-SESSION-PROMPT.local.md` with YAML frontmatter (`produced_by:`,
`produced_at:`). Multiple producers may have written candidates in different
locations; this phase refuses ambiguity before validating the state file.
@ -197,7 +197,7 @@ After resolving the project directory and state-file path, look for two
print the structured `errors[]` (each `[code] message` on its own line),
list both candidate paths, and exit non-zero. Do NOT proceed to Phase 2.
Resolve the conflict by deleting the stale candidate (run
`/ultracontinue-local --cleanup --confirm <project-dir>` after the
`/trekcontinue --cleanup --confirm <project-dir>` after the
current session closes, or remove by hand).
- **If `valid: true` with a `NEXT_SESSION_PROMPT_WALL_CLOCK_DRIFT` warning**
@ -277,8 +277,8 @@ Read the file at `next_session_brief_path` (it is the brief that the next
session is supposed to execute — typically the same `brief.md` for
single-brief multi-session plans, or a session-specific spec for parallel
session decomposition). Understand the task and begin executing per the
standard ultraplan-local pipeline. The user did not type a separate "start"
command — `/ultracontinue` is the start.
standard trekplan pipeline. The user did not type a separate "start"
command — `/trekcontinue` is the start.
If the brief file does not exist (validator emits a warning but does not
fail), print: `Warning: next_session_brief_path "{path}" does not exist on
@ -295,7 +295,7 @@ if the env var is set; silently skip otherwise.
## Hard rules
- **Idempotent.** Running `/ultracontinue` twice in the same Claude session
- **Idempotent.** Running `/trekcontinue` twice in the same Claude session
does not advance state — the writer (Phase 8 / hook / helper) advances state
only when a session completes.
- **Zero secrets in the state file.** Status, paths, labels — never API keys,

34
plugins/ultraplan-local/commands/trekendsession.md
View file

@ -5,25 +5,25 @@ argument-hint: "<next-brief-path> <next-label> | --help"
model: sonnet
---
# Ultraplan End-Session Local v1.0
# Voyage End-Session Local v1.0
Tiny helper for **informal** multi-session flows (no formal plan with
Execution Strategy). Writes a `.session-state.local.json` pointing at the
next session so `/ultracontinue` can resume in a fresh Claude chat.
next session so `/trekcontinue` can resume in a fresh Claude chat.
For formal flows (a plan produced by `/ultraplan-local --project`),
`/ultraexecute-local` Phase 8 already writes the state file — this helper
For formal flows (a plan produced by `/trekplan --project`),
`/trekexecute` Phase 8 already writes the state file — this helper
is unnecessary there. Use this command for ad-hoc release runs, manual
multi-session handovers, or any flow that does not run through
`/ultraexecute-local`.
`/trekexecute`.
Pipeline position:
```
... session N work ...
/ultraplan-end-session-local <brief> "<next-label>" → writes state
/trekendsession <brief> "<next-label>" → writes state
... session boundary, fresh chat ...
/ultracontinue → reads state, starts session N+1
/trekcontinue → reads state, starts session N+1
```
See **Handover 7** in `docs/HANDOVER-CONTRACTS.md` for the schema.
@ -34,11 +34,11 @@ If `$ARGUMENTS` contains `--help` or `-h`, print the usage block below and exit
cleanly. Do NOT proceed to any further phase.
```
/ultraplan-end-session-local — Mark current session done; point at next session.
/trekendsession — Mark current session done; point at next session.
Usage:
/ultraplan-end-session-local <next-brief-path> <next-label>
/ultraplan-end-session-local --help
/trekendsession <next-brief-path> <next-label>
/trekendsession --help
Both arguments are REQUIRED. No interactive prompt — headless-safe.
@ -51,10 +51,10 @@ Writes <project-dir>/.session-state.local.json with:
updated_at <now, ISO-8601>
Then validates via lib/validators/session-state-validator.mjs and prints
the same 3-line narration that /ultracontinue will show in the next session.
the same 3-line narration that /trekcontinue will show in the next session.
Example:
/ultraplan-end-session-local .claude/projects/2026-05-01-feature/brief.md "Session 2 of 3"
/trekendsession .claude/projects/2026-05-01-feature/brief.md "Session 2 of 3"
```
## Phase 1 — Resolve project directory
@ -82,12 +82,12 @@ If either is missing or empty:
```
Error: missing required args.
Usage: /ultraplan-end-session-local <next-brief-path> '<next-label>'
Usage: /trekendsession <next-brief-path> '<next-label>'
```
Print to stderr and exit 1. **No interactive prompt** — this keeps the helper
headless-safe (per brief NFR; addresses adversarial-review major #11). If you
want an interactive flow, use `/ultracontinue --help` to see the full pipeline.
want an interactive flow, use `/trekcontinue --help` to see the full pipeline.
## Phase 3 — Atomically write `.session-state.local.json` + sibling NEXT-SESSION-PROMPT.local.md
@ -129,7 +129,7 @@ const stateObj = { schema_version: 1, project: dir, next_session_brief_path: bri
const stateFile = path.join(dir, '.session-state.local.json');
atomicWriteJson(stateFile, stateObj);
const promptFile = path.join(dir, 'NEXT-SESSION-PROMPT.local.md');
const promptBody = '---\\nproduced_by: trekendsession\\nproduced_at: ' + now + '\\nproject: ' + dir + '\\n---\\n\\n# ' + label + '\\n\\nResume via /ultracontinue.\\n';
const promptBody = '---\\nproduced_by: trekendsession\\nproduced_at: ' + now + '\\nproject: ' + dir + '\\n---\\n\\n# ' + label + '\\n\\nResume via /trekcontinue.\\n';
writeFileSync(promptFile, promptBody);
console.log(stateFile);
console.log(promptFile);
@ -144,7 +144,7 @@ Validate the freshly-written state file:
!`node lib/validators/session-state-validator.mjs --json <project-dir>/.session-state.local.json`
```
If `valid: true`, print the success block matching `/ultracontinue` Phase 3
If `valid: true`, print the success block matching `/trekcontinue` Phase 3
narration (SC-8 cross-project consistency — same template both sides):
```
@ -154,7 +154,7 @@ Project: <project-dir>
Next session: <next-label>
Brief: <next-brief-path>
In a fresh Claude session, run /ultracontinue to resume.
In a fresh Claude session, run /trekcontinue to resume.
```
If `valid: false`, print the structured `errors[]` and exit 1. Investigate

108
plugins/ultraplan-local/commands/trekexecute.md
View file

@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
# Ultraexecute Local
Disciplined executor for ultraplan plans. Reads a plan file, detects if it has
Disciplined executor for trekplan plans. Reads a plan file, detects if it has
an Execution Strategy (multi-session), and either executes directly or
orchestrates parallel headless sessions — all to realize one plan.
@ -25,7 +25,7 @@ Parse `$ARGUMENTS` for mode flags:
- If `{dir}` does not exist or `{dir}/plan.md` is missing:
```
Error: project directory missing plan.md: {dir}
Run /ultraplan-local --project {dir} to produce it.
Run /trekplan --project {dir} to produce it.
```
- If no explicit `<plan.md>` argument is provided after flag parsing,
use the derived `{dir}/plan.md`. If a `<plan.md>` argument IS provided,
@ -54,20 +54,20 @@ If no path is provided (and `--project` was not used to derive one), output
usage and stop:
```
Usage: /ultraexecute-local <plan.md>
/ultraexecute-local --project <dir>
/ultraexecute-local --fg <plan.md>
/ultraexecute-local --resume <plan.md>
/ultraexecute-local --dry-run <plan.md>
/ultraexecute-local --validate <plan.md>
/ultraexecute-local --step N <plan.md>
/ultraexecute-local --session N <plan.md>
/ultraexecute-local --project <dir> --resume
/ultraexecute-local --project <dir> --session N
Usage: /trekexecute <plan.md>
/trekexecute --project <dir>
/trekexecute --fg <plan.md>
/trekexecute --resume <plan.md>
/trekexecute --dry-run <plan.md>
/trekexecute --validate <plan.md>
/trekexecute --step N <plan.md>
/trekexecute --session N <plan.md>
/trekexecute --project <dir> --resume
/trekexecute --project <dir> --session N
Modes:
(default) Auto — multi-session if plan has Execution Strategy, else foreground
--project Resolve plan.md inside an ultrabrief project folder; progress.json
--project Resolve plan.md inside an trekbrief project folder; progress.json
is written there too
--fg Force foreground — all steps sequentially, ignore Execution Strategy
--resume Resume from last progress checkpoint
@ -77,13 +77,13 @@ Modes:
--session N Execute only session N from the plan's Execution Strategy
Examples:
/ultraexecute-local .claude/plans/ultraplan-2026-04-06-auth-refactor.md
/ultraexecute-local --project .claude/projects/2026-04-18-jwt-auth
/ultraexecute-local --project .claude/projects/2026-04-18-jwt-auth --resume
/ultraexecute-local --fg .claude/plans/ultraplan-2026-04-06-auth-refactor.md
/ultraexecute-local --session 2 .claude/plans/ultraplan-2026-04-06-auth-refactor.md
/ultraexecute-local --dry-run .claude/plans/ultraplan-2026-04-06-auth-refactor.md
/ultraexecute-local --validate .claude/plans/ultraplan-2026-04-06-auth-refactor.md
/trekexecute .claude/plans/trekplan-2026-04-06-auth-refactor.md
/trekexecute --project .claude/projects/2026-04-18-jwt-auth
/trekexecute --project .claude/projects/2026-04-18-jwt-auth --resume
/trekexecute --fg .claude/plans/trekplan-2026-04-06-auth-refactor.md
/trekexecute --session 2 .claude/plans/trekplan-2026-04-06-auth-refactor.md
/trekexecute --dry-run .claude/plans/trekplan-2026-04-06-auth-refactor.md
/trekexecute --validate .claude/plans/trekplan-2026-04-06-auth-refactor.md
```
If the file does not exist, report and stop:
@ -100,16 +100,16 @@ File: {path}
## Phase 2 — Detect file type and parse structure
Read the file. Determine whether it is an **ultraplan** or a **session spec**:
Read the file. Determine whether it is an **trekplan** or a **session spec**:
- **Session spec**: contains `## Dependencies` with `Entry condition:` AND `## Scope Fence`
AND `## Exit Condition` sections.
- **Ultraplan**: contains `## Implementation Plan` with numbered `### Step N:` headings
- **Voyage**: contains `## Implementation Plan` with numbered `### Step N:` headings
but no `## Scope Fence`.
If neither structure is detected, report and stop:
```
Error: unrecognized file format. Expected an ultraplan or session spec.
Error: unrecognized file format. Expected an trekplan or session spec.
```
### Parse steps
@ -226,7 +226,7 @@ Warnings: {count}
{if warnings}: - {each warning on own line}
Plan is schema-compliant. Safe to run:
/ultraexecute-local {path}
/trekexecute {path}
```
If Phase 2 parsing failed (unrecognized format, missing Manifest in strict
@ -240,15 +240,15 @@ Reason: {specific error from Phase 2}
{if format not recognized}:
Detected heading format: {e.g. "### Fase 1:", "## Phase 1"}
Expected: "### Step N: <description>"
Fix: re-run /ultraplan-local — planning-orchestrator must emit v1.7 format
Fix: re-run /trekplan — planning-orchestrator must emit v1.7 format
{if missing manifest}:
Step {N} has no Manifest block (plan_version=1.7 requires one per step)
Fix: re-run /ultraplan-local — planning-orchestrator must include manifest YAML
Fix: re-run /trekplan — planning-orchestrator must include manifest YAML
{if malformed YAML or invalid regex}:
Step {N}: {specific YAML/regex error}
Fix: edit the plan manually or re-run /ultraplan-local
Fix: edit the plan manually or re-run /trekplan
```
Exit after emitting the report. Do not continue to Phase 2.4 or later.
@ -390,13 +390,13 @@ Untracked/modified files:
{output of git status --porcelain}
Commit or stash your changes, then re-run.
To run sequentially instead: /ultraexecute-local --fg {plan-path}
To run sequentially instead: /trekexecute --fg {plan-path}
```
Stop execution. Update progress with `status: "stopped"`.
**Also write `.session-state.local.json`** (Handover 7) — this surfaces the
stopped state to `/ultracontinue` so the next session can prompt the user to
stopped state to `/trekcontinue` so the next session can prompt the user to
clean the working tree before resuming. Write atomically alongside `progress.json`:
```json
@ -458,7 +458,7 @@ that were manually edited or have bugs.
### Check 4 — Stale worktree cleanup
Run `git worktree list`. If any worktrees with paths containing
`ultraplan-sessions/{slug}/worktrees/` exist from a previous failed run:
`trekplan-sessions/{slug}/worktrees/` exist from a previous failed run:
```bash
git worktree remove --force {stale-path} 2>/dev/null
@ -532,7 +532,7 @@ If `ANTHROPIC_API_KEY` is NOT set: proceed silently to Step 1.
```bash
REPO_ROOT="$(git rev-parse --show-toplevel)"
SESSION_DIR="$REPO_ROOT/.claude/ultraplan-sessions/{slug}"
SESSION_DIR="$REPO_ROOT/.claude/trekplan-sessions/{slug}"
WORKTREE_DIR="$SESSION_DIR/worktrees"
LOG_DIR="$SESSION_DIR/logs"
mkdir -p "$WORKTREE_DIR" "$LOG_DIR"
@ -564,7 +564,7 @@ MAX_BUDGET_USD="${TREKEXECUTE_MAX_BUDGET_USD:-5}"
The budget caps default to safe values for normal-length steps. Operators may
override for long runs:
`TREKEXECUTE_MAX_TURNS=120 TREKEXECUTE_MAX_BUDGET_USD=20 /ultraexecute-local --project ...`
`TREKEXECUTE_MAX_TURNS=120 TREKEXECUTE_MAX_BUDGET_USD=20 /trekexecute --project ...`
**2a. Create worktrees for this wave's sessions:**
@ -651,7 +651,7 @@ For each session N in the wave:
```bash
SESSION_CWD="${session_cwd:-.}" # default: worktree root; overridable per-session via Execution Strategy `cwd:` field
cd "$WORKTREE_PATH/$SESSION_CWD" && \
GIT_OPTIONAL_LOCKS=0 claude -p "${SAFETY_PREAMBLE}\n\n/ultraexecute-local --session {N} {plan-path}" \
GIT_OPTIONAL_LOCKS=0 claude -p "${SAFETY_PREAMBLE}\n\n/trekexecute --session {N} {plan-path}" \
--allowedTools "Read,Write,Edit,Bash,Glob,Grep" \
--permission-mode bypassPermissions \
--max-turns "$MAX_TURNS" \
@ -690,7 +690,7 @@ wait {PID1} {PID2} ...
**2d. Check results after each wave:**
For each session in the wave, read its log file (in `$LOG_DIR`, always accessible
from the main worktree) and grep for `"ultraexecute_summary"`. Parse the JSON to
from the main worktree) and grep for `"trekexecute_summary"`. Parse the JSON to
determine:
- Did the session complete? (`result: "completed"`)
- Did it fail? (`result: "failed"` or `"stopped"`)
@ -719,7 +719,7 @@ unrecoverable failure to a recoverable one). Push failure is non-fatal
```bash
GIT_OPTIONAL_LOCKS=0 git push origin "trek/{slug}/session-{N}" 2>/dev/null || true
GIT_OPTIONAL_LOCKS=0 git merge --no-ff "trek/{slug}/session-{N}" \
-m "merge: ultraplan session {N} — {session-title}"
-m "merge: trekplan session {N} — {session-title}"
```
If the merge succeeds (exit code 0): continue to next session.
@ -823,12 +823,12 @@ The progress file location depends on whether `--project` is in use:
- **With `--project <dir>`:** progress lives at `{project_dir}/progress.json`.
- **Without `--project`:** progress lives at
`{plan-dir}/.ultraexecute-progress-{slug}.json`, where `{slug}` is the plan
`{plan-dir}/.trekexecute-progress-{slug}.json`, where `{slug}` is the plan
filename without extension.
**Session-scoped naming:** When `mode = session N`:
- With `--project`: `{project_dir}/progress-session-{N}.json`.
- Without `--project`: `{plan-dir}/.ultraexecute-progress-{slug}-session-{N}.json`.
- Without `--project`: `{plan-dir}/.trekexecute-progress-{slug}-session-{N}.json`.
This prevents merge conflicts when parallel sessions each write their own
progress file.
@ -879,7 +879,7 @@ progress file.
## Phase 4 — Entry condition check (session specs only)
**Skip for ultraplans.** Skip in dry-run mode (report what would be checked instead).
**Skip for trekplans.** Skip in dry-run mode (report what would be checked instead).
Read the entry condition. Evaluate it:
@ -899,14 +899,14 @@ Update progress file with `status: "stopped"`. Stop execution.
**Also write `.session-state.local.json`** (Handover 7) with the same
`status: "stopped"` and `next_session_brief_path` pointing at the brief that
the failed entry-condition session was supposed to consume. This lets
`/ultracontinue` surface the stop in the next session. Use the same atomic
`/trekcontinue` surface the stop in the next session. Use the same atomic
write pattern + validator check as Phase 2.55. On validator failure, warn
but do not block.
**Also write sibling `NEXT-SESSION-PROMPT.local.md`** with frontmatter
(`produced_by: trekexecute`, `produced_at: <ISO-8601>`,
`status: stopped`) — same combined ESM pattern as Phase 8 — so Phase 1.5
of `/ultracontinue` can compare project-dir and plugin-root candidates.
of `/trekcontinue` can compare project-dir and plugin-root candidates.
If the entry condition **passes**:
```
@ -948,9 +948,9 @@ If `has_execution_strategy = true`, show a preview of multi-session orchestratio
| Wave | Session | Steps | Depends on | Command |
|------|---------|-------|------------|---------|
| 1 | Session 1: {title} | {nums} | none | `claude -p "/ultraexecute-local --session 1 {path}"` |
| 1 | Session 2: {title} | {nums} | none | `claude -p "/ultraexecute-local --session 2 {path}"` |
| 2 | Session 3: {title} | {nums} | S1, S2 | `claude -p "/ultraexecute-local --session 3 {path}"` |
| 1 | Session 1: {title} | {nums} | none | `claude -p "/trekexecute --session 1 {path}"` |
| 1 | Session 2: {title} | {nums} | none | `claude -p "/trekexecute --session 2 {path}"` |
| 2 | Session 3: {title} | {nums} | S1, S2 | `claude -p "/trekexecute --session 3 {path}"` |
```
Check billing status via `echo "${ANTHROPIC_API_KEY:+SET}"` and report:
@ -1138,7 +1138,7 @@ If **FAIL**, read the `On failure:` clause. Apply the retry cap: **maximum 2 ret
`status: "passed"` in the progress file — collect their `Files:` fields. Never
use `git add -A` (risks staging secrets, binaries, or unrelated work).
```bash
git add {files from passed steps' Files: fields} && git commit -m "wip: ultraexecute-local stopped at step {N} — escalation needed"
git add {files from passed steps' Files: fields} && git commit -m "wip: trekexecute stopped at step {N} — escalation needed"
```
Jump to Phase 7.
@ -1170,7 +1170,7 @@ and jump to Phase 8 (final report).
## Phase 7 — Exit condition check (session specs only)
**Skip for ultraplans.** Run only when all steps passed (not on early stop).
**Skip for trekplans.** Run only when all steps passed (not on early stop).
Run each exit condition command from the `## Exit Condition` checklist:
@ -1230,7 +1230,7 @@ Record in progress file:
## Phase 7.6 — Recovery dispatch (multi-session parent context only)
**Preconditions:**
- This is the parent ultraexecute invocation (not a child `--session N`)
- This is the parent trekexecute invocation (not a child `--session N`)
- Phase 7.5 reported `drift`
- `recovery_depth < 2` (hard cap to prevent infinite loops)
@ -1256,7 +1256,7 @@ the user for manual resolution.
**Invoke the recovery session:**
```bash
cd "$WORKTREE_PATH" && claude -p "/ultraexecute-local --session {N} {recovery spec path}" \
cd "$WORKTREE_PATH" && claude -p "/trekexecute --session {N} {recovery spec path}" \
--allowedTools "Read,Write,Edit,Bash,Glob,Grep" \
--permission-mode bypassPermissions \
> "$LOG_DIR/session-{N}-recovery-{depth}.log" 2>&1
@ -1320,11 +1320,11 @@ node ${CLAUDE_PLUGIN_ROOT}/lib/stats/event-emit.mjs \
```
**Recovery surface:** if declined, `--resume re-enters at the gate` —
re-running `/ultraexecute-local --resume --project <dir>` jumps directly
re-running `/trekexecute --resume --project <dir>` jumps directly
back to the main-merge gate AskUserQuestion (skipping completed waves).
The wave session branches are preserved for inspection (Hard Rule 19's
push-before-cleanup ensures they survive on the remote even if local
cleanup ran). To inspect: `git log ultraplan/<slug>/session-N` per wave.
cleanup ran). To inspect: `git log trekplan/<slug>/session-N` per wave.
### Progress + state-file writes
@ -1353,7 +1353,7 @@ to stderr but do NOT block — Phase 8 must always reach the final report.
**Also write sibling `NEXT-SESSION-PROMPT.local.md`** (Bug 3 frontmatter
contract — see `docs/HANDOVER-CONTRACTS.md` § Handover 7 Lifecycle) in the
project directory. The frontmatter MUST contain `produced_by: trekexecute`
and `produced_at: <ISO-8601>` so `/ultracontinue` Phase 1.5 can detect
and `produced_at: <ISO-8601>` so `/trekcontinue` Phase 1.5 can detect
producer drift between project-dir and plugin-root candidates. Use a single
ESM inline block so state-file + prompt-file writes succeed or fail together:
@ -1366,7 +1366,7 @@ const [, dir, briefPath, label, status] = process.argv;
const now = new Date().toISOString();
const stateObj = { schema_version: 1, project: dir, next_session_brief_path: briefPath, next_session_label: label, status, updated_at: now };
atomicWriteJson(path.join(dir, '.session-state.local.json'), stateObj);
const promptBody = '---\\nproduced_by: trekexecute\\nproduced_at: ' + now + '\\nproject: ' + dir + '\\nstatus: ' + status + '\\n---\\n\\n# ' + label + '\\n\\nResume via /ultracontinue.\\n';
const promptBody = '---\\nproduced_by: trekexecute\\nproduced_at: ' + now + '\\nproject: ' + dir + '\\nstatus: ' + status + '\\n---\\n\\n# ' + label + '\\n\\nResume via /trekcontinue.\\n';
writeFileSync(path.join(dir, 'NEXT-SESSION-PROMPT.local.md'), promptBody);
" '{project_dir}' '{next_session_brief_path}' '{next_session_label}' '{status}'`
```
@ -1426,7 +1426,7 @@ Attempts: {N}
{Numbered list of unexecuted steps}
To resume: /ultraexecute-local --resume {path}
To resume: /trekexecute --resume {path}
```
**Result vocabulary (v1.7, strict):**
@ -1441,7 +1441,7 @@ To resume: /ultraexecute-local --resume {path}
```json
{
"ultraexecute_summary": {
"trekexecute_summary": {
"plan": "{path}",
"plan_type": "{plan | session-spec}",
"plan_version": "{1.7 | 1.6 | legacy}",
@ -1464,7 +1464,7 @@ To resume: /ultraexecute-local --resume {path}
}
```
The `ultraexecute_summary` key makes it grep-able in log files from headless runs.
The `trekexecute_summary` key makes it grep-able in log files from headless runs.
## Phase 9 — Stats tracking

86
plugins/ultraplan-local/commands/trekplan.md
View file

@ -6,24 +6,24 @@ model: opus
allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, TaskCreate, TaskUpdate, TeamCreate, TeamDelete
---
# Ultraplan Local v2.0
# Voyage Local v2.0
Deep, multi-phase implementation planning driven by a **task brief**.
Planning consumes the brief (produced by `/ultrabrief-local`) and any
Planning consumes the brief (produced by `/trekbrief`) and any
research briefs referenced in it, then runs specialized exploration
agents, synthesis, and adversarial review to produce an executable plan.
**v2.0 is a breaking release.** The interview phase has been extracted
into `/ultrabrief-local`. This command no longer accepts free-text task
into `/trekbrief`. This command no longer accepts free-text task
descriptions — it requires either `--brief <path>` or `--project <dir>`.
Pipeline position:
```
/ultrabrief-local → brief.md
/ultraresearch-local → research/*.md
/ultraplan-local → plan.md (this command)
/ultraexecute-local → execution
/trekbrief → brief.md
/trekresearch → research/*.md
/trekplan → plan.md (this command)
/trekexecute → execution
```
## Phase 1 — Parse mode and validate input
@ -57,7 +57,7 @@ Parse `$ARGUMENTS` for mode flags. Order of precedence:
- Research briefs auto-discovered from `{dir}/research/*.md` (sorted).
- If `{dir}` does not exist or `{dir}/brief.md` is missing:
```
Error: project directory not initialized. Run /ultrabrief-local to create it.
Error: project directory not initialized. Run /trekbrief to create it.
Missing: {dir}/brief.md
```
- Set **project_dir = {dir}**, **brief_path = {dir}/brief.md**.
@ -119,15 +119,15 @@ Parse `$ARGUMENTS` for mode flags. Order of precedence:
output usage and stop:
```
Usage: /ultraplan-local --brief <path-to-brief.md>
/ultraplan-local --project <project-dir>
/ultraplan-local --brief <path> --research <research-brief.md>
/ultraplan-local --project <dir> --fg
/ultraplan-local --project <dir> --quick
/ultraplan-local --export <pr|issue|markdown|headless> <plan-path>
/ultraplan-local --decompose <plan-path>
Usage: /trekplan --brief <path-to-brief.md>
/trekplan --project <project-dir>
/trekplan --brief <path> --research <research-brief.md>
/trekplan --project <dir> --fg
/trekplan --project <dir> --quick
/trekplan --export <pr|issue|markdown|headless> <plan-path>
/trekplan --decompose <plan-path>
A brief is required. Produce one with /ultrabrief-local first.
A brief is required. Produce one with /trekbrief first.
Modes:
--brief Plan from a brief file (foreground, v2.4.0+)
@ -139,12 +139,12 @@ Modes:
--decompose Split an existing plan into self-contained headless sessions
Examples:
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth
/ultraplan-local --brief .claude/projects/2026-04-18-jwt-auth/brief.md
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth --research extra.md
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth --fg
/ultraplan-local --export pr .claude/plans/ultraplan-2026-04-06-rate-limiting.md
/ultraplan-local --decompose .claude/plans/ultraplan-2026-04-06-rate-limiting.md
/trekplan --project .claude/projects/2026-04-18-jwt-auth
/trekplan --brief .claude/projects/2026-04-18-jwt-auth/brief.md
/trekplan --project .claude/projects/2026-04-18-jwt-auth --research extra.md
/trekplan --project .claude/projects/2026-04-18-jwt-auth --fg
/trekplan --export pr .claude/plans/trekplan-2026-04-06-rate-limiting.md
/trekplan --decompose .claude/plans/trekplan-2026-04-06-rate-limiting.md
Migrating from v1.x? See MIGRATION.md in this plugin. The old --spec flag
and free-text interview mode were removed in v2.0.
@ -176,13 +176,13 @@ Project: {project_dir or "-"}
Research: {N local briefs, M extra via --research}
```
### When the input is type:ultrareview (Handover 6)
### When the input is type:trekreview (Handover 6)
The brief input may be a `review.md` produced by `/ultrareview-local`
instead of a `brief.md` produced by `/ultrabrief-local`. Both files
The brief input may be a `review.md` produced by `/trekreview`
instead of a `brief.md` produced by `/trekbrief`. Both files
share the same handover slot — `type` is the discriminator.
If `fm.type === 'ultrareview'`:
If `fm.type === 'trekreview'`:
1. Skip the `research_status` gate above (review.md has no
`research_topics` and no Research Plan section).
@ -249,7 +249,7 @@ Output a markdown block formatted as a PR description:
{Risks from plan, abbreviated to 1 line each}
---
*Generated by ultraplan-local from {plan filename}*
*Generated by trekplan from {plan filename}*
```
### Format: `issue`
@ -270,7 +270,7 @@ Output a markdown block formatted as an issue comment:
{Top 2–3 risks from plan}
---
*Generated by ultraplan-local*
*Generated by trekplan*
```
### Format: `markdown`
@ -303,19 +303,19 @@ Then **stop**. Do not continue to any subsequent phase.
Read the plan file. Verify it contains an Implementation Plan section with
numbered steps. If no steps are found, report and stop:
```
Error: plan has no implementation steps. Run /ultraplan-local first to generate a plan.
Error: plan has no implementation steps. Run /trekplan first to generate a plan.
```
Determine the output directory from the plan slug:
- Extract the slug from the plan filename (e.g., `ultraplan-2026-04-06-auth-refactor` → `auth-refactor`)
- Output directory: `.claude/ultraplan-sessions/{slug}/`
- Extract the slug from the plan filename (e.g., `trekplan-2026-04-06-auth-refactor` → `auth-refactor`)
- Output directory: `.claude/trekplan-sessions/{slug}/`
Launch the **session-decomposer** agent:
```
Plan file: {plan path}
Plugin root: ${CLAUDE_PLUGIN_ROOT}
Output directory: .claude/ultraplan-sessions/{slug}/
Output directory: .claude/trekplan-sessions/{slug}/
```
The session-decomposer will:
@ -334,7 +334,7 @@ When the session-decomposer completes, present the summary to the user:
**Master plan:** {plan path}
**Sessions:** {N} across {W} waves
**Output:** .claude/ultraplan-sessions/{slug}/
**Output:** .claude/trekplan-sessions/{slug}/
### Sessions
@ -344,14 +344,14 @@ When the session-decomposer completes, present the summary to the user:
### Files generated
- Session specs: .claude/ultraplan-sessions/{slug}/session-*.md
- Dependency graph: .claude/ultraplan-sessions/{slug}/dependency-graph.md
- Launch script: .claude/ultraplan-sessions/{slug}/launch.sh
- Session specs: .claude/trekplan-sessions/{slug}/session-*.md
- Dependency graph: .claude/trekplan-sessions/{slug}/dependency-graph.md
- Launch script: .claude/trekplan-sessions/{slug}/launch.sh
You can:
- Review individual session specs before running
- Run all sessions: `bash .claude/ultraplan-sessions/{slug}/launch.sh`
- Run a single session: `claude -p "$(cat .claude/ultraplan-sessions/{slug}/session-1-*.md)"`
- Run all sessions: `bash .claude/trekplan-sessions/{slug}/launch.sh`
- Run a single session: `claude -p "$(cat .claude/trekplan-sessions/{slug}/session-1-*.md)"`
- Say **"launch"** to start headless execution from here
```
@ -361,7 +361,7 @@ Then **stop**. Do not continue to any subsequent phase.
## Phase 2 — (removed in v2.0)
The interview phase has moved to `/ultrabrief-local`. This command no
The interview phase has moved to `/trekbrief`. This command no
longer asks the user any requirements questions — the brief is the
authoritative input.
@ -372,7 +372,7 @@ Determine the plan destination path:
frontmatter field): **plan destination = {project_dir}/plan.md**.
- Otherwise: derive slug and date — if the brief has frontmatter `slug` and
`created`, use them; otherwise extract from the brief filename. Destination:
`.claude/plans/ultraplan-{YYYY-MM-DD}-{slug}.md`.
`.claude/plans/trekplan-{YYYY-MM-DD}-{slug}.md`.
Collect all research briefs (from `--research` flag and auto-discovered
`{project_dir}/research/*.md`).
@ -677,7 +677,7 @@ Write the plan following the template structure. The plan MUST include:
Use the plan destination computed in Phase 3:
- `--project` mode: `{project_dir}/plan.md`
- `--brief` mode: `.claude/plans/ultraplan-{YYYY-MM-DD}-{slug}.md`
- `--brief` mode: `.claude/plans/trekplan-{YYYY-MM-DD}-{slug}.md`
Create the parent directory if it does not exist.
@ -731,7 +731,7 @@ After both complete:
Present a summary to the user:
```
## Ultraplan Complete
## Voyage Complete
**Task:** {task description}
**Mode:** {foreground | quick}
@ -835,7 +835,7 @@ Never let tracking failures block the main workflow.
brief (Intent, Goal, Constraint, Preference, NFR, Success Criterion). If a
step has no brief basis, it is scope creep — flag it or remove it.
- **No interview**: Never ask the user requirements questions. If the brief is
inadequate, stop and ask the user to run `/ultrabrief-local` again.
inadequate, stop and ask the user to run `/trekbrief` again.
- **Scope**: Only explore the current working directory and its subdirectories.
Never read files outside the repo (no ~/.env, no credentials, no other repos).
- **Cost**: Sonnet for all agents (exploration, deep-dives, research, critics).

50
plugins/ultraplan-local/commands/trekresearch.md
View file

@ -17,9 +17,9 @@ external research could provide alone.
specialized agents, each seeing only what they need. The value is in triangulation
(cross-checking local vs. external) and synthesis (insights from combining both).
**Pipeline integration:** Research briefs feed into ultraplan via `--research`:
**Pipeline integration:** Research briefs feed into trekplan via `--research`:
```
/ultraresearch-local <question> → brief → /ultraplan-local --research <brief> <task>
/trekresearch <question> → brief → /trekplan --research <brief> <task>
```
## Phase 1 — Parse mode and validate input
@ -43,14 +43,14 @@ Supported flags:
is always foreground as of v2.4.0. Set **execution = foreground** (the
only mode).
5. `--project <dir>` — attach this research to an ultrabrief project folder.
5. `--project <dir>` — attach this research to an trekbrief project folder.
The brief will be written to `{dir}/research/{NN}-{slug}.md` (auto-incremented
index) instead of the default `.claude/research/` path. Set **project_dir = {dir}**.
If `{dir}` does not exist:
```
Error: project directory not found: {dir}
Run /ultrabrief-local first to create it.
Run /trekbrief first to create it.
```
Create `{dir}/research/` if it does not already exist.
@ -75,12 +75,12 @@ After stripping flags, the remaining text is the **research question**.
If no research question is provided, output usage and stop:
```
Usage: /ultraresearch-local <research question>
/ultraresearch-local --quick <research question>
/ultraresearch-local --local <research question>
/ultraresearch-local --external <research question>
/ultraresearch-local --fg <research question>
/ultraresearch-local --project <dir> [--external|--local|--quick|--fg] <research question>
Usage: /trekresearch <research question>
/trekresearch --quick <research question>
/trekresearch --local <research question>
/trekresearch --external <research question>
/trekresearch --fg <research question>
/trekresearch --project <dir> [--external|--local|--quick|--fg] <research question>
Modes:
default Interview → foreground research (local + external) → brief
@ -88,17 +88,17 @@ Modes:
--local Only codebase analysis agents (skip external + Gemini)
--external Only external research agents (skip codebase analysis)
--fg No-op alias (foreground is the only mode as of v2.4.0)
--project Write brief into an ultrabrief project folder (auto-indexed)
--project Write brief into an trekbrief project folder (auto-indexed)
Flags can be combined: --local, --external --quick, --project <dir> --external
Examples:
/ultraresearch-local Should we migrate from Express to Fastify?
/ultraresearch-local --quick What auth libraries are popular for Node.js?
/ultraresearch-local --local How is error handling structured in this codebase?
/ultraresearch-local --external What are the security implications of using Redis for sessions?
/ultraresearch-local --fg --local What patterns does this codebase use for database access?
/ultraresearch-local --project .claude/projects/2026-04-18-jwt-auth --external What JWT library is best for Node.js?
/trekresearch Should we migrate from Express to Fastify?
/trekresearch --quick What auth libraries are popular for Node.js?
/trekresearch --local How is error handling structured in this codebase?
/trekresearch --external What are the security implications of using Redis for sessions?
/trekresearch --fg --local What patterns does this codebase use for database access?
/trekresearch --project .claude/projects/2026-04-18-jwt-auth --external What JWT library is best for Node.js?
```
Do not continue past this step if no question was provided.
@ -119,7 +119,7 @@ If **project_dir is set**:
- Brief destination: `{project_dir}/research/{NN}-{slug}.md`
If **project_dir is not set**:
- Brief destination: `.claude/research/ultraresearch-{YYYY-MM-DD}-{slug}.md`
- Brief destination: `.claude/research/trekresearch-{YYYY-MM-DD}-{slug}.md`
Store as `brief_destination` for use in later phases.
@ -127,7 +127,7 @@ Store as `brief_destination` for use in later phases.
Use `AskUserQuestion` to clarify the research question. Ask **one question at a time**.
The interview is shorter than ultraplan's (2-4 questions, not 3-8) because research
The interview is shorter than trekplan's (2-4 questions, not 3-8) because research
is more focused than planning.
### Interview flow
@ -292,7 +292,7 @@ other agents — the value of Gemini is independence.
- Launch ALL selected agents **in parallel** in a single message
- Use model: "sonnet" for all sub-agents (the orchestrator runs on Opus)
- Scale maxTurns by codebase size for local agents (same as ultraplan):
- Scale maxTurns by codebase size for local agents (same as trekplan):
small = halved, medium/large = default
- convention-scanner: medium+ codebases only (50+ files)
@ -308,7 +308,7 @@ If no gaps exist, skip: "Initial research sufficient — no follow-ups needed."
## Phase 6 — Triangulation
This is the KEY phase that makes ultraresearch more than aggregation.
This is the KEY phase that makes trekresearch more than aggregation.
For each research dimension:
@ -346,7 +346,7 @@ Write the research brief following the template. Key rules:
Generate the slug from the research question (first 3-4 meaningful words).
Write the brief to the `brief_destination` computed in Phase 1:
- With `--project`: `{project_dir}/research/{NN}-{slug}.md`
- Without `--project`: `.claude/research/ultraresearch-{YYYY-MM-DD}-{slug}.md`
- Without `--project`: `.claude/research/trekresearch-{YYYY-MM-DD}-{slug}.md`
Create the parent directory if it does not exist.
@ -378,8 +378,8 @@ Present a summary to the user:
You can:
- Read the full brief at {brief_destination}
- If `--project` was used: run `/ultraplan-local --project {project_dir}` when all research topics are complete
- Otherwise: `/ultraplan-local --research {brief_destination} --brief <your-brief.md>`
- If `--project` was used: run `/trekplan --project {project_dir}` when all research topics are complete
- Otherwise: `/trekplan --research {brief_destination} --brief <your-brief.md>`
- Ask follow-up questions about specific findings
```
@ -413,7 +413,7 @@ If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip tracking silently.
## Hard rules
- **No planning:** This command produces research briefs, not implementation plans.
If the user asks to plan, direct them to `/ultraplan-local --research <brief>`.
If the user asks to plan, direct them to `/trekplan --research <brief>`.
- **Sources required:** Every claim must cite a source. No unsourced findings.
- **Independence:** Do not pre-bias external agents with local findings or vice versa.
Triangulate AFTER independent research.

32
plugins/ultraplan-local/commands/trekreview.md
View file

@ -11,19 +11,19 @@ allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion
# Ultrareview Local v1.0
Independent post-hoc review of code delivered by `/ultraexecute-local`
Independent post-hoc review of code delivered by `/trekexecute`
against the contract in `brief.md`. Produces `review.md` — a structured
artifact with severity-tagged findings that `/ultraplan-local --brief
artifact with severity-tagged findings that `/trekplan --brief
review.md` can consume as plan input (Handover 6).
Pipeline position:
```
/ultrabrief-local → brief.md
/ultraresearch-local → research/*.md
/ultraplan-local → plan.md
/ultraexecute-local → progress.json (+ commits)
/ultrareview-local → review.md (this command)
/trekbrief → brief.md
/trekresearch → research/*.md
/trekplan → plan.md
/trekexecute → progress.json (+ commits)
/trekreview → review.md (this command)
```
The review is **independent**: each reviewer runs without cross-feeding,
@ -38,15 +38,15 @@ command executes inline.
Parse `$ARGUMENTS` via the shared arg-parser:
```bash
node ${CLAUDE_PLUGIN_ROOT}/lib/parsers/arg-parser.mjs --command ultrareview "$@"
node ${CLAUDE_PLUGIN_ROOT}/lib/parsers/arg-parser.mjs --command trekreview "$@"
```
The parser recognizes these flags (see `lib/parsers/arg-parser.mjs`
FLAG_SCHEMA `ultrareview` entry):
FLAG_SCHEMA `trekreview` entry):
| Flag | Type | Purpose |
|------|------|---------|
| `--project <dir>` | valued | Required. Path to ultraplan-local project folder containing `brief.md`. |
| `--project <dir>` | valued | Required. Path to trekplan project folder containing `brief.md`. |
| `--since <ref>` | valued | Optional. Override "before" SHA for the diff. Validated via `git rev-parse --verify`. |
| `--quick` | boolean | Skip the brief-conformance pass; run only the code-correctness reviewer; skip the coordinator's reasonableness filter. |
| `--validate` | boolean | Schema-only check on existing `{project_dir}/review.md`. No LLM calls. |
@ -57,7 +57,7 @@ Resolution:
1. If `--project` is missing, print usage and stop:
```
Error: --project <dir> is required.
Usage: /ultrareview-local --project <dir> [--since <ref>] [--quick] [--validate] [--dry-run]
Usage: /trekreview --project <dir> [--since <ref>] [--quick] [--validate] [--dry-run]
```
2. Trim trailing slash from `{dir}`. Set:
- `project_dir = {dir}`
@ -65,7 +65,7 @@ Resolution:
- `review_path = {dir}/review.md`
3. If `{dir}` does not exist or `{dir}/brief.md` is missing:
```
Error: project directory not initialized. Run /ultrabrief-local first.
Error: project directory not initialized. Run /trekbrief first.
Missing: {dir}/brief.md
```
@ -87,7 +87,7 @@ node ${CLAUDE_PLUGIN_ROOT}/lib/validators/brief-validator.mjs --soft --json "{br
Read the JSON output. If `valid: false` AND any error has code
`BRIEF_MISSING_REQUIRED_FIELD` or `FRONTMATTER_PARSE_ERROR`: stop and
ask the user to re-run `/ultrabrief-local`. Other soft errors become
ask the user to re-run `/trekbrief`. Other soft errors become
warnings in the review's Executive Summary.
Read the brief frontmatter. Capture for review.md:
@ -299,13 +299,13 @@ After the write succeeds, print:
You can:
- Read the full review at {review_path}
- Feed BLOCKER + MAJOR findings into a follow-up plan:
/ultraplan-local --brief {review_path}
/trekplan --brief {review_path}
- Re-run with `--quick` for a faster correctness-only pass
- Re-run with `--since <ref>` to narrow scope
```
Per **Handover 6**, BLOCKER and MAJOR findings are consumed by
`/ultraplan-local --brief review.md` to produce a remediation plan. The
`/trekplan --brief review.md` to produce a remediation plan. The
review's frontmatter `findings:` list and the trailing JSON block are
the contract for that handover (see `docs/HANDOVER-CONTRACTS.md`).
@ -330,7 +330,7 @@ the contract for that handover (see `docs/HANDOVER-CONTRACTS.md`).
- **Refuse-with-suggestion above 100 files / 100K tokens.** Never run
blind on a giant diff. Use AskUserQuestion to surface the gate.
- **Cost.** Sonnet for all sub-agents (reviewers + coordinator). Opus
only runs in the main /ultrareview-local command thread.
only runs in the main /trekreview command thread.
- **Privacy.** Never log secrets, tokens, or credentials in review.md.
Findings citing files with secret-like content must redact the secret
in the `detail` field.

86
plugins/ultraplan-local/docs/HANDOVER-CONTRACTS.md
View file

@ -1,6 +1,6 @@
# Handover Contracts (ultra-suite local pipeline)
# Handover Contracts (voyage-suite local pipeline)
This document is the single source of truth for the file formats that pass between the four commands of the `ultraplan-local` pipeline. When you fork the plugin or extend a stage, the contracts below tell you what every producer must write and what every consumer is allowed to assume.
This document is the single source of truth for the file formats that pass between the four commands of the `trekplan` pipeline. When you fork the plugin or extend a stage, the contracts below tell you what every producer must write and what every consumer is allowed to assume.
For each handover, the same headings appear in the same order: **Producer**, **Consumer**, **Path conventions**, **Frontmatter schema**, **Body invariants**, **Validation strategy**, **Versioning**, **Failure modes**.
@ -11,7 +11,7 @@ Each artifact carries an explicit version field. Schema bumps are coordinated:
| Artifact | Field | Current |
|---|---|---|
| `brief.md` | `brief_version` (frontmatter) | `2.0` |
| `research/*.md` | (implicit; tracked via `type: ultraresearch-brief`) | unversioned |
| `research/*.md` | (implicit; tracked via `type: trekresearch-brief`) | unversioned |
| `plan.md` | `plan_version` (frontmatter) | `1.7` |
| `progress.json` | `schema_version` (top-level) | `"1"` |
| `review.md` | `review_version` (frontmatter) | `1.0` |
@ -43,9 +43,9 @@ Every validator exposes a CLI: `node lib/validators/<name>.mjs --json <path>` re
## Handover 1 — `brief.md` → research/
**Producer:** `/ultrabrief-local` Phase 4g (after `brief-reviewer` stop-gate passes or iteration cap is hit).
**Producer:** `/trekbrief` Phase 4g (after `brief-reviewer` stop-gate passes or iteration cap is hit).
**Consumer:** `/ultraresearch-local` Phase 1 (mode parse + brief validation).
**Consumer:** `/trekresearch` Phase 1 (mode parse + brief validation).
**Path conventions:**
- Project-dir mode (recommended): `.claude/projects/{YYYY-MM-DD}-{slug}/brief.md`.
@ -55,7 +55,7 @@ Every validator exposes a CLI: `node lib/validators/<name>.mjs --json <path>` re
| Field | Type | Required | Allowed values | Notes |
|---|---|---|---|---|
| `type` | string | yes | `ultrabrief` | Hard-coded discriminator |
| `type` | string | yes | `trekbrief` | Hard-coded discriminator |
| `brief_version` | string | yes | `"2.0"` (current) | Bump on schema change |
| `created` | date | yes | YYYY-MM-DD | |
| `task` | string | yes | one-line description | |
@ -81,7 +81,7 @@ Optional but standard sections: `## Non-Goals`, `## Constraints`, `## Preference
|---|---|---|
| Frontmatter parse | every read | YAML subset; reject nested dicts |
| Required fields | every read | All `BRIEF_REQUIRED_FRONTMATTER` present |
| Type discriminator | every read | `type === "ultrabrief"` |
| Type discriminator | every read | `type === "trekbrief"` |
| Status enum | every read | `research_status ∈ allowed values` |
| **State machine** | every read | `research_topics > 0 && research_status === "skipped"` requires `brief_quality === "partial"` |
| Body sections | strict only | All `BRIEF_BODY_SECTIONS` present |
@ -102,19 +102,19 @@ Optional but standard sections: `## Non-Goals`, `## Constraints`, `## Preference
## Handover 2 — research/*.md → plan
**Producer:** `/ultraresearch-local` Phase 7 (synthesis + brief writer).
**Producer:** `/trekresearch` Phase 7 (synthesis + brief writer).
**Consumer:** `/ultraplan-local` Phase 1 (project-dir auto-discovery) + `planning-orchestrator` (consumes findings as context).
**Consumer:** `/trekplan` Phase 1 (project-dir auto-discovery) + `planning-orchestrator` (consumes findings as context).
**Path conventions:**
- Project-dir mode: `.claude/projects/{YYYY-MM-DD}-{slug}/research/{NN}-{topic-slug}.md` (sorted by filename).
- Legacy: `.claude/research/ultraresearch-{date}-{slug}.md`.
- Legacy: `.claude/research/trekresearch-{date}-{slug}.md`.
**Frontmatter schema:**
| Field | Type | Required | Allowed values |
|---|---|---|---|
| `type` | string | yes | `ultraresearch-brief` |
| `type` | string | yes | `trekresearch-brief` |
| `created` | date | yes | YYYY-MM-DD |
| `question` | string | yes | the research question |
| `confidence` | number | optional | `[0.0, 1.0]` — strongly recommended |
@ -145,14 +145,14 @@ Optional: `## Local Context`, `## External Knowledge`, `## Triangulation`, `## S
**Producer:** external opt-in architect plugin (no longer publicly distributed).
**Consumer:** `/ultraplan-local` Phase 1 (architecture-discovery) + `planning-orchestrator` Phase 7 (cross-reference architecture-note as priors during synthesis).
**Consumer:** `/trekplan` Phase 1 (architecture-discovery) + `planning-orchestrator` Phase 7 (cross-reference architecture-note as priors during synthesis).
**Path conventions:**
- Canonical: `{project_dir}/architecture/overview.md`
- Optional: `{project_dir}/architecture/gaps.md`
- Tolerated alternatives (with warning): `architecture-overview.md`, `overview.markdown`, `README.md`
**Frontmatter schema:** **unenforced.** This is the external contract — `ultraplan-local` does not validate the format. We sniff only the first H1 heading.
**Frontmatter schema:** **unenforced.** This is the external contract — `trekplan` does not validate the format. We sniff only the first H1 heading.
**Body invariants:** **unenforced.** We never read body content beyond the first heading.
@ -177,11 +177,11 @@ The validator (`lib/validators/architecture-discovery.mjs`) is intentionally min
**Producer:** `planning-orchestrator` Phase 5 (plan synthesis) + Phase 5.5 (schema self-check via `plan-validator --strict`).
**Consumer:** `/ultraexecute-local` Phase 2 (plan parsing) + `--validate` mode.
**Consumer:** `/trekexecute` Phase 2 (plan parsing) + `--validate` mode.
**Path conventions:**
- Project-dir: `{project_dir}/plan.md`
- Legacy: `.claude/plans/ultraplan-{date}-{slug}.md`
- Legacy: `.claude/plans/trekplan-{date}-{slug}.md`
**Frontmatter schema:**
@ -207,7 +207,7 @@ The validator (`lib/validators/architecture-discovery.mjs`) is intentionally min
**Validation strategy:**
The strongest validation in the entire pipeline. Phase 5.5 (planning-orchestrator) **must** run `plan-validator --strict` before handing the plan to plan-critic. `--validate` mode of `/ultraexecute-local` runs the same check + `progress-validator`.
The strongest validation in the entire pipeline. Phase 5.5 (planning-orchestrator) **must** run `plan-validator --strict` before handing the plan to plan-critic. `--validate` mode of `/trekexecute` runs the same check + `progress-validator`.
| Code | Meaning | Recovery |
|---|---|---|
@ -228,13 +228,13 @@ The strongest validation in the entire pipeline. Phase 5.5 (planning-orchestrato
## Handover 5 — `progress.json` (resume contract)
**Producer:** `/ultraexecute-local` per-step (after Verify + Manifest audit + Checkpoint).
**Producer:** `/trekexecute` per-step (after Verify + Manifest audit + Checkpoint).
**Consumer:** `/ultraexecute-local --resume` (re-entry) + `pre-compact-flush` hook (drift detection before context compaction).
**Consumer:** `/trekexecute --resume` (re-entry) + `pre-compact-flush` hook (drift detection before context compaction).
**Path conventions:**
- Project-dir: `{project_dir}/progress.json`
- Legacy: `{plan-dir}/.ultraexecute-progress-{slug}.json`
- Legacy: `{plan-dir}/.trekexecute-progress-{slug}.json`
**Schema (top-level):**
@ -268,11 +268,11 @@ The strongest validation in the entire pipeline. Phase 5.5 (planning-orchestrato
| `note` | string | optional human-readable annotation |
**Validation strategy:** `progress-validator.mjs` runs at:
1. `/ultraexecute-local --validate` (alongside plan-validator)
2. `/ultraexecute-local --resume` entry (must pass `checkResumeReadiness`)
1. `/trekexecute --validate` (alongside plan-validator)
2. `/trekexecute --resume` entry (must pass `checkResumeReadiness`)
3. `pre-compact-flush` hook (drift check before compaction; never blocks)
**Drift detection:** the `pre-compact-flush` hook compares `progress.steps[N].commit` against `git log --oneline {session_start_sha}..HEAD`. If git reality has progressed past the recorded `current_step`, the hook updates progress.json atomically (`tmp + rename`, monotonic only) before allowing compaction. This guards against the documented P0 drift in `docs/ultraexecute-v2-observations-from-config-audit-v4.md`.
**Drift detection:** the `pre-compact-flush` hook compares `progress.steps[N].commit` against `git log --oneline {session_start_sha}..HEAD`. If git reality has progressed past the recorded `current_step`, the hook updates progress.json atomically (`tmp + rename`, monotonic only) before allowing compaction. This guards against the documented P0 drift in `docs/trekexecute-v2-observations-from-config-audit-v4.md`.
**Versioning:** `schema_version: "1"` is current. Future bump (e.g. `"2"`) should add a backward-compat read path that downgrades unknown fields to warnings.
@ -290,9 +290,9 @@ The strongest validation in the entire pipeline. Phase 5.5 (planning-orchestrato
**Handover 6 closes the iteration loop.** Where Handovers 1–4 flow forward (brief → research → plan → execute) and Handover 5 makes execute resumable, Handover 6 routes review findings *back* into planning so a remediation plan can be produced with full traceability via `source_findings`.
**Producer:** `/ultrareview-local` Phase 7 (write `review.md` after coordinator dedup + verdict).
**Producer:** `/trekreview` Phase 7 (write `review.md` after coordinator dedup + verdict).
**Consumer:** `/ultraplan-local` Phase 1 when `--brief review.md` is supplied and the consumer detects `type: ultrareview` in frontmatter. The plan command branches into a remediation-plan path: BLOCKER + MAJOR findings become plan goals, the produced `plan.md` carries a `source_findings: [<id>, ...]` frontmatter list as the audit trail back to the consumed findings. MINOR + SUGGESTION are skipped for v1.0 plan-input.
**Consumer:** `/trekplan` Phase 1 when `--brief review.md` is supplied and the consumer detects `type: trekreview` in frontmatter. The plan command branches into a remediation-plan path: BLOCKER + MAJOR findings become plan goals, the produced `plan.md` carries a `source_findings: [<id>, ...]` frontmatter list as the audit trail back to the consumed findings. MINOR + SUGGESTION are skipped for v1.0 plan-input.
**Path conventions:**
- Project-dir mode (recommended): `{project_dir}/review.md` (one per review iteration; subsequent runs overwrite atomically).
@ -302,7 +302,7 @@ The strongest validation in the entire pipeline. Phase 5.5 (planning-orchestrato
| Field | Type | Required | Allowed values | Notes |
|---|---|---|---|---|
| `type` | string | yes | `ultrareview` | Hard-coded discriminator |
| `type` | string | yes | `trekreview` | Hard-coded discriminator |
| `review_version` | string | yes | `"1.0"` (current) | Bump on schema change |
| `task` | string | yes | one-line description | Mirrors brief task |
| `slug` | string | yes | URL-safe slug | Used in project_dir |
@ -330,12 +330,12 @@ Optional but standard sections: `## Findings (BLOCKER)`, `## Findings (MAJOR)`,
|---|---|---|
| Frontmatter parse | every read | YAML subset; reject nested dicts |
| Required fields | every read | All `REVIEW_REQUIRED_FRONTMATTER` present |
| Type discriminator | every read | `type === "ultrareview"` |
| Type discriminator | every read | `type === "trekreview"` |
| Findings shape | every read | Array of strings, each matching `^[0-9a-f]{40}$` |
| Body sections | strict only | `Executive Summary`, `Coverage`, `Remediation Summary` |
| Version format | every read | `review_version` matches `N.M`; warning otherwise |
The validator (`lib/validators/review-validator.mjs`) exposes the same CLI as the others: `node lib/validators/review-validator.mjs --json <review.md>`. Strict mode is the default; `--soft` downgrades section-missing errors to warnings. `/ultrareview-local` Phase 8 runs `--strict`. `/ultraplan-local` Phase 1 (when consuming `--brief review.md`) runs `--soft` so a partially-valid review can still seed a plan.
The validator (`lib/validators/review-validator.mjs`) exposes the same CLI as the others: `node lib/validators/review-validator.mjs --json <review.md>`. Strict mode is the default; `--soft` downgrades section-missing errors to warnings. `/trekreview` Phase 8 runs `--strict`. `/trekplan` Phase 1 (when consuming `--brief review.md`) runs `--soft` so a partially-valid review can still seed a plan.
**Versioning:** current is `1.0`. There are no live `0.x` reviews. Future schema changes follow the breaking-change protocol above.
@ -343,7 +343,7 @@ The validator (`lib/validators/review-validator.mjs`) exposes the same CLI as th
- `REVIEW_NOT_FOUND` → consumer halts with usage message
- `REVIEW_READ_ERROR` → I/O failure; halt
- `FM_MISSING` → file has no frontmatter; halt
- `REVIEW_WRONG_TYPE` → `type !== "ultrareview"`; halt
- `REVIEW_WRONG_TYPE` → `type !== "trekreview"`; halt
- `REVIEW_MISSING_FIELD` → strict halt; soft-mode warning
- `REVIEW_BAD_FINDINGS_TYPE` → `findings` is not an array; halt (covers the YAML flow-style trap)
- `REVIEW_BAD_FINDING_ID` → an ID is not 40-char hex; halt
@ -354,17 +354,17 @@ The validator (`lib/validators/review-validator.mjs`) exposes the same CLI as th
## Handover 7 — `.session-state.local.json`
**Handover 7 enables zero-friction multi-session resumption.** Where Handover 5 (`progress.json`) makes a single execute run resumable after a crash inside that session, Handover 7 makes a *multi-session* plan resumable across fresh Claude Code chats. The state file is the contract; any session-end mechanism may write it; `/ultracontinue` only reads.
**Handover 7 enables zero-friction multi-session resumption.** Where Handover 5 (`progress.json`) makes a single execute run resumable after a crash inside that session, Handover 7 makes a *multi-session* plan resumable across fresh Claude Code chats. The state file is the contract; any session-end mechanism may write it; `/trekcontinue` only reads.
**Producer:**
- `/ultraexecute-local` Phase 8 (canonical convergence — every completed/failed/stopped/partial run that reaches the final report)
- `/ultraexecute-local` Phase 2.55 (Check 1 — dirty-tree pre-flight stop)
- `/ultraexecute-local` Phase 4 (entry-condition stop)
- `/ultraplan-end-session-local` (informal multi-session helper — Step 9 of v3.3.0)
- `/trekexecute` Phase 8 (canonical convergence — every completed/failed/stopped/partial run that reaches the final report)
- `/trekexecute` Phase 2.55 (Check 1 — dirty-tree pre-flight stop)
- `/trekexecute` Phase 4 (entry-condition stop)
- `/trekendsession` (informal multi-session helper — Step 9 of v3.3.0)
- *Future:* `graceful-handoff` v2.2 may dual-write here as part of its session-rescue artifact (additive — extra fields tolerated, see Body invariants).
- `hooks/scripts/pre-compact-flush.mjs` *refreshes* `updated_at` on existing state files (status `in_progress` or `partial` only). Never creates the file; never changes status or owned fields.
**Consumer:** `/ultracontinue` (read-only). Reads the file, validates it, narrates a 3-line summary, then begins executing the next session by reading `next_session_brief_path`.
**Consumer:** `/trekcontinue` (read-only). Reads the file, validates it, narrates a 3-line summary, then begins executing the next session by reading `next_session_brief_path`.
**Path conventions:**
- Per-project: `.claude/projects/{YYYY-MM-DD}-{slug}/.session-state.local.json` — one file per project directory.
@ -384,7 +384,7 @@ The validator (`lib/validators/review-validator.mjs`) exposes the same CLI as th
**Body invariants:** N/A (JSON).
**Forward-compat — drift-WARN principle:** Unknown top-level keys are **silently tolerated**. The validator does not warn on extras. This is a load-bearing decision: it lets future writers (graceful-handoff v2.2, custom plugin extensions) add metadata fields without breaking `/ultracontinue`. Mirrors Handover 3's discovery-only, drift-WARN posture.
**Forward-compat — drift-WARN principle:** Unknown top-level keys are **silently tolerated**. The validator does not warn on extras. This is a load-bearing decision: it lets future writers (graceful-handoff v2.2, custom plugin extensions) add metadata fields without breaking `/trekcontinue`. Mirrors Handover 3's discovery-only, drift-WARN posture.
**Validation strategy:**
@ -404,12 +404,12 @@ The validator (`lib/validators/session-state-validator.mjs`) exposes the standar
**Versioning:** Current is `1` (number). Schema is **additive only** — new optional fields land without bumping schema_version (forward-compat tolerates them). A breaking change (renaming a field, narrowing the status enum) requires bumping schema_version to `2`, adding migration support in the validator, and following the breaking-change protocol above.
**Failure modes:**
- `SESSION_STATE_NOT_FOUND` → `/ultracontinue` exits with cold-start message ("no active multi-session project here; start with `/ultrabrief-local` or `/ultraplan-local`")
- `SESSION_STATE_NOT_FOUND` → `/trekcontinue` exits with cold-start message ("no active multi-session project here; start with `/trekbrief` or `/trekplan`")
- `SESSION_STATE_PARSE_ERROR` → halt with structured error; user fixes JSON
- `SESSION_STATE_MISSING_FIELD` → halt; suggests running validator directly
- `SESSION_STATE_SCHEMA_MISMATCH` → halt; future `1` → `2` migration path will warn instead
- `SESSION_STATE_INVALID_STATUS` → halt; protects against typo'd writers
- `SESSION_STATE_NOT_RESUMABLE` → warning; `/ultracontinue` exits cleanly with "no further sessions to resume; project complete"
- `SESSION_STATE_NOT_RESUMABLE` → warning; `/trekcontinue` exits cleanly with "no further sessions to resume; project complete"
- Validator failures during writer Phase 8 emit a stderr warning but DO NOT block the session-end report. `progress.json` remains the authoritative record of what was attempted.
### § Lifecycle
@ -420,12 +420,12 @@ The state file follows a producer/consumer separation that keeps responsibilitie
| Role | Owners | Phase / location |
|---|---|---|
| Producer (writes the state file) | `/ultraexecute-local` | Phase 8 (canonical), Phase 2.55 (dirty-tree pre-flight stop), Phase 4 (entry-condition stop) |
| Producer (informal multi-session helper) | `/ultraplan-end-session-local` | Phase 3 — writes the same schema for ad-hoc handovers that don't run through executor |
| Producer (writes the state file) | `/trekexecute` | Phase 8 (canonical), Phase 2.55 (dirty-tree pre-flight stop), Phase 4 (entry-condition stop) |
| Producer (informal multi-session helper) | `/trekendsession` | Phase 3 — writes the same schema for ad-hoc handovers that don't run through executor |
| Refresher (touch only) | `hooks/scripts/pre-compact-flush.mjs` | Updates `updated_at` only; never creates the file; never changes `status` or any owned field; only acts when `status` is `in_progress` or `partial` |
| Consumer | `/ultracontinue-local` | Phase 2 — reads, validates, narrates a 3-line summary, then begins executing the next session |
| Consumer | `/trekcontinue` | Phase 2 — reads, validates, narrates a 3-line summary, then begins executing the next session |
**Stale-file principle (SC-5):** When `status === 'completed'`, the state file and its sibling `NEXT-SESSION-PROMPT.local.md` represent finished work and SHOULD be removed. Removal is **operator-invoked** via `/ultracontinue-local --cleanup --confirm <project-dir>`; the plugin does NOT auto-cleanup. Stale state is actively harmful — it can mislead a fresh `/ultracontinue` into resuming a project that's already shipped. The `--cleanup` gate refuses to act unless `validateSessionState({...}).valid === true && parsed.status === 'completed'`. There is no force flag.
**Stale-file principle (SC-5):** When `status === 'completed'`, the state file and its sibling `NEXT-SESSION-PROMPT.local.md` represent finished work and SHOULD be removed. Removal is **operator-invoked** via `/trekcontinue --cleanup --confirm <project-dir>`; the plugin does NOT auto-cleanup. Stale state is actively harmful — it can mislead a fresh `/trekcontinue` into resuming a project that's already shipped. The `--cleanup` gate refuses to act unless `validateSessionState({...}).valid === true && parsed.status === 'completed'`. There is no force flag.
**Frontmatter contract for `NEXT-SESSION-PROMPT.local.md`:** Producers MUST write a YAML frontmatter block on the prompt file with at minimum:
@ -434,7 +434,7 @@ The state file follows a producer/consumer separation that keeps responsibilitie
The `next-session-prompt-validator` (`lib/validators/next-session-prompt-validator.mjs`) cross-checks `produced_at` against the sibling state file's `updated_at` and emits a `NEXT_SESSION_PROMPT_INCONSISTENT` error when the prompt is older than the state — that means the prompt has not been refreshed for the current session and is stale. Files **without** any frontmatter are tolerated (warning, not error) for backwards compatibility with v3.3.x and earlier hand-rolled prompt files; this is consistent with Handover 3's drift-WARN posture.
**Idempotency:** `--cleanup --confirm` is safe to re-run. If only one of the two files (state file, prompt file) was previously deleted, the second run reports the partial state ("state file: not found, prompt file: removed") but does not auto-recover or re-create. There is no rollback. Operators choosing to re-create a project after `--cleanup` should re-run `/ultrabrief-local` from scratch.
**Idempotency:** `--cleanup --confirm` is safe to re-run. If only one of the two files (state file, prompt file) was previously deleted, the second run reports the partial state ("state file: not found, prompt file: removed") but does not auto-recover or re-create. There is no rollback. Operators choosing to re-create a project after `--cleanup` should re-run `/trekbrief` from scratch.
---
@ -448,6 +448,6 @@ The `next-session-prompt-validator` (`lib/validators/next-session-prompt-validat
| 4. plan → execute | **strict, both ends** | this plugin | medium — Opus 4.7 narrative drift requires constant vigilance |
| 5. progress.json | shape + resume readiness | this plugin | medium — drift during compaction handled by pre-compact-flush hook (CC v2.1.105+) |
| 6. review → plan | strict at write, soft at read | this plugin | low — additive feedback loop; consumer falls back gracefully when source_findings is absent |
| 7. session-state (multi-session resume) | required-fields + status enum + drift-WARN extras | this plugin | low — readers tolerate unknown keys; writers are owned by ultraexecute Phase 8 + helper command |
| 7. session-state (multi-session resume) | required-fields + status enum + drift-WARN extras | this plugin | low — readers tolerate unknown keys; writers are owned by trekexecute Phase 8 + helper command |
When extending the plugin or adding a new pipeline stage, follow the same pattern: produce an artifact with a versioned frontmatter (or `schema_version` for JSON), write a validator under `lib/validators/`, add fixtures under `tests/fixtures/`, and add an entry to this document.

42
plugins/ultraplan-local/docs/subagent-delegation-audit.md
View file

@ -2,11 +2,11 @@
**Status:** Exploratory brief — findings + options, not a decision
**Date:** 2026-04-19
**Scope:** ultraplan-local v2.3.2, all six user-facing commands
**Scope:** trekplan v2.3.2, all six user-facing commands
## Problem
Main context fills up quickly during ultraplan-local runs. The plugin's
Main context fills up quickly during trekplan runs. The plugin's
design principle is Context Engineering — the main context should
**orchestrate**, subagents should **execute**. In practice, the exploration
phases do delegate aggressively, but the **synthesis and writing phases
@ -21,11 +21,11 @@ Agent-spawn density per command (nominal):
| Command | Agents spawned |
|--------------------------|-------------------------------------------------------------------|
| ultraresearch-local | ~9–14 (5 local + 4 external + 1 bridge + up to 2 follow-ups) |
| ultraplan-local | ~10 (6 initial + conditional research-scout + up to 3 deep-dives) |
| ultrabrief-local | 1–3 (brief-reviewer per iteration, max 3) |
| ultraexecute-local | 0 (explicit no-agent rule) |
| ultra-skill-author-local | 3 (concept-extractor → skill-drafter → ip-hygiene-checker) |
| trekresearch | ~9–14 (5 local + 4 external + 1 bridge + up to 2 follow-ups) |
| trekplan | ~10 (6 initial + conditional research-scout + up to 3 deep-dives) |
| trekbrief | 1–3 (brief-reviewer per iteration, max 3) |
| trekexecute | 0 (explicit no-agent rule) |
| voyage-skill-author-local | 3 (concept-extractor → skill-drafter → ip-hygiene-checker) |
This part is healthy.
@ -33,27 +33,27 @@ This part is healthy.
The main context does the heavy cognitive work after swarm completion:
- **`commands/ultraplan-local.md:483–498` (Phase 7 Synthesis):**
- **`commands/trekplan.md:483–498` (Phase 7 Synthesis):**
"Read all agent results carefully" + "Build a mental model of the codebase
architecture" + "Catalog reusable code" + "Integrate research findings".
This forces 6–10 agent outputs to remain resident in main context simultaneously.
- **`commands/ultraplan-local.md:499–548` (Phase 8 Deep Planning):**
- **`commands/trekplan.md:499–548` (Phase 8 Deep Planning):**
Main context writes the entire plan.md from scratch, including all required
sections, quality standards, and file-path validation.
- **`commands/ultraresearch-local.md:302–323` (Phase 6 Triangulation):**
Explicitly labelled "the KEY phase that makes ultraresearch more than
- **`commands/trekresearch.md:302–323` (Phase 6 Triangulation):**
Explicitly labelled "the KEY phase that makes trekresearch more than
aggregation". Dimension-by-dimension comparison of local vs external
findings, contradiction flagging, confidence rating — all inline.
- **`commands/ultraresearch-local.md:325–341` (Phase 7 Synthesis):**
- **`commands/trekresearch.md:325–341` (Phase 7 Synthesis):**
Writes the research brief inline using the template.
### 3. Root cause — v2.4.0 foreground migration
Each command carries a `> **Why foreground?**` block
(`ultraplan-local.md:330`, `ultraresearch-local.md:192`) documenting that the
(`trekplan.md:330`, `trekresearch.md:192`) documenting that the
background orchestrators were removed because agents spawned from background
orchestrators silently degraded. The swarm-spawn logic was lifted into the
main context — but so was the synthesis logic the orchestrators used to
@ -66,10 +66,10 @@ are rough estimates based on the size of the phase bodies — not measured.
| # | Intervention | Target phase | Rough saving |
|---|---------------------------------------------------------------------|-------------------------------------|--------------|
| 1 | `synthesis-agent` — digests all exploration outputs into findings + reuse catalog + gaps | ultraplan Phase 7 | 40–50% |
| 2 | `plan-writer-agent` — writes plan.md from synthesis + template | ultraplan Phase 8 | part of #1 |
| 3 | `triangulation-synthesizer` — per-dimension local vs external diff + confidence rating | ultraresearch Phase 6 | 25–30% |
| 4 | `research-brief-writer` — writes research brief from triangulation output | ultraresearch Phase 7 | part of #3 |
| 1 | `synthesis-agent` — digests all exploration outputs into findings + reuse catalog + gaps | trekplan Phase 7 | 40–50% |
| 2 | `plan-writer-agent` — writes plan.md from synthesis + template | trekplan Phase 8 | part of #1 |
| 3 | `triangulation-synthesizer` — per-dimension local vs external diff + confidence rating | trekresearch Phase 6 | 25–30% |
| 4 | `research-brief-writer` — writes research brief from triangulation output | trekresearch Phase 7 | part of #3 |
## Tradeoffs (important)
@ -98,7 +98,7 @@ are rough estimates based on the size of the phase bodies — not measured.
## Recommendation (tentative)
If only one change is made, **intervention #1 (synthesis-agent for
ultraplan Phase 7)** has the largest ROI. It isolates the heaviest read
trekplan Phase 7)** has the largest ROI. It isolates the heaviest read
(all 6–10 agent outputs) behind a summarizer, and its output — a compact
findings document — is small enough to keep resident for Phase 8 planning
and Phase 9 review.
@ -116,7 +116,7 @@ that could validate the pattern before touching the main planner.
3. Is there a way to measure current main-context usage per phase so the
savings estimates above can be replaced with real numbers before
committing to changes?
4. Does this interact with `REMEMBER.md`'s note that "ultraplan schema-drift
4. Does this interact with `REMEMBER.md`'s note that "trekplan schema-drift
on 4.7 produces Phase-plans instead of v1.7 step-schema"? A writer-agent
might either help (isolated, more controllable) or hurt (another layer
where drift can happen) the schema-drift problem.
@ -124,6 +124,6 @@ that could validate the pattern before touching the main planner.
## Out of scope for this brief
- Implementation details of the new agents
- Changes to ultraexecute-local (no-agent by design)
- Changes to ultrabrief-local Phase 3 interview (must be inline to drive
- Changes to trekexecute (no-agent by design)
- Changes to trekbrief Phase 3 interview (must be inline to drive
user dialogue)

4
plugins/ultraplan-local/examples/01-add-verbose-flag/REGENERATED.md
View file

@ -3,7 +3,7 @@
| Field | Value |
|-------|-------|
| Last regenerated | 2026-05-01 |
| ultraplan-local version | 3.1.0 |
| trekplan version | 3.1.0 |
| Claude Code version | ≥ 2.1.105 (PreCompact-hook) |
| Source brief author | Hand-calibrated example, not LLM-generated |
| Plan author | Hand-calibrated to demonstrate plan_version 1.7 schema + manifest YAML |
@ -53,4 +53,4 @@ small-auth/
```
This project is **not** in the plugin repo. The example artifacts
reference it as if it were the cwd of an `/ultraexecute-local` run.
reference it as if it were the cwd of an `/trekexecute` run.

2
plugins/ultraplan-local/examples/01-add-verbose-flag/brief.md
View file

@ -1,5 +1,5 @@
---
type: ultrabrief
type: trekbrief
brief_version: 1.0
slug: add-verbose-flag
task: Add a --verbose flag to the small-auth CLI parser

2
plugins/ultraplan-local/examples/01-add-verbose-flag/plan.md
View file

@ -4,7 +4,7 @@ plan_version: 1.7
> **Plan quality: A** (92/100) — APPROVE
>
> Generated by ultraplan-local v3.1.0 on 2026-05-01.
> Generated by trekplan v3.1.0 on 2026-05-01.
## Context

2
plugins/ultraplan-local/examples/01-add-verbose-flag/research/01-cli-parser-conventions.md
View file

@ -1,5 +1,5 @@
---
type: ultraresearch-brief
type: trekresearch-brief
research_version: 1.0
question: How does small-auth currently parse arguments and where should --verbose hook in?
confidence: 0.85

24
plugins/ultraplan-local/examples/02-real-cli/REGENERATED.md
View file

@ -2,7 +2,7 @@
| Field | Value |
|-------|-------|
| Calibrated against | ultraplan-local v3.4.1 |
| Calibrated against | trekplan v3.4.1 |
| Last regenerated | 2026-05-04 (B3 session) |
| Source brief author | Hand-authored by operator (B1 session, 2026-05-04) |
| Baseline author | B2 session, 2026-05-04 (commit `c8146c1`) |
@ -10,7 +10,7 @@
## What this example demonstrates
`examples/02-real-cli/` is the first **runnable** ultraplan-local example.
`examples/02-real-cli/` is the first **runnable** trekplan example.
Unlike `examples/01-add-verbose-flag/` (which ships a frozen brief, plan,
and research as artifacts but no executable code), this example ships a
working ~80-line Node.js CLI (`tally`), a passing test suite, and known
@ -18,8 +18,8 @@ fixture data — all designed to be the input for a real pipeline run.
The fixture's purpose is twofold:
1. **End-to-end pipeline validation:** running `/ultraresearch-local`,
`/ultraplan-local`, and `/ultraexecute-local` against `brief.md` must
1. **End-to-end pipeline validation:** running `/trekresearch`,
`/trekplan`, and `/trekexecute` against `brief.md` must
produce green commits that satisfy all 10 brief Success Criteria. This
is the controlled environment used to verify pipeline correctness on
release-validation passes (see "Regeneration triggers" below).
@ -68,7 +68,7 @@ The pipeline ran against `brief.md` (research_topics: 0, hand-authored).
Each phase produced an artifact in
`.claude/projects/2026-05-04-examples-02-real-cli/`.
### `/ultraresearch-local`
### `/trekresearch`
**Outcome: skipped (intentionally).**
@ -83,11 +83,11 @@ The brief's "Research Plan" section is explicit:
Following the prompt's guidance ("Ikke kjør Gemini-bridge eller
community-researcher for trivielle Node-stdlib-spørsmål"), the swarm was
not invoked. No research file was written; `research/` directory does not
exist for this project. Downstream commands (`/ultraplan-local`) auto-discover
exist for this project. Downstream commands (`/trekplan`) auto-discover
research files but do not require them — the missing directory is fine
per the soft-mode `research-validator` contract.
### `/ultraplan-local`
### `/trekplan`
**Outcome: plan.md with 4 steps; plan-validator strict PASS;
plan-critic 0 BLOCKER (4 MAJOR fixed in revision); scope-guardian
@ -126,7 +126,7 @@ require named symbols (`flags.regex`, `compileRegex`, `--regex 'fo+'`,
`-r short form`, `invalid regex`) so the verifier confirms substantive
changes, not just file modifications.
### `/ultraexecute-local`
### `/trekexecute`
**Outcome: 4 commits, all green, all `verify_passed: true`.**
@ -180,12 +180,12 @@ Constraint compliance:
## How to re-run this example
```bash
cd /path/to/ultraplan-local
cd /path/to/trekplan
# 1. Re-run the pipeline against the existing brief
# (research is skipped — research_topics: 0)
/ultraplan-local --project .claude/projects/2026-05-04-examples-02-real-cli
/ultraexecute-local --project .claude/projects/2026-05-04-examples-02-real-cli
/trekplan --project .claude/projects/2026-05-04-examples-02-real-cli
/trekexecute --project .claude/projects/2026-05-04-examples-02-real-cli
# 2. Verify all 10 Success Criteria from brief.md hold (commands above)
node --test examples/02-real-cli/tests/tally.test.mjs # 14 pass
@ -209,7 +209,7 @@ triggers" below).
When to re-run this example:
- ultraplan-local minor version bump (e.g. v3.4 → v3.5)
- trekplan minor version bump (e.g. v3.4 → v3.5)
- `plan_version` schema bump
- Manifest YAML required-key additions
- `progress.json` schema bump

18
plugins/ultraplan-local/examples/README.md
View file

@ -1,13 +1,13 @@
# Examples
Complete kalibrerte walk-throughs of the ultraplan-local pipeline for
Complete kalibrerte walk-throughs of the trekplan pipeline for
realistic tasks. Each example shows the four artifacts a project
directory contains after a full run:
- `brief.md` — task brief from `/ultrabrief-local`
- `research/*.md` — research briefs from `/ultraresearch-local`
- `plan.md` — implementation plan from `/ultraplan-local`
- `progress.json` — execution log from `/ultraexecute-local`
- `brief.md` — task brief from `/trekbrief`
- `research/*.md` — research briefs from `/trekresearch`
- `plan.md` — implementation plan from `/trekplan`
- `progress.json` — execution log from `/trekexecute`
These are **hand-calibrated**, not LLM-generated. The point is to give
a fork-er a deterministic reference — what the artifacts look like
@ -19,10 +19,10 @@ For your own work, point the four commands at a real project directory:
```bash
mkdir -p .claude/projects/2026-05-01-my-task
/ultrabrief-local
/ultraresearch-local --project .claude/projects/2026-05-01-my-task
/ultraplan-local --project .claude/projects/2026-05-01-my-task
/ultraexecute-local --project .claude/projects/2026-05-01-my-task
/trekbrief
/trekresearch --project .claude/projects/2026-05-01-my-task
/trekplan --project .claude/projects/2026-05-01-my-task
/trekexecute --project .claude/projects/2026-05-01-my-task
```
The artifacts in each example mirror that flow.

6
plugins/ultraplan-local/hooks/scripts/post-bash-stats.mjs
View file

@ -3,11 +3,11 @@
//
// Captures duration_ms from PostToolUse payload for Bash tool calls and
// appends a structured stats line to ${CLAUDE_PLUGIN_DATA}/trekexecute-stats.jsonl
// when the running session is an ultraexecute session.
// when the running session is an trekexecute session.
//
// Detection: only fires when the tool input matches the verify/checkpoint
// pattern of an ultraexecute step (i.e., the command was issued from inside
// /ultraexecute-local). We err on the side of "log everything in plugin
// pattern of an trekexecute step (i.e., the command was issued from inside
// /trekexecute). We err on the side of "log everything in plugin
// scope" — duration data is cheap and the alternative is missing real
// per-step timings.
//

2
plugins/ultraplan-local/hooks/scripts/post-compact-flush.mjs
View file

@ -2,7 +2,7 @@
// Hook: post-compact-flush.mjs
// Event: PostCompact (Claude Code v2.1.105+)
// Purpose: Re-inject .session-state.local.json after compaction so
// /ultracontinue and `/ultraexecute-local --resume` see fresh
// /trekcontinue and `/trekexecute --resume` see fresh
// session-state and the model has Handover 7 context immediately
// after a context-compaction event.
//

6
plugins/ultraplan-local/hooks/scripts/pre-compact-flush.mjs
View file

@ -2,12 +2,12 @@
// Hook: pre-compact-flush.mjs
// Event: PreCompact (Claude Code v2.1.105+)
// Purpose: Flush progress.json drift before context compaction so
// /ultraexecute-local --resume works after long conversations.
// /trekexecute --resume works after long conversations.
// Direct fix for the documented P0 in
// docs/ultraexecute-v2-observations-from-config-audit-v4.md.
// docs/trekexecute-v2-observations-from-config-audit-v4.md.
//
// v3.3.0: also refreshes sibling .session-state.local.json
// (Handover 7) so /ultracontinue can detect a resumable session
// (Handover 7) so /trekcontinue can detect a resumable session
// even after a compaction event mid-run.
//
// Behavior:

4
plugins/ultraplan-local/hooks/scripts/session-title.mjs
View file

@ -1,11 +1,11 @@
#!/usr/bin/env node
// session-title.mjs — UserPromptSubmit hook (CC v2.1.94+)
//
// Sets a sessionTitle when the user invokes one of the four ultra commands,
// Sets a sessionTitle when the user invokes one of the four voyage commands,
// so multi-session headless runs are easy to identify in process lists and
// session pickers.
//
// Title format: ultra:<command>:<slug>
// Title format: voyage:<command>:<slug>
// - <command> ∈ {brief, research, plan, execute, review}
// - <slug> ∈ first 30 chars of project slug, or "ad-hoc" when no
// --project / --brief context is detected

2
plugins/ultraplan-local/lib/parsers/arg-parser.mjs
View file

@ -1,5 +1,5 @@
// lib/parsers/arg-parser.mjs
// Parse $ARGUMENTS strings for the four ultra commands.
// Parse $ARGUMENTS strings for the four voyage commands.
//
// Each command has its own valid-flag set; passing flags from another command
// produces an `unknown_flags` array but does not error — the caller decides.

2
plugins/ultraplan-local/lib/parsers/finding-id.mjs
View file

@ -1,5 +1,5 @@
// lib/parsers/finding-id.mjs
// Stable finding-ID for /ultrareview-local v1.0.
// Stable finding-ID for /trekreview v1.0.
//
// id = sha1(file:line:rule_key) → 40-char hex.
// Same input always produces same output (determinism floor SC4).

2
plugins/ultraplan-local/lib/review/plan-review-dedup.mjs
View file

@ -1,5 +1,5 @@
// lib/review/plan-review-dedup.mjs
// Phase-9 dedup helper for /ultraplan-local adversarial review:
// Phase-9 dedup helper for /trekplan adversarial review:
// merges plan-critic + scope-guardian findings into a single deduplicated
// stream, preserving provenance (which agent originally raised each finding).
//

2
plugins/ultraplan-local/lib/review/rule-catalogue.mjs
View file

@ -1,5 +1,5 @@
// lib/review/rule-catalogue.mjs
// Canonical rule catalogue for /ultrareview-local v1.0.
// Canonical rule catalogue for /trekreview v1.0.
//
// 12 rule keys, 4-tier severity (matches brief contract).
// llm-security 5-tier alignment is a v1.1 candidate.

2
plugins/ultraplan-local/lib/stats/cache-analyzer.mjs
View file

@ -2,7 +2,7 @@
// Summarizes trekexecute-stats.jsonl: total events, percentile wall times,
// time range. Companion to event-emit.mjs (which produces the jsonl).
//
// Designed for /ultraplan-local Spor C: gives C3 telemetry context when
// Designed for /trekplan Spor C: gives C3 telemetry context when
// interpreting Q3 experiment numbers (5+ weeks of accumulated data on the
// operator's machine as of 2026-05-04).
//

2
plugins/ultraplan-local/lib/util/autonomy-gate.mjs
View file

@ -1,5 +1,5 @@
// lib/util/autonomy-gate.mjs
// Autonomy-gate state machine for /ultraexecute-local + /ultraplan-local
// Autonomy-gate state machine for /trekexecute + /trekplan
// (plan-v2 Step 4 — drives the --gates flag).
//
// States:

8
plugins/ultraplan-local/lib/util/cleanup.mjs
View file

@ -1,7 +1,7 @@
// lib/util/cleanup.mjs
// Bug 4 — operator-invoked cleanup of completed-project state files.
//
// The ultraplan-local pipeline does NOT auto-cleanup state on session-end:
// The trekplan pipeline does NOT auto-cleanup state on session-end:
// stale .session-state.local.json + NEXT-SESSION-PROMPT.local.md across many
// projects accumulate over time. This util removes them safely once the
// project is fully done (status === 'completed' as seen by validateSessionState).
@ -11,7 +11,7 @@
// - Idempotent: re-running on a partially-cleaned dir succeeds with deleted: [].
// - Refuses dryRun: false without an explicit confirm: true (prevents accidents).
// - ENOENT counts as "already absent" — never an error.
// - Cleanup is operator-invoked from /ultracontinue --cleanup; no Bash binding here.
// - Cleanup is operator-invoked from /trekcontinue --cleanup; no Bash binding here.
import { existsSync, unlinkSync } from 'node:fs';
import { join } from 'node:path';
@ -24,7 +24,7 @@ const CANDIDATE_FILES = Object.freeze([
]);
/**
* Clean up state files for a completed ultraplan project.
* Clean up state files for a completed trekplan project.
*
* @param {string} projectDir - absolute or cwd-relative path to the project directory
* @param {{dryRun?: boolean, confirm?: boolean}} [opts]
@ -68,7 +68,7 @@ export function cleanupProject(projectDir, opts = {}) {
return fail(issue(
'CLEANUP_NOT_COMPLETED',
`Refused: status is "${validation.parsed.status}", not "completed"`,
'cleanup is reserved for fully-finished projects. Resume via /ultracontinue or wait until the run completes.',
'cleanup is reserved for fully-finished projects. Resume via /trekcontinue or wait until the run completes.',
));
}

2
plugins/ultraplan-local/lib/validators/brief-validator.mjs
View file

@ -1,5 +1,5 @@
// lib/validators/brief-validator.mjs
// Validate ultrabrief frontmatter + body invariants.
// Validate trekbrief frontmatter + body invariants.
import { readFileSync, existsSync } from 'node:fs';
import { parseDocument } from '../util/frontmatter.mjs';

2
plugins/ultraplan-local/lib/validators/next-session-prompt-validator.mjs
View file

@ -3,7 +3,7 @@
//
// Producers (trekexecute Phase 8/2.55/4, trekendsession Phase 3) MUST write
// `produced_by:` and `produced_at:` (ISO-8601) frontmatter.
// Consumers (/ultracontinue Phase 1.5) compare two candidate files and refuse
// Consumers (/trekcontinue Phase 1.5) compare two candidate files and refuse
// when producers disagree on a non-stale pair.
//
// Schema is forward-compatible: unknown frontmatter keys are tolerated.

2
plugins/ultraplan-local/lib/validators/review-validator.mjs
View file

@ -1,5 +1,5 @@
// lib/validators/review-validator.mjs
// Validate ultrareview frontmatter + body invariants.
// Validate trekreview frontmatter + body invariants.
// 3-layer pattern (Content → File → CLI shim) mirroring brief-validator.
import { readFileSync, existsSync } from 'node:fs';

6
plugins/ultraplan-local/lib/validators/session-state-validator.mjs
View file

@ -1,5 +1,5 @@
// lib/validators/session-state-validator.mjs
// Validate .session-state.local.json — the contract consumed by /ultracontinue.
// Validate .session-state.local.json — the contract consumed by /trekcontinue.
// Schema v1 documented in docs/HANDOVER-CONTRACTS.md (Handover 7).
import { readFileSync, existsSync } from 'node:fs';
@ -18,8 +18,8 @@ export const SESSION_STATE_REQUIRED_TOP = [
// session is not resumable. Unknown statuses fail.
export const SESSION_STATE_VALID_STATUSES = ['in_progress', 'partial', 'failed', 'stopped', 'completed'];
// Statuses that /ultracontinue can resume from. `completed` is intentionally
// excluded — running ultracontinue on a completed project should signal "no
// Statuses that /trekcontinue can resume from. `completed` is intentionally
// excluded — running trekcontinue on a completed project should signal "no
// further sessions to resume", not load stale context.
export const SESSION_STATE_RESUMABLE_STATUSES = ['in_progress', 'partial', 'failed', 'stopped'];

2
plugins/ultraplan-local/scripts/q3-cache-prefix-experiment.mjs
View file

@ -44,7 +44,7 @@ const ALLOWED_TOOLS = 'Read,Write,Edit,Bash,Glob,Grep';
const MODEL = 'sonnet';
// Sources for parent context build. Brief constraint: no secrets, no ~/, no
// other plugins. Stays inside plugins/ultraplan-local/.
// other plugins. Stays inside plugins/trekplan/.
//
// Calibration (empirical, CC v2.1.128 + Sonnet 4.6):
// Token-per-byte ratio varies from 0.38-0.90 depending on content type.

8
plugins/ultraplan-local/templates/headless-launch-template.md
View file

@ -7,7 +7,7 @@ for headless execution of decomposed sessions.
```bash
#!/usr/bin/env bash
# Headless launch script — generated by ultraplan-local
# Headless launch script — generated by trekplan
# Master plan: {plan_path}
# Generated: {date}
# Sessions: {total_sessions} ({parallel_count} parallel, {sequential_count} sequential)
@ -24,7 +24,7 @@ WORKTREE_BASE="{session_dir}/worktrees"
mkdir -p "$LOG_DIR" "$WORKTREE_BASE"
# Disable git's optional locks during parallel worktree ops (research/02 R2;
# GH #47721). Mirror Phase 2.6 hardenings (commands/ultraexecute-local.md).
# GH #47721). Mirror Phase 2.6 hardenings (commands/trekexecute.md).
export GIT_OPTIONAL_LOCKS=0
# Per-child guardrails (operator may override via env). Match Phase 2.6
@ -99,7 +99,7 @@ if [ "${TREKEXECUTE_SKIP_PREFLIGHT:-0}" != "1" ]; then
fi
fi
echo "=== Ultraplan Headless Execution (Worktree-Isolated) ==="
echo "=== Voyage Headless Execution (Worktree-Isolated) ==="
echo "Plan: {plan_path}"
echo "Sessions: {total_sessions}"
echo "Repo root: $REPO_ROOT"
@ -138,7 +138,7 @@ cd "$REPO_ROOT"
{# For each session in the wave: push BEFORE merge (Hard Rule 19 — push-before-cleanup). }
git push origin "trek/{slug}/session-{n}" 2>/dev/null || true
git merge --no-ff "trek/{slug}/session-{n}" \
-m "merge: ultraplan session {n} — {title}"
-m "merge: trekplan session {n} — {title}"
if [ $? -ne 0 ]; then
echo "MERGE CONFLICT: session {n}. Conflicting files:"
git diff --name-only --diff-filter=U

10
plugins/ultraplan-local/templates/plan-template.md
View file

@ -1,6 +1,6 @@
<!--
Optional YAML frontmatter — include ONLY when the plan was generated from a
`type: ultrareview` input (Handover 6). Lists the 40-char hex IDs of the
`type: trekreview` input (Handover 6). Lists the 40-char hex IDs of the
BLOCKER + MAJOR findings consumed from `review.md`. Use block-style YAML;
the frontmatter parser does not support flow-style arrays.
@ -18,7 +18,7 @@ source_findings:
> **Plan quality: {grade}** ({score}/100) — {APPROVE | APPROVE_WITH_NOTES | REVISE | REPLAN}
>
> Generated by ultraplan-local v{version} on {YYYY-MM-DD} — `plan_version: 1.7`
> Generated by trekplan v{version} on {YYYY-MM-DD} — `plan_version: 1.7`
## Context
@ -116,7 +116,7 @@ concrete command (e.g., run the app, check output, curl an endpoint).*
### Manifest — objective completion predicate
Every step MUST have a Manifest block. This is the machine-checkable contract
that ultraexecute-local verifies after the Verify command passes. A step is
that trekexecute verifies after the Verify command passes. A step is
not considered complete until its manifest verifies — regardless of Verify
command exit code.
@ -182,7 +182,7 @@ before execution.*
## Verification
*Per-step manifest verification runs automatically during execution (every
step's Manifest block is objectively checked by ultraexecute-local before the
step's Manifest block is objectively checked by trekexecute before the
step is marked passed). This section is for end-to-end integration checks
that cross step boundaries — complete workflows, system-level behavior.*
@ -198,7 +198,7 @@ that cross step boundaries — complete workflows, system-level behavior.*
## Execution Strategy
*Include this section when the plan has more than 5 implementation steps.
Omit for small plans (≤ 5 steps) — ultraexecute will run them sequentially
Omit for small plans (≤ 5 steps) — trekexecute will run them sequentially
in a single session.*
*The execution strategy groups steps into sessions and organizes sessions

2
plugins/ultraplan-local/templates/research-brief-template.md
View file

@ -11,7 +11,7 @@ external_agents_used: [{list}]
# {Research Question Title}
> Generated by ultraresearch-local v{version} on {YYYY-MM-DD}
> Generated by trekresearch v{version} on {YYYY-MM-DD}
## Research Question

8
plugins/ultraplan-local/templates/session-spec-template.md
View file

@ -23,7 +23,7 @@ the purpose and make judgment calls.}
## Session Manifest
Machine-readable aggregate of all step manifests in this session. Used by
ultraexecute-local for independent Phase 7.5 audit.
trekexecute for independent Phase 7.5 audit.
```yaml
session_manifest:
@ -69,7 +69,7 @@ session_manifest:
```
*Step 0 runs in the same sandbox as all real work. If it exits 77,
ultraexecute-local marks the session `blocked` and does NOT proceed. This
trekexecute marks the session `blocked` and does NOT proceed. This
catches the fail-late push-denial mode observed in Wave 1.*
*Escape hatch:* set `TREKEXECUTE_SKIP_PREFLIGHT=1` in the environment to
@ -146,10 +146,10 @@ introduced. This section bridges sessions — it's the "baton" in a relay race.}
## Recovery Metadata
*This section is populated only when this session spec was generated by the
ultraexecute-local Phase 7.6 recovery dispatcher. Omit for normal sessions.*
trekexecute Phase 7.6 recovery dispatcher. Omit for normal sessions.*
- **Recovery of:** `{original session spec path}`
- **Recovery depth:** {1 | 2}
- **Missing steps (reason for recovery):** {step numbers + drift summary}
- **Entry condition override:** {e.g., "previous partial session committed at {sha}"}
- **Parent progress file:** `{path to .ultraexecute-progress-*.json}`
- **Parent progress file:** `{path to .trekexecute-progress-*.json}`

2
plugins/ultraplan-local/templates/spec-template.md
View file

@ -61,4 +61,4 @@ without answers.
- **Created:** {YYYY-MM-DD}
- **Mode:** {interview | manual}
- **Source:** {ultraplan interview | user-provided}
- **Source:** {trekplan interview | user-provided}

26
plugins/ultraplan-local/templates/trekbrief-template.md
View file

@ -14,8 +14,8 @@ source: {interview | manual}
# Task: {title}
> Generated by `/ultrabrief-local` on {YYYY-MM-DD}.
> This brief is the contract between requirements and planning. `/ultraplan-local`
> Generated by `/trekbrief` on {YYYY-MM-DD}.
> This brief is the contract between requirements and planning. `/trekplan`
> reads it to produce the implementation plan. Every decision in the plan must
> trace back to content in this brief.
@ -81,9 +81,9 @@ Do NOT write vague criteria:
## Research Plan
*Explicit research topics that must be answered before `/ultraplan-local` can
*Explicit research topics that must be answered before `/trekplan` can
produce a high-confidence plan. Each topic is phrased as a research question ready
to feed into `/ultraresearch-local`. Topics may be empty (N=0) for trivial tasks
to feed into `/trekresearch`. Topics may be empty (N=0) for trivial tasks
where the codebase alone is sufficient context.*
{If research_topics = 0, write a single line: "No external research needed —
@ -93,9 +93,9 @@ the codebase and this brief contain sufficient context for planning."}
- **Why this matters:** {How the plan depends on this answer. Which steps or
decisions cannot be made confidently without it.}
- **Research question:** "{Exact question to feed to /ultraresearch-local.
- **Research question:** "{Exact question to feed to /trekresearch.
One sentence, ends in `?`.}"
- **Suggested invocation:** `/ultraresearch-local --project {project_dir} --external "{question}"`
- **Suggested invocation:** `/trekresearch --project {project_dir} --external "{question}"`
- **Required for plan steps:** {which kinds of steps will consume this — e.g.,
"migration strategy", "library selection", "threat model"}
- **Confidence needed:** {high | medium | low}
@ -106,7 +106,7 @@ the codebase and this brief contain sufficient context for planning."}
- **Why this matters:** ...
- **Research question:** "..."
- **Suggested invocation:** `/ultraresearch-local --project {project_dir} ...`
- **Suggested invocation:** `/trekresearch --project {project_dir} ...`
- **Required for plan steps:** ...
- **Confidence needed:** ...
- **Estimated cost:** ...
@ -133,7 +133,7 @@ failures.*
- **Created:** {YYYY-MM-DD}
- **Interview turns:** {N}
- **Auto-research opted in:** {yes | no}
- **Source:** {ultrabrief interview | manual}
- **Source:** {trekbrief interview | manual}
---
@ -143,15 +143,15 @@ Manual (default):
```bash
# Run each research topic (order does not matter):
/ultraresearch-local --project {project_dir} --external "{Topic 1 question}"
/ultraresearch-local --project {project_dir} --external "{Topic 2 question}"
/trekresearch --project {project_dir} --external "{Topic 1 question}"
/trekresearch --project {project_dir} --external "{Topic 2 question}"
# Then plan:
/ultraplan-local --project {project_dir}
/trekplan --project {project_dir}
# Then execute:
/ultraexecute-local --project {project_dir}
/trekexecute --project {project_dir}
```
Auto (opt-in during `/ultrabrief-local`): research and planning run
Auto (opt-in during `/trekbrief`): research and planning run
automatically; only execution is manual.

4
plugins/ultraplan-local/templates/trekreview-template.md
View file

@ -42,7 +42,7 @@ should look at first.
- file: lib/foo.mjs
- line: 42
- rule_key: BROKEN_SUCCESS_CRITERION
- brief_ref: SC3 — "review.md is parseable as input to /ultraplan-local"
- brief_ref: SC3 — "review.md is parseable as input to /trekplan"
- title: Plan-validator rejects review.md when source_findings is flow-style
- detail: The validator at lib/validators/plan-validator.mjs:N reads
`source_findings` via parseDocument(), which does not support flow-style
@ -101,7 +101,7 @@ should look at first.
- 1 MINOR → nice-to-have for v1.1
- 1 SUGGESTION → log and move on
If running `/ultraplan-local --brief review.md`, the planner will consume
If running `/trekplan --brief review.md`, the planner will consume
the BLOCKER + MAJOR findings as plan goals (their `recommended_action`
becomes the step intent). MINOR + SUGGESTION are skipped for v1.0
plan-input.

38
plugins/ultraplan-local/tests/commands/trekcontinue.test.mjs
View file

@ -1,8 +1,8 @@
// tests/commands/ultracontinue.test.mjs
// Regression tests for /ultracontinue-local (commands/ultracontinue-local.md).
// tests/commands/trekcontinue.test.mjs
// Regression tests for /trekcontinue (commands/trekcontinue.md).
//
// Steps 2 + 4 of the v3.4.1 hot-fix plan
// (project 2026-05-04-v3.3.1-ultracontinue-fixes).
// (project 2026-05-04-v3.3.1-trekcontinue-fixes).
//
// Pattern mix:
// - Pattern B (tmp-dir, mkdtempSync + try/finally) — fixture builds
@ -64,10 +64,10 @@ function completedState(updatedAtIso) {
// Step 2 — Bug 1 regression tests (SC-1, SC-2)
// ---------------------------------------------------------------
test('ultracontinue Bug 1 — Phase 1 documents auto-discovery sort by Date.parse(updated_at) DESC', () => {
test('trekcontinue Bug 1 — Phase 1 documents auto-discovery sort by Date.parse(updated_at) DESC', () => {
// Fixture-builds two project dirs and verifies our chosen sort key
// matches what Phase 1 prose documents.
const root = mkdtempSync(join(tmpdir(), 'ultracontinue-disc-'));
const root = mkdtempSync(join(tmpdir(), 'trekcontinue-disc-'));
try {
const projectsRoot = join(root, '.claude', 'projects');
mkdirSync(join(projectsRoot, '2026-05-04-fixture-a'), { recursive: true });
@ -103,7 +103,7 @@ test('ultracontinue Bug 1 — Phase 1 documents auto-discovery sort by Date.pars
}
});
test('ultracontinue Bug 1 — Phase 0 dispatches via parsed flags, not substring contains', () => {
test('trekcontinue Bug 1 — Phase 0 dispatches via parsed flags, not substring contains', () => {
const phase0 = extractPhase(readCommand(), '## Phase 0 ');
// Must NOT use the legacy "contains --help or -h" substring dispatch.
assert.doesNotMatch(
@ -121,7 +121,7 @@ test('ultracontinue Bug 1 — Phase 0 dispatches via parsed flags, not substring
);
});
test('ultracontinue Bug 1 — Phase 1 documents empty-args path explicitly to auto-discovery', () => {
test('trekcontinue Bug 1 — Phase 1 documents empty-args path explicitly to auto-discovery', () => {
const phase1 = extractPhase(readCommand(), '## Phase 1 ');
// Some explicit text mentioning the empty / whitespace path so a future reader
// can't misread Phase 0 as "fall through to usage on empty".
@ -137,7 +137,7 @@ test('ultracontinue Bug 1 — Phase 1 documents empty-args path explicitly to au
);
});
test('ultracontinue Bug 1 sub — Phase 1 emits SC-2 diagnostic for .md positional arg', () => {
test('trekcontinue Bug 1 sub — Phase 1 emits SC-2 diagnostic for .md positional arg', () => {
const phase1 = extractPhase(readCommand(), '## Phase 1 ');
// SC-2 verbatim diagnostic strings.
assert.match(
@ -162,7 +162,7 @@ test('ultracontinue Bug 1 sub — Phase 1 emits SC-2 diagnostic for .md position
// Step 4 — Bug 2 regression tests (SC-3)
// ---------------------------------------------------------------
test('ultracontinue Bug 2 — pre-bash-executor ALLOWS resolved validator invocation', async () => {
test('trekcontinue Bug 2 — pre-bash-executor ALLOWS resolved validator invocation', async () => {
// (d-1) Sanity-check that the planned Phase 2 Bash form (validator
// invocation with a concrete absolute path) is not blocked by the
// marketplace pre-bash-executor hook chain.
@ -175,7 +175,7 @@ test('ultracontinue Bug 2 — pre-bash-executor ALLOWS resolved validator invoca
// Step 8 — Bug 3 regression test (Phase 1.5 consistency wire-up)
// ---------------------------------------------------------------
test('ultracontinue Bug 3 — Phase 1.5 documents consistency check between Phase 1 and Phase 2', () => {
test('trekcontinue Bug 3 — Phase 1.5 documents consistency check between Phase 1 and Phase 2', () => {
const cmd = readCommand();
// Phase 1.5 must exist literally in the prose between Phase 1 and Phase 2.
assert.match(cmd, /## Phase 1\.5 /, 'Phase 1.5 header must be present');
@ -187,8 +187,8 @@ test('ultracontinue Bug 3 — Phase 1.5 documents consistency check between Phas
'Phase 1.5 must appear before Phase 2');
});
test('ultracontinue Bug 3 (e) — CLI consistency mode flags producer mismatch in JSON output', () => {
const root = mkdtempSync(join(tmpdir(), 'ultracontinue-fm-'));
test('trekcontinue Bug 3 (e) — CLI consistency mode flags producer mismatch in JSON output', () => {
const root = mkdtempSync(join(tmpdir(), 'trekcontinue-fm-'));
try {
const projectDir = join(root, '.claude', 'projects', '2026-05-04-fixture-c');
mkdirSync(projectDir, { recursive: true });
@ -207,7 +207,7 @@ test('ultracontinue Bug 3 (e) — CLI consistency mode flags producer mismatch i
}, null, 2),
);
// Project-dir prompt: produced_by ultraexecute-local at T-1
// Project-dir prompt: produced_by trekexecute at T-1
const projectPrompt = join(projectDir, 'NEXT-SESSION-PROMPT.local.md');
writeFileSync(projectPrompt,
'---\nproduced_by: trekexecute\nproduced_at: 2026-05-04T15:30:00.000Z\n---\n\n# Session 2\n');
@ -245,7 +245,7 @@ test('ultracontinue Bug 3 (e) — CLI consistency mode flags producer mismatch i
}
});
test('ultracontinue Bug 2 — Phase 2 contains no {state-file-path} or any {curly-template} placeholder', () => {
test('trekcontinue Bug 2 — Phase 2 contains no {state-file-path} or any {curly-template} placeholder', () => {
// (d-2) Pattern D structure test. The fix must eliminate the
// {state-file-path} placeholder and any other {anything} curly-brace
// template syntax from Phase 2 — substitution failures are the
@ -272,7 +272,7 @@ test('ultracontinue Bug 2 — Phase 2 contains no {state-file-path} or any {curl
// Step 10 — Bug 4 regression tests (Phase 0.5 wire-up + cleanup f-1/f-2/f-3)
// ---------------------------------------------------------------
test('ultracontinue Bug 4 — Phase 0.5 documents cleanup mode dispatch', () => {
test('trekcontinue Bug 4 — Phase 0.5 documents cleanup mode dispatch', () => {
const cmd = readCommand();
assert.match(cmd, /## Phase 0\.5 /, 'Phase 0.5 header must be present');
// Phase 0.5 must come BETWEEN Phase 0 and Phase 1.
@ -288,9 +288,9 @@ test('ultracontinue Bug 4 — Phase 0.5 documents cleanup mode dispatch', () =>
assert.match(cmd, /--cleanup --confirm/, 'usage must mention --cleanup --confirm');
});
test('ultracontinue Bug 4 (f-1) dry-run lists candidates without deleting', async () => {
test('trekcontinue Bug 4 (f-1) dry-run lists candidates without deleting', async () => {
const { cleanupProject } = await import('../../lib/util/cleanup.mjs');
const root = mkdtempSync(join(tmpdir(), 'ultracontinue-cleanup-'));
const root = mkdtempSync(join(tmpdir(), 'trekcontinue-cleanup-'));
try {
const dir = join(root, 'project-completed');
mkdirSync(dir, { recursive: true });
@ -314,10 +314,10 @@ test('ultracontinue Bug 4 (f-1) dry-run lists candidates without deleting', asyn
}
});
test('ultracontinue Bug 4 (f-2) confirm deletes and (f-3) idempotent re-run handles already-clean dir', async () => {
test('trekcontinue Bug 4 (f-2) confirm deletes and (f-3) idempotent re-run handles already-clean dir', async () => {
const { cleanupProject } = await import('../../lib/util/cleanup.mjs');
const { existsSync } = await import('node:fs');
const root = mkdtempSync(join(tmpdir(), 'ultracontinue-cleanup-'));
const root = mkdtempSync(join(tmpdir(), 'trekcontinue-cleanup-'));
try {
const dir = join(root, 'project-completed');
mkdirSync(dir, { recursive: true });

6
plugins/ultraplan-local/tests/fixtures/trekreview/README.md vendored
View file

@ -1,4 +1,4 @@
# ultrareview determinism fixtures
# trekreview determinism fixtures
Synthetic fixtures for the Jaccard-similarity determinism test in
`tests/lib/review-determinism.test.mjs`.
@ -24,7 +24,7 @@ fall out of sync.
## Why synthetic for v1.0
Hand-curated for v1.0. Edit JSON IDs directly to test new Jaccard scenarios.
Real-LLM determinism measurement is deferred to v1.1 once `/ultrareview-local`
Real-LLM determinism measurement is deferred to v1.1 once `/trekreview`
has produced enough real outputs to capture as fixtures.
These fixtures prove the Jaccard PIPELINE works given a known input — they do
@ -42,6 +42,6 @@ verify the model-level claim is open work for v1.1.
```
3. Add the IDs to `findings:` block-style YAML in frontmatter and to `### <id>`
subsections in the body.
4. Run `node lib/validators/review-validator.mjs --json tests/fixtures/ultrareview/review-run-X.md`
4. Run `node lib/validators/review-validator.mjs --json tests/fixtures/trekreview/review-run-X.md`
to confirm the fixture validates.
5. Update `tests/lib/review-determinism.test.mjs` if you want a new assertion.

4
plugins/ultraplan-local/tests/fixtures/trekreview/plan-with-source-findings.md vendored
View file

@ -8,14 +8,14 @@ source_findings:
# Remediation Plan: JWT auth review findings
> Generated by ultraplan-local v3.2.0 on 2026-05-01 — `plan_version: 1.7`.
> Generated by trekplan v3.2.0 on 2026-05-01 — `plan_version: 1.7`.
>
> Synthetic fixture — Handover 6 SC3(b) structural test only.
## Context
This synthetic plan is consumed by `tests/lib/source-findings.test.mjs` to verify
the structural contract of Handover 6: a plan generated from a `type: ultrareview`
the structural contract of Handover 6: a plan generated from a `type: trekreview`
brief carries a `source_findings:` block-style YAML list of 40-char hex IDs in
its frontmatter. The IDs trace back to the consumed findings in `review.md`.

2
plugins/ultraplan-local/tests/fixtures/trekreview/review-run-A.md vendored
View file

@ -88,7 +88,7 @@ NOT the output of a real LLM review.
## Remediation Summary
5 findings total: 1 BLOCKER, 3 MAJOR, 1 MINOR. Run a remediation plan via
`/ultraplan-local --brief review.md` — it will pick up BLOCKER + MAJOR findings as
`/trekplan --brief review.md` — it will pick up BLOCKER + MAJOR findings as
plan goals and emit `source_findings: [<id>, ...]` audit trail (Handover 6).
```json

2
plugins/ultraplan-local/tests/fixtures/trekreview/review-run-B.md vendored
View file

@ -99,7 +99,7 @@ Run A's set is a strict subset of Run B's set, giving Jaccard = 5/6 = 0.833.
6 findings total: 1 BLOCKER, 4 MAJOR, 1 MINOR. Same merge gate as Run A; one
extra MAJOR (PLACEHOLDER_IN_CODE) that Run A missed. Run a remediation plan via
`/ultraplan-local --brief review.md`.
`/trekplan --brief review.md`.
```json
{

2
plugins/ultraplan-local/tests/lib/agent-frontmatter.test.mjs
View file

@ -7,7 +7,7 @@
// MUST include the `Agent` tool in their tools allowlist (they spawn the swarm).
//
// When this test fails, fix the agent file — do NOT relax the assertion to
// hide drift. The contract is what /ultra*-local commands rely on for
// hide drift. The contract is what /trek* commands rely on for
// disciplined model selection + tool scoping.
import { test } from 'node:test';

46
plugins/ultraplan-local/tests/lib/arg-parser.test.mjs
View file

@ -2,66 +2,66 @@ import { test } from 'node:test';
import { strict as assert } from 'node:assert';
import { parseArgs } from '../../lib/parsers/arg-parser.mjs';
test('ultrabrief — empty args', () => {
test('trekbrief — empty args', () => {
const r = parseArgs('', 'trekbrief');
assert.equal(r.command, 'trekbrief');
assert.deepEqual(r.flags, {});
});
test('ultrabrief — --quick boolean', () => {
test('trekbrief — --quick boolean', () => {
const r = parseArgs('--quick', 'trekbrief');
assert.equal(r.flags['--quick'], true);
});
test('ultraresearch — --project value capture', () => {
test('trekresearch — --project value capture', () => {
const r = parseArgs('--project .claude/projects/2026-04-30-foo', 'trekresearch');
assert.equal(r.flags['--project'], '.claude/projects/2026-04-30-foo');
});
test('ultraresearch — --quick --local combined', () => {
test('trekresearch — --quick --local combined', () => {
const r = parseArgs('--quick --local', 'trekresearch');
assert.equal(r.flags['--quick'], true);
assert.equal(r.flags['--local'], true);
});
test('ultraplan — --research multi-value', () => {
test('trekplan — --research multi-value', () => {
const r = parseArgs('--research a.md b.md c.md', 'trekplan');
assert.deepEqual(r.flags['--research'], ['a.md', 'b.md', 'c.md']);
});
test('ultraplan — --research multi stops at next flag', () => {
test('trekplan — --research multi stops at next flag', () => {
const r = parseArgs('--research a.md b.md --project /x', 'trekplan');
assert.deepEqual(r.flags['--research'], ['a.md', 'b.md']);
assert.equal(r.flags['--project'], '/x');
});
test('ultraplan — --brief required-value flag', () => {
test('trekplan — --brief required-value flag', () => {
const r = parseArgs('--brief brief.md', 'trekplan');
assert.equal(r.flags['--brief'], 'brief.md');
});
test('ultraplan — missing value for --brief produces error', () => {
test('trekplan — missing value for --brief produces error', () => {
const r = parseArgs('--brief --quick', 'trekplan');
assert.ok(r.errors.find(e => e.code === 'ARG_MISSING_VALUE'));
});
test('ultraplan — --decompose value flag', () => {
test('trekplan — --decompose value flag', () => {
const r = parseArgs('--decompose plan.md', 'trekplan');
assert.equal(r.flags['--decompose'], 'plan.md');
});
test('ultraexecute — --resume + --project', () => {
test('trekexecute — --resume + --project', () => {
const r = parseArgs('--resume --project /tmp/p', 'trekexecute');
assert.equal(r.flags['--resume'], true);
assert.equal(r.flags['--project'], '/tmp/p');
});
test('ultraexecute — --step N value', () => {
test('trekexecute — --step N value', () => {
const r = parseArgs('--step 3', 'trekexecute');
assert.equal(r.flags['--step'], '3');
});
test('ultraexecute — unknown flag goes to unknown[]', () => {
test('trekexecute — unknown flag goes to unknown[]', () => {
const r = parseArgs('--mystery foo', 'trekexecute');
assert.ok(r.unknown.includes('--mystery'));
});
@ -76,28 +76,28 @@ test('unknown command reported as error', () => {
assert.ok(r.errors.find(e => e.code === 'ARG_UNKNOWN_COMMAND'));
});
test('ultrareview — --project value capture', () => {
test('trekreview — --project value capture', () => {
const r = parseArgs('--project .claude/projects/2026-05-01-foo', 'trekreview');
assert.equal(r.flags['--project'], '.claude/projects/2026-05-01-foo');
});
test('ultrareview — --since <ref> value', () => {
test('trekreview — --since <ref> value', () => {
const r = parseArgs('--since HEAD~5', 'trekreview');
assert.equal(r.flags['--since'], 'HEAD~5');
});
test('ultrareview — --quick + --validate combined', () => {
test('trekreview — --quick + --validate combined', () => {
const r = parseArgs('--quick --validate', 'trekreview');
assert.equal(r.flags['--quick'], true);
assert.equal(r.flags['--validate'], true);
});
test('ultrareview — unknown flag goes to unknown[]', () => {
test('trekreview — unknown flag goes to unknown[]', () => {
const r = parseArgs('--mystery foo', 'trekreview');
assert.ok(r.unknown.includes('--mystery'));
});
test('ultracontinue — empty args produce no flags and no positional', () => {
test('trekcontinue — empty args produce no flags and no positional', () => {
const r = parseArgs('', 'trekcontinue');
assert.equal(r.command, 'trekcontinue');
assert.deepEqual(r.flags, {});
@ -105,35 +105,35 @@ test('ultracontinue — empty args produce no flags and no positional', () => {
assert.deepEqual(r.errors, []);
});
test('ultracontinue — --help boolean flag', () => {
test('trekcontinue — --help boolean flag', () => {
const r = parseArgs('--help', 'trekcontinue');
assert.equal(r.flags['--help'], true);
});
test('ultracontinue — -h treated as positional (no alias resolution)', () => {
test('trekcontinue — -h treated as positional (no alias resolution)', () => {
const r = parseArgs('-h', 'trekcontinue');
assert.deepEqual(r.positional, ['-h']);
assert.deepEqual(r.errors, []);
assert.equal(r.flags['--help'], undefined);
});
test('ultracontinue — --cleanup boolean flag', () => {
test('trekcontinue — --cleanup boolean flag', () => {
const r = parseArgs('--cleanup', 'trekcontinue');
assert.equal(r.flags['--cleanup'], true);
});
test('ultracontinue — --cleanup --confirm both flags', () => {
test('trekcontinue — --cleanup --confirm both flags', () => {
const r = parseArgs('--cleanup --confirm', 'trekcontinue');
assert.equal(r.flags['--cleanup'], true);
assert.equal(r.flags['--confirm'], true);
});
test('ultracontinue — positional project dir captured', () => {
test('trekcontinue — positional project dir captured', () => {
const r = parseArgs('.claude/projects/2026-05-04-foo', 'trekcontinue');
assert.deepEqual(r.positional, ['.claude/projects/2026-05-04-foo']);
});
test('ultracontinue — .md positional accepted by parser (rejection is command-level)', () => {
test('trekcontinue — .md positional accepted by parser (rejection is command-level)', () => {
const r = parseArgs('NEXT-SESSION-PROMPT.local.md', 'trekcontinue');
assert.deepEqual(r.positional, ['NEXT-SESSION-PROMPT.local.md']);
assert.deepEqual(r.errors, []);

8
plugins/ultraplan-local/tests/lib/frontmatter.test.mjs
View file

@ -27,9 +27,9 @@ test('splitFrontmatter — no frontmatter', () => {
});
test('parseFrontmatter — string scalars', () => {
const r = parseFrontmatter('type: ultrabrief\nslug: jwt-auth\n');
const r = parseFrontmatter('type: trekbrief\nslug: jwt-auth\n');
assert.equal(r.valid, true);
assert.equal(r.parsed.type, 'ultrabrief');
assert.equal(r.parsed.type, 'trekbrief');
assert.equal(r.parsed.slug, 'jwt-auth');
});
@ -60,10 +60,10 @@ test('parseFrontmatter — rejects nested dict', () => {
});
test('parseDocument — full pipeline', () => {
const text = '---\ntype: ultrabrief\nresearch_topics: 2\n---\n\n# Body\n\ncontent\n';
const text = '---\ntype: trekbrief\nresearch_topics: 2\n---\n\n# Body\n\ncontent\n';
const r = parseDocument(text);
assert.equal(r.valid, true);
assert.equal(r.parsed.frontmatter.type, 'ultrabrief');
assert.equal(r.parsed.frontmatter.type, 'trekbrief');
assert.match(r.parsed.body, /content/);
});

2
plugins/ultraplan-local/tests/lib/project-discovery.test.mjs
View file

@ -9,7 +9,7 @@ import {
} from '../../lib/parsers/project-discovery.mjs';
function setupProject(structure) {
const root = mkdtempSync(join(tmpdir(), 'ultraplan-disc-'));
const root = mkdtempSync(join(tmpdir(), 'trekplan-disc-'));
for (const [path, content] of Object.entries(structure)) {
const full = join(root, path);
mkdirSync(join(full, '..'), { recursive: true });

2
plugins/ultraplan-local/tests/lib/source-findings.test.mjs
View file

@ -1,7 +1,7 @@
// tests/lib/source-findings.test.mjs
// SC3(b) structural test for Handover 6.
//
// The brief requires `plan.md` produced from a `type: ultrareview` brief to
// The brief requires `plan.md` produced from a `type: trekreview` brief to
// contain `source_findings: [<id>, ...]` in its frontmatter. Without an
// automated test, SC3(b) is unverified.
//

2
plugins/ultraplan-local/tests/synthetic/plan-run-A.md
View file

@ -50,7 +50,7 @@ steps:
# Synthetic plan run A — Add --verbose flag to CLI
This fixture represents one synthesized run of `/ultraplan-local` against a
This fixture represents one synthesized run of `/trekplan` against a
hand-calibrated brief. It is paired with `plan-run-B.md` for the
`plan-determinism.test.mjs` Jaccard floor (≥ 0.833).

2
plugins/ultraplan-local/tests/synthetic/plan-run-B.md
View file

@ -50,7 +50,7 @@ steps:
# Synthetic plan run B — Add --verbose flag to CLI
This fixture represents a second synthesized run of `/ultraplan-local` against
This fixture represents a second synthesized run of `/trekplan` against
the same hand-calibrated brief used for `plan-run-A.md`. The two runs differ
on 2 step titles (modeling realistic LLM variation).

2
plugins/ultraplan-local/tests/synthetic/review-run-A.md
View file

@ -41,7 +41,7 @@ findings:
# Synthetic review run A — JWT authentication with refresh-token rotation
This fixture represents one synthesized run of `/ultrareview-local` on a
This fixture represents one synthesized run of `/trekreview` on a
hand-calibrated brief. It is paired with `review-run-B.md` for the
`review-determinism.test.mjs` Jaccard floor (≥ 0.833).

2
plugins/ultraplan-local/tests/validators/architecture-discovery.test.mjs
View file

@ -6,7 +6,7 @@ import { join } from 'node:path';
import { discoverArchitecture } from '../../lib/validators/architecture-discovery.mjs';
function setup(structure) {
const root = mkdtempSync(join(tmpdir(), 'ultraplan-arch-'));
const root = mkdtempSync(join(tmpdir(), 'trekplan-arch-'));
for (const [path, content] of Object.entries(structure)) {
const full = join(root, path);
mkdirSync(join(full, '..'), { recursive: true });

14
plugins/ultraplan-local/tests/validators/brief-validator.test.mjs
View file

@ -95,9 +95,9 @@ test('validateBrief — missing frontmatter is hard error', () => {
const REVIEW_AS_BRIEF = `---
type: trekreview
task: "Review delivered ultrareview-local v1.0"
slug: ultrareview-local
project_dir: .claude/projects/2026-05-01-ultrareview-local/
task: "Review delivered trekreview v1.0"
slug: trekreview
project_dir: .claude/projects/2026-05-01-trekreview/
findings:
- 0123456789abcdef0123456789abcdef01234567
- fedcba9876543210fedcba9876543210fedcba98
@ -107,7 +107,7 @@ findings:
## Intent
Adversarial review of delivered ultrareview-local v1.0.
Adversarial review of delivered trekreview v1.0.
## Goal
@ -118,12 +118,12 @@ Find what was missed.
- All BLOCKER findings get a fix-plan.
`;
test('validateBrief — ultrareview type accepted with findings array', () => {
test('validateBrief — trekreview type accepted with findings array', () => {
const r = validateBriefContent(REVIEW_AS_BRIEF, { strict: true });
assert.equal(r.valid, true, JSON.stringify(r.errors));
});
test('validateBrief — ultrareview without findings rejected (BRIEF_MISSING_FIELD)', () => {
test('validateBrief — trekreview without findings rejected (BRIEF_MISSING_FIELD)', () => {
const t = REVIEW_AS_BRIEF.replace(/findings:\n - 0123[\s\S]*?- fedcba[0-9a-f]+\n/, '');
const r = validateBriefContent(t);
assert.equal(r.valid, false);
@ -133,7 +133,7 @@ test('validateBrief — ultrareview without findings rejected (BRIEF_MISSING_FIE
);
});
test('validateBrief — ultrareview with findings as scalar (not array) rejected (BRIEF_BAD_FINDINGS_TYPE)', () => {
test('validateBrief — trekreview with findings as scalar (not array) rejected (BRIEF_BAD_FINDINGS_TYPE)', () => {
const t = REVIEW_AS_BRIEF.replace(
/findings:\n - 0123[\s\S]*?- fedcba[0-9a-f]+/,
'findings: not-an-array',

2
plugins/ultraplan-local/tests/validators/session-state-validator.test.mjs
View file

@ -108,7 +108,7 @@ test('validateSessionStateContent — malformed JSON returns SESSION_STATE_PARSE
});
test('validateSessionState — missing file returns SESSION_STATE_NOT_FOUND', () => {
const r = validateSessionState('/tmp/nonexistent-ultracontinue-test-9b2f4e.json');
const r = validateSessionState('/tmp/nonexistent-trekcontinue-test-9b2f4e.json');
assert.equal(r.valid, false);
assert.ok(r.errors.find(e => e.code === 'SESSION_STATE_NOT_FOUND'));
});