From 14ecda886c215eaafa7ecad6d50ea3e1ca7f89b8 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Tue, 5 May 2026 15:08:20 +0200 Subject: [PATCH] feat(voyage)!: bulk content rewrite ultra -> voyage/trek prose [skip-docs] 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 --- plugins/ultraplan-local/CLAUDE.md | 80 ++++---- plugins/ultraplan-local/CONTRIBUTING.md | 22 +-- plugins/ultraplan-local/README.md | 176 +++++++++--------- plugins/ultraplan-local/SECURITY.md | 6 +- .../agents/architecture-mapper.md | 6 +- .../agents/brief-conformance-reviewer.md | 6 +- .../ultraplan-local/agents/brief-reviewer.md | 20 +- .../agents/code-correctness-reviewer.md | 4 +- .../agents/community-researcher.md | 8 +- .../agents/contrarian-researcher.md | 8 +- .../agents/convention-scanner.md | 6 +- .../agents/dependency-tracer.md | 6 +- .../ultraplan-local/agents/docs-researcher.md | 8 +- .../ultraplan-local/agents/gemini-bridge.md | 4 +- .../ultraplan-local/agents/git-historian.md | 6 +- plugins/ultraplan-local/agents/plan-critic.md | 10 +- .../agents/planning-orchestrator.md | 26 +-- .../agents/research-orchestrator.md | 14 +- .../ultraplan-local/agents/research-scout.md | 6 +- .../agents/review-coordinator.md | 10 +- .../agents/review-orchestrator.md | 20 +- .../ultraplan-local/agents/risk-assessor.md | 6 +- .../ultraplan-local/agents/scope-guardian.md | 6 +- .../agents/security-researcher.md | 8 +- .../agents/session-decomposer.md | 10 +- plugins/ultraplan-local/agents/task-finder.md | 6 +- .../ultraplan-local/agents/test-strategist.md | 6 +- plugins/ultraplan-local/commands/trekbrief.md | 54 +++--- .../ultraplan-local/commands/trekcontinue.md | 58 +++--- .../commands/trekendsession.md | 34 ++-- .../ultraplan-local/commands/trekexecute.md | 108 +++++------ plugins/ultraplan-local/commands/trekplan.md | 86 ++++----- .../ultraplan-local/commands/trekresearch.md | 50 ++--- .../ultraplan-local/commands/trekreview.md | 32 ++-- .../docs/HANDOVER-CONTRACTS.md | 86 ++++----- .../docs/subagent-delegation-audit.md | 42 ++--- .../01-add-verbose-flag/REGENERATED.md | 4 +- .../examples/01-add-verbose-flag/brief.md | 2 +- .../examples/01-add-verbose-flag/plan.md | 2 +- .../research/01-cli-parser-conventions.md | 2 +- .../examples/02-real-cli/REGENERATED.md | 24 +-- plugins/ultraplan-local/examples/README.md | 18 +- .../hooks/scripts/post-bash-stats.mjs | 6 +- .../hooks/scripts/post-compact-flush.mjs | 2 +- .../hooks/scripts/pre-compact-flush.mjs | 6 +- .../hooks/scripts/session-title.mjs | 4 +- .../lib/parsers/arg-parser.mjs | 2 +- .../lib/parsers/finding-id.mjs | 2 +- .../lib/review/plan-review-dedup.mjs | 2 +- .../lib/review/rule-catalogue.mjs | 2 +- .../lib/stats/cache-analyzer.mjs | 2 +- .../lib/util/autonomy-gate.mjs | 2 +- plugins/ultraplan-local/lib/util/cleanup.mjs | 8 +- .../lib/validators/brief-validator.mjs | 2 +- .../next-session-prompt-validator.mjs | 2 +- .../lib/validators/review-validator.mjs | 2 +- .../validators/session-state-validator.mjs | 6 +- .../scripts/q3-cache-prefix-experiment.mjs | 2 +- .../templates/headless-launch-template.md | 8 +- .../templates/plan-template.md | 10 +- .../templates/research-brief-template.md | 2 +- .../templates/session-spec-template.md | 8 +- .../templates/spec-template.md | 2 +- .../templates/trekbrief-template.md | 26 +-- .../templates/trekreview-template.md | 4 +- .../tests/commands/trekcontinue.test.mjs | 38 ++-- .../tests/fixtures/trekreview/README.md | 6 +- .../trekreview/plan-with-source-findings.md | 4 +- .../tests/fixtures/trekreview/review-run-A.md | 2 +- .../tests/fixtures/trekreview/review-run-B.md | 2 +- .../tests/lib/agent-frontmatter.test.mjs | 2 +- .../tests/lib/arg-parser.test.mjs | 46 ++--- .../tests/lib/frontmatter.test.mjs | 8 +- .../tests/lib/project-discovery.test.mjs | 2 +- .../tests/lib/source-findings.test.mjs | 2 +- .../tests/synthetic/plan-run-A.md | 2 +- .../tests/synthetic/plan-run-B.md | 2 +- .../tests/synthetic/review-run-A.md | 2 +- .../architecture-discovery.test.mjs | 2 +- .../tests/validators/brief-validator.test.mjs | 14 +- .../session-state-validator.test.mjs | 2 +- 81 files changed, 672 insertions(+), 672 deletions(-) diff --git a/plugins/ultraplan-local/CLAUDE.md b/plugins/ultraplan-local/CLAUDE.md index e13b248..b9bb9ca 100644 --- a/plugins/ultraplan-local/CLAUDE.md +++ b/plugins/ultraplan-local/CLAUDE.md @@ -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 --local`, `--external --quick`. -### /ultraplan-local modes +### /trekplan modes | Flag | Behavior | |------|----------| | `--project ` | **Required path A** — read `{dir}/brief.md`, auto-discover `{dir}/research/*.md`, write `{dir}/plan.md` | -| `--brief ` | **Required path B** — plan from a specific brief file; write to `.claude/plans/ultraplan-{date}-{slug}.md` | +| `--brief ` | **Required path B** — plan from a specific brief file; write to `.claude/plans/trekplan-{date}-{slug}.md` | | `--research [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 --local`, `--external --quick`. | `--decompose ` | 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 ` | **Required.** Path to ultraplan-local project folder containing `brief.md`. Review is written to `{dir}/review.md` | +| `--project ` | **Required.** Path to trekplan project folder containing `brief.md`. Review is written to `{dir}/review.md` | | `--since ` | 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::` 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::` 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 `` 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 `` 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 ` fills in `{dir}/research/`. `/ultraplan-local --project ` 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 ` executes and writes `{dir}/progress.json`. All artifacts live in one project directory. +**Pipeline:** `/trekbrief` produces the task brief. `/trekresearch --project ` fills in `{dir}/research/`. `/trekplan --project ` 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 ` 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). diff --git a/plugins/ultraplan-local/CONTRIBUTING.md b/plugins/ultraplan-local/CONTRIBUTING.md index 818a63f..e4c87ea 100644 --- a/plugins/ultraplan-local/CONTRIBUTING.md +++ b/plugins/ultraplan-local/CONTRIBUTING.md @@ -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 -/ultraplan-local -/ultraexecute-local +/trekresearch +/trekplan +/trekexecute ``` 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 diff --git a/plugins/ultraplan-local/README.md b/plugins/ultraplan-local/README.md index 8d72d33..27f83a6 100644 --- a/plugins/ultraplan-local/README.md +++ b/plugins/ultraplan-local/README.md @@ -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 ` | Dynamic interview until quality gates pass. No question cap. | | **Quick** | `/trekbrief --quick ` | 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}/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}/plan.md` -- With `--brief `: `.claude/plans/ultraplan-{date}-{slug}.md` +- With `--brief `: `.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::` whenever you invoke one of -the four ultra commands. This makes multi-session headless runs and +session title to `voyage::` 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//.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 ` | 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 ` | 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 --validate # schema check, no execution -/ultraexecute-local --project --dry-run # preview sessions and billing -/ultraexecute-local --project # execute +/trekexecute --project --validate # schema check, no execution +/trekexecute --project --dry-run # preview sessions and billing +/trekexecute --project # execute ``` **Review feedback loop (Handover 6):** ```bash -/ultrareview-local --project +/trekreview --project # → 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 /review.md +/trekplan --brief /review.md # → plan.md with source_findings: [, ...] audit trail -/ultraexecute-local --project # execute the remediation plan +/trekexecute --project # execute the remediation plan -/ultrareview-local --project # re-review (overwrites review.md) +/trekreview --project # 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 diff --git a/plugins/ultraplan-local/SECURITY.md b/plugins/ultraplan-local/SECURITY.md index 845d33e..7548aab 100644 --- a/plugins/ultraplan-local/SECURITY.md +++ b/plugins/ultraplan-local/SECURITY.md @@ -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::` for headless multiplexing | +| `session-title.mjs` *(planned, F9)* | `UserPromptSubmit` | Sets session title `voyage::` 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 diff --git a/plugins/ultraplan-local/agents/architecture-mapper.md b/plugins/ultraplan-local/agents/architecture-mapper.md index 3db046d..0da6f57 100644 --- a/plugins/ultraplan-local/agents/architecture-mapper.md +++ b/plugins/ultraplan-local/agents/architecture-mapper.md @@ -5,11 +5,11 @@ description: | tech stack, patterns, anti-patterns, and key abstractions. - 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." - Phase 5 of ultraplan triggers this agent for every codebase size. + Phase 5 of trekplan triggers this agent for every codebase size. diff --git a/plugins/ultraplan-local/agents/brief-conformance-reviewer.md b/plugins/ultraplan-local/agents/brief-conformance-reviewer.md index ec04bbb..1c60e0c 100644 --- a/plugins/ultraplan-local/agents/brief-conformance-reviewer.md +++ b/plugins/ultraplan-local/agents/brief-conformance-reviewer.md @@ -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 diff --git a/plugins/ultraplan-local/agents/brief-reviewer.md b/plugins/ultraplan-local/agents/brief-reviewer.md index 5878bd5..6cc8ebf 100644 --- a/plugins/ultraplan-local/agents/brief-reviewer.md +++ b/plugins/ultraplan-local/agents/brief-reviewer.md @@ -7,8 +7,8 @@ description: | exploration with a flawed brief. - 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." 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 diff --git a/plugins/ultraplan-local/agents/code-correctness-reviewer.md b/plugins/ultraplan-local/agents/code-correctness-reviewer.md index 436fd72..d8dac3d 100644 --- a/plugins/ultraplan-local/agents/code-correctness-reviewer.md +++ b/plugins/ultraplan-local/agents/code-correctness-reviewer.md @@ -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 diff --git a/plugins/ultraplan-local/agents/community-researcher.md b/plugins/ultraplan-local/agents/community-researcher.md index 19c155f..c2a3e54 100644 --- a/plugins/ultraplan-local/agents/community-researcher.md +++ b/plugins/ultraplan-local/agents/community-researcher.md @@ -6,8 +6,8 @@ description: | and what developers actually encounter when using a technology. - 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." Official docs won't cover migration regrets or production war stories. community-researcher @@ -16,8 +16,8 @@ description: | - 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." Framework comparisons live in community discourse, not official docs. community-researcher diff --git a/plugins/ultraplan-local/agents/contrarian-researcher.md b/plugins/ultraplan-local/agents/contrarian-researcher.md index a53b139..f589c6f 100644 --- a/plugins/ultraplan-local/agents/contrarian-researcher.md +++ b/plugins/ultraplan-local/agents/contrarian-researcher.md @@ -6,8 +6,8 @@ description: | answer might be wrong. - 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." The research equivalent of plan-critic. When one option is emerging as the answer, @@ -16,8 +16,8 @@ description: | - 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." Contrarian-researcher finds the downsides of the leading option — not to be negative, diff --git a/plugins/ultraplan-local/agents/convention-scanner.md b/plugins/ultraplan-local/agents/convention-scanner.md index 6a4520f..9abc32e 100644 --- a/plugins/ultraplan-local/agents/convention-scanner.md +++ b/plugins/ultraplan-local/agents/convention-scanner.md @@ -7,11 +7,11 @@ description: | documentation patterns. Uses concrete examples from the codebase. - 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." - Phase 5 of ultraplan triggers this agent for medium+ codebases (50+ files). + Phase 5 of trekplan triggers this agent for medium+ codebases (50+ files). diff --git a/plugins/ultraplan-local/agents/dependency-tracer.md b/plugins/ultraplan-local/agents/dependency-tracer.md index 0865d74..c390d70 100644 --- a/plugins/ultraplan-local/agents/dependency-tracer.md +++ b/plugins/ultraplan-local/agents/dependency-tracer.md @@ -5,11 +5,11 @@ description: | how modules connect and what side effects they produce. - 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." - 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. diff --git a/plugins/ultraplan-local/agents/docs-researcher.md b/plugins/ultraplan-local/agents/docs-researcher.md index 0dcbf4d..4e40386 100644 --- a/plugins/ultraplan-local/agents/docs-researcher.md +++ b/plugins/ultraplan-local/agents/docs-researcher.md @@ -5,8 +5,8 @@ description: | documentation, RFCs, vendor specifications, or Microsoft/Azure documentation. - 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." docs-researcher targets authoritative sources — RFCs, specs, official vendor docs — @@ -15,8 +15,8 @@ description: | - 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." Microsoft/Azure technologies have dedicated MCP tools (microsoft_docs_search, diff --git a/plugins/ultraplan-local/agents/gemini-bridge.md b/plugins/ultraplan-local/agents/gemini-bridge.md index fb01f66..b9c0c6a 100644 --- a/plugins/ultraplan-local/agents/gemini-bridge.md +++ b/plugins/ultraplan-local/agents/gemini-bridge.md @@ -7,8 +7,8 @@ description: | that can confirm or challenge findings from other agents. - 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." Technology choice with significant architectural implications triggers gemini-bridge diff --git a/plugins/ultraplan-local/agents/git-historian.md b/plugins/ultraplan-local/agents/git-historian.md index 03f41ec..f64c31a 100644 --- a/plugins/ultraplan-local/agents/git-historian.md +++ b/plugins/ultraplan-local/agents/git-historian.md @@ -5,11 +5,11 @@ description: | code ownership, hot files, and active branches relevant to the task. - 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." - Phase 2 of ultraplan triggers this agent for every codebase size. + Phase 2 of trekplan triggers this agent for every codebase size. diff --git a/plugins/ultraplan-local/agents/plan-critic.md b/plugins/ultraplan-local/agents/plan-critic.md index 9ed9e78..c8a3b28 100644 --- a/plugins/ultraplan-local/agents/plan-critic.md +++ b/plugins/ultraplan-local/agents/plan-critic.md @@ -5,11 +5,11 @@ description: | problems, never praises. - 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." - Phase 9 of ultraplan triggers this agent to review the generated plan. + Phase 9 of trekplan triggers this agent to review the generated plan. @@ -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 diff --git a/plugins/ultraplan-local/agents/planning-orchestrator.md b/plugins/ultraplan-local/agents/planning-orchestrator.md index a5677a2..d7f6abb 100644 --- a/plugins/ultraplan-local/agents/planning-orchestrator.md +++ b/plugins/ultraplan-local/agents/planning-orchestrator.md @@ -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} diff --git a/plugins/ultraplan-local/agents/research-orchestrator.md b/plugins/ultraplan-local/agents/research-orchestrator.md index dab52d9..98cd230 100644 --- a/plugins/ultraplan-local/agents/research-orchestrator.md +++ b/plugins/ultraplan-local/agents/research-orchestrator.md @@ -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} +- Feed into planning: /trekplan --research {brief path} - Ask follow-up questions ``` diff --git a/plugins/ultraplan-local/agents/research-scout.md b/plugins/ultraplan-local/agents/research-scout.md index 45c096e..bbde9c0 100644 --- a/plugins/ultraplan-local/agents/research-scout.md +++ b/plugins/ultraplan-local/agents/research-scout.md @@ -5,11 +5,11 @@ description: | APIs, or libraries where official documentation and known issues should be checked. - 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." - 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. diff --git a/plugins/ultraplan-local/agents/review-coordinator.md b/plugins/ultraplan-local/agents/review-coordinator.md index a6cfb88..4544897 100644 --- a/plugins/ultraplan-local/agents/review-coordinator.md +++ b/plugins/ultraplan-local/agents/review-coordinator.md @@ -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. diff --git a/plugins/ultraplan-local/agents/review-orchestrator.md b/plugins/ultraplan-local/agents/review-orchestrator.md index baef393..2186e33 100644 --- a/plugins/ultraplan-local/agents/review-orchestrator.md +++ b/plugins/ultraplan-local/agents/review-orchestrator.md @@ -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 diff --git a/plugins/ultraplan-local/agents/risk-assessor.md b/plugins/ultraplan-local/agents/risk-assessor.md index a223e7c..da697a9 100644 --- a/plugins/ultraplan-local/agents/risk-assessor.md +++ b/plugins/ultraplan-local/agents/risk-assessor.md @@ -5,11 +5,11 @@ description: | technical debt that could affect an implementation task. - 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." - 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. diff --git a/plugins/ultraplan-local/agents/scope-guardian.md b/plugins/ultraplan-local/agents/scope-guardian.md index 69d07bf..29b4302 100644 --- a/plugins/ultraplan-local/agents/scope-guardian.md +++ b/plugins/ultraplan-local/agents/scope-guardian.md @@ -5,11 +5,11 @@ description: | requirements — catches scope creep and scope gaps. - 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." - Phase 9 of ultraplan triggers this agent alongside plan-critic. + Phase 9 of trekplan triggers this agent alongside plan-critic. diff --git a/plugins/ultraplan-local/agents/security-researcher.md b/plugins/ultraplan-local/agents/security-researcher.md index c82032e..6338ee0 100644 --- a/plugins/ultraplan-local/agents/security-researcher.md +++ b/plugins/ultraplan-local/agents/security-researcher.md @@ -5,8 +5,8 @@ description: | dependency, or library — CVEs, audit history, supply chain risks, and OWASP relevance. - 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." Before adopting a dependency, security-researcher checks the attack surface: known @@ -15,8 +15,8 @@ description: | - 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." Technology choices have security tradeoffs. security-researcher maps the threat surface diff --git a/plugins/ultraplan-local/agents/session-decomposer.md b/plugins/ultraplan-local/agents/session-decomposer.md index 7c5e334..a3e1d74 100644 --- a/plugins/ultraplan-local/agents/session-decomposer.md +++ b/plugins/ultraplan-local/agents/session-decomposer.md @@ -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. 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." 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. diff --git a/plugins/ultraplan-local/agents/task-finder.md b/plugins/ultraplan-local/agents/task-finder.md index cab1713..c81977b 100644 --- a/plugins/ultraplan-local/agents/task-finder.md +++ b/plugins/ultraplan-local/agents/task-finder.md @@ -6,11 +6,11 @@ description: | structured code discovery. - 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." - Phase 2 of ultraplan triggers this agent for every codebase size. + Phase 2 of trekplan triggers this agent for every codebase size. diff --git a/plugins/ultraplan-local/agents/test-strategist.md b/plugins/ultraplan-local/agents/test-strategist.md index ae0efa7..1db4bb5 100644 --- a/plugins/ultraplan-local/agents/test-strategist.md +++ b/plugins/ultraplan-local/agents/test-strategist.md @@ -5,11 +5,11 @@ description: | discovers existing patterns, maps coverage gaps, and recommends what tests to write. - 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." - Phase 5 of ultraplan triggers this agent for medium and large codebases. + Phase 5 of trekplan triggers this agent for medium and large codebases. diff --git a/plugins/ultraplan-local/commands/trekbrief.md b/plugins/ultraplan-local/commands/trekbrief.md index b809c7b..a9d7406 100644 --- a/plugins/ultraplan-local/commands/trekbrief.md +++ b/plugins/ultraplan-local/commands/trekbrief.md @@ -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] " 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 → research/*.md -/ultraplan-local --project → plan.md -/ultraexecute-local --project → execution +/trekbrief → brief.md (this command) +/trekresearch --project → research/*.md +/trekplan --project → plan.md +/trekexecute --project → 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 - /ultrabrief-local --quick +Usage: /trekbrief + /trekbrief --quick 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. diff --git a/plugins/ultraplan-local/commands/trekcontinue.md b/plugins/ultraplan-local/commands/trekcontinue.md index 107a35b..1d9fee3 100644 --- a/plugins/ultraplan-local/commands/trekcontinue.md +++ b/plugins/ultraplan-local/commands/trekcontinue.md @@ -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: "[ | --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//.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 # explicit project directory - /ultracontinue --cleanup # dry-run: list stale files - /ultracontinue --cleanup --confirm # actually delete (requires status: completed) - /ultracontinue --help # this message + /trekcontinue # auto-discover state file under cwd + /trekcontinue # explicit project directory + /trekcontinue --cleanup # dry-run: list stale files + /trekcontinue --cleanup --confirm # actually delete (requires status: completed) + /trekcontinue --help # this message Reads .claude/projects//.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 . +Error: /trekcontinue --cleanup requires . Usage: - /ultracontinue-local --cleanup # dry-run: list stale files - /ultracontinue-local --cleanup --confirm # actually delete (status: completed) + /trekcontinue --cleanup # dry-run: list stale files + /trekcontinue --cleanup --confirm # 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 , got a markdown file path: Did you mean to paste the file path as a project directory? -Usage: /ultracontinue-local +Usage: /trekcontinue ``` ### 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 `.) + `/trekcontinue `.) ## 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 ` after the + `/trekcontinue --cleanup --confirm ` 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, diff --git a/plugins/ultraplan-local/commands/trekendsession.md b/plugins/ultraplan-local/commands/trekendsession.md index 57810d2..7a4188d 100644 --- a/plugins/ultraplan-local/commands/trekendsession.md +++ b/plugins/ultraplan-local/commands/trekendsession.md @@ -5,25 +5,25 @@ argument-hint: " | --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 "" → writes state +/trekendsession "" → 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 - /ultraplan-end-session-local --help + /trekendsession + /trekendsession --help Both arguments are REQUIRED. No interactive prompt — headless-safe. @@ -51,10 +51,10 @@ Writes /.session-state.local.json with: updated_at 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 '' +Usage: /trekendsession '' ``` 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 /.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: Next session: Brief: -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 diff --git a/plugins/ultraplan-local/commands/trekexecute.md b/plugins/ultraplan-local/commands/trekexecute.md index 812640e..e57422d 100644 --- a/plugins/ultraplan-local/commands/trekexecute.md +++ b/plugins/ultraplan-local/commands/trekexecute.md @@ -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 `` argument is provided after flag parsing, use the derived `{dir}/plan.md`. If a `` 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 - /ultraexecute-local --project - /ultraexecute-local --fg - /ultraexecute-local --resume - /ultraexecute-local --dry-run - /ultraexecute-local --validate - /ultraexecute-local --step N - /ultraexecute-local --session N - /ultraexecute-local --project --resume - /ultraexecute-local --project --session N +Usage: /trekexecute + /trekexecute --project + /trekexecute --fg + /trekexecute --resume + /trekexecute --dry-run + /trekexecute --validate + /trekexecute --step N + /trekexecute --session N + /trekexecute --project --resume + /trekexecute --project --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: " - 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 `:** 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: `, `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 ` jumps directly +re-running `/trekexecute --resume --project ` 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//session-N` per wave. +cleanup ran). To inspect: `git log trekplan//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: ` so `/ultracontinue` Phase 1.5 can detect +and `produced_at: ` 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 diff --git a/plugins/ultraplan-local/commands/trekplan.md b/plugins/ultraplan-local/commands/trekplan.md index ee2fd0b..0d38c3c 100644 --- a/plugins/ultraplan-local/commands/trekplan.md +++ b/plugins/ultraplan-local/commands/trekplan.md @@ -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 ` or `--project `. 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 - /ultraplan-local --project - /ultraplan-local --brief --research - /ultraplan-local --project --fg - /ultraplan-local --project --quick - /ultraplan-local --export - /ultraplan-local --decompose +Usage: /trekplan --brief + /trekplan --project + /trekplan --brief --research + /trekplan --project --fg + /trekplan --project --quick + /trekplan --export + /trekplan --decompose -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). diff --git a/plugins/ultraplan-local/commands/trekresearch.md b/plugins/ultraplan-local/commands/trekresearch.md index 4c5df45..33159fb 100644 --- a/plugins/ultraplan-local/commands/trekresearch.md +++ b/plugins/ultraplan-local/commands/trekresearch.md @@ -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 → brief → /ultraplan-local --research +/trekresearch → brief → /trekplan --research ``` ## 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 ` — attach this research to an ultrabrief project folder. +5. `--project ` — 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 - /ultraresearch-local --quick - /ultraresearch-local --local - /ultraresearch-local --external - /ultraresearch-local --fg - /ultraresearch-local --project [--external|--local|--quick|--fg] +Usage: /trekresearch + /trekresearch --quick + /trekresearch --local + /trekresearch --external + /trekresearch --fg + /trekresearch --project [--external|--local|--quick|--fg] 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 --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 ` +- If `--project` was used: run `/trekplan --project {project_dir}` when all research topics are complete +- Otherwise: `/trekplan --research {brief_destination} --brief ` - 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 `. + If the user asks to plan, direct them to `/trekplan --research `. - **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. diff --git a/plugins/ultraplan-local/commands/trekreview.md b/plugins/ultraplan-local/commands/trekreview.md index e3d91e4..ffef44d 100644 --- a/plugins/ultraplan-local/commands/trekreview.md +++ b/plugins/ultraplan-local/commands/trekreview.md @@ -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 ` | valued | Required. Path to ultraplan-local project folder containing `brief.md`. | +| `--project ` | valued | Required. Path to trekplan project folder containing `brief.md`. | | `--since ` | 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 is required. - Usage: /ultrareview-local --project [--since ] [--quick] [--validate] [--dry-run] + Usage: /trekreview --project [--since ] [--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 ` 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. diff --git a/plugins/ultraplan-local/docs/HANDOVER-CONTRACTS.md b/plugins/ultraplan-local/docs/HANDOVER-CONTRACTS.md index 1150124..ce00859 100644 --- a/plugins/ultraplan-local/docs/HANDOVER-CONTRACTS.md +++ b/plugins/ultraplan-local/docs/HANDOVER-CONTRACTS.md @@ -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/.mjs --json ` 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/.mjs --json ` 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: [, ...]` 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: [, ...]` 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 `. 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 `. 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 `; 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 `; 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. diff --git a/plugins/ultraplan-local/docs/subagent-delegation-audit.md b/plugins/ultraplan-local/docs/subagent-delegation-audit.md index ec15ada..e4f624d 100644 --- a/plugins/ultraplan-local/docs/subagent-delegation-audit.md +++ b/plugins/ultraplan-local/docs/subagent-delegation-audit.md @@ -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) diff --git a/plugins/ultraplan-local/examples/01-add-verbose-flag/REGENERATED.md b/plugins/ultraplan-local/examples/01-add-verbose-flag/REGENERATED.md index 9ebe6a0..eedb702 100644 --- a/plugins/ultraplan-local/examples/01-add-verbose-flag/REGENERATED.md +++ b/plugins/ultraplan-local/examples/01-add-verbose-flag/REGENERATED.md @@ -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. diff --git a/plugins/ultraplan-local/examples/01-add-verbose-flag/brief.md b/plugins/ultraplan-local/examples/01-add-verbose-flag/brief.md index 3e36f84..f980305 100644 --- a/plugins/ultraplan-local/examples/01-add-verbose-flag/brief.md +++ b/plugins/ultraplan-local/examples/01-add-verbose-flag/brief.md @@ -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 diff --git a/plugins/ultraplan-local/examples/01-add-verbose-flag/plan.md b/plugins/ultraplan-local/examples/01-add-verbose-flag/plan.md index 97687c0..c059f22 100644 --- a/plugins/ultraplan-local/examples/01-add-verbose-flag/plan.md +++ b/plugins/ultraplan-local/examples/01-add-verbose-flag/plan.md @@ -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 diff --git a/plugins/ultraplan-local/examples/01-add-verbose-flag/research/01-cli-parser-conventions.md b/plugins/ultraplan-local/examples/01-add-verbose-flag/research/01-cli-parser-conventions.md index 0467a99..52f893c 100644 --- a/plugins/ultraplan-local/examples/01-add-verbose-flag/research/01-cli-parser-conventions.md +++ b/plugins/ultraplan-local/examples/01-add-verbose-flag/research/01-cli-parser-conventions.md @@ -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 diff --git a/plugins/ultraplan-local/examples/02-real-cli/REGENERATED.md b/plugins/ultraplan-local/examples/02-real-cli/REGENERATED.md index a17a230..d098d7d 100644 --- a/plugins/ultraplan-local/examples/02-real-cli/REGENERATED.md +++ b/plugins/ultraplan-local/examples/02-real-cli/REGENERATED.md @@ -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 diff --git a/plugins/ultraplan-local/examples/README.md b/plugins/ultraplan-local/examples/README.md index 50b9852..40bf16c 100644 --- a/plugins/ultraplan-local/examples/README.md +++ b/plugins/ultraplan-local/examples/README.md @@ -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. diff --git a/plugins/ultraplan-local/hooks/scripts/post-bash-stats.mjs b/plugins/ultraplan-local/hooks/scripts/post-bash-stats.mjs index 65030fd..451bd2f 100755 --- a/plugins/ultraplan-local/hooks/scripts/post-bash-stats.mjs +++ b/plugins/ultraplan-local/hooks/scripts/post-bash-stats.mjs @@ -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. // diff --git a/plugins/ultraplan-local/hooks/scripts/post-compact-flush.mjs b/plugins/ultraplan-local/hooks/scripts/post-compact-flush.mjs index b25a14b..7217961 100755 --- a/plugins/ultraplan-local/hooks/scripts/post-compact-flush.mjs +++ b/plugins/ultraplan-local/hooks/scripts/post-compact-flush.mjs @@ -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. // diff --git a/plugins/ultraplan-local/hooks/scripts/pre-compact-flush.mjs b/plugins/ultraplan-local/hooks/scripts/pre-compact-flush.mjs index a33d684..a9520ad 100644 --- a/plugins/ultraplan-local/hooks/scripts/pre-compact-flush.mjs +++ b/plugins/ultraplan-local/hooks/scripts/pre-compact-flush.mjs @@ -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: diff --git a/plugins/ultraplan-local/hooks/scripts/session-title.mjs b/plugins/ultraplan-local/hooks/scripts/session-title.mjs index 6346463..abd4155 100755 --- a/plugins/ultraplan-local/hooks/scripts/session-title.mjs +++ b/plugins/ultraplan-local/hooks/scripts/session-title.mjs @@ -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:: +// Title format: voyage:: // - ∈ {brief, research, plan, execute, review} // - ∈ first 30 chars of project slug, or "ad-hoc" when no // --project / --brief context is detected diff --git a/plugins/ultraplan-local/lib/parsers/arg-parser.mjs b/plugins/ultraplan-local/lib/parsers/arg-parser.mjs index 9913c3d..7dbafd3 100644 --- a/plugins/ultraplan-local/lib/parsers/arg-parser.mjs +++ b/plugins/ultraplan-local/lib/parsers/arg-parser.mjs @@ -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. diff --git a/plugins/ultraplan-local/lib/parsers/finding-id.mjs b/plugins/ultraplan-local/lib/parsers/finding-id.mjs index 462cf0e..2466506 100644 --- a/plugins/ultraplan-local/lib/parsers/finding-id.mjs +++ b/plugins/ultraplan-local/lib/parsers/finding-id.mjs @@ -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). diff --git a/plugins/ultraplan-local/lib/review/plan-review-dedup.mjs b/plugins/ultraplan-local/lib/review/plan-review-dedup.mjs index 7a4085a..cdfe7b2 100644 --- a/plugins/ultraplan-local/lib/review/plan-review-dedup.mjs +++ b/plugins/ultraplan-local/lib/review/plan-review-dedup.mjs @@ -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). // diff --git a/plugins/ultraplan-local/lib/review/rule-catalogue.mjs b/plugins/ultraplan-local/lib/review/rule-catalogue.mjs index 279a1f5..ffbfefd 100644 --- a/plugins/ultraplan-local/lib/review/rule-catalogue.mjs +++ b/plugins/ultraplan-local/lib/review/rule-catalogue.mjs @@ -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. diff --git a/plugins/ultraplan-local/lib/stats/cache-analyzer.mjs b/plugins/ultraplan-local/lib/stats/cache-analyzer.mjs index 72777e7..609ce72 100644 --- a/plugins/ultraplan-local/lib/stats/cache-analyzer.mjs +++ b/plugins/ultraplan-local/lib/stats/cache-analyzer.mjs @@ -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). // diff --git a/plugins/ultraplan-local/lib/util/autonomy-gate.mjs b/plugins/ultraplan-local/lib/util/autonomy-gate.mjs index 314899c..235d35e 100644 --- a/plugins/ultraplan-local/lib/util/autonomy-gate.mjs +++ b/plugins/ultraplan-local/lib/util/autonomy-gate.mjs @@ -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: diff --git a/plugins/ultraplan-local/lib/util/cleanup.mjs b/plugins/ultraplan-local/lib/util/cleanup.mjs index 6b35ab0..1e9422d 100644 --- a/plugins/ultraplan-local/lib/util/cleanup.mjs +++ b/plugins/ultraplan-local/lib/util/cleanup.mjs @@ -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.', )); } diff --git a/plugins/ultraplan-local/lib/validators/brief-validator.mjs b/plugins/ultraplan-local/lib/validators/brief-validator.mjs index b6f77f6..11ae69f 100644 --- a/plugins/ultraplan-local/lib/validators/brief-validator.mjs +++ b/plugins/ultraplan-local/lib/validators/brief-validator.mjs @@ -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'; diff --git a/plugins/ultraplan-local/lib/validators/next-session-prompt-validator.mjs b/plugins/ultraplan-local/lib/validators/next-session-prompt-validator.mjs index e4cd708..89df0f5 100644 --- a/plugins/ultraplan-local/lib/validators/next-session-prompt-validator.mjs +++ b/plugins/ultraplan-local/lib/validators/next-session-prompt-validator.mjs @@ -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. diff --git a/plugins/ultraplan-local/lib/validators/review-validator.mjs b/plugins/ultraplan-local/lib/validators/review-validator.mjs index 63b764b..3594d27 100644 --- a/plugins/ultraplan-local/lib/validators/review-validator.mjs +++ b/plugins/ultraplan-local/lib/validators/review-validator.mjs @@ -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'; diff --git a/plugins/ultraplan-local/lib/validators/session-state-validator.mjs b/plugins/ultraplan-local/lib/validators/session-state-validator.mjs index 71fb5f7..431dabb 100644 --- a/plugins/ultraplan-local/lib/validators/session-state-validator.mjs +++ b/plugins/ultraplan-local/lib/validators/session-state-validator.mjs @@ -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']; diff --git a/plugins/ultraplan-local/scripts/q3-cache-prefix-experiment.mjs b/plugins/ultraplan-local/scripts/q3-cache-prefix-experiment.mjs index da57852..5ac07ef 100644 --- a/plugins/ultraplan-local/scripts/q3-cache-prefix-experiment.mjs +++ b/plugins/ultraplan-local/scripts/q3-cache-prefix-experiment.mjs @@ -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. diff --git a/plugins/ultraplan-local/templates/headless-launch-template.md b/plugins/ultraplan-local/templates/headless-launch-template.md index 79fa34c..e59664a 100644 --- a/plugins/ultraplan-local/templates/headless-launch-template.md +++ b/plugins/ultraplan-local/templates/headless-launch-template.md @@ -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 diff --git a/plugins/ultraplan-local/templates/plan-template.md b/plugins/ultraplan-local/templates/plan-template.md index d7c3fbf..f249ff4 100644 --- a/plugins/ultraplan-local/templates/plan-template.md +++ b/plugins/ultraplan-local/templates/plan-template.md @@ -1,6 +1,6 @@