aw-spec-cli 0.1.0 → 0.1.1

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

@@ -0,0 +1,255 @@
+---
+name: "aw-spec-tasks"
+description: "Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts."
+argument-hint: "Optional task generation constraints"
+compatibility: "Requires aw-spec project structure with .aw-spec/ directory"
+metadata:
+  author: "github-aw-spec"
+  source: "templates/commands/tasks.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-tasks`:
+- docs/architecture/folder-structure.md
+- docs/architecture/vertical-slices.md
+- docs/architecture/cqrs.md
+- docs/architecture/persistence.md
+- docs/architecture/testing.md
+- docs/architecture/eventing.md
+- docs/domain/domain-driven-design.md
+- docs/security/authorization.md
+- 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-tasks` 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-tasks:"* — 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 tasks generation)**:
+- Check if `.aw-spec/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_tasks` 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
+
+1. **Setup**: Run `.aw-spec/scripts/bash/setup-tasks.sh --json` from repo root and parse FEATURE_DIR, TASKS_TEMPLATE, and AVAILABLE_DOCS list. `FEATURE_DIR` and `TASKS_TEMPLATE` must be absolute paths when provided. `AVAILABLE_DOCS` is a list of document names/relative paths available under `FEATURE_DIR` (for example `research.md` or `contracts/`). 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 design documents**: Read from FEATURE_DIR:
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Optional**: data-model.md (entities), contracts/ (interface contracts), research.md (decisions), quickstart.md (test scenarios)
+   - **IF EXISTS**: Load `.aw-spec/memory/constitution.md` for project principles and governance constraints
+   - Note: Not all projects have all documents. Generate tasks based on what's available.
+
+3. **Execute task generation workflow**:
+   - Load plan.md and extract tech stack, libraries, project structure
+   - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
+   - If data-model.md exists: Extract entities and map to user stories
+   - If contracts/ exists: Map interface contracts to user stories
+   - If research.md exists: Extract decisions for setup tasks
+   - Generate tasks organized by user story (see Task Generation Rules below)
+   - Generate dependency graph showing user story completion order
+   - Create parallel execution examples per user story
+   - Validate task completeness (each user story has all needed tasks, independently testable)
+
+4. **Generate tasks.md**: Read the tasks template from TASKS_TEMPLATE (from the JSON output above) and use it as structure. If TASKS_TEMPLATE is empty, fall back to `.aw-spec/templates/tasks-template.md`. Fill with:
+   - Correct feature name from plan.md
+   - Phase 1: Setup tasks (project initialization)
+   - Phase 2: Foundational tasks (blocking prerequisites for all user stories)
+   - Phase 3+: One phase per user story (in priority order from spec.md)
+   - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
+   - Final Phase: Polish & cross-cutting concerns
+   - All tasks must follow the strict checklist format (see Task Generation Rules below)
+   - Clear file paths for each task
+   - Dependencies section showing story completion order
+   - Parallel execution examples per story
+   - Implementation strategy section (MVP first, incremental delivery)
+
+## 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_tasks`, skip to the Completion Report.
+- If it exists, read it and look for entries under the `hooks.after_tasks` 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
+
+Output path to generated tasks.md and summary:
+- Total task count
+- Task count per user story
+- Parallel opportunities identified
+- Independent test criteria for each story
+- Suggested MVP scope (typically just User Story 1)
+- Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
+
+## Task Generation Rules
+
+**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
+
+**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
+
+### Checklist Format (REQUIRED)
+
+Every task MUST strictly follow this format:
+
+```text
+- [ ] [TaskID] [P?] [Story?] Description with file path
+```
+
+**Format Components**:
+
+1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
+2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
+3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
+4. **[Story] label**: REQUIRED for user story phase tasks only
+   - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
+   - Setup phase: NO story label
+   - Foundational phase: NO story label  
+   - User Story phases: MUST have story label
+   - Polish phase: NO story label
+5. **Description**: Clear action with exact file path
+
+**Examples**:
+
+- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan`
+- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
+- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
+- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py`
+- ❌ WRONG: `- [ ] Create User model` (missing ID and Story label)
+- ❌ WRONG: `T001 [US1] Create model` (missing checkbox)
+- ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID)
+- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path)
+
+### Task Organization
+
+1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
+   - Each user story (P1, P2, P3...) gets its own phase
+   - Map all related components to their story:
+     - Models needed for that story
+     - Services needed for that story
+     - Interfaces/UI needed for that story
+     - If tests requested: Tests specific to that story
+   - Mark story dependencies (most stories should be independent)
+
+2. **From Contracts**:
+   - Map each interface contract → to the user story it serves
+   - If tests requested: Each interface contract → contract test task [P] before implementation in that story's phase
+
+3. **From Data Model**:
+   - Map each entity to the user story(ies) that need it
+   - If entity serves multiple stories: Put in earliest story or Setup phase
+   - Relationships → service layer tasks in appropriate story phase
+
+4. **From Setup/Infrastructure**:
+   - Shared infrastructure → Setup phase (Phase 1)
+   - Foundational/blocking tasks → Foundational phase (Phase 2)
+   - Story-specific setup → within that story's phase
+
+### Phase Structure
+
+- **Phase 1**: Setup (project initialization)
+- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories)
+- **Phase 3+**: User Stories in priority order (P1, P2, P3...)
+  - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
+  - Each phase should be a complete, independently testable increment
+- **Final Phase**: Polish & Cross-Cutting Concerns
+
+## Done When
+
+- [ ] tasks.md generated with all phases, task IDs, and file paths
+- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above
+- [ ] Completion reported to user with task count, story breakdown, and MVP scope

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

@@ -0,0 +1,107 @@
+---
+name: "aw-spec-taskstoissues"
+description: "Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts."
+argument-hint: "Optional filter or label for GitHub issues"
+compatibility: "Requires aw-spec project structure with .aw-spec/ directory"
+metadata:
+  author: "github-aw-spec"
+  source: "templates/commands/taskstoissues.md"
+user-invocable: true
+disable-model-invocation: false
+---
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Pre-Execution Checks
+
+**Check for extension hooks (before tasks-to-issues conversion)**:
+- Check if `.aw-spec/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.before_taskstoissues` 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
+
+1. Run `.aw-spec/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. 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").
+1. **IF EXISTS**: Load `.aw-spec/memory/constitution.md` for project principles and governance constraints.
+1. From the executed script, extract the path to **tasks**.
+1. Get the Git remote by running:
+
+```bash
+git config --get remote.origin.url
+```
+
+> [!CAUTION]
+> ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL
+
+1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.
+
+> [!CAUTION]
+> UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL
+
+## Post-Execution Checks
+
+**Check for extension hooks (after tasks-to-issues conversion)**:
+Check if `.aw-spec/extensions.yml` exists in the project root.
+- If it exists, read it and look for entries under the `hooks.after_taskstoissues` 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

package/assets/docs/README.md

@@ -0,0 +1,106 @@
+# Engineering Standards — Index & Context-Loading Map
+
+These docs are the detailed engineering standards expanded from the slim constitution inputs
+(`docs/technology-constitution.md` composed with a domain addenda such as
+`docs/healthcare-constitution.md` or `docs/pharma-constitution.md`, ratified into
+`.aw-spec/memory/constitution.md`). The constitution remains supreme; these files expand each
+principle into a focused, includable reference.
+
+The **technology** standards are loaded **automatically** by each AW-Spec command (see each
+`.claude/skills/aw-spec-*/SKILL.md`). The **domain** standards live under
+`domainspecs/<domain>/` and are added per project; a `healthcare` set is provided.
+
+## Naming convention: technology vs. domain
+
+- **`<area>/<name>.md`** — **pure technology**, domain-agnostic. Reusable across all projects.
+  Auto-loaded by the commands.
+- **`domainspecs/healthcare/<name>.md` and `<name>.domain.md`** — **healthcare domain-specific**
+  rules, all collected under one folder. A `.domain.md` extends the matching technology file
+  (FHIR, HL7, DICOM, PHI/HIPAA, ATNA, ICD/SNOMED/LOINC, consent, clinical aggregates, etc.);
+  the plain `.md` files there (fhir, hl7, dicom, terminology, consent, hipaa, clinical-terms,
+  integration-terms, domain-requirements) are inherently healthcare.
+
+> **To reuse on a non-healthcare project:** keep every technology `*.md` as-is and create a
+> sibling `domainspecs/<your-domain>/` folder with your own domain rule files. Select the active
+> domain with `/aw-spec-select-domain` (stored in `.aw-spec/domain.json`); commands resolve
+> `domainspecs/<active-domain>/comandrulemap.md` from it.
+
+Note: `domain/domain-driven-design.md` is generic DDD tactical guidance and is treated as
+pure technology (auto-loaded); its healthcare companion lives at
+`domainspecs/healthcare/domain-driven-design.domain.md`.
+
+## Files — technology (auto-loaded)
+
+### `architecture/`
+- [clean-architecture.md](architecture/clean-architecture.md) — dependency rule, layers, infra boundaries
+- [modular-monolith.md](architecture/modular-monolith.md) — module boundaries, cross-module rules, extraction
+- [folder-structure.md](architecture/folder-structure.md) — mandatory `src/tests/helm/docs` tree (templated with `<SampleProjectName>`)
+- [cqrs.md](architecture/cqrs.md) — mediator, Result pattern, transactions
+- [vertical-slices.md](architecture/vertical-slices.md) — feature & folder structure
+- [persistence.md](architecture/persistence.md) — EF Core, specs, concurrency, tenancy
+- [testing.md](architecture/testing.md) — unit/integration/Testcontainers/coverage
+- [eventing.md](architecture/eventing.md) — CloudEvents, versioning, broker
+
+### `security/`
+- [zero-trust.md](security/zero-trust.md) — TLS, identity, secrets
+- [authorization.md](security/authorization.md) — role+scope model, cache policy
+- [authorization-matrix.md](security/authorization-matrix.md) — role/scope matrix
+- [auditing.md](security/auditing.md) — observability, structured logging, immutable audit
+- [data-classification.md](security/data-classification.md) — classification framework, encryption
+
+### `governance/`
+- [coding-standards.md](governance/coding-standards.md) — naming, forbidden patterns, CI gates
+- [dependency-policy.md](governance/dependency-policy.md) — package governance, banned packages
+- [api-versioning.md](governance/api-versioning.md) — REST versioning, ETag, OpenAPI/AsyncAPI
+
+### `domain/`
+- [domain-driven-design.md](domain/domain-driven-design.md) — generic DDD tactical patterns *(reusable tech, lives here by topic)*
+
+### `glossary/`
+- [ai-rules.md](glossary/ai-rules.md) — generic AI agent rules
+
+## Files — healthcare domain (`domainspecs/healthcare/`, add per project)
+
+**Architecture overlays**
+- [folder-structure.domain.md](domainspecs/healthcare/folder-structure.domain.md) — healthcare Interop, conformance tests, PHI fixtures
+- [cqrs.domain.md](domainspecs/healthcare/cqrs.domain.md) — PHI-audit behavior
+- [vertical-slices.domain.md](domainspecs/healthcare/vertical-slices.domain.md) — FHIR-HL7-DICOM Interop slice
+- [persistence.domain.md](domainspecs/healthcare/persistence.domain.md) — PHI retention & encryption-at-rest
+- [testing.domain.md](domainspecs/healthcare/testing.domain.md) — FHIR validation & synthetic PHI
+- [eventing.domain.md](domainspecs/healthcare/eventing.domain.md) — healthcare feeds & protocol tracing
+
+**Domain (clinical)**
+- [domain-driven-design.domain.md](domainspecs/healthcare/domain-driven-design.domain.md) — healthcare canonical aggregates & invariants
+- [domain-requirements.md](domainspecs/healthcare/domain-requirements.md) — project bounded contexts / aggregates *(project-specific)*
+- [fhir.md](domainspecs/healthcare/fhir.md) — projectors, CapabilityStatement, profiles, Bundle/search, SMART, Bulk Data
+- [terminology.md](domainspecs/healthcare/terminology.md) — ICD/LOINC/SNOMED/RxNorm, coded value objects, terminology service
+- [hl7.md](domainspecs/healthcare/hl7.md) — HL7 v2 ingestion/egress, adapters, MLLP
+- [dicom.md](domainspecs/healthcare/dicom.md) — DICOMweb, PACS/VNA boundary, metadata-only persistence
+- [consent.md](domainspecs/healthcare/consent.md) — consent enforcement, break-the-glass, restriction-of-processing, FHIR Consent
+- [hipaa.md](domainspecs/healthcare/hipaa.md) — PHI handling, audit, retention, minimum-necessary, breach handling
+
+**Security overlays**
+- [zero-trust.domain.md](domainspecs/healthcare/zero-trust.domain.md) — PHI transport, SMART tokens, ATNA node auth
+- [authorization.domain.md](domainspecs/healthcare/authorization.domain.md) — clinical roles, SMART scopes, consent, break-the-glass
+- [auditing.domain.md](domainspecs/healthcare/auditing.domain.md) — ATNA, FHIR AuditEvent, PHI audit
+- [data-classification.domain.md](domainspecs/healthcare/data-classification.domain.md) — PHI/PII/PCI taxonomy, de-identification
+
+**Governance overlays**
+- [coding-standards.domain.md](domainspecs/healthcare/coding-standards.domain.md) — FHIR & PHI patterns and gates
+- [dependency-policy.domain.md](domainspecs/healthcare/dependency-policy.domain.md) — HIPAA suitability, healthcare libs
+- [api-versioning.domain.md](domainspecs/healthcare/api-versioning.domain.md) — FHIR versioning, CapabilityStatement
+
+**Glossary**
+- [clinical-terms.md](domainspecs/healthcare/clinical-terms.md) — MRN, Encounter, Observation, Coverage, etc.
+- [integration-terms.md](domainspecs/healthcare/integration-terms.md) — HL7, FHIR, DICOM, PIX/PDQ, ATNA, MHD, XDS
+- [ai-rules.domain.md](domainspecs/healthcare/ai-rules.domain.md) — PHI masking, codes, FHIR, security-edit limits
+
+## Context-loading map (which docs to include per AW-Spec command)
+
+Technology standards auto-load per command. The per-command mappings are single-sourced:
+
+- **Technical defaults** (auto-loaded) — the `Auto-Loaded Engineering Standards` section
+  inside each `.claude/skills/aw-spec-<command>/SKILL.md`.
+- **Domain rule files** (selectable) — the active domain's `comandrulemap.md` (e.g.
+  [domainspecs/healthcare/comandrulemap.md](domainspecs/healthcare/comandrulemap.md)),
+  resolved at runtime from `.aw-spec/domain.json`.

package/assets/docs/VerticalSlice/PACKAGING.md

@@ -0,0 +1,185 @@
+# VerticalSlice — Foundation Packaging Rules
+
+> **Why this exists.** The old `/aw-spec-foundation` skill *reconstructed* every project
+> file from prose rule docs. Any omission or namespace drift produced a broken,
+> non-compiling skeleton. This packaging model replaces reconstruction with a
+> **byte-for-byte bundle of a real, verified solution**.
+>
+> You build the foundation **once** (a solution that actually compiles and runs),
+> pack it into a single text file, and the scaffolder just **unpacks + renames** it.
+> No regeneration, no drift.
+
+---
+
+## The single artifact
+
+```
+docs/VerticalSlice/
+├── VerticalSlice.pack.txt      ← THE BUNDLE: every source file, in one text file
+├── PACKAGING.md                ← this file (how to build the bundle)
+├── pack-foundation.ps1         ← produces VerticalSlice.pack.txt from a solution
+└── unpack-foundation.ps1       ← extracts + renames into a target app (used by the skill)
+```
+
+The bundle is the single source of truth for scaffolding. The engineering standards
+the foundation solution must satisfy (vertical slices, DDD, CQRS, persistence, etc.)
+live in the project constitution and the domain-specs rule files, not in this folder.
+
+---
+
+## The sentinel convention
+
+You author the foundation solution under one fixed **sentinel app name**:
+
+```
+AppWeaver.Foundation
+```
+
+This is the placeholder that the scaffolder rewrites into the caller's app name.
+It must be a **distinctive two-segment token** that is **not a prefix of any
+`AppWeaver.*` NuGet package** (it isn't — there is no `AppWeaver.Foundation` package),
+so a full-token replacement can never clobber a framework reference.
+
+The scaffolder rewrites the sentinel in **four case forms** (ordinal, case-sensitive),
+applied to **file contents and to file/folder paths**:
+
+| Form        | Sentinel               | Example target (`AppWeaver.Health`) | Where it appears                                  |
+|-------------|------------------------|-------------------------------------|---------------------------------------------------|
+| dotted      | `AppWeaver.Foundation` | `AppWeaver.Health`                  | namespaces, `.csproj`/`.sln` names, project refs  |
+| underscored | `AppWeaver_Foundation` | `AppWeaver_Health`                  | Aspire project class names (`Projects.X_Service`) |
+| lower-hyphen| `appweaver-foundation` | `appweaver-health`                  | `UserSecretsId`, db/container names               |
+| lower-dot   | `appweaver.foundation` | `appweaver.health`                  | any lowercased identifiers                         |
+
+**Never** rename the bare `AppWeaver` company segment on its own — only the full
+sentinel token in the forms above. The framework packages (`AppWeaver.Mediator`,
+`AppWeaver.Repository`, …) stay exactly as written.
+
+### What does NOT get renamed
+
+- `AppWeaver.*` framework package references (`Directory.Packages.props`, every `.csproj`).
+- The sample domain folder **`Projects`** (aggregate `Project`, `CreateProject`, etc.).
+  This is intentional sample content the caller renames to their own bounded context later.
+- `<Company>` / `<Authors>` metadata in `Directory.Build.props` (display-only; edit manually if desired).
+
+---
+
+## How to author the foundation solution (do this once)
+
+1. **Pick a scratch folder** outside `docs/`, e.g.
+   `E:\Work\Bytestrone\AppWeaver\Testing\AppWeaver.Spec\.foundation-build\`.
+2. **Create the solution under the sentinel name** `AppWeaver.Foundation`, following the
+   engineering standards in the project constitution and domain-specs rule files:
+   ```
+   AppWeaver.Foundation.sln
+   global.json
+   Directory.Build.props
+   Directory.Packages.props
+   src/
+     AppWeaver.Foundation.AppHost/
+     AppWeaver.Foundation.ServiceDefaults/
+     AppWeaver.Foundation.Service/        (includes the sample 'Projects' domain)
+     AppWeaver.Foundation.Web/
+   ```
+3. **Make it actually work.** This is the whole point — the bundle is only as good as
+   the solution you pack. Verify before packing:
+   ```powershell
+   dotnet restore .foundation-build/AppWeaver.Foundation.sln
+   dotnet build   .foundation-build/AppWeaver.Foundation.sln -c Debug
+   # optional end-to-end:
+   dotnet run --project .foundation-build/src/AppWeaver.Foundation.AppHost
+   ```
+   Fix every error and warning-as-error here, in the real project, where the compiler
+   tells you exactly what's wrong. The packed bundle inherits this correctness.
+4. **Use the sentinel everywhere** the app name belongs: namespaces, project/folder
+   names, `UserSecretsId`, the Aspire db resource name, container names. Use the correct
+   case form for each (see table above).
+
+---
+
+## How to build the bundle
+
+From `docs/VerticalSlice/`:
+
+```powershell
+# This foundation intentionally ships the org-internal Azure Artifacts PAT in NuGet.config,
+# so the secret guard must be overridden with -AllowSecrets (org-internal use only — rotate periodically).
+./pack-foundation.ps1 -SourceDir ../../.foundation-build -OutFile ./VerticalSlice.pack.txt -AllowSecrets
+```
+
+The packer:
+
+- walks the solution, **excluding** build/IDE artifacts and secret-bearing files:
+  - dirs: `bin obj .vs .git .idea .vscode TestResults node_modules packages App_Data artifacts .next logs`
+  - files: `*.user *.suo *.DotSettings.user *.db *.db-shm *.db-wal *.sqlite *.log`
+    and **secrets**: `.env.* *.pfx *.pem *.key *.snk id_rsa id_rsa.pub secrets.json`;
+    > The root **`.env` is bundled on purpose** (required sample config); only per-environment
+    > overrides (`.env.local`, `.env.production`, …) are excluded. Keep the bundle org-internal
+    > and rotate any real values — the content scan still blocks PATs/keys regardless of filename.
+- **fails closed on detected secrets** — it scans file *contents* for credential markers
+  (`ClearTextPassword`, private-key blocks, AWS keys, Azure DevOps PAT patterns) and
+  **refuses to pack** if any are found, unless you pass `-AllowSecrets`. This is what stops
+  a `NuGet.config` PAT from being baked into the committed bundle. **Fix the source** (rotate
+  the secret, switch the feed to env/CLI auth) rather than overriding the guard;
+- stores text files **verbatim** and binary files (e.g. a `.png`) **base64-encoded**;
+- writes a header (foundation, sentinel, file count, format version, replacement contract);
+- **warns** if the sentinel token appears in zero files (a sign you used the wrong name).
+
+> **Credentials in a scaffold.** The bundled `NuGet.config` should contain only feed
+> *definitions* and `packageSourceMapping` — never `<packageSourceCredentials>`. Developers
+> authenticate to private feeds with `dotnet nuget` / the Azure Artifacts credential provider
+> / environment variables, not a checked-in PAT.
+
+Re-run it whenever the foundation changes; commit the regenerated `VerticalSlice.pack.txt`.
+
+---
+
+## Pack file format (`aw-spec-pack/v1`)
+
+```
+# AW-SPEC FOUNDATION PACK
+# foundation: VerticalSlice
+# sentinel: AppWeaver.Foundation
+# generated: 2026-06-14T10:00:00.0000000Z
+# files: 47
+# format: aw-spec-pack/v1
+# --- replacement contract ... ---
+# ============================================================
+
+<<<FILE path="Directory.Build.props">>>
+...verbatim file content...
+<<<ENDFILE>>>
+<<<FILE path="src/AppWeaver.Foundation.AppHost/Program.cs">>>
+...verbatim file content...
+<<<ENDFILE>>>
+<<<FILE path="src/AppWeaver.Foundation.Web/wwwroot/favicon.ico" encoding="base64">>>
+AAABAAE...
+<<<ENDFILE>>>
+```
+
+- Paths are repo-root-relative with `/` separators.
+- The marker lines `<<<FILE …>>>` and `<<<ENDFILE>>>` are **reserved** — they must never
+  occur as a literal line inside a source file (they can't in C#/XML/JSON/Razor).
+- `encoding="base64"` marks a binary file; everything else is UTF-8 text.
+
+---
+
+## How scaffolding consumes the bundle
+
+`/aw-spec-foundation VerticalSlice <AppName> [OutputDir]` runs `unpack-foundation.ps1`,
+which reads the sentinel from the pack header, derives the four target case forms, and
+writes the renamed files to the output directory (**repo root by default**). See
+`.claude/skills/aw-spec-foundation/SKILL.md`.
+
+```powershell
+./unpack-foundation.ps1 -PackFile ./VerticalSlice.pack.txt -TargetAppName AppWeaver.Health -OutDir ../../ 
+```
+
+---
+
+## Maintenance checklist
+
+- [ ] Foundation solution builds clean (`dotnet build`, warnings-as-errors satisfied).
+- [ ] Sentinel `AppWeaver.Foundation` used consistently in all four case forms.
+- [ ] No `bin/obj/.vs` or local `.db` files committed into the pack.
+- [ ] `pack-foundation.ps1` reported a non-zero sentinel hit count.
+- [ ] `VerticalSlice.pack.txt` regenerated and committed after any change.