ultra-builder-pro-cli 0.5.0

package/skills/ultra-init/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: ultra-init
+description: "Initialize Ultra Builder Pro project: detect context, confirm with user, scaffold .ultra/ via task.init_project, set up git."
+runtime: all
+mcp_tools_required:
+  - task.init_project
+cli_fallback: "task init-project"
+---
+
+# ultra-init — Phase 3.1
+
+把当前工作目录（或 `--target-dir`）初始化为一个 Ultra Builder Pro 项目：拉起
+`.ultra/` 骨架、写入 `tasks.json` 元数据、按需配 git。
+
+真实的目录搭建 + 模板拷贝 + tasks.json 注入统一由 **MCP tool `task.init_project`** 完成；
+MCP 不可达时回退 `ultra-tools task init-project`。
+
+## 设计要点（对比 pre-Phase-3 行为）
+
+- **无 Claude 独占依赖**：`task.init_project` + `ultra-tools init-project` 两条路径
+  都不调 Claude 原生工具，4 个 runtime 都能走通。
+- **模板内置**：`.ultra/` 骨架来自仓内 `templates/.ultra/`；不再依赖 `~/.claude/.ultra-template/`。
+- **幂等**：二次 init 默认拒绝，`--overwrite` 才会备份旧 `.ultra/` 为
+  `.ultra.backup.<ts>` 后重建。
+
+## Workflow
+
+### Step 0: 状态检测（skill 调用方做）
+
+在调 `task.init_project` 之前，调用方（Claude / CLI / SDK）需要先判断：
+
+- `target_dir/.ultra/` 是否已存在 → 决定是否需要 `overwrite=true`
+- `target_dir/.git/` 是否已存在 → 影响 Step 3 的分支
+- 读 `package.json` / `Cargo.toml` / `pyproject.toml` / `go.mod` 推断项目类型和栈
+- 如果调用方是 Claude，可在此用 `TaskCreate` 跟踪 Step 0–4 的 session 内进度
+  （这是 runtime 的 session-local 跟踪，不走 MCP）
+
+### Step 1: 补全参数
+
+入参不足时补：
+
+| 字段 | 缺省 |
+|------|------|
+| `project_name` | 当前目录名（`path.basename(target_dir)`） |
+| `project_type` | Step 0 识别结果；多技术栈 → `fullstack` |
+| `stack` | Step 0 识别到的依赖（逗号分隔多值，如 `react,express,postgres`） |
+| `git_init` | `.git/` 不存在 → 询问用户 |
+
+### Step 1.5: 交互确认（仅当检测到模糊或重入）
+
+触发条件：
+- `target_dir/.ultra/` 已存在（重入）
+- 识别到多项目类型（Web + API）
+- 显式 `--interactive` 标志
+
+交互渠道：
+- **Claude runtime**：调 `AskUserQuestion`（原生）
+- **其他 runtime**：使用 Host 原生提问界面；若当前表面不支持交互，
+  要求用户通过显式命令行参数选择
+
+确认 4 个问题：
+1. 项目类型（可多选，`detected` 标签打在识别项）
+2. 技术栈（可多选）
+3. 已有 `.git/` → 保留 / 重置备份 / 不用 git
+4. 已有 `.ultra/` → 覆盖（备份） / 保留 / 取消
+
+### Step 2: 调 `task.init_project` 拉起骨架
+
+**MCP 主路径**：
+```jsonc
+// call: task.init_project
+{
+  "target_dir": "/abs/path/to/project",
+  "project_name": "my-app",
+  "project_type": "fullstack",
+  "stack": "react,express,postgres",
+  "overwrite": false
+}
+// response
+{
+  "created_path": "/abs/path/to/project/.ultra",
+  "status": "created",
+  "copied_files": [
+    "specs/discovery.md", "specs/product.md", "specs/architecture.md",
+    "tasks/tasks.json", "tasks/contexts/TEMPLATE.md",
+    "docs/research/README.md",
+    "test-report.json", "delivery-report.json"
+  ]
+}
+```
+
+**CLI 回退路径**（`UBP_MCP=off` 或 MCP 调用返回网络错）：
+```bash
+ultra-tools task init-project \
+  --target-dir "$TARGET" \
+  --project-name "$NAME" \
+  --project-type "$TYPE" \
+  --stack "$STACK" \
+  $([ "$OVERWRITE" = "1" ] && echo --overwrite)
+```
+CLI 最后一行是 `{ "ok": true, "data": { ... } }`（见 spec/cli-protocol.md §2）。
+
+**错误处理**：
+- `ULTRA_DIR_EXISTS` → Step 1.5 重新询问是否 overwrite
+- `TEMPLATE_MISSING` → 致命；提示检查 `templates/.ultra/` 是否被 gitignore 吞了
+- `TARGET_NOT_DIR` / `VALIDATION_ERROR` → 返回调用方，修参数
+- `IO_ERROR` → retriable=true；最多重试 2 次
+
+### Step 3: Git 集成
+
+根据 Step 1.5 结果：
+
+- **初始化新仓**：`git init` + 写 `.gitignore`（排除 `.ultra/backups/`、`node_modules/`、
+  敏感文件等项目通用规则）+ 写基础 `README.md`（若不存在）。
+- **保留现有 `.git/`**：仅追加 `.gitignore` 里的 `.ultra/backups/` 一行（若缺失）。
+- **不用 git**：跳过。
+
+提示建议第一个 commit：`git add . && git commit -m "feat: initialize Ultra Builder Pro"`，
+但不代为执行（commit 是用户决策）。
+
+### Step 4: 成功总结 + 下一步
+
+用中文输出：
+- ✅ `.ultra/` 骨架（specs / tasks / docs / reports）
+- ✅ tasks.json 注入元数据（name / type / stack / created / updated）
+- ✅ git 状态（按选择）
+- ⚠️ **下一步**：跑 `/ultra-research` 做 17 步 discovery 填 spec；不要跳过直接 `/ultra-plan`
+
+## 调用方式（按 runtime）
+
+| Runtime | 调用形态 |
+|---------|----------|
+| Claude  | `/ultra-init [name] [type] [stack] [git]` — 命令薄壳拉起此 skill |
+| OpenCode | `/ultra-init …` 同上（agent frontmatter 小写化） |
+| Codex   | `codex exec "run /ultra-init …"`（Phase 4.4 adapter 接） |
+| Gemini  | `gemini --prompt "run /ultra-init …"`（Phase 4.5 extension 接） |
+
+## 输出锚点
+
+- `target_dir/.ultra/tasks/tasks.json` — project.name / project.type / project.stack 已注入
+- `target_dir/.ultra/specs/{discovery,product,architecture}.md` — 带 `[NEEDS CLARIFICATION]` 标记
+- 若 `overwrite=true`：`target_dir/.ultra.backup.<ts>/` 保存旧骨架
+
+## 不做的事
+
+- **不**创建业务 task（业务 task 由 `/ultra-plan` 在 spec 填完后批量创建）
+- **不**写入 state.db（state.db 由第一次 MCP 写操作或显式 `ultra-tools db init` 触发）
+- **不**调 web：离线可执行

package/skills/ultra-plan/SKILL.md

@@ -0,0 +1,314 @@
+---
+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."
+runtime: all
+mcp_tools_required:
+  - task.create
+  - task.parse_prd
+  - task.dependency_topo
+  - plan.export
+  - plan.get
+cli_fallback: "task create"
+---
+
+# ultra-plan — Phase 3.3
+
+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).
+
+## Prerequisites
+
+- `/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)
+
+## Workflow
+
+### Input Mode Selection (BEFORE Step 0)
+
+Two entry points lead into the planner:
+
+| 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 |
+
+---
+
+### 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), `dependencies` (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
+
+- 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,
+  "deps": [],
+  "tag": "<git branch>",              // optional
+  "trace_to": ".ultra/specs/product.md#US-01"
+}
+```
+
+**CLI fallback** (per task):
+```bash
+ultra-tools task create \
+  --title "Walking skeleton: …" --type architecture --priority P0 \
+  --complexity 4 --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`
+---
+```
+
+## Quality Standards
+
+- 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
+
+## Integration Points
+
+| | |
+|---|---|
+| **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` |
+
+## MCP → CLI fallback matrix
+
+| Purpose | MCP tool | CLI fallback |
+|---------|----------|--------------|
+| Scope mode prompt | none | current Host's native user-interaction surface |
+| Create task | `task.create` | `ultra-tools task create --title … --type … --priority …` |
+
+## What this skill DOES NOT do
+
+- Does NOT write state.db directly — all task writes go through `task.create`
+- Does NOT regenerate `tasks.json` — projector owns that
+- Does NOT start implementation — that's `/ultra-dev`
+- Does NOT re-run research — if specs are incomplete, redirects to `/ultra-research`

package/skills/ultra-research/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: ultra-research
+description: "Think-Driven Interactive Discovery - Deep research with step-file architecture for high-density output"
+user-invocable: true
+---
+
+# Ultra Research v2 — Step-File Architecture
+
+## Overview
+
+Transform vague ideas into complete, high-confidence specifications through progressive interactive discovery. Each research step is a self-contained instruction file loaded just-in-time for maximum LLM attention density.
+
+**Philosophy**: Research is collaborative. Each decision validated with user before proceeding. All findings must have 90%+ confidence. Every claim needs a source.
+
+## WORKFLOW ARCHITECTURE
+
+### Core Principles
+
+- **Step-File Design**: Each step is a self-contained .md file with full execution instructions
+- **Just-In-Time Loading**: Only the current step file is in context — never load future steps
+- **Sequential Enforcement**: Steps must be completed in order, no skipping
+- **Write-Immediately**: Every step writes its output to the spec file BEFORE presenting to user
+- **User Gate**: User must explicitly confirm [C] Continue before proceeding to next step
+- **State Tracking**: Track per-session progress via the runtime's native TaskCreate/TaskUpdate (session-local). Research does NOT write business tasks to state.db — it only emits spec files. Business tasks are created later by `/ultra-plan` via MCP `task.create`.
+- **Web-First**: Every analysis step REQUIRES web search with citations. No search = no proceed.
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order
+3. **SEARCH FIRST**: Execute web searches BEFORE generating analysis
+4. **WRITE IMMEDIATELY**: Append content to spec file as soon as analysis is complete
+5. **WAIT FOR INPUT**: Present [C] Continue — halt and wait for user selection
+6. **LOAD NEXT**: When user confirms, Read the next step file and follow it
+
+### Critical Rules (NO EXCEPTIONS)
+
+- NEVER load multiple step files simultaneously
+- ALWAYS read entire step file before execution
+- NEVER skip steps or optimize the sequence
+- ALWAYS write output to spec file before presenting to user
+- ALWAYS halt at [C] Continue and wait for user input
+- NEVER proceed without user confirmation
+- NEVER rely solely on training data — web search is mandatory for factual claims
+
+## STEP SEQUENCE
+
+### Round 0: Product Discovery & Strategy
+
+| Step | File | Focus | Output |
+|------|------|-------|--------|
+| 00 | `step-00-problem-validation.md` | Validate the problem is real and worth solving | discovery.md §0 |
+| 01 | `step-01-opportunity-discovery.md` | Opportunity Solution Tree (Teresa Torres) | discovery.md §1 |
+| 02 | `step-02-market-assessment.md` | TAM/SAM/SOM with dual approach | discovery.md §2 |
+| 03 | `step-03-competitive-landscape.md` | Competitors + Porter's Five Forces | discovery.md §3 |
+| 04 | `step-04-product-strategy.md` | Vision, segments, value prop, trade-offs | discovery.md §4 |
+| 05 | `step-05-assumptions-validation.md` | Risk assumptions + experiment design | discovery.md §5 |
+
+### Round 1: User & Scenario Discovery
+
+| Step | File | Focus | Output |
+|------|------|-------|--------|
+| 10 | `step-10-user-personas.md` | 2-3 personas with goals, pain points, context | product.md §1-2 |
+| 11 | `step-11-user-scenarios.md` | 3-5 user scenarios with trigger/flow/outcome | product.md §3 |
+
+### Round 2: Feature Definition
+
+| Step | File | Focus | Output |
+|------|------|-------|--------|
+| 20 | `step-20-user-stories.md` | User stories with acceptance criteria | product.md §4 |
+| 21 | `step-21-features-scope.md` | Feature prioritization + explicit exclusions | product.md §5 |
+| 22 | `step-22-success-metrics.md` | Business + user metrics with targets | product.md §6 |
+
+### Round 3: Architecture Design
+
+| Step | File | Focus | Output |
+|------|------|-------|--------|
+| 30 | `step-30-architecture-context.md` | Quality goals, constraints, system context | architecture.md §1-3 |
+| 31 | `step-31-solution-strategy.md` | Tech stack selection with rationale | architecture.md §4 |
+| 32 | `step-32-building-blocks.md` | Module decomposition + runtime scenarios | architecture.md §5-6 |
+
+### Round 4: Quality & Deployment
+
+| Step | File | Focus | Output |
+|------|------|-------|--------|
+| 40 | `step-40-deployment.md` | Infrastructure, environments, CI/CD | architecture.md §7-9 |
+| 41 | `step-41-quality-risks.md` | Quality scenarios, risks, tech debt | architecture.md §10-12 |
+
+### Synthesis
+
+| Step | File | Focus | Output |
+|------|------|-------|--------|
+| 99 | `step-99-synthesis.md` | Distillate + validation + quality summary | research-distillate.md |
+
+## ACTIVATION
+
+When invoked, follow this sequence:
+
+### 1. Pre-Research Check
+
+- If `.ultra/specs/product.md` has [NEEDS CLARIFICATION] → proceed with research
+- If `.ultra/specs/` doesn't exist → suggest `/ultra-init` first
+- If specs 100% complete → suggest skip to `/ultra-plan`
+
+### 2. Project Type Detection
+
+Ask user to determine research scope:
+
+| Type | Steps | Focus |
+|------|-------|-------|
+| Full Project | 00-99 | All rounds |
+| Product Only | 00-22 | Discovery + product |
+| Feature Only | 10-22 | User scenarios + features (skip discovery) |
+| Architecture Change | 30-41 | Architecture + deployment |
+| Custom | User selects | Specific steps |
+
+**Round 0 skip conditions**: Skip if user provides existing market research, validated strategy docs, or explicitly states "I already know the market".
+
+### 3. Begin Step Execution
+
+Read the first applicable step file:
+```
+Read: skills/ultra-research/steps/step-{NN}-{name}.md
+```
+
+Follow every instruction in that file. When the step is complete and user confirms [C], read the next step file.
+
+### 4. Output Files
+
+| File | Content |
+|------|---------|
+| `.ultra/specs/discovery.md` | §0-5: Problem, Opportunities, Market, Competition, Strategy, Assumptions |
+| `.ultra/specs/product.md` | §1-6: Problem, Personas, Scenarios, Stories, Scope, Metrics |
+| `.ultra/specs/architecture.md` | §1-12: arc42 structure |
+| `.ultra/specs/research-distillate.md` | Token-efficient summary for /ultra-plan consumption |
+| `.ultra/docs/research/*.md` | Per-round research reports |
+
+## QUALITY STANDARDS
+
+| Element | Requirement |
+|---------|-------------|
+| Sources | Every factual claim has URL citation |
+| Confidence | 90%+ for recommendations |
+| Code | Production-ready (no TODO/demo) |
+| Trade-offs | Quantified pros/cons |
+| Next steps | Specific, actionable items |
+
+## COMPLETION
+
+Research is complete when:
+- All selected steps have [C] confirmed by user
+- All spec files have no [NEEDS CLARIFICATION] markers
+- Research distillate generated
+- All recommendations have 90%+ confidence
+
+**Next**: Run `/ultra-plan` to generate task breakdown from complete specs.