aw-spec-cli 0.1.26 → 0.1.27

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/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

package/assets/.appweaver/orchestrator/modules/foundation-lane.orch.yaml

@@ -0,0 +1,237 @@
+# =============================================================================
+# foundation-lane (orchestrator) — scaffold ONE declared lane
+#
+# Included by aw-spec-foundation once per lane kind — backend first, then frontend — with
+# that lane's fields passed through `with:`. It answers "what is this lane built from?"
+# and hands off:
+#
+#   1. Can the lane take a foundation — does it run its commands inside its lane root folder
+#      and keep its tests there? If not, it is reported and passed over. Then: does it
+#      already hold files? If so, ask to overwrite them; "no" skips the lane and nothing
+#      else is asked. Each lane is asked on its own.
+#   2. List what fits the lane: every pack and spec under foundations/<ecosystem>/ whose
+#      `# kind:` / `# profiles:` header admits this lane, then [manual spec] and [skip].
+#   3. Pick one. A fast-path name (`/appweaver foundation VerticalSlice App`) preselects
+#      its entry in whichever lane lists it.
+#   4. pack -> foundation-pack (unpack the verified bundle, as before)
+#      spec | manual spec -> foundation-spec (an agent builds the project from the spec)
+#      skip -> nothing is written.
+#
+# Every refusal in here and in the two route modules RETURNS rather than stops, so the
+# caller always reaches the next lane; the reason is in fl_status, which the caller
+# reports per lane at the end of the run.
+#
+# Inputs (via include `with:`):
+#   fl_kind, fl_lane_id, fl_profile, fl_title, fl_language, fl_ecosystem,
+#   fl_source_path, fl_test_path, fl_workdir, fl_build
+# Shared with the caller: USER_INPUT (the fast path) and `app` (asked once per run, the
+#   first time a lane needs it, and reused by the next lane).
+# Produces: fl_status, fl_route, fl_name, fl_spec_path, fl_files, and fl_overwrite ("yes"
+#   when the lane already had files and the operator agreed to overwrite them), which the
+#   two route modules read.
+# =============================================================================
+
+name: foundation-lane
+dialect: aw-spec.orchestrator/v1
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+workflow:
+
+  # 0. Vars are shared across the two includes; start this lane clean.
+  - id: fl_reset
+    action: set
+    vars:
+      fl_status: "not scaffolded"
+      fl_route: ""
+      fl_name: ""
+      fl_spec_file: ""
+      fl_spec_path: ""
+      fl_files: ""
+      fl_has_files: ""
+      fl_files_summary: ""
+      fl_self_contained: ""
+      fl_shape_reason: ""
+      fl_overwrite_answer: ""
+      fl_overwrite: ""
+      fl_overwrite_note: ""
+      fl_go: "true"
+      fl_spec_route: ""
+
+  - id: fl_has_root
+    action: verify_context
+    require_non_empty: fl_source_path
+    on_empty: return
+    message_var: fl_status
+    on_empty_message: "not scaffolded — lane `{{fl_lane_id}}` declares no lane root folder in .appweaver/stacks.json; re-run /appweaver select-stack and give it its lane root folder"
+
+  # 1. Does the lane already hold files? Any file in its lane root folder or test path counts,
+  #    whatever stack wrote it, and so do its build files where its commands run when that
+  #    is outside the lane (a .NET solution at the repo root). Asked BEFORE the pick list,
+  #    so "no" skips this lane with nothing else asked and the run moves on to the next one.
+  #    The first option is the non-interactive default, so an unattended run never
+  #    overwrites. The answer key carries the lane kind, so a scripted run answers each lane
+  #    on its own: --answer fl_overwrite_backend=yes --answer fl_overwrite_frontend=no.
+  - id: fl_files_check
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-lane-files
+    args: ["--source", "{{fl_source_path}}", "--test", "{{fl_test_path}}", "--workdir", "{{fl_workdir}}", "--profile", "{{fl_profile}}"]
+    outputs:
+      - { name: fl_has_files,      from: "$.has_files" }
+      - { name: fl_files_summary,  from: "$.summary" }
+      - { name: fl_self_contained, from: "$.self_contained" }
+      - { name: fl_shape_reason,   from: "$.shape_reason" }
+
+  # A foundation is a complete project that lands INSIDE the lane root folder — build files,
+  # source and tests — so the lane has to run its commands there and keep its tests there.
+  # A lane declared the classic way (code in src/, solution and tests/ at the repo root)
+  # suits existing code but would get a project its own build cannot find; it is reported
+  # here, before anything is asked, and the run moves on to the next lane.
+  - id: fl_shape_gate
+    action: verify_context
+    require_true: fl_self_contained
+    on_false: return
+    message_var: fl_status
+    on_false_message: "not scaffolded — {{fl_shape_reason}}"
+
+  - id: fl_ask_overwrite
+    action: ask
+    condition: "{{fl_has_files}} == true"
+    prompt: >
+      {{fl_kind}} lane `{{fl_lane_id}}` ({{fl_profile}}) already has files — {{fl_files_summary}}.
+      Scaffolding it writes into these folders and replaces files with the same path; files
+      with other names stay, and nothing is deleted. Overwrite?
+    options: ["no — skip this lane", "yes — overwrite"]
+    answer_key: "fl_overwrite_{{fl_kind}}"
+    answer_var: fl_overwrite_answer
+
+  # The answer is free text from the launcher: the full option and a bare `yes` both count.
+  - id: fl_overwrite_option
+    action: set
+    condition: "{{fl_overwrite_answer}} == yes — overwrite"
+    vars: { fl_overwrite: "yes" }
+
+  - id: fl_overwrite_short
+    action: set
+    condition: "{{fl_overwrite_answer}} == yes"
+    vars: { fl_overwrite: "yes" }
+
+  - id: fl_overwrite_gate
+    action: verify_context
+    condition: "{{fl_has_files}} == true"
+    require_value: fl_overwrite
+    equals: "yes"
+    on_mismatch: return
+    message_var: fl_status
+    on_mismatch_message: "skipped — the lane already has files ({{fl_files_summary}}) and overwriting them was declined"
+
+  - id: fl_overwrite_noted
+    action: set
+    condition: "{{fl_overwrite}} == yes"
+    vars: { fl_overwrite_note: " It already has files, and you chose to overwrite them." }
+
+  # 2. What fits this lane.
+  - id: fl_list
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-list
+    args: ["--kind", "{{fl_kind}}", "--profile", "{{fl_profile}}", "--ecosystem", "{{fl_ecosystem}}", "--lane-id", "{{fl_lane_id}}", "--args", "{{USER_INPUT}}"]
+    outputs:
+      - { name: fl_options,   from: "$.options" }
+      - { name: fl_count,     from: "$.count" }
+      - { name: fl_all,       from: "$.all_foundations" }
+      - { name: fl_preselect, from: "$.preselect_option" }
+
+  # 3. Pick. There are always at least two options ([manual spec] and [skip]), so this
+  #    always asks unless the fast path named an entry this lane offers.
+  - id: fl_pick
+    action: user_select
+    prompt: >
+      {{fl_kind}} lane `{{fl_lane_id}}` — {{fl_title}} at {{fl_source_path}}.{{fl_overwrite_note}}
+      What should it be scaffolded from? A [pack] is a verified project unpacked as-is; a
+      [spec] describes a project the agent builds into the lane; [manual spec] lets you give
+      that description yourself; [skip] leaves the lane untouched.
+      ({{fl_count}} of the foundations shipped fit this lane; all of them: {{fl_all}})
+    options_from_variable: fl_options
+    preselect_from: fl_preselect
+    outputs:
+      - { name: fl_selection, from: selection }
+
+  - id: fl_choice
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-choice
+    args: ["--selection", "{{fl_selection}}", "--kind", "{{fl_kind}}", "--profile", "{{fl_profile}}", "--ecosystem", "{{fl_ecosystem}}"]
+    outputs:
+      - { name: fl_choice_ok,  from: "$.ok" }
+      - { name: fl_route,      from: "$.route" }
+      - { name: fl_name,       from: "$.name" }
+      - { name: fl_spec_file,  from: "$.file" }
+      - { name: fl_choice_msg, from: "$.reason" }
+
+  - id: fl_choice_gate
+    action: verify_context
+    require_true: fl_choice_ok
+    on_false: return
+    message_var: fl_status
+    on_false_message: "not scaffolded — {{fl_choice_msg}}"
+
+  - id: fl_skip
+    action: set
+    condition: "{{fl_route}} == skip"
+    vars: { fl_go: "" }
+
+  - id: fl_skip_gate
+    action: verify_context
+    require_true: fl_go
+    on_false: return
+    message_var: fl_status
+    on_false_message: "skipped — left as it is, by choice"
+
+  # 4. The project name — asked once per run, the first time a lane needs it, unless the
+  #    fast path gave it. The next lane reuses it.
+  - id: fl_ask_app
+    action: ask
+    condition: "{{app}} == "
+    prompt: >
+      Enter the project (application) name, e.g. AppWeaver.Health. A pack renames its
+      sentinel to it; a spec build names the project after it, in the form the stack uses.
+      It is asked once and used for every lane in this run.
+    answer_var: app_typed
+
+  - id: fl_app_from_typed
+    action: set
+    condition: "{{app}} == "
+    vars: { app: "{{app_typed}}" }
+
+  - id: fl_app_gate
+    action: verify_context
+    require_non_empty: app
+    on_empty: return
+    message_var: fl_status
+    on_empty_message: "not scaffolded — no project name was given"
+
+  # 5. Hand off. The engine has no OR, so the two spec routes set one flag.
+  - id: fl_route_spec
+    action: set
+    condition: "{{fl_route}} == spec"
+    vars: { fl_spec_route: "true" }
+
+  - id: fl_route_manual
+    action: set
+    condition: "{{fl_route}} == manual"
+    vars: { fl_spec_route: "true" }
+
+  - id: pack
+    action: include
+    condition: "{{fl_route}} == pack"
+    module: .appweaver/orchestrator/modules/foundation-pack.orch.yaml
+
+  - id: spec
+    action: include
+    condition: "{{fl_spec_route}} == true"
+    module: .appweaver/orchestrator/modules/foundation-spec.orch.yaml