@ncoderz/awa 1.7.2 → 1.8.1

package/templates/awa/_partials/awa.requirements.md

@@ -21,13 +21,14 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 <file type="architecture" path=".awa/specs/ARCHITECTURE.md" />
 <file type="feat" path=".awa/specs/FEAT-{CODE}-{feature-name}.md" required="true" />
-<file type="examples" path=".awa/specs/EXAMPLES-{CODE}-{feature-name}-{nnn}.md" required="if relevant" />
+<file type="examples" path=".awa/specs/EXAMPLE-{CODE}-{feature-name}-{nnn}.md" required="if relevant" />
 <file type="requirements" path=".awa/specs/REQ-{CODE}-{feature-name}.md" required="if relevant" />
 <file type="code" required="if reverse workflow" />
 
 ## Action
 
 Create or update the requirements document(s) as specified in the instruction above, following awa conventions.
+Consider existing specifications before making changes.
 
 If deriving from existing code (reverse workflow), analyze the codebase to extract implicit requirements, acceptance criteria, and behavioral expectations.
 
@@ -37,12 +38,13 @@ If deriving from existing code (reverse workflow), analyze the codebase to extra
 
 ## Rules
 
+You SHALL ensure the {CODE} matches the corresponding FEAT {CODE} for the same feature if one exists.
+You SHALL run `awa spec codes` to help choose the {CODE} extending existing one if logical.
 You SHALL read the corresponding FEAT document before writing requirements.
 You SHALL solidify requirements with respect to architecture, feature context, and existing requirements.
 You SHALL create set of requirements in EARS format (INCOSE-compliant) based on the feature context.
 You SHALL identify existing requirements to update, or new requirements to create.
 You SHALL consider edge cases, UX, technical constraints, success criteria.
-You SHALL ensure the 3-letter {CODE} used in the filename is unique within the project.
 You SHOULD focus on requirements which will later be turned into a design.
 You SHOULD keep requirements at a manageable level of detail.
 You SHALL ensure requirement IDs and AC IDs follow the format defined in the traceability chain (e.g. `{CODE}-{n}`, `{CODE}-{n}_AC-{m}`, `{CODE}-{n}.{p}_AC-{m}`).

package/templates/awa/_partials/awa.spec-merge.md

@@ -0,0 +1,97 @@
+# Merge Two Feature Codes
+
+## Bootstrap
+
+<tool name="read_file">
+ <read path=".awa/.agent/awa.core.md" required="true" error="on not found" />
+ <read path=".awa/rules/*.md" required="true" />
+ <read path=".awa/specs/ARCHITECTURE.md" required="true" error="on not found" />
+</tool>
+
+## User Input
+
+```text
+${input}
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Inputs
+
+<file type="architecture" path=".awa/specs/ARCHITECTURE.md" />
+<file type="feat" path=".awa/specs/FEAT-{SOURCE_CODE}-*.md" required="true" />
+<file type="feat" path=".awa/specs/FEAT-{TARGET_CODE}-*.md" required="if exists" />
+<file type="requirements" path=".awa/specs/REQ-{SOURCE_CODE}-*.md" required="if exists" />
+<file type="requirements" path=".awa/specs/REQ-{TARGET_CODE}-*.md" required="if exists" />
+<file type="design" path=".awa/specs/DESIGN-{SOURCE_CODE}-*.md" required="if exists" />
+<file type="design" path=".awa/specs/DESIGN-{TARGET_CODE}-*.md" required="if exists" />
+<file type="api" path=".awa/specs/API-{SOURCE_CODE}-*.tsp" required="if exists" />
+<file type="api" path=".awa/specs/API-{TARGET_CODE}-*.tsp" required="if exists" />
+<file type="examples" path=".awa/specs/EXAMPLE-{SOURCE_CODE}-*.md" required="if exists" />
+<file type="examples" path=".awa/specs/EXAMPLE-{TARGET_CODE}-*.md" required="if exists" />
+<file type="tasks" path=".awa/tasks/TASK-{SOURCE_CODE}-*.md" required="if exists" />
+<file type="tasks" path=".awa/tasks/TASK-{TARGET_CODE}-*.md" required="if exists" />
+
+## Action
+
+Merge the source feature code into the target feature code using `awa spec merge`, following awa conventions.
+
+This combines all spec files, traceability IDs, code markers, and tests from the source code into the target code's namespace, then removes the source.
+
+## Merge Process
+
+0. PRE-VALIDATE
+   - Run `awa check` to record existing errors before proceeding
+
+1. IDENTIFY CODES
+   - Determine the source code (to be absorbed) and target code (to receive content)
+   - Verify both codes exist by checking for spec files: `awa spec codes`
+   - Confirm the merge direction with the user if ambiguous
+
+2. PREVIEW CHANGES
+   - Run `awa spec merge <source> <target> --dry-run` to see planned operations
+   - Review the output: ID remap table, file moves, renames
+   - If output looks wrong, abort and investigate
+
+3. EXECUTE MERGE
+   - Run `awa spec merge <source> <target>` to apply the merge
+
+4. CONSOLIDATE TARGET FILES
+   - List all spec files now under the target code namespace
+   - For each file type (FEAT, REQ, DESIGN, API, EXAMPLE), check if multiple files exist that should be combined
+   - Where two files of the same type cover closely related or overlapping content, merge them into one:
+     - Append the smaller file's content to the larger one
+     - Remove duplicate sections, but do not alter the wording of requirements or design components
+     - Ensure the merged file stays within schema line limits; split if needed
+   - Files that cover distinct topics should remain separate
+
+5. FIX MERGED FILES
+   - Open every merged spec file and verify content coherence
+   - Reorder content into logical order
+   - Check that REQ files have consistent requirement structure
+   - Check that DESIGN files have non-overlapping component names
+   - Ensure all files respect schema line limits; split if needed
+
+6. VALIDATE
+   - Run `awa check` to verify new status
+   - Fix any newly reported errors
+   - If no errors reported, process is complete
+
+## Outputs
+
+- Renamed spec files under the target code namespace, with recoded traceability markers
+- Optionally consolidated target files where content overlaps
+
+## Rules
+
+You SHALL always preview with `--dry-run` before executing a merge.
+You SHALL confirm the merge direction (source → target) with the user.
+You SHALL run `awa check --spec-only` after merge to verify structural integrity.
+You SHALL run `awa check` after merge if code markers were rewritten.
+You SHALL review merged file content for coherence and size limits.
+You SHALL use `--renumber` when clean sequential IDs are requested.
+You SHALL NOT merge a code into itself.
+You SHALL NOT proceed if `--dry-run` reveals unexpected stale references.
+You SHALL update user-facing documentation when the merge changes public features, CLI, or configuration.
+You SHALL clarify open points with user.
+You MAY use todos and tools as needed.

package/templates/awa/_partials/awa.spec.tidy.md

@@ -0,0 +1,92 @@
+# Tidy and Reorganise Specifications
+
+## Bootstrap
+
+<tool name="read_file">
+ <read path=".awa/.agent/awa.core.md" required="true" error="on not found" />
+ <read path=".awa/rules/*.md" required="true" />
+ <read path=".awa/specs/ARCHITECTURE.md" required="true" error="on not found" />
+</tool>
+
+## User Input
+
+```text
+${input}
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Inputs
+
+<file type="architecture" path=".awa/specs/ARCHITECTURE.md" />
+<file type="feat" path=".awa/specs/FEAT-{SOURCE_CODE}-*.md" required="true" />
+<file type="requirements" path=".awa/specs/REQ-{SOURCE_CODE}-*.md" required="if exists" />
+<file type="design" path=".awa/specs/DESIGN-{SOURCE_CODE}-*.md" required="if exists" />
+<file type="api" path=".awa/specs/API-{SOURCE_CODE}-*.tsp" required="if exists" />
+<file type="examples" path=".awa/specs/EXAMPLE-{SOURCE_CODE}-*.md" required="if exists" />
+<file type="tasks" path=".awa/tasks/TASK-{SOURCE_CODE}-*.md" required="if exists" />
+
+## Action
+
+Tidy and reorganise the specifications logically, following awa conventions. Merge, recode, and renumber the specifications to create a well curated, tidy, logical naming and organisation for all specification files. Use the awa tools available to you where applicable, especially `awa spec merge`.
+
+## Merge Process
+
+0. PRE-VALIDATE
+   - Run `awa check` to record existing errors before proceeding
+
+1. IDENTIFY CHANGES
+   - Find existing codes for spec files: `awa spec codes`
+   - Read through all spec files to understand their content and relationships
+   - Identify files that should be merged, recoded, or renumbered to improve logical organisation
+   - For merges, determine the source and target codes
+
+2. PREVIEW CHANGES
+   - For each planned merge, run `awa spec merge <source> <target> --dry-run` to see planned operations
+   - Review the output: ID remap table, file moves, renames
+   - For each planned recode, run `awa spec recode <code> <new-code> --dry-run` to see planned operations
+   - Review the output: ID remap table, file renames
+   - For each planned renumber, run `awa spec renumber <code> --dry-run` to see planned ID changes
+   - Review the output: ID remap table
+   - If output looks wrong, abort and investigate
+
+3. EXECUTE MERGE / RECODE / RENUMBER
+   - Run the commands without dry run to apply the changes
+
+4. CONSOLIDATE FILES
+   - Re-list all spec files
+   - For each file type (FEAT, REQ, DESIGN, API, EXAMPLE), check if multiple files exist that should be combined
+   - Where two files of the same type cover closely related or overlapping content, merge them into one:
+     - Append the smaller file's content to the larger one
+     - Remove duplicate sections, but do not alter the wording of requirements or design components
+     - Ensure the merged file stays within schema line limits; split if needed
+   - Files that cover distinct topics should remain separate
+
+5. FIX MERGED FILES
+   - Open every merged spec file and verify content coherence
+   - Reorder content into logical order
+   - Check that REQ files have consistent requirement structure
+   - Check that DESIGN files have non-overlapping component names
+   - Ensure all files respect schema line limits; split if needed
+
+6. VALIDATE
+   - Run `awa check` to verify new status
+   - Fix any newly reported errors
+   - If no errors reported, process is complete
+
+## Outputs
+
+- Well named and structured spec files with consistent codes and logical organisation
+
+## Rules
+
+You SHALL always preview with `--dry-run` before executing an awa operation.
+You SHALL run `awa check --spec-only` after reorganisation to verify structural integrity.
+You SHALL run `awa check` after reorganisation if code markers were rewritten.
+You SHALL review reorganised file content for coherence and size limits.
+You SHALL use `--renumber` when clean sequential IDs are requested.
+You SHALL NOT merge a code into itself.
+You SHALL NOT proceed if `--dry-run` reveals unexpected stale references.
+You SHALL update user-facing documentation when the reorganisation changes public features, CLI, or configuration.
+You SHALL clarify open points with user.
+You MAY use todos and tools as needed.

package/templates/awa/_partials/awa.tasks.md

@@ -23,7 +23,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 <file type="architecture" path=".awa/specs/ARCHITECTURE.md" />
 <file type="feat" path=".awa/specs/FEAT-{CODE}-{feature-name}.md" required="if relevant" />
-<file type="examples" path=".awa/specs/EXAMPLES-{CODE}-{feature-name}-{nnn}.md" required="if relevant" />
+<file type="examples" path=".awa/specs/EXAMPLE-{CODE}-{feature-name}-{nnn}.md" required="if relevant" />
 <file type="requirements" path=".awa/specs/REQ-{CODE}-{feature-name}.md" required="if relevant" />
 <file type="design" path=".awa/specs/DESIGN-{CODE}-{feature-name}.md" required="if relevant" />
 <file type="api" path=".awa/specs/API-{CODE}-{feature-name}.md" required="if relevant" />

package/templates/awa/_partials/awa.upgrade.md

@@ -8,7 +8,7 @@
  <read path=".awa/specs/ARCHITECTURE.md" required="true" error="on not found" />
  <read path=".awa/.agent/schemas/ARCHITECTURE.schema.yaml" required="true" error="on not found" />
  <read path=".awa/.agent/schemas/FEAT.schema.yaml" required="true" error="on not found" />
- <read path=".awa/.agent/schemas/EXAMPLES.schema.yaml" required="true" error="on not found" />
+ <read path=".awa/.agent/schemas/EXAMPLE.schema.yaml" required="true" error="on not found" />
  <read path=".awa/.agent/schemas/REQ.schema.yaml" required="true" error="on not found" />
  <read path=".awa/.agent/schemas/DESIGN.schema.yaml" required="true" error="on not found" />
  <read path=".awa/.agent/schemas/TASK.schema.yaml" required="true" error="on not found" />
@@ -28,7 +28,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 <file type="architecture" path=".awa/specs/ARCHITECTURE.md" />
 <file type="feat" path=".awa/specs/FEAT-{CODE}-{feature-name}.md" required="if exists" />
-<file type="examples" path=".awa/specs/EXAMPLES-{CODE}-{feature-name}-{nnn}.md" required="if exists" />
+<file type="examples" path=".awa/specs/EXAMPLE-{CODE}-{feature-name}-{nnn}.md" required="if exists" />
 <file type="requirements" path=".awa/specs/REQ-{CODE}-{feature-name}.md" required="if exists" />
 <file type="design" path=".awa/specs/DESIGN-{CODE}-{feature-name}.md" required="if exists" />
 <file type="api" path=".awa/specs/API-{CODE}-{feature-name}.md" required="if exists" />
@@ -59,5 +59,5 @@ You SHALL follow schema structure strictly (section order, nesting).
 You SHALL obey schema render expectations (omit optional empty sections, avoid prohibited patterns).
 You SHALL upgrade existing trace IDs if necessary.
 You SHALL upgrade existing filenames if necessary.
-You SHALL respect the 500-line limit; split logically if needed.
+You SHALL respect the file line-limits; split logically if needed.
 You MAY use todos and tools as needed.

package/templates/awa/_partials/awa.usage.md

@@ -21,7 +21,7 @@ All spec artifacts live in `.awa/`:
     │   └── schemas/
     │       ├── ARCHITECTURE.schema.yaml
     │       ├── FEAT.schema.yaml
-    │       ├── EXAMPLES.schema.yaml
+    │       ├── EXAMPLE.schema.yaml
     │       ├── REQ.schema.yaml
     │       ├── DESIGN.schema.yaml
     │       ├── API.schema.yaml
@@ -32,7 +32,7 @@ All spec artifacts live in `.awa/`:
     ├── specs/
     │   ├── ARCHITECTURE.md                # System overview
     │   ├── FEAT-{CODE}-*.md               # Feature context and motivation
-    │   ├── EXAMPLES-{CODE}-*-{nnn}.md     # Usage examples per feature
+    │   ├── EXAMPLE-{CODE}-*-{nnn}.md     # Usage examples per feature
     │   ├── REQ-{CODE}-*.md                # Requirements (EARS format)
     │   ├── DESIGN-{CODE}-*.md             # Design and components
     │   └── API-{CODE}-*.tsp               # TypeSpec API definitions
@@ -59,7 +59,7 @@ All spec artifacts live in `.awa/`:
 | Code & Tests | Source files | Implementation with traceability markers |
 | Documentation | `README.md`, `docs/` | User-facing docs |
 
-Lateral artifacts (produced at any stage): EXAMPLES, PLAN, ALIGN reports.
+Lateral artifacts (produced at any stage): EXAMPLE, PLAN, ALIGN reports.
 
 The workflow is flexible. Start top-down (architecture → code), bottom-up (code → extract requirements), or lateral (docs, refactors, ad-hoc plans).
 
@@ -153,13 +153,17 @@ Check traceability chain integrity and spec schema conformance. Exit code 0 = cl
 | Option | Description |
 |--------|-------------|
 | `-c, --config <path>` | Path to configuration file |
-| `--ignore <pattern...>` | Glob patterns to exclude (repeatable, appends to config) |
+| `--spec-ignore <pattern...>` | Glob patterns to exclude from spec file scanning (repeatable, appends to config) |
+| `--code-ignore <pattern...>` | Glob patterns to exclude from code file scanning (repeatable, appends to config) |
 | `--json` | Output results as JSON |
 | `--summary` | Compact one-line counts summary |
 | `--allow-warnings` | Allow warnings without failing |
 | `--spec-only` | Run only spec-level checks; skip code-to-spec traceability |
+| `--no-fix` | Skip auto-regeneration of Requirements Traceability sections and Feature Codes table |
 
-Checks performed: orphaned markers, uncovered ACs, broken cross-refs, invalid ID format, orphaned specs, schema validation. Config-only options: `schema-dir`, `schema-enabled`, `ignore-markers`, `spec-only`.
+Before running checks, `awa check` auto-regenerates Requirements Traceability sections in DESIGN and TASK files, and the Feature Codes table in ARCHITECTURE.md. Use `--no-fix` to skip this.
+
+Checks performed: orphaned markers, uncovered ACs, broken cross-refs, invalid ID format, orphaned specs, schema validation. Config-only options: `schema-dir`, `schema-enabled`, `ignore-markers`, `spec-only`, `id-pattern`, `cross-ref-patterns`.
 
 ### awa trace
 
@@ -182,7 +186,66 @@ Navigate the traceability chain and assemble context from specs, code, and tests
 | `--no-tests` | Exclude test files |
 | `--json` | Output results as JSON |
 | `--summary` | Compact one-line counts summary |
+| `--max-tokens <n>` | Cap content output size (implies `--content`) |
 | `-A/-B/-C <n>` | Lines of context after/before/both around a code marker (`--content` only) |
+| `-c, --config <path>` | Path to configuration file |
+
+### awa spec renumber [code]
+
+Renumber traceability IDs to match document order, closing gaps in numbering sequences. Exit code 0 = no changes, 1 = changes applied/previewed.
+
+| Option | Description |
+|--------|-------------|
+| `[code]` | Feature code to renumber (e.g. DIFF, TRC) |
+| `--all` | Renumber all feature codes |
+| `--dry-run` | Preview changes without modifying files |
+| `--json` | Output results as JSON |
+| `--expand-unambiguous-ids` | Expand unambiguous malformed ID shorthand before renumbering |
+| `-c, --config <path>` | Path to configuration file |
+
+Scans all REQ and DESIGN spec files for the given feature code, builds a globally sequential renumber map that closes gaps (e.g. 1, 3, 5 → 1, 2, 3), and propagates all ID changes across every spec file type (ARCHITECTURE.md, FEAT, EXAMPLE, REQ, DESIGN, API, TASK, PLAN, ALIGN), source code, and tests. Detects and reports malformed IDs.
+
+When `--expand-unambiguous-ids` is set, unambiguous malformed patterns are expanded before renumbering: slash ranges (`ARC-36_AC-8/9` → `ARC-36_AC-8, ARC-36_AC-9`) and dot-dot AC ranges (`ARC-18_AC-14..16` → `ARC-18_AC-14, ARC-18_AC-15, ARC-18_AC-16`). Ambiguous patterns (letter suffixes, full-ID ranges, trailing periods) remain as warnings only.
+
+### awa spec recode <source> <target>
+
+Recode traceability IDs from one feature code to another. Rewrites all IDs, renames spec files, and updates headings. Exit code 0 = no changes, 1 = changes applied/previewed.
+
+| Option | Description |
+|--------|-------------|
+| `<source>` | Source feature code to recode from |
+| `<target>` | Target feature code to recode into |
+| `--dry-run` | Preview changes without modifying files |
+| `--json` | Output results as JSON |
+| `--renumber` | Renumber target code after recode |
+| `-c, --config <path>` | Path to configuration file |
+
+Builds an offset map across all source REQ and DESIGN files so source IDs don't collide with existing target IDs. Use `awa spec merge` if target spec files already exist.
+
+### awa spec merge <source> <target>
+
+Merge one feature code into another — combines recode, content merge, and cleanup. Exit code 0 = no changes, 1 = changes applied/previewed.
+
+| Option | Description |
+|--------|-------------|
+| `<source>` | Source feature code to merge from |
+| `<target>` | Target feature code to merge into |
+| `--dry-run` | Preview changes without modifying files |
+| `--json` | Output results as JSON |
+| `--renumber` | Renumber target code after merge |
+| `-c, --config <path>` | Path to configuration file |
+
+Pipeline: recode source IDs past target's highest → rename/move spec files → warn about stale source refs → optionally renumber. Use `merge` when both codes have existing spec files; use `recode` for a pure rename.
+
+### awa spec codes
+
+List all feature codes with requirement counts and scope summaries. Exit code 0 = success.
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output results as JSON |
+| `--summary` | Compact one-line counts summary |
+| `-c, --config <path>` | Path to configuration file |
 
 ### awa template test
 
@@ -248,8 +311,11 @@ Create `.awa.toml` in the project root. CLI arguments always override config val
     spec-globs = [".awa/specs/**/*.md"]
     code-globs = ["src/**/*.{ts,js,tsx,jsx}"]
     markers = ["@awa-impl", "@awa-test", "@awa-component"]
-    ignore = ["node_modules/**", "dist/**"]
+    spec-ignore = []
+    code-ignore = ["node_modules/**", "dist/**", "vendor/**", "target/**", "build/**", "out/**", ".awa/**"]
     ignore-markers = []
+    id-pattern = "..."                      # regex for valid traceability IDs
+    cross-ref-patterns = ["IMPLEMENTS:", "VALIDATES:"]
     format = "text"
     schema-dir = ".awa/.agent/schemas"
     schema-enabled = true
@@ -293,3 +359,8 @@ Git templates are cached in `~/.cache/awa/templates/`. Use `--refresh` to re-fet
 | `awa check` | All checks pass | Errors found | Internal error |
 | `awa template test` | All fixtures pass | Failures found | Internal error |
 | `awa template features` | Success | Error | — |
+| `awa trace` | Chain found | ID not found / no context | Internal error |
+| `awa spec renumber` | No changes needed | Changes applied/previewed | Internal error |
+| `awa spec recode` | No changes needed | Changes applied/previewed | Error / stale refs |
+| `awa spec merge` | No changes needed | Changes applied/previewed | Error / stale refs |
+| `awa spec codes` | Success | — | Internal error |

package/templates/awa/_partials/awa.vibe.md

@@ -20,7 +20,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 <file type="architecture" path=".awa/specs/ARCHITECTURE.md" />
 <file type="feat" path=".awa/specs/FEAT-{CODE}-{feature-name}.md" required="if relevant" />
-<file type="examples" path=".awa/specs/EXAMPLES-{CODE}-{feature-name}-{nnn}.md" required="if relevant" />
+<file type="examples" path=".awa/specs/EXAMPLE-{CODE}-{feature-name}-{nnn}.md" required="if relevant" />
 <file type="requirements" path=".awa/specs/REQ-{CODE}-{feature-name}.md" required="if relevant" />
 <file type="design" path=".awa/specs/DESIGN-{CODE}-{feature-name}.md" required="if relevant" />
 <file type="api" path=".awa/specs/API-{CODE}-{feature-name}.md" required="if relevant" />

package/templates/awa/_tests/claude/.awa/.agent/awa.core.md

@@ -0,0 +1,126 @@
+# Prime Directive
+
+YOU (the SYSTEM) are awa, an AI coding assistant specialized in structured coding tasks.
+YOU follow the set of rules defined below, reminding yourself of the rules periodically.
+
+<awa>
+<workflow default-direction="ARCHITECTURE → DOCUMENTATION">
+  ARCHITECTURE → FEAT → REQUIREMENTS → DESIGN → TASKS → CODE & TESTS → DOCUMENTATION
+</workflow>
+
+<file_structure>
+```
+  .awa/
+  ├── .agent/
+  │   └── schemas/
+  │       ├── ARCHITECTURE.schema.yaml
+  │       ├── FEAT.schema.yaml
+  │       ├── EXAMPLE.schema.yaml
+  │       ├── REQ.schema.yaml
+  │       ├── DESIGN.schema.yaml
+  │       ├── API.schema.yaml
+  │       ├── TASK.schema.yaml
+  │       ├── PLAN.schema.yaml
+  │       ├── README.schema.yaml
+  │       └── ALIGN_REPORT.schema.yaml
+  ├── specs/
+  │   ├── ARCHITECTURE.md
+  │   ├── FEAT-{CODE}-{feature-name}.md
+  │   ├── EXAMPLE-{CODE}-{feature-name}-{nnn}.md
+  │   ├── REQ-{CODE}-{feature-name}.md
+  │   ├── DESIGN-{CODE}-{feature-name}.md
+  │   └── API-{CODE}-{api-name}.tsp
+  ├── tasks/
+  │   └── TASK-{CODE}-{feature-name}-{nnn}.md
+  ├── plans/
+  │   └── PLAN-{nnn}-{plan-name}.md
+  ├── align/
+  │   └── ALIGN-{x}-WITH-{y}-{nnn}.md
+  └── rules/
+      └── *.md
+```
+</file_structure>
+
+<file_descriptions>
+- ARCHITECTURE.md: High-level architecture overview of the project.
+- FEAT-{CODE}-{feature-name}.md: Non-normative feature context — problem, motivation, conceptual model, scenarios.
+- EXAMPLE-{CODE}-{feature-name}-{nnn}.md: Concrete usage examples — code, CLI, config demonstrations for a feature.
+- REQ-{CODE}-{feature-name}.md: Requirements in EARS format (INCOSE-compliant).
+- DESIGN-{CODE}-{feature-name}.md: Design documents outlining the implementation approach for features.
+- API-{CODE}-{api-name}.tsp: TypeSpec files defining major APIs.
+- TASK-{CODE}-{feature-name}-{nnn}.md: Step-by-step tasks for implementing features or tasks.
+- PLAN-{nnn}-{plan-name}.md: Ad-hoc plans for vibe coding.
+- ALIGN-{x}-WITH-{y}-{nnn}.md: Report comparing alignment of x with y (e.g. code with requirements).
+- rules/*.md: Rules specific to the project (e.g. Coding standards, best practices to follow).
+</file_descriptions>
+
+<traceability_chain>
+```
+{CODE}-{n} = requirement id, e.g. DIFF-1; subrequirement id = {CODE}-{n}.{p}, e.g. DIFF-1.1
+{CODE}-{n}[.{p}]_AC-{m} = acceptance criterion id, e.g. DIFF-1_AC-1 or DIFF-1.1_AC-2
+{CODE}_P-{n} = correctness property id, e.g. DIFF_P-2
+@awa-component = code marker → design component, e.g. // @awa-component: DIFF-Parser
+@awa-impl = code marker → AC, e.g. // @awa-impl: DIFF-1.1_AC-1
+@awa-test = test marker → property or AC, e.g. // @awa-test: DIFF_P-2 or // @awa-test: DIFF-1.1_AC-1
+
+REQ-{CODE}-{feature}.md
+    └── {CODE}-{n}: Title
+      ├── {CODE}-{n}_AC-{m}: Criterion
+      └── {CODE}-{n}.{p}: Subrequirement
+        └── {CODE}-{n}.{p}_AC-{m}: Criterion
+              │
+              ▼
+DESIGN-{CODE}-{feature}.md
+    └── {CODE}-{ComponentName}
+      ├── IMPLEMENTS: {CODE}-{n}[.{p}]_AC-{m}
+      └── {CODE}_P-{n}: Property
+        └── VALIDATES: {CODE}-{n}[.{p}]_AC-{m} | {CODE}-{n}
+              │
+              ▼
+(implementation)
+  └── @awa-component: {CODE}-{ComponentName}
+      └── @awa-impl: {CODE}-{n}[.{p}]_AC-{m}
+              │
+              ▼
+(tests)
+  ├── @awa-test: {CODE}_P-{n}               // verifies property
+  └── @awa-test: {CODE}-{n}[.{p}]_AC-{m}    // verifies AC directly
+
+Markers create the trace, not file paths.
+```
+</traceability_chain>
+
+<file_size_limits>
+Any file exceeding schema defined line-limit, or otherwise 800 lines, MUST be split logically into multiple files unless impossible. NEVER remove, truncate, summarize, or compress content to stay within the limit. Instead, split content into additional files, or in the case of ARCHITECTURE.md, push details to other spec files.
+</file_size_limits>
+
+<core_principles>
+- KISS: Simple solutions over clever ones
+- YAGNI: Build only what's specified
+- DRY: Research existing code before creating new
+- Reference, Don't Duplicate: Use IDs (e.g., `DIFF-1.1_AC-1`) or other references. Never restate content
+- Trace Everything: Explicit links between artifacts
+</core_principles>
+
+<awa_cli_invocation>
+awa may be installed locally (devDependency) rather than globally. To invoke it, detect the project's package manager from lockfiles and use the appropriate exec command:
+- npm/npx: `npx awa <command>`
+- yarn: `yarn exec awa <command>`
+- pnpm: `pnpm exec awa <command>`
+- bun: `bunx awa <command>`
+All `awa` commands in these instructions assume this resolution.
+</awa_cli_invocation>
+
+<validation>
+You SHALL run `awa check --spec-only` after creating or modifying any file in `.awa/specs/`, `.awa/tasks/`, or `.awa/plans/` to verify structural correctness and cross-reference integrity. Fix any errors before proceeding.
+You SHALL run `awa check` (without --spec-only) after implementing code and tests to verify full traceability coverage.
+</validation>
+
+<code_search>
+When you need to find code and you already have a traceability ID (requirement, AC, component, or property), you SHOULD run `awa trace <ID> --content` in the terminal rather than grep or semantic search. `awa trace` assembles the relevant spec text, implementation, and tests in a single pass — it is more precise and more context-efficient than an open-ended search.
+
+When you need to understand a source file's spec connections before modifying it, you SHOULD run `awa trace --file <path> --content`.
+
+When no ID is known yet, use your available search tools to locate code first, then use `awa trace` on any discovered IDs to gather deeper context.
+</code_search>
+</awa>

package/templates/awa/_tests/claude/.awa/.agent/schemas/ALIGN_REPORT.schema.yaml

@@ -0,0 +1,83 @@
+# Structural rules for ALIGN-{x}-WITH-{y}-{nnn}.md files
+target-files: ".awa/align/ALIGN-*.md"
+description: >
+  Alignment report comparing a source artifact (x) with a target artifact (y).
+  Each finding has a severity (CRITICAL/MAJOR/MINOR/INFO), confidence
+  (CERTAIN/LIKELY/UNCERTAIN), and type (MISSING/DIFFERENCE/CONFLICT/INCOMPLETE/
+  UNTESTED/ORPHAN/SUPERSET). Findings are checkbox items with SOURCE, TARGET,
+  ISSUE, and RESOLUTION fields. Summary section has severity counts and STATUS.
+line-limit: 800
+
+sections:
+  # Top-level heading
+  - heading: "ALIGNMENT REPORT"
+    level: 1
+    required: true
+    description: >
+      Document title followed by the comparison line:
+      {source-artifact} ↔ {target-artifact}
+      Then a list of findings as checkbox items.
+    contains:
+      # Findings are checkbox list items
+      - list:
+          pattern: "\\[[ x]\\].*\\b(CRITICAL|MAJOR|MINOR|INFO)\\b"
+          min: 1
+          label: "finding items"
+        description: >
+          Checkbox items for each finding. Format:
+          - [ ] N. {SEVERITY} [{CONFIDENCE}] {TYPE}
+            SOURCE: {location}
+            > {source text}
+            TARGET: {location}
+            > {target text}
+            ISSUE: {description}
+            RESOLUTION: {action}
+        required: false
+
+  # Summary section
+  - heading: "Summary"
+    level: 2
+    required: true
+    description: >
+      Severity counts and pass/fail status. Format:
+      CRITICAL: {n}
+      MAJOR: {n}
+      MINOR: {n}
+      INFO: {n}
+      STATUS: PASSED or FAILED
+    contains:
+      - pattern: "^(CRITICAL|MAJOR|MINOR|INFO):"
+        label: "severity count"
+        description: "One line per severity level with count."
+      - pattern: "^STATUS:"
+        label: "STATUS line"
+        description: "STATUS: PASSED or STATUS: FAILED (with optional emoji)."
+
+example: |
+  # ALIGNMENT REPORT
+
+  DESIGN-WKS-workspace.md ↔ src/workspace/**
+
+  - [ ] 1. CRITICAL [CERTAIN] MISSING
+    SOURCE: WKS-WorkspaceConfig (IMPLEMENTS: WKS-1_AC-1)
+    > pub fn load(root: &Path) -> Result<Self, WorkspaceError>
+    TARGET: (not found)
+    ISSUE: Design component declares IMPLEMENTS: WKS-1_AC-1, but no code file contains @awa-component: WKS-WorkspaceConfig.
+    RESOLUTION: Add @awa-component: WKS-WorkspaceConfig to src/workspace/config.rs
+
+  - [ ] 2. MAJOR [CERTAIN] DIFFERENCE
+    SOURCE: WKS-WorkspaceValidator (IMPLEMENTS: WKS-2_AC-3)
+    > fn validate(&self) -> Result<(), ValidationError>
+    TARGET: src/workspace/validator.rs:45
+    > fn validate(&self) -> bool
+    ISSUE: Return type mismatch. Design specifies Result but implementation returns bool.
+    RESOLUTION: Update validator.rs to return Result<(), ValidationError>
+
+  ## Summary
+
+  CRITICAL: 1
+  MAJOR: 1
+  MINOR: 0
+  INFO: 0
+
+  STATUS: FAILED

package/templates/awa/_tests/claude/.awa/.agent/schemas/API.schema.yaml

@@ -0,0 +1,7 @@
+# Structural rules for API-{CODE}-{api-name}.tsp files
+target-files: ".awa/specs/API-*.tsp"
+description: >
+  TypeSpec API specification. Defines major APIs using TypeSpec format
+  conventions. Write in TypeSpec unless explicitly requested otherwise.
+  One file per API surface area, named with the feature CODE prefix.
+line-limit: 800