aw-spec-cli 0.1.1 → 0.1.3

package/assets/.kilocode/workflows/aw-spec-fast-implement.md

@@ -0,0 +1,263 @@
+---
+name: "aw-spec-fast-implement"
+description: "Token-efficient fast path that collapses /aw-spec-plan + /aw-spec-tasks + /aw-spec-analyze + /aw-spec-implement into a single pass: load engineering and domain standards once, derive a compact design, self-check it, and implement the spec directly following both technological and domain patterns. Run after /aw-spec-specify (and optionally /aw-spec-clarify or a verify step)."
+argument-hint: "Optional implementation guidance, scope filter (e.g. backend-only), or design hints"
+compatibility: "Requires aw-spec project structure with .aw-spec/ directory and an existing spec.md (produced by /aw-spec-specify)"
+---
+
+
+## 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.
+
+## What this command does
+
+Collapses `/aw-spec-plan` → `/aw-spec-tasks` → `/aw-spec-analyze` → `/aw-spec-implement` into one pass: load the deduplicated union of standards + domain rules **once**, fold the design into a single compact `plan.md` + `tasks.md` (no separate research/data-model/contracts/quickstart), inline the analyze consistency check as an in-memory gate, then implement. Same end result as the full sequence; non-negotiables (constitution, standards, domain rules, spec checklist, constitution/coverage gates, architecture patterns, extension hooks) are all honored — only the intermediate documents and repeated context loads are dropped.
+
+## Project Structure Gate (run before loading standards)
+
+**Before loading standards or writing code, confirm a scaffolded app exists** — the output of `/aw-spec-foundation`, not just `.aw-spec/`/`docs/`/`specs/` framework files. Check the repo root (Glob/Bash) for a real build entrypoint, ignoring matches only inside `.aw-spec/`/`docs/`/`specs/`: `*.sln` or `*.csproj` under `src/` (.NET/AppWeaver), else `package.json`/`pom.xml`/`build.gradle`/`go.mod`/`Cargo.toml`/`pyproject.toml` etc.
+
+- **None found → STOP, no side effects** (don't load standards, run hooks, or write anything): tell the developer *"No scaffolded project found — run `/aw-spec-foundation ModularMonolith <AppName>` (or `VerticalSlice <AppName>`) first, then re-run."*
+- **Found →** use its solution/host-project path as the implementation target and continue.
+
+## 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 — ONCE.** 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`.
+- This list is the **deduplicated union** of the standards that `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-analyze`, and `/aw-spec-implement` each load. Load every file **exactly once**; do not re-read a file you have already loaded in this pass.
+- 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-fast-implement` (union of the collapsed commands):
+- docs/architecture/clean-architecture.md
+- docs/architecture/modular-monolith.md
+- docs/architecture/folder-structure.md
+- docs/architecture/cqrs.md
+- docs/architecture/vertical-slices.md
+- docs/architecture/persistence.md
+- docs/architecture/testing.md
+- docs/architecture/eventing.md
+- docs/domain/domain-driven-design.md
+- docs/security/zero-trust.md
+- docs/security/authorization.md
+- docs/security/auditing.md
+- docs/security/data-classification.md
+- docs/governance/coding-standards.md
+- docs/governance/dependency-policy.md
+- docs/governance/api-versioning.md
+- docs/glossary/ai-rules.md
+
+## Domain Rule-File Selection (interactive, once)
+
+After the technical standards above are loaded, and **before** the Pre-Execution Checks, resolve the active domain and ask the user — **once for the whole pass** — which **domain** rule files to load:
+
+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-fast-implement`** heading in `docs/domainspecs/<domain>/comandrulemap.md` — this command has its own canonical entry, exactly like every other `/aw-spec-*` command.
+   - **Fallback (older domain maps).** If `comandrulemap.md` exists but has **no** `## /aw-spec-fast-implement` heading, derive the candidate set as the **deduplicated union** of the bullet lists under the `## /aw-spec-plan`, `## /aw-spec-tasks`, `## /aw-spec-analyze`, and `## /aw-spec-implement` headings (in practice `/aw-spec-plan` is the superset). A missing fast-implement heading is **not** an error.
+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 yields no candidate files (no `## /aw-spec-fast-implement` heading **and** none of the four fallback headings have entries), this is **not** a gate trigger — load no domain files 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-fast-implement:"* — 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 **exactly once** (the full deduplicated 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 collapsed pre-hooks (before fast implementation)**:
+- Check if `.aw-spec/extensions.yml` exists in the project root.
+- If it exists, read it and collect hook entries from the `hooks.before_plan`, `hooks.before_tasks`, and `hooks.before_implement` keys (the pre-hook points of the commands this fast path collapses).
+- 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.
+- **De-duplicate by command**: if the same hook `command` appears under more than one of those keys, execute it **only once** for this pass.
+- 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. Resolve paths and seed artifacts (reuses the standard scripts)
+
+1. Run `.aw-spec/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for `FEATURE_SPEC`, `IMPL_PLAN`, `SPECS_DIR`, `BRANCH`. All paths must be absolute. This step also copies the resolved `plan-template` to `IMPL_PLAN` if no plan exists yet (so the next script can resolve the tasks template). 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. **Spec gate**: Read `FEATURE_SPEC` (`spec.md`). If it does not exist or is empty, **STOP** and tell the user to run `/aw-spec-specify` first — this fast path requires a written spec. Do not invent a spec.
+3. Run `.aw-spec/scripts/bash/setup-tasks.sh --json` from repo root and parse `FEATURE_DIR`, `TASKS_TEMPLATE`, and `AVAILABLE_DOCS`. `TASKS_TEMPLATE` is the resolved tasks template to use when writing `tasks.md`. If `TASKS_TEMPLATE` is empty, fall back to `.aw-spec/templates/tasks-template.md`.
+
+### 2. Load the minimal authoritative context
+
+- **REQUIRED**: `spec.md` — user stories with priorities (P1, P2, P3…), Functional Requirements (FR-###), Success Criteria (SC-###), Key Entities, edge cases.
+- **IF EXISTS**: `.aw-spec/memory/constitution.md` — governance constraints (authoritative; MUST principles are non-negotiable).
+- **IF EXISTS**: `FEATURE_DIR/checklists/requirements.md` — the spec quality checklist produced by `/aw-spec-specify`.
+- **IF EXISTS**: any of `research.md`, `data-model.md`, `contracts/`, `quickstart.md` already present in `FEATURE_DIR` (from a prior partial run) — reuse them instead of regenerating.
+- The engineering standards and domain rule files were already loaded above; **do not re-read them**.
+
+### 3. Spec-readiness gate (folds in checklist + clarification status)
+
+- If `checklists/requirements.md` exists, scan it. Count total / completed / incomplete items.
+  - If any item is incomplete, display a short status line and **ask once**: "The spec quality checklist has incomplete items. Proceed with fast implementation anyway? (yes/no)". Halt on "no"/"stop"/"wait"; continue on "yes"/"proceed"/"continue". In a non-interactive run, default to proceed but record the gap in the Completion Report.
+- If the spec still contains unresolved `[NEEDS CLARIFICATION]` markers, list them and either (a) make a documented reasonable assumption (preferred for the fast path, recorded under Assumptions in `plan.md`), or (b) if a marker is high-impact on scope/security, ask the user a single targeted question before proceeding.
+
+### 4. Derive the design — write a single compact `plan.md`
+
+Fill `IMPL_PLAN` (`plan.md`) from the resolved plan template, then **append a "Design Detail" section** so this one file carries everything the separate `research.md` + `data-model.md` + `contracts/` + `quickstart.md` would have carried. Keep it compact — decisions and structure, not prose.
+
+Populate:
+- **Summary**: primary requirement + chosen technical approach.
+- **Technical Context**: language/version, primary dependencies, storage, testing, target platform, project type, performance goals, constraints, scale/scope. Resolve unknowns with documented assumptions (do **not** leave `NEEDS CLARIFICATION` for the fast path unless genuinely blocking).
+- **Constitution Check**: evaluate the gates from `.aw-spec/memory/constitution.md`. If a MUST principle is violated and unjustified, **STOP** and report — do not implement around a constitution violation.
+- **Project Structure**: the concrete source layout for this feature, following `docs/architecture/folder-structure.md`, `vertical-slices.md`, and the active domain's `folder-structure.domain.md`. Remove unused template options.
+- **Design Detail** (folded artifacts):
+  - *Data Model*: entities, fields, relationships, validation rules, and state transitions (replaces `data-model.md`).
+  - *Contracts*: the interfaces this feature exposes — endpoints / commands / queries / events with their request-response shapes, mapped to the user story they serve (replaces `contracts/`). Follow `cqrs.md`, `api-versioning.md`, and the domain interop rules (e.g. FHIR/HL7) where applicable.
+  - *Decisions & Rationale*: key technical decisions, why chosen, and notable alternatives rejected (replaces `research.md`).
+  - *Validation Quickstart*: the runnable steps that prove the feature works end-to-end (replaces `quickstart.md`).
+- Re-check the Constitution gate after the design is fleshed out.
+
+### 5. Derive the task plan — write `tasks.md`
+
+Using `TASKS_TEMPLATE` as the structure, write `tasks.md` organized **by user story** so each story is independently implementable and testable. Follow the strict checklist format from the template:
+
+```text
+- [ ] [TaskID] [P?] [Story?] Description with exact file path
+```
+
+- **Phase 1: Setup** (project initialization) — no story label.
+- **Phase 2: Foundational** (blocking prerequisites for all stories) — no story label.
+- **Phase 3+: one phase per user story** in priority order (P1, P2, P3…), each with a goal and independent-test criterion, each carrying its `[US#]` label.
+- **Final Phase: Polish & cross-cutting concerns** — no story label.
+- **Tests are OPTIONAL** — only generate test tasks if the spec explicitly requests tests or TDD. When generated, tests precede their implementation tasks (write-fail-implement) per `docs/architecture/testing.md`.
+- Mark `[P]` only for tasks on different files with no incomplete dependencies. Give every task an exact file path.
+
+### 6. Inline consistency self-check (replaces `/aw-spec-analyze`)
+
+Before writing any code, run a quick **in-memory** gate across `spec.md`, the `plan.md` you just wrote, and `tasks.md`. Do **not** write a report file. Check:
+- **Coverage**: every Functional Requirement and every user story maps to ≥1 task; every buildable Success Criterion (performance/security/availability tooling) has a task. Flag any requirement with zero coverage.
+- **Constitution alignment**: no requirement, design element, or task conflicts with a MUST principle (CRITICAL if it does).
+- **Consistency**: no terminology drift, no conflicting tech choices, no task-ordering contradictions (e.g. integration before its foundational setup).
+- **Ambiguity / underspecification**: vague attributes lacking measurable criteria; tasks referencing undefined components.
+
+Resolution:
+- **CRITICAL issues** (constitution MUST violation, zero-coverage of baseline functionality, conflicting requirements): **STOP**, summarize them, and ask the user how to proceed — adjust `plan.md`/`tasks.md` rather than implementing on a broken foundation.
+- **HIGH/MEDIUM/LOW issues**: fix them in `plan.md`/`tasks.md` in place when cheap, otherwise note them and continue.
+
+### 7. Project setup verification
+
+Create/verify ignore files based on the actual stack from `plan.md` (this is a .NET/C# AppWeaver project by default — `bin/`, `obj/`, `*.user`, `*.suo` for `.gitignore`; add Docker/other patterns only if detected). Use `git rev-parse --git-dir` to confirm a git repo before creating `.gitignore`. Append only missing critical patterns to existing ignore files; do not overwrite them.
+
+### 8. Implement directly
+
+Execute the tasks in `tasks.md`, phase by phase, applying the loaded standards and domain patterns:
+- **Setup → Foundational → User Stories (priority order) → Polish.** Complete each phase before the next; respect dependencies; `[P]` tasks may proceed together; tasks on the same file run sequentially.
+- **Follow the patterns**: vertical slices, CQRS command/query separation, DDD aggregates/value objects, the prescribed folder structure, persistence/eventing conventions, authorization/auditing/data-classification/zero-trust requirements, and the active domain's overlays (e.g. FHIR/HL7 mapping, consent, HIPAA, audit) — all already in context.
+- **TDD when requested**: write the story's tests first and see them fail before implementing.
+- **Mark every completed task `[X]` in `tasks.md`** as you finish it.
+- Report progress per phase. Halt on a failing non-parallel task with a clear, actionable error; for `[P]` tasks, continue the successful ones and report the failures.
+
+### 9. Completion validation
+
+- All required tasks completed and marked `[X]`.
+- Implementation matches `spec.md` (requirements + user stories) and the `plan.md` design.
+- The project builds; if tests were requested, they pass.
+- The validation quickstart steps in `plan.md` succeed (or are clearly documented as pending).
+
+## 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, skip to the Completion Report.
+- If it exists, read it and collect hook entries from the `hooks.after_plan`, `hooks.after_tasks`, and `hooks.after_implement` keys (the post-hook points of the commands this fast path collapses).
+- 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.
+- **De-duplicate by command**: if the same hook `command` (e.g. `aw-spec.agent-context.update`, which is registered for both `after_plan` and elsewhere) appears under more than one of those keys, execute it **only once** for this pass.
+- 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 final status with:
+- `FEATURE_DIR`, `plan.md`, and `tasks.md` paths.
+- Task summary: total tasks, tasks per user story, how many are now `[X]`.
+- Standards and domain rule files applied (domain name + count, or "technical only").
+- Any consistency-gate findings that were noted but not blocking.
+- Build/test status and whether the validation quickstart passed.
+- Any documented assumptions or deferred items.
+
+## Key rules
+
+- Use absolute paths for filesystem operations; use project-relative paths for references in `plan.md`/`tasks.md` and agent-context files.
+- Load each standards/domain/spec file **once** per pass — never re-read context you already hold. This single-load discipline is the primary token saving over the four-command sequence.
+- The constitution and the loaded standards are authoritative. **ERROR/STOP on unjustified constitution-gate failures or zero-coverage of baseline functionality** rather than implementing around them.
+- This command assumes `spec.md` exists. If it is missing, suggest `/aw-spec-specify`. If the user wants the full, audited artifact set (separate research/data-model/contracts/quickstart + analysis report), suggest the standard `/aw-spec-plan → /aw-spec-tasks → /aw-spec-analyze → /aw-spec-implement` sequence instead.
+
+## Done When
+
+- [ ] Engineering standards and domain rule files loaded **once** (deduplicated union)
+- [ ] `spec.md` present and read; spec-readiness gate cleared or its gaps documented
+- [ ] Compact `plan.md` written (with folded data-model / contracts / decisions / quickstart) and constitution gate passed
+- [ ] `tasks.md` generated by user story in strict checklist format
+- [ ] Inline consistency self-check passed (no unresolved CRITICAL issues)
+- [ ] All tasks implemented following technological and domain standards, and marked `[X]`
+- [ ] Implementation validated against spec, plan, and (if requested) tests
+- [ ] Extension hooks dispatched or skipped per the rules above
+- [ ] Completion reported with artifact paths, task summary, standards applied, and build/test status

package/assets/.kilocode/workflows/aw-spec-foundation.md

@@ -0,0 +1,358 @@
+---
+name: "aw-spec-foundation"
+description: "Scaffold a complete, compiling project by unpacking a verified foundation bundle (docs/<FoundationName>/<FoundationName>.pack.txt) and renaming its sentinel app name to your app name."
+argument-hint: "FoundationName AppName [OutputDirectory]  —  e.g. VerticalSlice AppWeaver.Health"
+compatibility: "Requires docs/<FoundationName>/<FoundationName>.pack.txt and an unpacker (unpack-foundation.ps1 preferred via pwsh; unpack-foundation.sh fallback when pwsh is absent)"
+metadata:
+  author: "github-aw-spec"
+user-invocable: true
+disable-model-invocation: false
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+Parse the arguments (positional, in order):
+
+- `FOUNDATION_NAME` — first token (e.g. `VerticalSlice`).
+- `APP_NAME` — second token; the root namespace / solution name (e.g. `AppWeaver.Health`, `MyCompany.Orders`).
+- `OUTPUT_DIR` — third token (optional); where to write the solution. **Default: the repo root (`.`).**
+
+If `FOUNDATION_NAME` or `APP_NAME` is missing, stop and tell the user:
+
+```
+Usage: /aw-spec-foundation <FoundationName> <AppName> [OutputDirectory]
+Example: /aw-spec-foundation VerticalSlice AppWeaver.Health
+```
+
+---
+
+## How this works
+
+Unpack a **byte-for-byte bundle of a verified solution**
+(`docs/<FOUNDATION_NAME>/<FOUNDATION_NAME>.pack.txt`) via its unpack script, which rewrites the
+pack's **sentinel** app name to `APP_NAME` (in dotted / underscored / lower-hyphen / lower-dot
+forms) across file contents and names. The sample domain folder `Projects` and `AppWeaver.*`
+framework packages are **left unchanged**.
+
+> ⚠️ **Never open a `.pack.txt` with Read/`cat`/`head`/`tail`** — it is ~700 KB (≈180K tokens).
+> The script parses and writes everything to disk; the only thing you read from the pack is its
+> `#` header, via a bounded `grep` (Step 1).
+
+---
+
+## Step 1 — Locate the bundle
+
+Resolve these paths relative to the repo root:
+
+- `PACK_FILE`   = `docs/<FOUNDATION_NAME>/<FOUNDATION_NAME>.pack.txt`
+- `UNPACK_PS1`  = `docs/<FOUNDATION_NAME>/unpack-foundation.ps1`
+
+Check both exist.
+
+- If the folder `docs/<FOUNDATION_NAME>/` does not exist:
+  ```
+  Foundation '<FOUNDATION_NAME>' not found. Expected: docs/<FOUNDATION_NAME>/
+  Available foundations: <list the subdirectories under docs/ that contain a *.pack.txt>
+  ```
+  Then stop.
+
+- If the folder exists but `PACK_FILE` is missing:
+  ```
+  Foundation '<FOUNDATION_NAME>' has no bundle yet (expected <PACK_FILE>).
+  Build it first — see docs/<FOUNDATION_NAME>/PACKAGING.md:
+    1. Create the sample solution under the sentinel name in a scratch folder.
+    2. Run docs/<FOUNDATION_NAME>/pack-foundation.ps1 to produce the .pack.txt.
+  ```
+  Then stop.
+
+Read **only** the `#` header lines of `PACK_FILE` to obtain `SENTINEL` and the declared
+file count. Use a bounded command — **do not** open the pack with the Read tool, `cat`,
+`head`, or `tail` (it would load ~20K tokens of pack body into context):
+
+```bash
+grep -m 30 '^#' "docs/<FOUNDATION_NAME>/<FOUNDATION_NAME>.pack.txt"
+```
+
+This returns just the sentinel, file count, and replacement contract.
+
+---
+
+## Step 2 — Confirm the scaffold plan
+
+Show this summary and wait for `yes`:
+
+```
+Foundation : <FOUNDATION_NAME>
+Bundle     : <PACK_FILE>  (<N> files, sentinel: <SENTINEL>)
+App Name   : <APP_NAME>
+Output     : <OUTPUT_DIR or repo root>
+
+Rename (from bundle sentinel -> your app name):
+  <SENTINEL>            -> <APP_NAME>
+  <SENTINEL _-form>     -> <APP_NAME _-form>
+  <sentinel --form>     -> <appname --form>
+  <sentinel .-form>     -> <appname lower-dot>
+
+Unchanged: 'Projects' sample domain, all AppWeaver.* framework packages.
+
+Proceed? (yes/no)
+```
+
+---
+
+## Step 3 — Dry run, then unpack
+
+### Choosing the runner (do this first)
+
+Each foundation ships two equivalent unpackers. **Prefer PowerShell** (`unpack-foundation.ps1`,
+~50× faster); fall back to bash (`unpack-foundation.sh`) only when `pwsh` is absent. Detect once
+and reuse the choice for every unpack call (Steps 3 and 4c):
+
+```bash
+command -v pwsh >/dev/null 2>&1 && echo "pwsh" || echo "sh"
+```
+
+The bash port takes the same flags in kebab-case (`--pack-file`, `--target-app-name`,
+`--out-dir`, `--dry-run`, `--force`); positional args also work.
+
+### Dry run
+
+First do a **dry run** to surface any path collisions without writing anything.
+
+PowerShell (preferred):
+```bash
+pwsh -NoProfile -File "docs/<FOUNDATION_NAME>/unpack-foundation.ps1" \
+    -PackFile "docs/<FOUNDATION_NAME>/<FOUNDATION_NAME>.pack.txt" \
+    -TargetAppName "<APP_NAME>" \
+    -OutDir "<OUTPUT_DIR>" \
+    -DryRun
+```
+
+bash fallback (only if `pwsh` is missing):
+```bash
+bash "docs/<FOUNDATION_NAME>/unpack-foundation.sh" \
+    --pack-file "docs/<FOUNDATION_NAME>/<FOUNDATION_NAME>.pack.txt" \
+    --target-app-name "<APP_NAME>" \
+    --out-dir "<OUTPUT_DIR>" \
+    --dry-run
+```
+
+- If it reports files that **already exist** (the script throws on conflict unless `-Force`
+  / `--force`), show the conflict list and ask whether to overwrite. Only add the force flag
+  if the user agrees.
+- Otherwise run it for real (drop `-DryRun`/`--dry-run`; add the force flag only if the user
+  approved overwrite). PowerShell (preferred):
+
+```bash
+pwsh -NoProfile -File "docs/<FOUNDATION_NAME>/unpack-foundation.ps1" \
+    -PackFile "docs/<FOUNDATION_NAME>/<FOUNDATION_NAME>.pack.txt" \
+    -TargetAppName "<APP_NAME>" \
+    -OutDir "<OUTPUT_DIR>"
+```
+
+bash fallback:
+```bash
+bash "docs/<FOUNDATION_NAME>/unpack-foundation.sh" \
+    --pack-file "docs/<FOUNDATION_NAME>/<FOUNDATION_NAME>.pack.txt" \
+    --target-app-name "<APP_NAME>" \
+    --out-dir "<OUTPUT_DIR>"
+```
+
+Capture the script's stdout (it reports the number of files written). Do **not**
+hand-edit or regenerate any unpacked file.
+
+---
+
+## Step 4 — Offer reference project
+
+After the foundation unpack succeeds, ask the user whether to also unpack the bundled
+reference sample:
+
+```
+AskUserQuestion — single-select:
+  "Would you like to include the reference sample project?"
+  • "Yes — include reference sample"  (description: "Unpacks sample domain slices — Projects, Users, Reports — and merges them into the scaffolded project")
+  • "No — skip reference sample"      (description: "Leave the project as a clean, empty foundation")
+```
+
+- If the user chooses **No**, proceed directly to Step 5 (Verify).
+- If the user chooses **Yes**, continue with the steps below **before** verifying.
+
+### Step 4a — Locate the reference pack
+
+`REFERENCE_PACK_FILE` = `docs/<FOUNDATION_NAME>/<FOUNDATION_NAME>.Reference.pack.txt`
+`UNPACK_REF`          = `docs/<FOUNDATION_NAME>/unpack-reference-foundation.ps1` (preferred)
+                        or `…/unpack-reference-foundation.sh` (fallback when `pwsh` is absent)
+
+If the pack or the matching unpacker for your chosen runner is missing:
+```
+Reference pack not found: <REFERENCE_PACK_FILE>
+Run pack-reference-foundation.ps1 first (see docs/<FOUNDATION_NAME>/).
+Skipping reference sample.
+```
+Then proceed to Step 5 without unpacking reference files.
+
+Read the header of `REFERENCE_PACK_FILE` to obtain `REF_SENTINEL` and `REF_FILE_COUNT` —
+again with a bounded `grep -m 30 '^#' "<REFERENCE_PACK_FILE>"`, **never** a full Read/`cat`
+of the reference pack (it is just as large as the foundation pack).
+
+### Step 4b — Save the foundation DbContext before overwrite
+
+The reference unpack will conflict with (and overwrite) `ApplicationDbContext.cs` because
+both packs rename their sentinel's project structure to the same output path. Before running
+the reference unpack, **read and save** the full content of the existing foundation DbContext:
+
+```powershell
+# Locate it — do NOT assume a fixed path; search the output tree:
+$dbCtxPath = Get-ChildItem -Path "<OUTPUT_DIR>/src" -Recurse -Filter "ApplicationDbContext.cs" |
+             Select-Object -First 1 -ExpandProperty FullName
+$foundationDbCtx = [System.IO.File]::ReadAllText($dbCtxPath)
+```
+
+Store `$foundationDbCtx` in memory; you will need it in Step 4d.
+
+### Step 4c — Unpack the reference pack
+
+Run with `-Force` / `--force` (the DbContext and any other overlapping files will be
+overwritten — the DbContext will be restored via merge in Step 4d). Use the **same runner**
+you selected in Step 3 (`pwsh` preferred, `.sh` only if `pwsh` is missing).
+
+PowerShell (preferred):
+```bash
+pwsh -NoProfile -File "docs/<FOUNDATION_NAME>/unpack-reference-foundation.ps1" \
+    -PackFile      "docs/<FOUNDATION_NAME>/<FOUNDATION_NAME>.Reference.pack.txt" \
+    -TargetAppName "<APP_NAME>" \
+    -OutDir        "<OUTPUT_DIR>" \
+    -Force
+```
+
+bash fallback:
+```bash
+bash "docs/<FOUNDATION_NAME>/unpack-reference-foundation.sh" \
+    --pack-file      "docs/<FOUNDATION_NAME>/<FOUNDATION_NAME>.Reference.pack.txt" \
+    --target-app-name "<APP_NAME>" \
+    --out-dir        "<OUTPUT_DIR>" \
+    --force
+```
+
+Capture the count of files written.
+
+### Step 4d — Merge ApplicationDbContext.cs
+
+After the reference unpack the DbContext file now contains the **reference version**
+(sample DbSet<> properties only, no `OnModelCreating`). Merge it with the saved
+**foundation version** (full `OnModelCreating`, no DbSet<>) to produce a single
+complete DbContext.
+
+**Merge rules — apply in order:**
+
+1. **Base = foundation file.** Start with `$foundationDbCtx` as the text to edit.
+
+2. **Add missing `using` directives.** Read the reference DbContext's `using` lines.
+   For each one not already present in the foundation file, insert it at the top of the
+   using block (before the namespace declaration or the class declaration).
+
+3. **Add `DbSet<>` properties.** Extract every `public DbSet<…>` property line from the
+   reference DbContext. Insert them as a block inside the foundation class body, directly
+   after the opening brace `{` of the class and before `OnModelCreating` (or before the
+   closing `}` if there is no `OnModelCreating`). Preserve the comment above the DbSets
+   (e.g. `// TaskContext`) if present.
+
+4. **Preserve everything else in the foundation file unchanged.** Do not touch the class
+   header, constructor, interface list, `OnModelCreating`, or any existing using statements.
+
+5. **Write the merged result** back to `$dbCtxPath` (overwrite the reference version that
+   the unpack left there).
+
+**Example — VerticalSlice result after merge:**
+```csharp
+using Microsoft.EntityFrameworkCore;
+using AppWeaver.Repository.EfCore;
+using AppWeaver.Contexts;
+using AppWeaver.DomainAbstraction.Entities;
+// ← reference usings inserted here, e.g.:
+using AppWeaver.Pharma.Service.Projects.Domain;
+using AppWeaver.Pharma.Service.Users.Domain;
+using AppWeaver.Pharma.Service.Reports.Domain;
+
+namespace AppWeaver.Pharma.Service.Infrastructure;
+
+public class ApplicationDbContext(
+    DbContextOptions<ApplicationDbContext> options,
+    ICurrentTenant? tenant = null
+) : ContextAwareDbContext<ApplicationDbContext>(options, tenant)
+{
+    // TaskContext  ← DbSet block from reference, inserted here
+    public DbSet<Project> Projects => Set<Project>();
+    public DbSet<ProjectTask> ProjectTasks => Set<ProjectTask>();
+    public DbSet<TaskUser> TaskUsers => Set<TaskUser>();
+    public DbSet<ReportRequest> ReportRequests => Set<ReportRequest>();
+
+    protected override void OnModelCreating(ModelBuilder modelBuilder)
+    {
+        // ... full foundation OnModelCreating preserved unchanged ...
+    }
+}
+```
+
+---
+
+## Step 5 — Verify
+
+After unpacking (and merging, if reference was included):
+
+1. **File count** — confirm the written count(s) match the bundle's declared file count(s).
+2. **Sentinel residue** — search the output tree for any leftover sentinel token
+   (dotted/underscored/lower forms). There should be **none**. If any remain, report the
+   files (it indicates a case form the bundle used that the rename list missed).
+3. **Framework packages intact** — confirm `AppWeaver.*` package references in the
+   generated `.csproj`/`Directory.Packages.props` are unchanged.
+4. **DbContext integrity (if reference included)** — confirm the merged `ApplicationDbContext.cs`
+   contains both `DbSet<>` properties (from reference) **and** `OnModelCreating` (from foundation).
+   If either section is missing, report it as a warning.
+5. **Build (optional, recommended)** — if the .NET SDK is available, offer to build.
+   The solution file is whatever the bundle shipped (e.g. `api.sln`) and is **not**
+   renamed unless its name contains the sentinel — so discover it rather than assuming
+   `<APP_NAME>.sln`:
+   ```powershell
+   $sln = Get-ChildItem "<OUTPUT_DIR>" -Filter *.sln | Select-Object -First 1
+   dotnet build $sln.FullName -c Debug
+   ```
+   Report results; do not auto-fix — a build failure means the **bundle** needs fixing
+   and repacking (see PACKAGING.md), not a per-scaffold patch.
+
+Report check failures as warnings; do not silently continue past a sentinel-residue finding.
+
+---
+
+## Step 6 — Completion report
+
+```
+✅ Foundation scaffold complete
+
+Foundation  : <FOUNDATION_NAME>
+App Name    : <APP_NAME>
+Output      : <OUTPUT_DIR or repo root>
+Files       : <N> written  [+ <M> reference files]  (omit reference line if skipped)
+Reference   : included / skipped
+
+Next steps:
+  1. [If reference skipped] Rename the sample 'Projects' domain to your bounded context.
+  2. Ensure your NuGet feed for AppWeaver.* packages is configured.
+  3. Run the AppHost:  dotnet run --project <OUTPUT_DIR>/src/<APP_NAME>.AppHost
+  4. Use /aw-spec-specify to create your first feature spec.
+```
+
+---
+
+## Notes
+
+- **The bundle is the source of truth** — if a scaffold comes out wrong, fix the foundation
+  solution and re-pack (`PACKAGING.md`); never patch generated output as a workaround.
+- To add a new foundation, create `docs/<Name>/` with its own `pack-foundation.ps1`,
+  `unpack-foundation.ps1`, `PACKAGING.md`, and built `<Name>.pack.txt`.
+```