aw-spec-cli 0.1.3 → 0.1.5

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: {}

package/assets/.aw-spec/integrations/aw-spec.manifest.json

@@ -4,14 +4,6 @@
   "installed_at": "2026-06-10T07:39:01.950069+00:00",
   "files": {
     ".aw-spec/scripts/bash/common.sh": "21cc21dd88c36e632fd052eca435c0e7ab262acaff632667dec87ff8b794ef43",
-    ".aw-spec/scripts/bash/setup-plan.sh": "4eb12c5b00f5c66a7d01b56c90898d320dcef4425d9b96652d57156c84948eda",
-    ".aw-spec/scripts/bash/setup-tasks.sh": "cf21ba2212b4dd5b435c5ea8527500cfd27768b86c0bbc7ebc3207759f118d27",
-    ".aw-spec/scripts/bash/check-prerequisites.sh": "afce0aa8db177320d83aa0b8e3619c06b865fd810781894e4a7a3f81664941ce",
-    ".aw-spec/scripts/bash/create-new-feature.sh": "324762a95ec2f534d0982931fdb11380558258791fe3bfe3ca7e11a768653134",
-    ".aw-spec/templates/constitution-template.md": "ce7549540fa45543cca797a150201d868e64495fdff39dc38246fb17bd4024b3",
-    ".aw-spec/templates/checklist-template.md": "c37695297e5d3153d64f82c21223509940b13932046c7961c42d1d669516130c",
-    ".aw-spec/templates/tasks-template.md": "fc29a233f6f5a27ca31f1aa46b596af6500c627441c6e62b2bc4a1d721525842",
-    ".aw-spec/templates/spec-template.md": "3945437fc35cd30a5b2bf7beea680337c3516826d3efa5a6b92c4a7eca1ba28e",
-    ".aw-spec/templates/plan-template.md": "cc7f7979cf8d8836ec26492785affd80791d3422a2b745062ec695be8c985ef7"
+    ".aw-spec/templates/spec-template.md": "3945437fc35cd30a5b2bf7beea680337c3516826d3efa5a6b92c4a7eca1ba28e"
   }
 }