aw-spec-cli 0.1.7 → 0.1.9

package/assets/.appweaver/memory/constitution.md

@@ -0,0 +1,50 @@
+# [PROJECT_NAME] Constitution
+<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+
+## Core Principles
+
+### [PRINCIPLE_1_NAME]
+<!-- Example: I. Library-First -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
+
+### [PRINCIPLE_2_NAME]
+<!-- Example: II. CLI Interface -->
+[PRINCIPLE_2_DESCRIPTION]
+<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
+
+### [PRINCIPLE_3_NAME]
+<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
+[PRINCIPLE_3_DESCRIPTION]
+<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+
+### [PRINCIPLE_4_NAME]
+<!-- Example: IV. Integration Testing -->
+[PRINCIPLE_4_DESCRIPTION]
+<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+
+### [PRINCIPLE_5_NAME]
+<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
+[PRINCIPLE_5_DESCRIPTION]
+<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
+
+## [SECTION_2_NAME]
+<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+
+[SECTION_2_CONTENT]
+<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+
+## [SECTION_3_NAME]
+<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+
+[SECTION_3_CONTENT]
+<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+
+## Governance
+<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
+
+[GOVERNANCE_RULES]
+<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
+
+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
+<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->

package/assets/.appweaver/orchestrator/.smoke-out/smoke.md

@@ -0,0 +1,6 @@
+<!-- authored by aw-orchestrator MOCK transport -->
+<!-- target: .appweaver/orchestrator/.smoke-out/smoke.md -->
+<!-- envelope: system=[] context=['.appweaver/orchestrator/.smoke-out/smoke.md'] -->
+<!-- task chars: 48 -->
+
+# (mock content)

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

@@ -0,0 +1,94 @@
+# Agent transport profile schema
+
+The orchestrator engine (`orchestrator.py`) is **agent-agnostic**. It never names
+Claude, Gemini, or Kilo. Each agent supplies a small JSON **profile** that maps
+the engine's neutral knobs onto that agent's real headless CLI flags. Each
+profile lives **once at its agent's root**, shared by every orchestrator skill
+for that agent; the engine that consumes it is the *general* file in `.appweaver/`.
+
+```
+.appweaver/orchestrator/orchestrator.py    ← general engine (reads a profile)
+.appweaver/orchestrator/adapters/*.py      ← shared SDK adapters (one per SDK, not per agent)
+.claude/agent.json                       ← Claude Code profile  (claude -p / claude-agent-sdk)
+.agents/agent.json                       ← Antigravity profile  (agy -p / google-antigravity)
+.kilocode/agent.json                     ← Kilo Code profile    (delegates to claude)
+```
+
+The launcher passes its profile with `--agent-profile <path>` (which implies
+`--transport real`).
+
+## Fields
+
+| Field | Meaning |
+|---|---|
+| `name` | label shown in the banner/logs |
+| `runtime` / `note` | free-text documentation (ignored by the engine) |
+| `bin` | the CLI executable (e.g. `claude`, `gemini`) |
+| `args` | always-on args prepended to every call |
+| `model_flag` | flag for `--model` (e.g. `--model`, `-m`); omit to ignore model |
+| `system` | how the interpreter's system block is injected: `{ "flag": "--system-prompt" }` to pass it as a flag, or `"prepend"` to fold it into the prompt (for CLIs with no system flag, e.g. gemini) |
+| `user` | how the user block is delivered: `{ "mode": "stdin" }` or `{ "mode": "arg", "flag": "-p" }` |
+| `tools_flag` | flag for the tools allowlist (e.g. `--tools`), or `null` if the CLI governs tools another way (gemini → `--approval-mode`) |
+| `approval` | map from the neutral permission mode (`acceptEdits`, `bypassPermissions`, `default`, `readonly`) to that CLI's args |
+| `isolation` | map from `--isolation` (`bare`, `fresh`) to that CLI's args (e.g. `--bare`, or `["--setting-sources", ""]`) |
+| `budget_flag` | optional flag for a per-call spend cap (`--max-budget-usd`); omit if unsupported |
+| `result_keys` | keys to look for in the CLI's JSON output that hold the final text (first match wins); falls back to raw stdout |
+| `sdk` | how the `sdk` / `sdk-apply` strategies run an isolated generation via that agent's SDK (see below) |
+
+## The `sdk` block
+
+The `sdk`/`sdk-apply` strategies never name an SDK in the engine — the profile
+declares everything:
+
+| Field | Meaning |
+|---|---|
+| `type` | label for humans/tooling (the engine does not branch on it) |
+| `package` | the pip package to install when the module isn't importable (`--sdk-install` or `auto_install: true` triggers `python -m pip install <package>`) |
+| `module` | the Python module the engine imports (e.g. `claude_agent_sdk`, `google.antigravity`) |
+| `adapter` | **required** — path (relative to this profile file) to a Python file exporting `generate(request) -> str` that owns this SDK's calling convention; may be sync or async. Shared adapters live in `.appweaver/orchestrator/adapters/`, one per SDK, so profiles whose SDKs match reference the same file (e.g. `"../.appweaver/orchestrator/adapters/claude_agent_sdk.py"`). The engine ships no SDK code of its own, so a profile without an adapter cannot run the `sdk`/`sdk-apply` strategies |
+| `auto_install` | `true` to always install the missing package without needing `--sdk-install` |
+
+`module`, `package`, and `adapter` are all required — the engine has no
+default agent, so a developer who only has one agent root (e.g. only
+`.agents/`) never depends on another agent's files being present. A missing
+or broken field/adapter stops the run with a message naming exactly what to
+fix.
+
+The adapter's `request` dict carries `system`, `user`, `tools`,
+`permission_mode`, `model`, and the full `sdk` block (for adapter-specific
+options). Adapters are keyed by SDK, not by agent:
+`adapters/google_antigravity.py` maps the neutral permission modes onto
+Antigravity policies and drives `Agent` / `LocalAgentConfig` (used by
+`.agents`), while `adapters/claude_agent_sdk.py` drives `query` /
+`ClaudeAgentOptions` (shared by `.claude` and `.kilocode`, whose SDK is the
+same) — none of which the engine knows about; it only follows the profile's
+`sdk.adapter` pointer.
+
+## How the engine builds the command
+
+```
+[bin] + args
+      + (model_flag model)                     if model_flag and --model
+      + (system.flag system)                   if system is a {flag}
+      + (tools_flag tools)                     if tools_flag
+      + approval[permission_mode | default]
+      + isolation[--isolation]
+      + (budget_flag budget)                   if budget_flag and --budget
+      + (user.flag prompt)                     if user.mode == "arg"
+stdin = prompt                                 if user.mode == "stdin"
+```
+
+When `system` is `"prepend"`, the system block is folded into the prompt
+(`system + "\n\n---\n\n" + user`) instead of passed as a flag.
+
+## Adding a new agent
+
+1. Drop an `agent.json` at that agent's root (`.<agent>/agent.json`) describing its CLI.
+2. Add a launcher in that agent's native format that calls
+   `orchestrator.py … --agent-profile .<agent>/agent.json`.
+3. For the `sdk`/`sdk-apply` strategies, add an `sdk` block and point
+   `sdk.adapter` at the matching adapter in `.appweaver/orchestrator/adapters/`
+   — or drop a new adapter there first if that SDK has none yet.
+
+No engine change required. Verify with `--dry-run` (prints the exact command
+without executing).

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

@@ -0,0 +1,300 @@
+# aw-orchestrator (prototype)
+
+A reference runtime for the architecture you sketched: **the Python interpreter
+owns 100% of context assembly; a _fresh_ agent does the execution with tools;
+control returns to the interpreter, which reviews and continues.**
+
+It is **agent-agnostic**: the same engine + workflows drive Claude Code,
+Antigravity (Gemini), or Kilo Code. The engine never names an agent — each agent
+supplies a small transport **profile**.
+
+This engine is now the **only** pipeline that ships. The earlier declarative tier
+(`aw-spec-decl-*` skills, `aw-spec.declarative/v1`) was **retired 2026-08-03**.
+
+> **`.appweaver/interpreter/run-skill.py` deliberately SURVIVES that retirement.**
+> It is no longer an entry point — nothing launches it — but `orchestrator.py`
+> imports it at load time for its YAML loader (`load_yaml`, orchestrator.py ~L112).
+> **Deleting it breaks every workflow in this directory.** Fold the loader in before
+> removing the file.
+
+## 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.
+
+```
+.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)
+  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
+.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
+```
+
+## Your diagram → this code
+
+| Diagram box | Where it lives |
+|---|---|
+| Agent skill launches the runtime | the per-agent launcher 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 |
+| 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` |
+
+## Why this overrides the launching agent's own context (your R6)
+
+Generation does **not** happen inside the launching agent's conversation. Each
+`agent_generate` / `agent_review` shells out to a **separate** process described
+by the profile. For the Claude Code profile that is:
+
+```
+claude -p --bare \
+  --system-prompt "<interpreter-authored standards>" \
+  --output-format json  --tools "Read,Write,Edit,Bash" \
+  --permission-mode acceptEdits  --no-session-persistence
+  < <interpreter-authored task on stdin>
+```
+
+- `-p` → a brand-new conversation; the caller's transcript is **not** inherited.
+- `--bare` → no CLAUDE.md / auto-memory / hooks; the only context is what we pass.
+- `--system-prompt` + stdin → the interpreter owns the system and user blocks.
+
+So every model request sees **exactly** the interpreter's payload — nothing from
+the launching agent. (The Gemini profile achieves the same isolation differently;
+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:
+
+```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
+```
+
+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
+
+# 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
+
+# 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
+```
+
+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).
+
+## Execution strategies — `--strategy`, per-step `strategy:`
+
+The interpreter assembles **100% of every payload in all strategies**; they
+differ only in *who executes it* and *who applies the file changes*. The
+developer picks per command (launcher passes `--strategy`) and can override
+per step in the workflow YAML (`strategy:` on `agent_generate`/`agent_review`).
+
+| `--strategy` | Who generates | Who applies | Instances | Isolation (R6) |
+|---|---|---|---|---|
+| `sdk` | isolated SDK instance | SDK instance (tools) | 1 | guaranteed |
+| `sdk-apply` | isolated SDK instance (read-only) | **invoking agent** (suspend/resume) | 1 + you | generation clean; apply local |
+| `spawn` | fresh CLI process (profile) | same process | N cold | guaranteed |
+| `agent` | invoking agent (suspend/resume) | invoking agent | **0** | best-effort |
+
+```bash
+# Strategy 1 — SDK generates + implements (needs: pip install claude-agent-sdk)
+python3 .appweaver/orchestrator/orchestrator.py <wf.yaml> --strategy sdk --model opus
+
+# Strategy 2 — SDK generates read-only; YOU apply the artifact (suspend kind=apply)
+python3 .appweaver/orchestrator/orchestrator.py <wf.yaml> --strategy sdk-apply \
+  --checkpoint <state.json>
+
+# Strategy 3 — the original profile transport
+python3 .appweaver/orchestrator/orchestrator.py <wf.yaml> --strategy spawn \
+  --agent-profile .claude/agent.json
+
+# Strategy 4 — zero new instances (the checkpoint section below)
+python3 .appweaver/orchestrator/orchestrator.py <wf.yaml> --strategy agent \
+  --checkpoint <state.json>
+```
+
+Rules: `spawn` needs `--agent-profile`; `agent` and `sdk-apply` need
+`--checkpoint`. Omitting `--strategy` keeps the legacy behavior
+(`--agent-profile` → spawn, `--checkpoint` → agent, neither → mock). The
+loop + checkpoint machinery is strategy-independent — every completed
+generation is written to the replay cache, so **mixed-strategy workflows
+survive suspend/resume** (an `sdk` result is not re-generated when an `agent`
+or `apply` step later suspends the run). The state file persists
+strategy/model, so resuming with a bare `--checkpoint` continues the original
+run correctly. In `sdk-apply`, `agent_review` steps degrade to a plain
+read-only `sdk` call (reviews have no apply phase). The `claude-agent-sdk`
+import is lazy — strategies `spawn`/`agent`/mock keep the engine stdlib-only.
+
+## Checkpoint transport — zero additional instances (the run-skill.py method)
+
+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
+```
+
+At each `agent_generate` / `agent_review` the interpreter writes the fully
+assembled payload to `<state>.system.md` / `<state>.user.md`, persists its
+state (`vars` seeds + a loop-aware **replay cache**), prints the pending
+request, and **exits with code 2** — which releases the invoking agent from
+the Bash call. The agent fulfills the request **in its own conversation**
+(instructed to use ONLY the payload files), writes its reply — ending with the
+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.
+
+**The trade-off, stated plainly:** the interpreter keeps 100% ownership of
+what goes *into* each payload, but the request executes inside the invoking
+agent's conversation — its system prompt and accumulated transcript ride
+along, and payloads pile up across steps. Payload ownership is preserved;
+**context isolation (R6) is not.**
+
+**`--checkpoint` + `--agent-profile` combine freely** (D1): mixing them as a
+*generation* transport still makes no sense (a step generates via the profile
+OR via the invoker, chosen by `--strategy`), but the checkpoint is also the
+**interaction channel** — `ask` / `user_select` / `dispatch_hooks` suspend
+through it under EVERY strategy so the launching agent can relay to the human.
+Converted `aw-spec-*` workflows therefore always run with `--checkpoint`,
+whatever the strategy. The full `pending.kind` protocol (`agent_generate`,
+`agent_review`/`agent_query`, `apply`, `author`, `ask`, `select`, `hook`) is
+documented in `.appweaver/ORCH-DIALECT.md`.
+
+| | profile transports (`--agent-profile`) | checkpoint (`--checkpoint`) |
+|---|---|---|
+| Agent instances | +1 fresh process per generation | **0** — the invoker generates |
+| Model request contains | ONLY the interpreter's payload | payload **+ the invoker's context** |
+| R6 (context override) | guaranteed by construction | best-effort (instructions only) |
+| Extra auth / CLI needed | yes (`claude`/`gemini` + key for `--bare`) | none |
+| Permission prompts / HITL | none (headless) | the agent's native ones |
+
+## The three 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.
+
+## Invoking from an agent (the top of your diagram)
+
+You don't run this by hand — each agent's skill/workflow launches it, and the
+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>
+     → interpreter builds context → spawns a fresh CLI per step (isolated)
+     → interpreter reviews + continues → agent reports final JSON
+```
+
+Contrast the retired `aw-spec-decl-*` launchers, which ran `run-skill.py --llm agent`
+and then asked the *same* agent to fulfill `pending_generation` in its own context —
+the context leak this design removes, and one reason that tier was retired.
+
+## Workflow vocabulary (prototype)
+
+- `set` — set vars (`vars: {k: v}`).
+- `build_context` — declare the envelope for the next request: `system:` files
+  (→ system prompt) and `context:` files (→ user message). Optional entries
+  `{ path: …, optional: true }` are tolerated when missing. `context_from: <var>`
+  appends a var holding a list of paths (e.g. files a prior generation wrote).
+- `agent_generate` — fresh generation with write tools. `task:` is the
+  instruction; **the interpreter does not specify output paths** — the fresh
+  runtime/LLM decides them (per the loaded folder-structure standards) and
+  reports them in the result's `files[]`. Bind with
+  `outputs: [{ name: gen_files, from: "$.files" }]`.
+- `agent_review` — fresh, read-only generation. `review_of_var: <var>` reviews
+  the files a prior generation reported (or `review_of:` for a static list);
+  returns `{pass, issues}`.
+- `loop` (`while:` + `max_iterations:`) with `break` (+ `condition:`) — the
+  review→revise cycle.
+
+The engine now implements the FULL dialect the `aw-spec-*` conversions need on
+top of these demo 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`
+(shared modules), foreach loops (`over:`/`as:`), `inputs:`/`--input`, and
+`--validate`. See `.appweaver/ORCH-DIALECT.md` for the complete reference;
+shared per-skill workflows live in `workflows/`, shared modules in `modules/`,
+and each root's parametric `/appweaver <skill> [strategy] [input…]`
+launcher runs them.
+
+## How this differed from `run-skill.py` (historical — that tier is retired)
+
+| | `run-skill.py` (retired tier) | `orchestrator.py` (ships) |
+|---|---|---|
+| Context handed over | file **paths** (agent/checkpoint) | fully **assembled content** |
+| Where generation runs | inside the caller's conversation | a **fresh**, profile-driven process — or the caller, via `--checkpoint` |
+| Caller's context leaks in | yes (agent/checkpoint mode) | **no** with a profile; yes with `--checkpoint` (by design) |
+| Multi-agent | per-agent launchers | per-agent launchers **+ transport profiles** |
+| Deterministic scripts/gates/hooks | rich (scaffolding, domain gate, …) | ported (`execute_script`, `verify_context`, `dispatch_hooks`, `include`, HITL — see `ORCH-DIALECT.md`) |
+
+That intended path — fold this mechanism back into `run-skill.py` — is now moot:
+the declarative tier was retired instead, and this engine won. What remains of
+`run-skill.py` is its YAML loader, which `orchestrator.py` imports (see the note
+at the top of this file).
+
+## Not yet (deliberately)
+
+- Structured output parsed from a trailing JSON fence (one retry on fresh
+  strategies), not enforced via a schema.
+- Gemini isolation is best-effort (no `--bare` equivalent); a `GEMINI.md` in the
+  working directory would still load.
+- No provider-side prompt-cache warming; `load_standards` keeps the system
+  prefix byte-stable across steps so a provider cache CAN hit, but nothing
+  primes it.
+- No session context ledger for the `agent` strategy (run-skill's
+  cross-command dedup); fresh strategies don't need one.
+
+(The deterministic dispatcher — scripts, gates, hooks, domain-select, includes,
+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
+
+# 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
+
+# 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 \
+  --strategy sdk-apply --agent-profile .claude/agent.json \
+  --checkpoint .appweaver/orchestrator/.demo-out/demo.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

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

@@ -0,0 +1,74 @@
+"""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
+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.
+
+Contract (see orchestrator.py `_run_sdk`):
+    generate(request) -> str        # the model's final reply text
+request keys:
+    system            interpreter-assembled system block (standards + rules)
+    user              interpreter-assembled user block (context + task)
+    tools             comma-separated tool allowlist for the fresh session
+    permission_mode   neutral mode: readonly | acceptEdits |
+                      bypassPermissions | default
+    model             model name or None
+    sdk               the profile's full sdk block (for adapter options)
+generate may be sync or async — the engine handles both.
+"""
+import os
+
+
+def _dotenv_get(name):
+    """Look up one key in ./.env then ~/.env (workspace wins); None if absent."""
+    for env_path in (os.path.join(os.getcwd(), ".env"), os.path.expanduser("~/.env")):
+        if not os.path.exists(env_path):
+            continue
+        with open(env_path, "r", encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    k, v = line.split("=", 1)
+                    if k.strip() == name:
+                        return v.strip().strip("'\"")
+    return None
+
+
+# the SDK authenticates via ANTHROPIC_API_KEY (unless the claude CLI login is
+# available); a value exported in the shell always wins — the .env lookup only
+# fills the gap when nothing is exported
+_key = _dotenv_get("ANTHROPIC_API_KEY")
+if _key:
+    os.environ.setdefault("ANTHROPIC_API_KEY", _key)
+
+from claude_agent_sdk import ClaudeAgentOptions, query
+
+# neutral permission modes → SDK modes ('readonly' is the workflow's notion,
+# not an SDK mode — read-only is enforced by the tools allowlist)
+_PERMISSION_MAP = {"acceptEdits": "acceptEdits",
+                   "bypassPermissions": "bypassPermissions",
+                   "default": "default", "readonly": "default"}
+
+
+async def generate(request):
+    kwargs = dict(
+        system_prompt=request["system"],
+        allowed_tools=[t.strip() for t in (request.get("tools") or "").split(",")
+                       if t.strip()],
+        permission_mode=_PERMISSION_MAP.get(request["permission_mode"], "default"),
+        setting_sources=[],   # isolation: no CLAUDE.md / settings / hooks
+    )
+    if request.get("model"):
+        kwargs["model"] = request["model"]
+    options = ClaudeAgentOptions(**kwargs)
+    raw, texts = "", []
+    async for msg in query(prompt=request["user"], options=options):
+        r = getattr(msg, "result", None)
+        if isinstance(r, str) and r:
+            raw = r          # ResultMessage: the final reply text
+        for blk in getattr(msg, "content", None) or []:
+            t = getattr(blk, "text", None)
+            if t:
+                texts.append(t)
+    return raw or "\n".join(texts)

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

@@ -0,0 +1,74 @@
+"""google-antigravity adapter — a shared SDK adapter, loaded by the
+aw-orchestrator engine when an agent profile's `sdk.adapter` points here
+(.agents/agent.json does). Adapters live in this library keyed by SDK, not
+by agent: everything google-antigravity-specific is HERE, the engine ships
+no SDK code of its own, and each profile declares which adapter drives its
+SDK.
+
+Contract (see orchestrator.py `_run_sdk`):
+    generate(request) -> str        # the model's final reply text
+request keys:
+    system            interpreter-assembled system block (standards + rules)
+    user              interpreter-assembled user block (context + task)
+    tools             the workflow's neutral tools list (informational here;
+                      Antigravity governs capability via policies instead)
+    permission_mode   neutral mode: readonly | acceptEdits |
+                      bypassPermissions | default
+    model             model name or None
+    sdk               the profile's full sdk block (for adapter options)
+generate may be sync or async — the engine handles both.
+"""
+import os
+
+
+def _dotenv_get(name):
+    """Look up one key in ./.env then ~/.env (workspace wins); None if absent."""
+    for env_path in (os.path.join(os.getcwd(), ".env"), os.path.expanduser("~/.env")):
+        if not os.path.exists(env_path):
+            continue
+        with open(env_path, "r", encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    k, v = line.split("=", 1)
+                    if k.strip() == name:
+                        return v.strip().strip("'\"")
+    return None
+
+
+# the SDK authenticates via GEMINI_API_KEY; a value exported in the shell
+# always wins — the .env lookup only fills the gap when nothing is exported
+_key = _dotenv_get("GEMINI_API_KEY")
+if _key:
+    os.environ.setdefault("GEMINI_API_KEY", _key)
+
+from google.antigravity import Agent, LocalAgentConfig
+from google.antigravity.hooks import policy
+
+# tools an isolated reviewer may use when the workflow asks for readonly
+_READONLY_TOOLS = ("view_file", "list_directory", "search_directory",
+                   "find_file", "finish", "ask_question")
+
+
+def _policies(permission_mode):
+    """Neutral permission modes → Antigravity policy chains."""
+    if permission_mode == "readonly":
+        return [policy.deny_all()] + [policy.allow(t) for t in _READONLY_TOOLS]
+    if permission_mode == "bypassPermissions":
+        return [policy.allow_all()]
+    # acceptEdits / default: edits proceed, shell commands need confirmation
+    return [policy.confirm_run_command()]
+
+
+async def generate(request):
+    config = LocalAgentConfig(
+        system_instructions=request["system"],
+        policies=_policies(request["permission_mode"]),
+        # a fresh SDK session has no workspace by default; grant the project
+        # root so the isolated generation can read/write the files it decides
+        workspaces=[os.getcwd()],
+        model=request.get("model") or None,
+    )
+    async with Agent(config=config) as agent:
+        response = await agent.chat(request["user"])
+        return await response.text()