aw-spec-cli 0.1.0 → 0.1.2

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

@@ -0,0 +1,129 @@
+---
+name: "aw-spec-addcomponent"
+description: "Add an opt-in AppWeaver framework component to the project: pick a component from docs/components/, choose one or more implementations from its integration.md catalog, and wire the matching code in."
+argument-hint: "Optional component folder name to select directly (e.g. Email)"
+compatibility: "Requires aw-spec project structure with a docs/components/ directory whose subfolders each contain an integration.md runbook"
+metadata:
+  author: "github-aw-spec"
+  source: "local"
+user-invocable: true
+disable-model-invocation: false
+---
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+The text the user typed after `/aw-spec-addcomponent` (if any) is an optional component folder name
+to select directly (e.g. `Email`). If it matches a folder under `docs/components/`, skip the
+component-selection prompt; otherwise fall through to interactive selection.
+
+## Purpose
+
+Add an **opt-in AppWeaver framework component** (Email, Jobs, QrGenerator, …) to the current
+project. Each component lives in its own folder under `docs/components/` and ships two
+agent-readable files: `README.md` (the contract) and `integration.md` (an **ordered agent
+runbook**). This command discovers the available components, lets the developer pick **one**, then
+lets them pick **one or more implementations** from that component's catalog, and finally executes
+the component's own `integration.md` runbook to add the required code.
+
+This command is the entry point; the per-component `integration.md` is the authority on *what code
+to add*. Always defer to the selected component's runbook for the actual edits, package versions,
+registration scaffold, and verification steps — do not invent integration steps from memory.
+
+## Outline
+
+1. **Discover candidate components.** List the immediate **subdirectories** of `docs/components/`
+   (directories only — ignore loose files such as `README.md`). This is the set of selectable
+   components.
+   - If `docs/components/` does not exist or has **no** subdirectories, report that no components
+     are available, point the user at `docs/components/README.md` for the expected layout, and
+     **stop** without changing anything.
+   - A component folder is only valid if it contains an `integration.md`. Skip (and note) any
+     subfolder missing one.
+
+2. **Direct argument (optional).** If the user passed an argument:
+   - If it exactly matches one of the discovered folder names, treat that as the chosen component
+     and skip to step 4.
+   - If it does not match any folder, note the mismatch, list the available names, and fall through
+     to the interactive selection in step 3.
+
+3. **Select the component (single-select).** Present the candidate components with the
+   `AskUserQuestion` tool (single-select, `multiSelect: false`). Use each folder name as the option
+   label and, if cheaply available, the one-line "Use when…" summary from
+   `docs/components/README.md` as the option description.
+   - If **more than 4** components exist, split across multiple `AskUserQuestion` questions/calls
+     (≤4 options per question).
+   - If **exactly one** component exists, ask a confirmation — *"Add component '<name>'?"* with
+     options **"Add '<name>'"** and **"Cancel"**.
+   - If the user cancels (or interactive questions cannot be asked and no valid argument was given),
+     **stop** without changing anything.
+
+4. **Load the component runbook.** Read `docs/components/<chosen>/integration.md` and, when it
+   references it, `docs/components/<chosen>/README.md`. Locate the **"Implementation catalog
+   (selection list)"** section — its table rows are the selectable implementations. Each row's
+   `Key` is the implementation identifier; capture each Key plus its human description for the
+   prompt.
+   - If `integration.md` is missing or has no implementation catalog, report that the component is
+     not integrable via this command and **stop**.
+
+5. **Select implementation(s) (multi-select).** Present the catalog rows with `AskUserQuestion`,
+   `multiSelect: true`. Use the `Key` as the option label and the row's "Implementation"/"Best for"
+   text as the description.
+   - If the catalog has a **single** row, tell the user it is the only available implementation and
+     ask them to confirm it (do not invent others).
+   - Honor any **grouping / selection rules** the component's `integration.md` states for reading
+     the answer (e.g. Jobs: pick exactly one Group A store, optionally one Group B status store).
+     If more rows exist than fit one prompt, split across multiple `AskUserQuestion` calls.
+
+6. **Empty selection → exit cleanly.** If the user submits with **nothing selected** (or cancels
+   the implementation prompt), do **not** modify the project. Report that no implementation was
+   chosen, name the component, and tell them they can re-run `/aw-spec-addcomponent` any time. Then
+   **stop**.
+
+7. **Add the code (one or more selected).** Execute the chosen component's `integration.md` runbook
+   **in order** for the selected implementation(s):
+   - Resolve the **host/startup project** the runbook targets — the single project that owns
+     `Program.cs` + the ASP.NET Core web SDK (`<App>.Service` for the Vertical Slice foundation,
+     `<App>.API` for the Modular Monolith foundation, or another name in a future template). **Find it
+     by locating `Program.cs`, not by assuming a fixed name.** These foundations have **no** separate
+     `…Application` / `…Infrastructure` project — package references, registration, and
+     `appsettings.json` all target this one project.
+   - Apply the runbook's **"Common steps"** once.
+   - Apply each selected implementation's **block** (package version in
+     `Directory.Packages.props`, `PackageReference` without `Version=`, registration line, config).
+   - Set `options.Provider` per the runbook (when multiple implementations are selected, follow the
+     runbook's rule for choosing the default/active provider — ask a single-select follow-up if it
+     requires one).
+   - Honor the cross-cutting rules in `docs/components/README.md` (R0.1–R0.5, incl. R0.2a): versions
+     only in `Directory.Packages.props`; register in the host/startup project resolved via `Program.cs`
+     (R0.2 — its `Extensions/InfrastructureServiceRegistration.cs`/`AddInfrastructure` if present,
+     else `Program.cs`); inject the abstraction; always set `options.Provider`; never commit secrets.
+   - **Register in both startup paths when they exist (R0.2a).** If the host project splits
+     registration into `AddInfrastructure` (`Extensions/InfrastructureServiceRegistration.cs`) **and**
+     `AddAspireInfrastructure` (`Extensions/AspireInfrastructureExtensions.cs`) — the
+     `if (isAspire) AddAspireInfrastructure(...) else AddInfrastructure(...)` switch in `Program.cs` —
+     add the component's registration to **both** methods, not just `AddInfrastructure`. The block is
+     the same in each, differing only in provider-specific calls (connection strings, `UseSqlite` vs
+     `UseNpgsql`) that must match that method's existing provider. Registering in only one leaves the
+     component missing whenever the app runs in the other mode.
+   - Run any optional usage/feature-slice and schema steps only if the runbook calls for them or the
+     user asks.
+
+8. **Verify and report.** Run the component runbook's **Verification** checklist (at minimum
+   `dotnet build`). Then report:
+   - the component added and which implementation key(s) were wired,
+   - the active provider,
+   - the files changed,
+   - any follow-ups the developer must do out-of-band (secrets, migrations, DDL).
+
+## Done When
+
+- [ ] A component was chosen, or nothing was changed (no components available, or the user
+      cancelled).
+- [ ] If implementations were selected, the component's `integration.md` runbook was executed for
+      each, the project builds, and the changes were reported.
+- [ ] If **no** implementation was selected, the project was left untouched and the user was told so.

package/assets/.agents/skills/aw-spec-agent-context-update/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: aw-spec-agent-context-update
+description: Refresh the managed AW-Spec section in the coding agent context file
+compatibility: Requires aw-spec project structure with .aw-spec/ directory
+metadata:
+  author: github-aw-spec
+  source: agent-context:commands/aw-spec.agent-context.update.md
+---
+
+# Update Coding Agent Context
+
+Refresh the managed AW-Spec section inside the active coding agent's context/instruction file (e.g. `CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`).
+
+## Behavior
+
+The script reads the agent-context extension config at
+`.aw-spec/extensions/agent-context/agent-context-config.yml` to discover:
+
+- `context_file` — the path of the coding agent context file to manage.
+- `context_markers.start` / `.end` — the delimiters surrounding the managed section. Defaults to `<!-- AW-SPEC START -->` and `<!-- AW-SPEC END -->` when the field is missing.
+
+It then creates, replaces, or appends the managed block so that the section points at the most recent plan path when one can be discovered (`specs/<feature>/plan.md`).
+
+If `context_file` is empty or the file cannot be located, the command reports nothing to do and exits successfully.
+
+## Execution
+
+- **Bash**: `.aw-spec/extensions/agent-context/scripts/bash/update-agent-context.sh [plan_path]`
+- **PowerShell**: `.aw-spec/extensions/agent-context/scripts/powershell/update-agent-context.ps1 [plan_path]`
+
+When `plan_path` is omitted, the script auto-detects the most recently modified `specs/*/plan.md`.

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

@@ -0,0 +1,296 @@
+---
+name: "aw-spec-analyze"
+description: "Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation."
+argument-hint: "Optional focus areas for analysis"
+compatibility: "Requires aw-spec project structure with .aw-spec/ directory"
+metadata:
+  author: "github-aw-spec"
+  source: "templates/commands/analyze.md"
+user-invocable: true
+disable-model-invocation: false
+---
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Context Reuse (cross-command dedup)
+
+**Skip Read-ing any file already in this conversation.** Before loading a standards/domain/template/spec file this command names, check whether it is already in context (loaded earlier here or by a prior `/aw-spec-*` command). If present and unchanged, reuse it and **skip the Read** — only Read files not yet loaded. A file already in context still counts as loaded; this just avoids the redundant re-read.
+
+## Auto-Loaded Engineering Standards (Required Context)
+
+**Before doing anything else in this command, load the project engineering-standards files listed below into context using the Read tool.** These were previously supplied manually as `@docs/...` mentions; they are now loaded automatically so the user does not need to pass them. Rules:
+
+- Read each file below **before** starting the Pre-Execution Checks / analysis. Treat their contents as authoritative engineering standards for this command, second only to `.aw-spec/memory/constitution.md`.
+- If a listed file does not exist, skip it silently and continue — do **not** error and do **not** ask the user to provide it.
+- This is the **domain-agnostic technical** set, so the framework is reusable across domains. Domain-specific rule files (e.g. healthcare FHIR/HL7/PHI) are **not** part of this set — they are offered separately in the **Domain Rule-File Selection** section below (sourced from `comandrulemap.md`). You can also add any extra file directly with an `@` mention.
+
+Standards for `/aw-spec-analyze`:
+- docs/security/auditing.md
+- docs/governance/coding-standards.md
+- docs/glossary/ai-rules.md
+
+## Domain Rule-File Selection (interactive)
+
+After the technical standards above are loaded, and **before** the Pre-Execution Checks, resolve the active domain and ask the user which **domain** rule files to load for this command:
+
+1. **Resolve the active domain.** Read `.aw-spec/domain.json` and take its `domain` value — the active domain-specs folder name. The candidate domain rule files are the bullet list under the `## /aw-spec-analyze` heading in `docs/domainspecs/<domain>/comandrulemap.md`.
+2. **Domain gate (missing domain or rules).** If `.aw-spec/domain.json` is absent or its `domain` is empty, **or** `docs/domainspecs/<domain>/comandrulemap.md` does not exist:
+   - Ask one single-select question with the AskUserQuestion tool — *"Domain is not set or its rule files are missing (state which: no domain set / domain '<domain>' has no comandrulemap.md). Continue without domain rules?"* — with options **"Continue (technical only)"** and **"Exit"**.
+   - **Continue (technical only)** → skip steps 3-5 and proceed with only the auto-loaded technical standards (plus any `@`-mentioned files).
+   - **Exit** → stop the command **immediately** with no side effects: do **not** run the Pre-Execution Checks, hooks, Outline, or any later step, and create/modify nothing. Tell the user to run `/aw-spec-select-domain` (or fix the domain folder) and re-run.
+   - If interactive questions cannot be asked (non-interactive/automated run), default to **Continue (technical only)**.
+   - Exception: if `comandrulemap.md` exists but has **no entries under this command's heading**, this is **not** a gate trigger — load no domain files for this command and continue normally to the Pre-Execution Checks.
+3. **Show a selection box** using the AskUserQuestion tool:
+   - Ask one single-select question — *"Domain rule files for /aw-spec-analyze:"* — with options **"Select all (recommended)"**, **"Pick a subset"**, and **"None (technical only)"**.
+   - If the user chooses **"Pick a subset"**, follow up with **multi-select** questions whose options are the individual candidate files so the user can tick the ones they want. AskUserQuestion allows ≤4 options per question and ≤4 questions per call, so split the candidates into groups of ≤4 (by category: architecture overlays, clinical domain, security overlays, governance overlays, glossary) across as many calls as needed.
+   - If interactive questions cannot be asked (non-interactive or automated run), skip the prompt and default to **Select all**.
+4. **Load the selection.** Read every file the user selected (the full list for "Select all"; nothing extra for "None"). If any selected file does not exist on disk, skip it silently and continue — do not error.
+5. **Final context set** = the always-loaded technical standards (section above) **＋** the domain files selected here **＋** any files the user passed via `@` mention in their command. The `@`-mentioned files are always loaded in addition, whether or not they appear in the candidate list, and are never removed by a "None"/subset choice.
+6. Proceed to the Pre-Execution Checks only after the selected files are loaded.
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before analysis)**:
+- Check if `.aw-spec/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_analyze` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `aw-spec.git.commit` → `/aw-spec-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Pre-Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Pre-Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    Wait for the result of the hook command before proceeding to the Goal.
+    ```
+- If no hooks are registered or `.aw-spec/extensions.yml` does not exist, skip silently
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/aw-spec-tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.aw-spec/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/aw-spec-analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.aw-spec/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Success Criteria (measurable outcomes — e.g., performance, security, availability, user success, business impact)
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.aw-spec/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: For each Functional Requirement (FR-###) and Success Criterion (SC-###), record a stable key. Use the explicit FR-/SC- identifier as the primary key when present, and optionally also derive an imperative-phrase slug for readability (e.g., "User can upload file" → `user-can-upload-file`). Include only Success Criteria items that require buildable work (e.g., load-testing infrastructure, security audit tooling), and exclude post-launch outcome metrics and business KPIs (e.g., "Reduce support tickets by 50%").
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/aw-spec-implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /aw-spec-specify with refinement", "Run /aw-spec-plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+### 9. Check for extension hooks
+
+After reporting, check if `.aw-spec/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.after_analyze` key
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
+- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.
+- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:
+  - If the hook has no `condition` field, or it is null/empty, treat the hook as executable
+  - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation
+- When constructing slash commands from hook command names, replace dots (`.`) with hyphens (`-`). For example, `aw-spec.git.commit` → `/aw-spec-git-commit`.
+- For each executable hook, output the following based on its `optional` flag:
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+  - **Mandatory hook** (`optional: false`):
+    ```
+    ## Extension Hooks
+
+    **Automatic Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+- If no hooks are registered or `.aw-spec/extensions.yml` does not exist, skip silently
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+$ARGUMENTS