aw-spec-cli 0.1.25 → 0.1.27

package/assets/.agents/skills/appweaver/SKILL.md

@@ -1,56 +1,16 @@
 ---
 name: "appweaver"
-description: "Parametric launcher (Antigravity): run ANY converted aw-spec skill on the aw-orchestrator under one of the 4 strategies (agent [default], spawn, sdk, sdk-apply)."
-argument-hint: "<skill> [strategy] [input…] — e.g. 'select-domain', 'specify spawn Build an order API', 'analyze-slice'"
-compatibility: "Requires .appweaver/orchestrator/ and the agy CLI on PATH"
+description: "Parametric launcher: run ANY converted aw-spec skill on the aw-orchestrator under one of the 4 strategies (agent [default], spawn, sdk, sdk-apply)."
+argument-hint: "<skill> [strategy] [input…] — e.g. 'select-stack', 'specify spawn Build an order API', 'analyze-slice'"
+compatibility: "Requires .appweaver/orchestrator/ and python3"
 user-invocable: true
 disable-model-invocation: false
 ---
 
-# Orchestrator Skill Launcher
+# AppWeaver launcher
 
-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. Execution follows the chosen strategy; the checkpoint channel carries every human-facing interaction regardless of strategy.
+Read `.appweaver/orchestrator/LAUNCHER.md` and follow it exactly.
 
-- **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/`
-- **This agent's transport profile:** `.agents/agent.json`
+Several agents read this folder, so this launcher names no agent: find the row for the agent you are in the profile table of `LAUNCHER.md` — that row is your transport profile. If you have no row, only the `agent` strategy is available.
 
-  > Antigravity spawns via the `agy` CLI (Gemini-based; no `--system-prompt`,
-  > so `system` is folded into the prompt — isolation is best-effort). Its
-  > `sdk` block declares the SDK the `sdk`/`sdk-apply` strategies import
-  > (`google-antigravity`) and the adapter
-  > (`.appweaver/orchestrator/adapters/google_antigravity.py`, shared per-SDK)
-  > that owns its calling convention.
-
-## Execution Steps
-
-1. **Parse Arguments** (`<skill> [strategy] [input…]`):
-   - `skill` (required): the aw-spec skill name, e.g. `demo`, `select-domain`, `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` — YOU fulfill each generation through the checkpoint channel, no profile needed): who executes each generation. Always pass `--strategy <strategy>`.
-   - Everything after the strategy is the user input: pass it as `--input "<text>"` (omit when empty).
-   - `--agent-profile .agents/agent.json` 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 `--isolation bare|fresh` and `--model <name>`; `sdk`/`sdk-apply` accept `--model <name>`.
-
-2. **Run the Interpreter**:
-   ```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 .agents/agent.json]   # spawn, sdk, sdk-apply \
-     [--input "<user input>"] \
-     --json
-   ```
-
-3. **Handle the Suspend/Resume Loop** — whenever the command exits with code `2`, 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` (done) or `1` (stopped by a gate).
-   - **`ask`** — ask the USER the `prompt` with the listed `options` (use your question tool). 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`; write the chosen value as plain text to `response_path`.
-   - **`hook`** — run each MANDATORY hook in `hooks` (each is a slash command of THIS agent) in this conversation; optional hooks at your discretion. 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`.
-   - **`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.
+The arguments are the text the user typed after `/appweaver`.

package/assets/.appweaver/ORCH-DIALECT.md

@@ -8,8 +8,9 @@ step/`outputs:`/`condition:` conventions, but built for
 the **orchestrator model**: the interpreter assembles 100% of every model
 payload (system = standards/rules, user = artifacts + task) and a **fresh
 agent** executes it under one of the 4 strategies. Everything here is common
-across agent roots — `.claude`, `.agents`, `.kilocode` differ only in their
-transport profile (`agent.json`) and their thin `/appweaver` launcher.
+across agent roots — each agent differs only in its transport profile
+(`agent.json`) and a thin `/appweaver` launcher that points at the shared
+`orchestrator/LAUNCHER.md`.
 
 ## Layout (the common folder)
 
@@ -19,6 +20,8 @@ transport profile (`agent.json`) and their thin `/appweaver` launcher.
   ORCH-DIALECT.md            → this doc lives at .appweaver/ORCH-DIALECT.md
   README.md                  strategies, transports, checkpoint machinery
   AGENT-PROFILE.md           profile (agent.json) reference
+  LAUNCHER.md                the /appweaver instructions every agent's launcher points at,
+                             with the profile table (which agent → which agent.json)
   adapters/                  shared per-SDK adapters (claude_agent_sdk, google_antigravity)
   modules/                   shared includable modules (*.orch.yaml): delta-design,
                              delta-spec, domain-select, lane-gate, tech-select
@@ -33,7 +36,7 @@ transport profile (`agent.json`) and their thin `/appweaver` launcher.
 
 ## Execution model (strictly held)
 
-1. **Context management is the orchestrator's** — as in `workflows/aw-spec-demo.orch.yaml`.
+1. **Context management is the orchestrator's** — as in `workflows/aw-spec-specify.orch.yaml`.
    `build_context` REPLACES the per-request envelope; `load_standards`
    maintains the sticky system prefix. Per-step `context:` is THIS request only
    and is never appended onto the envelope. No agent ever assembles its own context.
@@ -91,15 +94,15 @@ the raw object, not its JSON string.
 | `build_context` | engine | REPLACE the per-request envelope: `system:`/`context:` file lists (+ `context_from: <var>` — or a list of vars, appended in order — holding paths a prior step produced, + `vars:`) |
 | `load_standards` | engine | F4 — append to the **sticky standards set** prepended to every system block (dedup, `optional:`, `files:`/`files_from_variable`). This is the byte-stable, prompt-cacheable prefix |
 | `execute_script` | engine | F1 — run a `scripts:` ref (`subcommand:` + `args:`; sh/ps1 via `--os`); stdout's last line = JSON, bound via `outputs[]`; `on_error: continue` tolerates a script that ran and exited non-zero (a JSON object on its last stdout line is still bound, so a gate can show the script's own reason; with none, the outputs bind empty) — never an undeclared ref, which the pre-flight refuses before step 1; cached across resumes; runs for real even in mock transport |
-| `verify_context` | engine | F2 — gates: `required_files` (+`allow_missing`), `require_non_empty` (+`on_empty[_message]`), `require_true` (+`on_false[_message]`), `require_value`+`equals` (+`on_mismatch[_message]`). `stop` raises a terminal stop |
-| `agent_generate` | fresh agent | demo contract (code work): agent DECIDES file paths per the loaded standards, writes with its tools, reports `files[]` in the trailing ```json fence; a reported path not on disk is dropped from `files` (and listed in `files_not_written`) before outputs bind, so a `require_non_empty` gate on it proves something was written. `sdk-apply` = read-only generation + invoking agent applies |
-| `agent_review` | fresh agent | payload-only review of `review_of_var`/`review_of` files (inlined into THIS request, never sticky) → `{pass, issues}` |
+| `verify_context` | engine | F2 — gates: `required_files` (+`allow_missing`), `require_non_empty` (+`on_empty[_message]`), `require_true` (+`on_false[_message]`), `require_value`+`equals` (+`on_mismatch[_message]`). Outcomes: `stop` raises a terminal stop; `return` ends the module being included and the caller carries on with the step after its `include` (at the top level it ends the run normally, outputs resolved); `continue` (or the outcome absent, for `on_empty`) carries on. `message_var: <name>` binds a failed gate's resolved message, so a caller that returns or continues can still report why. `--validate` rejects any other outcome |
+| `agent_generate` | fresh agent | code work (`_smoke`'s `gen_file` is the minimal example): agent DECIDES file paths per the loaded standards, writes with its tools, reports `files[]` in the trailing ```json fence; a reported path not on disk is dropped from `files` (and listed in `files_not_written`) before outputs bind, so a `require_non_empty` gate on it proves something was written. `sdk-apply` = read-only generation + invoking agent applies |
+| `agent_review` | fresh agent | payload-only review of `review_of_var`/`review_of` files (inlined into THIS request, never sticky) → `{pass, issues}`; `_smoke`'s `review_file` reviews what `gen_file` reported |
 | `agent_author` | fresh agent | F5 — **authored artifact** (decl `llm_generate`): the INTERPRETER owns `output_target: {type: file, path}`. Generation is payload-only under every strategy (mapped `context:` + sticky envelope + standards are the entire world) and never writes — the ENGINE writes the returned content (sdk-apply degrades to sdk). Optional `context:` (per-request extras), `include_standards: false` (narrow payload), `tools:` (read-only opt-in for a task that names files by path) |
 | `agent_query` | fresh agent | F6 — generic payload-only structured JSON (decl `llm_query`): `schema:` shapes the required fence, `outputs[]` binds it, `mock:` supplies the mock-transport result; one malformed-JSON retry on fresh strategies. Same tools contract as `agent_author` — none unless the step declares `tools:` |
 | `ask` | human (via launcher) | F7 — question: `prompt`, `options`/`options_from`/`options_from_variable`, `multi`, `answer_key`, `answer_var` (default `answer`). Sources in order: cache → `--answer k=v` → `--non-interactive` (first option; all when multi) → checkpoint suspend `ask` → stdin |
 | `user_select` | human (via launcher) | F7 — pick ONE from `options_from_variable`; `preselect_from` (direct-argument fast path), `single_option_confirm`; `--select stepid=v`; binds `selection` + `outputs[]` |
 | `dispatch_hooks` | invoking agent | F8 — suspend kind `hook` with the `hooks_from_variable` list (slash commands of the LAUNCHING agent); logged-only without a checkpoint; never re-fires across resumes |
-| `include` | engine | F9 — run a module `.orch.yaml` inline: shares vars/envelope/standards/scripts/replay-cache; a module's own `scripts:` EXTEND the caller's map by `setdefault`, so the caller's ref wins on a clash and every module can declare what it invokes and still validate standalone; `with:` seeds inputs; cache keys namespaced `inc:<id>/…`; module `Stop` stops the caller |
+| `include` | engine | F9 — run a module `.orch.yaml` inline: shares vars/envelope/standards/scripts/replay-cache; a module's own `scripts:` EXTEND the caller's map by `setdefault`, so the caller's ref wins on a clash and every module can declare what it invokes and still validate standalone; `with:` seeds inputs; cache keys namespaced `inc:<id>/…`; module `Stop` stops the caller, a gate's `return` ends only the module. Vars are SHARED, not scoped: a module included twice (once per lane) resets its own vars first, or the second pass reads the first's answers |
 | `loop` | engine | `while: <cond>` + `max_iterations` (default 5), or F3 foreach `over: "{{list}}"` + `as: item` (binds `item`, `item_index`, `iteration`); `break` (+`condition:`) exits the innermost loop |
 
 Decl steps may keep their `parameters:` wrapper — every ported action reads
@@ -167,5 +170,6 @@ orchestrator.py <workflow.orch.yaml>
   reason, before any step runs and before a checkpoint response is ingested.
   Warnings never block.
 - `workflows/_smoke.orch.yaml` exercises every construct with no model and no
-  writes outside `.smoke-out`: run it `--non-interactive` (CI) and with
-  `--checkpoint` (protocol walk-through).
+  writes outside `.smoke-out` — including an `agent_generate` edit step (the
+  mock writes `SmokeGenerated.cs`) and an `agent_review` of what it reported:
+  run it `--non-interactive` (CI) and with `--checkpoint` (protocol walk-through).

package/assets/.appweaver/RULE-PARTITION.md

@@ -126,7 +126,7 @@ lane loads the technical base, the frontend lane loads the UI base. What they sh
 - **Which lanes exist is the declaration's answer.** `select-stack` runs first and writes
   `.appweaver/stacks.json`; onboard refuses to start without it. A lane declared there gets its
   half and its rule set, a lane declared `(none)` gets neither, and the scan — pointed at the
-  declared source path — decides what the governance SAYS, never whether the lane exists. A
+  declared lane root folder — decides what the governance SAYS, never whether the lane exists. A
   declared UI lane whose path holds no recognisable UI source is reported, and its governance is
   authored thin rather than skipped.
 - The **UI half** is authored from the lane's code, not from a map heading, because at onboard
@@ -190,8 +190,8 @@ lane loads the technical base, the frontend lane loads the UI base. What they sh
 
 | Map | Reader | Class |
 |---|---|---|
-| `guardrails/projects/<project>/domain-rule-bindings.md` | `resolve-domain` | domain rule files |
-| `guardrails/projects/<project>/tech-rule-bindings.md` | `resolve-tech` | technical rule files |
+| `guardrails/<project>/domain-rule-bindings.md` | `resolve-domain` | domain rule files |
+| `guardrails/<project>/tech-rule-bindings.md` | `resolve-tech` | technical rule files |
 
 Each map keys on `## /aw-spec-<command>` headings whose `- ` bullets are workspace-relative
 file paths — pointing into the shared corpora at `guardrails/technology/<stack>/` and