From 43cdc0b968c487820fdc4b5254a4538dc61a05cb Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Fri, 1 May 2026 20:49:01 +0200 Subject: [PATCH] feat(ultraplan-local): add /ultracontinue command for multi-session resumption [skip-docs] MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reads .claude/projects//.session-state.local.json (Handover 7), narrates a 3-line summary, and immediately begins executing the next session — no interactive confirmation, headless-safe. Phases: - 0: --help (self-documenting per brief NFR) - 1: resolve project dir (auto-discover via node -e enumeration) - 2: validate via session-state-validator - 3: narrate (project / next_session_label / brief path) - 4: read brief and begin - 5: stats [skip-docs] rationale: README + CLAUDE.md updates land in Step 11 (Session 2b) per plan structure. Step 8 (docs:) updates HANDOVER-CONTRACTS.md and the doc-consistency test pin in the same session. Co-Authored-By: Claude Opus 4.7 --- .../commands/ultracontinue-local.md | 161 ++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 plugins/ultraplan-local/commands/ultracontinue-local.md diff --git a/plugins/ultraplan-local/commands/ultracontinue-local.md b/plugins/ultraplan-local/commands/ultracontinue-local.md new file mode 100644 index 0000000..b3e3853 --- /dev/null +++ b/plugins/ultraplan-local/commands/ultracontinue-local.md @@ -0,0 +1,161 @@ +--- +name: ultracontinue-local +description: Resume the next session in a multi-session ultraplan project. Reads .session-state.local.json and immediately begins the next session. +argument-hint: "[ | --help]" +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 +(`.claude/projects//.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`). +This command only reads. + +Pipeline position: + +``` +/ultraplan-local → plan.md +/ultraexecute-local → progress.json + .session-state.local.json +... session boundary, fresh chat ... +/ultracontinue → reads .session-state.local.json, starts next session +``` + +See **Handover 7** in `docs/HANDOVER-CONTRACTS.md` for the full schema. + +## Phase 0 — `--help` handling + +If `$ARGUMENTS` contains `--help` or `-h`, print the usage block below and exit +cleanly. Do NOT proceed to any further phase. + +``` +/ultracontinue — Resume the next session in a multi-session ultraplan project. + +Usage: + /ultracontinue # auto-discover state file under cwd + /ultracontinue # explicit project directory + /ultracontinue --help # this message + +Reads .claude/projects//.session-state.local.json (per-project, +gitignored). On a valid resumable state, prints a 3-line summary and begins +executing the next session immediately. No interactive confirmation prompt. + +State-file schema (v1): + schema_version 1 + project string + next_session_brief_path string (validator soft-checks file existence) + next_session_label string + status in_progress | partial | failed | stopped | completed + (completed → no further sessions to resume) + updated_at ISO-8601 timestamp + (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 + ... (fresh Claude chat) ... + /ultracontinue # reads session-state, runs next session +``` + +## Phase 1 — Resolve project directory + +If `$ARGUMENTS` is non-empty and not `--help`/`-h`, treat the first positional +argument as the explicit ``. Otherwise auto-discover via Bash by +enumerating `.claude/projects/*/.session-state.local.json` paths with `node -e` +(NOT shell glob — harness-mode safety): + +```bash +!`node -e "const fs=require('fs'),path=require('path');const root='.claude/projects';if(!fs.existsSync(root))process.exit(0);const dirs=fs.readdirSync(root).map(d=>path.join(root,d,'.session-state.local.json')).filter(p=>fs.existsSync(p));dirs.forEach(p=>process.stdout.write(p+'\\n'));"` +``` + +Decision tree: + +- **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. + ``` +- **1 candidate (or explicit arg):** continue to Phase 2 with that path. +- **>1 candidates and no explicit arg:** print all paths sorted by `updated_at` + descending, instruct the user to disambiguate via explicit ``, + then exit: + ``` + Multiple active multi-session projects found: + .claude/projects//.session-state.local.json updated + .claude/projects//.session-state.local.json updated + Re-run as: /ultracontinue + ``` + +## Phase 2 — Validate the state file + +Run the validator from a Bash invocation: + +```bash +!`node lib/validators/session-state-validator.mjs --json {state-file-path}` +``` + +Interpret the result: + +- **Validator exit code != 0 OR `valid: false` in JSON output:** print the + structured `errors[]` (each `[code] message` on its own line) and exit. Do not + proceed to narration. Suggest running the validator directly for follow-up: + `node lib/validators/session-state-validator.mjs `. +- **`valid: true` AND any warning has `code: SESSION_STATE_NOT_RESUMABLE`** (i.e. + `status: completed`): print "no further sessions to resume; project complete" + and exit cleanly. +- **`valid: true` AND status is one of `in_progress | partial | failed | stopped`:** + proceed to Phase 3. + +## Phase 3 — Narrate 3-line summary + +Print this exact template (using values from the validated `parsed` object): + +``` +Project: {project} +Next session: {next_session_label} +Brief: {next_session_brief_path} +``` + +No interactive confirmation prompt — per the brief NFR ("ingen prompts, men la +informasjon synes"). The 3-line block is informational only. + +## Phase 4 — Begin execution + +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. + +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 +disk. Cannot continue automatically.` and exit. Do not guess. + +## Phase 5 — Stats tracking + +Append a one-line JSON record to `${CLAUDE_PLUGIN_DATA}/ultracontinue-stats.jsonl` +if the env var is set; silently skip otherwise. + +```json +{"ts":"","project":"","next_session_label":"