aw-spec-cli 0.1.26 → 0.1.28

package/assets/.appweaver/domain.json

@@ -1 +1 @@
-{"domain":""}
+{"domain":"project-specific"}

package/assets/.appweaver/interpreter/run-skill.py

@@ -62,13 +62,18 @@ def _indent(line):
 
 
 def _strip_comment(s):
-    """Strip a trailing ' #...' comment that is outside quotes/flow."""
+    """Strip a trailing ' #...' comment that is outside quotes/flow. Inside double
+    quotes a backslash escapes the next character, so \\" does not end the string."""
     out, i, depth = [], 0, 0
     quote = None
     while i < len(s):
         c = s[i]
         if quote:
             out.append(c)
+            if quote == '"' and c == "\\" and i + 1 < len(s):
+                out.append(s[i + 1])
+                i += 2
+                continue
             if c == quote:
                 quote = None
         elif c in ("'", '"'):
@@ -93,6 +98,9 @@ def _scalar(tok):
     if tok == "" or tok == "~" or tok.lower() == "null":
         return None
     if len(tok) >= 2 and tok[0] == tok[-1] and tok[0] in "'\"":
+        if tok[0] == '"':
+            # A double-quoted value reads \" as " and \\ as \, as YAML does.
+            return re.sub(r'\\(["\\])', r"\1", tok[1:-1])
         return tok[1:-1]
     low = tok.lower()
     if low == "true":
@@ -140,7 +148,9 @@ def _parse_flow(s):
         while pos[0] < len(s):
             ch = s[pos[0]]
             if quote:
-                if ch == quote:
+                if quote == '"' and ch == "\\":
+                    pos[0] += 1  # the escaped character never closes the quote
+                elif ch == quote:
                     quote = None
             elif ch in "'\"":
                 quote = ch
@@ -328,12 +338,23 @@ def _parse_block_scalar(lines, parent_indent, folded, chomp):
         trailing += 1
 
     if folded:
-        text = ""
-        for i, ln in enumerate(block):
-            if i == 0:
-                text = ln
+        # YAML folding: one line break between two lines becomes a space, a line break
+        # followed by k empty lines becomes k newlines, and the break before or after a
+        # more-indented line is kept as it is.
+        parts, prev, empties = [], None, 0
+        for ln in block:
+            if ln == "":
+                empties += 1
+                continue
+            if prev is None:
+                parts.append("\n" * empties)
+            elif prev[:1] not in " \t" and ln[:1] not in " \t":
+                parts.append("\n" * empties if empties else " ")
             else:
-                text += ("\n" if (block[i - 1] == "" or ln == "") else " ") + ln
+                parts.append("\n" * (empties + 1))
+            parts.append(ln)
+            prev, empties = ln, 0
+        text = "".join(parts)
     else:
         text = "\n".join(block)
 

package/assets/.appweaver/orchestrator/AGENT-PROFILE.md

@@ -9,11 +9,27 @@ for that agent; the engine that consumes it is the *general* file in `.appweaver
 ```
 .appweaver/orchestrator/orchestrator.py    ← general engine (reads a profile)
 .appweaver/orchestrator/adapters/*.py      ← shared SDK adapters (one per SDK, not per agent)
-.claude/agent.json                       ← Claude Code profile  (claude -p / claude-agent-sdk)
-.agents/agent.json                       ← Antigravity profile  (agy -p / google-antigravity)
-.kilocode/agent.json                     ← Kilo Code profile    (delegates to claude)
+.claude/agent.json                       ← Claude Code profile    (claude -p / claude-agent-sdk)
+.agents/agent.json                       ← Antigravity profile    (agy -p / google-antigravity)
+.kilo/agent.json                         ← Kilo Code profile      (kilo run / claude-agent-sdk)
+.cursor/agent.json                       ← Cursor profile         (cursor-agent -p)
+.copilot/agent.json                      ← GitHub Copilot profile (copilot -p)
+.devin/agent.json                        ← Devin profile          (devin -p)
+.cline/agent.json                        ← Cline profile          (cline)
+.roo/agent.json                          ← Roo Code profile       (roo --print)
+.opencode/agent.json                     ← opencode profile       (opencode run)
+.factory/agent.json                      ← Factory Droid profile  (droid exec)
+.augment/agent.json                      ← Augment profile        (auggie --print)
+.continue/agent.json                     ← Continue profile       (cn -p)
+.kiro/agent.json                         ← Kiro profile           (kiro-cli chat)
+.codex/agent.json                        ← OpenAI Codex profile   (codex exec)
+.gemini/agent.json                       ← Gemini CLI profile     (gemini -p)
+.amp/agent.json                          ← Amp profile            (amp -x)
 ```
 
+Only the first three have an `sdk` block; the rest support the `agent` and
+`spawn` strategies.
+
 The launcher passes its profile with `--agent-profile <path>` (which implies
 `--transport real`).
 
@@ -60,7 +76,7 @@ options). Adapters are keyed by SDK, not by agent:
 `adapters/google_antigravity.py` maps the neutral permission modes onto
 Antigravity policies and drives `Agent` / `LocalAgentConfig` (used by
 `.agents`), while `adapters/claude_agent_sdk.py` drives `query` /
-`ClaudeAgentOptions` (shared by `.claude` and `.kilocode`, whose SDK is the
+`ClaudeAgentOptions` (shared by `.claude` and `.kilo`, whose SDK is the
 same) — none of which the engine knows about; it only follows the profile's
 `sdk.adapter` pointer.
 
@@ -87,11 +103,23 @@ When `system` is `"prepend"`, the system block is folded into the prompt
 ## Adding a new agent
 
 1. Drop an `agent.json` at that agent's root (`.<agent>/agent.json`) describing its CLI.
-2. Add a launcher in that agent's native format that calls
-   `orchestrator.py … --agent-profile .<agent>/agent.json`.
-3. For the `sdk`/`sdk-apply` strategies, add an `sdk` block and point
+2. Add the agent's row to the profile table in `.appweaver/orchestrator/LAUNCHER.md`.
+   The launchers in folders several agents read (`.claude/skills/`, `.agents/skills/`)
+   name no agent; an agent loading one of them finds its profile in that table.
+3. Add a launcher in that agent's native format that points at `LAUNCHER.md` and
+   names `.<agent>/agent.json` as the agent's profile — `.cursor/commands/appweaver.md`
+   is the shortest example.
+4. For the `sdk`/`sdk-apply` strategies, add an `sdk` block and point
    `sdk.adapter` at the matching adapter in `.appweaver/orchestrator/adapters/`
    — or drop a new adapter there first if that SDK has none yet.
-
-No engine change required. Verify with `--dry-run` (prints the exact command
-without executing).
+5. Add the agent's folder (and its launcher folder, if different) to `KIT_AGENT_DIRS`
+   in `.appweaver/scripts/python/aw-inventory.py`, so a brownfield inventory does not
+   read the kit's files as the project's own. When the launcher sits in a folder the
+   project also uses (as `.github/` holds its CI), add the launcher's exact path to
+   `KIT_AGENT_FILES` instead.
+
+No engine change required. Verify with `--dry-run` on `_smoke.orch.yaml`
+(`--non-interactive --strategy spawn --agent-profile .<agent>/agent.json --dry-run`):
+it prints the exact command the profile builds for every model step — the
+read-only `agent_query`, `agent_author` and `agent_review`, and the `agent_generate`
+edit step — without executing any of them.

package/assets/.appweaver/orchestrator/LAUNCHER.md

@@ -0,0 +1,88 @@
+# AppWeaver launcher
+
+Every agent's `/appweaver` command points here. These instructions are the same for
+every agent; the launcher you came from only says which agent you are, or — in a
+folder that several agents read — tells you to find yourself in the profile table.
+
+Runs one converted `aw-spec-*` workflow on the shared, agent-agnostic engine. All orchestration and **all context management live in the workflow YAML + engine** (`.appweaver/orchestrator/orchestrator.py`): the interpreter assembles the COMPLETE payload (system + user) for every request; you never author generation context yourself. You run the interpreter, fulfill each request it hands you, and relay every human-facing interaction to the user.
+
+Usage: `/appweaver <skill> [strategy] [input…]` — e.g. `/appweaver select-stack`, `/appweaver specify spawn Build an order API`, `/appweaver analyze-slice`.
+
+- **Engine + workflows (common, shared by all agents):** `.appweaver/orchestrator/orchestrator.py`, `.appweaver/orchestrator/workflows/aw-spec-<skill>.orch.yaml`, shared modules in `.appweaver/orchestrator/modules/`, shared scripts in `.appweaver/scripts/`
+- **Working directory:** run every command from the workspace root (the folder that contains `.appweaver/`).
+
+## Profile table
+
+Find the row for the agent you are. Its profile is your transport profile: the CLI that `spawn` launches and the SDK that `sdk` / `sdk-apply` import. Read the profile's `note` before using it — it states that agent's limits (model name format, isolation, what must be installed and signed in).
+
+| You are | Profile | `spawn` runs | `sdk` / `sdk-apply` |
+|---|---|---|---|
+| Claude Code | `.claude/agent.json` | `claude -p` | ✓ |
+| Antigravity | `.agents/agent.json` | `agy` | ✓ |
+| Kilo Code | `.kilo/agent.json` | `kilo run` | ✓ (Claude Agent SDK — needs Claude access) |
+| Cursor | `.cursor/agent.json` | `cursor-agent -p` | — |
+| GitHub Copilot | `.copilot/agent.json` | `copilot -p` | — |
+| Devin Desktop / Devin CLI (formerly Windsurf) | `.devin/agent.json` | `devin -p` | — |
+| Cline | `.cline/agent.json` | `cline` | — |
+| Roo Code | `.roo/agent.json` | `roo --print` | — |
+| opencode | `.opencode/agent.json` | `opencode run` | — |
+| Factory Droid | `.factory/agent.json` | `droid exec` | — |
+| Augment | `.augment/agent.json` | `auggie --print` | — |
+| Continue | `.continue/agent.json` | `cn -p` | — |
+| Kiro | `.kiro/agent.json` | `kiro-cli chat` | — |
+| OpenAI Codex | `.codex/agent.json` | `codex exec` | — |
+| Gemini CLI | `.gemini/agent.json` | `gemini -p` | — |
+| Amp | `.amp/agent.json` | `amp -x` | — |
+| any other agent | — | — | — |
+
+## Strategies
+
+- **`agent`** (default) — YOU fulfill each generation through the checkpoint channel. Works for every agent and needs no profile.
+- **`spawn`** — each generation runs in a fresh process of your agent's CLI, as your profile describes. Needs your row's profile and that CLI on PATH.
+- **`sdk`** — an isolated SDK session generates and applies. Needs a profile with an `sdk` block.
+- **`sdk-apply`** — an isolated SDK session generates read-only; YOU apply its output (pending kind `apply`). Needs a profile with an `sdk` block.
+
+If the user names a strategy your row does not support — or you have no row and they name anything but `agent` — say so and stop.
+
+## Execution Steps
+
+1. **Parse Arguments** (`<skill> [strategy] [input…]`):
+   - `skill` (required): the aw-spec skill name, e.g. `select-stack`, `foundation`, `specify`, `design`, `implement`, `build`. Resolve the workflow file `.appweaver/orchestrator/workflows/aw-spec-<skill>.orch.yaml`. If it does not exist, list the available `aw-spec-*.orch.yaml` files in that folder and stop.
+   - `strategy` (optional, one of `agent`, `spawn`, `sdk`, `sdk-apply`; default `agent`): if the first word after the skill is one of these, it is the strategy. Always pass `--strategy <strategy>`.
+   - Everything after the strategy is the user input: pass it as `--input "<text>"` (omit when empty).
+   - `--agent-profile <your profile>` is required for `spawn`, `sdk`, and `sdk-apply` (`agent` needs no profile). If the SDK package isn't installed, add `--sdk-install`.
+   - **Always** pass `--checkpoint .appweaver/orchestrator/.state/<skill>.state.json` — for EVERY strategy. Converted skills contain interactive steps (questions, selections, hooks); the checkpoint is how they reach you and the user. Strategies only govern who generates.
+   - `spawn` may also add `--model <name>` (in the form your profile's `note` gives) and `--isolation bare|fresh` (only where your profile defines isolation args); `sdk`/`sdk-apply` accept `--model <name>`.
+
+2. **Run the Interpreter** in the terminal:
+   ```bash
+   python3 .appweaver/orchestrator/orchestrator.py \
+     .appweaver/orchestrator/workflows/aw-spec-<skill>.orch.yaml \
+     --strategy <strategy> \
+     --checkpoint .appweaver/orchestrator/.state/<skill>.state.json \
+     [--agent-profile <your profile>]   # spawn, sdk, sdk-apply \
+     [--input "<user input>"] \
+     --json
+   ```
+
+3. **Handle the Suspend/Resume Loop** — the exit code tells you what happened:
+   - `0` — done. Go to step 4.
+   - `1` — stopped by a gate. Go to step 4.
+   - `2` — **suspended, NOT an error.** The interpreter is waiting for you. Do not debug, retry with other flags, or edit the workflow, engine, or state files. Read the printed `pending` JSON and dispatch on `pending.kind`; fulfill it, write the response to `pending.response_path`, then re-run the SAME command. Repeat until exit `0` or `1`.
+
+   Dispatch on `pending.kind`:
+   - **`ask`** — ask the USER the `prompt` with the listed `options` (use your question tool; without one, post the prompt and options in chat as a numbered list, say that more than one may be picked when `multi` is true, and END YOUR TURN — never answer it yourself). When the user answers, write the chosen answer as PLAIN TEXT to `response_path` (comma-separated values when `multi` is true).
+   - **`select`** — ask the USER to pick ONE of `options` (use your question tool; without one, post the options in chat as a numbered list and END YOUR TURN). When the user answers, write the chosen value as plain text to `response_path`.
+   - **`hook`** — run each MANDATORY hook in `hooks` in this conversation; optional hooks are at your discretion. Each hook names a slash command (`slash`) from an extension (`extension`); if your agent does not have that command, read `.appweaver/extensions/<extension>/commands/<slash without the leading />.md` and follow it. Then write `done` to `response_path`.
+   - **`author`** — read `system_path` + `user_path` and treat them as your ONLY standards and context. Author the COMPLETE content of the file named in `target` and write it — content ONLY, no commentary, no code fence — to `response_path`. Do NOT write the target file yourself; the interpreter does that.
+   - **`agent_generate`** — read `system_path` + `user_path`; perform the task YOURSELF with the listed `tools` within `permission_mode`; write your full final reply — ending with the required ```json fence — to `response_path`. `tools` uses Claude Code tool names (`Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`); if yours differ, use your own equivalents.
+   - **`agent_query` / `agent_review`** — same as above but READ-ONLY (do not modify files); the reply must end with the required ```json fence.
+   - **`apply`** — an isolated generation already decided the changes: read `artifact_path` and write its file contents EXACTLY to the paths it names, then write the confirmation ```json fence to `response_path`.
+   - If `pending.note` is present, your previous response was rejected — follow the note and rewrite `response_path`.
+
+4. **Report**:
+   Report the final JSON (`status`, `outputs`, and any `reason`) to the user. On `stopped`, relay the gate message verbatim — it tells the user what to fix or run first.
+
+## Adding an agent
+
+Add its profile (see `AGENT-PROFILE.md`), add its row to the profile table above, and give it a launcher in its own native format that points here and names that profile.

package/assets/.appweaver/orchestrator/README.md

@@ -20,38 +20,68 @@ This engine is now the **only** pipeline that ships. The earlier declarative tie
 ## General vs. agent-specific (file layout)
 
 The transport **profile lives once at each agent's root** (`.claude/agent.json`,
-`.agents/agent.json`, `.kilocode/agent.json`), so every orchestrator skill for
-that agent shares it — no per-skill duplication. Only the thin launcher is
-per-skill.
+`.agents/agent.json`, `.kilo/agent.json`, …), so every orchestrator skill for
+that agent shares it — no per-skill duplication. The `/appweaver` instructions
+live once too, in `LAUNCHER.md`; each agent's launcher is a thin pointer to it.
+A launcher in a folder only one agent reads names that agent's profile; a
+launcher in a folder several agents read (`.claude/skills/`, `.agents/skills/`)
+names none, and the agent finds its row in `LAUNCHER.md`'s profile table.
 
 ```
 .appweaver/orchestrator/                     ← GENERAL (shared by all agents)
   orchestrator.py        engine (profile-driven; no agent hardcoded)
-  workflows/aw-spec-demo.orch.yaml   demo workflow (run: /appweaver demo)
+  LAUNCHER.md            the /appweaver instructions + profile table (every launcher points here)
+  workflows/_smoke.orch.yaml   CI smoke: every construct, mock, writes only to .smoke-out/
   AGENT-PROFILE.md       the transport-profile schema
   README.md
 
 .claude/agent.json                         ← Claude Code profile (all its skills share this)
-.claude/skills/appweaver-demo/SKILL.md  ← Claude Code launcher
+.claude/skills/appweaver/SKILL.md          ← launcher (shared folder: Copilot, Cursor, Kilo read it too)
 .agents/agent.json                         ← Antigravity profile
-.agents/skills/appweaver-demo/SKILL.md  ← Antigravity launcher
-.kilocode/agent.json                       ← Kilo Code profile
-.kilocode/workflows/appweaver-demo.md   ← Kilo Code launcher
+.agents/skills/appweaver/SKILL.md          ← launcher (shared folder: Codex, Gemini CLI, Amp, Devin, Copilot, Cursor, Kilo read it too)
+.kilo/agent.json                           ← Kilo Code profile
+.kilo/agents/appweaver-{edit,read}.md      ← Kilo agents a spawned step runs as
+.kilo/commands/appweaver.md                ← Kilo Code launcher
+.cursor/agent.json                         ← Cursor profile
+.cursor/commands/appweaver.md              ← Cursor launcher
+.copilot/agent.json                        ← GitHub Copilot profile
+.github/prompts/appweaver.prompt.md        ← GitHub Copilot launcher
+.devin/agent.json                          ← Devin profile (Devin Desktop, formerly Windsurf)
+.devin/workflows/appweaver.md              ← Devin launcher
+.cline/agent.json                          ← Cline profile (not in .clinerules/: every file there is a rule)
+.clinerules/workflows/appweaver.md         ← Cline launcher (/appweaver.md)
+.roo/agent.json                            ← Roo Code profile
+.roo/commands/appweaver.md                 ← Roo Code launcher
+.opencode/agent.json                       ← opencode profile
+.opencode/agents/appweaver-{edit,read}.md  ← opencode agents a spawned step runs as
+.opencode/commands/appweaver.md            ← opencode launcher
+.factory/agent.json                        ← Factory Droid profile
+.factory/commands/appweaver.md             ← Factory Droid launcher
+.augment/agent.json                        ← Augment profile
+.augment/commands/appweaver.md             ← Augment launcher
+.continue/agent.json                       ← Continue profile
+.continue/prompts/appweaver.md             ← Continue launcher (invokable prompt)
+.kiro/agent.json                           ← Kiro profile
+.kiro/skills/appweaver/SKILL.md            ← Kiro launcher
+.codex/agent.json                          ← OpenAI Codex profile (launcher: .agents/skills/)
+.gemini/agent.json                         ← Gemini CLI profile (launcher: .agents/skills/)
+.amp/agent.json                            ← Amp profile (launcher: .agents/skills/)
+.amp/settings-{edit,read}.json             ← Amp permission sets a spawned step runs with
 ```
 
 ## Your diagram → this code
 
 | Diagram box | Where it lives |
 |---|---|
-| Agent skill launches the runtime | the per-agent launcher runs `orchestrator.py … --agent-profile <profile>` |
+| Agent skill launches the runtime | the per-agent launcher points at `LAUNCHER.md`, which runs `orchestrator.py … --agent-profile <profile>` |
 | Python Workflow / Interpreter Runtime | `orchestrator.py` — `Orchestrator.run()` |
 | **Builds Complete Context** | `build_context` → `_assemble_system()` + `_assemble_user()` |
-| **Invoke (fresh generation)** | `agent_generate` → `_run_fresh()` → the profile's CLI |
+| **Invoke (fresh generation)** | `agent_generate` → `_run_fresh()` → the profile's CLI (every code step in `workflows/aw-spec-implement.orch.yaml`; `_smoke`'s `gen_file` is the minimal one) |
 | Agent uses tools (Edit, Bash…) | tools/approval flags from the profile |
 | **Return structured result** | trailing ```` ```json {…} ```` block → `_extract_json()` → bound via `outputs:` |
 | Interpreter continues next step | `_run_steps()` / `_run_loop()` |
-| **Review the current output** | `agent_review` → a second fresh, read-only generation |
-| …continues | the `revise` loop in `workflows/aw-spec-demo.orch.yaml` |
+| **Review the current output** | `agent_review` → a second fresh, read-only generation (`_smoke`'s `review_file` reviews what `gen_file` reported) |
+| …continues | a `loop` (`while:` + `break`) around `agent_generate` → `agent_review` — the review→revise cycle |
 
 ## Why this overrides the launching agent's own context (your R6)
 
@@ -78,31 +108,37 @@ see below.)
 ## Run it
 
 Safe (default) — **no model calls**. Prints the exact payloads the fresh agent
-would receive (proof of isolation), simulates the writes, runs the whole loop:
+would receive (proof of isolation), simulates the writes, runs the whole
+workflow — including the `agent_generate` edit step and the `agent_review` of
+what it wrote. `_smoke` has one `ask`, so it runs with `--non-interactive`:
 
 ```bash
-python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/aw-spec-demo.orch.yaml            # mock
-python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/aw-spec-demo.orch.yaml --show-full
+python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/_smoke.orch.yaml --non-interactive            # mock
+python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/_smoke.orch.yaml --non-interactive --show-full
 ```
 
 For real — pass an agent profile (implies `--transport real`):
 
 ```bash
 # Claude Code
-python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/aw-spec-demo.orch.yaml \
-  --agent-profile .claude/agent.json --isolation bare --model opus
+python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/_smoke.orch.yaml \
+  --non-interactive --agent-profile .claude/agent.json --isolation bare --model opus
 
 # Antigravity (Gemini)
-python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/aw-spec-demo.orch.yaml \
-  --agent-profile .agents/agent.json --isolation fresh --model gemini-2.5-pro
+python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/_smoke.orch.yaml \
+  --non-interactive --agent-profile .agents/agent.json --isolation fresh --model gemini-2.5-pro
 
-# Kilo Code (delegates generation to claude -p)
-python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/aw-spec-demo.orch.yaml \
-  --agent-profile .kilocode/agent.json --isolation fresh --model opus
+# Kilo Code (kilo run; --model takes Kilo's provider/model form)
+python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/_smoke.orch.yaml \
+  --non-interactive --agent-profile .kilo/agent.json --model <provider>/<model>
 ```
 
-Add `--dry-run` to print the exact command a profile would run **without
-executing it**. Output lands in `.appweaver/orchestrator/.demo-out/` (safe to delete).
+Add `--dry-run` to print the exact command a profile would run for every model
+step **without executing any of them**: each step then takes its mock result, so
+the run carries on to the next. A dry run never writes an `agent_author` target
+(a later `required_files` gate counts it as present) and never caches a result
+in the checkpoint. Output lands in `.appweaver/orchestrator/.smoke-out/`
+(gitignored, safe to delete).
 
 ## Execution strategies — `--strategy`, per-step `strategy:`
 
@@ -153,8 +189,8 @@ If spawning a second agent instance is impossible or unwanted, `--checkpoint`
 ports run-skill.py's **suspend/resume** method into this engine:
 
 ```bash
-python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/aw-spec-demo.orch.yaml \
-  --checkpoint .appweaver/orchestrator/.demo-out/demo.state.json --json
+python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/_smoke.orch.yaml \
+  --checkpoint .appweaver/orchestrator/.state/smoke.state.json --json
 ```
 
 At each `agent_generate` / `agent_review` the interpreter writes the fully
@@ -166,10 +202,9 @@ the Bash call. The agent fulfills the request **in its own conversation**
 required ```` ```json ```` fence — to `<state>.response.md`, and re-runs the
 same command. Completed steps replay from the cache, so the run continues
 exactly where it suspended; on a terminal end the state file and sidecars are
-deleted. Launcher: the `appweaver-demo` skill/workflow handles this via its
-`sdk-apply` / `agent` strategies (step 3, the suspend/resume loop). The same
-loop works for any agent that can run bash and read/write files — including
-Kilo Code, natively, with no `claude` CLI.
+deleted. Launcher: `LAUNCHER.md` step 3 (the suspend/resume loop), which every
+agent's `/appweaver` follows. The same loop works for any agent that can run
+bash and read/write files — it needs no profile and no extra CLI.
 
 **The trade-off, stated plainly:** the interpreter keeps 100% ownership of
 what goes *into* each payload, but the request executes inside the invoking
@@ -195,16 +230,39 @@ documented in `.appweaver/ORCH-DIALECT.md`.
 | Extra auth / CLI needed | yes (`claude`/`gemini` + key for `--bare`) | none |
 | Permission prompts / HITL | none (headless) | the agent's native ones |
 
-## The three agents
+## The agents
 
-| Agent | Folder | Fresh-generation CLI | System block | Tools | Isolation |
-|---|---|---|---|---|---|
-| Claude Code | `.claude/` | `claude -p` | `--system-prompt` | `--tools` | `--bare` (needs `ANTHROPIC_API_KEY`) / `--setting-sources ""` |
-| Antigravity | `.agents/` | `gemini -p` | folded into prompt (no system flag) | `--approval-mode` | best-effort (no `--bare` equivalent) |
-| Kilo Code | `.kilocode/` | `claude -p` (no native headless CLI) | `--system-prompt` | `--tools` | `--bare` / `--setting-sources ""` |
-
-Adding a fourth agent = drop an `agent.json` + a launcher in its folder; no
-engine change. See `AGENT-PROFILE.md` for the schema.
+| Agent | Profile | Fresh-generation CLI | Edit steps | Read-only steps |
+|---|---|---|---|---|
+| Claude Code | `.claude/` | `claude -p` (prompt on stdin) | `--tools <list> --permission-mode acceptEdits` | `--tools "" --permission-mode default` |
+| Antigravity | `.agents/` | `agy -p` | `--mode accept-edits` | `--mode plan` |
+| Kilo Code | `.kilo/` | `kilo run` (prompt on stdin) | `--agent appweaver-edit` | `--agent appweaver-read` |
+| Cursor | `.cursor/` | `cursor-agent -p` | `--force` | `--mode ask` |
+| GitHub Copilot | `.copilot/` | `copilot -p` | `--allow-all-tools` | no flag |
+| Devin (formerly Windsurf) | `.devin/` | `devin -p` | `--permission-mode dangerous` | no flag (Devin's default `normal` mode) |
+| Cline | `.cline/` | `cline` | act mode, `--auto-approve true` | `--plan` |
+| Roo Code | `.roo/` | `roo --print` | `--mode code` | `--mode ask` |
+| opencode | `.opencode/` | `opencode run --auto` | `--agent appweaver-edit` | `--agent appweaver-read` |
+| Factory Droid | `.factory/` | `droid exec -o json` (prompt on stdin) | `--auto high` | no flag (read-only by default) |
+| Augment | `.augment/` | `auggie --quiet --print` | no flag | `--ask` |
+| Continue | `.continue/` | `cn --silent -p` | `--auto` | `--readonly` |
+| Kiro | `.kiro/` | `kiro-cli chat --no-interactive` (prompt on stdin) | `--trust-all-tools` | `--trust-tools=read,grep` |
+| OpenAI Codex | `.codex/` | `codex exec` (prompt on stdin) | `--sandbox workspace-write` | `--sandbox read-only` |
+| Gemini CLI | `.gemini/` | `gemini -o json -p` | `--approval-mode auto_edit` | `--approval-mode plan` |
+| Amp | `.amp/` | `amp -x` (prompt on stdin) | `--settings-file .amp/settings-edit.json` | `--settings-file .amp/settings-read.json` |
+
+Only Claude Code takes the system block as a flag (`--system-prompt`), limits
+tools per step (`--tools`) and isolates a generation (`--bare`, which needs
+`ANTHROPIC_API_KEY`, or `--setting-sources ""`). Every other profile folds the
+system block into the prompt, and its isolation is best-effort: the agent's own
+rules files still load. Only Claude Code, Antigravity and Kilo Code have an
+`sdk` block. Each profile's `note` gives that agent's limits.
+
+Adding an agent = drop an `agent.json` + a thin launcher in its folder that
+points at `LAUNCHER.md`, add the agent's row to `LAUNCHER.md`'s profile
+table, and add its folder to the inventory's `KIT_AGENT_DIRS`
+(`.appweaver/scripts/python/aw-inventory.py`); no engine change. See
+`AGENT-PROFILE.md` for the schema and the full steps.
 
 ## Invoking from an agent (the top of your diagram)
 
@@ -213,7 +271,7 @@ agent's *only* job is to run the orchestrator and relay the JSON. It **never
 generates**; its conversation **never** enters a model request.
 
 ```
-User → /appweaver-demo → (agent runs) orchestrator.py --agent-profile <its profile>
+User → /appweaver <skill> → (agent runs) orchestrator.py --agent-profile <its profile>
      → interpreter builds context → spawns a fresh CLI per step (isolated)
      → interpreter reviews + continues → agent reports final JSON
 ```
@@ -240,8 +298,13 @@ the context leak this design removes, and one reason that tier was retired.
 - `loop` (`while:` + `max_iterations:`) with `break` (+ `condition:`) — the
   review→revise cycle.
 
+`_smoke.orch.yaml` runs one `agent_generate` (`gen_file`) and one
+`agent_review` (`review_file`) of what it wrote, gated on `files[]` being
+non-empty and on `pass`; with no model, the mock writes `SmokeGenerated.cs`
+under `.smoke-out/` and the review passes when the reported files exist.
+
 The engine now implements the FULL dialect the `aw-spec-*` conversions need on
-top of these demo actions: `execute_script`, `verify_context`,
+top of these actions: `execute_script`, `verify_context`,
 `load_standards` (sticky system prefix), `agent_author` (interpreter-owned
 `output_target`, read-only generation), `agent_query` (generic structured
 JSON), `ask`/`user_select` (HITL via checkpoint), `dispatch_hooks`, `include`
@@ -282,19 +345,23 @@ at the top of this file).
 HITL — IS now ported; see `.appweaver/ORCH-DIALECT.md`.)
 
 
-# spawn (Strategy 3) — demo skill
-python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/aw-spec-demo.orch.yaml \
-  --strategy spawn --agent-profile .claude/agent.json --isolation bare --json
+## Each strategy on `_smoke`
 
-# sdk (Strategy 1) — demo skill
-python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/aw-spec-demo.orch.yaml \
-  --strategy sdk --agent-profile .claude/agent.json --model opus --json
+```bash
+# spawn (Strategy 3)
+python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/_smoke.orch.yaml \
+  --non-interactive --strategy spawn --agent-profile .claude/agent.json --isolation bare --json
+
+# sdk (Strategy 1)
+python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/_smoke.orch.yaml \
+  --non-interactive --strategy sdk --agent-profile .claude/agent.json --model opus --json
 
-# sdk-apply (Strategy 2) — demo skill, then follow the suspend/resume loop
-python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/aw-spec-demo.orch.yaml \
+# sdk-apply (Strategy 2) — then follow the suspend/resume loop
+python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/_smoke.orch.yaml \
   --strategy sdk-apply --agent-profile .claude/agent.json \
-  --checkpoint .appweaver/orchestrator/.demo-out/demo.state.json --json
+  --checkpoint .appweaver/orchestrator/.state/smoke.state.json --json
 
-# agent (Strategy 4) — demo skill, then follow the suspend/resume loop
-python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/aw-spec-demo.orch.yaml \
-  --strategy agent --checkpoint .appweaver/orchestrator/.demo-out/demo.state.json --json
+# agent (Strategy 4) — then follow the suspend/resume loop
+python3 .appweaver/orchestrator/orchestrator.py .appweaver/orchestrator/workflows/_smoke.orch.yaml \
+  --strategy agent --checkpoint .appweaver/orchestrator/.state/smoke.state.json --json
+```

package/assets/.appweaver/orchestrator/adapters/claude_agent_sdk.py

@@ -1,6 +1,6 @@
 """claude-agent-sdk adapter — a shared SDK adapter, loaded by the
 aw-orchestrator engine when an agent profile's `sdk.adapter` points here
-(both .claude/agent.json and .kilocode/agent.json do). Adapters live in this
+(both .claude/agent.json and .kilo/agent.json do). Adapters live in this
 library keyed by SDK, not by agent: everything claude-agent-sdk-specific is
 HERE, the engine ships no SDK code of its own, and each profile declares
 which adapter drives its SDK.

package/assets/.appweaver/orchestrator/modules/delta-plan.orch.yaml

@@ -130,6 +130,9 @@ workflow:
                                              # the context's CANONICAL model — the aggregate root,
                                              # its entities and its invariants live here, not in the
                                              # spec and not in this plan.
+      - { path: .appweaver/memory/constitution.technical.md, optional: true }
+                                             # the lane's ratified technology base, the same one
+                                             # the master plan is authored under — no domain.
       - { path: "{{cr_dir}}/delta-slice-analyze-report.md", optional: true }
                                              # WHAT THE LAST GATE FOUND, when this change
                                              # has already been through analyze-slice-delta.
@@ -191,7 +194,9 @@ workflow:
         lane" with every addition or change to this feature's published surface, as field
         shapes. That table is the only part of this document the frontend delta plan may
         bind against; a contract the UI needs and this document never states becomes a
-        client-side workaround. "None" when the surface is unchanged.
+        client-side workaround. "None" when the surface is unchanged. Each row carries the
+        endpoint's operation id: a changed endpoint keeps the one the master plan gives
+        it, and a new endpoint gets one unique across the service.
       - Stay technology-agnostic (no code) and keep the master's form: behaviour as
         signatures + pre/post/invariant/raises, contracts as field shapes.
       - TWO CASES — decide from the delta-spec in context:
@@ -208,11 +213,12 @@ workflow:
 
   # ══════════ THE LANE SWAP — the frontend's rules replace the backend's ═══════
   # The delta twin of the swap `plan` performs before its own master frontend sections.
-  # Sticky standards only accumulate, and the caller loaded BOTH lanes' rule sets before
-  # including this module, so without this the service delta plan is authored with the UI
-  # rules in its envelope and the experience delta plan with the service rules. `replace`
-  # resets to the workflow's declared seed and loads `## /aw-spec-plan-ui`, so the backend
-  # delta above kept the service set and everything below this line is the frontend's.
+  # The caller loads only the service lane's rules (`## /aw-spec-plan-backend`, when that
+  # lane is declared) before including this module, and sticky standards only accumulate,
+  # so without this the experience delta plan would be authored with the service rules in
+  # its envelope. `replace` resets to the workflow's declared seed and loads
+  # `## /aw-spec-plan-frontend`, so the backend delta above is authored under the service
+  # set and everything below this line under the frontend's.
   #
   # Conditioned on the same flag as the lane it precedes: a change with no frontend half
   # authors nothing here and must not have its envelope swapped out from under the
@@ -221,7 +227,7 @@ workflow:
     condition: "{{fe_existing}} == true"
     action: include
     module: .appweaver/orchestrator/modules/tech-select.orch.yaml
-    with: { command: aw-spec-plan-ui, replace: "true" }
+    with: { command: aw-spec-plan-frontend, replace: "true" }
 
   # ═════════════════════ FRONTEND LANE — the experience delta plan ═════════════
   - id: ctx_frontend_delta
@@ -292,6 +298,10 @@ workflow:
         and introduce no server-side behaviour or persistence assumption. What the
         experience needs and the surface does not offer goes under "Contract deltas
         needed", raised back to the service lane — never worked around in the client.
+      - A BINDING ROW'S ELEMENT LEADS WITH ITS OPERATION ID — `OperationId` · `VERB
+        /route` — copied exactly from the service delta's table or, for an endpoint the
+        change does not touch, the master backend plan. Implement looks the endpoint up by
+        it in the service's exported API document.
       - UX- IS THIS DOCUMENT'S TO REALISE. The service plan excludes the spec's Experience
         Standards by contract, so a UX- item in the delta-spec that reaches neither plan
         is a dropped requirement.

package/assets/.appweaver/orchestrator/modules/domain-select.orch.yaml

@@ -45,13 +45,15 @@ workflow:
       - { name: dg_rulemap_exists, from: "$.rulemap_exists" }
       - { name: dg_candidates,     from: "$.candidates" }
 
-  # 2. Domain gate — only when the domain/domain-rule-bindings is missing.
+  # 2. Domain gate — only when the project or its domain-rule-bindings.md is missing.
   - id: gate
     action: ask
     condition: "{{dg_rulemap_exists}} == false"
     prompt: >
-      Domain is not set or its rule files are missing (domain '{{domain}}').
-      Continue with technical standards only, or exit to run /appweaver select-domain?
+      No domain rule map found for project '{{domain}}': .appweaver/domain.json must name a
+      folder under guardrails/ that holds domain-rule-bindings.md (project-specific by default;
+      /appweaver select-domain lists the folders that qualify). Continue with technical
+      standards only, or exit to fix it?
     options: ["continue", "exit"]
     answer_var: dg_gate
   - id: gate_stop
@@ -60,7 +62,7 @@ workflow:
     require_value: dg_gate
     equals: "continue"
     on_mismatch: stop
-    on_mismatch_message: "Exited — run /appweaver select-domain (or fix the domain folder) and re-run."
+    on_mismatch_message: "Exited — run /appweaver select-domain, or set 'domain' in .appweaver/domain.json to a folder under guardrails/ that holds domain-rule-bindings.md (project-specific by default), then re-run."
 
   # 3. Selection box — only when a rule map with candidates exists.
   - id: select_mode