aw-spec-cli 0.1.4 → 0.1.5

package/assets/.aw-spec/templates/spec-template.md

@@ -1,131 +1,252 @@
-# Feature Specification: [FEATURE NAME]
+# Specification: [AGGREGATE]
 
-**Feature Branch**: `[###-feature-name]`
+**Aggregate (feature)**: `[Aggregate]`  <!-- the feature = the aggregate, e.g. Order -->
 
-**Created**: [DATE]
+**Spec home**: `specs/[Aggregate]/`
+
+**Version**: v1.0   <!-- living truth; every applied change request bumps this — see Change History -->
 
 **Status**: Draft
 
 **Input**: User description: "$ARGUMENTS"
 
-## User Scenarios & Testing *(mandatory)*
+<!--
+  AGGREGATE = FEATURE. This spec covers ONE aggregate (e.g. Order) and is the
+  single LIVING source of truth for its whole lifecycle. Every operation on it
+  (CreateOrder, UpdateOrder, …) is a USER STORY below — NOT a separate feature.
+  A later requirement is a new US-n added here as a delta (see .aw-spec/changes/
+  and delta-spec-template.md), never a new spec folder. One spec + one design.md
+  (specs/[Aggregate]/design.md) — the DESIGN derives from THIS document.
+
+  Section order is intentional: establish the business need and scope, then the
+  stable core the aggregate IS (requirements → rules → constraints → entities →
+  data classification → integration contracts → edge cases), then the prioritized
+  user journeys that exercise it, then measurable success.
+
+  DOMAIN LIFT (specify's job): three sections — Constraints & NFRs (CN-), Data
+  Classification (DC-), Integration Contracts (IC-) — are where specify LIFTS
+  domain-derived constraints out of the domain rule files into the spec. Design
+  authors architecture from the spec ONLY, so anything not captured here never
+  reaches design. Fill them when the domain applies; keep them (empty → "None")
+  otherwise.
+-->
+
+## Business Need
 
 <!--
-  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
-  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
-  you should still have a viable MVP (Minimum Viable Product) that delivers value.
-
-  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
-  Think of each story as a standalone slice of functionality that can be:
-  - Developed independently
-  - Tested independently
-  - Deployed independently
-  - Demonstrated to users independently
+  ACTION REQUIRED: Why this aggregate exists — the problem, the affected users,
+  and the value delivered. Business-facing; no implementation detail.
 -->
 
-### User Story 1 - [Brief Title] (Priority: P1)
+[The problem this aggregate solves, who it serves, and the value it delivers.]
 
-[Describe this user journey in plain language]
+## Scope & Assumptions
 
-**Why this priority**: [Explain the value and why it has this priority level]
+### Aggregate Boundary
 
-**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+<!--
+  The aggregate = the largest slice whose code no other feature owns. State what
+  it OWNS, what it only REFERENCES (by identifier, not owned), and what is out of
+  scope. This anchors the design's "dependencies point inward" and keeps commands
+  as deltas on THIS aggregate rather than new features.
+-->
 
-**Acceptance Scenarios**:
+- **Owns**: [entities/behaviour inside this aggregate — e.g. Order, OrderLine]
+- **References (by id, not owned)**: [Customer, Product — read-only / by identifier]
+- **Out of scope / non-goals**: [explicitly excluded — e.g. payment settlement, shipping]
 
-1. **Given** [initial state], **When** [action], **Then** [expected outcome]
-2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+### Assumptions
 
----
+<!--
+  Reasonable defaults chosen where the description was silent, plus dependencies
+  on existing systems/services.
+-->
 
-### User Story 2 - [Brief Title] (Priority: P2)
+- [Assumption about target users, e.g., "Users have stable internet connectivity"]
+- [Assumption about scope, e.g., "Mobile support is out of scope for v1"]
+- [Dependency on an existing system/service, e.g., "Requires the existing user-profile API"]
 
-[Describe this user journey in plain language]
+## System Requirements *(mandatory)*
 
-**Why this priority**: [Explain the value and why it has this priority level]
+<!--
+  Functional requirements in EARS notation (Easy Approach to Requirements Syntax):
+  atomic, testable, unambiguous. Choose the pattern that fits each requirement —
+
+    • Ubiquitous     THE SYSTEM SHALL <requirement>
+    • Event-driven   WHEN <trigger> THE SYSTEM SHALL <response>
+    • State-driven   WHILE <in a state> THE SYSTEM SHALL <response>
+    • Unwanted       IF <condition/error> THEN THE SYSTEM SHALL <response>
+    • Optional       WHERE <feature is present> THE SYSTEM SHALL <response>
+
+  Give each a STABLE id (FR-001, …) — design sections and code trace to these ids.
+  Mark genuine unknowns "[NEEDS CLARIFICATION: <question>]" (≤3; scope/UX/security
+  only, and only where no reasonable default exists).
+-->
 
-**Independent Test**: [Describe how this can be tested independently]
+- **FR-001**: WHEN [a customer submits an order] THE SYSTEM SHALL [create it in Draft state].
+- **FR-002**: THE SYSTEM SHALL [persist every order under a unique identifier].
+- **FR-003**: IF [the order has no line items] THEN THE SYSTEM SHALL [reject the submission].
+- **FR-004**: WHILE [an order is in Draft] THE SYSTEM SHALL [allow line items to be added or removed].
+- **FR-005**: WHERE [tax calculation is enabled] THE SYSTEM SHALL [apply the regional tax rule].
 
-**Acceptance Scenarios**:
+## Business Rules *(invariants — always true, technology-agnostic)*
 
-1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+<!--
+  ACTION REQUIRED: Constraints that must ALWAYS hold for the aggregate, independent
+  of any single operation. These become the design's §Domain invariants and must be
+  enforceable and testable. Give each a STABLE id (BR-001, …).
+-->
 
----
+- **BR-001**: [An order's total MUST never be negative.]
+- **BR-002**: [A submitted order MUST always have at least one line item.]
+- **BR-003**: [An order's identifier is immutable once created.]
 
-### User Story 3 - [Brief Title] (Priority: P3)
+## Constraints & Non-Functional Requirements *(domain lift — CN)*
 
-[Describe this user journey in plain language]
+<!--
+  ACTION REQUIRED (when the domain applies; else "None (as of vX.Y)"). Constraints the
+  aggregate MUST satisfy that are NEITHER functional behaviour (those are FR) NOR
+  always-true business invariants (those are BR): the regulatory, retention,
+  immutability, audit-mandate, and performance-as-a-limit rules. Many are LIFTED here
+  by specify from the domain rule files (e.g. persistence.domain, auditing.domain,
+  data-classification.domain) so they survive into design — which reads the spec ONLY.
+  Give each a STABLE id (CN-001, …); design's §5 Cross-Cutting and the analyze gate
+  trace to these ids. State each as testable; where lifted, cite the source rule.
+-->
 
-**Why this priority**: [Explain the value and why it has this priority level]
+- **CN-001**: [Retention — e.g. submitted orders + their audit trail are retained for [period] per [policy]; hard delete is forbidden once submitted (logical/retire only). — lifted from persistence.domain]
+- **CN-002**: [Audit immutability — e.g. every create/modify/cancel emits an append-only audit entry (User, Timestamp, Action, Previous, New). — lifted from auditing.domain]
+- **CN-003**: [Data integrity — e.g. records subject to [regime] satisfy [integrity standard].]
+- **CN-004**: [Performance-as-a-limit — e.g. P95 read latency < 200 ms at 200 RPS; not a behaviour, a bound.]
 
-**Independent Test**: [Describe how this can be tested independently]
+## Key Entities *(the aggregate's conceptual model — no implementation detail)*
 
-**Acceptance Scenarios**:
+<!--
+  The aggregate root and the entities/value objects inside its boundary: what each
+  represents, its key attributes, lifecycle/states, and relationships. Reference to
+  OTHER aggregates is by identifier only (see Aggregate Boundary).
+-->
 
-1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+- **[Aggregate root — e.g. Order]**: [what it represents; key attributes; lifecycle/states, e.g. Draft → Submitted → Fulfilled]
+- **[Entity / value object — e.g. OrderLine]**: [what it represents; relationship to the root]
 
----
+## Data Classification *(domain lift — DC)*
 
-[Add more user stories as needed, each with an assigned priority]
+<!--
+  ACTION REQUIRED (when the aggregate handles sensitive data; else "None (as of vX.Y)").
+  The sensitivity taxonomy for this aggregate's data and the exposure rules that follow:
+  which categories exist, which Key-Entity fields fall in each, and where each category
+  MAY / MUST NOT appear (public API surface, logs, metrics, traces, external projections).
+  Lifted by specify from the domain data-classification rules. Design enforces these; the
+  analyze-design / analyze-slice gates check them. Give each a STABLE id (DC-001, …); reference fields by
+  the names used in Key Entities.
+-->
+
+| id | Category | Applies to (fields / entities) | Exposure rule |
+|---|---|---|---|
+| DC-001 | [Public] | [id, status, non-sensitive attributes] | [may appear on the public API + external projections] |
+| DC-002 | [Sensitive / restricted] | [PII, pre-release, commercially-sensitive fields] | [MUST NOT appear on the public surface, nor in logs / metrics / traces] |
+| DC-003 | [Externally-sourced] | [imported fields] | [carries provenance; [handling rule]] |
+
+## Integration Contracts *(domain lift — IC)*
+
+<!--
+  ACTION REQUIRED (when the aggregate interoperates; else "None (as of vX.Y)"). The
+  external contracts this aggregate MUST satisfy — interoperability obligations lifted by
+  specify from the domain interop rules (e.g. FHIR/HL7/DICOM projections, terminology
+  services, inbound feeds). State each at CONTRACT level: which standard, which resources,
+  direction (inbound/outbound), projection vs system-of-record — NOT the adapter design
+  (design realises these in its API / Infrastructure layers). Give each a STABLE id
+  (IC-001, …); design's §4.2 External Integrations traces to these ids.
+-->
 
-### Edge Cases
+- **IC-001**: [Outbound projection — e.g. the aggregate SHALL project to [external standard / resources] as read-only projections (not the system of record); identifiers map to [external identifier]; coded fields to [coded type].]
+- **IC-002**: [Reference-data validation — e.g. coded values SHALL validate against [terminology / reference service]; no invented codes.]
+- **IC-003**: [Inbound feed — e.g. inbound [feed/standard] SHALL flow through an Interop adapter, never a direct write path to the aggregate.]
+
+## Edge Cases & Exceptional Scenarios
 
 <!--
-  ACTION REQUIRED: The content in this section represents placeholders.
-  Fill them out with the right edge cases.
+  ACTION REQUIRED: Boundary conditions, error paths, and concurrency/consistency
+  cases. Each should map to a System Requirement (often an IF…THEN unwanted-behaviour
+  requirement) or a Business Rule.
 -->
 
-- What happens when [boundary condition]?
-- How does system handle [error scenario]?
+- What happens when [boundary condition, e.g., the same order is submitted twice]?
+- How does the system handle [error scenario, e.g., a referenced product no longer exists]?
 
-## Requirements *(mandatory)*
+## User Stories *(prioritized)*
 
 <!--
-  ACTION REQUIRED: The content in this section represents placeholders.
-  Fill them out with the right functional requirements.
+  Prioritized user journeys (P1 = most critical). Each MUST be INDEPENDENTLY
+  TESTABLE — implementing just one still yields a viable slice of value that can be
+  developed, tested, deployed, and demonstrated on its own.
+
+  Give each a STABLE id (US-1, US-2, …); design sections trace to these ids. Each
+  story exercises specific System Requirements / Business Rules — cite them so the
+  spine (US ↔ FR/BR ↔ design ↔ code) stays exact. On this living spec, note when a
+  story entered or changed: "Added: vX.Y (CR-…)" / "Modified: vX.Y (CR-…)".
 -->
 
-### Functional Requirements
+### US-1 - [Brief Title] (Priority: P1)   ·   _Added: v1.0_
+
+[Describe this user journey in plain language.]
+
+**Why this priority**: [The value and why it ranks here.]
+
+**Exercises**: [FR-001, FR-003, BR-001]
+
+**Acceptance Criteria**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+**Independent Test**: [How this story is verified on its own and the value it delivers.]
+
+---
+
+### US-2 - [Brief Title] (Priority: P2)   ·   _Added: v1.0_
 
-- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
-- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
-- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
-- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
-- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+[Describe this user journey in plain language.]
 
-*Example of marking unclear requirements:*
+**Why this priority**: [The value and why it ranks here.]
 
-- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
-- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+**Exercises**: [FR-…, BR-…]
 
-### Key Entities *(include if feature involves data)*
+**Acceptance Criteria**:
 
-- **[Entity 1]**: [What it represents, key attributes without implementation]
-- **[Entity 2]**: [What it represents, relationships to other entities]
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+**Independent Test**: [How this story is verified on its own.]
+
+---
+
+[Add more user stories as needed (US-3, US-4, …), each with a priority and a stable id.]
 
 ## Success Criteria *(mandatory)*
 
 <!--
-  ACTION REQUIRED: Define measurable success criteria.
-  These must be technology-agnostic and measurable.
+  ACTION REQUIRED: Measurable, technology-agnostic outcomes — verified at the
+  `analyze-slice` phase. Give each a STABLE id (SC-001, …).
 -->
 
 ### Measurable Outcomes
 
-- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
-- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
-- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
-- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]
+- **SC-001**: [Measurable metric, e.g., "A customer can place an order in under 2 minutes."]
+- **SC-002**: [Measurable metric, e.g., "The system sustains 1000 concurrent orders without degradation."]
+- **SC-003**: [User-satisfaction metric, e.g., "90% of first-time users complete an order without assistance."]
+- **SC-004**: [Business metric, e.g., "Reduce order-related support tickets by 50%."]
 
-## Assumptions
+## Change History
 
 <!--
-  ACTION REQUIRED: The content in this section represents placeholders.
-  Fill them out with the right assumptions based on reasonable defaults
-  chosen when the feature description did not specify certain details.
+  The living-truth ledger. Every applied change request appends a row here, carrying
+  the version it ships as. finalize-delta writes the row when it merges the delta;
+  close-delta then archives the CR, bumps the minor version in active_version.json and
+  stamps that same number into this document's **Version** header — one mechanism, one
+  stage, so header, row and active_version.json never disagree. Newest last.
 -->
 
-- [Assumption about target users, e.g., "Users have stable internet connectivity"]
-- [Assumption about scope boundaries, e.g., "Mobile support is out of scope for v1"]
-- [Assumption about data/environment, e.g., "Existing authentication system will be reused"]
-- [Dependency on existing system/service, e.g., "Requires access to the existing user profile API"]
+| Version | Date | Change | User stories | CR |
+|---------|------|--------|--------------|-----|
+| v1.0 | [DATE] | Initial specification | US-1 | — |

package/assets/.claude/agent.json

@@ -0,0 +1,27 @@
+{
+  "name": "claude-code",
+  "sdk": {
+    "type": "claude-agent-sdk",
+    "package": "claude-agent-sdk",
+    "module": "claude_agent_sdk",
+    "adapter": "../.aw-spec/orchestrator/adapters/claude_agent_sdk.py"
+  },
+  "runtime": "Claude Code CLI (claude -p)",
+  "bin": "claude",
+  "args": ["-p", "--output-format", "json", "--no-session-persistence"],
+  "model_flag": "--model",
+  "system": { "flag": "--system-prompt" },
+  "user": { "mode": "stdin" },
+  "tools_flag": "--tools",
+  "approval": {
+    "acceptEdits": ["--permission-mode", "acceptEdits"],
+    "bypassPermissions": ["--permission-mode", "bypassPermissions"],
+    "default": ["--permission-mode", "default"]
+  },
+  "isolation": {
+    "bare": ["--bare"],
+    "fresh": ["--setting-sources", ""]
+  },
+  "budget_flag": "--max-budget-usd",
+  "result_keys": ["result"]
+}

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

@@ -0,0 +1,55 @@
+---
+name: "aw-spec-orch"
+description: "Parametric launcher (Claude Code): 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 claude 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:** `.claude/agent.json`
+
+  > Claude Code spawns via the `claude -p` CLI (native `--system-prompt`,
+  > `--tools`, and `--bare` isolation). Its `sdk` block declares the SDK the
+  > `sdk`/`sdk-apply` strategies import (`claude-agent-sdk`) and the adapter
+  > (`.aw-spec/orchestrator/adapters/claude_agent_sdk.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 .claude/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 .claude/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/.claude/skills/aw-spec-orch-demo/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: "aw-spec-orch-demo"
+description: "Prototype launcher (Claude Code): 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 claude 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:** `.claude/agent.json`
+
+  > Claude Code spawns via the `claude -p` CLI (native `--system-prompt`,
+  > `--tools`, and `--bare` isolation). Its `sdk` block declares the SDK the
+  > `sdk`/`sdk-apply` strategies import (`claude-agent-sdk`) and the adapter
+  > (`.aw-spec/orchestrator/adapters/claude_agent_sdk.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 .claude/agent.json` is required for `spawn`, `sdk`, and `sdk-apply`:
+     `spawn` reads the CLI to launch 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` may also add `--isolation bare|fresh` and `--model <name>` (bare is
+     strongest; use it when `ANTHROPIC_API_KEY` is set). `sdk`/`sdk-apply` accept
+     `--model <name>`; isolation is intrinsic (fresh SDK session, no settings).
+
+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 .claude/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/.kilocode/agent.json

@@ -0,0 +1,28 @@
+{
+  "name": "kilocode",
+  "sdk": {
+    "type": "claude-agent-sdk",
+    "package": "claude-agent-sdk",
+    "module": "claude_agent_sdk",
+    "adapter": "../.aw-spec/orchestrator/adapters/claude_agent_sdk.py"
+  },
+  "runtime": "Kilo Code launches the interpreter; generation delegates to the Claude Code CLI",
+  "note": "Kilo Code is a VS Code extension with no standalone headless generation CLI, so this profile reuses `claude -p` for the fresh generation. To generate via Gemini instead, replace bin/args/system/user/tools_flag/approval with the .agents (antigravity) profile's values.",
+  "bin": "claude",
+  "args": ["-p", "--output-format", "json", "--no-session-persistence"],
+  "model_flag": "--model",
+  "system": { "flag": "--system-prompt" },
+  "user": { "mode": "stdin" },
+  "tools_flag": "--tools",
+  "approval": {
+    "acceptEdits": ["--permission-mode", "acceptEdits"],
+    "bypassPermissions": ["--permission-mode", "bypassPermissions"],
+    "default": ["--permission-mode", "default"]
+  },
+  "isolation": {
+    "bare": ["--bare"],
+    "fresh": ["--setting-sources", ""]
+  },
+  "budget_flag": "--max-budget-usd",
+  "result_keys": ["result"]
+}

package/assets/.kilocode/workflows/aw-spec-orch-demo.md

@@ -0,0 +1,59 @@
+---
+name: "aw-spec-orch-demo"
+description: "Prototype launcher (Kilo Code): 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 claude 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:** `.kilocode/agent.json`
+
+  > Kilo Code has no native headless CLI, so it reuses `claude -p` for `spawn`
+  > (native `--system-prompt`, `--tools`, `--bare` isolation). Its `sdk` block
+  > declares the SDK the `sdk`/`sdk-apply` strategies import (`claude-agent-sdk`)
+  > and the adapter (`.aw-spec/orchestrator/adapters/claude_agent_sdk.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 .kilocode/agent.json` is required for `spawn`, `sdk`, and `sdk-apply`:
+     `spawn` reads the CLI to launch 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` may also add `--isolation bare|fresh` and `--model <name>` (bare is
+     strongest; use it when `ANTHROPIC_API_KEY` is set). `sdk`/`sdk-apply` accept
+     `--model <name>`; isolation is intrinsic (fresh SDK session, no settings).
+
+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 .kilocode/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/.kilocode/workflows/aw-spec-orch.md

@@ -0,0 +1,55 @@
+---
+name: "aw-spec-orch"
+description: "Parametric launcher (Kilo Code): 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 claude 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:** `.kilocode/agent.json`
+
+  > Kilo Code has no native headless CLI, so it reuses `claude -p` for `spawn`
+  > (native `--system-prompt`, `--tools`, `--bare` isolation). Its `sdk` block
+  > declares the SDK the `sdk`/`sdk-apply` strategies import (`claude-agent-sdk`)
+  > and the adapter (`.aw-spec/orchestrator/adapters/claude_agent_sdk.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 .kilocode/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 .kilocode/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/docs/architecture/clean-architecture.md

@@ -1,6 +1,6 @@
 # Clean Architecture Standards
 
-> Pure technology (domain-agnostic). NON-NEGOTIABLE. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+> Pure technology (domain-agnostic). NON-NEGOTIABLE. Commands: `/aw-spec-design`, `/aw-spec-build`.
 
 ## Dependency direction