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

/ultracontinue — Design Notes

Companion to: ultracontinue-brief.md (sibling file in this folder). Captured: 2026-05-01, end of config-audit v5.0.0 release session. Purpose: Preserve the dialogue rationale that shaped the brief so a fresh session (with no memory of the discussion) can plan + execute with full context. Read this AFTER the brief, not instead of it.

---

Why this work exists (origin)

The brief was drafted immediately after shipping config-audit v5.0.0 — a 5-session release run (alpha.1 → alpha.2 → beta.1 → rc.1 → release) executed across 5 fresh Claude Code sessions. Each session ended with KTG (or Claude on KTG's behalf) hand-writing a NEXT-SESSION-PROMPT.local.md file containing the canonical "paste this into the next session" prompt. Each session began with KTG manually reading + invoking that prompt.

The pattern works (v5 shipped clean, 635 tests, SC-6b PASS at -0.85% delta) but is operator-driven: ~10 manual context-handover steps across the run, each a candidate for omission, copy errors, or stale-file risk.

Initial Q from KTG: "Er det formalisert i ultraexecute-local at NEXT-SESSION-PROMPT.local.md er mekanismen for å lage en ny prompt til neste sesjon?"

Investigation found: No, it is not. NEXT-SESSION-PROMPT.local.md references in the ultraplan-local plugin tree exist only in historical project artifacts (.claude/projects/2026-04-18-v3.0-skill-factory-ekstraksjon/). The convention lives in KTG's auto-memory (feedback_session_handoff_prompt.md, feedback_next_session_prompt_manual.md) — not in any tool. /ultraexecute-local has its own multi-session model via session specs (YAML manifests + --session N flag), but that's for scripted/headless runs, not interactive multi-session.

KTG's framing of the goal: "Jeg ønsker at det blir så enkelt å kjøre X antall sesjoner i sekvens slik at samme kommando kan kjøres for hver eneste sesjon for å redusere mental belastning, og jeg ønsker at dette blir likt mellom alle sesjoner."

That's the load-bearing constraint: identical command, every session, every project.

---

The key design insight

The brief's Goal section reads "state-filen ER kontrakten" — that phrase came out of dialogue and is the load-bearing decision.

Initial framing was "build a /ultracontinue skill that wraps a state-write helper". The problem with that framing: it ties the consistency promise to a specific writer. If /ultraexecute-local writes the state file but a manual session series (like the v5 release) doesn't, the convention is broken in the cases that matter most.

Reframing: the state file is the contract, not the writer. /ultracontinue reads a documented JSON convention. ANY tool, helper command, or operator-driven session-end may write to it. Loose coupling. The convention is what's universal, not the integration depth into any one command.

This shifts the work-shape from "build one big integration" to "(1) define the convention, (2) build the reader, (3) build writers wherever they make sense — including a tiny manual-session helper that doesn't require touching /ultraexecute-local at all". SC-4 (full ultraexecute integration) becomes optional/follow-up rather than a v1.0 blocker.

---

Decisions and alternatives

1. Where does /ultracontinue live?

Decision: ultraplan-local plugin.

Alternative considered: graceful-handoff plugin (since it already deals with "save state, restart in new context").

Reasoning: graceful-handoff solves intra-session context-budget rescue (one project's session is hitting token limits, dump and restart). /ultracontinue solves planned multi-session execution (this is session 3 of 5 in a release run). Different problems sharing convention surface. ultraplan-local is the natural home because multi-session planning is part of its remit (see --decompose, session-spec template, --session N flag).

KTG noted graceful-handoff "trenger det også for konsistens" — captured in brief as Topic 2 of the research plan. Convergence is desirable but not blocking; /ultracontinue must work standalone.

2. State scope: per-project vs global

Decision: Per-project. .claude/projects/<project>/.session-state.local.json.

Alternative considered: ~/.claude/active-session.json (one active project at a time, machine-global).

Reasoning: KTG explicit: "Per prosjekt". Global has the same single-active-project assumption baked in but breaks if KTG context-switches. Per-project also matches existing ultraplan-local convention (briefs, plans, progress.json all live under .claude/projects/<project>/).

3. UX: prompt before starting next session?

Decision: No interactive prompt. Show 3-line summary (project / next-session-label / brief-path), then start executing.

Alternative considered: Y/N prompt ("Run session 3 now?").

Reasoning: From dialogue: "Maksimalt brukervennlig = ingen prompts, men la informasjon synes." Y/N is friction. Information visibility matters; gating on confirmation does not. If KTG wants to abort, Ctrl+C. Brief codifies this in NFRs.

4. State-file format: JSON vs YAML

Decision (assumption in brief): JSON.

Reasoning: Parity with progress.json already in ultraplan-local. Mechanical validator parity. Marked as [ASSUMPTION] so plan-critic / scope-guardian can flag if there's a strong case for YAML during planning.

5. Command name: /ultracontinue vs /ultraplan-local continue vs /continue

Decision: /ultracontinue (KTG choice).

Reasoning: Muscle-memory parity with the four existing ultra-commands (/ultrabrief-local, /ultraresearch-local, /ultraplan-local, /ultraexecute-local). /continue is risky (potential collision with Claude Code builtins — flagged as open question in brief).

6. Single command for N sessions, or N invocations?

Decision: N invocations. Each /ultracontinue advances exactly ONE session.

Alternative considered: "auto-run all remaining sessions."

Reasoning: Multi-session exists precisely because context resets between sessions are valuable. Compaction-survival, fresh perspective, no token-budget rot. Running N sessions in one go destroys the reason multi-session exists. Captured in brief as explicit non-goal.

---

What's NOT in the brief but worth knowing

1. Anti-pattern flagged in KTG's auto-memory: feedback_next_session_prompt_manual.md says "Ikke foreslå auto-loading via SessionStart/CLAUDE.md. Manuell invokasjon unngår stale-fil-risiko." /ultracontinue respects this — it's still operator-invoked. The improvement is that the file the operator loads is mechanically defined and validated, not a hand-written prompt that may have drifted from reality.

2. Existing handover-contracts pattern: docs/HANDOVER-CONTRACTS.md already documents 5 handovers (brief→research, research→plan, architecture→plan, plan→execute, progress.json). Adding .session-state.local.json as Handover 6 is the natural placement and SC-6 in the brief codifies it.

3. Plan-critic / scope-guardian risks to anticipate:

   • Plan-critic will likely push on SC-4 (ultraexecute integration depth). The brief positions this as "may land in a follow-up" — defend that framing or accept it lands in v1.0 if the research finds the insertion points are clean.
   • Scope-guardian may flag SC-5 (helper command) as scope creep if ultraplan-local doesn't already have an end-session slash. It's NEW surface but justified by the "informal multi-session" use case (v5 release). Plan should make this trade-off explicit.

4. The v5 release run is the canonical motivating example. When in doubt, ask: "would this have removed friction in the 5-session config-audit v5 run?" If no, scope it out. If yes, scope it in.

5. Token-budget realism: This brief is being created at the END of a 250K-context conversation that already shipped v5.0.0. The implementer of /ultracontinue will be a fresh session with this brief + design-notes + handover-contracts as context. Keep that in mind when writing the plan — front-load decisions, minimize cross-references that require reading more files than necessary.

---

Recommended next steps for the implementing session

1. Read in this order: ultracontinue-brief.md → ultracontinue-design-notes.md (this file) → docs/HANDOVER-CONTRACTS.md (just the structure, to know where Handover 6 fits) → commands/ultraexecute-local.md end-of-session sections (for SC-4 scoping).

2. Decide research path:

   • Light research path (recommended if context-budget is a concern): skip topics 1 and 2, run only Topic 3 (Claude Code slash-command conventions) since 1 and 2 are largely answerable from local code-reading during planning. /ultraresearch-local --external "..." for Topic 3 alone.
   • Full research path: run all 3 as suggested in the brief.

3. Plan with /ultraplan-local --brief plugins/ultraplan-local/docs/ultracontinue-brief.md (or --project .claude/projects/2026-05-01-ultracontinue if you set up a project dir for the research outputs first).

4. Expect 1-2 execution sessions. Small surface area: validator + reader-command + helper writer + docs sweep + tests. Not a multi-session epic — meta-irony noted (the work to ship /ultracontinue itself doesn't need /ultracontinue).

5. Don't forget the marketplace root README — KTG conventions: every plugin doc-affecting change updates plugin README + plugin CLAUDE.md + root marketplace README. Brief's SC-7 codifies this.