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,6 +1,6 @@
|
|||
---
|
||||
name: trekbrief
|
||||
description: Interactive interview that produces a task brief with explicit research plan. Feeds /ultraresearch-local and /ultraplan-local. Optionally orchestrates the full pipeline end-to-end.
|
||||
description: Interactive interview that produces a task brief with explicit research plan. Feeds /trekresearch and /trekplan. Optionally orchestrates the full pipeline end-to-end.
|
||||
argument-hint: "[--quick] <task description>"
|
||||
model: opus
|
||||
allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion
|
||||
|
|
@ -10,18 +10,18 @@ allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion
|
|||
|
||||
Interactive requirements-gathering command. Produces a **task brief** — a
|
||||
structured markdown file that declares intent, goal, constraints, and an
|
||||
**explicit research plan** with copy-paste-ready `/ultraresearch-local` commands.
|
||||
**explicit research plan** with copy-paste-ready `/trekresearch` commands.
|
||||
|
||||
Pipeline position:
|
||||
|
||||
```
|
||||
/ultrabrief-local → brief.md (this command)
|
||||
/ultraresearch-local --project <dir> → research/*.md
|
||||
/ultraplan-local --project <dir> → plan.md
|
||||
/ultraexecute-local --project <dir> → execution
|
||||
/trekbrief → brief.md (this command)
|
||||
/trekresearch --project <dir> → research/*.md
|
||||
/trekplan --project <dir> → plan.md
|
||||
/trekexecute --project <dir> → execution
|
||||
```
|
||||
|
||||
The brief is the contract between the user's intent and `/ultraplan-local`.
|
||||
The brief is the contract between the user's intent and `/trekplan`.
|
||||
Every decision the plan makes must trace back to content in the brief.
|
||||
|
||||
**This command is always interactive.** There is no background mode — the
|
||||
|
|
@ -55,17 +55,17 @@ Parse `$ARGUMENTS`:
|
|||
If no task description is provided, output usage and stop:
|
||||
|
||||
```
|
||||
Usage: /ultrabrief-local <task description>
|
||||
/ultrabrief-local --quick <task description>
|
||||
Usage: /trekbrief <task description>
|
||||
/trekbrief --quick <task description>
|
||||
|
||||
Modes:
|
||||
default Dynamic interview until quality gates pass — brief with research plan
|
||||
--quick Compact start; still escalates on weak sections — brief with research plan
|
||||
|
||||
Examples:
|
||||
/ultrabrief-local Add user authentication with JWT tokens
|
||||
/ultrabrief-local --quick Add rate limiting to the API
|
||||
/ultrabrief-local Migrate from Express to Fastify
|
||||
/trekbrief Add user authentication with JWT tokens
|
||||
/trekbrief --quick Add rate limiting to the API
|
||||
/trekbrief Migrate from Express to Fastify
|
||||
```
|
||||
|
||||
Report:
|
||||
|
|
@ -292,7 +292,7 @@ Proceeding to draft and review.
|
|||
|
||||
Phase 4 runs a **draft → brief-reviewer → revise** loop. The draft is
|
||||
not written to disk until the brief-review quality gate passes (or the
|
||||
iteration cap is hit). This ensures the brief that reaches `/ultraplan-local`
|
||||
iteration cap is hit). This ensures the brief that reaches `/trekplan`
|
||||
has already survived a critical review.
|
||||
|
||||
Read the brief template first:
|
||||
|
|
@ -502,8 +502,8 @@ Ask the user via `AskUserQuestion`:
|
|||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| **Manual (default)** | Print the commands. You run `/ultraresearch-local` and `/ultraplan-local` yourself, choosing depth per topic. |
|
||||
| **Auto (managed by Claude Code)** | I run all {N} research topics sequentially in foreground, then automatically trigger `/ultraplan-local` when research completes. This session blocks until the plan is ready. |
|
||||
| **Manual (default)** | Print the commands. You run `/trekresearch` and `/trekplan` yourself, choosing depth per topic. |
|
||||
| **Auto (managed by Claude Code)** | I run all {N} research topics sequentially in foreground, then automatically trigger `/trekplan` when research completes. This session blocks until the plan is ready. |
|
||||
|
||||
### Manual path (default)
|
||||
|
||||
|
|
@ -519,13 +519,13 @@ Research topics: {N}
|
|||
Next steps (run in order or parallel):
|
||||
|
||||
{For each topic:}
|
||||
/ultraresearch-local --project {PROJECT_DIR} --external "{topic question}"
|
||||
/trekresearch --project {PROJECT_DIR} --external "{topic question}"
|
||||
|
||||
Then:
|
||||
/ultraplan-local --project {PROJECT_DIR}
|
||||
/trekplan --project {PROJECT_DIR}
|
||||
|
||||
Then:
|
||||
/ultraexecute-local --project {PROJECT_DIR}
|
||||
/trekexecute --project {PROJECT_DIR}
|
||||
```
|
||||
|
||||
Stop. Do not continue to Phase 6.
|
||||
|
|
@ -549,7 +549,7 @@ answers no, fall back to the manual path output and stop. Otherwise
|
|||
proceed to Phase 6.
|
||||
|
||||
If `gates_mode == false` (default in auto): proceed directly to Phase 6.
|
||||
The chain stops only at the main-merge gate (see `commands/ultraexecute-local.md`
|
||||
The chain stops only at the main-merge gate (see `commands/trekexecute.md`
|
||||
Phase 8).
|
||||
|
||||
Proceed to Phase 6.
|
||||
|
|
@ -578,11 +578,11 @@ If cancelled → fall back to manual path output and stop.
|
|||
|
||||
Set `research_status: in_progress` in the brief's frontmatter.
|
||||
|
||||
For each research topic (index i = 1 .. N), invoke `/ultraresearch-local`
|
||||
For each research topic (index i = 1 .. N), invoke `/trekresearch`
|
||||
inline in this main-context session:
|
||||
|
||||
```
|
||||
/ultraresearch-local --project {PROJECT_DIR} {--external | --local | (none)} "{topic i question}"
|
||||
/trekresearch --project {PROJECT_DIR} {--external | --local | (none)} "{topic i question}"
|
||||
```
|
||||
|
||||
Pass the scope flag that matches the topic's scope hint. Wait for each
|
||||
|
|
@ -617,7 +617,7 @@ Update brief frontmatter: `research_status: complete`.
|
|||
Invoke the planning command inline in this session:
|
||||
|
||||
```
|
||||
/ultraplan-local --project {PROJECT_DIR}
|
||||
/trekplan --project {PROJECT_DIR}
|
||||
```
|
||||
|
||||
The planning pipeline runs all phases (exploration, synthesis, review) in
|
||||
|
|
@ -629,7 +629,7 @@ before continuing.
|
|||
When the planning-orchestrator finishes, present:
|
||||
|
||||
```
|
||||
## Ultrabrief + Ultraresearch + Ultraplan Complete (auto mode)
|
||||
## Ultrabrief + Ultraresearch + Voyage Complete (auto mode)
|
||||
|
||||
**Project:** {PROJECT_DIR}/
|
||||
**Brief:** {PROJECT_DIR}/brief.md
|
||||
|
|
@ -645,11 +645,11 @@ When the planning-orchestrator finishes, present:
|
|||
| Plan | Complete ({steps} steps, critic: {verdict}) |
|
||||
|
||||
Next:
|
||||
/ultraexecute-local --project {PROJECT_DIR}
|
||||
/trekexecute --project {PROJECT_DIR}
|
||||
|
||||
Or:
|
||||
/ultraexecute-local --dry-run --project {PROJECT_DIR} # preview
|
||||
/ultraexecute-local --validate --project {PROJECT_DIR} # schema check
|
||||
/trekexecute --dry-run --project {PROJECT_DIR} # preview
|
||||
/trekexecute --validate --project {PROJECT_DIR} # schema check
|
||||
```
|
||||
|
||||
## Phase 7 — Stats tracking
|
||||
|
|
@ -685,7 +685,7 @@ Never let stats failures block the workflow.
|
|||
the user until motivation is clear — the plan and every review agent
|
||||
will trace decisions back to this.
|
||||
4. **Research topics must be answerable.** Each topic's research question
|
||||
must be phrased so `/ultraresearch-local` can answer it. If a topic is
|
||||
must be phrased so `/trekresearch` can answer it. If a topic is
|
||||
too vague, split or reformulate before writing.
|
||||
5. **Never invent research topics the user did not agree to.** Topics
|
||||
come from the interview. If the user says "I know this", respect it.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: trekcontinue
|
||||
description: Resume the next session in a multi-session ultraplan project. Reads .session-state.local.json and immediately begins the next session.
|
||||
description: Resume the next session in a multi-session trekplan project. Reads .session-state.local.json and immediately begins the next session.
|
||||
argument-hint: "[<project-dir> | --help]"
|
||||
model: opus
|
||||
---
|
||||
|
|
@ -8,22 +8,22 @@ model: opus
|
|||
# Ultracontinue Local v1.0
|
||||
|
||||
Zero-friction multi-session resumption. In a fresh Claude Code session, type
|
||||
`/ultracontinue` — the command reads the per-project state file
|
||||
`/trekcontinue` — the command reads the per-project state file
|
||||
(`.claude/projects/<project>/.session-state.local.json`), shows a 3-line summary,
|
||||
and immediately begins executing the next session.
|
||||
|
||||
The state file is the contract. Any session-end mechanism may write it
|
||||
(`/ultraexecute-local` Phase 8 / Phase 2.55 / Phase 4, the
|
||||
`/ultraplan-end-session-local` helper, or — in the future — `graceful-handoff`).
|
||||
(`/trekexecute` Phase 8 / Phase 2.55 / Phase 4, the
|
||||
`/trekendsession` helper, or — in the future — `graceful-handoff`).
|
||||
This command only reads.
|
||||
|
||||
Pipeline position:
|
||||
|
||||
```
|
||||
/ultraplan-local → plan.md
|
||||
/ultraexecute-local → progress.json + .session-state.local.json
|
||||
/trekplan → plan.md
|
||||
/trekexecute → progress.json + .session-state.local.json
|
||||
... session boundary, fresh chat ...
|
||||
/ultracontinue → reads .session-state.local.json, starts next session
|
||||
/trekcontinue → reads .session-state.local.json, starts next session
|
||||
```
|
||||
|
||||
See **Handover 7** in `docs/HANDOVER-CONTRACTS.md` for the full schema.
|
||||
|
|
@ -43,14 +43,14 @@ the literal empty string `""`, or a positional project-dir — fall through to
|
|||
Phase 1. Do NOT print the usage block on empty args.
|
||||
|
||||
```
|
||||
/ultracontinue — Resume the next session in a multi-session ultraplan project.
|
||||
/trekcontinue — Resume the next session in a multi-session trekplan project.
|
||||
|
||||
Usage:
|
||||
/ultracontinue # auto-discover state file under cwd
|
||||
/ultracontinue <project-dir> # explicit project directory
|
||||
/ultracontinue --cleanup <project-dir> # dry-run: list stale files
|
||||
/ultracontinue --cleanup --confirm <project-dir> # actually delete (requires status: completed)
|
||||
/ultracontinue --help # this message
|
||||
/trekcontinue # auto-discover state file under cwd
|
||||
/trekcontinue <project-dir> # explicit project directory
|
||||
/trekcontinue --cleanup <project-dir> # dry-run: list stale files
|
||||
/trekcontinue --cleanup --confirm <project-dir> # actually delete (requires status: completed)
|
||||
/trekcontinue --help # this message
|
||||
|
||||
Reads .claude/projects/<project>/.session-state.local.json (per-project,
|
||||
gitignored). On a valid resumable state, prints a 3-line summary and begins
|
||||
|
|
@ -67,11 +67,11 @@ State-file schema (v1):
|
|||
(unknown top-level keys are tolerated — forward-compat for graceful-handoff v2.2)
|
||||
|
||||
Typical flow:
|
||||
/ultrabrief-local # produces brief.md
|
||||
/ultraplan-local --project ... # produces plan.md
|
||||
/ultraexecute-local --project .. # writes session-state on session-end
|
||||
/trekbrief # produces brief.md
|
||||
/trekplan --project ... # produces plan.md
|
||||
/trekexecute --project .. # writes session-state on session-end
|
||||
... (fresh Claude chat) ...
|
||||
/ultracontinue # reads session-state, runs next session
|
||||
/trekcontinue # reads session-state, runs next session
|
||||
```
|
||||
|
||||
## Phase 0.5 — Cleanup mode dispatch
|
||||
|
|
@ -89,10 +89,10 @@ irreversible. If `positional[0]` is missing, empty, or starts with `-`,
|
|||
print this usage block to stderr and exit non-zero:
|
||||
|
||||
```
|
||||
Error: /ultracontinue-local --cleanup requires <project-dir>.
|
||||
Error: /trekcontinue --cleanup requires <project-dir>.
|
||||
Usage:
|
||||
/ultracontinue-local --cleanup <project-dir> # dry-run: list stale files
|
||||
/ultracontinue-local --cleanup --confirm <project-dir> # actually delete (status: completed)
|
||||
/trekcontinue --cleanup <project-dir> # dry-run: list stale files
|
||||
/trekcontinue --cleanup --confirm <project-dir> # actually delete (status: completed)
|
||||
```
|
||||
|
||||
**Compute mode from parsed flags:**
|
||||
|
|
@ -117,7 +117,7 @@ booleans above. The validator emits a `{valid, errors, warnings, parsed}`
|
|||
JSON record. Print it to stdout. Exit with the validator's exit code.
|
||||
|
||||
**Cleanup is a terminal mode.** It must not fall through to Phase 1/2/3/4.
|
||||
Operators who want to resume after cleanup must invoke `/ultracontinue`
|
||||
Operators who want to resume after cleanup must invoke `/trekcontinue`
|
||||
again without `--cleanup`.
|
||||
|
||||
## Phase 1 — Resolve project directory
|
||||
|
|
@ -134,7 +134,7 @@ Print the following diagnostic to stderr and exit non-zero. Do NOT proceed.
|
|||
```
|
||||
Error: expected <project-dir>, got a markdown file path: <positional[0]>
|
||||
Did you mean to paste the file path as a project directory?
|
||||
Usage: /ultracontinue-local <project-dir>
|
||||
Usage: /trekcontinue <project-dir>
|
||||
```
|
||||
|
||||
### Step 1.b — Auto-discover candidates
|
||||
|
|
@ -157,17 +157,17 @@ resumable state wins.
|
|||
- **0 candidates and no explicit arg:** print SC-2 cold-start message and exit:
|
||||
```
|
||||
No active multi-session project here.
|
||||
Start with /ultrabrief-local or /ultraplan-local.
|
||||
Start with /trekbrief or /trekplan.
|
||||
```
|
||||
- **1 candidate (or explicit non-`.md` arg):** continue to Phase 2 with that path.
|
||||
- **>1 candidates and no explicit arg:** with the Date.parse sort applied, the
|
||||
newest resumable state wins automatically and the command continues to Phase 2
|
||||
with that path. (Operators who want a different candidate re-invoke as
|
||||
`/ultracontinue <project-dir>`.)
|
||||
`/trekcontinue <project-dir>`.)
|
||||
|
||||
## Phase 1.5 — Frontmatter consistency check
|
||||
|
||||
Bug 3 contract: producers (`/ultraexecute-local`, `/ultraplan-end-session-local`)
|
||||
Bug 3 contract: producers (`/trekexecute`, `/trekendsession`)
|
||||
write `NEXT-SESSION-PROMPT.local.md` with YAML frontmatter (`produced_by:`,
|
||||
`produced_at:`). Multiple producers may have written candidates in different
|
||||
locations; this phase refuses ambiguity before validating the state file.
|
||||
|
|
@ -197,7 +197,7 @@ After resolving the project directory and state-file path, look for two
|
|||
print the structured `errors[]` (each `[code] message` on its own line),
|
||||
list both candidate paths, and exit non-zero. Do NOT proceed to Phase 2.
|
||||
Resolve the conflict by deleting the stale candidate (run
|
||||
`/ultracontinue-local --cleanup --confirm <project-dir>` after the
|
||||
`/trekcontinue --cleanup --confirm <project-dir>` after the
|
||||
current session closes, or remove by hand).
|
||||
|
||||
- **If `valid: true` with a `NEXT_SESSION_PROMPT_WALL_CLOCK_DRIFT` warning**
|
||||
|
|
@ -277,8 +277,8 @@ Read the file at `next_session_brief_path` (it is the brief that the next
|
|||
session is supposed to execute — typically the same `brief.md` for
|
||||
single-brief multi-session plans, or a session-specific spec for parallel
|
||||
session decomposition). Understand the task and begin executing per the
|
||||
standard ultraplan-local pipeline. The user did not type a separate "start"
|
||||
command — `/ultracontinue` is the start.
|
||||
standard trekplan pipeline. The user did not type a separate "start"
|
||||
command — `/trekcontinue` is the start.
|
||||
|
||||
If the brief file does not exist (validator emits a warning but does not
|
||||
fail), print: `Warning: next_session_brief_path "{path}" does not exist on
|
||||
|
|
@ -295,7 +295,7 @@ if the env var is set; silently skip otherwise.
|
|||
|
||||
## Hard rules
|
||||
|
||||
- **Idempotent.** Running `/ultracontinue` twice in the same Claude session
|
||||
- **Idempotent.** Running `/trekcontinue` twice in the same Claude session
|
||||
does not advance state — the writer (Phase 8 / hook / helper) advances state
|
||||
only when a session completes.
|
||||
- **Zero secrets in the state file.** Status, paths, labels — never API keys,
|
||||
|
|
|
|||
|
|
@ -5,25 +5,25 @@ argument-hint: "<next-brief-path> <next-label> | --help"
|
|||
model: sonnet
|
||||
---
|
||||
|
||||
# Ultraplan End-Session Local v1.0
|
||||
# Voyage End-Session Local v1.0
|
||||
|
||||
Tiny helper for **informal** multi-session flows (no formal plan with
|
||||
Execution Strategy). Writes a `.session-state.local.json` pointing at the
|
||||
next session so `/ultracontinue` can resume in a fresh Claude chat.
|
||||
next session so `/trekcontinue` can resume in a fresh Claude chat.
|
||||
|
||||
For formal flows (a plan produced by `/ultraplan-local --project`),
|
||||
`/ultraexecute-local` Phase 8 already writes the state file — this helper
|
||||
For formal flows (a plan produced by `/trekplan --project`),
|
||||
`/trekexecute` Phase 8 already writes the state file — this helper
|
||||
is unnecessary there. Use this command for ad-hoc release runs, manual
|
||||
multi-session handovers, or any flow that does not run through
|
||||
`/ultraexecute-local`.
|
||||
`/trekexecute`.
|
||||
|
||||
Pipeline position:
|
||||
|
||||
```
|
||||
... session N work ...
|
||||
/ultraplan-end-session-local <brief> "<next-label>" → writes state
|
||||
/trekendsession <brief> "<next-label>" → writes state
|
||||
... session boundary, fresh chat ...
|
||||
/ultracontinue → reads state, starts session N+1
|
||||
/trekcontinue → reads state, starts session N+1
|
||||
```
|
||||
|
||||
See **Handover 7** in `docs/HANDOVER-CONTRACTS.md` for the schema.
|
||||
|
|
@ -34,11 +34,11 @@ If `$ARGUMENTS` contains `--help` or `-h`, print the usage block below and exit
|
|||
cleanly. Do NOT proceed to any further phase.
|
||||
|
||||
```
|
||||
/ultraplan-end-session-local — Mark current session done; point at next session.
|
||||
/trekendsession — Mark current session done; point at next session.
|
||||
|
||||
Usage:
|
||||
/ultraplan-end-session-local <next-brief-path> <next-label>
|
||||
/ultraplan-end-session-local --help
|
||||
/trekendsession <next-brief-path> <next-label>
|
||||
/trekendsession --help
|
||||
|
||||
Both arguments are REQUIRED. No interactive prompt — headless-safe.
|
||||
|
||||
|
|
@ -51,10 +51,10 @@ Writes <project-dir>/.session-state.local.json with:
|
|||
updated_at <now, ISO-8601>
|
||||
|
||||
Then validates via lib/validators/session-state-validator.mjs and prints
|
||||
the same 3-line narration that /ultracontinue will show in the next session.
|
||||
the same 3-line narration that /trekcontinue will show in the next session.
|
||||
|
||||
Example:
|
||||
/ultraplan-end-session-local .claude/projects/2026-05-01-feature/brief.md "Session 2 of 3"
|
||||
/trekendsession .claude/projects/2026-05-01-feature/brief.md "Session 2 of 3"
|
||||
```
|
||||
|
||||
## Phase 1 — Resolve project directory
|
||||
|
|
@ -82,12 +82,12 @@ If either is missing or empty:
|
|||
|
||||
```
|
||||
Error: missing required args.
|
||||
Usage: /ultraplan-end-session-local <next-brief-path> '<next-label>'
|
||||
Usage: /trekendsession <next-brief-path> '<next-label>'
|
||||
```
|
||||
|
||||
Print to stderr and exit 1. **No interactive prompt** — this keeps the helper
|
||||
headless-safe (per brief NFR; addresses adversarial-review major #11). If you
|
||||
want an interactive flow, use `/ultracontinue --help` to see the full pipeline.
|
||||
want an interactive flow, use `/trekcontinue --help` to see the full pipeline.
|
||||
|
||||
## Phase 3 — Atomically write `.session-state.local.json` + sibling NEXT-SESSION-PROMPT.local.md
|
||||
|
||||
|
|
@ -129,7 +129,7 @@ const stateObj = { schema_version: 1, project: dir, next_session_brief_path: bri
|
|||
const stateFile = path.join(dir, '.session-state.local.json');
|
||||
atomicWriteJson(stateFile, stateObj);
|
||||
const promptFile = path.join(dir, 'NEXT-SESSION-PROMPT.local.md');
|
||||
const promptBody = '---\\nproduced_by: trekendsession\\nproduced_at: ' + now + '\\nproject: ' + dir + '\\n---\\n\\n# ' + label + '\\n\\nResume via /ultracontinue.\\n';
|
||||
const promptBody = '---\\nproduced_by: trekendsession\\nproduced_at: ' + now + '\\nproject: ' + dir + '\\n---\\n\\n# ' + label + '\\n\\nResume via /trekcontinue.\\n';
|
||||
writeFileSync(promptFile, promptBody);
|
||||
console.log(stateFile);
|
||||
console.log(promptFile);
|
||||
|
|
@ -144,7 +144,7 @@ Validate the freshly-written state file:
|
|||
!`node lib/validators/session-state-validator.mjs --json <project-dir>/.session-state.local.json`
|
||||
```
|
||||
|
||||
If `valid: true`, print the success block matching `/ultracontinue` Phase 3
|
||||
If `valid: true`, print the success block matching `/trekcontinue` Phase 3
|
||||
narration (SC-8 cross-project consistency — same template both sides):
|
||||
|
||||
```
|
||||
|
|
@ -154,7 +154,7 @@ Project: <project-dir>
|
|||
Next session: <next-label>
|
||||
Brief: <next-brief-path>
|
||||
|
||||
In a fresh Claude session, run /ultracontinue to resume.
|
||||
In a fresh Claude session, run /trekcontinue to resume.
|
||||
```
|
||||
|
||||
If `valid: false`, print the structured `errors[]` and exit 1. Investigate
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
|
|||
|
||||
# Ultraexecute Local
|
||||
|
||||
Disciplined executor for ultraplan plans. Reads a plan file, detects if it has
|
||||
Disciplined executor for trekplan plans. Reads a plan file, detects if it has
|
||||
an Execution Strategy (multi-session), and either executes directly or
|
||||
orchestrates parallel headless sessions — all to realize one plan.
|
||||
|
||||
|
|
@ -25,7 +25,7 @@ Parse `$ARGUMENTS` for mode flags:
|
|||
- If `{dir}` does not exist or `{dir}/plan.md` is missing:
|
||||
```
|
||||
Error: project directory missing plan.md: {dir}
|
||||
Run /ultraplan-local --project {dir} to produce it.
|
||||
Run /trekplan --project {dir} to produce it.
|
||||
```
|
||||
- If no explicit `<plan.md>` argument is provided after flag parsing,
|
||||
use the derived `{dir}/plan.md`. If a `<plan.md>` argument IS provided,
|
||||
|
|
@ -54,20 +54,20 @@ If no path is provided (and `--project` was not used to derive one), output
|
|||
usage and stop:
|
||||
|
||||
```
|
||||
Usage: /ultraexecute-local <plan.md>
|
||||
/ultraexecute-local --project <dir>
|
||||
/ultraexecute-local --fg <plan.md>
|
||||
/ultraexecute-local --resume <plan.md>
|
||||
/ultraexecute-local --dry-run <plan.md>
|
||||
/ultraexecute-local --validate <plan.md>
|
||||
/ultraexecute-local --step N <plan.md>
|
||||
/ultraexecute-local --session N <plan.md>
|
||||
/ultraexecute-local --project <dir> --resume
|
||||
/ultraexecute-local --project <dir> --session N
|
||||
Usage: /trekexecute <plan.md>
|
||||
/trekexecute --project <dir>
|
||||
/trekexecute --fg <plan.md>
|
||||
/trekexecute --resume <plan.md>
|
||||
/trekexecute --dry-run <plan.md>
|
||||
/trekexecute --validate <plan.md>
|
||||
/trekexecute --step N <plan.md>
|
||||
/trekexecute --session N <plan.md>
|
||||
/trekexecute --project <dir> --resume
|
||||
/trekexecute --project <dir> --session N
|
||||
|
||||
Modes:
|
||||
(default) Auto — multi-session if plan has Execution Strategy, else foreground
|
||||
--project Resolve plan.md inside an ultrabrief project folder; progress.json
|
||||
--project Resolve plan.md inside an trekbrief project folder; progress.json
|
||||
is written there too
|
||||
--fg Force foreground — all steps sequentially, ignore Execution Strategy
|
||||
--resume Resume from last progress checkpoint
|
||||
|
|
@ -77,13 +77,13 @@ Modes:
|
|||
--session N Execute only session N from the plan's Execution Strategy
|
||||
|
||||
Examples:
|
||||
/ultraexecute-local .claude/plans/ultraplan-2026-04-06-auth-refactor.md
|
||||
/ultraexecute-local --project .claude/projects/2026-04-18-jwt-auth
|
||||
/ultraexecute-local --project .claude/projects/2026-04-18-jwt-auth --resume
|
||||
/ultraexecute-local --fg .claude/plans/ultraplan-2026-04-06-auth-refactor.md
|
||||
/ultraexecute-local --session 2 .claude/plans/ultraplan-2026-04-06-auth-refactor.md
|
||||
/ultraexecute-local --dry-run .claude/plans/ultraplan-2026-04-06-auth-refactor.md
|
||||
/ultraexecute-local --validate .claude/plans/ultraplan-2026-04-06-auth-refactor.md
|
||||
/trekexecute .claude/plans/trekplan-2026-04-06-auth-refactor.md
|
||||
/trekexecute --project .claude/projects/2026-04-18-jwt-auth
|
||||
/trekexecute --project .claude/projects/2026-04-18-jwt-auth --resume
|
||||
/trekexecute --fg .claude/plans/trekplan-2026-04-06-auth-refactor.md
|
||||
/trekexecute --session 2 .claude/plans/trekplan-2026-04-06-auth-refactor.md
|
||||
/trekexecute --dry-run .claude/plans/trekplan-2026-04-06-auth-refactor.md
|
||||
/trekexecute --validate .claude/plans/trekplan-2026-04-06-auth-refactor.md
|
||||
```
|
||||
|
||||
If the file does not exist, report and stop:
|
||||
|
|
@ -100,16 +100,16 @@ File: {path}
|
|||
|
||||
## Phase 2 — Detect file type and parse structure
|
||||
|
||||
Read the file. Determine whether it is an **ultraplan** or a **session spec**:
|
||||
Read the file. Determine whether it is an **trekplan** or a **session spec**:
|
||||
|
||||
- **Session spec**: contains `## Dependencies` with `Entry condition:` AND `## Scope Fence`
|
||||
AND `## Exit Condition` sections.
|
||||
- **Ultraplan**: contains `## Implementation Plan` with numbered `### Step N:` headings
|
||||
- **Voyage**: contains `## Implementation Plan` with numbered `### Step N:` headings
|
||||
but no `## Scope Fence`.
|
||||
|
||||
If neither structure is detected, report and stop:
|
||||
```
|
||||
Error: unrecognized file format. Expected an ultraplan or session spec.
|
||||
Error: unrecognized file format. Expected an trekplan or session spec.
|
||||
```
|
||||
|
||||
### Parse steps
|
||||
|
|
@ -226,7 +226,7 @@ Warnings: {count}
|
|||
{if warnings}: - {each warning on own line}
|
||||
|
||||
Plan is schema-compliant. Safe to run:
|
||||
/ultraexecute-local {path}
|
||||
/trekexecute {path}
|
||||
```
|
||||
|
||||
If Phase 2 parsing failed (unrecognized format, missing Manifest in strict
|
||||
|
|
@ -240,15 +240,15 @@ Reason: {specific error from Phase 2}
|
|||
{if format not recognized}:
|
||||
Detected heading format: {e.g. "### Fase 1:", "## Phase 1"}
|
||||
Expected: "### Step N: <description>"
|
||||
Fix: re-run /ultraplan-local — planning-orchestrator must emit v1.7 format
|
||||
Fix: re-run /trekplan — planning-orchestrator must emit v1.7 format
|
||||
|
||||
{if missing manifest}:
|
||||
Step {N} has no Manifest block (plan_version=1.7 requires one per step)
|
||||
Fix: re-run /ultraplan-local — planning-orchestrator must include manifest YAML
|
||||
Fix: re-run /trekplan — planning-orchestrator must include manifest YAML
|
||||
|
||||
{if malformed YAML or invalid regex}:
|
||||
Step {N}: {specific YAML/regex error}
|
||||
Fix: edit the plan manually or re-run /ultraplan-local
|
||||
Fix: edit the plan manually or re-run /trekplan
|
||||
```
|
||||
|
||||
Exit after emitting the report. Do not continue to Phase 2.4 or later.
|
||||
|
|
@ -390,13 +390,13 @@ Untracked/modified files:
|
|||
{output of git status --porcelain}
|
||||
|
||||
Commit or stash your changes, then re-run.
|
||||
To run sequentially instead: /ultraexecute-local --fg {plan-path}
|
||||
To run sequentially instead: /trekexecute --fg {plan-path}
|
||||
```
|
||||
|
||||
Stop execution. Update progress with `status: "stopped"`.
|
||||
|
||||
**Also write `.session-state.local.json`** (Handover 7) — this surfaces the
|
||||
stopped state to `/ultracontinue` so the next session can prompt the user to
|
||||
stopped state to `/trekcontinue` so the next session can prompt the user to
|
||||
clean the working tree before resuming. Write atomically alongside `progress.json`:
|
||||
|
||||
```json
|
||||
|
|
@ -458,7 +458,7 @@ that were manually edited or have bugs.
|
|||
### Check 4 — Stale worktree cleanup
|
||||
|
||||
Run `git worktree list`. If any worktrees with paths containing
|
||||
`ultraplan-sessions/{slug}/worktrees/` exist from a previous failed run:
|
||||
`trekplan-sessions/{slug}/worktrees/` exist from a previous failed run:
|
||||
|
||||
```bash
|
||||
git worktree remove --force {stale-path} 2>/dev/null
|
||||
|
|
@ -532,7 +532,7 @@ If `ANTHROPIC_API_KEY` is NOT set: proceed silently to Step 1.
|
|||
|
||||
```bash
|
||||
REPO_ROOT="$(git rev-parse --show-toplevel)"
|
||||
SESSION_DIR="$REPO_ROOT/.claude/ultraplan-sessions/{slug}"
|
||||
SESSION_DIR="$REPO_ROOT/.claude/trekplan-sessions/{slug}"
|
||||
WORKTREE_DIR="$SESSION_DIR/worktrees"
|
||||
LOG_DIR="$SESSION_DIR/logs"
|
||||
mkdir -p "$WORKTREE_DIR" "$LOG_DIR"
|
||||
|
|
@ -564,7 +564,7 @@ MAX_BUDGET_USD="${TREKEXECUTE_MAX_BUDGET_USD:-5}"
|
|||
|
||||
The budget caps default to safe values for normal-length steps. Operators may
|
||||
override for long runs:
|
||||
`TREKEXECUTE_MAX_TURNS=120 TREKEXECUTE_MAX_BUDGET_USD=20 /ultraexecute-local --project ...`
|
||||
`TREKEXECUTE_MAX_TURNS=120 TREKEXECUTE_MAX_BUDGET_USD=20 /trekexecute --project ...`
|
||||
|
||||
**2a. Create worktrees for this wave's sessions:**
|
||||
|
||||
|
|
@ -651,7 +651,7 @@ For each session N in the wave:
|
|||
```bash
|
||||
SESSION_CWD="${session_cwd:-.}" # default: worktree root; overridable per-session via Execution Strategy `cwd:` field
|
||||
cd "$WORKTREE_PATH/$SESSION_CWD" && \
|
||||
GIT_OPTIONAL_LOCKS=0 claude -p "${SAFETY_PREAMBLE}\n\n/ultraexecute-local --session {N} {plan-path}" \
|
||||
GIT_OPTIONAL_LOCKS=0 claude -p "${SAFETY_PREAMBLE}\n\n/trekexecute --session {N} {plan-path}" \
|
||||
--allowedTools "Read,Write,Edit,Bash,Glob,Grep" \
|
||||
--permission-mode bypassPermissions \
|
||||
--max-turns "$MAX_TURNS" \
|
||||
|
|
@ -690,7 +690,7 @@ wait {PID1} {PID2} ...
|
|||
**2d. Check results after each wave:**
|
||||
|
||||
For each session in the wave, read its log file (in `$LOG_DIR`, always accessible
|
||||
from the main worktree) and grep for `"ultraexecute_summary"`. Parse the JSON to
|
||||
from the main worktree) and grep for `"trekexecute_summary"`. Parse the JSON to
|
||||
determine:
|
||||
- Did the session complete? (`result: "completed"`)
|
||||
- Did it fail? (`result: "failed"` or `"stopped"`)
|
||||
|
|
@ -719,7 +719,7 @@ unrecoverable failure to a recoverable one). Push failure is non-fatal
|
|||
```bash
|
||||
GIT_OPTIONAL_LOCKS=0 git push origin "trek/{slug}/session-{N}" 2>/dev/null || true
|
||||
GIT_OPTIONAL_LOCKS=0 git merge --no-ff "trek/{slug}/session-{N}" \
|
||||
-m "merge: ultraplan session {N} — {session-title}"
|
||||
-m "merge: trekplan session {N} — {session-title}"
|
||||
```
|
||||
|
||||
If the merge succeeds (exit code 0): continue to next session.
|
||||
|
|
@ -823,12 +823,12 @@ The progress file location depends on whether `--project` is in use:
|
|||
|
||||
- **With `--project <dir>`:** progress lives at `{project_dir}/progress.json`.
|
||||
- **Without `--project`:** progress lives at
|
||||
`{plan-dir}/.ultraexecute-progress-{slug}.json`, where `{slug}` is the plan
|
||||
`{plan-dir}/.trekexecute-progress-{slug}.json`, where `{slug}` is the plan
|
||||
filename without extension.
|
||||
|
||||
**Session-scoped naming:** When `mode = session N`:
|
||||
- With `--project`: `{project_dir}/progress-session-{N}.json`.
|
||||
- Without `--project`: `{plan-dir}/.ultraexecute-progress-{slug}-session-{N}.json`.
|
||||
- Without `--project`: `{plan-dir}/.trekexecute-progress-{slug}-session-{N}.json`.
|
||||
|
||||
This prevents merge conflicts when parallel sessions each write their own
|
||||
progress file.
|
||||
|
|
@ -879,7 +879,7 @@ progress file.
|
|||
|
||||
## Phase 4 — Entry condition check (session specs only)
|
||||
|
||||
**Skip for ultraplans.** Skip in dry-run mode (report what would be checked instead).
|
||||
**Skip for trekplans.** Skip in dry-run mode (report what would be checked instead).
|
||||
|
||||
Read the entry condition. Evaluate it:
|
||||
|
||||
|
|
@ -899,14 +899,14 @@ Update progress file with `status: "stopped"`. Stop execution.
|
|||
**Also write `.session-state.local.json`** (Handover 7) with the same
|
||||
`status: "stopped"` and `next_session_brief_path` pointing at the brief that
|
||||
the failed entry-condition session was supposed to consume. This lets
|
||||
`/ultracontinue` surface the stop in the next session. Use the same atomic
|
||||
`/trekcontinue` surface the stop in the next session. Use the same atomic
|
||||
write pattern + validator check as Phase 2.55. On validator failure, warn
|
||||
but do not block.
|
||||
|
||||
**Also write sibling `NEXT-SESSION-PROMPT.local.md`** with frontmatter
|
||||
(`produced_by: trekexecute`, `produced_at: <ISO-8601>`,
|
||||
`status: stopped`) — same combined ESM pattern as Phase 8 — so Phase 1.5
|
||||
of `/ultracontinue` can compare project-dir and plugin-root candidates.
|
||||
of `/trekcontinue` can compare project-dir and plugin-root candidates.
|
||||
|
||||
If the entry condition **passes**:
|
||||
```
|
||||
|
|
@ -948,9 +948,9 @@ If `has_execution_strategy = true`, show a preview of multi-session orchestratio
|
|||
|
||||
| Wave | Session | Steps | Depends on | Command |
|
||||
|------|---------|-------|------------|---------|
|
||||
| 1 | Session 1: {title} | {nums} | none | `claude -p "/ultraexecute-local --session 1 {path}"` |
|
||||
| 1 | Session 2: {title} | {nums} | none | `claude -p "/ultraexecute-local --session 2 {path}"` |
|
||||
| 2 | Session 3: {title} | {nums} | S1, S2 | `claude -p "/ultraexecute-local --session 3 {path}"` |
|
||||
| 1 | Session 1: {title} | {nums} | none | `claude -p "/trekexecute --session 1 {path}"` |
|
||||
| 1 | Session 2: {title} | {nums} | none | `claude -p "/trekexecute --session 2 {path}"` |
|
||||
| 2 | Session 3: {title} | {nums} | S1, S2 | `claude -p "/trekexecute --session 3 {path}"` |
|
||||
```
|
||||
|
||||
Check billing status via `echo "${ANTHROPIC_API_KEY:+SET}"` and report:
|
||||
|
|
@ -1138,7 +1138,7 @@ If **FAIL**, read the `On failure:` clause. Apply the retry cap: **maximum 2 ret
|
|||
`status: "passed"` in the progress file — collect their `Files:` fields. Never
|
||||
use `git add -A` (risks staging secrets, binaries, or unrelated work).
|
||||
```bash
|
||||
git add {files from passed steps' Files: fields} && git commit -m "wip: ultraexecute-local stopped at step {N} — escalation needed"
|
||||
git add {files from passed steps' Files: fields} && git commit -m "wip: trekexecute stopped at step {N} — escalation needed"
|
||||
```
|
||||
Jump to Phase 7.
|
||||
|
||||
|
|
@ -1170,7 +1170,7 @@ and jump to Phase 8 (final report).
|
|||
|
||||
## Phase 7 — Exit condition check (session specs only)
|
||||
|
||||
**Skip for ultraplans.** Run only when all steps passed (not on early stop).
|
||||
**Skip for trekplans.** Run only when all steps passed (not on early stop).
|
||||
|
||||
Run each exit condition command from the `## Exit Condition` checklist:
|
||||
|
||||
|
|
@ -1230,7 +1230,7 @@ Record in progress file:
|
|||
## Phase 7.6 — Recovery dispatch (multi-session parent context only)
|
||||
|
||||
**Preconditions:**
|
||||
- This is the parent ultraexecute invocation (not a child `--session N`)
|
||||
- This is the parent trekexecute invocation (not a child `--session N`)
|
||||
- Phase 7.5 reported `drift`
|
||||
- `recovery_depth < 2` (hard cap to prevent infinite loops)
|
||||
|
||||
|
|
@ -1256,7 +1256,7 @@ the user for manual resolution.
|
|||
**Invoke the recovery session:**
|
||||
|
||||
```bash
|
||||
cd "$WORKTREE_PATH" && claude -p "/ultraexecute-local --session {N} {recovery spec path}" \
|
||||
cd "$WORKTREE_PATH" && claude -p "/trekexecute --session {N} {recovery spec path}" \
|
||||
--allowedTools "Read,Write,Edit,Bash,Glob,Grep" \
|
||||
--permission-mode bypassPermissions \
|
||||
> "$LOG_DIR/session-{N}-recovery-{depth}.log" 2>&1
|
||||
|
|
@ -1320,11 +1320,11 @@ node ${CLAUDE_PLUGIN_ROOT}/lib/stats/event-emit.mjs \
|
|||
```
|
||||
|
||||
**Recovery surface:** if declined, `--resume re-enters at the gate` —
|
||||
re-running `/ultraexecute-local --resume --project <dir>` jumps directly
|
||||
re-running `/trekexecute --resume --project <dir>` jumps directly
|
||||
back to the main-merge gate AskUserQuestion (skipping completed waves).
|
||||
The wave session branches are preserved for inspection (Hard Rule 19's
|
||||
push-before-cleanup ensures they survive on the remote even if local
|
||||
cleanup ran). To inspect: `git log ultraplan/<slug>/session-N` per wave.
|
||||
cleanup ran). To inspect: `git log trekplan/<slug>/session-N` per wave.
|
||||
|
||||
### Progress + state-file writes
|
||||
|
||||
|
|
@ -1353,7 +1353,7 @@ to stderr but do NOT block — Phase 8 must always reach the final report.
|
|||
**Also write sibling `NEXT-SESSION-PROMPT.local.md`** (Bug 3 frontmatter
|
||||
contract — see `docs/HANDOVER-CONTRACTS.md` § Handover 7 Lifecycle) in the
|
||||
project directory. The frontmatter MUST contain `produced_by: trekexecute`
|
||||
and `produced_at: <ISO-8601>` so `/ultracontinue` Phase 1.5 can detect
|
||||
and `produced_at: <ISO-8601>` so `/trekcontinue` Phase 1.5 can detect
|
||||
producer drift between project-dir and plugin-root candidates. Use a single
|
||||
ESM inline block so state-file + prompt-file writes succeed or fail together:
|
||||
|
||||
|
|
@ -1366,7 +1366,7 @@ const [, dir, briefPath, label, status] = process.argv;
|
|||
const now = new Date().toISOString();
|
||||
const stateObj = { schema_version: 1, project: dir, next_session_brief_path: briefPath, next_session_label: label, status, updated_at: now };
|
||||
atomicWriteJson(path.join(dir, '.session-state.local.json'), stateObj);
|
||||
const promptBody = '---\\nproduced_by: trekexecute\\nproduced_at: ' + now + '\\nproject: ' + dir + '\\nstatus: ' + status + '\\n---\\n\\n# ' + label + '\\n\\nResume via /ultracontinue.\\n';
|
||||
const promptBody = '---\\nproduced_by: trekexecute\\nproduced_at: ' + now + '\\nproject: ' + dir + '\\nstatus: ' + status + '\\n---\\n\\n# ' + label + '\\n\\nResume via /trekcontinue.\\n';
|
||||
writeFileSync(path.join(dir, 'NEXT-SESSION-PROMPT.local.md'), promptBody);
|
||||
" '{project_dir}' '{next_session_brief_path}' '{next_session_label}' '{status}'`
|
||||
```
|
||||
|
|
@ -1426,7 +1426,7 @@ Attempts: {N}
|
|||
|
||||
{Numbered list of unexecuted steps}
|
||||
|
||||
To resume: /ultraexecute-local --resume {path}
|
||||
To resume: /trekexecute --resume {path}
|
||||
```
|
||||
|
||||
**Result vocabulary (v1.7, strict):**
|
||||
|
|
@ -1441,7 +1441,7 @@ To resume: /ultraexecute-local --resume {path}
|
|||
|
||||
```json
|
||||
{
|
||||
"ultraexecute_summary": {
|
||||
"trekexecute_summary": {
|
||||
"plan": "{path}",
|
||||
"plan_type": "{plan | session-spec}",
|
||||
"plan_version": "{1.7 | 1.6 | legacy}",
|
||||
|
|
@ -1464,7 +1464,7 @@ To resume: /ultraexecute-local --resume {path}
|
|||
}
|
||||
```
|
||||
|
||||
The `ultraexecute_summary` key makes it grep-able in log files from headless runs.
|
||||
The `trekexecute_summary` key makes it grep-able in log files from headless runs.
|
||||
|
||||
## Phase 9 — Stats tracking
|
||||
|
||||
|
|
|
|||
|
|
@ -6,24 +6,24 @@ model: opus
|
|||
allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion, TaskCreate, TaskUpdate, TeamCreate, TeamDelete
|
||||
---
|
||||
|
||||
# Ultraplan Local v2.0
|
||||
# Voyage Local v2.0
|
||||
|
||||
Deep, multi-phase implementation planning driven by a **task brief**.
|
||||
Planning consumes the brief (produced by `/ultrabrief-local`) and any
|
||||
Planning consumes the brief (produced by `/trekbrief`) and any
|
||||
research briefs referenced in it, then runs specialized exploration
|
||||
agents, synthesis, and adversarial review to produce an executable plan.
|
||||
|
||||
**v2.0 is a breaking release.** The interview phase has been extracted
|
||||
into `/ultrabrief-local`. This command no longer accepts free-text task
|
||||
into `/trekbrief`. This command no longer accepts free-text task
|
||||
descriptions — it requires either `--brief <path>` or `--project <dir>`.
|
||||
|
||||
Pipeline position:
|
||||
|
||||
```
|
||||
/ultrabrief-local → brief.md
|
||||
/ultraresearch-local → research/*.md
|
||||
/ultraplan-local → plan.md (this command)
|
||||
/ultraexecute-local → execution
|
||||
/trekbrief → brief.md
|
||||
/trekresearch → research/*.md
|
||||
/trekplan → plan.md (this command)
|
||||
/trekexecute → execution
|
||||
```
|
||||
|
||||
## Phase 1 — Parse mode and validate input
|
||||
|
|
@ -57,7 +57,7 @@ Parse `$ARGUMENTS` for mode flags. Order of precedence:
|
|||
- Research briefs auto-discovered from `{dir}/research/*.md` (sorted).
|
||||
- If `{dir}` does not exist or `{dir}/brief.md` is missing:
|
||||
```
|
||||
Error: project directory not initialized. Run /ultrabrief-local to create it.
|
||||
Error: project directory not initialized. Run /trekbrief to create it.
|
||||
Missing: {dir}/brief.md
|
||||
```
|
||||
- Set **project_dir = {dir}**, **brief_path = {dir}/brief.md**.
|
||||
|
|
@ -119,15 +119,15 @@ Parse `$ARGUMENTS` for mode flags. Order of precedence:
|
|||
output usage and stop:
|
||||
|
||||
```
|
||||
Usage: /ultraplan-local --brief <path-to-brief.md>
|
||||
/ultraplan-local --project <project-dir>
|
||||
/ultraplan-local --brief <path> --research <research-brief.md>
|
||||
/ultraplan-local --project <dir> --fg
|
||||
/ultraplan-local --project <dir> --quick
|
||||
/ultraplan-local --export <pr|issue|markdown|headless> <plan-path>
|
||||
/ultraplan-local --decompose <plan-path>
|
||||
Usage: /trekplan --brief <path-to-brief.md>
|
||||
/trekplan --project <project-dir>
|
||||
/trekplan --brief <path> --research <research-brief.md>
|
||||
/trekplan --project <dir> --fg
|
||||
/trekplan --project <dir> --quick
|
||||
/trekplan --export <pr|issue|markdown|headless> <plan-path>
|
||||
/trekplan --decompose <plan-path>
|
||||
|
||||
A brief is required. Produce one with /ultrabrief-local first.
|
||||
A brief is required. Produce one with /trekbrief first.
|
||||
|
||||
Modes:
|
||||
--brief Plan from a brief file (foreground, v2.4.0+)
|
||||
|
|
@ -139,12 +139,12 @@ Modes:
|
|||
--decompose Split an existing plan into self-contained headless sessions
|
||||
|
||||
Examples:
|
||||
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth
|
||||
/ultraplan-local --brief .claude/projects/2026-04-18-jwt-auth/brief.md
|
||||
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth --research extra.md
|
||||
/ultraplan-local --project .claude/projects/2026-04-18-jwt-auth --fg
|
||||
/ultraplan-local --export pr .claude/plans/ultraplan-2026-04-06-rate-limiting.md
|
||||
/ultraplan-local --decompose .claude/plans/ultraplan-2026-04-06-rate-limiting.md
|
||||
/trekplan --project .claude/projects/2026-04-18-jwt-auth
|
||||
/trekplan --brief .claude/projects/2026-04-18-jwt-auth/brief.md
|
||||
/trekplan --project .claude/projects/2026-04-18-jwt-auth --research extra.md
|
||||
/trekplan --project .claude/projects/2026-04-18-jwt-auth --fg
|
||||
/trekplan --export pr .claude/plans/trekplan-2026-04-06-rate-limiting.md
|
||||
/trekplan --decompose .claude/plans/trekplan-2026-04-06-rate-limiting.md
|
||||
|
||||
Migrating from v1.x? See MIGRATION.md in this plugin. The old --spec flag
|
||||
and free-text interview mode were removed in v2.0.
|
||||
|
|
@ -176,13 +176,13 @@ Project: {project_dir or "-"}
|
|||
Research: {N local briefs, M extra via --research}
|
||||
```
|
||||
|
||||
### When the input is type:ultrareview (Handover 6)
|
||||
### When the input is type:trekreview (Handover 6)
|
||||
|
||||
The brief input may be a `review.md` produced by `/ultrareview-local`
|
||||
instead of a `brief.md` produced by `/ultrabrief-local`. Both files
|
||||
The brief input may be a `review.md` produced by `/trekreview`
|
||||
instead of a `brief.md` produced by `/trekbrief`. Both files
|
||||
share the same handover slot — `type` is the discriminator.
|
||||
|
||||
If `fm.type === 'ultrareview'`:
|
||||
If `fm.type === 'trekreview'`:
|
||||
|
||||
1. Skip the `research_status` gate above (review.md has no
|
||||
`research_topics` and no Research Plan section).
|
||||
|
|
@ -249,7 +249,7 @@ Output a markdown block formatted as a PR description:
|
|||
{Risks from plan, abbreviated to 1 line each}
|
||||
|
||||
---
|
||||
*Generated by ultraplan-local from {plan filename}*
|
||||
*Generated by trekplan from {plan filename}*
|
||||
```
|
||||
|
||||
### Format: `issue`
|
||||
|
|
@ -270,7 +270,7 @@ Output a markdown block formatted as an issue comment:
|
|||
{Top 2–3 risks from plan}
|
||||
|
||||
---
|
||||
*Generated by ultraplan-local*
|
||||
*Generated by trekplan*
|
||||
```
|
||||
|
||||
### Format: `markdown`
|
||||
|
|
@ -303,19 +303,19 @@ Then **stop**. Do not continue to any subsequent phase.
|
|||
Read the plan file. Verify it contains an Implementation Plan section with
|
||||
numbered steps. If no steps are found, report and stop:
|
||||
```
|
||||
Error: plan has no implementation steps. Run /ultraplan-local first to generate a plan.
|
||||
Error: plan has no implementation steps. Run /trekplan first to generate a plan.
|
||||
```
|
||||
|
||||
Determine the output directory from the plan slug:
|
||||
- Extract the slug from the plan filename (e.g., `ultraplan-2026-04-06-auth-refactor` → `auth-refactor`)
|
||||
- Output directory: `.claude/ultraplan-sessions/{slug}/`
|
||||
- Extract the slug from the plan filename (e.g., `trekplan-2026-04-06-auth-refactor` → `auth-refactor`)
|
||||
- Output directory: `.claude/trekplan-sessions/{slug}/`
|
||||
|
||||
Launch the **session-decomposer** agent:
|
||||
|
||||
```
|
||||
Plan file: {plan path}
|
||||
Plugin root: ${CLAUDE_PLUGIN_ROOT}
|
||||
Output directory: .claude/ultraplan-sessions/{slug}/
|
||||
Output directory: .claude/trekplan-sessions/{slug}/
|
||||
```
|
||||
|
||||
The session-decomposer will:
|
||||
|
|
@ -334,7 +334,7 @@ When the session-decomposer completes, present the summary to the user:
|
|||
|
||||
**Master plan:** {plan path}
|
||||
**Sessions:** {N} across {W} waves
|
||||
**Output:** .claude/ultraplan-sessions/{slug}/
|
||||
**Output:** .claude/trekplan-sessions/{slug}/
|
||||
|
||||
### Sessions
|
||||
|
||||
|
|
@ -344,14 +344,14 @@ When the session-decomposer completes, present the summary to the user:
|
|||
|
||||
### Files generated
|
||||
|
||||
- Session specs: .claude/ultraplan-sessions/{slug}/session-*.md
|
||||
- Dependency graph: .claude/ultraplan-sessions/{slug}/dependency-graph.md
|
||||
- Launch script: .claude/ultraplan-sessions/{slug}/launch.sh
|
||||
- Session specs: .claude/trekplan-sessions/{slug}/session-*.md
|
||||
- Dependency graph: .claude/trekplan-sessions/{slug}/dependency-graph.md
|
||||
- Launch script: .claude/trekplan-sessions/{slug}/launch.sh
|
||||
|
||||
You can:
|
||||
- Review individual session specs before running
|
||||
- Run all sessions: `bash .claude/ultraplan-sessions/{slug}/launch.sh`
|
||||
- Run a single session: `claude -p "$(cat .claude/ultraplan-sessions/{slug}/session-1-*.md)"`
|
||||
- Run all sessions: `bash .claude/trekplan-sessions/{slug}/launch.sh`
|
||||
- Run a single session: `claude -p "$(cat .claude/trekplan-sessions/{slug}/session-1-*.md)"`
|
||||
- Say **"launch"** to start headless execution from here
|
||||
```
|
||||
|
||||
|
|
@ -361,7 +361,7 @@ Then **stop**. Do not continue to any subsequent phase.
|
|||
|
||||
## Phase 2 — (removed in v2.0)
|
||||
|
||||
The interview phase has moved to `/ultrabrief-local`. This command no
|
||||
The interview phase has moved to `/trekbrief`. This command no
|
||||
longer asks the user any requirements questions — the brief is the
|
||||
authoritative input.
|
||||
|
||||
|
|
@ -372,7 +372,7 @@ Determine the plan destination path:
|
|||
frontmatter field): **plan destination = {project_dir}/plan.md**.
|
||||
- Otherwise: derive slug and date — if the brief has frontmatter `slug` and
|
||||
`created`, use them; otherwise extract from the brief filename. Destination:
|
||||
`.claude/plans/ultraplan-{YYYY-MM-DD}-{slug}.md`.
|
||||
`.claude/plans/trekplan-{YYYY-MM-DD}-{slug}.md`.
|
||||
|
||||
Collect all research briefs (from `--research` flag and auto-discovered
|
||||
`{project_dir}/research/*.md`).
|
||||
|
|
@ -677,7 +677,7 @@ Write the plan following the template structure. The plan MUST include:
|
|||
|
||||
Use the plan destination computed in Phase 3:
|
||||
- `--project` mode: `{project_dir}/plan.md`
|
||||
- `--brief` mode: `.claude/plans/ultraplan-{YYYY-MM-DD}-{slug}.md`
|
||||
- `--brief` mode: `.claude/plans/trekplan-{YYYY-MM-DD}-{slug}.md`
|
||||
|
||||
Create the parent directory if it does not exist.
|
||||
|
||||
|
|
@ -731,7 +731,7 @@ After both complete:
|
|||
Present a summary to the user:
|
||||
|
||||
```
|
||||
## Ultraplan Complete
|
||||
## Voyage Complete
|
||||
|
||||
**Task:** {task description}
|
||||
**Mode:** {foreground | quick}
|
||||
|
|
@ -835,7 +835,7 @@ Never let tracking failures block the main workflow.
|
|||
brief (Intent, Goal, Constraint, Preference, NFR, Success Criterion). If a
|
||||
step has no brief basis, it is scope creep — flag it or remove it.
|
||||
- **No interview**: Never ask the user requirements questions. If the brief is
|
||||
inadequate, stop and ask the user to run `/ultrabrief-local` again.
|
||||
inadequate, stop and ask the user to run `/trekbrief` again.
|
||||
- **Scope**: Only explore the current working directory and its subdirectories.
|
||||
Never read files outside the repo (no ~/.env, no credentials, no other repos).
|
||||
- **Cost**: Sonnet for all agents (exploration, deep-dives, research, critics).
|
||||
|
|
|
|||
|
|
@ -17,9 +17,9 @@ external research could provide alone.
|
|||
specialized agents, each seeing only what they need. The value is in triangulation
|
||||
(cross-checking local vs. external) and synthesis (insights from combining both).
|
||||
|
||||
**Pipeline integration:** Research briefs feed into ultraplan via `--research`:
|
||||
**Pipeline integration:** Research briefs feed into trekplan via `--research`:
|
||||
```
|
||||
/ultraresearch-local <question> → brief → /ultraplan-local --research <brief> <task>
|
||||
/trekresearch <question> → brief → /trekplan --research <brief> <task>
|
||||
```
|
||||
|
||||
## Phase 1 — Parse mode and validate input
|
||||
|
|
@ -43,14 +43,14 @@ Supported flags:
|
|||
is always foreground as of v2.4.0. Set **execution = foreground** (the
|
||||
only mode).
|
||||
|
||||
5. `--project <dir>` — attach this research to an ultrabrief project folder.
|
||||
5. `--project <dir>` — attach this research to an trekbrief project folder.
|
||||
The brief will be written to `{dir}/research/{NN}-{slug}.md` (auto-incremented
|
||||
index) instead of the default `.claude/research/` path. Set **project_dir = {dir}**.
|
||||
|
||||
If `{dir}` does not exist:
|
||||
```
|
||||
Error: project directory not found: {dir}
|
||||
Run /ultrabrief-local first to create it.
|
||||
Run /trekbrief first to create it.
|
||||
```
|
||||
Create `{dir}/research/` if it does not already exist.
|
||||
|
||||
|
|
@ -75,12 +75,12 @@ After stripping flags, the remaining text is the **research question**.
|
|||
If no research question is provided, output usage and stop:
|
||||
|
||||
```
|
||||
Usage: /ultraresearch-local <research question>
|
||||
/ultraresearch-local --quick <research question>
|
||||
/ultraresearch-local --local <research question>
|
||||
/ultraresearch-local --external <research question>
|
||||
/ultraresearch-local --fg <research question>
|
||||
/ultraresearch-local --project <dir> [--external|--local|--quick|--fg] <research question>
|
||||
Usage: /trekresearch <research question>
|
||||
/trekresearch --quick <research question>
|
||||
/trekresearch --local <research question>
|
||||
/trekresearch --external <research question>
|
||||
/trekresearch --fg <research question>
|
||||
/trekresearch --project <dir> [--external|--local|--quick|--fg] <research question>
|
||||
|
||||
Modes:
|
||||
default Interview → foreground research (local + external) → brief
|
||||
|
|
@ -88,17 +88,17 @@ Modes:
|
|||
--local Only codebase analysis agents (skip external + Gemini)
|
||||
--external Only external research agents (skip codebase analysis)
|
||||
--fg No-op alias (foreground is the only mode as of v2.4.0)
|
||||
--project Write brief into an ultrabrief project folder (auto-indexed)
|
||||
--project Write brief into an trekbrief project folder (auto-indexed)
|
||||
|
||||
Flags can be combined: --local, --external --quick, --project <dir> --external
|
||||
|
||||
Examples:
|
||||
/ultraresearch-local Should we migrate from Express to Fastify?
|
||||
/ultraresearch-local --quick What auth libraries are popular for Node.js?
|
||||
/ultraresearch-local --local How is error handling structured in this codebase?
|
||||
/ultraresearch-local --external What are the security implications of using Redis for sessions?
|
||||
/ultraresearch-local --fg --local What patterns does this codebase use for database access?
|
||||
/ultraresearch-local --project .claude/projects/2026-04-18-jwt-auth --external What JWT library is best for Node.js?
|
||||
/trekresearch Should we migrate from Express to Fastify?
|
||||
/trekresearch --quick What auth libraries are popular for Node.js?
|
||||
/trekresearch --local How is error handling structured in this codebase?
|
||||
/trekresearch --external What are the security implications of using Redis for sessions?
|
||||
/trekresearch --fg --local What patterns does this codebase use for database access?
|
||||
/trekresearch --project .claude/projects/2026-04-18-jwt-auth --external What JWT library is best for Node.js?
|
||||
```
|
||||
|
||||
Do not continue past this step if no question was provided.
|
||||
|
|
@ -119,7 +119,7 @@ If **project_dir is set**:
|
|||
- Brief destination: `{project_dir}/research/{NN}-{slug}.md`
|
||||
|
||||
If **project_dir is not set**:
|
||||
- Brief destination: `.claude/research/ultraresearch-{YYYY-MM-DD}-{slug}.md`
|
||||
- Brief destination: `.claude/research/trekresearch-{YYYY-MM-DD}-{slug}.md`
|
||||
|
||||
Store as `brief_destination` for use in later phases.
|
||||
|
||||
|
|
@ -127,7 +127,7 @@ Store as `brief_destination` for use in later phases.
|
|||
|
||||
Use `AskUserQuestion` to clarify the research question. Ask **one question at a time**.
|
||||
|
||||
The interview is shorter than ultraplan's (2-4 questions, not 3-8) because research
|
||||
The interview is shorter than trekplan's (2-4 questions, not 3-8) because research
|
||||
is more focused than planning.
|
||||
|
||||
### Interview flow
|
||||
|
|
@ -292,7 +292,7 @@ other agents — the value of Gemini is independence.
|
|||
|
||||
- Launch ALL selected agents **in parallel** in a single message
|
||||
- Use model: "sonnet" for all sub-agents (the orchestrator runs on Opus)
|
||||
- Scale maxTurns by codebase size for local agents (same as ultraplan):
|
||||
- Scale maxTurns by codebase size for local agents (same as trekplan):
|
||||
small = halved, medium/large = default
|
||||
- convention-scanner: medium+ codebases only (50+ files)
|
||||
|
||||
|
|
@ -308,7 +308,7 @@ If no gaps exist, skip: "Initial research sufficient — no follow-ups needed."
|
|||
|
||||
## Phase 6 — Triangulation
|
||||
|
||||
This is the KEY phase that makes ultraresearch more than aggregation.
|
||||
This is the KEY phase that makes trekresearch more than aggregation.
|
||||
|
||||
For each research dimension:
|
||||
|
||||
|
|
@ -346,7 +346,7 @@ Write the research brief following the template. Key rules:
|
|||
Generate the slug from the research question (first 3-4 meaningful words).
|
||||
Write the brief to the `brief_destination` computed in Phase 1:
|
||||
- With `--project`: `{project_dir}/research/{NN}-{slug}.md`
|
||||
- Without `--project`: `.claude/research/ultraresearch-{YYYY-MM-DD}-{slug}.md`
|
||||
- Without `--project`: `.claude/research/trekresearch-{YYYY-MM-DD}-{slug}.md`
|
||||
|
||||
Create the parent directory if it does not exist.
|
||||
|
||||
|
|
@ -378,8 +378,8 @@ Present a summary to the user:
|
|||
|
||||
You can:
|
||||
- Read the full brief at {brief_destination}
|
||||
- If `--project` was used: run `/ultraplan-local --project {project_dir}` when all research topics are complete
|
||||
- Otherwise: `/ultraplan-local --research {brief_destination} --brief <your-brief.md>`
|
||||
- If `--project` was used: run `/trekplan --project {project_dir}` when all research topics are complete
|
||||
- Otherwise: `/trekplan --research {brief_destination} --brief <your-brief.md>`
|
||||
- Ask follow-up questions about specific findings
|
||||
```
|
||||
|
||||
|
|
@ -413,7 +413,7 @@ If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip tracking silently.
|
|||
## Hard rules
|
||||
|
||||
- **No planning:** This command produces research briefs, not implementation plans.
|
||||
If the user asks to plan, direct them to `/ultraplan-local --research <brief>`.
|
||||
If the user asks to plan, direct them to `/trekplan --research <brief>`.
|
||||
- **Sources required:** Every claim must cite a source. No unsourced findings.
|
||||
- **Independence:** Do not pre-bias external agents with local findings or vice versa.
|
||||
Triangulate AFTER independent research.
|
||||
|
|
|
|||
|
|
@ -11,19 +11,19 @@ allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion
|
|||
|
||||
# Ultrareview Local v1.0
|
||||
|
||||
Independent post-hoc review of code delivered by `/ultraexecute-local`
|
||||
Independent post-hoc review of code delivered by `/trekexecute`
|
||||
against the contract in `brief.md`. Produces `review.md` — a structured
|
||||
artifact with severity-tagged findings that `/ultraplan-local --brief
|
||||
artifact with severity-tagged findings that `/trekplan --brief
|
||||
review.md` can consume as plan input (Handover 6).
|
||||
|
||||
Pipeline position:
|
||||
|
||||
```
|
||||
/ultrabrief-local → brief.md
|
||||
/ultraresearch-local → research/*.md
|
||||
/ultraplan-local → plan.md
|
||||
/ultraexecute-local → progress.json (+ commits)
|
||||
/ultrareview-local → review.md (this command)
|
||||
/trekbrief → brief.md
|
||||
/trekresearch → research/*.md
|
||||
/trekplan → plan.md
|
||||
/trekexecute → progress.json (+ commits)
|
||||
/trekreview → review.md (this command)
|
||||
```
|
||||
|
||||
The review is **independent**: each reviewer runs without cross-feeding,
|
||||
|
|
@ -38,15 +38,15 @@ command executes inline.
|
|||
Parse `$ARGUMENTS` via the shared arg-parser:
|
||||
|
||||
```bash
|
||||
node ${CLAUDE_PLUGIN_ROOT}/lib/parsers/arg-parser.mjs --command ultrareview "$@"
|
||||
node ${CLAUDE_PLUGIN_ROOT}/lib/parsers/arg-parser.mjs --command trekreview "$@"
|
||||
```
|
||||
|
||||
The parser recognizes these flags (see `lib/parsers/arg-parser.mjs`
|
||||
FLAG_SCHEMA `ultrareview` entry):
|
||||
FLAG_SCHEMA `trekreview` entry):
|
||||
|
||||
| Flag | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| `--project <dir>` | valued | Required. Path to ultraplan-local project folder containing `brief.md`. |
|
||||
| `--project <dir>` | valued | Required. Path to trekplan project folder containing `brief.md`. |
|
||||
| `--since <ref>` | valued | Optional. Override "before" SHA for the diff. Validated via `git rev-parse --verify`. |
|
||||
| `--quick` | boolean | Skip the brief-conformance pass; run only the code-correctness reviewer; skip the coordinator's reasonableness filter. |
|
||||
| `--validate` | boolean | Schema-only check on existing `{project_dir}/review.md`. No LLM calls. |
|
||||
|
|
@ -57,7 +57,7 @@ Resolution:
|
|||
1. If `--project` is missing, print usage and stop:
|
||||
```
|
||||
Error: --project <dir> is required.
|
||||
Usage: /ultrareview-local --project <dir> [--since <ref>] [--quick] [--validate] [--dry-run]
|
||||
Usage: /trekreview --project <dir> [--since <ref>] [--quick] [--validate] [--dry-run]
|
||||
```
|
||||
2. Trim trailing slash from `{dir}`. Set:
|
||||
- `project_dir = {dir}`
|
||||
|
|
@ -65,7 +65,7 @@ Resolution:
|
|||
- `review_path = {dir}/review.md`
|
||||
3. If `{dir}` does not exist or `{dir}/brief.md` is missing:
|
||||
```
|
||||
Error: project directory not initialized. Run /ultrabrief-local first.
|
||||
Error: project directory not initialized. Run /trekbrief first.
|
||||
Missing: {dir}/brief.md
|
||||
```
|
||||
|
||||
|
|
@ -87,7 +87,7 @@ node ${CLAUDE_PLUGIN_ROOT}/lib/validators/brief-validator.mjs --soft --json "{br
|
|||
|
||||
Read the JSON output. If `valid: false` AND any error has code
|
||||
`BRIEF_MISSING_REQUIRED_FIELD` or `FRONTMATTER_PARSE_ERROR`: stop and
|
||||
ask the user to re-run `/ultrabrief-local`. Other soft errors become
|
||||
ask the user to re-run `/trekbrief`. Other soft errors become
|
||||
warnings in the review's Executive Summary.
|
||||
|
||||
Read the brief frontmatter. Capture for review.md:
|
||||
|
|
@ -299,13 +299,13 @@ After the write succeeds, print:
|
|||
You can:
|
||||
- Read the full review at {review_path}
|
||||
- Feed BLOCKER + MAJOR findings into a follow-up plan:
|
||||
/ultraplan-local --brief {review_path}
|
||||
/trekplan --brief {review_path}
|
||||
- Re-run with `--quick` for a faster correctness-only pass
|
||||
- Re-run with `--since <ref>` to narrow scope
|
||||
```
|
||||
|
||||
Per **Handover 6**, BLOCKER and MAJOR findings are consumed by
|
||||
`/ultraplan-local --brief review.md` to produce a remediation plan. The
|
||||
`/trekplan --brief review.md` to produce a remediation plan. The
|
||||
review's frontmatter `findings:` list and the trailing JSON block are
|
||||
the contract for that handover (see `docs/HANDOVER-CONTRACTS.md`).
|
||||
|
||||
|
|
@ -330,7 +330,7 @@ the contract for that handover (see `docs/HANDOVER-CONTRACTS.md`).
|
|||
- **Refuse-with-suggestion above 100 files / 100K tokens.** Never run
|
||||
blind on a giant diff. Use AskUserQuestion to surface the gate.
|
||||
- **Cost.** Sonnet for all sub-agents (reviewers + coordinator). Opus
|
||||
only runs in the main /ultrareview-local command thread.
|
||||
only runs in the main /trekreview command thread.
|
||||
- **Privacy.** Never log secrets, tokens, or credentials in review.md.
|
||||
Findings citing files with secret-like content must redact the secret
|
||||
in the `detail` field.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue