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