aw-spec-cli 0.1.0 → 0.1.2

package/assets/.kilocode/workflows/aw-spec-taskstoissues.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.