aw-spec-cli 0.1.4 → 0.1.5

package/assets/.agents/agent.json

@@ -0,0 +1,28 @@
+{
+  "name": "antigravity",
+  "sdk": {
+    "type": "google-antigravity",
+    "package": "google-antigravity",
+    "module": "google.antigravity",
+    "adapter": "../.aw-spec/orchestrator/adapters/google_antigravity.py"
+  },
+  "runtime": "Antigravity CLI (agy -p) — Antigravity is Gemini-based",
+  "note": "Antigravity (agy) has no --system-prompt flag, so 'system' is folded into the prompt (system: prepend).",
+  "bin": "agy",
+  "args": ["--dangerously-skip-permissions", "--add-dir", "."],
+  "model_flag": "--model",
+  "system": "prepend",
+  "user": { "mode": "arg", "flag": "-p" },
+  "tools_flag": null,
+  "approval": {
+    "acceptEdits": ["--mode", "accept-edits"],
+    "bypassPermissions": ["--dangerously-skip-permissions"],
+    "default": [],
+    "readonly": ["--mode", "plan"]
+  },
+  "isolation": {
+    "bare": [],
+    "fresh": []
+  },
+  "result_keys": ["response", "result"]
+}

package/assets/.agents/skills/aw-spec-orch/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: "aw-spec-orch"
+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 .aw-spec/orchestrator/ and the agy CLI on PATH"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Orchestrator Skill 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** (`.aw-spec/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.
+
+- **Engine + workflows (common, shared by all agents):** `.aw-spec/orchestrator/orchestrator.py`, `.aw-spec/orchestrator/workflows/aw-spec-<skill>.orch.yaml`, shared modules in `.aw-spec/orchestrator/modules/`, shared scripts in `.aw-spec/scripts/`
+- **This agent's transport profile:** `.agents/agent.json`
+
+  > 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
+  > (`.aw-spec/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 `.aw-spec/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 .aw-spec/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 .aw-spec/orchestrator/orchestrator.py \
+     .aw-spec/orchestrator/workflows/aw-spec-<skill>.orch.yaml \
+     --strategy <strategy> \
+     --checkpoint .aw-spec/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.

package/assets/.agents/skills/aw-spec-orch-demo/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: "aw-spec-orch-demo"
+description: "Prototype launcher (Antigravity): run the aw-orchestrator using the specified strategy (spawn, agent, sdk, sdk-apply)."
+argument-hint: "Optional strategy ('agent', 'spawn', 'sdk', 'sdk-apply') and/or k=value vars (e.g. 'agent out_dir=...')"
+compatibility: "Requires .aw-spec/orchestrator/ and the gemini CLI on PATH"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Orchestrator Launcher
+
+All orchestration lives in the workflow YAML and is executed by `.aw-spec/orchestrator/orchestrator.py` (the general, agent-agnostic engine). The interpreter assembles the COMPLETE payload (system + user) for every request; you never author generation context yourself.
+
+- **Engine + workflow (general):** `.aw-spec/orchestrator/orchestrator.py`, `*.orch.yaml`
+- **This agent's transport profile:** `.agents/agent.json`
+
+  > Antigravity spawns via the `agy` CLI (Gemini-based; no `--system-prompt`, so
+  > `system` is folded into the prompt). Its `sdk` block declares the SDK the
+  > `sdk`/`sdk-apply` strategies import (`google-antigravity`) and the adapter
+  > (`.aw-spec/orchestrator/adapters/google_antigravity.py`, shared per-SDK)
+  > that owns its calling convention.
+
+## Execution Steps
+
+1. **Parse Arguments**:
+   - Identify the requested strategy (one of: `agent`, `spawn`, `sdk`, `sdk-apply`). If the user specifies a strategy as the first argument, use it. Otherwise, default to `spawn`.
+   - Always pass the strategy explicitly: `--strategy <strategy>`.
+   - `--agent-profile .agents/agent.json` is required for `spawn`, `sdk`, and `sdk-apply`:
+     `spawn` reads the CLI to launch (`agy`) from it; `sdk`/`sdk-apply` read the SDK
+     package/module (and its `adapter` file) to import from its `sdk` block.
+     If the SDK package isn't installed, add `--sdk-install` so the engine
+     pip-installs the declared package first. (`agent` needs no profile.)
+   - `--checkpoint .aw-spec/orchestrator/.demo-out/demo.state.json` is required for
+     `sdk-apply` and `agent` (suspend/resume — follow the loop in step 3).
+   - `spawn` accepts `--model <name>` (e.g. `gemini-2.5-pro`); isolation is
+     best-effort for Antigravity (no `--bare` equivalent). `sdk`/`sdk-apply`
+     accept `--model <name>`; isolation is intrinsic (fresh SDK session).
+
+2. **Run the Interpreter**:
+   Run the command (include only the bracketed flags that apply to the chosen strategy):
+   ```bash
+   python3 .aw-spec/orchestrator/orchestrator.py \
+     .aw-spec/orchestrator/workflows/aw-spec-demo.orch.yaml \
+     --strategy <strategy> \
+     [--agent-profile .agents/agent.json]   # spawn, sdk, sdk-apply \
+     [--checkpoint .aw-spec/orchestrator/.demo-out/demo.state.json]  # sdk-apply, agent \
+     --json
+   ```
+
+3. **Handle Suspend/Resume Loop (for `agent` or `sdk-apply` strategies)**:
+   - If the command exits with code `2` (suspend):
+     - Read the prompt from the sidecar file `<checkpoint-path>.user.md` (and system instructions from `<checkpoint-path>.system.md`).
+     - Fulfill the request directly using your own tools (e.g., implementing the handler or reviewing files in the workspace).
+     - Write the final generation or review output to `<checkpoint-path>.response.md`.
+     - Re-run the exact same command.
+     - Repeat until the orchestrator exits with code `0`.
+
+4. **Report**:
+   Report the final JSON outputs (`status`, `outputs`, `review_pass`, generated file paths, etc.) to the user.

package/assets/.aw-spec/DESIGN-FORMAT.md

@@ -0,0 +1,151 @@
+# aw-spec design-doc format — the single high-level design (HLD)
+
+The format the spec-anchored pipeline uses for the **Design** phase. Sibling of
+`ORCH-DIALECT.md` (the orchestrator dialect) and `RULE-PARTITION.md` (which rules each
+command loads): this one governs the *artifact* those workflows read and write — the
+design document — not the engine. The authoring template is
+`.aw-spec/templates/design-template.md`.
+
+## The contract
+
+A feature's design is **one document**, living beside its spec:
+
+```
+specs/<Aggregate>/
+  spec.md      # behaviour (tech-agnostic) — WHAT / WHY — the source of truth
+  design.md    # structure & decisions (tech-agnostic HLD) — the MEDIATOR
+  changes/     # open + archived change records (delta-spec + delta-design)
+```
+
+`design.md` is the **mediator** between the spec and the generated code:
+
+```
+spec.md  ──▶  design.md  ──▶  code (+ tests)
+behaviour     structure &       generated by `implement`
+FR/BR/US/SC   decisions (HLD)    (stack bound at generation time)
+```
+
+- **One design per aggregate.** The four clean-architecture layers (Domain,
+  Application, API, Infrastructure) are **sections** of this one document, each at
+  design level. Feature = aggregate; commands are user stories inside it. *(This is
+  the **greenfield** layout, authored from `design-template.md`. See the Brownfield
+  variant below for reverse-engineered / existing-codebase designs.)*
+- **High-level, not code.** It carries entities/value-objects/events, behaviour as
+  **signatures + pre/post/invariant/raises**, use-cases, endpoint contracts, ports,
+  and the significant technical decisions with rationale — but **no complete method
+  bodies**. See `design-template.md` for the section structure (§0–§9). The domain
+  layer (§1) follows spec.md exactly — its entities/value-objects are the spec's Key
+  Entities and its invariants are the spec's Business Rules.
+- **Technology-agnostic.** Behaviour and contracts use conceptual types, never a
+  language. The SAME design.md must be generatable on a different stack. The target
+  language/framework/persistence is bound only at `implement` time from the
+  constitution's technology base + the active stack profile.
+- **Physical schema is out of scope.** PKs/FKs, columns, indexes, JSON shapes, and
+  migration SQL belong to a separate technical-data-model — design.md states WHAT is
+  stored and WHICH port persists it, not the schema.
+- **Two deferral ledgers are first-class:** §7 Assumptions (`DA-n`, clarify later)
+  and §8 Workarounds (`WA-n`, clear later). They keep the HLD honest about what it
+  defers; `implement` tags generated code that leans on them.
+- **Solution-wide rules live elsewhere, not per feature:** the layering/dependency
+  rule is the constitution's; the code-generation mechanics (folder mapping,
+  file-per-element, test pairing, stack binding) are a technology-specific rule
+  applied in the `implement` phase. `design.md` stays feature-specific and
+  technology-agnostic.
+
+## Brownfield variant (existing codebases)
+
+A design reverse-engineered from — or added forward to — an **existing** codebase is
+authored from the repo's **code-derived `design-template` override**, which
+`/aw-spec-orch onboard` reverse-engineers from the repo's own structure and installs at
+`.aw-spec/templates/overrides/design-template.md`. Both `adopt` (reverse design) and the
+forward `design` phase scaffold from it via the default template name. It is the **same
+contract** as above — one living HLD per aggregate, tech-agnostic, spec-anchored, with the
+same traceability spine and the two deferral ledgers — with **one difference that matters**:
+
+- **Structure follows the code, not a fixed layering.** The **code is the source of
+  truth**, so the design describes the system **as-built**. Its structural sections
+  are **derived from the code's own organisation** (its folders / projects / modules)
+  rather than the fixed Domain/Application/API/Infrastructure four. A component the
+  code has that fits no textbook layer (a UI tier, a worker, a host project) gets its
+  own section; a layer the code lacks does not appear. Two neutral anchors are kept
+  because every system has them and the tooling keys on them: **§1 is the domain/data
+  model** (the cross-reference tool reads it for `<Other>Id` reference edges) and one
+  **§2 subsection is the External Integrations table** (matched by heading keyword, so
+  `aw-xref` extracts contract edges from either layout). The `debt` ledger records
+  only debt the **code itself** evidences (stubs, dead code, torn seams) — being
+  organised unlike a reference architecture is **not** debt, it is the as-built shape;
+  migrating toward a target is a separate modernization decision.
+
+This keeps a brownfield design free of greenfield architectural bias while remaining a
+normal feature the CR delta loop and forward pipeline consume unchanged.
+
+## Generate forward, reconcile only the high-level back
+
+The design document and the code are **not** a byte-for-byte copy of each other.
+
+| Direction | Phase | What happens |
+|---|---|---|
+| **Generate** (forward) | Implement | The model reads spec + design.md and **generates** the code and tests — a reasoning step the design guides and constrains, not a transcription. |
+| **Reconcile** (high-level back) | Build / Run fixes | Compile/typecheck/runtime fixes happen on the **code**. Only when a fix is a **high-level technical variation** — a changed pattern, a new component, an altered contract/dependency — is that decision written back into design.md. Low-level churn stays in the code. |
+
+> **Invariant:** design.md remains a faithful **high-level** account of the built
+> system — every significant technical decision is recorded — but it is a durable
+> design reference, **not** a line-by-line mirror of the code. (This retires the old
+> `docs == files` extract/reconcile invariant.)
+
+## The traceability spine
+
+```
+FR/BR/US/SC ↔ design section (element / decision) ↔ code (+ tests) ↔ commit
+```
+
+Every design element traces **up** to a spec id, and the whole spec traces **down**
+into a design section (§6 Traceability). This is what makes the analyze gate and the
+review able to check coverage, and what keeps CR impact analysis exact.
+
+## Feature granularity (why a command is a delta, not a new feature)
+
+A **feature is the largest slice whose code no other feature owns.** Because
+`implement` regenerates the whole feature's code coherently, a shared file
+(`src/Domain/Order.cs`) must have exactly **one** owning design. So for an aggregate
+with a shared entity, **feature = the aggregate** (`Order`), and individual commands
+(`CreateOrder`, `UpdateOrder`, …) are **user stories / deltas** on the same design.md:
+
+- `CreateOrder` = US-1; `UpdateOrder` = US-2.
+- Adding `UpdateOrder` is an additive CR: a Delta Spec (`+US-2`) and a Delta Design
+  (`ADDED` new use-case/endpoint sections, `MODIFIED` the shared Order/root and
+  repository sections — see `delta-design-template.md`). The design phase amends
+  design.md doc-first, bumps the feature version (`v1.0 → v1.1`), and archives the CR;
+  `implement` regenerates the touched slice; regression re-tests the shared-file
+  dependents.
+
+Two command-level features would both claim `src/Domain/Order.cs` and collide —
+which is exactly why the aggregate is the boundary.
+
+## Migration status
+
+**Complete.** Every phase now runs this HLD model, including the executable chain.
+
+The legacy path-tagged helpers (`design-extract` / `design-reconcile` / `design-paths`)
+are **retired and deleted** from both shells. They belonged to the four-document,
+full-code model in which `design.{domain,application,api,infra}.md` carried the source
+inside ` ```lang path=… ` fences. That convention is gone — no template emits `path=`,
+and `design-scaffold` writes a single `design.md` — so all three had been finding
+nothing and no-op'ing at exit 0. (Their glob, `design.*.md`, could not have matched a
+single `design.md` even if the fences had survived: the second dot required a middle
+segment. The one legitimate remaining user of that glob, `list-features`'s informational
+`design_docs` count, is fixed to `design*.md`.)
+
+The question those helpers answered — *which files is this slice made of* — is now an
+**OKF query**, because the knowledge bundle is where that answer is actually maintained:
+
+| Need | Now |
+| --- | --- |
+| read the slice's files | `aw-xref concept-paths --feature-dir <dir>` → the concept's `source_files` |
+| record files a fix loop touched | `aw-xref concept-upsert --source-files … --merge` |
+
+`build`, `run`, and `analyze-slice` all read through `concept-paths` (feeding their fix
+loops and, in `analyze-slice`, the conformance pass) and write back through
+`concept-upsert --merge`. Both directions are advisory: `concept-paths` is strictly
+read-only and returns an empty list rather than an error when no concept exists yet, so
+a greenfield slice before its first `implement` behaves exactly as it did before.

package/assets/.aw-spec/ORCH-DIALECT.md

@@ -0,0 +1,156 @@
+# aw-spec.orchestrator/v1 — orchestrator workflow dialect
+
+The workflow dialect executed by `.aw-spec/orchestrator/orchestrator.py`, and the
+**only** workflow dialect that ships. It grew out of the earlier declarative
+`skill.yaml` dialect (`aw-spec.declarative/v1`, the `aw-spec-decl-*` skills), which
+was **retired 2026-08-03** along with its reference doc: same YAML subset, same
+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 `/aw-spec-orch` launcher.
+
+## Layout (the common folder)
+
+```
+.aw-spec/orchestrator/
+  orchestrator.py            the engine (stdlib-only; reuses run-skill's YAML loader)
+  ORCH-DIALECT.md            → this doc lives at .aw-spec/ORCH-DIALECT.md
+  README.md                  strategies, transports, checkpoint machinery
+  AGENT-PROFILE.md           profile (agent.json) reference
+  adapters/                  shared per-SDK adapters (claude_agent_sdk, google_antigravity)
+  modules/                   shared includable modules (*.orch.yaml): delta-design,
+                             delta-spec, domain-select, tech-select
+  rev-templates/             neutral (shape-only) skeletons the brownfield govern-backward
+                             authors follow — see aw-spec-onboard.orch.yaml
+  workflows/                 one aw-spec-<skill>.orch.yaml per converted skill (+ _smoke)
+.aw-spec/scripts/            53 deterministic subcommands — 36 in aw-spec-actions (a true
+                             bash+powershell pair) + 17 across aw-xref, aw-inventory,
+                             aw-parity, aw-rev-constitution (thin sh/ps1 wrappers over one
+                             python core each) — reused as-is
+```
+
+## Execution model (strictly held)
+
+1. **Context management is the orchestrator's** — as in `workflows/aw-spec-demo.orch.yaml`.
+   `build_context` REPLACES the per-request envelope; `load_standards`
+   maintains the sticky system prefix. No agent ever assembles its own context.
+2. **Execution follows any of the 4 strategies** (`--strategy`, per-step
+   `strategy:` override): `sdk`, `sdk-apply`, `spawn`, `agent` — they only
+   govern WHO fulfills a generation, never what goes into it.
+3. **The checkpoint channel is strategy-independent** (D1): `ask`,
+   `user_select` and `dispatch_hooks` suspend via `--checkpoint` under EVERY
+   strategy, so the launching agent can relay to the human. Converted-skill
+   launchers therefore always pass `--checkpoint`.
+
+## Workflow file anatomy
+
+```yaml
+name: aw-spec-<skill>
+dialect: aw-spec.orchestrator/v1     # checked by --validate
+
+inputs:                              # F10 — bound from --input
+  user_input: { description: …, required: false, bind: USER_INPUT }
+
+scripts:                             # F1 — ref map for execute_script
+  actions:
+    sh:  .aw-spec/scripts/bash/aw-spec-actions.sh
+    ps1: .aw-spec/scripts/powershell/aw-spec-actions.ps1
+
+standards:                           # F4 — optional seed of the sticky set
+  - { path: docs/architecture/clean-architecture.md, optional: true }
+
+vars: { k: v }                       # seed variables (--var k=v overrides)
+workflow: [ …steps… ]
+outputs: { k: "{{v}}" }              # resolved and printed at the end
+```
+
+Every step: `id:` (required, unique), `action:`, optional `condition:`
+(`==`/`!=`/truthy), optional `strategy:`/`model:` (generating actions),
+optional `outputs: [{name, from: "$.field"}]` (JSONPath into the step's
+structured result). `{{var}}` substitutes with dotted/index access
+(`{{q.text}}`, `{{items.0}}`); a value that is EXACTLY one `{{ref}}` yields
+the raw object, not its JSON string.
+
+## Actions
+
+| action | who runs | what it does |
+|---|---|---|
+| `set` | engine | assign vars (`vars:` or decl-style `parameters:`); raw-object aware |
+| `build_context` | engine | REPLACE the per-request envelope: `system:`/`context:` file lists (+ `context_from: <var>` holding paths a prior generation reported, + `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` tolerated; 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. `sdk-apply` = read-only generation + invoking agent applies |
+| `agent_review` | fresh agent | read-only review of `review_of_var`/`review_of` files → `{pass, issues}` |
+| `agent_author` | fresh agent | F5 — **authored artifact** (decl `llm_generate`): the INTERPRETER owns `output_target: {type: file, path}`. Generation is READ-ONLY under every strategy; the ENGINE writes the returned content (sdk-apply degrades to sdk). Optional `context:` (per-request extras), `include_standards: false` (narrow payload) |
+| `agent_query` | fresh agent | F6 — generic read-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 |
+| `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; `with:` seeds inputs; cache keys namespaced `inc:<id>/…`; module `Stop` stops the caller |
+| `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
+`parameters:` or flat step keys interchangeably, so conversion is mechanical.
+
+## The suspend-kind protocol (checkpoint transport)
+
+At each handoff the engine writes sidecars next to the state file, prints the
+`pending` request (exit 2), and the launcher fulfills it, writes
+`response_path`, and re-runs the same command. Kinds:
+
+| kind | sidecars | launcher writes to response_path | resume ingests as |
+|---|---|---|---|
+| `agent_generate` | system/user | full reply ending in ```json fence | parsed fence → replay cache |
+| `agent_review`, `agent_query` | system/user | read-only reply ending in ```json fence | parsed fence |
+| `apply` | artifact | confirmation ```json fence after writing the named files | parsed fence |
+| `author` | system/user (+`target`) | the COMPLETE file content — no fence, no commentary (the ENGINE writes `target`) | raw content |
+| `ask` | none (`prompt`/`options`/`multi` inline) | the answer as plain text (comma-separated when multi) | string / list |
+| `select` | none (`prompt`/`options` inline) | the chosen option's value | string |
+| `hook` | none (`hooks` inline) | `done` after running the mandatory slash commands | `true` |
+
+A rejected response re-suspends with a `note` explaining what to fix. The
+state file persists vars, strategy, model, profile path, `--input`, answers,
+selects, `--os` and the replay cache — a bare
+`… <workflow> --checkpoint <state>` resumes with everything restored.
+Completed steps (generations, scripts, answers, hooks) replay from the cache
+and never re-fire; loop iterations get their own keys (`loopid#i`).
+
+## CLI
+
+```
+orchestrator.py <workflow.orch.yaml>
+  --strategy sdk|sdk-apply|spawn|agent   (per-step `strategy:` overrides)
+  --agent-profile <agent.json>           spawn/sdk/sdk-apply
+  --checkpoint <statefile>               the interaction channel (always, for converted skills)
+  --input "<text>"                       bound via inputs: (F10)
+  --answer k=v … / --select stepid=v …   HITL prefills
+  --non-interactive                      CI: first option everywhere
+  --os posix|windows                     script variant (F1 / D7)
+  --model <name> / --budget / --isolation bare|fresh / --sdk-install
+  --var k=v … / --show-full / --json / --dry-run
+  --validate                             F11 — static lint, never executes
+```
+
+## decl → orch conversion map
+
+| declarative (run-skill) | orchestrator |
+|---|---|
+| `load_context` (standards, domain rules, constitution) | `load_standards` (sticky system set — D3) |
+| `load_context` (feature artifacts, templates) | `build_context` `context:` before the consuming step |
+| `llm_generate` + `output_target` | `agent_author` (same `output_target`) |
+| `llm_query` | `agent_query` (+ `schema:`, `mock:`) |
+| `include_loaded_context: false` | narrow `build_context` + `include_standards: false` |
+| `execute_script` / `verify_context` / `ask` / `user_select` / `dispatch_hooks` / `set` / `loop` / `break` / `include` | same action, `parameters:` wrapper optional |
+| implement-style code tasks | `agent_generate` (+ `agent_review`), `context_from` chaining between iterations |
+
+## Validation & smoke
+
+- `--validate` every workflow/module (unknown actions/strategies, duplicate
+  ids, script refs + files on disk, `output_target.path`, module paths,
+  unproduced `{{vars}}`, dialect header).
+- `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).

package/assets/.aw-spec/RULE-PARTITION.md

@@ -0,0 +1,126 @@
+# Rule Partition — which command reads which rules
+
+*AppWeaver · aw-spec · companion to [Spec-Anchored-Pipeline.md](Spec-Anchored-Pipeline.md) and
+[DESIGN-FORMAT.md](DESIGN-FORMAT.md)*
+
+The authority on how rule files are partitioned across the pipeline, so each phase gets a
+focused, non-overlapping context. Domain-agnostic and technology-agnostic: it describes the
+**contract**, never a particular project's files. The concrete file lists are configuration —
+they live in the two rule maps, not here.
+
+---
+
+## The principle — the spec is the pivot
+
+Domain knowledge enters the pipeline **once**, at `specify`, and is written into the spec as
+identified requirements (`BR-` / `CN-` / `DC-` / `IC-` / `FR-`). From that point on the **spec is
+the only domain input**. Later phases mediate against the spec, not against the domain files.
+
+This is what makes a spec re-platformable: swap the technical rule set and the same spec still
+governs. It also stops domain detail leaking straight into code authoring without ever being
+pinned in a reviewable requirement.
+
+> **Lift, then gate.** If a domain constraint is needed downstream, it must first be *lifted*
+> into the spec as an id. A gate that finds a constraint in neither the spec nor the design
+> reports `LIFT-FAILURE:` and routes back to `specify` — it must never invent the rule into a
+> design or into code.
+
+---
+
+## The three classes of rule input
+
+| Class | What it is | Carried by |
+|---|---|---|
+| **Domain rule files** | Business/domain rules of the active domain | `comandrulemap.md`, read by `resolve-domain` |
+| **Technical rule files** | Architecture, conventions, code-generation rules | `commandtechrulemap.md`, read by `resolve-tech` |
+| **Constitution halves** | Ratified standing principles | Referred to **directly, as-is** — never mapped |
+
+Both maps are **configuration**: to change what a phase loads, edit the map, not the workflow.
+A command with **no heading** in a map loads nothing mapped for that class and
+**soft-continues** — an absent heading is a valid state, never a failure.
+
+### The constitution halves are not mapped
+
+- `.aw-spec/memory/constitution.technical.md` — the technology base. Standing input to
+  **design + implement**. Domain-agnostic.
+- `.aw-spec/memory/constitution.domain.md` — the active domain's addenda. Standing input to
+  **specify** (and the gate checklist). Deliberately **not** loaded by design or implement.
+- `.aw-spec/memory/constitution.md` — the composed human/compatibility view. The pipeline loads
+  the halves, not this file.
+
+---
+
+## The map
+
+### `specify` — *domain modelling*
+- **Domain rule files: yes** — the domain authority. Authored INTO the spec as ids.
+- **Technical rule files: no**, with one exception: a **modelling methodology** (e.g. DDD
+  tactical patterns) may seed it. That is a domain-agnostic way of *modelling*, not a
+  technology choice. Like every other class, that exception is **configuration** — it is
+  wired under `## /aw-spec-specify` in `commandtechrulemap.md`, not hardcoded in the
+  workflow. Nothing else may go under that heading: an architecture, persistence, or
+  code-generation file there would break specify's domain purity. Greenfield wires
+  `docs/domain/domain-driven-design.md`; a code-derived (brownfield) pack wires
+  `tech/domain-modelling.md`, which `onboard` reverse-engineers from the code — the
+  as-built answer to *how does this codebase express a domain model*. Either way it is
+  **HOW to model**; **WHAT** the model is stays in the domain tier.
+- Constitution: the **domain** half.
+
+### `design` — *architecture; domain input = the spec only*
+- **Domain rule files: NEVER.** Domain reaches design solely as spec ids.
+- **Technical rule files: yes** — architecture and cross-cutting rules the design mediates the
+  spec against.
+- Constitution: the **technical** half.
+
+### `implement` / `implement-delta` — *code generation*
+- **Domain rule files: NEVER.** The design is the only input describing what to build.
+- **Technical rule files: yes** — the code-generation and convention set.
+- Constitution: the **technical** half.
+
+### `build` — *compile + repair*
+- **Technical rule files: yes** — the layering and convention rules the compile-fixer respects.
+- No domain files: build repairs against design intent, which the domain never reaches.
+
+### `run` — *runtime*
+- **Technical rule files:** only if the project evidences a runtime/hosting concern.
+
+### Gates — `analyze-design`, `analyze-delta-design`, `analyze-slice`, and the `/aw-spec-gate` overlay set
+- Load the domain **gate overlays** as a **conformance checklist**.
+- **Validation input ONLY — never authoring.** A gate may fail a document or a slice; it may
+  never write a rule into one.
+
+### `constitution`
+- Loads both classes to author the two halves from their own sources.
+
+### `adopt` (brownfield)
+- Same partition, reversed: the reversed **spec** is authored with domain rules in context; the
+  reversed **design** is authored with the technical set only, so design stays domain-free.
+- Technical files here are **reference, not authority — the CODE wins.**
+
+---
+
+## Invariants
+
+1. **No domain rule file is ever loaded by `design`, `implement`, `implement-delta` or `build`.**
+2. **Domain reaches design and code only as spec ids.**
+3. **Gate overlays validate; they never author.**
+4. **A constraint not in the spec cannot be honoured downstream** — lift it first
+   (`LIFT-FAILURE:` → back to `specify`).
+5. **An absent map heading loads nothing and soft-continues** — it is never a blocking error.
+6. **The constitution halves are referred to directly** and never listed in either map.
+
+---
+
+## Where the concrete lists live
+
+| Map | Reader | Class |
+|---|---|---|
+| `docs/domainspecs/<domain>/comandrulemap.md` | `resolve-domain` | domain rule files |
+| `docs/domainspecs/<domain>/commandtechrulemap.md` | `resolve-tech` | technical rule files |
+
+Each map keys on `## /aw-spec-<command>` headings whose `- ` bullets are workspace-relative
+file paths. Shape references for authoring a new pack live in
+`.aw-spec/orchestrator/rev-templates/`.
+
+Rule files may carry a `Commands:` header naming their consumers. That header is **derived from
+these maps** — the maps are authoritative; a header that disagrees is a bug in the header.

package/assets/.aw-spec/extensions/agent-context/extension.yml

@@ -18,15 +18,18 @@ provides:
       file: commands/aw-spec.agent-context.update.md
       description: "Refresh the managed AW-Spec section in the coding agent context file"
 
-hooks:
-  after_specify:
-    command: aw-spec.agent-context.update
-    optional: true
-    description: "Refresh agent context after specification"
-  after_plan:
-    command: aw-spec.agent-context.update
-    optional: true
-    description: "Refresh agent context after planning"
+# NO auto-wired hooks — this extension is ON-DEMAND only
+# (/aw-spec.agent-context.update). It previously declared after_specify + after_plan,
+# and installing it re-wrote both into .aw-spec/extensions.yml. Both were stale:
+#   • after_plan   — no workflow dispatches that phase; the plan/tasks tier was
+#                    retired by the spec-anchored redesign.
+#   • after_specify — the updater targets `specs/*/plan.md`, which nothing produces,
+#                    so every specify (greenfield forward loop AND brownfield CR
+#                    loop, which both enter at specify) offered a hook that could
+#                    not do its job.
+# Restore a hook here once the updater is retargeted at spec.md / design.md — that
+# retarget is the open work, not the hook wiring.
+hooks: {}
 
 tags:
   - "agent"

package/assets/.aw-spec/extensions.yml

@@ -1,23 +1,16 @@
+# Installed extensions + the hook wiring the pipeline dispatches.
+#
+# `installed:` keeps agent-context available as an ON-DEMAND extension
+# (/aw-spec.agent-context.update); it is simply no longer wired into any pipeline
+# phase. It was hooked on after_specify and after_plan, and BOTH were stale:
+#   • after_plan   — no workflow dispatches that phase at all; the plan/tasks tier
+#                    was retired by the spec-anchored redesign.
+#   • after_specify — the updater targets `specs/*/plan.md`, which nothing produces
+#                    any more, so every specify in BOTH the greenfield loop and the
+#                    brownfield CR loop offered a hook that could not do its job.
+# Re-wire it here once the updater is retargeted at spec.md / design.md.
 installed:
 - agent-context
 settings:
   auto_execute_hooks: true
-hooks:
-  after_specify:
-  - extension: agent-context
-    command: aw-spec.agent-context.update
-    enabled: true
-    optional: true
-    priority: 10
-    prompt: Execute aw-spec.agent-context.update?
-    description: Refresh agent context after specification
-    condition: null
-  after_plan:
-  - extension: agent-context
-    command: aw-spec.agent-context.update
-    enabled: true
-    optional: true
-    priority: 10
-    prompt: Execute aw-spec.agent-context.update?
-    description: Refresh agent context after planning
-    condition: null
+hooks: {}