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 <noreply@anthropic.com>
This commit is contained in:
parent
ca5a8cec67
commit
14ecda886c
81 changed files with 672 additions and 672 deletions
|
|
@ -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.
|
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 |
|
| `/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 |
|
| `/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 |
|
| 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).
|
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 |
|
| Flag | Behavior |
|
||||||
|------|----------|
|
|------|----------|
|
||||||
|
|
@ -42,12 +42,12 @@ Always interactive. Phase 3 is a section-driven completeness loop (no hard cap o
|
||||||
|
|
||||||
Flags combine: `--project <dir> --local`, `--external --quick`.
|
Flags combine: `--project <dir> --local`, `--external --quick`.
|
||||||
|
|
||||||
### /ultraplan-local modes
|
### /trekplan modes
|
||||||
|
|
||||||
| Flag | Behavior |
|
| Flag | Behavior |
|
||||||
|------|----------|
|
|------|----------|
|
||||||
| `--project <dir>` | **Required path A** — read `{dir}/brief.md`, auto-discover `{dir}/research/*.md`, write `{dir}/plan.md` |
|
| `--project <dir>` | **Required path A** — read `{dir}/brief.md`, auto-discover `{dir}/research/*.md`, write `{dir}/plan.md` |
|
||||||
| `--brief <path>` | **Required path B** — plan from a specific brief file; write to `.claude/plans/ultraplan-{date}-{slug}.md` |
|
| `--brief <path>` | **Required path B** — plan from a specific brief file; write to `.claude/plans/trekplan-{date}-{slug}.md` |
|
||||||
| `--research <brief> [brief2]` | Enrich with extra research briefs beyond what is in `{project_dir}/research/` |
|
| `--research <brief> [brief2]` | Enrich with extra research briefs beyond what is in `{project_dir}/research/` |
|
||||||
| `--fg` | No-op alias (foreground is default since v2.4.0) |
|
| `--fg` | No-op alias (foreground is default since v2.4.0) |
|
||||||
| `--quick` | Plan directly (no agent swarm) |
|
| `--quick` | Plan directly (no agent swarm) |
|
||||||
|
|
@ -55,11 +55,11 @@ Flags combine: `--project <dir> --local`, `--external --quick`.
|
||||||
| `--decompose <plan>` | Split plan into self-contained headless sessions |
|
| `--decompose <plan>` | Split plan into self-contained headless sessions |
|
||||||
| `--gates {open\|closed\|adaptive}` | (v3.4.0) Autonomy-checkpoint policy. Default `adaptive` |
|
| `--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.
|
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 |
|
| 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 |
|
| `--session N` | Execute only session N from plan's Execution Strategy |
|
||||||
| `--gates {open\|closed\|adaptive}` | (v3.4.0) Autonomy-checkpoint policy. Default `adaptive` |
|
| `--gates {open\|closed\|adaptive}` | (v3.4.0) Autonomy-checkpoint policy. Default `adaptive` |
|
||||||
|
|
||||||
### /ultrareview-local modes
|
### /trekreview modes
|
||||||
|
|
||||||
| Flag | Behavior |
|
| Flag | Behavior |
|
||||||
|------|----------|
|
|------|----------|
|
||||||
| _(default)_ | Run brief-conformance + code-correctness reviewers in parallel, coordinator dedup + verdict, write `{project_dir}/review.md` |
|
| _(default)_ | Run brief-conformance + code-correctness reviewers in parallel, coordinator dedup + verdict, write `{project_dir}/review.md` |
|
||||||
| `--project <dir>` | **Required.** Path to ultraplan-local project folder containing `brief.md`. Review is written to `{dir}/review.md` |
|
| `--project <dir>` | **Required.** Path to trekplan project folder containing `brief.md`. Review is written to `{dir}/review.md` |
|
||||||
| `--since <ref>` | Override "before" SHA for the diff range. Validated via `git rev-parse --verify` |
|
| `--since <ref>` | Override "before" SHA for the diff range. Validated via `git rev-parse --verify` |
|
||||||
| `--quick` | Skip brief-conformance reviewer; skip coordinator's reasonableness filter — fast correctness-only pass |
|
| `--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 |
|
| `--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`
|
- `lib/validators/architecture-discovery.mjs` — drift-WARN external-contract discovery for `architecture/overview.md`
|
||||||
|
|
||||||
Wiring points (replaces previous prose-grep instructions):
|
Wiring points (replaces previous prose-grep instructions):
|
||||||
- `/ultrabrief-local` Phase 4g → `brief-validator` (post-write sanity check)
|
- `/trekbrief` Phase 4g → `brief-validator` (post-write sanity check)
|
||||||
- `/ultraplan-local` Phase 1 → `brief-validator --soft`, `research-validator --dir`, `architecture-discovery`
|
- `/trekplan` Phase 1 → `brief-validator --soft`, `research-validator --dir`, `architecture-discovery`
|
||||||
- `planning-orchestrator` Phase 5.5 → `plan-validator --strict` (replaces 3 `grep -cE` calls)
|
- `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).
|
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.
|
`docs/HANDOVER-CONTRACTS.md` is the single source of truth for the 7 pipeline handovers (brief→research, research→plan, architecture→plan EXTERNAL, plan→execute, progress.json resume, review→plan, `.session-state.local.json`). Read it before changing any artifact format.
|
||||||
|
|
||||||
`hooks/scripts/pre-compact-flush.mjs` (PreCompact event, CC v2.1.105+) fixes the documented P0 in `docs/ultraexecute-v2-observations-from-config-audit-v4.md`: keeps `progress.json` in sync with git history before context compaction so `--resume` works after long conversations. Atomic write, monotonic only, never blocks compaction.
|
`hooks/scripts/pre-compact-flush.mjs` (PreCompact event, CC v2.1.105+) fixes the documented P0 in `docs/trekexecute-v2-observations-from-config-audit-v4.md`: keeps `progress.json` in sync with git history before context compaction so `--resume` works after long conversations. Atomic write, monotonic only, never blocks compaction.
|
||||||
|
|
||||||
`hooks/scripts/session-title.mjs` (UserPromptSubmit, CC v2.1.94+) sets `sessionTitle` to `ultra:<command>:<slug>` for ultra-command invocations. Helps multi-session headless runs identify themselves in process lists.
|
`hooks/scripts/session-title.mjs` (UserPromptSubmit, CC v2.1.94+) sets `sessionTitle` to `voyage:<command>:<slug>` for voyage-command invocations. Helps multi-session headless runs identify themselves in process lists.
|
||||||
|
|
||||||
`hooks/scripts/post-bash-stats.mjs` (PostToolUse, CC v2.1.97+) appends `duration_ms` for each Bash call into `${CLAUDE_PLUGIN_DATA}/trekexecute-stats.jsonl`. Useful for finding long-running verify or checkpoint commands.
|
`hooks/scripts/post-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)
|
## 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 |
|
| `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) |
|
| `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)
|
### Path A/B/C decision (v3.4.0; Path C closed 2026-05-05)
|
||||||
|
|
||||||
Three architectural options were considered for the speedup work:
|
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 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`.
|
- **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.
|
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.
|
**Decompose:** Parse plan → Analyze step dependencies → Group into sessions → Identify parallel waves → Generate session specs + dependency graph + launch script.
|
||||||
|
|
||||||
**Execute:** Parse plan → Security scan (Phase 2.4) → Detect Execution Strategy → Single-session (step loop) or multi-session (parallel waves via `claude -p` with scoped `--allowedTools`) → Phase 7.5 manifest audit → Phase 7.6 bounded recovery (if partial) → Phase 8 atomically writes `progress.json` + `.session-state.local.json` (Handover 7) → Report. With `--project`, reads `{dir}/plan.md`. Phase 2.55 (pre-flight stop) and Phase 4 (entry-condition stop) also write `.session-state.local.json` so `/ultracontinue` can surface the stop and prompt for next steps.
|
**Execute:** Parse plan → Security scan (Phase 2.4) → Detect Execution Strategy → Single-session (step loop) or multi-session (parallel waves via `claude -p` with scoped `--allowedTools`) → Phase 7.5 manifest audit → Phase 7.6 bounded recovery (if partial) → Phase 8 atomically writes `progress.json` + `.session-state.local.json` (Handover 7) → Report. With `--project`, reads `{dir}/plan.md`. Phase 2.55 (pre-flight stop) and Phase 4 (entry-condition stop) also write `.session-state.local.json` so `/trekcontinue` can surface the stop and prompt for next steps.
|
||||||
|
|
||||||
**Continue:** `/ultracontinue-local` reads `{dir}/.session-state.local.json` (Handover 7), validates schema-v1 via `session-state-validator`, narrates a 3-line summary (project / next-session-label / brief-path), and immediately begins executing the next session. Auto-discovers active project state files under `.claude/projects/*/.session-state.local.json` if no explicit `<project-dir>` argument. Operator-invoked only — never auto-loaded via SessionStart. The `/ultraplan-end-session-local` helper is the informal-flow producer: writes the same state file for ad-hoc multi-session handovers that don't run through `/ultraexecute-local`.
|
**Continue:** `/trekcontinue` reads `{dir}/.session-state.local.json` (Handover 7), validates schema-v1 via `session-state-validator`, narrates a 3-line summary (project / next-session-label / brief-path), and immediately begins executing the next session. Auto-discovers active project state files under `.claude/projects/*/.session-state.local.json` if no explicit `<project-dir>` argument. Operator-invoked only — never auto-loaded via SessionStart. The `/trekendsession` helper is the informal-flow producer: writes the same state file for ad-hoc multi-session handovers that don't run through `/trekexecute`.
|
||||||
|
|
||||||
**Security:** 4-layer defense-in-depth: plugin hooks (pre-bash-executor, pre-write-executor), prompt-level denylist (works in headless sessions), pre-execution plan scan (Phase 2.4), scoped `--allowedTools` replacing `--dangerously-skip-permissions`. Hard Rules 14-16 enforce verify command security, repo-boundary writes, and sensitive path protection.
|
**Security:** 4-layer defense-in-depth: plugin hooks (pre-bash-executor, pre-write-executor), prompt-level denylist (works in headless sessions), pre-execution plan scan (Phase 2.4), scoped `--allowedTools` replacing `--dangerously-skip-permissions`. Hard Rules 14-16 enforce verify command security, repo-boundary writes, and sensitive path protection.
|
||||||
|
|
||||||
**Pipeline:** `/ultrabrief-local` produces the task brief. `/ultraresearch-local --project <dir>` fills in `{dir}/research/`. `/ultraplan-local --project <dir>` reads brief + research to produce `{dir}/plan.md` (and auto-discovers `{dir}/architecture/overview.md` if an opt-in upstream architect plugin produced one). `/ultraexecute-local --project <dir>` executes and writes `{dir}/progress.json`. All artifacts live in one project directory.
|
**Pipeline:** `/trekbrief` produces the task brief. `/trekresearch --project <dir>` fills in `{dir}/research/`. `/trekplan --project <dir>` reads brief + research to produce `{dir}/plan.md` (and auto-discovers `{dir}/architecture/overview.md` if an opt-in upstream architect plugin produced one). `/trekexecute --project <dir>` executes and writes `{dir}/progress.json`. All artifacts live in one project directory.
|
||||||
|
|
||||||
**Project-directory contract (v3.0.0):** ultraplan-local owns the directory layout below. The `architecture/` subdirectory is opt-in and produced by an opt-in upstream architect plugin (not bundled) — the architect plugin is no longer publicly distributed, but the `architecture/overview.md` slot remains available for any compatible producer.
|
**Project-directory contract (v3.0.0):** trekplan owns the directory layout below. The `architecture/` subdirectory is opt-in and produced by an opt-in upstream architect plugin (not bundled) — the architect plugin is no longer publicly distributed, but the `architecture/overview.md` slot remains available for any compatible producer.
|
||||||
|
|
||||||
```
|
```
|
||||||
.claude/projects/{YYYY-MM-DD}-{slug}/
|
.claude/projects/{YYYY-MM-DD}-{slug}/
|
||||||
brief.md ← ultrabrief-local writes; everyone reads
|
brief.md ← trekbrief writes; everyone reads
|
||||||
research/*.md ← ultraresearch-local writes; plan + architect read
|
research/*.md ← trekresearch writes; plan + architect read
|
||||||
architecture/ ← OPT-IN, owned by an opt-in upstream architect plugin (not bundled)
|
architecture/ ← OPT-IN, owned by an opt-in upstream architect plugin (not bundled)
|
||||||
overview.md
|
overview.md
|
||||||
gaps.md
|
gaps.md
|
||||||
plan.md ← ultraplan-local writes; ultraexecute reads
|
plan.md ← trekplan writes; trekexecute reads
|
||||||
progress.json ← ultraexecute-local writes
|
progress.json ← trekexecute writes
|
||||||
```
|
```
|
||||||
|
|
||||||
No code-level dependency between plugins — the contract is filesystem-level only.
|
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):
|
All artifacts in one project directory (default):
|
||||||
- Project root: `.claude/projects/{YYYY-MM-DD}-{slug}/`
|
- Project root: `.claude/projects/{YYYY-MM-DD}-{slug}/`
|
||||||
- `brief.md` (task brief from `/ultrabrief-local`)
|
- `brief.md` (task brief from `/trekbrief`)
|
||||||
- `research/{NN}-{slug}.md` (research briefs from `/ultraresearch-local --project`)
|
- `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)
|
- `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`)
|
- `sessions/session-*.md` (from `--decompose`)
|
||||||
- `progress.json` (from `/ultraexecute-local --project`)
|
- `progress.json` (from `/trekexecute --project`)
|
||||||
- `review.md` (from `/ultrareview-local --project`)
|
- `review.md` (from `/trekreview --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`)
|
- `.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`):
|
Legacy paths (still work without `--project`):
|
||||||
- Research briefs: `.claude/research/ultraresearch-{date}-{slug}.md`
|
- Research briefs: `.claude/research/trekresearch-{date}-{slug}.md`
|
||||||
- Plans: `.claude/plans/ultraplan-{date}-{slug}.md`
|
- Plans: `.claude/plans/trekplan-{date}-{slug}.md`
|
||||||
- Sessions: `.claude/ultraplan-sessions/{slug}/session-*.md`
|
- Sessions: `.claude/trekplan-sessions/{slug}/session-*.md`
|
||||||
- Launch scripts: `.claude/ultraplan-sessions/{slug}/launch.sh`
|
- Launch scripts: `.claude/trekplan-sessions/{slug}/launch.sh`
|
||||||
- Progress: `{plan-dir}/.ultraexecute-progress-{slug}.json`
|
- Progress: `{plan-dir}/.trekexecute-progress-{slug}.json`
|
||||||
|
|
||||||
Stats:
|
Stats:
|
||||||
- Brief stats: `${CLAUDE_PLUGIN_DATA}/trekbrief-stats.jsonl`
|
- Brief stats: `${CLAUDE_PLUGIN_DATA}/trekbrief-stats.jsonl`
|
||||||
|
|
@ -230,10 +230,10 @@ Stats:
|
||||||
|
|
||||||
## Terminology
|
## Terminology
|
||||||
|
|
||||||
- **Task brief** — produced by `/ultrabrief-local`. Declares intent, goal, and research plan. Drives planning.
|
- **Task brief** — produced by `/trekbrief`. Declares intent, goal, and research plan. Drives planning.
|
||||||
- **Research brief** — produced by `/ultraresearch-local`. Answers a specific research question. Feeds 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.
|
- **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.
|
- **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 (`/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`).
|
- **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).
|
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).
|
||||||
|
|
|
||||||
|
|
@ -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.
|
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 |
|
| File | Purpose |
|
||||||
|------|---------|
|
|------|---------|
|
||||||
| `.claude-plugin/plugin.json` | Plugin manifest |
|
| `.claude-plugin/plugin.json` | Plugin manifest |
|
||||||
| `commands/ultraresearch-local.md` | The `/ultraresearch-local` slash command — research orchestration |
|
| `commands/trekresearch.md` | The `/trekresearch` slash command — research orchestration |
|
||||||
| `commands/ultraplan-local.md` | The `/ultraplan-local` slash command — planning orchestration |
|
| `commands/trekplan.md` | The `/trekplan` slash command — planning orchestration |
|
||||||
| `commands/ultraexecute-local.md` | The `/ultraexecute-local` slash command — execution orchestration |
|
| `commands/trekexecute.md` | The `/trekexecute` slash command — execution orchestration |
|
||||||
| `agents/*.md` | 19 specialized agents for research, exploration, review, and orchestration |
|
| `agents/*.md` | 19 specialized agents for research, exploration, review, and orchestration |
|
||||||
| `templates/plan-template.md` | Structured plan output format |
|
| `templates/plan-template.md` | Structured plan output format |
|
||||||
| `templates/research-brief-template.md` | Research brief format with triangulation and confidence |
|
| `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
|
## Testing locally
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
claude --plugin-dir /path/to/ultraplan-local
|
claude --plugin-dir /path/to/trekplan
|
||||||
# Then in the session:
|
# Then in the session:
|
||||||
/ultraresearch-local <research question>
|
/trekresearch <research question>
|
||||||
/ultraplan-local <describe a task>
|
/trekplan <describe a task>
|
||||||
/ultraexecute-local <path to plan>
|
/trekexecute <path to plan>
|
||||||
```
|
```
|
||||||
|
|
||||||
Verify:
|
Verify:
|
||||||
- `/ultraresearch-local`: Research agents spawn, brief written to `.claude/research/`
|
- `/trekresearch`: 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
|
- `/trekplan`: 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
|
- `/trekexecute`: Steps execute with verify + checkpoint per step
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# ultraplan-local — Brief, Research, Plan, Execute, Review, Continue
|
# trekplan — Brief, Research, Plan, Execute, Review, Continue
|
||||||
|
|
||||||

|

|
||||||

|

|
||||||
|
|
@ -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) |
|
| `/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` |
|
| `/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 |
|
| `/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.
|
**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
|
### Two kinds of briefs
|
||||||
|
|
||||||
Terminology matters:
|
Terminology matters:
|
||||||
- **Task brief** — produced by `/ultrabrief-local`. Captures *what we want and why*. Drives planning.
|
- **Task brief** — produced by `/trekbrief`. Captures *what we want and why*. Drives planning.
|
||||||
- **Research brief** — produced by `/ultraresearch-local`. Captures *what we learned about a topic*. Feeds 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.
|
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).
|
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**.
|
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. |
|
| `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. |
|
| `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
|
## 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
|
- The task is a single-file change where the fix is obvious
|
||||||
- You already know exactly what to change and in what order
|
- 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
|
## 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".
|
**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:**
|
**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.
|
- 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.
|
Interactive requirements-gathering command. Runs a **dynamic, quality-gated interview** and produces a **task brief** with an explicit research plan. Optionally orchestrates the rest of the pipeline.
|
||||||
|
|
||||||
|
|
@ -148,7 +148,7 @@ Output: `.claude/projects/{YYYY-MM-DD}-{slug}/brief.md`
|
||||||
| **Default** | `/trekbrief <task>` | Dynamic interview until quality gates pass. No question cap. |
|
| **Default** | `/trekbrief <task>` | Dynamic interview until quality gates pass. No question cap. |
|
||||||
| **Quick** | `/trekbrief --quick <task>` | Starts compact (optional sections get at most one probe), still escalates on weak required sections or failed review gate. |
|
| **Quick** | `/trekbrief --quick <task>` | Starts compact (optional sections get at most one probe), still escalates on weak required sections or failed review gate. |
|
||||||
|
|
||||||
`/ultrabrief-local` is **always interactive**. There is no foreground/background mode — the interview requires user input.
|
`/trekbrief` is **always interactive**. There is no foreground/background mode — the interview requires user input.
|
||||||
|
|
||||||
### Force-stop
|
### 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
|
- **Non-Goals** — explicitly out of scope
|
||||||
- **Constraints / Preferences / NFRs** — technical, time, resource limits
|
- **Constraints / Preferences / NFRs** — technical, time, resource limits
|
||||||
- **Success Criteria** — 2-4 falsifiable commands/observations
|
- **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
|
- **Open Questions / Assumptions** — from "I don't know" answers and implicit gaps
|
||||||
- **Prior Attempts** — what worked/failed before
|
- **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.
|
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:
|
Output:
|
||||||
- With `--project <dir>`: `{dir}/research/{NN}-{slug}.md` (auto-incremented index)
|
- With `--project <dir>`: `{dir}/research/{NN}-{slug}.md` (auto-incremented index)
|
||||||
- Without: `.claude/research/ultraresearch-{date}-{slug}.md`
|
- Without: `.claude/research/trekresearch-{date}-{slug}.md`
|
||||||
|
|
||||||
### Modes
|
### 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.
|
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:
|
Output:
|
||||||
- With `--project <dir>`: `{dir}/plan.md`
|
- With `--project <dir>`: `{dir}/plan.md`
|
||||||
- With `--brief <path>`: `.claude/plans/ultraplan-{date}-{slug}.md`
|
- With `--brief <path>`: `.claude/plans/trekplan-{date}-{slug}.md`
|
||||||
|
|
||||||
### Modes
|
### Modes
|
||||||
|
|
||||||
|
|
@ -218,7 +218,7 @@ Output:
|
||||||
| **Decompose** | `/trekplan --decompose plan.md` | Split plan into headless session specs |
|
| **Decompose** | `/trekplan --decompose plan.md` | Split plan into headless session specs |
|
||||||
| **Export** | `/trekplan --export pr plan.md` | PR description, issue comment, or clean markdown |
|
| **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
|
### 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.
|
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)
|
### 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
|
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}`)
|
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
|
### 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:
|
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
|
- **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
|
### 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
|
- **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
|
- **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+)
|
#### 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
|
connect, multiplying across waves. Setting it lets MCP connect lazily
|
||||||
on first tool call.
|
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
|
A `UserPromptSubmit` hook (`hooks/scripts/session-title.mjs`) sets the
|
||||||
session title to `ultra:<command>:<slug>` whenever you invoke one of
|
session title to `voyage:<command>:<slug>` whenever you invoke one of
|
||||||
the four ultra commands. This makes multi-session headless runs and
|
the four voyage commands. This makes multi-session headless runs and
|
||||||
session-picker output trivially identifiable. Slug derivation:
|
session-picker output trivially identifiable. Slug derivation:
|
||||||
|
|
||||||
| Invocation | Session title |
|
| Invocation | Session title |
|
||||||
|-----------|---------------|
|
|-----------|---------------|
|
||||||
| `/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth` | `ultra:plan:jwt-auth` |
|
| `/trekplan --project .claude/projects/2026-04-18-jwt-auth` | `voyage:plan:jwt-auth` |
|
||||||
| `/ultrabrief-local --quick` | `ultra:brief:ad-hoc` |
|
| `/trekbrief --quick` | `voyage:brief:ad-hoc` |
|
||||||
| `/ultraexecute-local --project .claude/projects/2026-05-10-cleanup --resume` | `ultra:execute:cleanup` |
|
| `/trekexecute --project .claude/projects/2026-05-10-cleanup --resume` | `voyage:execute:cleanup` |
|
||||||
|
|
||||||
The hook is fail-open — any error → title is left untouched.
|
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
|
A `PostToolUse` hook (`hooks/scripts/post-bash-stats.mjs`) appends
|
||||||
`duration_ms` from each Bash tool call to
|
`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
|
call; useful for identifying long-running verify or checkpoint commands
|
||||||
across executions.
|
across executions.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## `/ultrareview-local` — Review
|
## `/trekreview` — Review
|
||||||
|
|
||||||
Independent post-hoc review of delivered code against the brief. Reads `brief.md`
|
Independent post-hoc review of delivered code against the brief. Reads `brief.md`
|
||||||
from scratch and treats research/plan as supplementary context. The output
|
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
|
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.
|
the iteration loop without ad-hoc conventions.
|
||||||
|
|
||||||
### Modes
|
### 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 Code session — the command reads the per-project state file
|
||||||
(`.claude/projects/<project>/.session-state.local.json`), prints a 3-line
|
(`.claude/projects/<project>/.session-state.local.json`), prints a 3-line
|
||||||
summary, and immediately begins executing the next session.
|
summary, and immediately begins executing the next session.
|
||||||
|
|
||||||
The state file is the contract — any session-end mechanism may write it
|
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;
|
(`/trekexecute` Phase 8 / Phase 2.55 / Phase 4 do so automatically;
|
||||||
the `/ultraplan-end-session-local` helper writes it for informal flows;
|
the `/trekendsession` helper writes it for informal flows;
|
||||||
`graceful-handoff` may converge on it in a future release). `/ultracontinue`
|
`graceful-handoff` may converge on it in a future release). `/trekcontinue`
|
||||||
only reads. See **Handover 7** in `docs/HANDOVER-CONTRACTS.md` for the full
|
only reads. See **Handover 7** in `docs/HANDOVER-CONTRACTS.md` for the full
|
||||||
schema and producer/consumer contract.
|
schema and producer/consumer contract.
|
||||||
|
|
||||||
|
|
@ -449,9 +449,9 @@ schema and producer/consumer contract.
|
||||||
|
|
||||||
| Mode | Command | Description |
|
| Mode | Command | Description |
|
||||||
|------|---------|-------------|
|
|------|---------|-------------|
|
||||||
| **Default** | `/ultracontinue` | Auto-discover `.session-state.local.json` under cwd, validate, narrate, and begin executing the next session |
|
| **Default** | `/trekcontinue` | Auto-discover `.session-state.local.json` under cwd, validate, narrate, and begin executing the next session |
|
||||||
| **Explicit** | `/ultracontinue <project-dir>` | Use the named project directory; helpful when several active projects coexist under cwd |
|
| **Explicit** | `/trekcontinue <project-dir>` | Use the named project directory; helpful when several active projects coexist under cwd |
|
||||||
| **Help** | `/ultracontinue --help` | Print usage block and the schema-v1 reference |
|
| **Help** | `/trekcontinue --help` | Print usage block and the schema-v1 reference |
|
||||||
|
|
||||||
### Schema v1 — `.session-state.local.json`
|
### 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.
|
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
|
(ad-hoc release runs, manual handovers), use the helper to write the state
|
||||||
file at session-end:
|
file at session-end:
|
||||||
|
|
||||||
```bash
|
```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.
|
# 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.
|
Both arguments are required. No interactive prompt — headless-safe.
|
||||||
|
|
@ -484,12 +484,12 @@ Both arguments are required. No interactive prompt — headless-safe.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Session 1 (long-running formal pipeline)
|
# Session 1 (long-running formal pipeline)
|
||||||
/ultraplan-local --project .claude/projects/2026-05-01-feature
|
/trekplan --project .claude/projects/2026-05-01-feature
|
||||||
/ultraexecute-local --project .claude/projects/2026-05-01-feature
|
/trekexecute --project .claude/projects/2026-05-01-feature
|
||||||
# ... ultraexecute Phase 8 writes .session-state.local.json on session-end ...
|
# ... trekexecute Phase 8 writes .session-state.local.json on session-end ...
|
||||||
|
|
||||||
# (chat boundary — fresh Claude Code session)
|
# (chat boundary — fresh Claude Code session)
|
||||||
/ultracontinue
|
/trekcontinue
|
||||||
# → reads state, prints 3-line summary, begins next session
|
# → 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
|
## The full pipeline
|
||||||
|
|
||||||
```
|
```
|
||||||
/ultrabrief-local /ultraresearch-local /ultraplan-local /ultraexecute-local
|
/trekbrief /trekresearch /trekplan /trekexecute
|
||||||
┌──────────────┐ ┌───────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
|
┌──────────────┐ ┌───────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
|
||||||
│ Interview │ │ 5 local agents │ │ brief-reviewer │ │ Parse plan │
|
│ Interview │ │ 5 local agents │ │ brief-reviewer │ │ Parse plan │
|
||||||
│ ↓ │ │ 4 external agents │ │ ↓ │ │ ↓ │
|
│ ↓ │ │ 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}/`.
|
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
|
### Example workflows
|
||||||
|
|
||||||
**Standard pipeline (manual control):**
|
**Standard pipeline (manual control):**
|
||||||
```bash
|
```bash
|
||||||
/ultrabrief-local Add session caching with Redis
|
/trekbrief Add session caching with Redis
|
||||||
# → .claude/projects/2026-04-18-redis-session-caching/brief.md
|
# → .claude/projects/2026-04-18-redis-session-caching/brief.md
|
||||||
# Interview identifies 2 research topics.
|
# Interview identifies 2 research topics.
|
||||||
|
|
||||||
/ultraresearch-local --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 --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 --local "How is caching currently handled in the codebase?"
|
||||||
# → .claude/projects/2026-04-18-redis-session-caching/research/01-*.md, 02-*.md
|
# → .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
|
# → .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
|
# → progress.json + code changes
|
||||||
```
|
```
|
||||||
|
|
||||||
**Auto-mode (Claude manages the pipeline):**
|
**Auto-mode (Claude manages the pipeline):**
|
||||||
```bash
|
```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.
|
# Interview identifies topics. Choose "Auto (managed by Claude Code)" when asked.
|
||||||
# Claude runs research in parallel, then planning in foreground.
|
# Claude runs research in parallel, then planning in foreground.
|
||||||
# Returns when plan.md is ready.
|
# 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):**
|
**Standalone research (no planning):**
|
||||||
```bash
|
```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.
|
# Read the brief, share with team, use for decision-making.
|
||||||
```
|
```
|
||||||
|
|
||||||
**Quick plan for small tasks:**
|
**Quick plan for small tasks:**
|
||||||
```bash
|
```bash
|
||||||
/ultrabrief-local --quick Fix the login redirect bug
|
/trekbrief --quick Fix the login redirect bug
|
||||||
/ultraplan-local --project .claude/projects/2026-04-18-login-redirect-fix --quick
|
/trekplan --project .claude/projects/2026-04-18-login-redirect-fix --quick
|
||||||
/ultraexecute-local --project .claude/projects/2026-04-18-login-redirect-fix
|
/trekexecute --project .claude/projects/2026-04-18-login-redirect-fix
|
||||||
```
|
```
|
||||||
|
|
||||||
**Dry run + validate before executing:**
|
**Dry run + validate before executing:**
|
||||||
```bash
|
```bash
|
||||||
/ultraexecute-local --project <dir> --validate # schema check, no execution
|
/trekexecute --project <dir> --validate # schema check, no execution
|
||||||
/ultraexecute-local --project <dir> --dry-run # preview sessions and billing
|
/trekexecute --project <dir> --dry-run # preview sessions and billing
|
||||||
/ultraexecute-local --project <dir> # execute
|
/trekexecute --project <dir> # execute
|
||||||
```
|
```
|
||||||
|
|
||||||
**Review feedback loop (Handover 6):**
|
**Review feedback loop (Handover 6):**
|
||||||
```bash
|
```bash
|
||||||
/ultrareview-local --project <dir>
|
/trekreview --project <dir>
|
||||||
# → review.md with severity-tagged findings + verdict (BLOCK / WARN / ALLOW)
|
# → review.md with severity-tagged findings + verdict (BLOCK / WARN / ALLOW)
|
||||||
|
|
||||||
# If verdict is BLOCK or WARN, feed findings back into a remediation plan:
|
# If verdict is BLOCK or WARN, feed findings back into a remediation plan:
|
||||||
/ultraplan-local --brief <dir>/review.md
|
/trekplan --brief <dir>/review.md
|
||||||
# → plan.md with source_findings: [<id>, ...] audit trail
|
# → plan.md with source_findings: [<id>, ...] audit trail
|
||||||
|
|
||||||
/ultraexecute-local --project <dir> # execute the remediation plan
|
/trekexecute --project <dir> # execute the remediation plan
|
||||||
|
|
||||||
/ultrareview-local --project <dir> # re-review (overwrites review.md)
|
/trekreview --project <dir> # re-review (overwrites review.md)
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
@ -593,7 +593,7 @@ Migration notes for breaking changes (v1.x → v2.0, v2.x → v3.0) live in [CHA
|
||||||
The plugin ships with `node:test`-based unit tests and a `lib/` directory of pure-JS validators wired into the commands. Forking the plugin for internal use? Run `npm test` to confirm the parsers, validators, and doc-consistency invariants still hold:
|
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
|
```bash
|
||||||
cd plugins/ultraplan-local
|
cd plugins/trekplan
|
||||||
npm test # runs all tests under tests/**/*.test.mjs
|
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+)
|
### 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
|
## 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
|
## Installation
|
||||||
|
|
||||||
|
|
@ -638,16 +638,16 @@ Or enable directly in `~/.claude/settings.json`:
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"enabledPlugins": {
|
"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
|
## 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
|
## Requirements
|
||||||
|
|
||||||
|
|
@ -661,9 +661,9 @@ Opus runs the orchestrators (one per command) and the executor (one per plan ses
|
||||||
Top-level layout:
|
Top-level layout:
|
||||||
|
|
||||||
```
|
```
|
||||||
ultraplan-local/
|
trekplan/
|
||||||
├── agents/ 23 specialized agents (sonnet for exploration + review, opus for orchestration)
|
├── 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
|
├── templates/ Frontmatter templates for brief, research, plan, session, launch
|
||||||
├── hooks/ 5 hooks (pre-bash, pre-write, session-title, post-bash-stats, pre-compact-flush)
|
├── 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/)
|
├── 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
|
### 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
|
They read the codebase and contribute structured findings to plan
|
||||||
synthesis.
|
synthesis.
|
||||||
|
|
||||||
|
|
@ -702,26 +702,26 @@ synthesis.
|
||||||
|
|
||||||
### Switch the planning model
|
### Switch the planning model
|
||||||
|
|
||||||
The default for `/ultrabrief-local`, `/ultraresearch-local`,
|
The default for `/trekbrief`, `/trekresearch`,
|
||||||
`/ultraplan-local`, and `/ultraexecute-local` is `opus` (deep
|
`/trekplan`, and `/trekexecute` is `opus` (deep
|
||||||
reasoning). To run on Sonnet for cost or latency, search-and-replace
|
reasoning). To run on Sonnet for cost or latency, search-and-replace
|
||||||
the frontmatter in three files:
|
the frontmatter in three files:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
sed -i.bak 's/^model: opus$/model: sonnet/' \
|
sed -i.bak 's/^model: opus$/model: sonnet/' \
|
||||||
commands/ultrabrief-local.md \
|
commands/trekbrief.md \
|
||||||
commands/ultraresearch-local.md \
|
commands/trekresearch.md \
|
||||||
commands/ultraplan-local.md \
|
commands/trekplan.md \
|
||||||
commands/ultraexecute-local.md
|
commands/trekexecute.md
|
||||||
```
|
```
|
||||||
|
|
||||||
The exploration agents stay on Sonnet — only the orchestrator is bumped.
|
The exploration agents stay on Sonnet — only the orchestrator is bumped.
|
||||||
|
|
||||||
### Disable external research
|
### 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
|
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
|
of the `--local` argument check. Or just always pass `--local` and
|
||||||
document it in your team's CLAUDE.md.
|
document it in your team's CLAUDE.md.
|
||||||
|
|
||||||
|
|
@ -744,7 +744,7 @@ schema drift.
|
||||||
|
|
||||||
### Disable the architect bridge
|
### 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
|
opt-in upstream architect plugin (not bundled) produced one. To
|
||||||
suppress this, leave the `architecture/` directory absent from your
|
suppress this, leave the `architecture/` directory absent from your
|
||||||
project directory. Discovery is additive — missing file is fine, no
|
project directory. Discovery is additive — missing file is fine, no
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# Security Policy — ultraplan-local
|
# Security Policy — trekplan
|
||||||
|
|
||||||
## Reporting a vulnerability
|
## 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-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-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` |
|
| `pre-compact-flush.mjs` | `PreCompact` | Flushes `progress.json` from git history before compaction (P0 drift fix); read-only beyond `progress.json` |
|
||||||
| `session-title.mjs` *(planned, F9)* | `UserPromptSubmit` | Sets session title `ultra:<command>:<slug>` for headless multiplexing |
|
| `session-title.mjs` *(planned, F9)* | `UserPromptSubmit` | Sets session title `voyage:<command>:<slug>` for headless multiplexing |
|
||||||
|
|
||||||
All hooks are zero-dependency Node.js (`.mjs`) scripts and are designed
|
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 **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
|
to stderr only; they never write to user files outside their declared
|
||||||
scope.
|
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
|
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
|
sessions where hooks may not fire. This is layer 4 of the defense-in-depth
|
||||||
|
|
|
||||||
|
|
@ -5,11 +5,11 @@ description: |
|
||||||
tech stack, patterns, anti-patterns, and key abstractions.
|
tech stack, patterns, anti-patterns, and key abstractions.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: Ultraplan exploration phase needs architecture overview
|
Context: Voyage exploration phase needs architecture overview
|
||||||
user: "/ultraplan-local Add authentication to the API"
|
user: "/trekplan Add authentication to the API"
|
||||||
assistant: "Launching architecture-mapper to analyze codebase structure and patterns."
|
assistant: "Launching architecture-mapper to analyze codebase structure and patterns."
|
||||||
<commentary>
|
<commentary>
|
||||||
Phase 5 of ultraplan triggers this agent for every codebase size.
|
Phase 5 of trekplan triggers this agent for every codebase size.
|
||||||
</commentary>
|
</commentary>
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
name: brief-conformance-reviewer
|
name: brief-conformance-reviewer
|
||||||
description: |
|
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
|
against the task brief — every Success Criterion must trace to delivered
|
||||||
code, every Non-Goal must remain unbuilt. Emits findings with rule_keys
|
code, every Non-Goal must remain unbuilt. Emits findings with rule_keys
|
||||||
from the canonical RULE_CATALOGUE. Never praises.
|
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
|
changed files with per-file content excerpts when the diff is too
|
||||||
large).
|
large).
|
||||||
- **Triage map** — `{file → deep-review|summary-only|skip}` from the
|
- **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
|
skipped files unless the skip itself is wrong (then emit
|
||||||
`COVERAGE_SILENT_SKIP`).
|
`COVERAGE_SILENT_SKIP`).
|
||||||
- **Rule catalogue** — the 12-key catalogue in
|
- **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) |
|
| **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
|
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
|
### 3. Trace each Non-Goal to delivered code
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -7,8 +7,8 @@ description: |
|
||||||
exploration with a flawed brief.
|
exploration with a flawed brief.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: Ultraplan runs brief review before exploration
|
Context: Voyage runs brief review before exploration
|
||||||
user: "/ultraplan-local --project .claude/projects/2026-04-18-notifications"
|
user: "/trekplan --project .claude/projects/2026-04-18-notifications"
|
||||||
assistant: "Reviewing brief quality before launching exploration agents."
|
assistant: "Reviewing brief quality before launching exploration agents."
|
||||||
<commentary>
|
<commentary>
|
||||||
Orchestrator Phase 1b triggers this agent after the brief is available.
|
Orchestrator Phase 1b triggers this agent after the brief is available.
|
||||||
|
|
@ -35,8 +35,8 @@ missing, vague, or contradictory.
|
||||||
|
|
||||||
## Input
|
## Input
|
||||||
|
|
||||||
You receive the path to a brief file (ultrabrief v2.0 format, produced by
|
You receive the path to a brief file (trekbrief v2.0 format, produced by
|
||||||
`/ultrabrief-local`). Read it and evaluate its quality across five dimensions.
|
`/trekbrief`). Read it and evaluate its quality across five dimensions.
|
||||||
|
|
||||||
A brief has these sections (see template for full structure):
|
A brief has these sections (see template for full structure):
|
||||||
- `## Intent` — why the work matters (load-bearing)
|
- `## Intent` — why the work matters (load-bearing)
|
||||||
|
|
@ -115,18 +115,18 @@ Flag as **unclear scope** if:
|
||||||
### 5. Research Plan validity (NEW in v2.0)
|
### 5. Research Plan validity (NEW in v2.0)
|
||||||
|
|
||||||
The `## Research Plan` section declares topics that must be answered before
|
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:**
|
**Per topic:**
|
||||||
- **Research question:** phrased as a question, ends in `?`, answerable by
|
- **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?")
|
the tradeoffs between library X and library Y for our use case?")
|
||||||
- **Required for plan steps:** names specific kinds of steps that consume
|
- **Required for plan steps:** names specific kinds of steps that consume
|
||||||
this answer (e.g., "migration strategy", "library selection", "threat model")
|
this answer (e.g., "migration strategy", "library selection", "threat model")
|
||||||
- **Confidence needed:** one of `high`, `medium`, `low`
|
- **Confidence needed:** one of `high`, `medium`, `low`
|
||||||
- **Estimated cost:** one of `quick`, `standard`, `deep`
|
- **Estimated cost:** one of `quick`, `standard`, `deep`
|
||||||
- **Scope hint:** one of `local`, `external`, `both`
|
- **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:**
|
**Cross-check with frontmatter:**
|
||||||
- `research_topics: N` matches the actual count of `### Topic` headings
|
- `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)
|
- **1** — section is effectively missing or contradictory (maps to Fail)
|
||||||
|
|
||||||
Use both. The verbal rating drives the human-readable verdict. The numeric
|
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.
|
review as a quality gate and need per-dimension granularity.
|
||||||
|
|
||||||
## Output format
|
## Output format
|
||||||
|
|
@ -174,7 +174,7 @@ Produce **two artifacts in this order**:
|
||||||
|
|
||||||
1. A prose report (for humans and for `planning-orchestrator` Phase 1b).
|
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
|
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
|
The JSON block MUST be the last fenced block in your output so parsers can
|
||||||
find it by reading the last `json` code fence.
|
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}
|
- **Suggestion:** {how to fix it}
|
||||||
|
|
||||||
### Suggested additions
|
### 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.}
|
information that would strengthen the brief. List only if actionable.}
|
||||||
|
|
||||||
### Verdict
|
### Verdict
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
name: code-correctness-reviewer
|
name: code-correctness-reviewer
|
||||||
description: |
|
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,
|
delivered code across 7 dimensions: error handling, fragile assumptions,
|
||||||
cross-file regressions, test coverage gaps, placeholder code, security
|
cross-file regressions, test coverage gaps, placeholder code, security
|
||||||
surface, hidden dependencies. Cites file:line for every finding. Never
|
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:
|
You will receive a prompt containing:
|
||||||
- **Diff text** — unified diff of the changes under review.
|
- **Diff text** — unified diff of the changes under review.
|
||||||
- **Triage map** — `{file → deep-review|summary-only|skip}` from the
|
- **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
|
skipped files when the skip itself is wrong (then emit
|
||||||
`COVERAGE_SILENT_SKIP`). Files marked `summary-only` get a structural
|
`COVERAGE_SILENT_SKIP`). Files marked `summary-only` get a structural
|
||||||
pass — declared signatures, exports, top-level wiring — but no deep
|
pass — declared signatures, exports, top-level wiring — but no deep
|
||||||
|
|
|
||||||
|
|
@ -6,8 +6,8 @@ description: |
|
||||||
and what developers actually encounter when using a technology.
|
and what developers actually encounter when using a technology.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: ultraresearch-local needs real-world experience data on a database migration
|
Context: trekresearch needs real-world experience data on a database migration
|
||||||
user: "/ultraresearch-local What's the real-world experience with migrating from MongoDB to PostgreSQL?"
|
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."
|
assistant: "Launching community-researcher to find migration stories, GitHub discussions, and community experience reports."
|
||||||
<commentary>
|
<commentary>
|
||||||
Official docs won't cover migration regrets or production war stories. community-researcher
|
Official docs won't cover migration regrets or production war stories. community-researcher
|
||||||
|
|
@ -16,8 +16,8 @@ description: |
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: ultraresearch-local is building a technology comparison
|
Context: trekresearch is building a technology comparison
|
||||||
user: "/ultraresearch-local Research community sentiment around adopting SvelteKit vs Next.js"
|
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."
|
assistant: "I'll use community-researcher to find discussions, blog posts, and community reports on both frameworks."
|
||||||
<commentary>
|
<commentary>
|
||||||
Framework comparisons live in community discourse, not official docs. community-researcher
|
Framework comparisons live in community discourse, not official docs. community-researcher
|
||||||
|
|
|
||||||
|
|
@ -6,8 +6,8 @@ description: |
|
||||||
answer might be wrong.
|
answer might be wrong.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: ultraresearch-local has found evidence favoring a technology and needs the other side
|
Context: trekresearch 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"
|
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."
|
assistant: "Launching contrarian-researcher to find the strongest arguments against Kafka and what alternatives might serve better."
|
||||||
<commentary>
|
<commentary>
|
||||||
The research equivalent of plan-critic. When one option is emerging as the answer,
|
The research equivalent of plan-critic. When one option is emerging as the answer,
|
||||||
|
|
@ -16,8 +16,8 @@ description: |
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: ultraresearch-local is comparing options and needs the downsides of the leading candidate
|
Context: trekresearch is comparing options and needs the downsides of the leading candidate
|
||||||
user: "/ultraresearch-local Compare Redis vs Memcached — initial research favors Redis"
|
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."
|
assistant: "I'll use contrarian-researcher to find the strongest case against Redis and scenarios where Memcached wins."
|
||||||
<commentary>
|
<commentary>
|
||||||
Contrarian-researcher finds the downsides of the leading option — not to be negative,
|
Contrarian-researcher finds the downsides of the leading option — not to be negative,
|
||||||
|
|
|
||||||
|
|
@ -7,11 +7,11 @@ description: |
|
||||||
documentation patterns. Uses concrete examples from the codebase.
|
documentation patterns. Uses concrete examples from the codebase.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: Ultraplan exploration phase for a medium+ codebase
|
Context: Voyage exploration phase for a medium+ codebase
|
||||||
user: "/ultraplan-local Add authentication to the API"
|
user: "/trekplan Add authentication to the API"
|
||||||
assistant: "Launching convention-scanner to discover coding patterns."
|
assistant: "Launching convention-scanner to discover coding patterns."
|
||||||
<commentary>
|
<commentary>
|
||||||
Phase 5 of ultraplan triggers this agent for medium+ codebases (50+ files).
|
Phase 5 of trekplan triggers this agent for medium+ codebases (50+ files).
|
||||||
</commentary>
|
</commentary>
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -5,11 +5,11 @@ description: |
|
||||||
how modules connect and what side effects they produce.
|
how modules connect and what side effects they produce.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: Ultraplan needs to understand module relationships for a task
|
Context: Voyage needs to understand module relationships for a task
|
||||||
user: "/ultraplan-local Refactor the payment processing pipeline"
|
user: "/trekplan Refactor the payment processing pipeline"
|
||||||
assistant: "Launching dependency-tracer to map module connections and data flow."
|
assistant: "Launching dependency-tracer to map module connections and data flow."
|
||||||
<commentary>
|
<commentary>
|
||||||
Phase 5 of ultraplan triggers this agent to trace dependencies relevant to the task.
|
Phase 5 of trekplan triggers this agent to trace dependencies relevant to the task.
|
||||||
</commentary>
|
</commentary>
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -5,8 +5,8 @@ description: |
|
||||||
documentation, RFCs, vendor specifications, or Microsoft/Azure documentation.
|
documentation, RFCs, vendor specifications, or Microsoft/Azure documentation.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: ultraresearch-local needs to ground an OAuth2 implementation in official specs
|
Context: trekresearch needs to ground an OAuth2 implementation in official specs
|
||||||
user: "/ultraresearch-local Research OAuth2 PKCE flow for our SPA"
|
user: "/trekresearch Research OAuth2 PKCE flow for our SPA"
|
||||||
assistant: "Launching docs-researcher to find the official RFC and vendor documentation for OAuth2 PKCE."
|
assistant: "Launching docs-researcher to find the official RFC and vendor documentation for OAuth2 PKCE."
|
||||||
<commentary>
|
<commentary>
|
||||||
docs-researcher targets authoritative sources — RFCs, specs, official vendor docs —
|
docs-researcher targets authoritative sources — RFCs, specs, official vendor docs —
|
||||||
|
|
@ -15,8 +15,8 @@ description: |
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: ultraresearch-local encounters an Azure-specific technology
|
Context: trekresearch encounters an Azure-specific technology
|
||||||
user: "/ultraresearch-local How should we configure Azure Service Bus for our event pipeline?"
|
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."
|
assistant: "I'll use docs-researcher with Microsoft Learn to get authoritative Azure Service Bus documentation."
|
||||||
<commentary>
|
<commentary>
|
||||||
Microsoft/Azure technologies have dedicated MCP tools (microsoft_docs_search,
|
Microsoft/Azure technologies have dedicated MCP tools (microsoft_docs_search,
|
||||||
|
|
|
||||||
|
|
@ -7,8 +7,8 @@ description: |
|
||||||
that can confirm or challenge findings from other agents.
|
that can confirm or challenge findings from other agents.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: ultraresearch launches gemini-bridge for an independent second opinion on a technology choice
|
Context: trekresearch 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?"
|
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."
|
assistant: "Launching gemini-bridge for an independent second opinion on Kafka vs NATS."
|
||||||
<commentary>
|
<commentary>
|
||||||
Technology choice with significant architectural implications triggers gemini-bridge
|
Technology choice with significant architectural implications triggers gemini-bridge
|
||||||
|
|
|
||||||
|
|
@ -5,11 +5,11 @@ description: |
|
||||||
code ownership, hot files, and active branches relevant to the task.
|
code ownership, hot files, and active branches relevant to the task.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: Ultraplan exploration phase needs git context
|
Context: Voyage exploration phase needs git context
|
||||||
user: "/ultraplan-local Refactor the database layer"
|
user: "/trekplan Refactor the database layer"
|
||||||
assistant: "Launching git-historian to check recent changes and ownership of DB code."
|
assistant: "Launching git-historian to check recent changes and ownership of DB code."
|
||||||
<commentary>
|
<commentary>
|
||||||
Phase 2 of ultraplan triggers this agent for every codebase size.
|
Phase 2 of trekplan triggers this agent for every codebase size.
|
||||||
</commentary>
|
</commentary>
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -5,11 +5,11 @@ description: |
|
||||||
problems, never praises.
|
problems, never praises.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: Ultraplan adversarial review phase
|
Context: Voyage adversarial review phase
|
||||||
user: "/ultraplan-local Implement WebSocket real-time updates"
|
user: "/trekplan Implement WebSocket real-time updates"
|
||||||
assistant: "Launching plan-critic to stress-test the implementation plan."
|
assistant: "Launching plan-critic to stress-test the implementation plan."
|
||||||
<commentary>
|
<commentary>
|
||||||
Phase 9 of ultraplan triggers this agent to review the generated plan.
|
Phase 9 of trekplan triggers this agent to review the generated plan.
|
||||||
</commentary>
|
</commentary>
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
|
|
@ -168,7 +168,7 @@ cannot be decomposed into headless sessions).
|
||||||
|
|
||||||
### 10. Manifest quality (hard gate)
|
### 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
|
them to determine whether a step is actually done — not just whether the
|
||||||
Verify command returned 0. A plan without valid manifests cannot drive
|
Verify command returned 0. A plan without valid manifests cannot drive
|
||||||
deterministic execution.
|
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
|
**Backward compat:** For plans without `plan_version: 1.7` (legacy), emit
|
||||||
a single advisory note ("Plan is v1.6 legacy format — manifests will be
|
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.
|
dimension's scoring.
|
||||||
|
|
||||||
## Rating system
|
## Rating system
|
||||||
|
|
|
||||||
|
|
@ -2,12 +2,12 @@
|
||||||
name: planning-orchestrator
|
name: planning-orchestrator
|
||||||
description: |
|
description: |
|
||||||
Inline reference (v2.4.0) — documents the planning workflow that
|
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
|
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
|
to sub-agents, so an orchestrator launched with run_in_background: true
|
||||||
cannot spawn the exploration swarm (architecture-mapper, task-finder,
|
cannot spawn the exploration swarm (architecture-mapper, task-finder,
|
||||||
plan-critic, etc.) and would degrade to single-context reasoning. The
|
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.
|
main session.
|
||||||
model: opus
|
model: opus
|
||||||
color: cyan
|
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 5 = Command Phase 8 (Deep planning)
|
||||||
Orchestrator Phase 6 = Command Phase 9 (Adversarial review)
|
Orchestrator Phase 6 = Command Phase 9 (Adversarial review)
|
||||||
Orchestrator Phase 7 = Command Phase 10 (Completion)
|
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
|
instead of spawning this agent. Keep this file as the canonical
|
||||||
reference for what those phases do. -->
|
reference for what those phases do. -->
|
||||||
|
|
||||||
This document is the canonical workflow description for the ultraplan
|
This document is the canonical workflow description for the trekplan
|
||||||
pipeline as of v2.4.0. The `/ultraplan-local` command reads it as reference
|
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
|
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
|
no longer spawned as a background sub-agent — that mode silently lost the
|
||||||
Agent tool and degraded the exploration swarm to single-context reasoning.
|
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
|
## Input
|
||||||
|
|
||||||
You will receive a prompt containing:
|
You will receive a prompt containing:
|
||||||
- **Brief file path** — the task brief (produced by `/ultrabrief-local`)
|
- **Brief file path** — the task brief (produced by `/trekbrief`)
|
||||||
- **Project dir** (optional) — path to an ultrabrief project folder when the user
|
- **Project dir** (optional) — path to an trekbrief project folder when the user
|
||||||
invoked `/ultraplan-local --project`. If set, the plan destination is
|
invoked `/trekplan --project`. If set, the plan destination is
|
||||||
`{project_dir}/plan.md` and any `{project_dir}/research/*.md` files are
|
`{project_dir}/plan.md` and any `{project_dir}/research/*.md` files are
|
||||||
pre-existing research briefs to read.
|
pre-existing research briefs to read.
|
||||||
- **Task description** — one-line summary (matches the brief's frontmatter `task`)
|
- **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
|
- **Estimated Scope** — file counts and complexity
|
||||||
|
|
||||||
**Plan-version header:** Include `plan_version: 1.7` in the metadata line below
|
**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
|
verification manifests and enables strict audit mode. Plans without this
|
||||||
marker are treated as legacy v1.6 with synthesized minimal manifests.
|
marker are treated as legacy v1.6 with synthesized minimal manifests.
|
||||||
|
|
||||||
### Mandatory step format — copy this exactly
|
### Mandatory step format — copy this exactly
|
||||||
|
|
||||||
The Implementation Plan section MUST contain numbered steps using the EXACT
|
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
|
strict regex matching. Any deviation breaks parsing and forces the user to
|
||||||
re-run planning.
|
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,
|
Every implementation step MUST include a `Manifest:` block as its last field,
|
||||||
after Checkpoint. The manifest is the objective completion predicate — the
|
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
|
Verify command passes. A step cannot be marked passed if its manifest does
|
||||||
not verify.
|
not verify.
|
||||||
|
|
||||||
|
|
@ -427,7 +427,7 @@ After both complete:
|
||||||
- Address all blockers and major issues by revising the plan
|
- Address all blockers and major issues by revising the plan
|
||||||
- **Manifest quality is a hard gate:** any manifest-related `major` finding
|
- **Manifest quality is a hard gate:** any manifest-related `major` finding
|
||||||
must be fixed before the plan can be handed off. This enforces the
|
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
|
machine-checkable — a plan without verifiable manifests cannot drive
|
||||||
deterministic execution.
|
deterministic execution.
|
||||||
- Add a "Revisions" note at the bottom documenting changes
|
- Add a "Revisions" note at the bottom documenting changes
|
||||||
|
|
@ -437,7 +437,7 @@ After both complete:
|
||||||
When done, your output message should contain:
|
When done, your output message should contain:
|
||||||
|
|
||||||
```
|
```
|
||||||
## Ultraplan Complete (Background)
|
## Voyage Complete (Background)
|
||||||
|
|
||||||
**Task:** {task}
|
**Task:** {task}
|
||||||
**Plan:** {plan path}
|
**Plan:** {plan path}
|
||||||
|
|
|
||||||
|
|
@ -2,11 +2,11 @@
|
||||||
name: research-orchestrator
|
name: research-orchestrator
|
||||||
description: |
|
description: |
|
||||||
Inline reference (v2.4.0) — documents the research workflow that
|
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
|
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
|
to sub-agents, so an orchestrator launched with run_in_background: true
|
||||||
cannot spawn the research swarm and would degrade to single-context
|
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.
|
below directly in the main session.
|
||||||
model: opus
|
model: opus
|
||||||
color: cyan
|
color: cyan
|
||||||
|
|
@ -20,12 +20,12 @@ tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash"]
|
||||||
Orchestrator Phase 4 = Command Phase 7 (Triangulation)
|
Orchestrator Phase 4 = Command Phase 7 (Triangulation)
|
||||||
Orchestrator Phase 5 = Command Phase 8 (Synthesis + write brief)
|
Orchestrator Phase 5 = Command Phase 8 (Synthesis + write brief)
|
||||||
Orchestrator Phase 6 = Command Phase 9 (Completion)
|
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
|
context instead of spawning this agent. Keep this file as the canonical
|
||||||
reference for what those phases do. -->
|
reference for what those phases do. -->
|
||||||
|
|
||||||
This document is the canonical workflow description for the ultraresearch
|
This document is the canonical workflow description for the trekresearch
|
||||||
pipeline as of v2.4.0. The `/ultraresearch-local` command reads it as
|
pipeline as of v2.4.0. The `/trekresearch` command reads it as
|
||||||
reference and executes the phases below **inline in the main command
|
reference and executes the phases below **inline in the main command
|
||||||
context**. It is no longer spawned as a background sub-agent — that mode
|
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
|
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
|
### 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:
|
For each dimension of the research question:
|
||||||
|
|
||||||
|
|
@ -208,7 +208,7 @@ When done, your output message should contain:
|
||||||
|
|
||||||
You can:
|
You can:
|
||||||
- Read the full brief at {brief path}
|
- Read the full brief at {brief path}
|
||||||
- Feed into planning: /ultraplan-local --research {brief path} <task>
|
- Feed into planning: /trekplan --research {brief path} <task>
|
||||||
- Ask follow-up questions
|
- Ask follow-up questions
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -5,11 +5,11 @@ description: |
|
||||||
APIs, or libraries where official documentation and known issues should be checked.
|
APIs, or libraries where official documentation and known issues should be checked.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: Ultraplan detects external technology in the task
|
Context: Voyage detects external technology in the task
|
||||||
user: "/ultraplan-local Integrate Stripe payment processing"
|
user: "/trekplan Integrate Stripe payment processing"
|
||||||
assistant: "Launching research-scout to find Stripe documentation and best practices."
|
assistant: "Launching research-scout to find Stripe documentation and best practices."
|
||||||
<commentary>
|
<commentary>
|
||||||
Phase 5 of ultraplan conditionally triggers this agent when external tech is detected.
|
Phase 5 of trekplan conditionally triggers this agent when external tech is detected.
|
||||||
</commentary>
|
</commentary>
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
---
|
---
|
||||||
name: review-coordinator
|
name: review-coordinator
|
||||||
description: |
|
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
|
reviewers (brief-conformance-reviewer, code-correctness-reviewer) and
|
||||||
applies BOUNDED operations: deduplication, severity ranking, HubSpot
|
applies BOUNDED operations: deduplication, severity ranking, HubSpot
|
||||||
Judge filters, Cloudflare reasonableness filter, verdict computation.
|
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`
|
`brief-conformance-reviewer` and `code-correctness-reviewer` (in `quick`
|
||||||
mode, only the latter).
|
mode, only the latter).
|
||||||
- **Triage map** — `{file → deep-review|summary-only|skip, reason}` from
|
- **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
|
- **Brief metadata** — `task`, `slug`, `project_dir`, `brief_path` from
|
||||||
the brief frontmatter.
|
the brief frontmatter.
|
||||||
- **Scope SHA range** — `scope_sha_start`, `scope_sha_end`,
|
- **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
|
## Output: review.md content
|
||||||
|
|
||||||
Produce the full review.md content as your output. The
|
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)
|
### 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
|
8. `## Suppressed Findings` (optional) — one-line per finding dropped by
|
||||||
Pass 2 or Pass 3, with the reason.
|
Pass 2 or Pass 3, with the reason.
|
||||||
9. `## Remediation Summary` — bullet count per severity + 1 sentence on
|
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
|
Each Findings subsection uses the `### {finding-id-40-char-hex}` heading
|
||||||
followed by these fields:
|
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:`
|
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
|
`--brief review.md`) reads the JSON for full content and the frontmatter
|
||||||
for the ID list.
|
for the ID list.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -2,13 +2,13 @@
|
||||||
name: review-orchestrator
|
name: review-orchestrator
|
||||||
description: |
|
description: |
|
||||||
Inline reference (v3.2.0) — documents the review workflow that
|
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
|
as a sub-agent. The Claude Code harness does not expose the Agent tool
|
||||||
to sub-agents, so a background orchestrator launched with
|
to sub-agents, so a background orchestrator launched with
|
||||||
run_in_background: true cannot spawn the reviewer swarm
|
run_in_background: true cannot spawn the reviewer swarm
|
||||||
(brief-conformance-reviewer, code-correctness-reviewer, review-coordinator)
|
(brief-conformance-reviewer, code-correctness-reviewer, review-coordinator)
|
||||||
and would degrade silently to single-context reasoning. The
|
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.
|
the main session.
|
||||||
model: opus
|
model: opus
|
||||||
color: red
|
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 6 = Command Phase 6 (Coordinator dedup + verdict)
|
||||||
Orchestrator Phase 7 = Command Phase 7 (Write review.md)
|
Orchestrator Phase 7 = Command Phase 7 (Write review.md)
|
||||||
Orchestrator Phase 8 = Command Phase 8 (Validate + stats)
|
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
|
context instead of spawning this agent. Keep this file as the canonical
|
||||||
reference for what those phases do. -->
|
reference for what those phases do. -->
|
||||||
|
|
||||||
This document is the canonical workflow description for the ultrareview
|
This document is the canonical workflow description for the trekreview
|
||||||
pipeline as of v3.2.0. The `/ultrareview-local` command reads it as
|
pipeline as of v3.2.0. The `/trekreview` command reads it as
|
||||||
reference and executes the phases below **inline in the main command
|
reference and executes the phases below **inline in the main command
|
||||||
context**. It is not spawned as a background sub-agent — that mode would
|
context**. It is not spawned as a background sub-agent — that mode would
|
||||||
silently lose the Agent tool and degrade the reviewer swarm to
|
silently lose the Agent tool and degrade the reviewer swarm to
|
||||||
|
|
@ -50,7 +50,7 @@ explicitly forbidden in v1.0 (Judge Agent pattern).
|
||||||
## Input
|
## Input
|
||||||
|
|
||||||
You will receive a prompt containing:
|
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
|
optional `progress.json` live here; the review will be written to
|
||||||
`{project_dir}/review.md`).
|
`{project_dir}/review.md`).
|
||||||
- **Brief path** — `{project_dir}/brief.md`. Read it; the brief is the
|
- **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:
|
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
|
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
|
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
|
### 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
|
a runnable sub-agent. Background mode silently degrades — the harness
|
||||||
does not expose the Agent tool to sub-agents, so the reviewer swarm
|
does not expose the Agent tool to sub-agents, so the reviewer swarm
|
||||||
collapses to single-context reasoning. Always run review agents from
|
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
|
- **Reviewers run independently.** No cross-feeding of findings. The
|
||||||
coordinator is the only place where reviewer outputs are combined.
|
coordinator is the only place where reviewer outputs are combined.
|
||||||
- **Coordinator scope is bounded.** Dedup, severity ranking, reasonableness
|
- **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
|
the Coverage section, even if its treatment is `skip`. Hidden truncation
|
||||||
is COVERAGE_SILENT_SKIP (MAJOR).
|
is COVERAGE_SILENT_SKIP (MAJOR).
|
||||||
- **Cost:** Use Sonnet for all sub-agents. The orchestrator (the
|
- **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
|
- **Privacy:** Never log secrets, tokens, or credentials. Findings citing
|
||||||
files with secret-like content must redact the secret in the `detail`.
|
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
|
- **Honesty:** If the diff is trivially small or all-skip, say so. Do
|
||||||
|
|
|
||||||
|
|
@ -5,11 +5,11 @@ description: |
|
||||||
technical debt that could affect an implementation task.
|
technical debt that could affect an implementation task.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: Ultraplan exploration phase identifies potential risks
|
Context: Voyage exploration phase identifies potential risks
|
||||||
user: "/ultraplan-local Migrate database from PostgreSQL to MongoDB"
|
user: "/trekplan Migrate database from PostgreSQL to MongoDB"
|
||||||
assistant: "Launching risk-assessor to identify failure modes and edge cases for this migration."
|
assistant: "Launching risk-assessor to identify failure modes and edge cases for this migration."
|
||||||
<commentary>
|
<commentary>
|
||||||
Phase 5 of ultraplan triggers this agent to find risks before planning begins.
|
Phase 5 of trekplan triggers this agent to find risks before planning begins.
|
||||||
</commentary>
|
</commentary>
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -5,11 +5,11 @@ description: |
|
||||||
requirements — catches scope creep and scope gaps.
|
requirements — catches scope creep and scope gaps.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: Ultraplan adversarial review phase checks scope alignment
|
Context: Voyage adversarial review phase checks scope alignment
|
||||||
user: "/ultraplan-local Add caching to the API layer"
|
user: "/trekplan Add caching to the API layer"
|
||||||
assistant: "Launching scope-guardian to verify plan matches requirements."
|
assistant: "Launching scope-guardian to verify plan matches requirements."
|
||||||
<commentary>
|
<commentary>
|
||||||
Phase 9 of ultraplan triggers this agent alongside plan-critic.
|
Phase 9 of trekplan triggers this agent alongside plan-critic.
|
||||||
</commentary>
|
</commentary>
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -5,8 +5,8 @@ description: |
|
||||||
dependency, or library — CVEs, audit history, supply chain risks, and OWASP relevance.
|
dependency, or library — CVEs, audit history, supply chain risks, and OWASP relevance.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: ultraresearch-local is evaluating whether a dependency is safe to adopt
|
Context: trekresearch is evaluating whether a dependency is safe to adopt
|
||||||
user: "/ultraresearch-local Research whether we should trust the `node-fetch` library"
|
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."
|
assistant: "Launching security-researcher to check CVE history, supply chain risk, and audit reports for node-fetch."
|
||||||
<commentary>
|
<commentary>
|
||||||
Before adopting a dependency, security-researcher checks the attack surface: known
|
Before adopting a dependency, security-researcher checks the attack surface: known
|
||||||
|
|
@ -15,8 +15,8 @@ description: |
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: ultraresearch-local is assessing the security posture of a technology choice
|
Context: trekresearch is assessing the security posture of a technology choice
|
||||||
user: "/ultraresearch-local Evaluate the security implications of using JWT for session management"
|
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."
|
assistant: "I'll use security-researcher to check known JWT vulnerabilities, OWASP guidance, and community security reports."
|
||||||
<commentary>
|
<commentary>
|
||||||
Technology choices have security tradeoffs. security-researcher maps the threat surface
|
Technology choices have security tradeoffs. security-researcher maps the threat surface
|
||||||
|
|
|
||||||
|
|
@ -1,13 +1,13 @@
|
||||||
---
|
---
|
||||||
name: session-decomposer
|
name: session-decomposer
|
||||||
description: |
|
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,
|
Reads a plan file, analyzes step dependencies, groups steps into sessions,
|
||||||
identifies parallelism, and generates session specs + dependency graph + launch script.
|
identifies parallelism, and generates session specs + dependency graph + launch script.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: User wants to run a plan across multiple headless sessions
|
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."
|
assistant: "Launching session-decomposer to split the plan into headless sessions."
|
||||||
<commentary>
|
<commentary>
|
||||||
The --decompose flag triggers this agent to analyze and split the plan.
|
The --decompose flag triggers this agent to analyze and split the plan.
|
||||||
|
|
@ -27,15 +27,15 @@ color: green
|
||||||
tools: ["Read", "Glob", "Grep", "Write"]
|
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.
|
plan and split it into self-contained sessions optimized for headless execution.
|
||||||
|
|
||||||
## Input
|
## Input
|
||||||
|
|
||||||
You will receive:
|
You will receive:
|
||||||
- **Plan file path** — the ultraplan to decompose
|
- **Plan file path** — the trekplan to decompose
|
||||||
- **Plugin root** — for template access
|
- **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
|
Read the plan file first. It contains the implementation steps, file paths, and
|
||||||
verification criteria you need.
|
verification criteria you need.
|
||||||
|
|
|
||||||
|
|
@ -6,11 +6,11 @@ description: |
|
||||||
structured code discovery.
|
structured code discovery.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: Ultraplan exploration phase needs task-relevant code
|
Context: Voyage exploration phase needs task-relevant code
|
||||||
user: "/ultraplan-local Add authentication to the API"
|
user: "/trekplan Add authentication to the API"
|
||||||
assistant: "Launching task-finder to locate auth-related code, endpoints, and models."
|
assistant: "Launching task-finder to locate auth-related code, endpoints, and models."
|
||||||
<commentary>
|
<commentary>
|
||||||
Phase 2 of ultraplan triggers this agent for every codebase size.
|
Phase 2 of trekplan triggers this agent for every codebase size.
|
||||||
</commentary>
|
</commentary>
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -5,11 +5,11 @@ description: |
|
||||||
discovers existing patterns, maps coverage gaps, and recommends what tests to write.
|
discovers existing patterns, maps coverage gaps, and recommends what tests to write.
|
||||||
|
|
||||||
<example>
|
<example>
|
||||||
Context: Ultraplan exploration phase for medium+ codebase
|
Context: Voyage exploration phase for medium+ codebase
|
||||||
user: "/ultraplan-local Add rate limiting to the API"
|
user: "/trekplan Add rate limiting to the API"
|
||||||
assistant: "Launching test-strategist to analyze existing test patterns and design test coverage."
|
assistant: "Launching test-strategist to analyze existing test patterns and design test coverage."
|
||||||
<commentary>
|
<commentary>
|
||||||
Phase 5 of ultraplan triggers this agent for medium and large codebases.
|
Phase 5 of trekplan triggers this agent for medium and large codebases.
|
||||||
</commentary>
|
</commentary>
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
---
|
---
|
||||||
name: trekbrief
|
name: trekbrief
|
||||||
description: Interactive interview that produces a task brief with explicit research plan. Feeds /ultraresearch-local and /ultraplan-local. Optionally orchestrates the full pipeline end-to-end.
|
description: Interactive interview that produces a task brief with explicit research plan. Feeds /trekresearch and /trekplan. Optionally orchestrates the full pipeline end-to-end.
|
||||||
argument-hint: "[--quick] <task description>"
|
argument-hint: "[--quick] <task description>"
|
||||||
model: opus
|
model: opus
|
||||||
allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion
|
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
|
Interactive requirements-gathering command. Produces a **task brief** — a
|
||||||
structured markdown file that declares intent, goal, constraints, and an
|
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:
|
Pipeline position:
|
||||||
|
|
||||||
```
|
```
|
||||||
/ultrabrief-local → brief.md (this command)
|
/trekbrief → brief.md (this command)
|
||||||
/ultraresearch-local --project <dir> → research/*.md
|
/trekresearch --project <dir> → research/*.md
|
||||||
/ultraplan-local --project <dir> → plan.md
|
/trekplan --project <dir> → plan.md
|
||||||
/ultraexecute-local --project <dir> → execution
|
/trekexecute --project <dir> → execution
|
||||||
```
|
```
|
||||||
|
|
||||||
The brief is the contract between the user's intent and `/ultraplan-local`.
|
The brief is the contract between the user's intent and `/trekplan`.
|
||||||
Every decision the plan makes must trace back to content in the brief.
|
Every decision the plan makes must trace back to content in the brief.
|
||||||
|
|
||||||
**This command is always interactive.** There is no background mode — the
|
**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:
|
If no task description is provided, output usage and stop:
|
||||||
|
|
||||||
```
|
```
|
||||||
Usage: /ultrabrief-local <task description>
|
Usage: /trekbrief <task description>
|
||||||
/ultrabrief-local --quick <task description>
|
/trekbrief --quick <task description>
|
||||||
|
|
||||||
Modes:
|
Modes:
|
||||||
default Dynamic interview until quality gates pass — brief with research plan
|
default Dynamic interview until quality gates pass — brief with research plan
|
||||||
--quick Compact start; still escalates on weak sections — brief with research plan
|
--quick Compact start; still escalates on weak sections — brief with research plan
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
/ultrabrief-local Add user authentication with JWT tokens
|
/trekbrief Add user authentication with JWT tokens
|
||||||
/ultrabrief-local --quick Add rate limiting to the API
|
/trekbrief --quick Add rate limiting to the API
|
||||||
/ultrabrief-local Migrate from Express to Fastify
|
/trekbrief Migrate from Express to Fastify
|
||||||
```
|
```
|
||||||
|
|
||||||
Report:
|
Report:
|
||||||
|
|
@ -292,7 +292,7 @@ Proceeding to draft and review.
|
||||||
|
|
||||||
Phase 4 runs a **draft → brief-reviewer → revise** loop. The draft is
|
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
|
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.
|
has already survived a critical review.
|
||||||
|
|
||||||
Read the brief template first:
|
Read the brief template first:
|
||||||
|
|
@ -502,8 +502,8 @@ Ask the user via `AskUserQuestion`:
|
||||||
|
|
||||||
| Option | Description |
|
| Option | Description |
|
||||||
|--------|-------------|
|
|--------|-------------|
|
||||||
| **Manual (default)** | Print the commands. You run `/ultraresearch-local` and `/ultraplan-local` yourself, choosing depth per topic. |
|
| **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 `/ultraplan-local` when research completes. This session blocks until the plan is ready. |
|
| **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)
|
### Manual path (default)
|
||||||
|
|
||||||
|
|
@ -519,13 +519,13 @@ Research topics: {N}
|
||||||
Next steps (run in order or parallel):
|
Next steps (run in order or parallel):
|
||||||
|
|
||||||
{For each topic:}
|
{For each topic:}
|
||||||
/ultraresearch-local --project {PROJECT_DIR} --external "{topic question}"
|
/trekresearch --project {PROJECT_DIR} --external "{topic question}"
|
||||||
|
|
||||||
Then:
|
Then:
|
||||||
/ultraplan-local --project {PROJECT_DIR}
|
/trekplan --project {PROJECT_DIR}
|
||||||
|
|
||||||
Then:
|
Then:
|
||||||
/ultraexecute-local --project {PROJECT_DIR}
|
/trekexecute --project {PROJECT_DIR}
|
||||||
```
|
```
|
||||||
|
|
||||||
Stop. Do not continue to Phase 6.
|
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.
|
proceed to Phase 6.
|
||||||
|
|
||||||
If `gates_mode == false` (default in auto): proceed directly 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).
|
Phase 8).
|
||||||
|
|
||||||
Proceed to Phase 6.
|
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.
|
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:
|
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
|
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:
|
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
|
The planning pipeline runs all phases (exploration, synthesis, review) in
|
||||||
|
|
@ -629,7 +629,7 @@ before continuing.
|
||||||
When the planning-orchestrator finishes, present:
|
When the planning-orchestrator finishes, present:
|
||||||
|
|
||||||
```
|
```
|
||||||
## Ultrabrief + Ultraresearch + Ultraplan Complete (auto mode)
|
## Ultrabrief + Ultraresearch + Voyage Complete (auto mode)
|
||||||
|
|
||||||
**Project:** {PROJECT_DIR}/
|
**Project:** {PROJECT_DIR}/
|
||||||
**Brief:** {PROJECT_DIR}/brief.md
|
**Brief:** {PROJECT_DIR}/brief.md
|
||||||
|
|
@ -645,11 +645,11 @@ When the planning-orchestrator finishes, present:
|
||||||
| Plan | Complete ({steps} steps, critic: {verdict}) |
|
| Plan | Complete ({steps} steps, critic: {verdict}) |
|
||||||
|
|
||||||
Next:
|
Next:
|
||||||
/ultraexecute-local --project {PROJECT_DIR}
|
/trekexecute --project {PROJECT_DIR}
|
||||||
|
|
||||||
Or:
|
Or:
|
||||||
/ultraexecute-local --dry-run --project {PROJECT_DIR} # preview
|
/trekexecute --dry-run --project {PROJECT_DIR} # preview
|
||||||
/ultraexecute-local --validate --project {PROJECT_DIR} # schema check
|
/trekexecute --validate --project {PROJECT_DIR} # schema check
|
||||||
```
|
```
|
||||||
|
|
||||||
## Phase 7 — Stats tracking
|
## 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
|
the user until motivation is clear — the plan and every review agent
|
||||||
will trace decisions back to this.
|
will trace decisions back to this.
|
||||||
4. **Research topics must be answerable.** Each topic's research question
|
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.
|
too vague, split or reformulate before writing.
|
||||||
5. **Never invent research topics the user did not agree to.** Topics
|
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.
|
come from the interview. If the user says "I know this", respect it.
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
---
|
---
|
||||||
name: trekcontinue
|
name: trekcontinue
|
||||||
description: Resume the next session in a multi-session ultraplan project. Reads .session-state.local.json and immediately begins the next session.
|
description: Resume the next session in a multi-session trekplan project. Reads .session-state.local.json and immediately begins the next session.
|
||||||
argument-hint: "[<project-dir> | --help]"
|
argument-hint: "[<project-dir> | --help]"
|
||||||
model: opus
|
model: opus
|
||||||
---
|
---
|
||||||
|
|
@ -8,22 +8,22 @@ model: opus
|
||||||
# Ultracontinue Local v1.0
|
# Ultracontinue Local v1.0
|
||||||
|
|
||||||
Zero-friction multi-session resumption. In a fresh Claude Code session, type
|
Zero-friction multi-session resumption. In a fresh Claude Code session, type
|
||||||
`/ultracontinue` — the command reads the per-project state file
|
`/trekcontinue` — the command reads the per-project state file
|
||||||
(`.claude/projects/<project>/.session-state.local.json`), shows a 3-line summary,
|
(`.claude/projects/<project>/.session-state.local.json`), shows a 3-line summary,
|
||||||
and immediately begins executing the next session.
|
and immediately begins executing the next session.
|
||||||
|
|
||||||
The state file is the contract. Any session-end mechanism may write it
|
The state file is the contract. Any session-end mechanism may write it
|
||||||
(`/ultraexecute-local` Phase 8 / Phase 2.55 / Phase 4, the
|
(`/trekexecute` Phase 8 / Phase 2.55 / Phase 4, the
|
||||||
`/ultraplan-end-session-local` helper, or — in the future — `graceful-handoff`).
|
`/trekendsession` helper, or — in the future — `graceful-handoff`).
|
||||||
This command only reads.
|
This command only reads.
|
||||||
|
|
||||||
Pipeline position:
|
Pipeline position:
|
||||||
|
|
||||||
```
|
```
|
||||||
/ultraplan-local → plan.md
|
/trekplan → plan.md
|
||||||
/ultraexecute-local → progress.json + .session-state.local.json
|
/trekexecute → progress.json + .session-state.local.json
|
||||||
... session boundary, fresh chat ...
|
... 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.
|
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.
|
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:
|
Usage:
|
||||||
/ultracontinue # auto-discover state file under cwd
|
/trekcontinue # auto-discover state file under cwd
|
||||||
/ultracontinue <project-dir> # explicit project directory
|
/trekcontinue <project-dir> # explicit project directory
|
||||||
/ultracontinue --cleanup <project-dir> # dry-run: list stale files
|
/trekcontinue --cleanup <project-dir> # dry-run: list stale files
|
||||||
/ultracontinue --cleanup --confirm <project-dir> # actually delete (requires status: completed)
|
/trekcontinue --cleanup --confirm <project-dir> # actually delete (requires status: completed)
|
||||||
/ultracontinue --help # this message
|
/trekcontinue --help # this message
|
||||||
|
|
||||||
Reads .claude/projects/<project>/.session-state.local.json (per-project,
|
Reads .claude/projects/<project>/.session-state.local.json (per-project,
|
||||||
gitignored). On a valid resumable state, prints a 3-line summary and begins
|
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)
|
(unknown top-level keys are tolerated — forward-compat for graceful-handoff v2.2)
|
||||||
|
|
||||||
Typical flow:
|
Typical flow:
|
||||||
/ultrabrief-local # produces brief.md
|
/trekbrief # produces brief.md
|
||||||
/ultraplan-local --project ... # produces plan.md
|
/trekplan --project ... # produces plan.md
|
||||||
/ultraexecute-local --project .. # writes session-state on session-end
|
/trekexecute --project .. # writes session-state on session-end
|
||||||
... (fresh Claude chat) ...
|
... (fresh Claude chat) ...
|
||||||
/ultracontinue # reads session-state, runs next session
|
/trekcontinue # reads session-state, runs next session
|
||||||
```
|
```
|
||||||
|
|
||||||
## Phase 0.5 — Cleanup mode dispatch
|
## 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:
|
print this usage block to stderr and exit non-zero:
|
||||||
|
|
||||||
```
|
```
|
||||||
Error: /ultracontinue-local --cleanup requires <project-dir>.
|
Error: /trekcontinue --cleanup requires <project-dir>.
|
||||||
Usage:
|
Usage:
|
||||||
/ultracontinue-local --cleanup <project-dir> # dry-run: list stale files
|
/trekcontinue --cleanup <project-dir> # dry-run: list stale files
|
||||||
/ultracontinue-local --cleanup --confirm <project-dir> # actually delete (status: completed)
|
/trekcontinue --cleanup --confirm <project-dir> # actually delete (status: completed)
|
||||||
```
|
```
|
||||||
|
|
||||||
**Compute mode from parsed flags:**
|
**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.
|
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.
|
**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`.
|
again without `--cleanup`.
|
||||||
|
|
||||||
## Phase 1 — Resolve project directory
|
## Phase 1 — Resolve project directory
|
||||||
|
|
@ -134,7 +134,7 @@ Print the following diagnostic to stderr and exit non-zero. Do NOT proceed.
|
||||||
```
|
```
|
||||||
Error: expected <project-dir>, got a markdown file path: <positional[0]>
|
Error: expected <project-dir>, got a markdown file path: <positional[0]>
|
||||||
Did you mean to paste the file path as a project directory?
|
Did you mean to paste the file path as a project directory?
|
||||||
Usage: /ultracontinue-local <project-dir>
|
Usage: /trekcontinue <project-dir>
|
||||||
```
|
```
|
||||||
|
|
||||||
### Step 1.b — Auto-discover candidates
|
### 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:
|
- **0 candidates and no explicit arg:** print SC-2 cold-start message and exit:
|
||||||
```
|
```
|
||||||
No active multi-session project here.
|
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 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
|
- **>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
|
newest resumable state wins automatically and the command continues to Phase 2
|
||||||
with that path. (Operators who want a different candidate re-invoke as
|
with that path. (Operators who want a different candidate re-invoke as
|
||||||
`/ultracontinue <project-dir>`.)
|
`/trekcontinue <project-dir>`.)
|
||||||
|
|
||||||
## Phase 1.5 — Frontmatter consistency check
|
## 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:`,
|
write `NEXT-SESSION-PROMPT.local.md` with YAML frontmatter (`produced_by:`,
|
||||||
`produced_at:`). Multiple producers may have written candidates in different
|
`produced_at:`). Multiple producers may have written candidates in different
|
||||||
locations; this phase refuses ambiguity before validating the state file.
|
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),
|
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.
|
list both candidate paths, and exit non-zero. Do NOT proceed to Phase 2.
|
||||||
Resolve the conflict by deleting the stale candidate (run
|
Resolve the conflict by deleting the stale candidate (run
|
||||||
`/ultracontinue-local --cleanup --confirm <project-dir>` after the
|
`/trekcontinue --cleanup --confirm <project-dir>` after the
|
||||||
current session closes, or remove by hand).
|
current session closes, or remove by hand).
|
||||||
|
|
||||||
- **If `valid: true` with a `NEXT_SESSION_PROMPT_WALL_CLOCK_DRIFT` warning**
|
- **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
|
session is supposed to execute — typically the same `brief.md` for
|
||||||
single-brief multi-session plans, or a session-specific spec for parallel
|
single-brief multi-session plans, or a session-specific spec for parallel
|
||||||
session decomposition). Understand the task and begin executing per the
|
session decomposition). Understand the task and begin executing per the
|
||||||
standard ultraplan-local pipeline. The user did not type a separate "start"
|
standard trekplan pipeline. The user did not type a separate "start"
|
||||||
command — `/ultracontinue` is the start.
|
command — `/trekcontinue` is the start.
|
||||||
|
|
||||||
If the brief file does not exist (validator emits a warning but does not
|
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
|
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
|
## 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
|
does not advance state — the writer (Phase 8 / hook / helper) advances state
|
||||||
only when a session completes.
|
only when a session completes.
|
||||||
- **Zero secrets in the state file.** Status, paths, labels — never API keys,
|
- **Zero secrets in the state file.** Status, paths, labels — never API keys,
|
||||||
|
|
|
||||||
|
|
@ -5,25 +5,25 @@ argument-hint: "<next-brief-path> <next-label> | --help"
|
||||||
model: sonnet
|
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
|
Tiny helper for **informal** multi-session flows (no formal plan with
|
||||||
Execution Strategy). Writes a `.session-state.local.json` pointing at the
|
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`),
|
For formal flows (a plan produced by `/trekplan --project`),
|
||||||
`/ultraexecute-local` Phase 8 already writes the state file — this helper
|
`/trekexecute` Phase 8 already writes the state file — this helper
|
||||||
is unnecessary there. Use this command for ad-hoc release runs, manual
|
is unnecessary there. Use this command for ad-hoc release runs, manual
|
||||||
multi-session handovers, or any flow that does not run through
|
multi-session handovers, or any flow that does not run through
|
||||||
`/ultraexecute-local`.
|
`/trekexecute`.
|
||||||
|
|
||||||
Pipeline position:
|
Pipeline position:
|
||||||
|
|
||||||
```
|
```
|
||||||
... session N work ...
|
... session N work ...
|
||||||
/ultraplan-end-session-local <brief> "<next-label>" → writes state
|
/trekendsession <brief> "<next-label>" → writes state
|
||||||
... session boundary, fresh chat ...
|
... 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.
|
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.
|
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:
|
Usage:
|
||||||
/ultraplan-end-session-local <next-brief-path> <next-label>
|
/trekendsession <next-brief-path> <next-label>
|
||||||
/ultraplan-end-session-local --help
|
/trekendsession --help
|
||||||
|
|
||||||
Both arguments are REQUIRED. No interactive prompt — headless-safe.
|
Both arguments are REQUIRED. No interactive prompt — headless-safe.
|
||||||
|
|
||||||
|
|
@ -51,10 +51,10 @@ Writes <project-dir>/.session-state.local.json with:
|
||||||
updated_at <now, ISO-8601>
|
updated_at <now, ISO-8601>
|
||||||
|
|
||||||
Then validates via lib/validators/session-state-validator.mjs and prints
|
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:
|
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
|
## Phase 1 — Resolve project directory
|
||||||
|
|
@ -82,12 +82,12 @@ If either is missing or empty:
|
||||||
|
|
||||||
```
|
```
|
||||||
Error: missing required args.
|
Error: missing required args.
|
||||||
Usage: /ultraplan-end-session-local <next-brief-path> '<next-label>'
|
Usage: /trekendsession <next-brief-path> '<next-label>'
|
||||||
```
|
```
|
||||||
|
|
||||||
Print to stderr and exit 1. **No interactive prompt** — this keeps the helper
|
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
|
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
|
## 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');
|
const stateFile = path.join(dir, '.session-state.local.json');
|
||||||
atomicWriteJson(stateFile, stateObj);
|
atomicWriteJson(stateFile, stateObj);
|
||||||
const promptFile = path.join(dir, 'NEXT-SESSION-PROMPT.local.md');
|
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);
|
writeFileSync(promptFile, promptBody);
|
||||||
console.log(stateFile);
|
console.log(stateFile);
|
||||||
console.log(promptFile);
|
console.log(promptFile);
|
||||||
|
|
@ -144,7 +144,7 @@ Validate the freshly-written state file:
|
||||||
!`node lib/validators/session-state-validator.mjs --json <project-dir>/.session-state.local.json`
|
!`node lib/validators/session-state-validator.mjs --json <project-dir>/.session-state.local.json`
|
||||||
```
|
```
|
||||||
|
|
||||||
If `valid: true`, print the success block matching `/ultracontinue` Phase 3
|
If `valid: true`, print the success block matching `/trekcontinue` Phase 3
|
||||||
narration (SC-8 cross-project consistency — same template both sides):
|
narration (SC-8 cross-project consistency — same template both sides):
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
@ -154,7 +154,7 @@ Project: <project-dir>
|
||||||
Next session: <next-label>
|
Next session: <next-label>
|
||||||
Brief: <next-brief-path>
|
Brief: <next-brief-path>
|
||||||
|
|
||||||
In a fresh Claude session, run /ultracontinue to resume.
|
In a fresh Claude session, run /trekcontinue to resume.
|
||||||
```
|
```
|
||||||
|
|
||||||
If `valid: false`, print the structured `errors[]` and exit 1. Investigate
|
If `valid: false`, print the structured `errors[]` and exit 1. Investigate
|
||||||
|
|
|
||||||
|
|
@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
|
||||||
|
|
||||||
# Ultraexecute Local
|
# 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
|
an Execution Strategy (multi-session), and either executes directly or
|
||||||
orchestrates parallel headless sessions — all to realize one plan.
|
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:
|
- If `{dir}` does not exist or `{dir}/plan.md` is missing:
|
||||||
```
|
```
|
||||||
Error: project directory missing plan.md: {dir}
|
Error: project directory missing plan.md: {dir}
|
||||||
Run /ultraplan-local --project {dir} to produce it.
|
Run /trekplan --project {dir} to produce it.
|
||||||
```
|
```
|
||||||
- If no explicit `<plan.md>` argument is provided after flag parsing,
|
- If no explicit `<plan.md>` argument is provided after flag parsing,
|
||||||
use the derived `{dir}/plan.md`. If a `<plan.md>` argument IS provided,
|
use the derived `{dir}/plan.md`. If a `<plan.md>` argument IS provided,
|
||||||
|
|
@ -54,20 +54,20 @@ If no path is provided (and `--project` was not used to derive one), output
|
||||||
usage and stop:
|
usage and stop:
|
||||||
|
|
||||||
```
|
```
|
||||||
Usage: /ultraexecute-local <plan.md>
|
Usage: /trekexecute <plan.md>
|
||||||
/ultraexecute-local --project <dir>
|
/trekexecute --project <dir>
|
||||||
/ultraexecute-local --fg <plan.md>
|
/trekexecute --fg <plan.md>
|
||||||
/ultraexecute-local --resume <plan.md>
|
/trekexecute --resume <plan.md>
|
||||||
/ultraexecute-local --dry-run <plan.md>
|
/trekexecute --dry-run <plan.md>
|
||||||
/ultraexecute-local --validate <plan.md>
|
/trekexecute --validate <plan.md>
|
||||||
/ultraexecute-local --step N <plan.md>
|
/trekexecute --step N <plan.md>
|
||||||
/ultraexecute-local --session N <plan.md>
|
/trekexecute --session N <plan.md>
|
||||||
/ultraexecute-local --project <dir> --resume
|
/trekexecute --project <dir> --resume
|
||||||
/ultraexecute-local --project <dir> --session N
|
/trekexecute --project <dir> --session N
|
||||||
|
|
||||||
Modes:
|
Modes:
|
||||||
(default) Auto — multi-session if plan has Execution Strategy, else foreground
|
(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
|
is written there too
|
||||||
--fg Force foreground — all steps sequentially, ignore Execution Strategy
|
--fg Force foreground — all steps sequentially, ignore Execution Strategy
|
||||||
--resume Resume from last progress checkpoint
|
--resume Resume from last progress checkpoint
|
||||||
|
|
@ -77,13 +77,13 @@ Modes:
|
||||||
--session N Execute only session N from the plan's Execution Strategy
|
--session N Execute only session N from the plan's Execution Strategy
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
/ultraexecute-local .claude/plans/ultraplan-2026-04-06-auth-refactor.md
|
/trekexecute .claude/plans/trekplan-2026-04-06-auth-refactor.md
|
||||||
/ultraexecute-local --project .claude/projects/2026-04-18-jwt-auth
|
/trekexecute --project .claude/projects/2026-04-18-jwt-auth
|
||||||
/ultraexecute-local --project .claude/projects/2026-04-18-jwt-auth --resume
|
/trekexecute --project .claude/projects/2026-04-18-jwt-auth --resume
|
||||||
/ultraexecute-local --fg .claude/plans/ultraplan-2026-04-06-auth-refactor.md
|
/trekexecute --fg .claude/plans/trekplan-2026-04-06-auth-refactor.md
|
||||||
/ultraexecute-local --session 2 .claude/plans/ultraplan-2026-04-06-auth-refactor.md
|
/trekexecute --session 2 .claude/plans/trekplan-2026-04-06-auth-refactor.md
|
||||||
/ultraexecute-local --dry-run .claude/plans/ultraplan-2026-04-06-auth-refactor.md
|
/trekexecute --dry-run .claude/plans/trekplan-2026-04-06-auth-refactor.md
|
||||||
/ultraexecute-local --validate .claude/plans/ultraplan-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:
|
If the file does not exist, report and stop:
|
||||||
|
|
@ -100,16 +100,16 @@ File: {path}
|
||||||
|
|
||||||
## Phase 2 — Detect file type and parse structure
|
## 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`
|
- **Session spec**: contains `## Dependencies` with `Entry condition:` AND `## Scope Fence`
|
||||||
AND `## Exit Condition` sections.
|
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`.
|
but no `## Scope Fence`.
|
||||||
|
|
||||||
If neither structure is detected, report and stop:
|
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
|
### Parse steps
|
||||||
|
|
@ -226,7 +226,7 @@ Warnings: {count}
|
||||||
{if warnings}: - {each warning on own line}
|
{if warnings}: - {each warning on own line}
|
||||||
|
|
||||||
Plan is schema-compliant. Safe to run:
|
Plan is schema-compliant. Safe to run:
|
||||||
/ultraexecute-local {path}
|
/trekexecute {path}
|
||||||
```
|
```
|
||||||
|
|
||||||
If Phase 2 parsing failed (unrecognized format, missing Manifest in strict
|
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}:
|
{if format not recognized}:
|
||||||
Detected heading format: {e.g. "### Fase 1:", "## Phase 1"}
|
Detected heading format: {e.g. "### Fase 1:", "## Phase 1"}
|
||||||
Expected: "### Step N: <description>"
|
Expected: "### Step N: <description>"
|
||||||
Fix: re-run /ultraplan-local — planning-orchestrator must emit v1.7 format
|
Fix: re-run /trekplan — planning-orchestrator must emit v1.7 format
|
||||||
|
|
||||||
{if missing manifest}:
|
{if missing manifest}:
|
||||||
Step {N} has no Manifest block (plan_version=1.7 requires one per step)
|
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}:
|
{if malformed YAML or invalid regex}:
|
||||||
Step {N}: {specific YAML/regex error}
|
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.
|
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}
|
{output of git status --porcelain}
|
||||||
|
|
||||||
Commit or stash your changes, then re-run.
|
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"`.
|
Stop execution. Update progress with `status: "stopped"`.
|
||||||
|
|
||||||
**Also write `.session-state.local.json`** (Handover 7) — this surfaces the
|
**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`:
|
clean the working tree before resuming. Write atomically alongside `progress.json`:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
|
|
@ -458,7 +458,7 @@ that were manually edited or have bugs.
|
||||||
### Check 4 — Stale worktree cleanup
|
### Check 4 — Stale worktree cleanup
|
||||||
|
|
||||||
Run `git worktree list`. If any worktrees with paths containing
|
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
|
```bash
|
||||||
git worktree remove --force {stale-path} 2>/dev/null
|
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
|
```bash
|
||||||
REPO_ROOT="$(git rev-parse --show-toplevel)"
|
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"
|
WORKTREE_DIR="$SESSION_DIR/worktrees"
|
||||||
LOG_DIR="$SESSION_DIR/logs"
|
LOG_DIR="$SESSION_DIR/logs"
|
||||||
mkdir -p "$WORKTREE_DIR" "$LOG_DIR"
|
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
|
The budget caps default to safe values for normal-length steps. Operators may
|
||||||
override for long runs:
|
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:**
|
**2a. Create worktrees for this wave's sessions:**
|
||||||
|
|
||||||
|
|
@ -651,7 +651,7 @@ For each session N in the wave:
|
||||||
```bash
|
```bash
|
||||||
SESSION_CWD="${session_cwd:-.}" # default: worktree root; overridable per-session via Execution Strategy `cwd:` field
|
SESSION_CWD="${session_cwd:-.}" # default: worktree root; overridable per-session via Execution Strategy `cwd:` field
|
||||||
cd "$WORKTREE_PATH/$SESSION_CWD" && \
|
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" \
|
--allowedTools "Read,Write,Edit,Bash,Glob,Grep" \
|
||||||
--permission-mode bypassPermissions \
|
--permission-mode bypassPermissions \
|
||||||
--max-turns "$MAX_TURNS" \
|
--max-turns "$MAX_TURNS" \
|
||||||
|
|
@ -690,7 +690,7 @@ wait {PID1} {PID2} ...
|
||||||
**2d. Check results after each wave:**
|
**2d. Check results after each wave:**
|
||||||
|
|
||||||
For each session in the wave, read its log file (in `$LOG_DIR`, always accessible
|
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:
|
determine:
|
||||||
- Did the session complete? (`result: "completed"`)
|
- Did the session complete? (`result: "completed"`)
|
||||||
- Did it fail? (`result: "failed"` or `"stopped"`)
|
- Did it fail? (`result: "failed"` or `"stopped"`)
|
||||||
|
|
@ -719,7 +719,7 @@ unrecoverable failure to a recoverable one). Push failure is non-fatal
|
||||||
```bash
|
```bash
|
||||||
GIT_OPTIONAL_LOCKS=0 git push origin "trek/{slug}/session-{N}" 2>/dev/null || true
|
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}" \
|
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.
|
If the merge succeeds (exit code 0): continue to next session.
|
||||||
|
|
@ -823,12 +823,12 @@ The progress file location depends on whether `--project` is in use:
|
||||||
|
|
||||||
- **With `--project <dir>`:** progress lives at `{project_dir}/progress.json`.
|
- **With `--project <dir>`:** progress lives at `{project_dir}/progress.json`.
|
||||||
- **Without `--project`:** progress lives at
|
- **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.
|
filename without extension.
|
||||||
|
|
||||||
**Session-scoped naming:** When `mode = session N`:
|
**Session-scoped naming:** When `mode = session N`:
|
||||||
- With `--project`: `{project_dir}/progress-session-{N}.json`.
|
- 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
|
This prevents merge conflicts when parallel sessions each write their own
|
||||||
progress file.
|
progress file.
|
||||||
|
|
@ -879,7 +879,7 @@ progress file.
|
||||||
|
|
||||||
## Phase 4 — Entry condition check (session specs only)
|
## 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:
|
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
|
**Also write `.session-state.local.json`** (Handover 7) with the same
|
||||||
`status: "stopped"` and `next_session_brief_path` pointing at the brief that
|
`status: "stopped"` and `next_session_brief_path` pointing at the brief that
|
||||||
the failed entry-condition session was supposed to consume. This lets
|
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
|
write pattern + validator check as Phase 2.55. On validator failure, warn
|
||||||
but do not block.
|
but do not block.
|
||||||
|
|
||||||
**Also write sibling `NEXT-SESSION-PROMPT.local.md`** with frontmatter
|
**Also write sibling `NEXT-SESSION-PROMPT.local.md`** with frontmatter
|
||||||
(`produced_by: trekexecute`, `produced_at: <ISO-8601>`,
|
(`produced_by: trekexecute`, `produced_at: <ISO-8601>`,
|
||||||
`status: stopped`) — same combined ESM pattern as Phase 8 — so Phase 1.5
|
`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**:
|
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 |
|
| Wave | Session | Steps | Depends on | Command |
|
||||||
|------|---------|-------|------------|---------|
|
|------|---------|-------|------------|---------|
|
||||||
| 1 | Session 1: {title} | {nums} | none | `claude -p "/ultraexecute-local --session 1 {path}"` |
|
| 1 | Session 1: {title} | {nums} | none | `claude -p "/trekexecute --session 1 {path}"` |
|
||||||
| 1 | Session 2: {title} | {nums} | none | `claude -p "/ultraexecute-local --session 2 {path}"` |
|
| 1 | Session 2: {title} | {nums} | none | `claude -p "/trekexecute --session 2 {path}"` |
|
||||||
| 2 | Session 3: {title} | {nums} | S1, S2 | `claude -p "/ultraexecute-local --session 3 {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:
|
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
|
`status: "passed"` in the progress file — collect their `Files:` fields. Never
|
||||||
use `git add -A` (risks staging secrets, binaries, or unrelated work).
|
use `git add -A` (risks staging secrets, binaries, or unrelated work).
|
||||||
```bash
|
```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.
|
Jump to Phase 7.
|
||||||
|
|
||||||
|
|
@ -1170,7 +1170,7 @@ and jump to Phase 8 (final report).
|
||||||
|
|
||||||
## Phase 7 — Exit condition check (session specs only)
|
## 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:
|
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)
|
## Phase 7.6 — Recovery dispatch (multi-session parent context only)
|
||||||
|
|
||||||
**Preconditions:**
|
**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`
|
- Phase 7.5 reported `drift`
|
||||||
- `recovery_depth < 2` (hard cap to prevent infinite loops)
|
- `recovery_depth < 2` (hard cap to prevent infinite loops)
|
||||||
|
|
||||||
|
|
@ -1256,7 +1256,7 @@ the user for manual resolution.
|
||||||
**Invoke the recovery session:**
|
**Invoke the recovery session:**
|
||||||
|
|
||||||
```bash
|
```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" \
|
--allowedTools "Read,Write,Edit,Bash,Glob,Grep" \
|
||||||
--permission-mode bypassPermissions \
|
--permission-mode bypassPermissions \
|
||||||
> "$LOG_DIR/session-{N}-recovery-{depth}.log" 2>&1
|
> "$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` —
|
**Recovery surface:** if declined, `--resume re-enters at the gate` —
|
||||||
re-running `/ultraexecute-local --resume --project <dir>` jumps directly
|
re-running `/trekexecute --resume --project <dir>` jumps directly
|
||||||
back to the main-merge gate AskUserQuestion (skipping completed waves).
|
back to the main-merge gate AskUserQuestion (skipping completed waves).
|
||||||
The wave session branches are preserved for inspection (Hard Rule 19's
|
The wave session branches are preserved for inspection (Hard Rule 19's
|
||||||
push-before-cleanup ensures they survive on the remote even if local
|
push-before-cleanup ensures they survive on the remote even if local
|
||||||
cleanup ran). To inspect: `git log ultraplan/<slug>/session-N` per wave.
|
cleanup ran). To inspect: `git log trekplan/<slug>/session-N` per wave.
|
||||||
|
|
||||||
### Progress + state-file writes
|
### 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
|
**Also write sibling `NEXT-SESSION-PROMPT.local.md`** (Bug 3 frontmatter
|
||||||
contract — see `docs/HANDOVER-CONTRACTS.md` § Handover 7 Lifecycle) in the
|
contract — see `docs/HANDOVER-CONTRACTS.md` § Handover 7 Lifecycle) in the
|
||||||
project directory. The frontmatter MUST contain `produced_by: trekexecute`
|
project directory. The frontmatter MUST contain `produced_by: trekexecute`
|
||||||
and `produced_at: <ISO-8601>` so `/ultracontinue` Phase 1.5 can detect
|
and `produced_at: <ISO-8601>` so `/trekcontinue` Phase 1.5 can detect
|
||||||
producer drift between project-dir and plugin-root candidates. Use a single
|
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:
|
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 now = new Date().toISOString();
|
||||||
const stateObj = { schema_version: 1, project: dir, next_session_brief_path: briefPath, next_session_label: label, status, updated_at: now };
|
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);
|
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);
|
writeFileSync(path.join(dir, 'NEXT-SESSION-PROMPT.local.md'), promptBody);
|
||||||
" '{project_dir}' '{next_session_brief_path}' '{next_session_label}' '{status}'`
|
" '{project_dir}' '{next_session_brief_path}' '{next_session_label}' '{status}'`
|
||||||
```
|
```
|
||||||
|
|
@ -1426,7 +1426,7 @@ Attempts: {N}
|
||||||
|
|
||||||
{Numbered list of unexecuted steps}
|
{Numbered list of unexecuted steps}
|
||||||
|
|
||||||
To resume: /ultraexecute-local --resume {path}
|
To resume: /trekexecute --resume {path}
|
||||||
```
|
```
|
||||||
|
|
||||||
**Result vocabulary (v1.7, strict):**
|
**Result vocabulary (v1.7, strict):**
|
||||||
|
|
@ -1441,7 +1441,7 @@ To resume: /ultraexecute-local --resume {path}
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ultraexecute_summary": {
|
"trekexecute_summary": {
|
||||||
"plan": "{path}",
|
"plan": "{path}",
|
||||||
"plan_type": "{plan | session-spec}",
|
"plan_type": "{plan | session-spec}",
|
||||||
"plan_version": "{1.7 | 1.6 | legacy}",
|
"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
|
## Phase 9 — Stats tracking
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -6,24 +6,24 @@ model: opus
|
||||||
allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, TaskCreate, TaskUpdate, TeamCreate, TeamDelete
|
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**.
|
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
|
research briefs referenced in it, then runs specialized exploration
|
||||||
agents, synthesis, and adversarial review to produce an executable plan.
|
agents, synthesis, and adversarial review to produce an executable plan.
|
||||||
|
|
||||||
**v2.0 is a breaking release.** The interview phase has been extracted
|
**v2.0 is a breaking release.** The interview phase has been extracted
|
||||||
into `/ultrabrief-local`. This command no longer accepts free-text task
|
into `/trekbrief`. This command no longer accepts free-text task
|
||||||
descriptions — it requires either `--brief <path>` or `--project <dir>`.
|
descriptions — it requires either `--brief <path>` or `--project <dir>`.
|
||||||
|
|
||||||
Pipeline position:
|
Pipeline position:
|
||||||
|
|
||||||
```
|
```
|
||||||
/ultrabrief-local → brief.md
|
/trekbrief → brief.md
|
||||||
/ultraresearch-local → research/*.md
|
/trekresearch → research/*.md
|
||||||
/ultraplan-local → plan.md (this command)
|
/trekplan → plan.md (this command)
|
||||||
/ultraexecute-local → execution
|
/trekexecute → execution
|
||||||
```
|
```
|
||||||
|
|
||||||
## Phase 1 — Parse mode and validate input
|
## 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).
|
- Research briefs auto-discovered from `{dir}/research/*.md` (sorted).
|
||||||
- If `{dir}` does not exist or `{dir}/brief.md` is missing:
|
- 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
|
Missing: {dir}/brief.md
|
||||||
```
|
```
|
||||||
- Set **project_dir = {dir}**, **brief_path = {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:
|
output usage and stop:
|
||||||
|
|
||||||
```
|
```
|
||||||
Usage: /ultraplan-local --brief <path-to-brief.md>
|
Usage: /trekplan --brief <path-to-brief.md>
|
||||||
/ultraplan-local --project <project-dir>
|
/trekplan --project <project-dir>
|
||||||
/ultraplan-local --brief <path> --research <research-brief.md>
|
/trekplan --brief <path> --research <research-brief.md>
|
||||||
/ultraplan-local --project <dir> --fg
|
/trekplan --project <dir> --fg
|
||||||
/ultraplan-local --project <dir> --quick
|
/trekplan --project <dir> --quick
|
||||||
/ultraplan-local --export <pr|issue|markdown|headless> <plan-path>
|
/trekplan --export <pr|issue|markdown|headless> <plan-path>
|
||||||
/ultraplan-local --decompose <plan-path>
|
/trekplan --decompose <plan-path>
|
||||||
|
|
||||||
A brief is required. Produce one with /ultrabrief-local first.
|
A brief is required. Produce one with /trekbrief first.
|
||||||
|
|
||||||
Modes:
|
Modes:
|
||||||
--brief Plan from a brief file (foreground, v2.4.0+)
|
--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
|
--decompose Split an existing plan into self-contained headless sessions
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth
|
/trekplan --project .claude/projects/2026-04-18-jwt-auth
|
||||||
/ultraplan-local --brief .claude/projects/2026-04-18-jwt-auth/brief.md
|
/trekplan --brief .claude/projects/2026-04-18-jwt-auth/brief.md
|
||||||
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth --research extra.md
|
/trekplan --project .claude/projects/2026-04-18-jwt-auth --research extra.md
|
||||||
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth --fg
|
/trekplan --project .claude/projects/2026-04-18-jwt-auth --fg
|
||||||
/ultraplan-local --export pr .claude/plans/ultraplan-2026-04-06-rate-limiting.md
|
/trekplan --export pr .claude/plans/trekplan-2026-04-06-rate-limiting.md
|
||||||
/ultraplan-local --decompose .claude/plans/ultraplan-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
|
Migrating from v1.x? See MIGRATION.md in this plugin. The old --spec flag
|
||||||
and free-text interview mode were removed in v2.0.
|
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}
|
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`
|
The brief input may be a `review.md` produced by `/trekreview`
|
||||||
instead of a `brief.md` produced by `/ultrabrief-local`. Both files
|
instead of a `brief.md` produced by `/trekbrief`. Both files
|
||||||
share the same handover slot — `type` is the discriminator.
|
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
|
1. Skip the `research_status` gate above (review.md has no
|
||||||
`research_topics` and no Research Plan section).
|
`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}
|
{Risks from plan, abbreviated to 1 line each}
|
||||||
|
|
||||||
---
|
---
|
||||||
*Generated by ultraplan-local from {plan filename}*
|
*Generated by trekplan from {plan filename}*
|
||||||
```
|
```
|
||||||
|
|
||||||
### Format: `issue`
|
### Format: `issue`
|
||||||
|
|
@ -270,7 +270,7 @@ Output a markdown block formatted as an issue comment:
|
||||||
{Top 2–3 risks from plan}
|
{Top 2–3 risks from plan}
|
||||||
|
|
||||||
---
|
---
|
||||||
*Generated by ultraplan-local*
|
*Generated by trekplan*
|
||||||
```
|
```
|
||||||
|
|
||||||
### Format: `markdown`
|
### 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
|
Read the plan file. Verify it contains an Implementation Plan section with
|
||||||
numbered steps. If no steps are found, report and stop:
|
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:
|
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`)
|
- Extract the slug from the plan filename (e.g., `trekplan-2026-04-06-auth-refactor` → `auth-refactor`)
|
||||||
- Output directory: `.claude/ultraplan-sessions/{slug}/`
|
- Output directory: `.claude/trekplan-sessions/{slug}/`
|
||||||
|
|
||||||
Launch the **session-decomposer** agent:
|
Launch the **session-decomposer** agent:
|
||||||
|
|
||||||
```
|
```
|
||||||
Plan file: {plan path}
|
Plan file: {plan path}
|
||||||
Plugin root: ${CLAUDE_PLUGIN_ROOT}
|
Plugin root: ${CLAUDE_PLUGIN_ROOT}
|
||||||
Output directory: .claude/ultraplan-sessions/{slug}/
|
Output directory: .claude/trekplan-sessions/{slug}/
|
||||||
```
|
```
|
||||||
|
|
||||||
The session-decomposer will:
|
The session-decomposer will:
|
||||||
|
|
@ -334,7 +334,7 @@ When the session-decomposer completes, present the summary to the user:
|
||||||
|
|
||||||
**Master plan:** {plan path}
|
**Master plan:** {plan path}
|
||||||
**Sessions:** {N} across {W} waves
|
**Sessions:** {N} across {W} waves
|
||||||
**Output:** .claude/ultraplan-sessions/{slug}/
|
**Output:** .claude/trekplan-sessions/{slug}/
|
||||||
|
|
||||||
### Sessions
|
### Sessions
|
||||||
|
|
||||||
|
|
@ -344,14 +344,14 @@ When the session-decomposer completes, present the summary to the user:
|
||||||
|
|
||||||
### Files generated
|
### Files generated
|
||||||
|
|
||||||
- Session specs: .claude/ultraplan-sessions/{slug}/session-*.md
|
- Session specs: .claude/trekplan-sessions/{slug}/session-*.md
|
||||||
- Dependency graph: .claude/ultraplan-sessions/{slug}/dependency-graph.md
|
- Dependency graph: .claude/trekplan-sessions/{slug}/dependency-graph.md
|
||||||
- Launch script: .claude/ultraplan-sessions/{slug}/launch.sh
|
- Launch script: .claude/trekplan-sessions/{slug}/launch.sh
|
||||||
|
|
||||||
You can:
|
You can:
|
||||||
- Review individual session specs before running
|
- Review individual session specs before running
|
||||||
- Run all sessions: `bash .claude/ultraplan-sessions/{slug}/launch.sh`
|
- Run all sessions: `bash .claude/trekplan-sessions/{slug}/launch.sh`
|
||||||
- Run a single session: `claude -p "$(cat .claude/ultraplan-sessions/{slug}/session-1-*.md)"`
|
- Run a single session: `claude -p "$(cat .claude/trekplan-sessions/{slug}/session-1-*.md)"`
|
||||||
- Say **"launch"** to start headless execution from here
|
- 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)
|
## 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
|
longer asks the user any requirements questions — the brief is the
|
||||||
authoritative input.
|
authoritative input.
|
||||||
|
|
||||||
|
|
@ -372,7 +372,7 @@ Determine the plan destination path:
|
||||||
frontmatter field): **plan destination = {project_dir}/plan.md**.
|
frontmatter field): **plan destination = {project_dir}/plan.md**.
|
||||||
- Otherwise: derive slug and date — if the brief has frontmatter `slug` and
|
- Otherwise: derive slug and date — if the brief has frontmatter `slug` and
|
||||||
`created`, use them; otherwise extract from the brief filename. Destination:
|
`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
|
Collect all research briefs (from `--research` flag and auto-discovered
|
||||||
`{project_dir}/research/*.md`).
|
`{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:
|
Use the plan destination computed in Phase 3:
|
||||||
- `--project` mode: `{project_dir}/plan.md`
|
- `--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.
|
Create the parent directory if it does not exist.
|
||||||
|
|
||||||
|
|
@ -731,7 +731,7 @@ After both complete:
|
||||||
Present a summary to the user:
|
Present a summary to the user:
|
||||||
|
|
||||||
```
|
```
|
||||||
## Ultraplan Complete
|
## Voyage Complete
|
||||||
|
|
||||||
**Task:** {task description}
|
**Task:** {task description}
|
||||||
**Mode:** {foreground | quick}
|
**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
|
brief (Intent, Goal, Constraint, Preference, NFR, Success Criterion). If a
|
||||||
step has no brief basis, it is scope creep — flag it or remove it.
|
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
|
- **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.
|
- **Scope**: Only explore the current working directory and its subdirectories.
|
||||||
Never read files outside the repo (no ~/.env, no credentials, no other repos).
|
Never read files outside the repo (no ~/.env, no credentials, no other repos).
|
||||||
- **Cost**: Sonnet for all agents (exploration, deep-dives, research, critics).
|
- **Cost**: Sonnet for all agents (exploration, deep-dives, research, critics).
|
||||||
|
|
|
||||||
|
|
@ -17,9 +17,9 @@ external research could provide alone.
|
||||||
specialized agents, each seeing only what they need. The value is in triangulation
|
specialized agents, each seeing only what they need. The value is in triangulation
|
||||||
(cross-checking local vs. external) and synthesis (insights from combining both).
|
(cross-checking local vs. external) and synthesis (insights from combining both).
|
||||||
|
|
||||||
**Pipeline integration:** Research briefs feed into ultraplan via `--research`:
|
**Pipeline integration:** Research briefs feed into trekplan via `--research`:
|
||||||
```
|
```
|
||||||
/ultraresearch-local <question> → brief → /ultraplan-local --research <brief> <task>
|
/trekresearch <question> → brief → /trekplan --research <brief> <task>
|
||||||
```
|
```
|
||||||
|
|
||||||
## Phase 1 — Parse mode and validate input
|
## 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
|
is always foreground as of v2.4.0. Set **execution = foreground** (the
|
||||||
only mode).
|
only mode).
|
||||||
|
|
||||||
5. `--project <dir>` — attach this research to an ultrabrief project folder.
|
5. `--project <dir>` — attach this research to an trekbrief project folder.
|
||||||
The brief will be written to `{dir}/research/{NN}-{slug}.md` (auto-incremented
|
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}**.
|
index) instead of the default `.claude/research/` path. Set **project_dir = {dir}**.
|
||||||
|
|
||||||
If `{dir}` does not exist:
|
If `{dir}` does not exist:
|
||||||
```
|
```
|
||||||
Error: project directory not found: {dir}
|
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.
|
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:
|
If no research question is provided, output usage and stop:
|
||||||
|
|
||||||
```
|
```
|
||||||
Usage: /ultraresearch-local <research question>
|
Usage: /trekresearch <research question>
|
||||||
/ultraresearch-local --quick <research question>
|
/trekresearch --quick <research question>
|
||||||
/ultraresearch-local --local <research question>
|
/trekresearch --local <research question>
|
||||||
/ultraresearch-local --external <research question>
|
/trekresearch --external <research question>
|
||||||
/ultraresearch-local --fg <research question>
|
/trekresearch --fg <research question>
|
||||||
/ultraresearch-local --project <dir> [--external|--local|--quick|--fg] <research question>
|
/trekresearch --project <dir> [--external|--local|--quick|--fg] <research question>
|
||||||
|
|
||||||
Modes:
|
Modes:
|
||||||
default Interview → foreground research (local + external) → brief
|
default Interview → foreground research (local + external) → brief
|
||||||
|
|
@ -88,17 +88,17 @@ Modes:
|
||||||
--local Only codebase analysis agents (skip external + Gemini)
|
--local Only codebase analysis agents (skip external + Gemini)
|
||||||
--external Only external research agents (skip codebase analysis)
|
--external Only external research agents (skip codebase analysis)
|
||||||
--fg No-op alias (foreground is the only mode as of v2.4.0)
|
--fg No-op alias (foreground is the only mode as of v2.4.0)
|
||||||
--project Write brief into an ultrabrief project folder (auto-indexed)
|
--project Write brief into an trekbrief project folder (auto-indexed)
|
||||||
|
|
||||||
Flags can be combined: --local, --external --quick, --project <dir> --external
|
Flags can be combined: --local, --external --quick, --project <dir> --external
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
/ultraresearch-local Should we migrate from Express to Fastify?
|
/trekresearch Should we migrate from Express to Fastify?
|
||||||
/ultraresearch-local --quick What auth libraries are popular for Node.js?
|
/trekresearch --quick What auth libraries are popular for Node.js?
|
||||||
/ultraresearch-local --local How is error handling structured in this codebase?
|
/trekresearch --local How is error handling structured in this codebase?
|
||||||
/ultraresearch-local --external What are the security implications of using Redis for sessions?
|
/trekresearch --external What are the security implications of using Redis for sessions?
|
||||||
/ultraresearch-local --fg --local What patterns does this codebase use for database access?
|
/trekresearch --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 --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.
|
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`
|
- Brief destination: `{project_dir}/research/{NN}-{slug}.md`
|
||||||
|
|
||||||
If **project_dir is not set**:
|
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.
|
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**.
|
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.
|
is more focused than planning.
|
||||||
|
|
||||||
### Interview flow
|
### Interview flow
|
||||||
|
|
@ -292,7 +292,7 @@ other agents — the value of Gemini is independence.
|
||||||
|
|
||||||
- Launch ALL selected agents **in parallel** in a single message
|
- Launch ALL selected agents **in parallel** in a single message
|
||||||
- Use model: "sonnet" for all sub-agents (the orchestrator runs on Opus)
|
- 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
|
small = halved, medium/large = default
|
||||||
- convention-scanner: medium+ codebases only (50+ files)
|
- 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
|
## 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:
|
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).
|
Generate the slug from the research question (first 3-4 meaningful words).
|
||||||
Write the brief to the `brief_destination` computed in Phase 1:
|
Write the brief to the `brief_destination` computed in Phase 1:
|
||||||
- With `--project`: `{project_dir}/research/{NN}-{slug}.md`
|
- 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.
|
Create the parent directory if it does not exist.
|
||||||
|
|
||||||
|
|
@ -378,8 +378,8 @@ Present a summary to the user:
|
||||||
|
|
||||||
You can:
|
You can:
|
||||||
- Read the full brief at {brief_destination}
|
- Read the full brief at {brief_destination}
|
||||||
- If `--project` was used: run `/ultraplan-local --project {project_dir}` when all research topics are complete
|
- If `--project` was used: run `/trekplan --project {project_dir}` when all research topics are complete
|
||||||
- Otherwise: `/ultraplan-local --research {brief_destination} --brief <your-brief.md>`
|
- Otherwise: `/trekplan --research {brief_destination} --brief <your-brief.md>`
|
||||||
- Ask follow-up questions about specific findings
|
- 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
|
## Hard rules
|
||||||
|
|
||||||
- **No planning:** This command produces research briefs, not implementation plans.
|
- **No planning:** This command produces research briefs, not implementation plans.
|
||||||
If the user asks to plan, direct them to `/ultraplan-local --research <brief>`.
|
If the user asks to plan, direct them to `/trekplan --research <brief>`.
|
||||||
- **Sources required:** Every claim must cite a source. No unsourced findings.
|
- **Sources required:** Every claim must cite a source. No unsourced findings.
|
||||||
- **Independence:** Do not pre-bias external agents with local findings or vice versa.
|
- **Independence:** Do not pre-bias external agents with local findings or vice versa.
|
||||||
Triangulate AFTER independent research.
|
Triangulate AFTER independent research.
|
||||||
|
|
|
||||||
|
|
@ -11,19 +11,19 @@ allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion
|
||||||
|
|
||||||
# Ultrareview Local v1.0
|
# 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
|
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).
|
review.md` can consume as plan input (Handover 6).
|
||||||
|
|
||||||
Pipeline position:
|
Pipeline position:
|
||||||
|
|
||||||
```
|
```
|
||||||
/ultrabrief-local → brief.md
|
/trekbrief → brief.md
|
||||||
/ultraresearch-local → research/*.md
|
/trekresearch → research/*.md
|
||||||
/ultraplan-local → plan.md
|
/trekplan → plan.md
|
||||||
/ultraexecute-local → progress.json (+ commits)
|
/trekexecute → progress.json (+ commits)
|
||||||
/ultrareview-local → review.md (this command)
|
/trekreview → review.md (this command)
|
||||||
```
|
```
|
||||||
|
|
||||||
The review is **independent**: each reviewer runs without cross-feeding,
|
The review is **independent**: each reviewer runs without cross-feeding,
|
||||||
|
|
@ -38,15 +38,15 @@ command executes inline.
|
||||||
Parse `$ARGUMENTS` via the shared arg-parser:
|
Parse `$ARGUMENTS` via the shared arg-parser:
|
||||||
|
|
||||||
```bash
|
```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`
|
The parser recognizes these flags (see `lib/parsers/arg-parser.mjs`
|
||||||
FLAG_SCHEMA `ultrareview` entry):
|
FLAG_SCHEMA `trekreview` entry):
|
||||||
|
|
||||||
| Flag | Type | Purpose |
|
| Flag | Type | Purpose |
|
||||||
|------|------|---------|
|
|------|------|---------|
|
||||||
| `--project <dir>` | valued | Required. Path to ultraplan-local project folder containing `brief.md`. |
|
| `--project <dir>` | valued | Required. Path to trekplan project folder containing `brief.md`. |
|
||||||
| `--since <ref>` | valued | Optional. Override "before" SHA for the diff. Validated via `git rev-parse --verify`. |
|
| `--since <ref>` | valued | Optional. Override "before" SHA for the diff. Validated via `git rev-parse --verify`. |
|
||||||
| `--quick` | boolean | Skip the brief-conformance pass; run only the code-correctness reviewer; skip the coordinator's reasonableness filter. |
|
| `--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. |
|
| `--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:
|
1. If `--project` is missing, print usage and stop:
|
||||||
```
|
```
|
||||||
Error: --project <dir> is required.
|
Error: --project <dir> is required.
|
||||||
Usage: /ultrareview-local --project <dir> [--since <ref>] [--quick] [--validate] [--dry-run]
|
Usage: /trekreview --project <dir> [--since <ref>] [--quick] [--validate] [--dry-run]
|
||||||
```
|
```
|
||||||
2. Trim trailing slash from `{dir}`. Set:
|
2. Trim trailing slash from `{dir}`. Set:
|
||||||
- `project_dir = {dir}`
|
- `project_dir = {dir}`
|
||||||
|
|
@ -65,7 +65,7 @@ Resolution:
|
||||||
- `review_path = {dir}/review.md`
|
- `review_path = {dir}/review.md`
|
||||||
3. If `{dir}` does not exist or `{dir}/brief.md` is missing:
|
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
|
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
|
Read the JSON output. If `valid: false` AND any error has code
|
||||||
`BRIEF_MISSING_REQUIRED_FIELD` or `FRONTMATTER_PARSE_ERROR`: stop and
|
`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.
|
warnings in the review's Executive Summary.
|
||||||
|
|
||||||
Read the brief frontmatter. Capture for review.md:
|
Read the brief frontmatter. Capture for review.md:
|
||||||
|
|
@ -299,13 +299,13 @@ After the write succeeds, print:
|
||||||
You can:
|
You can:
|
||||||
- Read the full review at {review_path}
|
- Read the full review at {review_path}
|
||||||
- Feed BLOCKER + MAJOR findings into a follow-up plan:
|
- 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 `--quick` for a faster correctness-only pass
|
||||||
- Re-run with `--since <ref>` to narrow scope
|
- Re-run with `--since <ref>` to narrow scope
|
||||||
```
|
```
|
||||||
|
|
||||||
Per **Handover 6**, BLOCKER and MAJOR findings are consumed by
|
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
|
review's frontmatter `findings:` list and the trailing JSON block are
|
||||||
the contract for that handover (see `docs/HANDOVER-CONTRACTS.md`).
|
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
|
- **Refuse-with-suggestion above 100 files / 100K tokens.** Never run
|
||||||
blind on a giant diff. Use AskUserQuestion to surface the gate.
|
blind on a giant diff. Use AskUserQuestion to surface the gate.
|
||||||
- **Cost.** Sonnet for all sub-agents (reviewers + coordinator). Opus
|
- **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.
|
- **Privacy.** Never log secrets, tokens, or credentials in review.md.
|
||||||
Findings citing files with secret-like content must redact the secret
|
Findings citing files with secret-like content must redact the secret
|
||||||
in the `detail` field.
|
in the `detail` field.
|
||||||
|
|
|
||||||
|
|
@ -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**.
|
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 |
|
| Artifact | Field | Current |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| `brief.md` | `brief_version` (frontmatter) | `2.0` |
|
| `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` |
|
| `plan.md` | `plan_version` (frontmatter) | `1.7` |
|
||||||
| `progress.json` | `schema_version` (top-level) | `"1"` |
|
| `progress.json` | `schema_version` (top-level) | `"1"` |
|
||||||
| `review.md` | `review_version` (frontmatter) | `1.0` |
|
| `review.md` | `review_version` (frontmatter) | `1.0` |
|
||||||
|
|
@ -43,9 +43,9 @@ Every validator exposes a CLI: `node lib/validators/<name>.mjs --json <path>` re
|
||||||
|
|
||||||
## Handover 1 — `brief.md` → research/
|
## 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:**
|
**Path conventions:**
|
||||||
- Project-dir mode (recommended): `.claude/projects/{YYYY-MM-DD}-{slug}/brief.md`.
|
- Project-dir mode (recommended): `.claude/projects/{YYYY-MM-DD}-{slug}/brief.md`.
|
||||||
|
|
@ -55,7 +55,7 @@ Every validator exposes a CLI: `node lib/validators/<name>.mjs --json <path>` re
|
||||||
|
|
||||||
| Field | Type | Required | Allowed values | Notes |
|
| 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 |
|
| `brief_version` | string | yes | `"2.0"` (current) | Bump on schema change |
|
||||||
| `created` | date | yes | YYYY-MM-DD | |
|
| `created` | date | yes | YYYY-MM-DD | |
|
||||||
| `task` | string | yes | one-line description | |
|
| `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 |
|
| Frontmatter parse | every read | YAML subset; reject nested dicts |
|
||||||
| Required fields | every read | All `BRIEF_REQUIRED_FRONTMATTER` present |
|
| 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` |
|
| Status enum | every read | `research_status ∈ allowed values` |
|
||||||
| **State machine** | every read | `research_topics > 0 && research_status === "skipped"` requires `brief_quality === "partial"` |
|
| **State machine** | every read | `research_topics > 0 && research_status === "skipped"` requires `brief_quality === "partial"` |
|
||||||
| Body sections | strict only | All `BRIEF_BODY_SECTIONS` present |
|
| 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
|
## 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:**
|
**Path conventions:**
|
||||||
- Project-dir mode: `.claude/projects/{YYYY-MM-DD}-{slug}/research/{NN}-{topic-slug}.md` (sorted by filename).
|
- 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:**
|
**Frontmatter schema:**
|
||||||
|
|
||||||
| Field | Type | Required | Allowed values |
|
| Field | Type | Required | Allowed values |
|
||||||
|---|---|---|---|
|
|---|---|---|---|
|
||||||
| `type` | string | yes | `ultraresearch-brief` |
|
| `type` | string | yes | `trekresearch-brief` |
|
||||||
| `created` | date | yes | YYYY-MM-DD |
|
| `created` | date | yes | YYYY-MM-DD |
|
||||||
| `question` | string | yes | the research question |
|
| `question` | string | yes | the research question |
|
||||||
| `confidence` | number | optional | `[0.0, 1.0]` — strongly recommended |
|
| `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).
|
**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:**
|
**Path conventions:**
|
||||||
- Canonical: `{project_dir}/architecture/overview.md`
|
- Canonical: `{project_dir}/architecture/overview.md`
|
||||||
- Optional: `{project_dir}/architecture/gaps.md`
|
- Optional: `{project_dir}/architecture/gaps.md`
|
||||||
- Tolerated alternatives (with warning): `architecture-overview.md`, `overview.markdown`, `README.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.
|
**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`).
|
**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:**
|
**Path conventions:**
|
||||||
- Project-dir: `{project_dir}/plan.md`
|
- Project-dir: `{project_dir}/plan.md`
|
||||||
- Legacy: `.claude/plans/ultraplan-{date}-{slug}.md`
|
- Legacy: `.claude/plans/trekplan-{date}-{slug}.md`
|
||||||
|
|
||||||
**Frontmatter schema:**
|
**Frontmatter schema:**
|
||||||
|
|
||||||
|
|
@ -207,7 +207,7 @@ The validator (`lib/validators/architecture-discovery.mjs`) is intentionally min
|
||||||
|
|
||||||
**Validation strategy:**
|
**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 |
|
| 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)
|
## 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:**
|
**Path conventions:**
|
||||||
- Project-dir: `{project_dir}/progress.json`
|
- Project-dir: `{project_dir}/progress.json`
|
||||||
- Legacy: `{plan-dir}/.ultraexecute-progress-{slug}.json`
|
- Legacy: `{plan-dir}/.trekexecute-progress-{slug}.json`
|
||||||
|
|
||||||
**Schema (top-level):**
|
**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 |
|
| `note` | string | optional human-readable annotation |
|
||||||
|
|
||||||
**Validation strategy:** `progress-validator.mjs` runs at:
|
**Validation strategy:** `progress-validator.mjs` runs at:
|
||||||
1. `/ultraexecute-local --validate` (alongside plan-validator)
|
1. `/trekexecute --validate` (alongside plan-validator)
|
||||||
2. `/ultraexecute-local --resume` entry (must pass `checkResumeReadiness`)
|
2. `/trekexecute --resume` entry (must pass `checkResumeReadiness`)
|
||||||
3. `pre-compact-flush` hook (drift check before compaction; never blocks)
|
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.
|
**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`.
|
**Handover 6 closes the iteration loop.** Where Handovers 1–4 flow forward (brief → research → plan → execute) and Handover 5 makes execute resumable, Handover 6 routes review findings *back* into planning so a remediation plan can be produced with full traceability via `source_findings`.
|
||||||
|
|
||||||
**Producer:** `/ultrareview-local` Phase 7 (write `review.md` after coordinator dedup + verdict).
|
**Producer:** `/trekreview` Phase 7 (write `review.md` after coordinator dedup + verdict).
|
||||||
|
|
||||||
**Consumer:** `/ultraplan-local` Phase 1 when `--brief review.md` is supplied and the consumer detects `type: ultrareview` in frontmatter. The plan command branches into a remediation-plan path: BLOCKER + MAJOR findings become plan goals, the produced `plan.md` carries a `source_findings: [<id>, ...]` frontmatter list as the audit trail back to the consumed findings. MINOR + SUGGESTION are skipped for v1.0 plan-input.
|
**Consumer:** `/trekplan` Phase 1 when `--brief review.md` is supplied and the consumer detects `type: trekreview` in frontmatter. The plan command branches into a remediation-plan path: BLOCKER + MAJOR findings become plan goals, the produced `plan.md` carries a `source_findings: [<id>, ...]` frontmatter list as the audit trail back to the consumed findings. MINOR + SUGGESTION are skipped for v1.0 plan-input.
|
||||||
|
|
||||||
**Path conventions:**
|
**Path conventions:**
|
||||||
- Project-dir mode (recommended): `{project_dir}/review.md` (one per review iteration; subsequent runs overwrite atomically).
|
- 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 |
|
| 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 |
|
| `review_version` | string | yes | `"1.0"` (current) | Bump on schema change |
|
||||||
| `task` | string | yes | one-line description | Mirrors brief task |
|
| `task` | string | yes | one-line description | Mirrors brief task |
|
||||||
| `slug` | string | yes | URL-safe slug | Used in project_dir |
|
| `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 |
|
| Frontmatter parse | every read | YAML subset; reject nested dicts |
|
||||||
| Required fields | every read | All `REVIEW_REQUIRED_FRONTMATTER` present |
|
| 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}$` |
|
| Findings shape | every read | Array of strings, each matching `^[0-9a-f]{40}$` |
|
||||||
| Body sections | strict only | `Executive Summary`, `Coverage`, `Remediation Summary` |
|
| Body sections | strict only | `Executive Summary`, `Coverage`, `Remediation Summary` |
|
||||||
| Version format | every read | `review_version` matches `N.M`; warning otherwise |
|
| Version format | every read | `review_version` matches `N.M`; warning otherwise |
|
||||||
|
|
||||||
The validator (`lib/validators/review-validator.mjs`) exposes the same CLI as the others: `node lib/validators/review-validator.mjs --json <review.md>`. Strict mode is the default; `--soft` downgrades section-missing errors to warnings. `/ultrareview-local` Phase 8 runs `--strict`. `/ultraplan-local` Phase 1 (when consuming `--brief review.md`) runs `--soft` so a partially-valid review can still seed a plan.
|
The validator (`lib/validators/review-validator.mjs`) exposes the same CLI as the others: `node lib/validators/review-validator.mjs --json <review.md>`. Strict mode is the default; `--soft` downgrades section-missing errors to warnings. `/trekreview` Phase 8 runs `--strict`. `/trekplan` Phase 1 (when consuming `--brief review.md`) runs `--soft` so a partially-valid review can still seed a plan.
|
||||||
|
|
||||||
**Versioning:** current is `1.0`. There are no live `0.x` reviews. Future schema changes follow the breaking-change protocol above.
|
**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_NOT_FOUND` → consumer halts with usage message
|
||||||
- `REVIEW_READ_ERROR` → I/O failure; halt
|
- `REVIEW_READ_ERROR` → I/O failure; halt
|
||||||
- `FM_MISSING` → file has no frontmatter; 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_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_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
|
- `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 — `.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:**
|
**Producer:**
|
||||||
- `/ultraexecute-local` Phase 8 (canonical convergence — every completed/failed/stopped/partial run that reaches the final report)
|
- `/trekexecute` 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)
|
- `/trekexecute` Phase 2.55 (Check 1 — dirty-tree pre-flight stop)
|
||||||
- `/ultraexecute-local` Phase 4 (entry-condition stop)
|
- `/trekexecute` Phase 4 (entry-condition stop)
|
||||||
- `/ultraplan-end-session-local` (informal multi-session helper — Step 9 of v3.3.0)
|
- `/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).
|
- *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.
|
- `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:**
|
**Path conventions:**
|
||||||
- Per-project: `.claude/projects/{YYYY-MM-DD}-{slug}/.session-state.local.json` — one file per project directory.
|
- 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).
|
**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:**
|
**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.
|
**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:**
|
**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_PARSE_ERROR` → halt with structured error; user fixes JSON
|
||||||
- `SESSION_STATE_MISSING_FIELD` → halt; suggests running validator directly
|
- `SESSION_STATE_MISSING_FIELD` → halt; suggests running validator directly
|
||||||
- `SESSION_STATE_SCHEMA_MISMATCH` → halt; future `1` → `2` migration path will warn instead
|
- `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_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.
|
- 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
|
### § Lifecycle
|
||||||
|
|
@ -420,12 +420,12 @@ The state file follows a producer/consumer separation that keeps responsibilitie
|
||||||
|
|
||||||
| Role | Owners | Phase / location |
|
| 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 (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) | `/ultraplan-end-session-local` | Phase 3 — writes the same schema for ad-hoc handovers that don't run through executor |
|
| 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` |
|
| Refresher (touch only) | `hooks/scripts/pre-compact-flush.mjs` | Updates `updated_at` only; never creates the file; never changes `status` or any owned field; only acts when `status` is `in_progress` or `partial` |
|
||||||
| Consumer | `/ultracontinue-local` | Phase 2 — reads, validates, narrates a 3-line summary, then begins executing the next session |
|
| Consumer | `/trekcontinue` | Phase 2 — reads, validates, narrates a 3-line summary, then begins executing the next session |
|
||||||
|
|
||||||
**Stale-file principle (SC-5):** When `status === 'completed'`, the state file and its sibling `NEXT-SESSION-PROMPT.local.md` represent finished work and SHOULD be removed. Removal is **operator-invoked** via `/ultracontinue-local --cleanup --confirm <project-dir>`; the plugin does NOT auto-cleanup. Stale state is actively harmful — it can mislead a fresh `/ultracontinue` into resuming a project that's already shipped. The `--cleanup` gate refuses to act unless `validateSessionState({...}).valid === true && parsed.status === 'completed'`. There is no force flag.
|
**Stale-file principle (SC-5):** When `status === 'completed'`, the state file and its sibling `NEXT-SESSION-PROMPT.local.md` represent finished work and SHOULD be removed. Removal is **operator-invoked** via `/trekcontinue --cleanup --confirm <project-dir>`; the plugin does NOT auto-cleanup. Stale state is actively harmful — it can mislead a fresh `/trekcontinue` into resuming a project that's already shipped. The `--cleanup` gate refuses to act unless `validateSessionState({...}).valid === true && parsed.status === 'completed'`. There is no force flag.
|
||||||
|
|
||||||
**Frontmatter contract for `NEXT-SESSION-PROMPT.local.md`:** Producers MUST write a YAML frontmatter block on the prompt file with at minimum:
|
**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.
|
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 |
|
| 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+) |
|
| 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 |
|
| 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.
|
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.
|
||||||
|
|
|
||||||
|
|
@ -2,11 +2,11 @@
|
||||||
|
|
||||||
**Status:** Exploratory brief — findings + options, not a decision
|
**Status:** Exploratory brief — findings + options, not a decision
|
||||||
**Date:** 2026-04-19
|
**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
|
## 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
|
design principle is Context Engineering — the main context should
|
||||||
**orchestrate**, subagents should **execute**. In practice, the exploration
|
**orchestrate**, subagents should **execute**. In practice, the exploration
|
||||||
phases do delegate aggressively, but the **synthesis and writing phases
|
phases do delegate aggressively, but the **synthesis and writing phases
|
||||||
|
|
@ -21,11 +21,11 @@ Agent-spawn density per command (nominal):
|
||||||
|
|
||||||
| Command | Agents spawned |
|
| Command | Agents spawned |
|
||||||
|--------------------------|-------------------------------------------------------------------|
|
|--------------------------|-------------------------------------------------------------------|
|
||||||
| ultraresearch-local | ~9–14 (5 local + 4 external + 1 bridge + up to 2 follow-ups) |
|
| trekresearch | ~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) |
|
| trekplan | ~10 (6 initial + conditional research-scout + up to 3 deep-dives) |
|
||||||
| ultrabrief-local | 1–3 (brief-reviewer per iteration, max 3) |
|
| trekbrief | 1–3 (brief-reviewer per iteration, max 3) |
|
||||||
| ultraexecute-local | 0 (explicit no-agent rule) |
|
| trekexecute | 0 (explicit no-agent rule) |
|
||||||
| ultra-skill-author-local | 3 (concept-extractor → skill-drafter → ip-hygiene-checker) |
|
| voyage-skill-author-local | 3 (concept-extractor → skill-drafter → ip-hygiene-checker) |
|
||||||
|
|
||||||
This part is healthy.
|
This part is healthy.
|
||||||
|
|
||||||
|
|
@ -33,27 +33,27 @@ This part is healthy.
|
||||||
|
|
||||||
The main context does the heavy cognitive work after swarm completion:
|
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
|
"Read all agent results carefully" + "Build a mental model of the codebase
|
||||||
architecture" + "Catalog reusable code" + "Integrate research findings".
|
architecture" + "Catalog reusable code" + "Integrate research findings".
|
||||||
This forces 6–10 agent outputs to remain resident in main context simultaneously.
|
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
|
Main context writes the entire plan.md from scratch, including all required
|
||||||
sections, quality standards, and file-path validation.
|
sections, quality standards, and file-path validation.
|
||||||
|
|
||||||
- **`commands/ultraresearch-local.md:302–323` (Phase 6 Triangulation):**
|
- **`commands/trekresearch.md:302–323` (Phase 6 Triangulation):**
|
||||||
Explicitly labelled "the KEY phase that makes ultraresearch more than
|
Explicitly labelled "the KEY phase that makes trekresearch more than
|
||||||
aggregation". Dimension-by-dimension comparison of local vs external
|
aggregation". Dimension-by-dimension comparison of local vs external
|
||||||
findings, contradiction flagging, confidence rating — all inline.
|
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.
|
Writes the research brief inline using the template.
|
||||||
|
|
||||||
### 3. Root cause — v2.4.0 foreground migration
|
### 3. Root cause — v2.4.0 foreground migration
|
||||||
|
|
||||||
Each command carries a `> **Why foreground?**` block
|
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
|
background orchestrators were removed because agents spawned from background
|
||||||
orchestrators silently degraded. The swarm-spawn logic was lifted into the
|
orchestrators silently degraded. The swarm-spawn logic was lifted into the
|
||||||
main context — but so was the synthesis logic the orchestrators used to
|
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 |
|
| # | Intervention | Target phase | Rough saving |
|
||||||
|---|---------------------------------------------------------------------|-------------------------------------|--------------|
|
|---|---------------------------------------------------------------------|-------------------------------------|--------------|
|
||||||
| 1 | `synthesis-agent` — digests all exploration outputs into findings + reuse catalog + gaps | ultraplan Phase 7 | 40–50% |
|
| 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 | ultraplan Phase 8 | part of #1 |
|
| 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 | ultraresearch Phase 6 | 25–30% |
|
| 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 | ultraresearch Phase 7 | part of #3 |
|
| 4 | `research-brief-writer` — writes research brief from triangulation output | trekresearch Phase 7 | part of #3 |
|
||||||
|
|
||||||
## Tradeoffs (important)
|
## Tradeoffs (important)
|
||||||
|
|
||||||
|
|
@ -98,7 +98,7 @@ are rough estimates based on the size of the phase bodies — not measured.
|
||||||
## Recommendation (tentative)
|
## Recommendation (tentative)
|
||||||
|
|
||||||
If only one change is made, **intervention #1 (synthesis-agent for
|
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
|
(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
|
findings document — is small enough to keep resident for Phase 8 planning
|
||||||
and Phase 9 review.
|
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
|
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
|
savings estimates above can be replaced with real numbers before
|
||||||
committing to changes?
|
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
|
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
|
might either help (isolated, more controllable) or hurt (another layer
|
||||||
where drift can happen) the schema-drift problem.
|
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
|
## Out of scope for this brief
|
||||||
|
|
||||||
- Implementation details of the new agents
|
- Implementation details of the new agents
|
||||||
- Changes to ultraexecute-local (no-agent by design)
|
- Changes to trekexecute (no-agent by design)
|
||||||
- Changes to ultrabrief-local Phase 3 interview (must be inline to drive
|
- Changes to trekbrief Phase 3 interview (must be inline to drive
|
||||||
user dialogue)
|
user dialogue)
|
||||||
|
|
|
||||||
|
|
@ -3,7 +3,7 @@
|
||||||
| Field | Value |
|
| Field | Value |
|
||||||
|-------|-------|
|
|-------|-------|
|
||||||
| Last regenerated | 2026-05-01 |
|
| Last regenerated | 2026-05-01 |
|
||||||
| ultraplan-local version | 3.1.0 |
|
| trekplan version | 3.1.0 |
|
||||||
| Claude Code version | ≥ 2.1.105 (PreCompact-hook) |
|
| Claude Code version | ≥ 2.1.105 (PreCompact-hook) |
|
||||||
| Source brief author | Hand-calibrated example, not LLM-generated |
|
| Source brief author | Hand-calibrated example, not LLM-generated |
|
||||||
| Plan author | Hand-calibrated to demonstrate plan_version 1.7 schema + manifest YAML |
|
| 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
|
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.
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
---
|
---
|
||||||
type: ultrabrief
|
type: trekbrief
|
||||||
brief_version: 1.0
|
brief_version: 1.0
|
||||||
slug: add-verbose-flag
|
slug: add-verbose-flag
|
||||||
task: Add a --verbose flag to the small-auth CLI parser
|
task: Add a --verbose flag to the small-auth CLI parser
|
||||||
|
|
|
||||||
|
|
@ -4,7 +4,7 @@ plan_version: 1.7
|
||||||
|
|
||||||
> **Plan quality: A** (92/100) — APPROVE
|
> **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
|
## Context
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
---
|
---
|
||||||
type: ultraresearch-brief
|
type: trekresearch-brief
|
||||||
research_version: 1.0
|
research_version: 1.0
|
||||||
question: How does small-auth currently parse arguments and where should --verbose hook in?
|
question: How does small-auth currently parse arguments and where should --verbose hook in?
|
||||||
confidence: 0.85
|
confidence: 0.85
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
|
|
||||||
| Field | Value |
|
| Field | Value |
|
||||||
|-------|-------|
|
|-------|-------|
|
||||||
| Calibrated against | ultraplan-local v3.4.1 |
|
| Calibrated against | trekplan v3.4.1 |
|
||||||
| Last regenerated | 2026-05-04 (B3 session) |
|
| Last regenerated | 2026-05-04 (B3 session) |
|
||||||
| Source brief author | Hand-authored by operator (B1 session, 2026-05-04) |
|
| Source brief author | Hand-authored by operator (B1 session, 2026-05-04) |
|
||||||
| Baseline author | B2 session, 2026-05-04 (commit `c8146c1`) |
|
| Baseline author | B2 session, 2026-05-04 (commit `c8146c1`) |
|
||||||
|
|
@ -10,7 +10,7 @@
|
||||||
|
|
||||||
## What this example demonstrates
|
## 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,
|
Unlike `examples/01-add-verbose-flag/` (which ships a frozen brief, plan,
|
||||||
and research as artifacts but no executable code), this example ships a
|
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
|
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:
|
The fixture's purpose is twofold:
|
||||||
|
|
||||||
1. **End-to-end pipeline validation:** running `/ultraresearch-local`,
|
1. **End-to-end pipeline validation:** running `/trekresearch`,
|
||||||
`/ultraplan-local`, and `/ultraexecute-local` against `brief.md` must
|
`/trekplan`, and `/trekexecute` against `brief.md` must
|
||||||
produce green commits that satisfy all 10 brief Success Criteria. This
|
produce green commits that satisfy all 10 brief Success Criteria. This
|
||||||
is the controlled environment used to verify pipeline correctness on
|
is the controlled environment used to verify pipeline correctness on
|
||||||
release-validation passes (see "Regeneration triggers" below).
|
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
|
Each phase produced an artifact in
|
||||||
`.claude/projects/2026-05-04-examples-02-real-cli/`.
|
`.claude/projects/2026-05-04-examples-02-real-cli/`.
|
||||||
|
|
||||||
### `/ultraresearch-local`
|
### `/trekresearch`
|
||||||
|
|
||||||
**Outcome: skipped (intentionally).**
|
**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
|
Following the prompt's guidance ("Ikke kjør Gemini-bridge eller
|
||||||
community-researcher for trivielle Node-stdlib-spørsmål"), the swarm was
|
community-researcher for trivielle Node-stdlib-spørsmål"), the swarm was
|
||||||
not invoked. No research file was written; `research/` directory does not
|
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
|
research files but do not require them — the missing directory is fine
|
||||||
per the soft-mode `research-validator` contract.
|
per the soft-mode `research-validator` contract.
|
||||||
|
|
||||||
### `/ultraplan-local`
|
### `/trekplan`
|
||||||
|
|
||||||
**Outcome: plan.md with 4 steps; plan-validator strict PASS;
|
**Outcome: plan.md with 4 steps; plan-validator strict PASS;
|
||||||
plan-critic 0 BLOCKER (4 MAJOR fixed in revision); scope-guardian
|
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
|
`-r short form`, `invalid regex`) so the verifier confirms substantive
|
||||||
changes, not just file modifications.
|
changes, not just file modifications.
|
||||||
|
|
||||||
### `/ultraexecute-local`
|
### `/trekexecute`
|
||||||
|
|
||||||
**Outcome: 4 commits, all green, all `verify_passed: true`.**
|
**Outcome: 4 commits, all green, all `verify_passed: true`.**
|
||||||
|
|
||||||
|
|
@ -180,12 +180,12 @@ Constraint compliance:
|
||||||
## How to re-run this example
|
## How to re-run this example
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd /path/to/ultraplan-local
|
cd /path/to/trekplan
|
||||||
|
|
||||||
# 1. Re-run the pipeline against the existing brief
|
# 1. Re-run the pipeline against the existing brief
|
||||||
# (research is skipped — research_topics: 0)
|
# (research is skipped — research_topics: 0)
|
||||||
/ultraplan-local --project .claude/projects/2026-05-04-examples-02-real-cli
|
/trekplan --project .claude/projects/2026-05-04-examples-02-real-cli
|
||||||
/ultraexecute-local --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)
|
# 2. Verify all 10 Success Criteria from brief.md hold (commands above)
|
||||||
node --test examples/02-real-cli/tests/tally.test.mjs # 14 pass
|
node --test examples/02-real-cli/tests/tally.test.mjs # 14 pass
|
||||||
|
|
@ -209,7 +209,7 @@ triggers" below).
|
||||||
|
|
||||||
When to re-run this example:
|
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
|
- `plan_version` schema bump
|
||||||
- Manifest YAML required-key additions
|
- Manifest YAML required-key additions
|
||||||
- `progress.json` schema bump
|
- `progress.json` schema bump
|
||||||
|
|
|
||||||
|
|
@ -1,13 +1,13 @@
|
||||||
# Examples
|
# 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
|
realistic tasks. Each example shows the four artifacts a project
|
||||||
directory contains after a full run:
|
directory contains after a full run:
|
||||||
|
|
||||||
- `brief.md` — task brief from `/ultrabrief-local`
|
- `brief.md` — task brief from `/trekbrief`
|
||||||
- `research/*.md` — research briefs from `/ultraresearch-local`
|
- `research/*.md` — research briefs from `/trekresearch`
|
||||||
- `plan.md` — implementation plan from `/ultraplan-local`
|
- `plan.md` — implementation plan from `/trekplan`
|
||||||
- `progress.json` — execution log from `/ultraexecute-local`
|
- `progress.json` — execution log from `/trekexecute`
|
||||||
|
|
||||||
These are **hand-calibrated**, not LLM-generated. The point is to give
|
These are **hand-calibrated**, not LLM-generated. The point is to give
|
||||||
a fork-er a deterministic reference — what the artifacts look like
|
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
|
```bash
|
||||||
mkdir -p .claude/projects/2026-05-01-my-task
|
mkdir -p .claude/projects/2026-05-01-my-task
|
||||||
/ultrabrief-local
|
/trekbrief
|
||||||
/ultraresearch-local --project .claude/projects/2026-05-01-my-task
|
/trekresearch --project .claude/projects/2026-05-01-my-task
|
||||||
/ultraplan-local --project .claude/projects/2026-05-01-my-task
|
/trekplan --project .claude/projects/2026-05-01-my-task
|
||||||
/ultraexecute-local --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.
|
The artifacts in each example mirror that flow.
|
||||||
|
|
|
||||||
|
|
@ -3,11 +3,11 @@
|
||||||
//
|
//
|
||||||
// Captures duration_ms from PostToolUse payload for Bash tool calls and
|
// Captures duration_ms from PostToolUse payload for Bash tool calls and
|
||||||
// appends a structured stats line to ${CLAUDE_PLUGIN_DATA}/trekexecute-stats.jsonl
|
// 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
|
// Detection: only fires when the tool input matches the verify/checkpoint
|
||||||
// pattern of an ultraexecute step (i.e., the command was issued from inside
|
// pattern of an trekexecute step (i.e., the command was issued from inside
|
||||||
// /ultraexecute-local). We err on the side of "log everything in plugin
|
// /trekexecute). We err on the side of "log everything in plugin
|
||||||
// scope" — duration data is cheap and the alternative is missing real
|
// scope" — duration data is cheap and the alternative is missing real
|
||||||
// per-step timings.
|
// per-step timings.
|
||||||
//
|
//
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
// Hook: post-compact-flush.mjs
|
// Hook: post-compact-flush.mjs
|
||||||
// Event: PostCompact (Claude Code v2.1.105+)
|
// Event: PostCompact (Claude Code v2.1.105+)
|
||||||
// Purpose: Re-inject .session-state.local.json after compaction so
|
// 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
|
// session-state and the model has Handover 7 context immediately
|
||||||
// after a context-compaction event.
|
// after a context-compaction event.
|
||||||
//
|
//
|
||||||
|
|
|
||||||
|
|
@ -2,12 +2,12 @@
|
||||||
// Hook: pre-compact-flush.mjs
|
// Hook: pre-compact-flush.mjs
|
||||||
// Event: PreCompact (Claude Code v2.1.105+)
|
// Event: PreCompact (Claude Code v2.1.105+)
|
||||||
// Purpose: Flush progress.json drift before context compaction so
|
// 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
|
// 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
|
// 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.
|
// even after a compaction event mid-run.
|
||||||
//
|
//
|
||||||
// Behavior:
|
// Behavior:
|
||||||
|
|
|
||||||
|
|
@ -1,11 +1,11 @@
|
||||||
#!/usr/bin/env node
|
#!/usr/bin/env node
|
||||||
// session-title.mjs — UserPromptSubmit hook (CC v2.1.94+)
|
// 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
|
// so multi-session headless runs are easy to identify in process lists and
|
||||||
// session pickers.
|
// session pickers.
|
||||||
//
|
//
|
||||||
// Title format: ultra:<command>:<slug>
|
// Title format: voyage:<command>:<slug>
|
||||||
// - <command> ∈ {brief, research, plan, execute, review}
|
// - <command> ∈ {brief, research, plan, execute, review}
|
||||||
// - <slug> ∈ first 30 chars of project slug, or "ad-hoc" when no
|
// - <slug> ∈ first 30 chars of project slug, or "ad-hoc" when no
|
||||||
// --project / --brief context is detected
|
// --project / --brief context is detected
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
// lib/parsers/arg-parser.mjs
|
// 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
|
// 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.
|
// produces an `unknown_flags` array but does not error — the caller decides.
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
// lib/parsers/finding-id.mjs
|
// 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.
|
// id = sha1(file:line:rule_key) → 40-char hex.
|
||||||
// Same input always produces same output (determinism floor SC4).
|
// Same input always produces same output (determinism floor SC4).
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
// lib/review/plan-review-dedup.mjs
|
// 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
|
// merges plan-critic + scope-guardian findings into a single deduplicated
|
||||||
// stream, preserving provenance (which agent originally raised each finding).
|
// stream, preserving provenance (which agent originally raised each finding).
|
||||||
//
|
//
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
// lib/review/rule-catalogue.mjs
|
// 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).
|
// 12 rule keys, 4-tier severity (matches brief contract).
|
||||||
// llm-security 5-tier alignment is a v1.1 candidate.
|
// llm-security 5-tier alignment is a v1.1 candidate.
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
// Summarizes trekexecute-stats.jsonl: total events, percentile wall times,
|
// Summarizes trekexecute-stats.jsonl: total events, percentile wall times,
|
||||||
// time range. Companion to event-emit.mjs (which produces the jsonl).
|
// 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
|
// interpreting Q3 experiment numbers (5+ weeks of accumulated data on the
|
||||||
// operator's machine as of 2026-05-04).
|
// operator's machine as of 2026-05-04).
|
||||||
//
|
//
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
// lib/util/autonomy-gate.mjs
|
// 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).
|
// (plan-v2 Step 4 — drives the --gates flag).
|
||||||
//
|
//
|
||||||
// States:
|
// States:
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
// lib/util/cleanup.mjs
|
// lib/util/cleanup.mjs
|
||||||
// Bug 4 — operator-invoked cleanup of completed-project state files.
|
// 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
|
// stale .session-state.local.json + NEXT-SESSION-PROMPT.local.md across many
|
||||||
// projects accumulate over time. This util removes them safely once the
|
// projects accumulate over time. This util removes them safely once the
|
||||||
// project is fully done (status === 'completed' as seen by validateSessionState).
|
// 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: [].
|
// - Idempotent: re-running on a partially-cleaned dir succeeds with deleted: [].
|
||||||
// - Refuses dryRun: false without an explicit confirm: true (prevents accidents).
|
// - Refuses dryRun: false without an explicit confirm: true (prevents accidents).
|
||||||
// - ENOENT counts as "already absent" — never an error.
|
// - 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 { existsSync, unlinkSync } from 'node:fs';
|
||||||
import { join } from 'node:path';
|
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 {string} projectDir - absolute or cwd-relative path to the project directory
|
||||||
* @param {{dryRun?: boolean, confirm?: boolean}} [opts]
|
* @param {{dryRun?: boolean, confirm?: boolean}} [opts]
|
||||||
|
|
@ -68,7 +68,7 @@ export function cleanupProject(projectDir, opts = {}) {
|
||||||
return fail(issue(
|
return fail(issue(
|
||||||
'CLEANUP_NOT_COMPLETED',
|
'CLEANUP_NOT_COMPLETED',
|
||||||
`Refused: status is "${validation.parsed.status}", 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.',
|
||||||
));
|
));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
// lib/validators/brief-validator.mjs
|
// lib/validators/brief-validator.mjs
|
||||||
// Validate ultrabrief frontmatter + body invariants.
|
// Validate trekbrief frontmatter + body invariants.
|
||||||
|
|
||||||
import { readFileSync, existsSync } from 'node:fs';
|
import { readFileSync, existsSync } from 'node:fs';
|
||||||
import { parseDocument } from '../util/frontmatter.mjs';
|
import { parseDocument } from '../util/frontmatter.mjs';
|
||||||
|
|
|
||||||
|
|
@ -3,7 +3,7 @@
|
||||||
//
|
//
|
||||||
// Producers (trekexecute Phase 8/2.55/4, trekendsession Phase 3) MUST write
|
// Producers (trekexecute Phase 8/2.55/4, trekendsession Phase 3) MUST write
|
||||||
// `produced_by:` and `produced_at:` (ISO-8601) frontmatter.
|
// `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.
|
// when producers disagree on a non-stale pair.
|
||||||
//
|
//
|
||||||
// Schema is forward-compatible: unknown frontmatter keys are tolerated.
|
// Schema is forward-compatible: unknown frontmatter keys are tolerated.
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
// lib/validators/review-validator.mjs
|
// 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.
|
// 3-layer pattern (Content → File → CLI shim) mirroring brief-validator.
|
||||||
|
|
||||||
import { readFileSync, existsSync } from 'node:fs';
|
import { readFileSync, existsSync } from 'node:fs';
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
// lib/validators/session-state-validator.mjs
|
// 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).
|
// Schema v1 documented in docs/HANDOVER-CONTRACTS.md (Handover 7).
|
||||||
|
|
||||||
import { readFileSync, existsSync } from 'node:fs';
|
import { readFileSync, existsSync } from 'node:fs';
|
||||||
|
|
@ -18,8 +18,8 @@ export const SESSION_STATE_REQUIRED_TOP = [
|
||||||
// session is not resumable. Unknown statuses fail.
|
// session is not resumable. Unknown statuses fail.
|
||||||
export const SESSION_STATE_VALID_STATUSES = ['in_progress', 'partial', 'failed', 'stopped', 'completed'];
|
export const SESSION_STATE_VALID_STATUSES = ['in_progress', 'partial', 'failed', 'stopped', 'completed'];
|
||||||
|
|
||||||
// Statuses that /ultracontinue can resume from. `completed` is intentionally
|
// Statuses that /trekcontinue can resume from. `completed` is intentionally
|
||||||
// excluded — running ultracontinue on a completed project should signal "no
|
// excluded — running trekcontinue on a completed project should signal "no
|
||||||
// further sessions to resume", not load stale context.
|
// further sessions to resume", not load stale context.
|
||||||
export const SESSION_STATE_RESUMABLE_STATUSES = ['in_progress', 'partial', 'failed', 'stopped'];
|
export const SESSION_STATE_RESUMABLE_STATUSES = ['in_progress', 'partial', 'failed', 'stopped'];
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -44,7 +44,7 @@ const ALLOWED_TOOLS = 'Read,Write,Edit,Bash,Glob,Grep';
|
||||||
const MODEL = 'sonnet';
|
const MODEL = 'sonnet';
|
||||||
|
|
||||||
// Sources for parent context build. Brief constraint: no secrets, no ~/, no
|
// 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):
|
// Calibration (empirical, CC v2.1.128 + Sonnet 4.6):
|
||||||
// Token-per-byte ratio varies from 0.38-0.90 depending on content type.
|
// Token-per-byte ratio varies from 0.38-0.90 depending on content type.
|
||||||
|
|
|
||||||
|
|
@ -7,7 +7,7 @@ for headless execution of decomposed sessions.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
#!/usr/bin/env bash
|
#!/usr/bin/env bash
|
||||||
# Headless launch script — generated by ultraplan-local
|
# Headless launch script — generated by trekplan
|
||||||
# Master plan: {plan_path}
|
# Master plan: {plan_path}
|
||||||
# Generated: {date}
|
# Generated: {date}
|
||||||
# Sessions: {total_sessions} ({parallel_count} parallel, {sequential_count} sequential)
|
# Sessions: {total_sessions} ({parallel_count} parallel, {sequential_count} sequential)
|
||||||
|
|
@ -24,7 +24,7 @@ WORKTREE_BASE="{session_dir}/worktrees"
|
||||||
mkdir -p "$LOG_DIR" "$WORKTREE_BASE"
|
mkdir -p "$LOG_DIR" "$WORKTREE_BASE"
|
||||||
|
|
||||||
# Disable git's optional locks during parallel worktree ops (research/02 R2;
|
# 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
|
export GIT_OPTIONAL_LOCKS=0
|
||||||
|
|
||||||
# Per-child guardrails (operator may override via env). Match Phase 2.6
|
# 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
|
||||||
fi
|
fi
|
||||||
|
|
||||||
echo "=== Ultraplan Headless Execution (Worktree-Isolated) ==="
|
echo "=== Voyage Headless Execution (Worktree-Isolated) ==="
|
||||||
echo "Plan: {plan_path}"
|
echo "Plan: {plan_path}"
|
||||||
echo "Sessions: {total_sessions}"
|
echo "Sessions: {total_sessions}"
|
||||||
echo "Repo root: $REPO_ROOT"
|
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). }
|
{# 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 push origin "trek/{slug}/session-{n}" 2>/dev/null || true
|
||||||
git merge --no-ff "trek/{slug}/session-{n}" \
|
git merge --no-ff "trek/{slug}/session-{n}" \
|
||||||
-m "merge: ultraplan session {n} — {title}"
|
-m "merge: trekplan session {n} — {title}"
|
||||||
if [ $? -ne 0 ]; then
|
if [ $? -ne 0 ]; then
|
||||||
echo "MERGE CONFLICT: session {n}. Conflicting files:"
|
echo "MERGE CONFLICT: session {n}. Conflicting files:"
|
||||||
git diff --name-only --diff-filter=U
|
git diff --name-only --diff-filter=U
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
<!--
|
<!--
|
||||||
Optional YAML frontmatter — include ONLY when the plan was generated from a
|
Optional YAML frontmatter — include ONLY when the plan was generated from a
|
||||||
`type: ultrareview` input (Handover 6). Lists the 40-char hex IDs of the
|
`type: trekreview` input (Handover 6). Lists the 40-char hex IDs of the
|
||||||
BLOCKER + MAJOR findings consumed from `review.md`. Use block-style YAML;
|
BLOCKER + MAJOR findings consumed from `review.md`. Use block-style YAML;
|
||||||
the frontmatter parser does not support flow-style arrays.
|
the frontmatter parser does not support flow-style arrays.
|
||||||
|
|
||||||
|
|
@ -18,7 +18,7 @@ source_findings:
|
||||||
|
|
||||||
> **Plan quality: {grade}** ({score}/100) — {APPROVE | APPROVE_WITH_NOTES | REVISE | REPLAN}
|
> **Plan quality: {grade}** ({score}/100) — {APPROVE | APPROVE_WITH_NOTES | REVISE | REPLAN}
|
||||||
>
|
>
|
||||||
> Generated by ultraplan-local v{version} on {YYYY-MM-DD} — `plan_version: 1.7`
|
> Generated by trekplan v{version} on {YYYY-MM-DD} — `plan_version: 1.7`
|
||||||
|
|
||||||
## Context
|
## Context
|
||||||
|
|
||||||
|
|
@ -116,7 +116,7 @@ concrete command (e.g., run the app, check output, curl an endpoint).*
|
||||||
### Manifest — objective completion predicate
|
### Manifest — objective completion predicate
|
||||||
|
|
||||||
Every step MUST have a Manifest block. This is the machine-checkable contract
|
Every step MUST have a Manifest block. This is the machine-checkable contract
|
||||||
that ultraexecute-local verifies after the Verify command passes. A step is
|
that trekexecute verifies after the Verify command passes. A step is
|
||||||
not considered complete until its manifest verifies — regardless of Verify
|
not considered complete until its manifest verifies — regardless of Verify
|
||||||
command exit code.
|
command exit code.
|
||||||
|
|
||||||
|
|
@ -182,7 +182,7 @@ before execution.*
|
||||||
## Verification
|
## Verification
|
||||||
|
|
||||||
*Per-step manifest verification runs automatically during execution (every
|
*Per-step manifest verification runs automatically during execution (every
|
||||||
step's Manifest block is objectively checked by ultraexecute-local before the
|
step's Manifest block is objectively checked by trekexecute before the
|
||||||
step is marked passed). This section is for end-to-end integration checks
|
step is marked passed). This section is for end-to-end integration checks
|
||||||
that cross step boundaries — complete workflows, system-level behavior.*
|
that cross step boundaries — complete workflows, system-level behavior.*
|
||||||
|
|
||||||
|
|
@ -198,7 +198,7 @@ that cross step boundaries — complete workflows, system-level behavior.*
|
||||||
## Execution Strategy
|
## Execution Strategy
|
||||||
|
|
||||||
*Include this section when the plan has more than 5 implementation steps.
|
*Include this section when the plan has more than 5 implementation steps.
|
||||||
Omit for small plans (≤ 5 steps) — ultraexecute will run them sequentially
|
Omit for small plans (≤ 5 steps) — trekexecute will run them sequentially
|
||||||
in a single session.*
|
in a single session.*
|
||||||
|
|
||||||
*The execution strategy groups steps into sessions and organizes sessions
|
*The execution strategy groups steps into sessions and organizes sessions
|
||||||
|
|
|
||||||
|
|
@ -11,7 +11,7 @@ external_agents_used: [{list}]
|
||||||
|
|
||||||
# {Research Question Title}
|
# {Research Question Title}
|
||||||
|
|
||||||
> Generated by ultraresearch-local v{version} on {YYYY-MM-DD}
|
> Generated by trekresearch v{version} on {YYYY-MM-DD}
|
||||||
|
|
||||||
## Research Question
|
## Research Question
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -23,7 +23,7 @@ the purpose and make judgment calls.}
|
||||||
## Session Manifest
|
## Session Manifest
|
||||||
|
|
||||||
Machine-readable aggregate of all step manifests in this session. Used by
|
Machine-readable aggregate of all step manifests in this session. Used by
|
||||||
ultraexecute-local for independent Phase 7.5 audit.
|
trekexecute for independent Phase 7.5 audit.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
session_manifest:
|
session_manifest:
|
||||||
|
|
@ -69,7 +69,7 @@ session_manifest:
|
||||||
```
|
```
|
||||||
|
|
||||||
*Step 0 runs in the same sandbox as all real work. If it exits 77,
|
*Step 0 runs in the same sandbox as all real work. If it exits 77,
|
||||||
ultraexecute-local marks the session `blocked` and does NOT proceed. This
|
trekexecute marks the session `blocked` and does NOT proceed. This
|
||||||
catches the fail-late push-denial mode observed in Wave 1.*
|
catches the fail-late push-denial mode observed in Wave 1.*
|
||||||
|
|
||||||
*Escape hatch:* set `TREKEXECUTE_SKIP_PREFLIGHT=1` in the environment to
|
*Escape hatch:* set `TREKEXECUTE_SKIP_PREFLIGHT=1` in the environment to
|
||||||
|
|
@ -146,10 +146,10 @@ introduced. This section bridges sessions — it's the "baton" in a relay race.}
|
||||||
## Recovery Metadata
|
## Recovery Metadata
|
||||||
|
|
||||||
*This section is populated only when this session spec was generated by the
|
*This section is populated only when this session spec was generated by the
|
||||||
ultraexecute-local Phase 7.6 recovery dispatcher. Omit for normal sessions.*
|
trekexecute Phase 7.6 recovery dispatcher. Omit for normal sessions.*
|
||||||
|
|
||||||
- **Recovery of:** `{original session spec path}`
|
- **Recovery of:** `{original session spec path}`
|
||||||
- **Recovery depth:** {1 | 2}
|
- **Recovery depth:** {1 | 2}
|
||||||
- **Missing steps (reason for recovery):** {step numbers + drift summary}
|
- **Missing steps (reason for recovery):** {step numbers + drift summary}
|
||||||
- **Entry condition override:** {e.g., "previous partial session committed at {sha}"}
|
- **Entry condition override:** {e.g., "previous partial session committed at {sha}"}
|
||||||
- **Parent progress file:** `{path to .ultraexecute-progress-*.json}`
|
- **Parent progress file:** `{path to .trekexecute-progress-*.json}`
|
||||||
|
|
|
||||||
|
|
@ -61,4 +61,4 @@ without answers.
|
||||||
|
|
||||||
- **Created:** {YYYY-MM-DD}
|
- **Created:** {YYYY-MM-DD}
|
||||||
- **Mode:** {interview | manual}
|
- **Mode:** {interview | manual}
|
||||||
- **Source:** {ultraplan interview | user-provided}
|
- **Source:** {trekplan interview | user-provided}
|
||||||
|
|
|
||||||
|
|
@ -14,8 +14,8 @@ source: {interview | manual}
|
||||||
|
|
||||||
# Task: {title}
|
# Task: {title}
|
||||||
|
|
||||||
> Generated by `/ultrabrief-local` on {YYYY-MM-DD}.
|
> Generated by `/trekbrief` on {YYYY-MM-DD}.
|
||||||
> This brief is the contract between requirements and planning. `/ultraplan-local`
|
> This brief is the contract between requirements and planning. `/trekplan`
|
||||||
> reads it to produce the implementation plan. Every decision in the plan must
|
> reads it to produce the implementation plan. Every decision in the plan must
|
||||||
> trace back to content in this brief.
|
> trace back to content in this brief.
|
||||||
|
|
||||||
|
|
@ -81,9 +81,9 @@ Do NOT write vague criteria:
|
||||||
|
|
||||||
## Research Plan
|
## Research Plan
|
||||||
|
|
||||||
*Explicit research topics that must be answered before `/ultraplan-local` can
|
*Explicit research topics that must be answered before `/trekplan` can
|
||||||
produce a high-confidence plan. Each topic is phrased as a research question ready
|
produce a high-confidence plan. Each topic is phrased as a research question ready
|
||||||
to feed into `/ultraresearch-local`. Topics may be empty (N=0) for trivial tasks
|
to feed into `/trekresearch`. Topics may be empty (N=0) for trivial tasks
|
||||||
where the codebase alone is sufficient context.*
|
where the codebase alone is sufficient context.*
|
||||||
|
|
||||||
{If research_topics = 0, write a single line: "No external research needed —
|
{If research_topics = 0, write a single line: "No external research needed —
|
||||||
|
|
@ -93,9 +93,9 @@ the codebase and this brief contain sufficient context for planning."}
|
||||||
|
|
||||||
- **Why this matters:** {How the plan depends on this answer. Which steps or
|
- **Why this matters:** {How the plan depends on this answer. Which steps or
|
||||||
decisions cannot be made confidently without it.}
|
decisions cannot be made confidently without it.}
|
||||||
- **Research question:** "{Exact question to feed to /ultraresearch-local.
|
- **Research question:** "{Exact question to feed to /trekresearch.
|
||||||
One sentence, ends in `?`.}"
|
One sentence, ends in `?`.}"
|
||||||
- **Suggested invocation:** `/ultraresearch-local --project {project_dir} --external "{question}"`
|
- **Suggested invocation:** `/trekresearch --project {project_dir} --external "{question}"`
|
||||||
- **Required for plan steps:** {which kinds of steps will consume this — e.g.,
|
- **Required for plan steps:** {which kinds of steps will consume this — e.g.,
|
||||||
"migration strategy", "library selection", "threat model"}
|
"migration strategy", "library selection", "threat model"}
|
||||||
- **Confidence needed:** {high | medium | low}
|
- **Confidence needed:** {high | medium | low}
|
||||||
|
|
@ -106,7 +106,7 @@ the codebase and this brief contain sufficient context for planning."}
|
||||||
|
|
||||||
- **Why this matters:** ...
|
- **Why this matters:** ...
|
||||||
- **Research question:** "..."
|
- **Research question:** "..."
|
||||||
- **Suggested invocation:** `/ultraresearch-local --project {project_dir} ...`
|
- **Suggested invocation:** `/trekresearch --project {project_dir} ...`
|
||||||
- **Required for plan steps:** ...
|
- **Required for plan steps:** ...
|
||||||
- **Confidence needed:** ...
|
- **Confidence needed:** ...
|
||||||
- **Estimated cost:** ...
|
- **Estimated cost:** ...
|
||||||
|
|
@ -133,7 +133,7 @@ failures.*
|
||||||
- **Created:** {YYYY-MM-DD}
|
- **Created:** {YYYY-MM-DD}
|
||||||
- **Interview turns:** {N}
|
- **Interview turns:** {N}
|
||||||
- **Auto-research opted in:** {yes | no}
|
- **Auto-research opted in:** {yes | no}
|
||||||
- **Source:** {ultrabrief interview | manual}
|
- **Source:** {trekbrief interview | manual}
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -143,15 +143,15 @@ Manual (default):
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Run each research topic (order does not matter):
|
# Run each research topic (order does not matter):
|
||||||
/ultraresearch-local --project {project_dir} --external "{Topic 1 question}"
|
/trekresearch --project {project_dir} --external "{Topic 1 question}"
|
||||||
/ultraresearch-local --project {project_dir} --external "{Topic 2 question}"
|
/trekresearch --project {project_dir} --external "{Topic 2 question}"
|
||||||
|
|
||||||
# Then plan:
|
# Then plan:
|
||||||
/ultraplan-local --project {project_dir}
|
/trekplan --project {project_dir}
|
||||||
|
|
||||||
# Then execute:
|
# Then execute:
|
||||||
/ultraexecute-local --project {project_dir}
|
/trekexecute --project {project_dir}
|
||||||
```
|
```
|
||||||
|
|
||||||
Auto (opt-in during `/ultrabrief-local`): research and planning run
|
Auto (opt-in during `/trekbrief`): research and planning run
|
||||||
automatically; only execution is manual.
|
automatically; only execution is manual.
|
||||||
|
|
|
||||||
|
|
@ -42,7 +42,7 @@ should look at first.
|
||||||
- file: lib/foo.mjs
|
- file: lib/foo.mjs
|
||||||
- line: 42
|
- line: 42
|
||||||
- rule_key: BROKEN_SUCCESS_CRITERION
|
- rule_key: BROKEN_SUCCESS_CRITERION
|
||||||
- brief_ref: SC3 — "review.md is parseable as input to /ultraplan-local"
|
- brief_ref: SC3 — "review.md is parseable as input to /trekplan"
|
||||||
- title: Plan-validator rejects review.md when source_findings is flow-style
|
- title: Plan-validator rejects review.md when source_findings is flow-style
|
||||||
- detail: The validator at lib/validators/plan-validator.mjs:N reads
|
- detail: The validator at lib/validators/plan-validator.mjs:N reads
|
||||||
`source_findings` via parseDocument(), which does not support flow-style
|
`source_findings` via parseDocument(), which does not support flow-style
|
||||||
|
|
@ -101,7 +101,7 @@ should look at first.
|
||||||
- 1 MINOR → nice-to-have for v1.1
|
- 1 MINOR → nice-to-have for v1.1
|
||||||
- 1 SUGGESTION → log and move on
|
- 1 SUGGESTION → log and move on
|
||||||
|
|
||||||
If running `/ultraplan-local --brief review.md`, the planner will consume
|
If running `/trekplan --brief review.md`, the planner will consume
|
||||||
the BLOCKER + MAJOR findings as plan goals (their `recommended_action`
|
the BLOCKER + MAJOR findings as plan goals (their `recommended_action`
|
||||||
becomes the step intent). MINOR + SUGGESTION are skipped for v1.0
|
becomes the step intent). MINOR + SUGGESTION are skipped for v1.0
|
||||||
plan-input.
|
plan-input.
|
||||||
|
|
|
||||||
|
|
@ -1,8 +1,8 @@
|
||||||
// tests/commands/ultracontinue.test.mjs
|
// tests/commands/trekcontinue.test.mjs
|
||||||
// Regression tests for /ultracontinue-local (commands/ultracontinue-local.md).
|
// Regression tests for /trekcontinue (commands/trekcontinue.md).
|
||||||
//
|
//
|
||||||
// Steps 2 + 4 of the v3.4.1 hot-fix plan
|
// Steps 2 + 4 of the v3.4.1 hot-fix plan
|
||||||
// (project 2026-05-04-v3.3.1-ultracontinue-fixes).
|
// (project 2026-05-04-v3.3.1-trekcontinue-fixes).
|
||||||
//
|
//
|
||||||
// Pattern mix:
|
// Pattern mix:
|
||||||
// - Pattern B (tmp-dir, mkdtempSync + try/finally) — fixture builds
|
// - Pattern B (tmp-dir, mkdtempSync + try/finally) — fixture builds
|
||||||
|
|
@ -64,10 +64,10 @@ function completedState(updatedAtIso) {
|
||||||
// Step 2 — Bug 1 regression tests (SC-1, SC-2)
|
// Step 2 — Bug 1 regression tests (SC-1, SC-2)
|
||||||
// ---------------------------------------------------------------
|
// ---------------------------------------------------------------
|
||||||
|
|
||||||
test('ultracontinue Bug 1 — Phase 1 documents auto-discovery sort by Date.parse(updated_at) DESC', () => {
|
test('trekcontinue Bug 1 — Phase 1 documents auto-discovery sort by Date.parse(updated_at) DESC', () => {
|
||||||
// Fixture-builds two project dirs and verifies our chosen sort key
|
// Fixture-builds two project dirs and verifies our chosen sort key
|
||||||
// matches what Phase 1 prose documents.
|
// matches what Phase 1 prose documents.
|
||||||
const root = mkdtempSync(join(tmpdir(), 'ultracontinue-disc-'));
|
const root = mkdtempSync(join(tmpdir(), 'trekcontinue-disc-'));
|
||||||
try {
|
try {
|
||||||
const projectsRoot = join(root, '.claude', 'projects');
|
const projectsRoot = join(root, '.claude', 'projects');
|
||||||
mkdirSync(join(projectsRoot, '2026-05-04-fixture-a'), { recursive: true });
|
mkdirSync(join(projectsRoot, '2026-05-04-fixture-a'), { recursive: true });
|
||||||
|
|
@ -103,7 +103,7 @@ test('ultracontinue Bug 1 — Phase 1 documents auto-discovery sort by Date.pars
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultracontinue Bug 1 — Phase 0 dispatches via parsed flags, not substring contains', () => {
|
test('trekcontinue Bug 1 — Phase 0 dispatches via parsed flags, not substring contains', () => {
|
||||||
const phase0 = extractPhase(readCommand(), '## Phase 0 ');
|
const phase0 = extractPhase(readCommand(), '## Phase 0 ');
|
||||||
// Must NOT use the legacy "contains --help or -h" substring dispatch.
|
// Must NOT use the legacy "contains --help or -h" substring dispatch.
|
||||||
assert.doesNotMatch(
|
assert.doesNotMatch(
|
||||||
|
|
@ -121,7 +121,7 @@ test('ultracontinue Bug 1 — Phase 0 dispatches via parsed flags, not substring
|
||||||
);
|
);
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultracontinue Bug 1 — Phase 1 documents empty-args path explicitly to auto-discovery', () => {
|
test('trekcontinue Bug 1 — Phase 1 documents empty-args path explicitly to auto-discovery', () => {
|
||||||
const phase1 = extractPhase(readCommand(), '## Phase 1 ');
|
const phase1 = extractPhase(readCommand(), '## Phase 1 ');
|
||||||
// Some explicit text mentioning the empty / whitespace path so a future reader
|
// Some explicit text mentioning the empty / whitespace path so a future reader
|
||||||
// can't misread Phase 0 as "fall through to usage on empty".
|
// can't misread Phase 0 as "fall through to usage on empty".
|
||||||
|
|
@ -137,7 +137,7 @@ test('ultracontinue Bug 1 — Phase 1 documents empty-args path explicitly to au
|
||||||
);
|
);
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultracontinue Bug 1 sub — Phase 1 emits SC-2 diagnostic for .md positional arg', () => {
|
test('trekcontinue Bug 1 sub — Phase 1 emits SC-2 diagnostic for .md positional arg', () => {
|
||||||
const phase1 = extractPhase(readCommand(), '## Phase 1 ');
|
const phase1 = extractPhase(readCommand(), '## Phase 1 ');
|
||||||
// SC-2 verbatim diagnostic strings.
|
// SC-2 verbatim diagnostic strings.
|
||||||
assert.match(
|
assert.match(
|
||||||
|
|
@ -162,7 +162,7 @@ test('ultracontinue Bug 1 sub — Phase 1 emits SC-2 diagnostic for .md position
|
||||||
// Step 4 — Bug 2 regression tests (SC-3)
|
// Step 4 — Bug 2 regression tests (SC-3)
|
||||||
// ---------------------------------------------------------------
|
// ---------------------------------------------------------------
|
||||||
|
|
||||||
test('ultracontinue Bug 2 — pre-bash-executor ALLOWS resolved validator invocation', async () => {
|
test('trekcontinue Bug 2 — pre-bash-executor ALLOWS resolved validator invocation', async () => {
|
||||||
// (d-1) Sanity-check that the planned Phase 2 Bash form (validator
|
// (d-1) Sanity-check that the planned Phase 2 Bash form (validator
|
||||||
// invocation with a concrete absolute path) is not blocked by the
|
// invocation with a concrete absolute path) is not blocked by the
|
||||||
// marketplace pre-bash-executor hook chain.
|
// marketplace pre-bash-executor hook chain.
|
||||||
|
|
@ -175,7 +175,7 @@ test('ultracontinue Bug 2 — pre-bash-executor ALLOWS resolved validator invoca
|
||||||
// Step 8 — Bug 3 regression test (Phase 1.5 consistency wire-up)
|
// Step 8 — Bug 3 regression test (Phase 1.5 consistency wire-up)
|
||||||
// ---------------------------------------------------------------
|
// ---------------------------------------------------------------
|
||||||
|
|
||||||
test('ultracontinue Bug 3 — Phase 1.5 documents consistency check between Phase 1 and Phase 2', () => {
|
test('trekcontinue Bug 3 — Phase 1.5 documents consistency check between Phase 1 and Phase 2', () => {
|
||||||
const cmd = readCommand();
|
const cmd = readCommand();
|
||||||
// Phase 1.5 must exist literally in the prose between Phase 1 and Phase 2.
|
// Phase 1.5 must exist literally in the prose between Phase 1 and Phase 2.
|
||||||
assert.match(cmd, /## Phase 1\.5 /, 'Phase 1.5 header must be present');
|
assert.match(cmd, /## Phase 1\.5 /, 'Phase 1.5 header must be present');
|
||||||
|
|
@ -187,8 +187,8 @@ test('ultracontinue Bug 3 — Phase 1.5 documents consistency check between Phas
|
||||||
'Phase 1.5 must appear before Phase 2');
|
'Phase 1.5 must appear before Phase 2');
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultracontinue Bug 3 (e) — CLI consistency mode flags producer mismatch in JSON output', () => {
|
test('trekcontinue Bug 3 (e) — CLI consistency mode flags producer mismatch in JSON output', () => {
|
||||||
const root = mkdtempSync(join(tmpdir(), 'ultracontinue-fm-'));
|
const root = mkdtempSync(join(tmpdir(), 'trekcontinue-fm-'));
|
||||||
try {
|
try {
|
||||||
const projectDir = join(root, '.claude', 'projects', '2026-05-04-fixture-c');
|
const projectDir = join(root, '.claude', 'projects', '2026-05-04-fixture-c');
|
||||||
mkdirSync(projectDir, { recursive: true });
|
mkdirSync(projectDir, { recursive: true });
|
||||||
|
|
@ -207,7 +207,7 @@ test('ultracontinue Bug 3 (e) — CLI consistency mode flags producer mismatch i
|
||||||
}, null, 2),
|
}, null, 2),
|
||||||
);
|
);
|
||||||
|
|
||||||
// Project-dir prompt: produced_by ultraexecute-local at T-1
|
// Project-dir prompt: produced_by trekexecute at T-1
|
||||||
const projectPrompt = join(projectDir, 'NEXT-SESSION-PROMPT.local.md');
|
const projectPrompt = join(projectDir, 'NEXT-SESSION-PROMPT.local.md');
|
||||||
writeFileSync(projectPrompt,
|
writeFileSync(projectPrompt,
|
||||||
'---\nproduced_by: trekexecute\nproduced_at: 2026-05-04T15:30:00.000Z\n---\n\n# Session 2\n');
|
'---\nproduced_by: trekexecute\nproduced_at: 2026-05-04T15:30:00.000Z\n---\n\n# Session 2\n');
|
||||||
|
|
@ -245,7 +245,7 @@ test('ultracontinue Bug 3 (e) — CLI consistency mode flags producer mismatch i
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultracontinue Bug 2 — Phase 2 contains no {state-file-path} or any {curly-template} placeholder', () => {
|
test('trekcontinue Bug 2 — Phase 2 contains no {state-file-path} or any {curly-template} placeholder', () => {
|
||||||
// (d-2) Pattern D structure test. The fix must eliminate the
|
// (d-2) Pattern D structure test. The fix must eliminate the
|
||||||
// {state-file-path} placeholder and any other {anything} curly-brace
|
// {state-file-path} placeholder and any other {anything} curly-brace
|
||||||
// template syntax from Phase 2 — substitution failures are the
|
// template syntax from Phase 2 — substitution failures are the
|
||||||
|
|
@ -272,7 +272,7 @@ test('ultracontinue Bug 2 — Phase 2 contains no {state-file-path} or any {curl
|
||||||
// Step 10 — Bug 4 regression tests (Phase 0.5 wire-up + cleanup f-1/f-2/f-3)
|
// Step 10 — Bug 4 regression tests (Phase 0.5 wire-up + cleanup f-1/f-2/f-3)
|
||||||
// ---------------------------------------------------------------
|
// ---------------------------------------------------------------
|
||||||
|
|
||||||
test('ultracontinue Bug 4 — Phase 0.5 documents cleanup mode dispatch', () => {
|
test('trekcontinue Bug 4 — Phase 0.5 documents cleanup mode dispatch', () => {
|
||||||
const cmd = readCommand();
|
const cmd = readCommand();
|
||||||
assert.match(cmd, /## Phase 0\.5 /, 'Phase 0.5 header must be present');
|
assert.match(cmd, /## Phase 0\.5 /, 'Phase 0.5 header must be present');
|
||||||
// Phase 0.5 must come BETWEEN Phase 0 and Phase 1.
|
// Phase 0.5 must come BETWEEN Phase 0 and Phase 1.
|
||||||
|
|
@ -288,9 +288,9 @@ test('ultracontinue Bug 4 — Phase 0.5 documents cleanup mode dispatch', () =>
|
||||||
assert.match(cmd, /--cleanup --confirm/, 'usage must mention --cleanup --confirm');
|
assert.match(cmd, /--cleanup --confirm/, 'usage must mention --cleanup --confirm');
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultracontinue Bug 4 (f-1) dry-run lists candidates without deleting', async () => {
|
test('trekcontinue Bug 4 (f-1) dry-run lists candidates without deleting', async () => {
|
||||||
const { cleanupProject } = await import('../../lib/util/cleanup.mjs');
|
const { cleanupProject } = await import('../../lib/util/cleanup.mjs');
|
||||||
const root = mkdtempSync(join(tmpdir(), 'ultracontinue-cleanup-'));
|
const root = mkdtempSync(join(tmpdir(), 'trekcontinue-cleanup-'));
|
||||||
try {
|
try {
|
||||||
const dir = join(root, 'project-completed');
|
const dir = join(root, 'project-completed');
|
||||||
mkdirSync(dir, { recursive: true });
|
mkdirSync(dir, { recursive: true });
|
||||||
|
|
@ -314,10 +314,10 @@ test('ultracontinue Bug 4 (f-1) dry-run lists candidates without deleting', asyn
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultracontinue Bug 4 (f-2) confirm deletes and (f-3) idempotent re-run handles already-clean dir', async () => {
|
test('trekcontinue Bug 4 (f-2) confirm deletes and (f-3) idempotent re-run handles already-clean dir', async () => {
|
||||||
const { cleanupProject } = await import('../../lib/util/cleanup.mjs');
|
const { cleanupProject } = await import('../../lib/util/cleanup.mjs');
|
||||||
const { existsSync } = await import('node:fs');
|
const { existsSync } = await import('node:fs');
|
||||||
const root = mkdtempSync(join(tmpdir(), 'ultracontinue-cleanup-'));
|
const root = mkdtempSync(join(tmpdir(), 'trekcontinue-cleanup-'));
|
||||||
try {
|
try {
|
||||||
const dir = join(root, 'project-completed');
|
const dir = join(root, 'project-completed');
|
||||||
mkdirSync(dir, { recursive: true });
|
mkdirSync(dir, { recursive: true });
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# ultrareview determinism fixtures
|
# trekreview determinism fixtures
|
||||||
|
|
||||||
Synthetic fixtures for the Jaccard-similarity determinism test in
|
Synthetic fixtures for the Jaccard-similarity determinism test in
|
||||||
`tests/lib/review-determinism.test.mjs`.
|
`tests/lib/review-determinism.test.mjs`.
|
||||||
|
|
@ -24,7 +24,7 @@ fall out of sync.
|
||||||
## Why synthetic for v1.0
|
## Why synthetic for v1.0
|
||||||
|
|
||||||
Hand-curated for v1.0. Edit JSON IDs directly to test new Jaccard scenarios.
|
Hand-curated for v1.0. Edit JSON IDs directly to test new Jaccard scenarios.
|
||||||
Real-LLM determinism measurement is deferred to v1.1 once `/ultrareview-local`
|
Real-LLM determinism measurement is deferred to v1.1 once `/trekreview`
|
||||||
has produced enough real outputs to capture as fixtures.
|
has produced enough real outputs to capture as fixtures.
|
||||||
|
|
||||||
These fixtures prove the Jaccard PIPELINE works given a known input — they do
|
These fixtures prove the Jaccard PIPELINE works given a known input — they do
|
||||||
|
|
@ -42,6 +42,6 @@ verify the model-level claim is open work for v1.1.
|
||||||
```
|
```
|
||||||
3. Add the IDs to `findings:` block-style YAML in frontmatter and to `### <id>`
|
3. Add the IDs to `findings:` block-style YAML in frontmatter and to `### <id>`
|
||||||
subsections in the body.
|
subsections in the body.
|
||||||
4. Run `node lib/validators/review-validator.mjs --json tests/fixtures/ultrareview/review-run-X.md`
|
4. Run `node lib/validators/review-validator.mjs --json tests/fixtures/trekreview/review-run-X.md`
|
||||||
to confirm the fixture validates.
|
to confirm the fixture validates.
|
||||||
5. Update `tests/lib/review-determinism.test.mjs` if you want a new assertion.
|
5. Update `tests/lib/review-determinism.test.mjs` if you want a new assertion.
|
||||||
|
|
|
||||||
|
|
@ -8,14 +8,14 @@ source_findings:
|
||||||
|
|
||||||
# Remediation Plan: JWT auth review findings
|
# Remediation Plan: JWT auth review findings
|
||||||
|
|
||||||
> Generated by ultraplan-local v3.2.0 on 2026-05-01 — `plan_version: 1.7`.
|
> Generated by trekplan v3.2.0 on 2026-05-01 — `plan_version: 1.7`.
|
||||||
>
|
>
|
||||||
> Synthetic fixture — Handover 6 SC3(b) structural test only.
|
> Synthetic fixture — Handover 6 SC3(b) structural test only.
|
||||||
|
|
||||||
## Context
|
## Context
|
||||||
|
|
||||||
This synthetic plan is consumed by `tests/lib/source-findings.test.mjs` to verify
|
This synthetic plan is consumed by `tests/lib/source-findings.test.mjs` to verify
|
||||||
the structural contract of Handover 6: a plan generated from a `type: ultrareview`
|
the structural contract of Handover 6: a plan generated from a `type: trekreview`
|
||||||
brief carries a `source_findings:` block-style YAML list of 40-char hex IDs in
|
brief carries a `source_findings:` block-style YAML list of 40-char hex IDs in
|
||||||
its frontmatter. The IDs trace back to the consumed findings in `review.md`.
|
its frontmatter. The IDs trace back to the consumed findings in `review.md`.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -88,7 +88,7 @@ NOT the output of a real LLM review.
|
||||||
## Remediation Summary
|
## Remediation Summary
|
||||||
|
|
||||||
5 findings total: 1 BLOCKER, 3 MAJOR, 1 MINOR. Run a remediation plan via
|
5 findings total: 1 BLOCKER, 3 MAJOR, 1 MINOR. Run a remediation plan via
|
||||||
`/ultraplan-local --brief review.md` — it will pick up BLOCKER + MAJOR findings as
|
`/trekplan --brief review.md` — it will pick up BLOCKER + MAJOR findings as
|
||||||
plan goals and emit `source_findings: [<id>, ...]` audit trail (Handover 6).
|
plan goals and emit `source_findings: [<id>, ...]` audit trail (Handover 6).
|
||||||
|
|
||||||
```json
|
```json
|
||||||
|
|
|
||||||
|
|
@ -99,7 +99,7 @@ Run A's set is a strict subset of Run B's set, giving Jaccard = 5/6 = 0.833.
|
||||||
|
|
||||||
6 findings total: 1 BLOCKER, 4 MAJOR, 1 MINOR. Same merge gate as Run A; one
|
6 findings total: 1 BLOCKER, 4 MAJOR, 1 MINOR. Same merge gate as Run A; one
|
||||||
extra MAJOR (PLACEHOLDER_IN_CODE) that Run A missed. Run a remediation plan via
|
extra MAJOR (PLACEHOLDER_IN_CODE) that Run A missed. Run a remediation plan via
|
||||||
`/ultraplan-local --brief review.md`.
|
`/trekplan --brief review.md`.
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
|
|
|
||||||
|
|
@ -7,7 +7,7 @@
|
||||||
// MUST include the `Agent` tool in their tools allowlist (they spawn the swarm).
|
// MUST include the `Agent` tool in their tools allowlist (they spawn the swarm).
|
||||||
//
|
//
|
||||||
// When this test fails, fix the agent file — do NOT relax the assertion to
|
// When this test fails, fix the agent file — do NOT relax the assertion to
|
||||||
// hide drift. The contract is what /ultra*-local commands rely on for
|
// hide drift. The contract is what /trek* commands rely on for
|
||||||
// disciplined model selection + tool scoping.
|
// disciplined model selection + tool scoping.
|
||||||
|
|
||||||
import { test } from 'node:test';
|
import { test } from 'node:test';
|
||||||
|
|
|
||||||
|
|
@ -2,66 +2,66 @@ import { test } from 'node:test';
|
||||||
import { strict as assert } from 'node:assert';
|
import { strict as assert } from 'node:assert';
|
||||||
import { parseArgs } from '../../lib/parsers/arg-parser.mjs';
|
import { parseArgs } from '../../lib/parsers/arg-parser.mjs';
|
||||||
|
|
||||||
test('ultrabrief — empty args', () => {
|
test('trekbrief — empty args', () => {
|
||||||
const r = parseArgs('', 'trekbrief');
|
const r = parseArgs('', 'trekbrief');
|
||||||
assert.equal(r.command, 'trekbrief');
|
assert.equal(r.command, 'trekbrief');
|
||||||
assert.deepEqual(r.flags, {});
|
assert.deepEqual(r.flags, {});
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultrabrief — --quick boolean', () => {
|
test('trekbrief — --quick boolean', () => {
|
||||||
const r = parseArgs('--quick', 'trekbrief');
|
const r = parseArgs('--quick', 'trekbrief');
|
||||||
assert.equal(r.flags['--quick'], true);
|
assert.equal(r.flags['--quick'], true);
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultraresearch — --project value capture', () => {
|
test('trekresearch — --project value capture', () => {
|
||||||
const r = parseArgs('--project .claude/projects/2026-04-30-foo', 'trekresearch');
|
const r = parseArgs('--project .claude/projects/2026-04-30-foo', 'trekresearch');
|
||||||
assert.equal(r.flags['--project'], '.claude/projects/2026-04-30-foo');
|
assert.equal(r.flags['--project'], '.claude/projects/2026-04-30-foo');
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultraresearch — --quick --local combined', () => {
|
test('trekresearch — --quick --local combined', () => {
|
||||||
const r = parseArgs('--quick --local', 'trekresearch');
|
const r = parseArgs('--quick --local', 'trekresearch');
|
||||||
assert.equal(r.flags['--quick'], true);
|
assert.equal(r.flags['--quick'], true);
|
||||||
assert.equal(r.flags['--local'], true);
|
assert.equal(r.flags['--local'], true);
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultraplan — --research multi-value', () => {
|
test('trekplan — --research multi-value', () => {
|
||||||
const r = parseArgs('--research a.md b.md c.md', 'trekplan');
|
const r = parseArgs('--research a.md b.md c.md', 'trekplan');
|
||||||
assert.deepEqual(r.flags['--research'], ['a.md', 'b.md', 'c.md']);
|
assert.deepEqual(r.flags['--research'], ['a.md', 'b.md', 'c.md']);
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultraplan — --research multi stops at next flag', () => {
|
test('trekplan — --research multi stops at next flag', () => {
|
||||||
const r = parseArgs('--research a.md b.md --project /x', 'trekplan');
|
const r = parseArgs('--research a.md b.md --project /x', 'trekplan');
|
||||||
assert.deepEqual(r.flags['--research'], ['a.md', 'b.md']);
|
assert.deepEqual(r.flags['--research'], ['a.md', 'b.md']);
|
||||||
assert.equal(r.flags['--project'], '/x');
|
assert.equal(r.flags['--project'], '/x');
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultraplan — --brief required-value flag', () => {
|
test('trekplan — --brief required-value flag', () => {
|
||||||
const r = parseArgs('--brief brief.md', 'trekplan');
|
const r = parseArgs('--brief brief.md', 'trekplan');
|
||||||
assert.equal(r.flags['--brief'], 'brief.md');
|
assert.equal(r.flags['--brief'], 'brief.md');
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultraplan — missing value for --brief produces error', () => {
|
test('trekplan — missing value for --brief produces error', () => {
|
||||||
const r = parseArgs('--brief --quick', 'trekplan');
|
const r = parseArgs('--brief --quick', 'trekplan');
|
||||||
assert.ok(r.errors.find(e => e.code === 'ARG_MISSING_VALUE'));
|
assert.ok(r.errors.find(e => e.code === 'ARG_MISSING_VALUE'));
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultraplan — --decompose value flag', () => {
|
test('trekplan — --decompose value flag', () => {
|
||||||
const r = parseArgs('--decompose plan.md', 'trekplan');
|
const r = parseArgs('--decompose plan.md', 'trekplan');
|
||||||
assert.equal(r.flags['--decompose'], 'plan.md');
|
assert.equal(r.flags['--decompose'], 'plan.md');
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultraexecute — --resume + --project', () => {
|
test('trekexecute — --resume + --project', () => {
|
||||||
const r = parseArgs('--resume --project /tmp/p', 'trekexecute');
|
const r = parseArgs('--resume --project /tmp/p', 'trekexecute');
|
||||||
assert.equal(r.flags['--resume'], true);
|
assert.equal(r.flags['--resume'], true);
|
||||||
assert.equal(r.flags['--project'], '/tmp/p');
|
assert.equal(r.flags['--project'], '/tmp/p');
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultraexecute — --step N value', () => {
|
test('trekexecute — --step N value', () => {
|
||||||
const r = parseArgs('--step 3', 'trekexecute');
|
const r = parseArgs('--step 3', 'trekexecute');
|
||||||
assert.equal(r.flags['--step'], '3');
|
assert.equal(r.flags['--step'], '3');
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultraexecute — unknown flag goes to unknown[]', () => {
|
test('trekexecute — unknown flag goes to unknown[]', () => {
|
||||||
const r = parseArgs('--mystery foo', 'trekexecute');
|
const r = parseArgs('--mystery foo', 'trekexecute');
|
||||||
assert.ok(r.unknown.includes('--mystery'));
|
assert.ok(r.unknown.includes('--mystery'));
|
||||||
});
|
});
|
||||||
|
|
@ -76,28 +76,28 @@ test('unknown command reported as error', () => {
|
||||||
assert.ok(r.errors.find(e => e.code === 'ARG_UNKNOWN_COMMAND'));
|
assert.ok(r.errors.find(e => e.code === 'ARG_UNKNOWN_COMMAND'));
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultrareview — --project value capture', () => {
|
test('trekreview — --project value capture', () => {
|
||||||
const r = parseArgs('--project .claude/projects/2026-05-01-foo', 'trekreview');
|
const r = parseArgs('--project .claude/projects/2026-05-01-foo', 'trekreview');
|
||||||
assert.equal(r.flags['--project'], '.claude/projects/2026-05-01-foo');
|
assert.equal(r.flags['--project'], '.claude/projects/2026-05-01-foo');
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultrareview — --since <ref> value', () => {
|
test('trekreview — --since <ref> value', () => {
|
||||||
const r = parseArgs('--since HEAD~5', 'trekreview');
|
const r = parseArgs('--since HEAD~5', 'trekreview');
|
||||||
assert.equal(r.flags['--since'], 'HEAD~5');
|
assert.equal(r.flags['--since'], 'HEAD~5');
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultrareview — --quick + --validate combined', () => {
|
test('trekreview — --quick + --validate combined', () => {
|
||||||
const r = parseArgs('--quick --validate', 'trekreview');
|
const r = parseArgs('--quick --validate', 'trekreview');
|
||||||
assert.equal(r.flags['--quick'], true);
|
assert.equal(r.flags['--quick'], true);
|
||||||
assert.equal(r.flags['--validate'], true);
|
assert.equal(r.flags['--validate'], true);
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultrareview — unknown flag goes to unknown[]', () => {
|
test('trekreview — unknown flag goes to unknown[]', () => {
|
||||||
const r = parseArgs('--mystery foo', 'trekreview');
|
const r = parseArgs('--mystery foo', 'trekreview');
|
||||||
assert.ok(r.unknown.includes('--mystery'));
|
assert.ok(r.unknown.includes('--mystery'));
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultracontinue — empty args produce no flags and no positional', () => {
|
test('trekcontinue — empty args produce no flags and no positional', () => {
|
||||||
const r = parseArgs('', 'trekcontinue');
|
const r = parseArgs('', 'trekcontinue');
|
||||||
assert.equal(r.command, 'trekcontinue');
|
assert.equal(r.command, 'trekcontinue');
|
||||||
assert.deepEqual(r.flags, {});
|
assert.deepEqual(r.flags, {});
|
||||||
|
|
@ -105,35 +105,35 @@ test('ultracontinue — empty args produce no flags and no positional', () => {
|
||||||
assert.deepEqual(r.errors, []);
|
assert.deepEqual(r.errors, []);
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultracontinue — --help boolean flag', () => {
|
test('trekcontinue — --help boolean flag', () => {
|
||||||
const r = parseArgs('--help', 'trekcontinue');
|
const r = parseArgs('--help', 'trekcontinue');
|
||||||
assert.equal(r.flags['--help'], true);
|
assert.equal(r.flags['--help'], true);
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultracontinue — -h treated as positional (no alias resolution)', () => {
|
test('trekcontinue — -h treated as positional (no alias resolution)', () => {
|
||||||
const r = parseArgs('-h', 'trekcontinue');
|
const r = parseArgs('-h', 'trekcontinue');
|
||||||
assert.deepEqual(r.positional, ['-h']);
|
assert.deepEqual(r.positional, ['-h']);
|
||||||
assert.deepEqual(r.errors, []);
|
assert.deepEqual(r.errors, []);
|
||||||
assert.equal(r.flags['--help'], undefined);
|
assert.equal(r.flags['--help'], undefined);
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultracontinue — --cleanup boolean flag', () => {
|
test('trekcontinue — --cleanup boolean flag', () => {
|
||||||
const r = parseArgs('--cleanup', 'trekcontinue');
|
const r = parseArgs('--cleanup', 'trekcontinue');
|
||||||
assert.equal(r.flags['--cleanup'], true);
|
assert.equal(r.flags['--cleanup'], true);
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultracontinue — --cleanup --confirm both flags', () => {
|
test('trekcontinue — --cleanup --confirm both flags', () => {
|
||||||
const r = parseArgs('--cleanup --confirm', 'trekcontinue');
|
const r = parseArgs('--cleanup --confirm', 'trekcontinue');
|
||||||
assert.equal(r.flags['--cleanup'], true);
|
assert.equal(r.flags['--cleanup'], true);
|
||||||
assert.equal(r.flags['--confirm'], true);
|
assert.equal(r.flags['--confirm'], true);
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultracontinue — positional project dir captured', () => {
|
test('trekcontinue — positional project dir captured', () => {
|
||||||
const r = parseArgs('.claude/projects/2026-05-04-foo', 'trekcontinue');
|
const r = parseArgs('.claude/projects/2026-05-04-foo', 'trekcontinue');
|
||||||
assert.deepEqual(r.positional, ['.claude/projects/2026-05-04-foo']);
|
assert.deepEqual(r.positional, ['.claude/projects/2026-05-04-foo']);
|
||||||
});
|
});
|
||||||
|
|
||||||
test('ultracontinue — .md positional accepted by parser (rejection is command-level)', () => {
|
test('trekcontinue — .md positional accepted by parser (rejection is command-level)', () => {
|
||||||
const r = parseArgs('NEXT-SESSION-PROMPT.local.md', 'trekcontinue');
|
const r = parseArgs('NEXT-SESSION-PROMPT.local.md', 'trekcontinue');
|
||||||
assert.deepEqual(r.positional, ['NEXT-SESSION-PROMPT.local.md']);
|
assert.deepEqual(r.positional, ['NEXT-SESSION-PROMPT.local.md']);
|
||||||
assert.deepEqual(r.errors, []);
|
assert.deepEqual(r.errors, []);
|
||||||
|
|
|
||||||
|
|
@ -27,9 +27,9 @@ test('splitFrontmatter — no frontmatter', () => {
|
||||||
});
|
});
|
||||||
|
|
||||||
test('parseFrontmatter — string scalars', () => {
|
test('parseFrontmatter — string scalars', () => {
|
||||||
const r = parseFrontmatter('type: ultrabrief\nslug: jwt-auth\n');
|
const r = parseFrontmatter('type: trekbrief\nslug: jwt-auth\n');
|
||||||
assert.equal(r.valid, true);
|
assert.equal(r.valid, true);
|
||||||
assert.equal(r.parsed.type, 'ultrabrief');
|
assert.equal(r.parsed.type, 'trekbrief');
|
||||||
assert.equal(r.parsed.slug, 'jwt-auth');
|
assert.equal(r.parsed.slug, 'jwt-auth');
|
||||||
});
|
});
|
||||||
|
|
||||||
|
|
@ -60,10 +60,10 @@ test('parseFrontmatter — rejects nested dict', () => {
|
||||||
});
|
});
|
||||||
|
|
||||||
test('parseDocument — full pipeline', () => {
|
test('parseDocument — full pipeline', () => {
|
||||||
const text = '---\ntype: ultrabrief\nresearch_topics: 2\n---\n\n# Body\n\ncontent\n';
|
const text = '---\ntype: trekbrief\nresearch_topics: 2\n---\n\n# Body\n\ncontent\n';
|
||||||
const r = parseDocument(text);
|
const r = parseDocument(text);
|
||||||
assert.equal(r.valid, true);
|
assert.equal(r.valid, true);
|
||||||
assert.equal(r.parsed.frontmatter.type, 'ultrabrief');
|
assert.equal(r.parsed.frontmatter.type, 'trekbrief');
|
||||||
assert.match(r.parsed.body, /content/);
|
assert.match(r.parsed.body, /content/);
|
||||||
});
|
});
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -9,7 +9,7 @@ import {
|
||||||
} from '../../lib/parsers/project-discovery.mjs';
|
} from '../../lib/parsers/project-discovery.mjs';
|
||||||
|
|
||||||
function setupProject(structure) {
|
function setupProject(structure) {
|
||||||
const root = mkdtempSync(join(tmpdir(), 'ultraplan-disc-'));
|
const root = mkdtempSync(join(tmpdir(), 'trekplan-disc-'));
|
||||||
for (const [path, content] of Object.entries(structure)) {
|
for (const [path, content] of Object.entries(structure)) {
|
||||||
const full = join(root, path);
|
const full = join(root, path);
|
||||||
mkdirSync(join(full, '..'), { recursive: true });
|
mkdirSync(join(full, '..'), { recursive: true });
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
// tests/lib/source-findings.test.mjs
|
// tests/lib/source-findings.test.mjs
|
||||||
// SC3(b) structural test for Handover 6.
|
// SC3(b) structural test for Handover 6.
|
||||||
//
|
//
|
||||||
// The brief requires `plan.md` produced from a `type: ultrareview` brief to
|
// The brief requires `plan.md` produced from a `type: trekreview` brief to
|
||||||
// contain `source_findings: [<id>, ...]` in its frontmatter. Without an
|
// contain `source_findings: [<id>, ...]` in its frontmatter. Without an
|
||||||
// automated test, SC3(b) is unverified.
|
// automated test, SC3(b) is unverified.
|
||||||
//
|
//
|
||||||
|
|
|
||||||
|
|
@ -50,7 +50,7 @@ steps:
|
||||||
|
|
||||||
# Synthetic plan run A — Add --verbose flag to CLI
|
# Synthetic plan run A — Add --verbose flag to CLI
|
||||||
|
|
||||||
This fixture represents one synthesized run of `/ultraplan-local` against a
|
This fixture represents one synthesized run of `/trekplan` against a
|
||||||
hand-calibrated brief. It is paired with `plan-run-B.md` for the
|
hand-calibrated brief. It is paired with `plan-run-B.md` for the
|
||||||
`plan-determinism.test.mjs` Jaccard floor (≥ 0.833).
|
`plan-determinism.test.mjs` Jaccard floor (≥ 0.833).
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -50,7 +50,7 @@ steps:
|
||||||
|
|
||||||
# Synthetic plan run B — Add --verbose flag to CLI
|
# Synthetic plan run B — Add --verbose flag to CLI
|
||||||
|
|
||||||
This fixture represents a second synthesized run of `/ultraplan-local` against
|
This fixture represents a second synthesized run of `/trekplan` against
|
||||||
the same hand-calibrated brief used for `plan-run-A.md`. The two runs differ
|
the same hand-calibrated brief used for `plan-run-A.md`. The two runs differ
|
||||||
on 2 step titles (modeling realistic LLM variation).
|
on 2 step titles (modeling realistic LLM variation).
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -41,7 +41,7 @@ findings:
|
||||||
|
|
||||||
# Synthetic review run A — JWT authentication with refresh-token rotation
|
# Synthetic review run A — JWT authentication with refresh-token rotation
|
||||||
|
|
||||||
This fixture represents one synthesized run of `/ultrareview-local` on a
|
This fixture represents one synthesized run of `/trekreview` on a
|
||||||
hand-calibrated brief. It is paired with `review-run-B.md` for the
|
hand-calibrated brief. It is paired with `review-run-B.md` for the
|
||||||
`review-determinism.test.mjs` Jaccard floor (≥ 0.833).
|
`review-determinism.test.mjs` Jaccard floor (≥ 0.833).
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -6,7 +6,7 @@ import { join } from 'node:path';
|
||||||
import { discoverArchitecture } from '../../lib/validators/architecture-discovery.mjs';
|
import { discoverArchitecture } from '../../lib/validators/architecture-discovery.mjs';
|
||||||
|
|
||||||
function setup(structure) {
|
function setup(structure) {
|
||||||
const root = mkdtempSync(join(tmpdir(), 'ultraplan-arch-'));
|
const root = mkdtempSync(join(tmpdir(), 'trekplan-arch-'));
|
||||||
for (const [path, content] of Object.entries(structure)) {
|
for (const [path, content] of Object.entries(structure)) {
|
||||||
const full = join(root, path);
|
const full = join(root, path);
|
||||||
mkdirSync(join(full, '..'), { recursive: true });
|
mkdirSync(join(full, '..'), { recursive: true });
|
||||||
|
|
|
||||||
|
|
@ -95,9 +95,9 @@ test('validateBrief — missing frontmatter is hard error', () => {
|
||||||
|
|
||||||
const REVIEW_AS_BRIEF = `---
|
const REVIEW_AS_BRIEF = `---
|
||||||
type: trekreview
|
type: trekreview
|
||||||
task: "Review delivered ultrareview-local v1.0"
|
task: "Review delivered trekreview v1.0"
|
||||||
slug: ultrareview-local
|
slug: trekreview
|
||||||
project_dir: .claude/projects/2026-05-01-ultrareview-local/
|
project_dir: .claude/projects/2026-05-01-trekreview/
|
||||||
findings:
|
findings:
|
||||||
- 0123456789abcdef0123456789abcdef01234567
|
- 0123456789abcdef0123456789abcdef01234567
|
||||||
- fedcba9876543210fedcba9876543210fedcba98
|
- fedcba9876543210fedcba9876543210fedcba98
|
||||||
|
|
@ -107,7 +107,7 @@ findings:
|
||||||
|
|
||||||
## Intent
|
## Intent
|
||||||
|
|
||||||
Adversarial review of delivered ultrareview-local v1.0.
|
Adversarial review of delivered trekreview v1.0.
|
||||||
|
|
||||||
## Goal
|
## Goal
|
||||||
|
|
||||||
|
|
@ -118,12 +118,12 @@ Find what was missed.
|
||||||
- All BLOCKER findings get a fix-plan.
|
- All BLOCKER findings get a fix-plan.
|
||||||
`;
|
`;
|
||||||
|
|
||||||
test('validateBrief — ultrareview type accepted with findings array', () => {
|
test('validateBrief — trekreview type accepted with findings array', () => {
|
||||||
const r = validateBriefContent(REVIEW_AS_BRIEF, { strict: true });
|
const r = validateBriefContent(REVIEW_AS_BRIEF, { strict: true });
|
||||||
assert.equal(r.valid, true, JSON.stringify(r.errors));
|
assert.equal(r.valid, true, JSON.stringify(r.errors));
|
||||||
});
|
});
|
||||||
|
|
||||||
test('validateBrief — ultrareview without findings rejected (BRIEF_MISSING_FIELD)', () => {
|
test('validateBrief — trekreview without findings rejected (BRIEF_MISSING_FIELD)', () => {
|
||||||
const t = REVIEW_AS_BRIEF.replace(/findings:\n - 0123[\s\S]*?- fedcba[0-9a-f]+\n/, '');
|
const t = REVIEW_AS_BRIEF.replace(/findings:\n - 0123[\s\S]*?- fedcba[0-9a-f]+\n/, '');
|
||||||
const r = validateBriefContent(t);
|
const r = validateBriefContent(t);
|
||||||
assert.equal(r.valid, false);
|
assert.equal(r.valid, false);
|
||||||
|
|
@ -133,7 +133,7 @@ test('validateBrief — ultrareview without findings rejected (BRIEF_MISSING_FIE
|
||||||
);
|
);
|
||||||
});
|
});
|
||||||
|
|
||||||
test('validateBrief — ultrareview with findings as scalar (not array) rejected (BRIEF_BAD_FINDINGS_TYPE)', () => {
|
test('validateBrief — trekreview with findings as scalar (not array) rejected (BRIEF_BAD_FINDINGS_TYPE)', () => {
|
||||||
const t = REVIEW_AS_BRIEF.replace(
|
const t = REVIEW_AS_BRIEF.replace(
|
||||||
/findings:\n - 0123[\s\S]*?- fedcba[0-9a-f]+/,
|
/findings:\n - 0123[\s\S]*?- fedcba[0-9a-f]+/,
|
||||||
'findings: not-an-array',
|
'findings: not-an-array',
|
||||||
|
|
|
||||||
|
|
@ -108,7 +108,7 @@ test('validateSessionStateContent — malformed JSON returns SESSION_STATE_PARSE
|
||||||
});
|
});
|
||||||
|
|
||||||
test('validateSessionState — missing file returns SESSION_STATE_NOT_FOUND', () => {
|
test('validateSessionState — missing file returns SESSION_STATE_NOT_FOUND', () => {
|
||||||
const r = validateSessionState('/tmp/nonexistent-ultracontinue-test-9b2f4e.json');
|
const r = validateSessionState('/tmp/nonexistent-trekcontinue-test-9b2f4e.json');
|
||||||
assert.equal(r.valid, false);
|
assert.equal(r.valid, false);
|
||||||
assert.ok(r.errors.find(e => e.code === 'SESSION_STATE_NOT_FOUND'));
|
assert.ok(r.errors.find(e => e.code === 'SESSION_STATE_NOT_FOUND'));
|
||||||
});
|
});
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue