ktg-plugin-marketplace/plugins/ultraplan-local/docs/ultracontinue-brief.md

type	brief_version	created	task	slug	project_dir	research_topics	research_status	auto_research	interview_turns	source
ultrabrief	2.0	2026-05-01	Add /ultracontinue command for zero-friction multi-session resumption	ultracontinue	.claude/projects/2026-05-01-ultracontinue/	3	pending	false	0	manual

Task: /ultracontinue — Zero-Friction Multi-Session Resumption

Drafted manually 2026-05-01 from KTG/Claude design dialogue after the config-audit v5.0.0 release run (5 sessions, ~40 turns of NEXT-SESSION-PROMPT.local.md handoffs). Brief follows the /ultrabrief-local template for consistency with the rest of the ultraplan-local pipeline, but was not produced through the interview — it is a hand-written design brief. /ultraplan-local should still be able to consume it.

Intent

Multi-session execution today (e.g. config-audit v5.0.0's 5-session release run) requires KTG to manually maintain a NEXT-SESSION-PROMPT.local.md at the end of every session and copy-paste its contents into the next fresh Claude Code session. This works but adds two friction points per session: (1) at session-end, decide what context the next session needs and write it; (2) at session-start, locate the file and paste it. Across a 5-session run that's 10 manual context-handover steps, each prone to omission, copy errors, or stale state. The NEXT-SESSION-PROMPT.local.md convention is captured in KTG's auto-memory as feedback_session_handoff_prompt.md but is not formalized in any tool — it lives entirely in operator discipline.

The opportunity: a single command, identical across all projects, that bootstraps the next session with zero thinking. KTG starts a fresh Claude session, types /ultracontinue, and the right context loads. End of friction.

Goal

A new /ultracontinue command in the ultraplan-local plugin that reads a per-project state file (.claude/projects/<project>/.session-state.local.json), shows a 3-line summary (project, next-session label, brief path), and immediately begins executing the next session. Works whether the previous session was driven by /ultraexecute-local (formal pipeline) or executed manually turn-by-turn (informal pipeline like the v5.0.0 release run). The state file is the contract — any session-end mechanism may write to it, and /ultracontinue only reads.

Non-Goals

• Replace /ultraexecute-local --resume. That flag resumes a SINGLE session from a progress.json checkpoint after a crash. /ultracontinue advances to the NEXT session in a multi-session plan. They are complementary, not overlapping.
• Replace graceful-handoff. That plugin solves context-budget rescue (dump state when current session approaches its token limit). /ultracontinue solves planned multi-session continuation. They MAY share the state-file convention as a consistency win, but /ultracontinue must work standalone without graceful-handoff installed.
• Auto-orchestrate the entire multi-session run from one command. /ultracontinue advances ONE session per invocation. Running 5 sessions back-to-back requires 5 invocations across 5 fresh Claude sessions (which is the point — context resets between them).
• Replace NEXT-SESSION-PROMPT.local.md retroactively. Existing projects mid-flight may keep using it. The new command works alongside it; migration is opt-in per project.
• Build a session scheduler / cron / background runner. Out of scope. KTG starts each session manually.

Constraints

• Per-project state file. Path: .claude/projects/<project>/.session-state.local.json. Gitignored by default. No global state.
• No hard dependency on graceful-handoff. /ultracontinue must work in projects/repos where graceful-handoff is not installed.
• Works for both formal and informal multi-session flows. Formal = /ultraexecute-local writes the state file as part of its standard end-of-session contract. Informal = a tiny helper command (or KTG manually) writes the state file at end of a manual session series like the v5.0.0 release run.
• Zero new external dependencies. Plain node:fs JSON read. No npm packages.
• Cross-platform. Node .mjs script, no shell-isms; works on macOS / Linux / Windows.
• Convention is documented in docs/HANDOVER-CONTRACTS.md — same place as the brief/research/plan/progress.json contracts already live. The state file gets a sixth handover entry.

Preferences

• State file IS the contract. /ultracontinue reads it; multiple writers can update it. Loose coupling > tight coupling to a specific writer.
• Minimal state-file schema. project, next_session_brief_path, next_session_label, status, updated_at. Everything else is optional metadata.
• No interactive prompts in /ultracontinue startup. Show summary, start. If KTG wants to abort, Ctrl+C. Per dialogue: "ingen prompts, men la informasjon synes".
• Match existing ultraplan-local skill structure. New command file at commands/ultracontinue-local.md, no agents needed (deterministic file read), follow existing frontmatter conventions.
• Match existing handover-validator pattern. Add lib/validators/session-state-validator.mjs for the new contract; CLI returns {valid, errors[], warnings[], parsed}.

Non-Functional Requirements

• Cold-start latency: < 500ms from /ultracontinue invocation to "begin executing session" output.
• Failure mode is obvious. Missing state file → tell user "no active multi-session project here; start with /ultrabrief-local or /ultraplan-local". Malformed state file → tell user the validation error and where to fix it.
• Idempotent. Running /ultracontinue twice in the same session does not advance state. State only advances when the SESSION completes (writer's responsibility).
• Self-documenting. First-time user can /ultracontinue --help and understand the model without reading other docs.
• Zero secrets in the state file. Status, paths, labels — never API keys, never user content beyond filenames.

Success Criteria

Falsifiable, command-checkable:

• SC-1: A new project with .claude/projects/<project>/.session-state.local.json containing the documented schema can be resumed via /ultracontinue from a fresh Claude session, and the correct brief loads. Verified by running the command in a fixture project and asserting the loaded content.
• SC-2: /ultracontinue invoked in a directory with no state file emits a helpful message (not a stack trace) pointing at /ultrabrief-local / /ultraplan-local as the entry points. Verified: exit cleanly with informative stderr.
• SC-3: The session-state-validator CLI exists at lib/validators/session-state-validator.mjs and returns {valid:true, errors:[], warnings:[], parsed:{...}} for a well-formed file; structured errors with stable codes for malformed files. Verified via fixture-backed tests.
• SC-4: /ultraexecute-local writes the state file at end-of-session — both for explicit session-spec runs (--session N) and for formal session-strategy plans. Verified: after a session completes, .session-state.local.json exists and points at next session. (May land in a follow-up step if it requires significant ultraexecute restructure.)
• SC-5: A /ultraplan-local end-session (or equivalent) helper exists for INFORMAL multi-session flows like the v5.0.0 release run — single command writes the state file pointing at the next session brief. Verified: invocation produces a valid state file the validator accepts.
• SC-6: docs/HANDOVER-CONTRACTS.md has a "Handover 6 — .session-state.local.json" entry with producer, consumer, path conventions, schema, body invariants, validation strategy, versioning, and failure modes. Verified: file exists with the section heading.
• SC-7: Plugin README.md, CLAUDE.md, and root marketplace README.md document /ultracontinue in command tables. Verified: grep finds the command name in all three.
• SC-8: Cross-project consistency: running /ultracontinue in two different projects (config-audit-style and any greenfield project) shows identical output structure (project / next-session-label / brief-path / "Begin?"-equivalent narration). Verified by manual diff or fixture-based test.
• SC-9: Tests: at least 1 unit test for the validator, 1 integration test for the command's load+narrate flow, 1 negative test (missing file), 1 negative test (malformed file). Plugin's node --test 'tests/**/*.test.mjs' stays green.
• SC-10: No new external dependencies in package.json or any new node_modules/ directory created by this work. Verified: git diff package.json shows no dependencies change; find . -name node_modules -not -path '*/tests/fixtures/*' returns no new entries.

Research Plan

Three research topics. Topics 1 and 2 are local (codebase-only); topic 3 is light external (verify Anthropic / Claude Code conventions).

Topic 1: /ultraexecute-local end-of-session integration depth

• Why this matters: Per dialogue: "ultraexecute-local må være 100% konsekvent for hvordan den fullfører hver eneste sesjon". The state file's reliability depends on EVERY session-end path writing it. This research scopes how invasive that change is.
• Research question: "Where in commands/ultraexecute-local.md does end-of-session occur, and what fewest-touch insertion points guarantee state-file write across (a) successful session, (b) failed session with manual abort, (c) compaction-survival recovery, (d) --session N explicit single-session runs?"
• Suggested invocation: /ultraresearch-local --project .claude/projects/2026-05-01-ultracontinue --local "Where in ultraexecute-local does end-of-session occur, and what fewest-touch insertion points guarantee state-file write across all session-end paths?"
• Required for plan steps: ultraexecute-local code edits; failure-mode handling; whether SC-4 lands in v1.0 or follow-up
• Confidence needed: high
• Estimated cost: standard — agent swarm
• Scope hint: local

Topic 2: graceful-handoff plugin alignment

• Why this matters: The two plugins solve adjacent problems and SHOULD share the state-file convention without making graceful-handoff a hard dep. This research determines whether graceful-handoff writes a similar file today, what schema it uses, and whether convergence is one-sided (graceful-handoff adopts ultraplan's schema) or mutual (both align on a v1 schema co-published in ultraplan-local).
• Research question: "Does graceful-handoff already produce a session-state file, what is its schema, and what is the minimum-friction path to make it write to the same .session-state.local.json convention without imposing a hard dependency from /ultracontinue on graceful-handoff?"
• Suggested invocation: /ultraresearch-local --project .claude/projects/2026-05-01-ultracontinue --local "Does graceful-handoff produce a session-state file? What schema? Convergence path?"
• Required for plan steps: SC-5 helper command design; whether graceful-handoff gets a docs note in its README pointing at the convention
• Confidence needed: medium
• Estimated cost: quick — inline research
• Scope hint: local (both plugins are in this repo)

Topic 3: Claude Code slash-command conventions for read+execute commands

• Why this matters: /ultracontinue reads state then immediately starts work. We need to verify that this pattern (no AskUserQuestion, just narrate-and-go) matches Claude Code's UX expectations and doesn't trip any guardrails (e.g. auto-approval behavior in plan mode, hook ordering, allowed-tools list for the slash command).
• Research question: "What are Claude Code's documented conventions for slash commands that read state and immediately begin a multi-step task without user confirmation, and what allowed-tools / model / frontmatter pattern do similar commands use?"
• Suggested invocation: /ultraresearch-local --project .claude/projects/2026-05-01-ultracontinue --external "What are Claude Code's documented conventions for slash commands that read state and immediately begin a multi-step task without user confirmation?"
• Required for plan steps: commands/ultracontinue-local.md frontmatter + behavior section
• Confidence needed: medium
• Estimated cost: quick — docs lookup
• Scope hint: external

Open Questions / Assumptions

• [ASSUMPTION] State-file format .session-state.local.json is JSON, not YAML — matches progress.json convention from ultraplan-local. Could be YAML for human-edit-friendliness, but JSON has mechanical-validator advantages and parity with existing progress.json.
• [ASSUMPTION] State file is gitignored via the existing *.local.* pattern (already in most plugin .gitignore files including config-audit). No new gitignore entry needed.
• [QUESTION] Should /ultracontinue accept an optional <project-dir> arg for projects not at the cwd? Default is "find .claude/projects/<...>/.session-state.local.json reachable from cwd". Argument override = nice-to-have.
• [QUESTION] Should the state file track ALL completed sessions (history), or just last + next? Minimal contract = last + next. History is metadata that can grow as needed without breaking compat.
• [QUESTION] Naming — /ultracontinue vs /ultraplan-local continue vs /continue. KTG decision in dialogue: /ultracontinue for muscle-memory parity with the other ultra-prefixed commands. Plan should confirm no global Claude Code /continue builtin collides.
• [QUESTION] What's the upgrade path for projects that already have NEXT-SESSION-PROMPT.local.md (config-audit historical, ultraplan-local historical)? Backward compat = /ultracontinue could read either if state-file is missing. Or simpler: documented manual migration ("write a state file pointing at your existing NEXT-SESSION-PROMPT").

Prior Attempts

• NEXT-SESSION-PROMPT.local.md manual convention. Captured in KTG's auto-memory (feedback_session_handoff_prompt.md and feedback_next_session_prompt_manual.md). Used heavily in config-audit v5.0.0 release (5 sessions). Worked, but operator-driven — KTG must remember to invoke it at session-start AND write it at session-end. The auto-memory entry feedback_next_session_prompt_manual.md explicitly notes: "Ikke foreslå auto-loading via SessionStart/CLAUDE.md. Manuell invokasjon unngår stale-fil-risiko." This brief addresses the friction without re-introducing the stale-file risk: /ultracontinue is still operator-invoked, but the state file is mechanically validated and the load is deterministic.

• /ultraexecute-local --session N flag. Already exists and works for HEADLESS / scripted multi-session runs via session specs. Does not address the INTERACTIVE multi-session case where each session is a fresh Claude Code chat.

• graceful-handoff plugin. Solves a different problem (intra-session context-budget rescue). Pattern overlap exists; this brief proposes alignment without dependency.

Metadata

• Created: 2026-05-01
• Interview turns: 0 (manual brief from design dialogue)
• Auto-research opted in: no — research is suggested but KTG decides
• Source: manual

---

How to continue

Manual (recommended for this brief — research is light and the planning happens once):

# Run the three research topics (order does not matter):
/ultraresearch-local --project .claude/projects/2026-05-01-ultracontinue --local "Where in ultraexecute-local does end-of-session occur, and what fewest-touch insertion points guarantee state-file write across all session-end paths?"
/ultraresearch-local --project .claude/projects/2026-05-01-ultracontinue --local "Does graceful-handoff produce a session-state file? What schema? Convergence path?"
/ultraresearch-local --project .claude/projects/2026-05-01-ultracontinue --external "What are Claude Code's documented conventions for slash commands that read state and immediately begin a multi-step task without user confirmation?"

# Then plan:
/ultraplan-local --project .claude/projects/2026-05-01-ultracontinue

# Then execute (likely 1-2 sessions; not large enough to need /ultracontinue itself):
/ultraexecute-local --project .claude/projects/2026-05-01-ultracontinue

Skip-research path (faster, lower confidence): /ultraplan-local --brief plugins/ultraplan-local/docs/ultracontinue-brief.md directly. Will ship /ultracontinue with assumptions noted and SC-4 (ultraexecute integration) likely deferred to follow-up.