From 1dad53a1e4cb4255d9064d2e33516a9fb346b017 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Fri, 1 May 2026 21:01:34 +0200 Subject: [PATCH] docs(ultraplan-local): document /ultracontinue in README + CLAUDE MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: version badge 3.2.0 → 3.3.0, "Six commands" intro, /ultracontinue row in command table, full /ultracontinue-local section with modes + schema v1 + /ultraplan-end-session helper + typical flow. - CLAUDE.md: extend validators list (atomic-write util, session-state-validator), bump test count 109 → 185, "7 pipeline handovers" line, Continue paragraph in Architecture, .session-state.local.json + Continue stats in State, Session-state entry in Terminology. Step 11 of /ultracontinue v3.3.0. --- plugins/ultraplan-local/CLAUDE.md | 20 ++++++--- plugins/ultraplan-local/README.md | 73 +++++++++++++++++++++++++++++-- 2 files changed, 82 insertions(+), 11 deletions(-) diff --git a/plugins/ultraplan-local/CLAUDE.md b/plugins/ultraplan-local/CLAUDE.md index 8dc9e24..a104274 100644 --- a/plugins/ultraplan-local/CLAUDE.md +++ b/plugins/ultraplan-local/CLAUDE.md @@ -114,9 +114,9 @@ The triage gate is deterministic — path-pattern classifier produces `{file → `lib/` contains zero-dep validators and parsers wired into the four commands: -- `lib/util/{frontmatter,result}.mjs` — shared YAML-frontmatter parser + Result helpers +- `lib/util/{frontmatter,result,atomic-write}.mjs` — shared YAML-frontmatter parser + Result helpers + `atomicWriteJson(path, obj)` for tmp+rename writes - `lib/parsers/{plan-schema,manifest-yaml,project-discovery,arg-parser,bash-normalize}.mjs` — pure parsers (no I/O), unit-tested -- `lib/validators/{brief,research,plan,progress}-validator.mjs` — schema validators with CLI shims (`node lib/validators/X.mjs --json `) +- `lib/validators/{brief,research,plan,progress,session-state}-validator.mjs` — schema validators with CLI shims (`node lib/validators/X.mjs --json `) - `lib/validators/architecture-discovery.mjs` — drift-WARN external-contract discovery for `architecture/overview.md` Wiring points (replaces previous prose-grep instructions): @@ -125,11 +125,11 @@ Wiring points (replaces previous prose-grep instructions): - `planning-orchestrator` Phase 5.5 → `plan-validator --strict` (replaces 3 `grep -cE` calls) - `/ultraexecute-local --validate` → `plan-validator --strict` + `progress-validator` -Tests under `tests/**/*.test.mjs` (109 tests, 0 deps). `npm test` is the fork-readiness gate. +Tests under `tests/**/*.test.mjs` (185 tests, 0 deps). `npm test` is the fork-readiness gate. -Doc-consistency test at `tests/lib/doc-consistency.test.mjs` pins agent-table count, command-table coverage, plan_version invariant, and settings.json scope cleanliness. +Doc-consistency test at `tests/lib/doc-consistency.test.mjs` pins agent-table count, command-table coverage, plan_version invariant, settings.json scope cleanliness, Handover 7 presence, and `session-state-validator` CLI shim. -`docs/HANDOVER-CONTRACTS.md` is the single source of truth for the 5 pipeline handovers (brief→research, research→plan, architecture→plan EXTERNAL, plan→execute, progress.json resume). Read it before changing any artifact format. +`docs/HANDOVER-CONTRACTS.md` is the single source of truth for the 7 pipeline handovers (brief→research, research→plan, architecture→plan EXTERNAL, plan→execute, progress.json resume, review→plan, `.session-state.local.json`). Read it before changing any artifact format. `hooks/scripts/pre-compact-flush.mjs` (PreCompact event, CC v2.1.105+) fixes the documented P0 in `docs/ultraexecute-v2-observations-from-config-audit-v4.md`: keeps `progress.json` in sync with git history before context compaction so `--resume` works after long conversations. Atomic write, monotonic only, never blocks compaction. @@ -147,7 +147,9 @@ Doc-consistency test at `tests/lib/doc-consistency.test.mjs` pins agent-table co **Decompose:** Parse plan → Analyze step dependencies → Group into sessions → Identify parallel waves → Generate session specs + dependency graph + launch script. -**Execute:** Parse plan → Security scan (Phase 2.4) → Detect Execution Strategy → Single-session (step loop) or multi-session (parallel waves via `claude -p` with scoped `--allowedTools`) → Phase 7.5 manifest audit → Phase 7.6 bounded recovery (if partial) → Report. With `--project`, reads `{dir}/plan.md` and writes `{dir}/progress.json`. +**Execute:** Parse plan → Security scan (Phase 2.4) → Detect Execution Strategy → Single-session (step loop) or multi-session (parallel waves via `claude -p` with scoped `--allowedTools`) → Phase 7.5 manifest audit → Phase 7.6 bounded recovery (if partial) → Phase 8 atomically writes `progress.json` + `.session-state.local.json` (Handover 7) → Report. With `--project`, reads `{dir}/plan.md`. Phase 2.55 (pre-flight stop) and Phase 4 (entry-condition stop) also write `.session-state.local.json` so `/ultracontinue` can surface the stop and prompt for next steps. + +**Continue:** `/ultracontinue-local` reads `{dir}/.session-state.local.json` (Handover 7), validates schema-v1 via `session-state-validator`, narrates a 3-line summary (project / next-session-label / brief-path), and immediately begins executing the next session. Auto-discovers active project state files under `.claude/projects/*/.session-state.local.json` if no explicit `` argument. Operator-invoked only — never auto-loaded via SessionStart. The `/ultraplan-end-session-local` helper is the informal-flow producer: writes the same state file for ad-hoc multi-session handovers that don't run through `/ultraexecute-local`. **Security:** 4-layer defense-in-depth: plugin hooks (pre-bash-executor, pre-write-executor), prompt-level denylist (works in headless sessions), pre-execution plan scan (Phase 2.4), scoped `--allowedTools` replacing `--dangerously-skip-permissions`. Hard Rules 14-16 enforce verify command security, repo-boundary writes, and sensitive path protection. @@ -178,6 +180,8 @@ All artifacts in one project directory (default): - `plan.md` (from `/ultraplan-local --project`) - `sessions/session-*.md` (from `--decompose`) - `progress.json` (from `/ultraexecute-local --project`) + - `review.md` (from `/ultrareview-local --project`) + - `.session-state.local.json` (Handover 7 — gitignored via `*.local.json`; written by `/ultraexecute-local` Phase 8/2.55/4 or `/ultraplan-end-session-local`; read by `/ultracontinue`) Legacy paths (still work without `--project`): - Research briefs: `.claude/research/ultraresearch-{date}-{slug}.md` @@ -191,6 +195,7 @@ Stats: - Plan stats: `${CLAUDE_PLUGIN_DATA}/ultraplan-stats.jsonl` - Exec stats: `${CLAUDE_PLUGIN_DATA}/ultraexecute-stats.jsonl` - Research stats: `${CLAUDE_PLUGIN_DATA}/ultraresearch-stats.jsonl` +- Continue stats: `${CLAUDE_PLUGIN_DATA}/ultracontinue-stats.jsonl` ## Terminology @@ -198,5 +203,6 @@ Stats: - **Research brief** — produced by `/ultraresearch-local`. Answers a specific research question. Feeds planning. - **Architecture note** — opt-in, produced by `/ultra-cc-architect-local` from the separate `ultra-cc-architect` plugin. Proposes which Claude Code features fit the task with brief-anchored rationale + explicit gaps. When present, enriches planning. - **Review** — produced by `/ultrareview-local`. Independent post-hoc review of delivered code against the task brief. **Handover 6 (review → plan)** routes BLOCKER + MAJOR findings into `/ultraplan-local --brief review.md` for a remediation plan. The plan's optional `source_findings:` frontmatter list is the audit trail back to the consumed findings. MINOR + SUGGESTION are skipped for v1.0 plan-input. +- **Session state** — `.session-state.local.json` per project. **Handover 7** — produced by any session-end mechanism (`/ultraexecute-local` Phase 8/2.55/4, `/ultraplan-end-session-local` helper, future graceful-handoff v2.2). Consumed by `/ultracontinue-local` to resume the next session in a fresh chat. Schema v1 is forward-compat (unknown top-level keys ignored). Never committed (gitignored via `*.local.json`). -A project typically has 1 task brief, 0–N research briefs, 0 or 1 architecture note, and 0–N reviews (one per review iteration). +A project typically has 1 task brief, 0–N research briefs, 0 or 1 architecture note, 0–N reviews (one per review iteration), and 0 or 1 session-state file (overwritten on every session-end). diff --git a/plugins/ultraplan-local/README.md b/plugins/ultraplan-local/README.md index ad338c1..8e5a542 100644 --- a/plugins/ultraplan-local/README.md +++ b/plugins/ultraplan-local/README.md @@ -1,12 +1,12 @@ -# ultraplan-local — Brief, Research, Plan, Execute, Review +# ultraplan-local — Brief, Research, Plan, Execute, Review, Continue -![Version](https://img.shields.io/badge/version-3.2.0-blue) +![Version](https://img.shields.io/badge/version-3.3.0-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![Platform](https://img.shields.io/badge/platform-Claude%20Code-purple) *AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)* -A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, autonomous execution, and independent post-hoc review. Five commands, one pipeline: +A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep implementation planning, multi-source research, autonomous execution, independent post-hoc review, and zero-friction multi-session resumption. Six commands, one pipeline: | Command | What it does | |---------|-------------| @@ -15,6 +15,7 @@ A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep | **`/ultraplan-local`** | Plan — agent swarm exploration, Opus planning, adversarial review | | **`/ultraexecute-local`** | Execute — disciplined step-by-step implementation with failure recovery | | **`/ultrareview-local`** | Review — independent post-hoc review of delivered code against the brief, severity-tagged findings | +| **`/ultracontinue-local`** | Continue — read `.session-state.local.json` and resume the next session in a multi-session project | Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `plan.md`, `sessions/`, `progress.json`, and `review.md`. @@ -416,6 +417,70 @@ The plan's optional `source_findings:` frontmatter list is the audit trail back --- +## `/ultracontinue-local` — Resume + +Zero-friction multi-session resumption. Type `/ultracontinue` in a fresh +Claude Code session — the command reads the per-project state file +(`.claude/projects//.session-state.local.json`), prints a 3-line +summary, and immediately begins executing the next session. + +The state file is the contract — any session-end mechanism may write it +(`/ultraexecute-local` Phase 8 / Phase 2.55 / Phase 4 do so automatically; +the `/ultraplan-end-session-local` helper writes it for informal flows; +`graceful-handoff` may converge on it in a future release). `/ultracontinue` +only reads. See **Handover 7** in `docs/HANDOVER-CONTRACTS.md` for the full +schema and producer/consumer contract. + +### Modes + +| Mode | Command | Description | +|------|---------|-------------| +| **Default** | `/ultracontinue` | Auto-discover `.session-state.local.json` under cwd, validate, narrate, and begin executing the next session | +| **Explicit** | `/ultracontinue ` | Use the named project directory; helpful when several active projects coexist under cwd | +| **Help** | `/ultracontinue --help` | Print usage block and the schema-v1 reference | + +### Schema v1 — `.session-state.local.json` + +| Field | Type | Required | Notes | +|---|---|---|---| +| `schema_version` | number | yes | Must be `1` | +| `project` | string | yes | Project directory path | +| `next_session_brief_path` | string | yes | Validator soft-checks file existence (warning, not error) | +| `next_session_label` | string | yes | Human-readable label for the next session (e.g. "Session 2 of 5") | +| `status` | enum | yes | `in_progress` \| `partial` \| `failed` \| `stopped` \| `completed` (`completed` → no further sessions to resume) | +| `updated_at` | string | yes | ISO-8601 timestamp | + +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 + +For informal multi-session flows that don't run through `/ultraexecute-local` +(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" +# Writes .session-state.local.json with status=in_progress. +# Then in a fresh chat: /ultracontinue +``` + +Both arguments are required. No interactive prompt — headless-safe. + +### Typical flow + +```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 ... + +# (chat boundary — fresh Claude Code session) +/ultracontinue +# → reads state, prints 3-line summary, begins next session +``` + +--- + ## The full pipeline ``` @@ -584,7 +649,7 @@ Top-level layout: ``` ultraplan-local/ ├── agents/ 23 specialized agents (sonnet for exploration + review, opus for orchestration) -├── commands/ 5 slash commands (ultrabrief, ultraresearch, ultraplan, ultraexecute, ultrareview) +├── commands/ 6 slash commands (ultrabrief, ultraresearch, ultraplan, ultraexecute, ultrareview, ultracontinue) + ultraplan-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/)