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

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

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

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

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

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

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

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

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

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

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

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

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