aw-spec-cli 0.1.0 → 0.1.1

package/assets/.agents/skills/aw-spec-select-domain/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: "aw-spec-select-domain"
+description: "Select the active domain-specs folder and store it in .aw-spec/domain.json, so all AW-Spec commands load the right domain rule files."
+argument-hint: "Optional domain folder name to set directly (e.g. healthcare)"
+compatibility: "Requires aw-spec project structure with .aw-spec/ and docs/domainspecs/ directories"
+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-select-domain` (if any) is an optional domain folder name to set directly.
+
+## Purpose
+
+Set the **active domain** for this project. The active domain is the name of a folder under
+`docs/domainspecs/`. It is stored in `.aw-spec/domain.json` as `{ "domain": "<folder-name>" }`,
+and every `/aw-spec-*` command resolves `docs/domainspecs/<domain>/comandrulemap.md` from it to
+offer that domain's rule files.
+
+## Outline
+
+1. **Discover candidate domains.** List the immediate **subdirectories** of `docs/domainspecs/`
+   (directories only — ignore loose files). This is the set of selectable domains.
+   - If `docs/domainspecs/` does not exist or has **no** subdirectories, report that no domains
+     are available, instruct the user to create `docs/domainspecs/<name>/` containing a
+     `comandrulemap.md` (laid out like the healthcare one), and **stop** without writing anything.
+
+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 domain 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. **Interactive selection.** Present the candidate domains with the AskUserQuestion tool:
+   - If **2–4** domains exist: a single single-select question listing them.
+   - If **more than 4** domains exist: split across multiple questions/calls (AskUserQuestion
+     allows ≤4 options per question and ≤4 questions per call).
+   - If **exactly one** domain exists: ask a confirmation — *"Set active domain to '<name>'?"* with
+     options **"Set '<name>'"** and **"Cancel"**.
+   - If the user cancels (or interactive questions cannot be asked and no valid argument was given),
+     **stop** without writing anything.
+
+4. **Validate the choice.** Check whether `docs/domainspecs/<chosen>/comandrulemap.md` exists.
+   - If it is missing, warn the user that domain rules will not load until that file is added, but
+     still allow setting the domain (it is the developer's choice).
+
+5. **Write `.aw-spec/domain.json`.** Write (creating or overwriting) `.aw-spec/domain.json` with:
+   ```json
+   {
+     "domain": "<chosen folder name>"
+   }
+   ```
+   Store the **folder name only**, not a path.
+
+6. **Confirm.** Report to the user:
+   - the active domain now set,
+   - the resolved map path `docs/domainspecs/<chosen>/comandrulemap.md` and whether it exists,
+   - that subsequent `/aw-spec-*` commands will offer this domain's rule files.
+
+## Done When
+
+- [ ] `.aw-spec/domain.json` written with the chosen domain folder name (or nothing written if the
+      user cancelled / no domains available).
+- [ ] The active domain and resolved `comandrulemap.md` path reported to the user.

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

@@ -0,0 +1,378 @@
+---
+name: "aw-spec-specify"
+description: "Create or update the feature specification from a natural language feature description."
+argument-hint: "Describe the feature you want to specify"
+compatibility: "Requires aw-spec project structure with .aw-spec/ directory"
+metadata:
+  author: "github-aw-spec"
+  source: "templates/commands/specify.md"
+user-invocable: true
+disable-model-invocation: false
+---
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## 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 / Outline. 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-specify`:
+- docs/domain/domain-driven-design.md
+- docs/security/data-classification.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-specify` 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-specify:"* — 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 specification)**:
+- Check if `.aw-spec/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_specify` 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 Outline.
+    ```
+- If no hooks are registered or `.aw-spec/extensions.yml` does not exist, skip silently
+
+## Outline
+
+The text the user typed after `/aw-spec-specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+
+Given that feature description, do this:
+
+1. **Generate a concise short name** (2-4 words) for the feature:
+   - Analyze the feature description and extract the most meaningful keywords
+   - Create a 2-4 word short name that captures the essence of the feature
+   - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
+   - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
+   - Keep it concise but descriptive enough to understand the feature at a glance
+   - Examples:
+     - "I want to add user authentication" → "user-auth"
+     - "Implement OAuth2 integration for the API" → "oauth2-api-integration"
+     - "Create a dashboard for analytics" → "analytics-dashboard"
+     - "Fix payment processing timeout bug" → "fix-payment-timeout"
+
+2. **Branch creation** (optional, via hook):
+
+   If a `before_specify` hook ran successfully in the Pre-Execution Checks above, it will have created/switched to a git branch and output JSON containing `BRANCH_NAME` and `FEATURE_NUM`. Note these values for reference, but the branch name does **not** dictate the spec directory name.
+
+   If the user explicitly provided `GIT_BRANCH_NAME`, pass it through to the hook so the branch script uses the exact value as the branch name (bypassing all prefix/suffix generation).
+
+3. **Create the spec feature directory**:
+
+Specs live under `specs/<Aggregate>/<Feature>/` unless the user explicitly provides `SPECIFY_FEATURE_DIRECTORY`.
+
+   **Resolution order for `SPECIFY_FEATURE_DIRECTORY`**:
+   1. If the user explicitly provided `SPECIFY_FEATURE_DIRECTORY` (e.g., via environment variable, argument, or configuration), use it as-is
+   2. Otherwise, auto-generate it under `specs/` keyed by aggregate and feature:
+      - Derive `<Aggregate>` and `<Feature>` from the feature description (arguments):
+        - If the description begins with an `Aggregate/Feature` token — two PascalCase segments separated by a single `/` (e.g. `Patient/RegisterPatient`) — split it into `<Aggregate>` (`Patient`) and `<Feature>` (`RegisterPatient`), and treat any remaining text as the descriptive detail.
+        - Otherwise, set `<Feature>` to the PascalCase form of the short-name from step 1, and `<Aggregate>` to the primary domain entity named in the description; if none is identifiable, use `General` and note this in the summary.
+      - Preserve the casing of `<Aggregate>` and `<Feature>` exactly as provided (PascalCase, **no** numeric/timestamp prefix).
+      - Set `SPECIFY_FEATURE_DIRECTORY` to `specs/<Aggregate>/<Feature>` (e.g. `specs/Patient/RegisterPatient`).
+      - The git branch (created by the `before_specify` hook) is independent and keeps its own numbering — do **not** mirror the branch name into the spec directory.
+
+   **Create the directory and spec file**:
+   - `mkdir -p SPECIFY_FEATURE_DIRECTORY`
+   - Resolve the active `spec-template` through the AW-Spec preset/template resolution stack (equivalent to `specify preset resolve spec-template`)
+   - Copy the resolved `spec-template` file to `SPECIFY_FEATURE_DIRECTORY/spec.md` as the starting point
+   - Set `SPEC_FILE` to `SPECIFY_FEATURE_DIRECTORY/spec.md`
+   - Persist the resolved path to `.aw-spec/feature.json`:
+     ```json
+     {
+       "feature_directory": "<resolved feature dir>"
+     }
+     ```
+     Write the actual resolved directory path value (for example, `specs/003-user-auth`), not the literal string `SPECIFY_FEATURE_DIRECTORY`.
+     This allows downstream commands (`/aw-spec-plan`, `/aw-spec-tasks`, etc.) to locate the feature directory without relying on git branch name conventions.
+
+   **IMPORTANT**:
+   - You must only create one feature per `/aw-spec-specify` invocation
+   - The spec directory name and the git branch name are independent — they may be the same but that is the user's choice
+   - The spec directory and file are always created by this command, never by the hook
+
+4. Load the resolved active `spec-template` file to understand required sections.
+
+5. **IF EXISTS**: Load `.aw-spec/memory/constitution.md` for project principles and governance constraints.
+
+6. Follow this execution flow:
+    1. Parse user description from arguments
+       If empty: ERROR "No feature description provided"
+    2. Extract key concepts from description
+       Identify: actors, actions, data, constraints
+    3. For unclear aspects:
+       - Make informed guesses based on context and industry standards
+       - Only mark with [NEEDS CLARIFICATION: specific question] if:
+         - The choice significantly impacts feature scope or user experience
+         - Multiple reasonable interpretations exist with different implications
+         - No reasonable default exists
+       - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
+       - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
+    4. Fill User Scenarios & Testing section
+       If no clear user flow: ERROR "Cannot determine user scenarios"
+    5. Generate Functional Requirements
+       Each requirement must be testable
+       Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
+    6. Define Success Criteria
+       Create measurable, technology-agnostic outcomes
+       Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
+       Each criterion must be verifiable without implementation details
+    7. Identify Key Entities (if data involved)
+    8. Return: SUCCESS (spec ready for planning)
+
+6. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+
+7. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
+
+   a. **Create Spec Quality Checklist**: Generate a checklist file at `SPECIFY_FEATURE_DIRECTORY/checklists/requirements.md` using the checklist template structure with these validation items:
+
+      ```markdown
+      # Specification Quality Checklist: [FEATURE NAME]
+      
+      **Purpose**: Validate specification completeness and quality before proceeding to planning
+      **Created**: [DATE]
+      **Feature**: [Link to spec.md]
+      
+      ## Content Quality
+      
+      - [ ] No implementation details (languages, frameworks, APIs)
+      - [ ] Focused on user value and business needs
+      - [ ] Written for non-technical stakeholders
+      - [ ] All mandatory sections completed
+      
+      ## Requirement Completeness
+      
+      - [ ] No [NEEDS CLARIFICATION] markers remain
+      - [ ] Requirements are testable and unambiguous
+      - [ ] Success criteria are measurable
+      - [ ] Success criteria are technology-agnostic (no implementation details)
+      - [ ] All acceptance scenarios are defined
+      - [ ] Edge cases are identified
+      - [ ] Scope is clearly bounded
+      - [ ] Dependencies and assumptions identified
+      
+      ## Feature Readiness
+      
+      - [ ] All functional requirements have clear acceptance criteria
+      - [ ] User scenarios cover primary flows
+      - [ ] Feature meets measurable outcomes defined in Success Criteria
+      - [ ] No implementation details leak into specification
+      
+      ## Notes
+      
+      - Items marked incomplete require spec updates before `/aw-spec-clarify` or `/aw-spec-plan`
+      ```
+
+   b. **Run Validation Check**: Review the spec against each checklist item:
+      - For each item, determine if it passes or fails
+      - Document specific issues found (quote relevant spec sections)
+
+   c. **Handle Validation Results**:
+
+      - **If all items pass**: Mark checklist complete and proceed to the Mandatory Post-Execution Hooks section
+
+      - **If items fail (excluding [NEEDS CLARIFICATION])**:
+        1. List the failing items and specific issues
+        2. Update the spec to address each issue
+        3. Re-run validation until all items pass (max 3 iterations)
+        4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
+
+      - **If [NEEDS CLARIFICATION] markers remain**:
+        1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
+        2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
+        3. For each clarification needed (max 3), present options to user in this format:
+
+           ```markdown
+           ## Question [N]: [Topic]
+           
+           **Context**: [Quote relevant spec section]
+           
+           **What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
+           
+           **Suggested Answers**:
+           
+           | Option | Answer | Implications |
+           |--------|--------|--------------|
+           | A      | [First suggested answer] | [What this means for the feature] |
+           | B      | [Second suggested answer] | [What this means for the feature] |
+           | C      | [Third suggested answer] | [What this means for the feature] |
+           | Custom | Provide your own answer | [Explain how to provide custom input] |
+           
+           **Your choice**: _[Wait for user response]_
+           ```
+
+        4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
+           - Use consistent spacing with pipes aligned
+           - Each cell should have spaces around content: `| Content |` not `|Content|`
+           - Header separator must have at least 3 dashes: `|--------|`
+           - Test that the table renders correctly in markdown preview
+        5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
+        6. Present all questions together before waiting for responses
+        7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
+        8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
+        9. Re-run validation after all clarifications are resolved
+
+   d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
+
+## Mandatory Post-Execution Hooks
+
+**You MUST complete this section before reporting completion to the user.**
+
+Check if `.aw-spec/extensions.yml` exists in the project root.
+- If it does not exist, or no hooks are registered under `hooks.after_specify`, skip to the Completion Report.
+- If it exists, read it and look for entries under the `hooks.after_specify` key.
+- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue to the Completion Report.
+- 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:
+  - **Mandatory hook** (`optional: false`) — **You MUST emit `EXECUTE_COMMAND:` for each mandatory hook**:
+    ```
+    ## Extension Hooks
+
+    **Automatic Hook**: {extension}
+    Executing: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+  - **Optional hook** (`optional: true`):
+    ```
+    ## Extension Hooks
+
+    **Optional Hook**: {extension}
+    Command: `/{command}`
+    Description: {description}
+
+    Prompt: {prompt}
+    To execute: `/{command}`
+    ```
+
+## Completion Report
+
+Report completion to the user with:
+- `SPECIFY_FEATURE_DIRECTORY` — the feature directory path
+- `SPEC_FILE` — the spec file path
+- Checklist results summary
+- Readiness for the next phase (`/aw-spec-clarify` or `/aw-spec-plan`)
+
+**NOTE:** Branch creation is handled by the `before_specify` hook (git extension). Spec directory and file creation are always handled by this core command.
+
+## Quick Guidelines
+
+- Focus on **WHAT** users need and **WHY**.
+- Avoid HOW to implement (no tech stack, APIs, code structure).
+- Written for business stakeholders, not developers.
+- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
+
+### Section Requirements
+
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+
+When creating this spec from a user prompt:
+
+1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
+2. **Document assumptions**: Record reasonable defaults in the Assumptions section
+3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
+   - Significantly impact feature scope or user experience
+   - Have multiple reasonable interpretations with different implications
+   - Lack any reasonable default
+4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
+5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+6. **Common areas needing clarification** (only if no reasonable default exists):
+   - Feature scope and boundaries (include/exclude specific use cases)
+   - User types and permissions (if multiple conflicting interpretations possible)
+   - Security/compliance requirements (when legally/financially significant)
+
+**Examples of reasonable defaults** (don't ask about these):
+
+- Data retention: Industry-standard practices for the domain
+- Performance targets: Standard web/mobile app expectations unless specified
+- Error handling: User-friendly messages with appropriate fallbacks
+- Authentication method: Standard session-based or OAuth2 for web apps
+- Integration patterns: Use project-appropriate patterns (REST/GraphQL for web services, function calls for libraries, CLI args for tools, etc.)
+
+### Success Criteria Guidelines
+
+Success criteria must be:
+
+1. **Measurable**: Include specific metrics (time, percentage, count, rate)
+2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
+3. **User-focused**: Describe outcomes from user/business perspective, not system internals
+4. **Verifiable**: Can be tested/validated without knowing implementation details
+
+**Good examples**:
+
+- "Users can complete checkout in under 3 minutes"
+- "System supports 10,000 concurrent users"
+- "95% of searches return results in under 1 second"
+- "Task completion rate improves by 40%"
+
+**Bad examples** (implementation-focused):
+
+- "API response time is under 200ms" (too technical, use "Users see results instantly")
+- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
+- "React components render efficiently" (framework-specific)
+- "Redis cache hit rate above 80%" (technology-specific)
+
+## Done When
+
+- [ ] Specification written to `SPEC_FILE` and validated against quality checklist
+- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above
+- [ ] Completion reported to user with feature directory, spec file path, and checklist results