b37b9383e9
Adds two sibling files in plugins/ultraplan-local/docs/ that together
specify a new /ultracontinue command for zero-friction multi-session
resumption — drafted from design dialogue at the end of the config-audit
v5.0.0 release session (5 sessions, ~10 manual NEXT-SESSION-PROMPT
context-handovers — friction this work removes).
ultracontinue-brief.md (159 lines):
- Follows the /ultrabrief-local template (frontmatter brief_version: 2.0)
so /ultraplan-local can consume it directly
- Defines per-project state-file convention .claude/projects/<project>/
.session-state.local.json as the contract; /ultracontinue is read-only,
multiple writers may update
- 10 falsifiable success criteria including cross-project consistency,
no-new-deps, validator + helper command, docs sweep across plugin
README + CLAUDE.md + marketplace root README
- 3 research topics: ultraexecute end-of-session integration depth,
graceful-handoff alignment (no hard dep), Claude Code slash-command
conventions for read+execute commands
- Explicit non-goals: not replacing /ultraexecute-local --resume, not
replacing graceful-handoff, not auto-orchestrating N sessions
- Open questions and assumptions flagged for plan-critic / scope-guardian
ultracontinue-design-notes.md (117 lines):
- Captures the dialogue rationale that shaped the brief, so the
implementing session has full context without needing to read this
conversation's transcript
- Origin (config-audit v5 release pain point), key design insight
("state-fil ER kontrakten, ikke verktøyet"), 6 design decisions with
alternatives considered, anti-patterns from KTG auto-memory to respect,
recommended reading order, expected scope (1-2 execution sessions)
No code changes. Brief is ready for /ultraplan-local --brief
plugins/ultraplan-local/docs/ultracontinue-brief.md (light path) or
/ultraresearch-local for full research path.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
117 lines
9.4 KiB
Markdown
117 lines
9.4 KiB
Markdown
# `/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.
|