@enderfga/claw-orchestrator 3.7.1 → 4.0.0

package/dist/src/ultraapp/versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../../src/ultraapp/versions.ts"],"names":[],"mappings":"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"}

package/openclaw.plugin.json

@@ -98,7 +98,21 @@
       "ultraplan_start",
       "ultraplan_status",
       "ultrareview_start",
-      "ultrareview_status"
+      "ultrareview_status",
+      "ultraapp_list",
+      "ultraapp_get",
+      "ultraapp_status",
+      "ultraapp_new",
+      "ultraapp_answer",
+      "ultraapp_add_file",
+      "ultraapp_spec_edit",
+      "ultraapp_build_start",
+      "ultraapp_build_cancel",
+      "ultraapp_feedback",
+      "ultraapp_promote_version",
+      "ultraapp_start_container",
+      "ultraapp_stop_container",
+      "ultraapp_delete"
     ]
   },
   "skills": ["skills/SKILL.md"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enderfga/claw-orchestrator",
-  "version": "3.7.1",
+  "version": "4.0.0",
   "description": "Claw Orchestrator — run Claude Code, Codex, Gemini, Cursor Agent, OpenCode and custom coding CLIs as one unified runtime. Drop into Hermes Agent, Claude Desktop, Cursor, Cline, Continue, Zed, Windsurf, Goose or any Model Context Protocol (MCP) host, install as an OpenClaw plugin, or run standalone. Persistent sessions, multi-agent council, ultraplan, ultrareview, autoloop, tool orchestration.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -92,6 +92,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^12.1.0",
+    "diff": "^9.0.0",
     "re2": "^1.24.0"
   },
   "peerDependencies": {
@@ -99,6 +100,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.15.0",
+    "@types/diff": "^7.0.2",
     "@types/node": "^22.10.0",
     "@vitest/coverage-v8": "^3.1.0",
     "eslint": "^9.15.0",

package/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: claw-orchestrator
-description: Manage persistent coding sessions across Claude Code, Codex, Gemini, Cursor, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, switching models/tools at runtime, or exposing the orchestrator's 41 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "autonomous iteration", "iterate until goal", "deep paper review", "auto research", "switch model", "multi-agent", "coding session", "session inbox", "cursor agent", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol".
+description: Manage persistent coding sessions across Claude Code, Codex, Gemini, Cursor, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, ultraapp building deployable web apps from a structured Q&A interview, switching models/tools at runtime, or exposing the orchestrator's 55 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "ultraapp", "Forge tab", "build a web app", "one-click app", "AppSpec", "autonomous iteration", "iterate until goal", "deep paper review", "auto research", "switch model", "multi-agent", "coding session", "session inbox", "cursor agent", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol".
 metadata:
   {
     "openclaw":
@@ -43,7 +43,7 @@ metadata:
 
 # Claw Orchestrator Skill
 
-Claw Orchestrator — persistent multi-engine coding session manager for claw-style agent systems. Runs as a standalone CLI/server, with first-class OpenClaw plugin support. Wraps Claude Code, Codex, Gemini, Cursor Agent, OpenCode, and custom CLIs into headless agentic engines with 35 tools.
+Claw Orchestrator — persistent multi-engine coding session manager for claw-style agent systems. Runs as a standalone CLI/server, with first-class OpenClaw plugin support. Wraps Claude Code, Codex, Gemini, Cursor Agent, OpenCode, and custom CLIs into headless agentic engines with 55 tools.
 
 ## Engine Quick Reference
 

package/skills/references/autoloop.md

@@ -5,7 +5,7 @@ the **Planner** to design a plan; on your approval, the Planner spawns the
 **Coder** + **Reviewer** subloop, monitors it, and pushes you (wechat →
 whatsapp → email fallback chain) only when something needs your attention.
 
-Design rationale: `tasks/autoloop.md`. This page is the operator reference.
+This page is the operator reference.
 
 ## When to use
 

package/skills/references/mcp.md

@@ -1,6 +1,6 @@
 # MCP integration
 
-Claw Orchestrator ships a Model Context Protocol (MCP) server (`clawo-mcp`) so any MCP-compatible host can drive its 41 tools.
+Claw Orchestrator ships a Model Context Protocol (MCP) server (`clawo-mcp`) so any MCP-compatible host can drive its 55 tools.
 
 This document covers:
 
@@ -229,7 +229,7 @@ The engines themselves (`claude`, `codex`, `gemini`, `agent`, `opencode`) must a
 
 ## Tool filtering
 
-41 tools is a lot for a small context window. Reduce noise either at the host level (most hosts have an `include` / `exclude` filter — see Hermes example above) or at the server level via `CLAWO_MCP_TOOLS`:
+55 tools is a lot for a small context window. Reduce noise either at the host level (most hosts have an `include` / `exclude` filter — see Hermes example above) or at the server level via `CLAWO_MCP_TOOLS`:
 
 ```bash
 CLAWO_MCP_TOOLS="session_start,session_send,session_stop,council_start,council_status" clawo-mcp

package/skills/references/tools.md

@@ -414,3 +414,186 @@ Get status and findings when completed.
 | Parameter | Type | Required |
 |-----------|------|----------|
 | `id` | string | yes |
+
+---
+
+## Autoloop (6)
+
+Three-agent autonomous iteration loop (Planner / Coder / Reviewer) over a git workspace. See [`autoloop.md`](./autoloop.md) for the operator reference (push policy, ledger layout, smoke test).
+
+### `autoloop_start`
+
+Start an autoloop run. Planner is created persistent; Coder + Reviewer are spawned by the Planner once `plan.md` is ready.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `cwd` | string | yes | Workspace (must be a git repo) |
+| `goal` | string | yes | High-level user goal in natural language |
+| `model` | string | | Planner model (default Opus) |
+| `coderModel` | string | | Coder subagent model |
+| `reviewerModel` | string | | Reviewer subagent model |
+| `maxIters` | number | | Cap on Coder/Reviewer rounds (default 50) |
+| `pushChannels` | string[] | | Notification channels (`wechat`, `whatsapp`, `email`) |
+
+### `autoloop_chat`
+
+Send a message into the Planner conversation (e.g. answer a clarifying question, refine the plan, kick off the subloop).
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+| `message` | string | yes |
+
+### `autoloop_status`
+
+Get current state, phase, recent inbox messages, and ledger summary.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `autoloop_list`
+
+List active and recent autoloop runs (in-memory + on-disk registry, deduped by run_id).
+
+(no params)
+
+### `autoloop_reset_agent`
+
+Reset one of the subagent sessions (Coder or Reviewer) without losing Planner state — useful when a subagent loops on a stale belief.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | yes | Run id |
+| `agent` | `'coder'` \| `'reviewer'` | yes | Which subagent to reset |
+
+### `autoloop_stop`
+
+Terminate the run. All sessions are stopped and ledger state is finalised.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+---
+
+## Ultraapp (14)
+
+Forge tab — turn a structured Q&A interview into a deployed web app reachable at `localhost:19000/forge/<slug>/`. See [`ultraapp.md`](./ultraapp.md) for the operator reference (lifecycle, conventions §1–§7, runtime modes, file layout, HTTP routes).
+
+### `ultraapp_list`
+
+List all ultraapp runs.
+
+(no params)
+
+### `ultraapp_get`
+
+Full snapshot of a run: spec + chat + state.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_status`
+
+Lightweight status (mode + timestamps).
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_new`
+
+Create a fresh run. Optionally seeds the interview with the user's first message.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `firstMessage` | string | | Free-form opening line; the interview Opus reads it before its first question |
+
+### `ultraapp_answer`
+
+Submit an answer to the current interview question.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | yes | Run id |
+| `value` | string | yes | One of the question's `options[].value`, or `''` when using freeform |
+| `freeform` | string | | Free-form text when none of the options fit |
+
+### `ultraapp_add_file`
+
+Upload a sample file to `examples/` (the interview engine will `extract_metadata` it).
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+| `path` | string | yes |
+| `content` | string \| Buffer | yes |
+
+### `ultraapp_spec_edit`
+
+Apply RFC 6902 JSON Patch ops to the AppSpec mid-interview.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+| `patch` | object[] | yes |
+
+### `ultraapp_build_start`
+
+Validate the spec strictly (shape + cross-refs + DAG) and enqueue the build. Council picks it up FIFO.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_build_cancel`
+
+Abort an active build. Council sessions are stopped and the worktrees are left as-is for inspection.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_feedback`
+
+Done-mode feedback. Haiku classifier routes into `cosmetic` (Opus patcher), `spec-delta` (focused interview + auto-rerun), or `structural` (suggest fresh run).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | yes | Run id |
+| `text` | string | yes | The feedback (1+ chars) |
+
+### `ultraapp_promote_version`
+
+Atomically swap the deployed version. Stops the current container/process, starts the target's, updates the router map.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | yes | Run id |
+| `version` | string | yes | Target version label (`v1`, `v2`, …) |
+
+### `ultraapp_start_container`
+
+Start the container/process for the active version (no-op if already running).
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_stop_container`
+
+Stop the container/process without deleting any state.
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |
+
+### `ultraapp_delete`
+
+Stop + remove the run completely (sessions, container, on-disk state, router entry).
+
+| Parameter | Type | Required |
+|-----------|------|----------|
+| `id` | string | yes |

package/skills/references/ultraapp.md

@@ -0,0 +1,203 @@
+# ultraapp — Reference
+
+Turn a structured Q&A interview into a deployed web app reachable at
+`localhost:19000/forge/<slug>/`. The dashboard's **Forge** tab and a
+14-tool MCP surface drive the end-to-end loop: interview → 3-agent
+council → fix-on-failure → deploy → done-mode feedback.
+
+This page is the operator reference. The interview behavioural contract
+lives in [`skills/ultraapp/SKILL.md`](../ultraapp/SKILL.md). The
+council architectural conventions every generated app must satisfy live
+in [`src/ultraapp/conventions.ts`](../../src/ultraapp/conventions.ts).
+
+## When to use
+
+- You have a workflow in your head (or a sample input file) and want a
+  shareable web app for it without writing code.
+- You want to iterate cosmetically on a deployed app via chat ("make
+  the button green", "shrink the hero h1") without touching the
+  codebase yourself.
+- You want to evolve the AppSpec ("also output a thumbnail") and
+  rebuild without restarting the interview.
+
+## Lifecycle
+
+```text
+interview ─► queued ─► building ─► build-complete ─► deploying ─► done
+                                                                    │
+                                                                    ▼
+                                                              done-mode chat
+                                                              (cosmetic /
+                                                               spec-delta /
+                                                               structural)
+```
+
+| Mode | Meaning |
+|------|---------|
+| `interview` | AppSpec being filled by Q&A. Chat input goes to the interview Opus. |
+| `queued` | Build accepted, waiting for a slot in the FIFO build queue. |
+| `building` | Council writing code, fix-on-failure driving install/build/test. |
+| `build-complete` | Codebase ready, awaiting `deploy` step. |
+| `deploying` | Container/process being started, router map being updated. |
+| `done` | App live at `/forge/<slug>/`. Chat input now goes to the done-mode classifier. |
+| `failed` | Council didn't reach consensus, or fix-on-failure couldn't get the build green. |
+
+## Architectural conventions (§1–§7)
+
+Every generated app MUST satisfy these. They're embedded in the council
+super-task prompt verbatim from `src/ultraapp/conventions.ts`.
+
+| § | Topic | Headline rule |
+|---|-------|---------------|
+| 1 | Path-based deploy | Mount at `BASE_PATH=/forge/<slug>/`; in-app links MUST be relative. |
+| 2 | Async file-queue runtime | Exact endpoints: `GET /`, `POST /run`, `GET /status/:jobId`, `GET /result/:jobId`, `GET /health`. File-based job queue under `$DATA_DIR/jobs/<jobId>/`. NO database. Data path from `process.env.DATA_DIR ?? '/data'`. |
+| 3 | BYOK | If `runtime.needsLLM`, API keys live in browser localStorage and are sent direct to the provider. The server MUST NEVER receive the key (enforced by `eslint-plugin-no-server-keys`). |
+| 4 | Dockerfile + smoke test | Single multi-stage Dockerfile, `npm run smoke` drives one full job in < 90s using `examples[0].ref`. |
+| 5 | Council voting protocol | 3 agents in git worktrees, all-YES vote required, max 8 rounds. |
+| 6 | Tech stack | Modern TypeScript / JavaScript framework (Next.js, Vite + Hono, SvelteKit). NO Python, NO pure SSGs. |
+| 7 | **Frontend quality** | **Real styling system + real type hierarchy + four-state coverage on every async surface + drag-and-drop forms + appropriate result presentation + one deliberate theme.** §7g requires every agent to capture Chrome-headless screenshots at 1440×900 AND 375×812 and visually inspect the PNGs before voting YES — source-code review is explicitly insufficient evidence. |
+
+## Runtime modes
+
+```bash
+clawo serve --ultraapp-runtime host    # default
+clawo serve --ultraapp-runtime docker  # opt-in
+```
+
+| Mode | Build | Run | Pros | Cons |
+|------|-------|-----|------|------|
+| `host` | `npm install && npm run build` | `npm start` (detached, `setsid`-equivalent) | Zero extra deps; works anywhere Node works; faster start. | No process isolation; deps installed under the user. |
+| `docker` | `docker build .` | `docker run -d --restart unless-stopped` | Per-app isolation, restart policy, image is the artefact. | Requires a running Docker daemon. |
+
+Both modes allocate a backend port in `[19100, 19999]`. The reverse-
+proxy router runs at port `19000` (auto-fallback up to `19099` if
+taken) and maps `/forge/<slug>/*` to the right backend. Slug→port map
+persists to `~/.claw-orchestrator/_router.json`. Host-mode pid metadata
+persists to `~/.claw-orchestrator/host-procs.json`.
+
+## File layout (per run)
+
+```text
+~/.claw-orchestrator/ultraapps/<runId>/
+├── spec.json                  # current AppSpec (latest)
+├── spec.history.jsonl         # every accepted update_spec patch
+├── chat.jsonl                 # all chat turns (interview + done-mode)
+├── state.json                 # { runId, mode, createdAt, updatedAt }
+├── examples/                  # uploaded sample files
+├── data/                      # passed to host-mode app as DATA_DIR
+├── council-project/           # fresh git repo the council collaborates in
+│   ├── .worktrees/{agent-A,agent-B,agent-C}/
+│   └── (council code, merged to main on consensus)
+└── versions/
+    ├── v1/
+    │   ├── codebase/          # snapshot of council main HEAD
+    │   └── artifact.json      # { worktreePath, builtAt, deploy: { url, port, … } }
+    └── v2/                    # patcher / spec-delta produces v2, v3, …
+```
+
+## HTTP routes (drive headlessly)
+
+All routes are served by the embedded server (default `:18796`), under
+`Authorization: Bearer <token>` from `~/.openclaw/server-token`.
+
+| Method + path | Purpose |
+|----|----|
+| `GET /ultraapp/list` | All runs with mode + createdAt. |
+| `POST /ultraapp/new` | Body: `{ firstMessage?: string }`. Returns `{ runId }`. |
+| `GET /ultraapp/<id>` | Full snapshot: spec + chat + state. |
+| `POST /ultraapp/<id>/answer` | Body: `{ value, freeform? }`. Submit interview answer. |
+| `POST /ultraapp/<id>/spec-edit` | Body: RFC 6902 patch ops. Edit the spec mid-interview. |
+| `POST /ultraapp/<id>/files` | Multipart upload to `examples/`. |
+| `GET /ultraapp/<id>/events` | SSE stream of build/chat events (mode pill, narrator, council activity). |
+| `POST /ultraapp/<id>/build` | Validate spec strictly + enqueue. |
+| `POST /ultraapp/<id>/build/cancel` | Abort the active build. |
+| `GET /ultraapp/<id>/artifacts` | List `versions/vN/`. |
+| `POST /ultraapp/<id>/start` | Start the deployed container/process for the active version. |
+| `POST /ultraapp/<id>/stop` | Stop without deleting. |
+| `POST /ultraapp/<id>/delete` | Stop + remove all per-run state. |
+| `POST /ultraapp/<id>/feedback` | Body: `{ text }`. Done-mode classifier routes cosmetic / spec-delta / structural. |
+| `POST /ultraapp/<id>/promote-version` | Body: `{ version: "vN" }`. Atomically swap deployed version. |
+
+## MCP tools (14)
+
+Same surface as HTTP, callable from any Model Context Protocol host
+(Claude Desktop, Hermes Agent, Cursor, Cline, Continue, Zed,
+Windsurf, Goose). Param schemas in [`tools.md`](./tools.md#ultraapp).
+
+```text
+ultraapp_list           ultraapp_get             ultraapp_status
+ultraapp_new            ultraapp_answer          ultraapp_add_file
+ultraapp_spec_edit      ultraapp_build_start     ultraapp_build_cancel
+ultraapp_feedback       ultraapp_promote_version
+ultraapp_start_container ultraapp_stop_container ultraapp_delete
+```
+
+## Done-mode feedback classification
+
+After the run reaches `done`, chat input goes to a per-run Haiku
+classifier. Three classes:
+
+| Class | Routes to | Behaviour |
+|-------|-----------|-----------|
+| `cosmetic` | Patcher | Opus generates a unified diff against the deployed worktree → `applyUnifiedDiff` → validate via fix-on-failure → on success snapshot to `versions/vN+1/`, on any failure restore the snapshot atomically and post the reason to chat. |
+| `spec-delta` | Focused interview | Flips mode back to `interview` with a bootstrap message that names the field(s) being changed. Completion auto-triggers a fresh `startBuild`. |
+| `structural` | Suggestion only | Posts a narrator note: "this sounds like a different app — click + New". |
+
+To swap which version is live, use `promote-version` (HTTP) or
+`ultraapp_promote_version` (MCP) — the router map and host-procs map
+update atomically.
+
+## Reference traces + replay
+
+5 captured JSONL traces of real interviews ground-truth the interview
+engine against drift:
+
+```text
+src/__tests__/fixtures/ultraapp-traces/
+├── text-summariser.jsonl      (synthetic, simple text in/out)
+├── image-batch-resize.jsonl   (batch upload + Pillow + zip)
+├── vlog-cut.jsonl             (ffmpeg + whisper + branching DAG)
+├── llm-agent-pipeline.jsonl   (BYOK, multi-step LLM)
+├── branching-dag.jsonl        (parallel paths converging)
+├── _format.md                 (trace JSONL schema)
+└── expected/<name>.appspec.json   (frozen target)
+```
+
+```bash
+tsx test-ultraapp-integration.ts --trace=image-batch-resize
+tsx test-ultraapp-integration.ts --trace=all
+```
+
+The `spec-extraction-quality.test.ts` test replays each trace through
+the interview engine and asserts the resulting `AppSpec` matches the
+frozen snapshot — any future engine or skill drift fails this test.
+
+## Operator quick start
+
+```bash
+# 1. Boot
+clawo serve   # dashboard at :18796, ultraapp router at :19000
+open "http://127.0.0.1:18796/dashboard?token=$(cat ~/.openclaw/server-token)"
+
+# 2. Forge tab → + New → walk through the interview
+
+# 3. After [Start Build] (or POST /ultraapp/<id>/build), watch:
+#      mode pill: queued → building → done
+#      narrator: short conversational chat updates
+#      Versions panel: v1, v2, … with Promote per row
+
+# 4. Live URL appears in the share card. The deployed app is reachable at:
+curl http://127.0.0.1:19000/forge/<slug>/health
+```
+
+## Known limitations (v4.0.0)
+
+- The done-mode patcher loop occasionally hangs between
+  feedback-classification and the patcher Opus session creation;
+  cosmetic changes can be applied manually until the underlying race
+  is fixed.
+- The §7g frontend gate currently relies on per-agent honesty about
+  running the screenshot capture; agents that skip the inspection can
+  still pass the smoke gate. A follow-up will plumb a server-side
+  screenshot validator into the council verifier so the gate becomes
+  structurally enforced rather than persona-enforced.

package/skills/ultraapp/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: ultraapp-interview
+description: Use when the user opens a Forge tab in the claw-orchestrator dashboard to start building a new ultraapp. Drives a structured Q&A interview that produces a complete AppSpec, then signals readiness to build.
+---
+
+# ultraapp interview
+
+You are interviewing a user who wants to turn a workflow they already have in their head (or an example they uploaded) into a deployable web application. Your job is to fill in their `AppSpec` by asking one question at a time. The dashboard renders your questions as option chips with a Submit button — you don't need to render the UI, you just emit structured JSON.
+
+## Behavioural contract
+
+1. **One question per turn.** Never ask two things in one turn. If you need a multi-part answer, ask the parts in sequence.
+2. **Always emit a structured question envelope** (see schema below). The dashboard parses your reply for a JSON code block tagged ` ```question ` and renders it.
+3. **Always provide a recommended option.** The user's default move is "submit your recommendation". Make it the right one.
+4. **Provide 3–4 plausible options.** Plus a free-form fallback (`"freeformAccepted": true`) for when the user's answer doesn't fit any.
+5. **Cite context.** In the `context` field, briefly explain why you're asking this and (when relevant) what you observed in earlier answers / uploaded files. This is what builds trust.
+6. **Update the spec after every answer.** Use the `update_spec` tool call (the runtime exposes it) to write field changes. Don't batch; write incrementally.
+7. **Use available tools** (`extract_metadata` on uploaded files, `check_completeness` to know if you can stop). Don't guess metadata you can read.
+8. **Tool call + question in the same reply is encouraged.** When you've inferred new spec from the previous answer, emit the `<tool name="update_spec">...</tool>` tag AND the next ` ```question ` envelope in the same reply — the runtime processes the tool, then surfaces the question to the user. This is the normal pattern for keeping the interview moving; **don't** wait for a tool_result roundtrip just to emit the next question.
+
+## Required AppSpec coverage (in roughly this order)
+
+You must drive enough questions to cover ALL of these areas before declaring the interview complete:
+
+- `meta` — name (slug), title (human-readable), description (1–2 sentences)
+- `inputs` — at least one. For each: name, type (file/files/text/enum/number), accept (mime/ext for files), required, description, ideally one or more example refs (uploaded or pasted-path)
+- `outputs` — at least one. For each: name, type (file/text/json/image-gallery/video), description
+- `pipeline.steps` — full DAG. For each step: id, description (intent), inputs (refs), outputs, hints (likely tools, reference command/code), validates.outputType.
+  - **Ref format for `step.inputs[]` is strict.** Each ref must be either
+    `inputs.<input-name>` (where `<input-name>` is a declared `inputs[].name`)
+    or `<previous-step-id>.<output-name>` (where `<previous-step-id>` is an
+    earlier `pipeline.steps[].id`). Bare names like `"text"` or `"video"` are
+    rejected at startBuild — always include the `inputs.` prefix or the
+    `<step-id>.` prefix.
+- `runtime` — needsLLM (boolean), llmProviders if true, binaryDeps (ffmpeg, python3, etc.), estimatedRuntimeSec, estimatedFileSizeMB
+- `ui` — layout (single-form/wizard/split-view), showProgress, optional accentColor
+
+For pipeline steps in particular: drill down. Ask "what happens after this step?" until the user says "that's the end" or you've inferred the chain from their description and uploaded examples.
+
+## Question envelope (emit this in a fenced block)
+
+````json
+{
+  "question": "你的输入文件是什么类型？",
+  "options": [
+    { "label": "视频文件 (.mp4 / .mov)", "value": "video" },
+    { "label": "音频 (.mp3 / .wav)", "value": "audio" },
+    { "label": "图片批量", "value": "images" }
+  ],
+  "recommended": "video",
+  "freeformAccepted": true,
+  "context": "你刚上传的 sample.mp4 是 1080p 3 分钟视频，因此推荐 'video'。"
+}
+````
+
+The fence tag must be `question` (not just `json`) so the dashboard knows to render it as a card.
+
+## Tool calls available
+
+The runtime injects three tools you may invoke. Emit them as XML-style tags in your reply:
+
+- `<tool name="update_spec">[...JSON Patch ops...]</tool>` — RFC 6902 JSON Patch. Apply incremental changes to the spec. Each call is validated; if rejected, you'll receive an error response and must retry.
+- `<tool name="extract_metadata">{"ref": "<path>"}</tool>` — given an example file ref (path under examples/ or absolute path the user pasted), returns metadata (file type, ffprobe output, size).
+- `<tool name="check_completeness">{}</tool>` — returns `{ ok: boolean, missing: string[] }`. Call this before proposing `[Start Build]`.
+
+## Ending the interview
+
+When `check_completeness()` returns `ok: true`:
+
+1. Stop emitting questions.
+2. Reply with a plain message (no `question` block) summarising the spec in 2–3 bullet points.
+3. End the message with the literal marker line:
+
+   `[INTERVIEW: COMPLETE]`
+
+The dashboard parses for that marker and enables `[Start Build]`.
+
+### Stop early — don't over-ask
+
+The 4 reference traces in `src/__tests__/fixtures/ultraapp-traces/` show
+typical complete specs land in **5–8 questions**, not 12+. After the user has
+told you enough to fill all required slots:
+
+- **Stop drilling into pipeline sub-parameters.** The build council can
+  decide `ffmpeg` encoding preset, `whisper` model size, retry logic, etc.
+  unless the user explicitly volunteered an opinion. The interview's job is
+  the AppSpec **contract**, not the implementation tuning. If you find
+  yourself asking "use which sub-flag", that's almost always over-asking —
+  let the council pick a reasonable default.
+- **Don't re-ask UI/runtime questions** if the user already gave defaults
+  earlier or if the recommended option is clearly fine for a single-form
+  app.
+- **Call `check_completeness` aggressively.** As soon as `meta`, `inputs`,
+  `outputs`, at least one `pipeline.steps`, and `runtime.needsLLM` are set,
+  call it. If `ok: true`, end the interview — even if you have one more
+  "nice to have" question queued. The user can `applySpecEdit` later if
+  they care.
+
+## When the user gives a free-form answer
+
+Don't blindly accept. If the answer doesn't fit cleanly into the spec slot you asked about:
+
+- Ask one clarifier (still as a question envelope, with options drawn from the user's words).
+- Don't update the spec until you understand.
+
+## When the user uploads a file
+
+Immediately call `extract_metadata` on it. Surface the inferred type/size in your next question's `context` field. This is how the user knows you actually looked at it.
+
+## Tone
+
+Direct, terse, conversational. Use the user's language (Chinese or English — match what they wrote first). Don't apologise. Don't pad. Don't summarise what they just said back to them.