ultra-builder-pro-cli 0.9.0 → 0.10.0

package/skills/ultra-plan/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ultra-plan
-description: "Generate task breakdown from complete specs OR from a raw PRD (Phase 8A). Scope-mode-aware; writes state.db via task.create or task.parse_prd; projector generates tasks.json + contexts/*.md."
+description: "Turn a validated baseline, active delta, or approved PRD into fresh-context vertical slices with public seams and exact verification contracts."
+user-invocable: true
 runtime: all
 mcp_tools_required:
   - task.create
@@ -8,322 +9,101 @@ mcp_tools_required:
   - task.dependency_topo
   - plan.export
   - plan.get
+  - change.get
+  - change.context
+  - change.breadcrumb
 ---
 
-# ultra-plan — Phase 3.3
+# ultra-plan — Fresh-Context Execution Planning
 
-Transform validated `.ultra/specs/` into an executable task plan. **state.db is
-the authority** (D32): every new task is created via MCP `task.create`; the
-projector regenerates `.ultra/tasks/tasks.json` and context-md frontmatter
-automatically. Context-md bodies are written by this skill (not projector).
+Produce a dependency-valid plan whose tasks can be executed in isolated contexts.
+`.ultra/state.db` is authoritative; the projector owns task JSON and context
+frontmatter.
 
-## Authority failure boundary
+## Failure boundary
 
-Before planning, call a state-backed MCP tool. If the MCP server is missing,
-unreachable, or returns any authority error, stop before creating tasks. In
-particular, `LEGACY_STATE_MIGRATION_REQUIRED` means the project still has a
-non-empty v4.4 projection; tell the user to run:
+Start with a state-backed MCP read. On `LEGACY_STATE_MIGRATION_REQUIRED`, stop and
+instruct:
 
 ```bash
 ultra-tools migrate --from=4.4 --to=4.5 --source-dir <project-root>
 ```
 
-Never read or write `.ultra/tasks/tasks.json` as a fallback. It is a generated
-projection, not an alternate task store. There is no task-mutation CLI fallback.
+Never read or write `.ultra/tasks/tasks.json` as authority. If task MCP mutation is
+unavailable, stop; there is no task-creation CLI fallback.
 
-## Prerequisites
+## Inputs
 
-- `/ultra-research` completed — specs must be 100% (no `[NEEDS CLARIFICATION]`)
-- `.ultra/specs/product.md` + `.ultra/specs/architecture.md` exist
-- `.ultra/specs/research-distillate.md` preferred when present (token-efficient)
+Choose exactly one:
 
-## Workflow
+- validated baseline specs under `.ultra/specs/`;
+- one active change packet (`intent.md`, `delta/`, `plan.md`);
+- raw PRD using the approval-gated direct mode below.
 
-### Workflow activation
+Ask only for a product or risk decision that cannot be derived from current evidence.
+Record assumptions explicitly; unresolved material assumptions block planning.
 
-At entry, write `.ultra/workflow-state.json` with
-`{"command":"ultra-plan","task_id":"plan","step":"0","status":"active","ts":"<ISO8601>"}`.
-This activates the workflow-only hooks. Mark it terminal only after the MCP
-task writes and verification complete.
+## Planning rules
 
-### Input Mode Selection (BEFORE Step 0)
+1. Trace acceptance through a live entry point, domain behavior, side effects, and a
+   user-observable/public seam.
+2. Prefer a walking skeleton / `tracer_bullet` before horizontal layers.
+3. Make each task completable in a fresh context: one outcome, bounded references,
+   explicit dependencies, and one deterministic verification command.
+4. Keep the default context packet at or below 12 files, 12k approximate tokens, and
+   40% of the fresh context budget.
+5. Use `expand_contract` only when a wider change is approved and cannot be split
+   without losing correctness.
+6. Create integration checkpoints at real seams, not after arbitrary task counts.
+7. Include error, recovery, documentation, and migration work in the task that owns
+   the behavior; do not create unreachable scaffolding tasks.
 
-Two entry points lead into the planner:
+## Task contract
 
-| Mode | When | Path |
-|------|------|------|
-| **Spec Mode** (default) | `.ultra/specs/` exists and `/ultra-research` is complete | Steps 0–7 below |
-| **PRD Direct** (Phase 8A) | User hands you a raw PRD (path or inline text) and wants to skip the spec layer | see **PRD Direct Workflow** below |
+Every `task.create` must carry or be paired with:
 
----
-
-### PRD Direct Workflow (Phase 8A — human-gated artifact)
-
-For a one-shot PRD → task graph pipeline with approval gate:
-
-1. **Dry-run parse** (no state.db writes):
-   ```jsonc
-   // MCP
-   { "tool": "task.parse_prd", "args": { "prd_path": "<path>", "dry_run": true, "tag": "<branch>" } }
-   ```
-   Returns `{ tasks: [...], topo: [[...],[...]] }` without touching state.db.
-
-2. **Build execution plan** (in-memory via the server's `plan-builder`):
-   The server composes `computeWaves` + `files_modified` overlap + `pricing.computeCost`
-   into a plan with `waves`, `ownership_forecast`, `conflict_surface`, and
-   estimated cost / duration.
-
-3. **Human gate** — ask through the current Host's native user-interaction
-   surface with the plan summary and estimated cost:
-   - `approve` → re-run `task.parse_prd` **with `dry_run: false`** to commit
-     tasks, then `plan.export { out_path: ".ultra/execution-plan.json" }`
-     to land the artifact and emit the `plan_approved` event.
-   - `reject` → **do not** call the non-dry-run path. No state.db rows, no
-     artifact. Prompt user for PRD revision and loop.
-
-4. **Post-approval** — the artifact at `.ultra/execution-plan.json` is the
-   source of truth for Phase 8B orchestration (wave-by-wave dispatch).
-   Use `plan.get { section: "topo" | "conflicts" | "all" }` to inspect
-   without re-reading the file.
-
-**AC guarantees**:
-- `reject` path performs zero state.db writes (dry_run=true on parse).
-- `approve` path emits exactly one `plan_approved` event, tied to the
-  persisted artifact path.
-- Task IDs returned by the dry-run and the final persisted tasks are
-  identical (parser is deterministic given the same LLM output).
-
----
-
-### Step 0 — Scope Mode Selection
-
-Ask the user which posture this plan takes. **Commit once selected — do not
-drift silently.**
-
-| Mode | Posture | Use when |
-|------|---------|----------|
-| **EXPAND** | "What would make this 10x better for 2x effort?" — surface stretch opportunities | Greenfield, user wants to think bigger |
-| **SELECTIVE** (default) | Baseline scope held; optional expansions surfaced individually | Most common; feature work on existing product |
-| **HOLD** | Scope locked; make it bulletproof; catch every failure mode | Requirements clear, need execution depth |
-| **REDUCE** | Find the minimum viable version; cut ruthlessly | MVP, time pressure, PoC |
-
-Use the current Host's native picker. If that Host has no structured picker,
-present the choices directly and require an explicit answer.
-
-**Dual-scale effort** on every EXPAND/SELECTIVE expansion decision:
-`Complete: ~X LOC, AI ~Y min | Shortcut: ~X LOC, saves Y min but ___`
-
-### Step 1 — Specification Completeness Validation (BLOCK gate)
-
-Read specs and check field-by-field. **Fail loud** — don't generate a plan
-against broken specs.
-
-**discovery.md** (if present):
-- §0 Problem Validation has demand signal + confidence %
-- §2 Market Assessment has TAM/SAM/SOM with numbers + sources
-- §3 Competitive Landscape has ≥2 competitors compared
-- §4 Product Strategy has ≥3 trade-offs
-
-**product.md**:
-- §2 Personas: ≥2 with goals + pain points
-- §3 Scenarios: ≥3 with current + desired flow
-- §4 User Stories: acceptance criteria in Given/When/Then
-- §5 Feature Scope: Features Out section with rationale
-- §6 Success Metrics: North Star has numeric target
-
-**architecture.md**:
-- §1 Quality Goals: ≥3 measurable scenarios
-- §4 Solution Strategy: tech stack with URL-cited rationale
-- §5 Building Blocks: modules map to features
-- §6 Runtime Scenarios: ≥1 with data flow
-
-**Fail if**: `[NEEDS CLARIFICATION]` markers present / file missing / checklist fails.
-On fail → instruct user to run `/ultra-research` targeting the gap.
-
-### Step 2 — Requirements + Codebase Analysis
-
-**Requirements extraction** (prefer distillate):
-- Functional requirements (product.md §4)
-- Technical constraints (architecture.md §2)
-- Quality requirements (architecture.md §10)
-- Success metrics (product.md §6)
-
-**Codebase analysis** (for AI-executable context):
-- Directory structure (src/ tests/ config/)
-- Existing patterns worth referencing
-- Tech stack detection (framework versions, test runners)
-- Naming conventions
-
-### Step 3 — Task Generation
-
-#### tasks.json schema (v4.5 projection, source in state.db)
-
-Fields per task: `id`, `title` (action verb + target), `type`
-(architecture/feature/bugfix), `priority` (P0-P3), `complexity` (1-10),
-`status` (pending initially), `deps` (task IDs), `estimated_days`,
-`context_file`, `trace_to` (spec section anchor).
-
-#### Integration tasks — MANDATORY inserts
-
-1. **Walking Skeleton — always Task #1, P0, type=architecture**
-   - Title: "Walking skeleton: {primary use case} end-to-end"
-   - Must touch every layer: entry → use case → domain → persistence
-   - Acceptance: one real request returns real data through all layers
-
-2. **Contract Definition** (when specs show component boundaries)
-   - Title: "Define contract: {component A} ↔ {component B}"
-   - Must PRECEDE implementation tasks on both sides
-   - Acceptance: shared interface/schema + contract test
-
-3. **Integration Checkpoint** — every 3-4 feature tasks
-   - Title: "Integration checkpoint: verify {feature group} connectivity"
-   - Acceptance: components from recent tasks communicate end-to-end
-
-#### Task granularity
+- outcome and acceptance assertions;
+- priority, complexity, dependencies, and ownership paths;
+- linked `change_id` when planning a delta;
+- `slice_kind`: `tracer_bullet`, `expand_contract`, or `integration_checkpoint`;
+- `public_seam`;
+- exact `verification_command`;
+- required context references and their reasons;
+- expected red/green signal for fixes and incidents;
+- documentation impact.
 
-- Ideal complexity: 3-5 (one-session completable)
-- Too large (>6) → split
-- Too small (<3) → merge
-- Context budget: target 40% per task; max 8 files touched; complexity ≥7 must split
-
-### Step 4 — Dependency Analysis
-
-- Build dependency graph from each task's `deps` list
-- Detect cycles (DFS with visited + recursion stack) — cycles are **fatal**
-- Topological order → surface parallel opportunities
-- Vertical slicing check: flag any task touching only one layer → split or merge
-- Walking skeleton blocks all feature tasks
-- Contract tasks precede their consumer implementations
-
-### Step 5 — Persist via MCP `task.create`
-
-For **each** task in the planned list (topological order):
-
-```jsonc
-// MCP call per task
-{
-  "id": "1",                          // optional; server mints uuid if omitted
-  "title": "Walking skeleton: …",
-  "type": "architecture",
-  "priority": "P0",
-  "complexity": 4,
-  "estimated_days": 2,
-  "deps": [],
-  "tag": "<git branch>",              // optional
-  "trace_to": ".ultra/specs/product.md#US-01"
-}
-```
-
-After each `task.create`, the server auto-runs the projector — `tasks.json`
-and `contexts/task-{id}.md` (frontmatter only) appear.
-
-Create one task per `task.create` call so every write is schema-validated and
-projected through the same live MCP contract.
-
-### Step 5.5 — Context-md body (skill responsibility)
-
-Projector writes the frontmatter; this skill writes the body. For each task,
-write `.ultra/tasks/contexts/task-{id}.md` body (projector preserves it):
-
-```markdown
-## Context
-**What**: …
-**Why**: … (Persona/Scenario link)
-**Constraints**: - …
-
-## Implementation
-**Target Files**: - path/to/file.ts (create|modify: desc)
-**Pattern**: …
-**Tech Notes**: …
-
-## Acceptance
-**Tests**: - [ ] `test cmd`
-**Verification**: ```bash …```
-
-## Trace
-**Source**: `.ultra/specs/product.md#US-01`
-
-## Change Log
-| Date | Change | Specs Updated | Reason |
-|------|--------|---------------|--------|
-
-## Completion
-> _Filled when task completed by /ultra-dev_
-```
-
-### Step 6 — Plan Verification (BLOCKING)
-
-Run programmatic checks **before** presenting to user:
-
-| Check | Severity | Action on fail |
-|-------|----------|----------------|
-| Every user story (US-XX) mapped to ≥1 task via `trace_to` | CRITICAL | create missing task or flag |
-| Dependency graph acyclic | CRITICAL | report cycle chain, block |
-| `trace_to` points at real spec anchor | WARN | suggest correction |
-| Tasks with complexity ≥7 | WARN | suggest split |
-| Tasks touching >8 files | WARN | suggest split |
-| Total tasks >20 | WARN | suggest phased delivery |
-| Per-task complexity × 5% context > 40% | WARN | split recommended |
-
-All CRITICAL pass → present to user (Step 7). Any CRITICAL fail → auto-fix or surface.
-
-### Step 7 — Report + Next Steps
-
-Summary output:
-- Total tasks, priority distribution (P0/P1/P2), complexity histogram
-- Dependency edge count, parallel-track count
-- Estimated total effort (sum of `estimated_days`)
-- Requirement coverage % (stories mapped / stories total)
-- First task details (Walking Skeleton)
-- Suggest `/ultra-dev`
-
-### Continuation block (MANDATORY)
-
-```markdown
----
-## ▶ Next Up
-**Start Development** — TDD workflow on Task #1: {Walking Skeleton title}
-
-`/clear` then `/ultra-dev`
-
----
-**Also available**: `/ultra-status`
----
-```
+After each task is persisted, compile `change.context` with `role=plan` and
+`gate=planning` when it belongs to a change. A blocked readiness result must be fixed
+before the task is called executable.
 
-## Quality Standards
+## Spec mode / change mode
 
-- 100% requirement coverage (every user story mapped)
-- Clear acceptance criteria per task
-- No circular dependencies
-- Realistic complexity (justifiable in review)
-- Action-verb titles
-- Walking Skeleton is Task #1
-- Every feature task is a vertical slice (≥2 layers)
-- Integration checkpoint every 3-4 feature tasks
-- Contract tasks precede cross-boundary implementations
+1. Read the smallest authoritative references that define acceptance.
+2. Build a task DAG in memory and check file-ownership conflicts.
+3. Present the outcome, order, cost/risk concentration, and walking-skeleton seam.
+4. Obtain approval when the plan materially changes scope or cost.
+5. Persist tasks through `task.create`.
+6. Call `task.dependency_topo`; cycles or missing dependencies are blocking.
+7. Call `plan.export`, then verify it with `plan.get` rather than reparsing the file.
+8. For an active change, call `change.breadcrumb` and report its one next action.
 
-## Integration Points
+## PRD direct mode
 
-| | |
-|---|---|
-| **Prerequisite** | `/ultra-research` — specs 100% complete |
-| **Input** | `.ultra/specs/research-distillate.md` (primary), `product.md`, `architecture.md`, `discovery.md` |
-| **Writes** | state.db via `task.create`; context-md bodies |
-| **Output (projected)** | `.ultra/tasks/tasks.json`, `.ultra/tasks/contexts/task-*.md` |
-| **Next** | `/ultra-dev` |
+1. Call `task.parse_prd` with `dry_run: true`.
+2. Show the proposed vertical slices, topology, conflict surface, and estimated cost.
+3. Require explicit approval. Rejection performs no state write.
+4. On approval, repeat the same parse with `dry_run: false`, then `plan.export`.
+5. Verify dry-run and persisted task ids match; mismatch is a deterministic failure.
 
-## MCP failure matrix
+## Context body
 
-| Purpose | MCP tool | Failure behavior |
-|---------|----------|------------------|
-| Scope mode prompt | none | current Host's native user-interaction surface |
-| Create task | `task.create` | stop; surface the MCP error; never write a projection |
+Human-readable task context may explain intent, acceptance, seam, red/green signal,
+and relevant references. It must not duplicate entire specs, provider memory, or a
+static codebase tour. The next worker should be able to begin from the manifest and
+verify the slice without recovering the planner's full conversation.
 
-## What this skill DOES NOT do
+## Completion gate
 
-- Does NOT write state.db directly — all task writes go through `task.create`
-- Does NOT regenerate `tasks.json` — projector owns that
-- Does NOT read `tasks.json` when MCP state is empty or unavailable
-- Does NOT start implementation — that's `/ultra-dev`
-- Does NOT re-run research — if specs are incomplete, redirects to `/ultra-research`
+Planning is complete only when the DAG is valid, every task is reachable through a
+public seam, every command is executable, every change-linked task has a ready Context
+Manifest v2 snapshot, and no required documentation or decision is unknown.