docs(ultraplan-local): document /ultracontinue in README + CLAUDE
- 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.
This commit is contained in:
Kjell Tore Guttormsen
parent
d893a46e41
commit
1dad53a1e4
2 changed files with 82 additions and 11 deletions
|
|
@ -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 <path>`)
|
||||
- `lib/validators/{brief,research,plan,progress,session-state}-validator.mjs` — schema validators with CLI shims (`node lib/validators/X.mjs --json <path>`)
|
||||
- `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 `<project-dir>` 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).
|
||||
|
|
|
|||
|
|
@ -1,12 +1,12 @@
|
|||
# ultraplan-local — Brief, Research, Plan, Execute, Review
|
||||
# ultraplan-local — Brief, Research, Plan, Execute, Review, Continue
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
*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/<project>/.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 <project-dir>` | 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/)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue