@ncoderz/awa 1.0.0 → 1.2.0

package/templates/awa/_partials/awa.check.md

@@ -0,0 +1,73 @@
+# Run Traceability and Schema Checks
+
+## 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="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="code_and_tests" path="various" required="if relevant" />
+
+## Action
+
+Run `awa check` to validate traceability integrity and schema correctness across the project, then analyze and fix any reported errors.
+
+## Process
+
+1. RUN CHECK
+   - Execute `awa check` using the project's package manager
+   - Capture the full output (errors and warnings)
+
+2. ANALYZE FINDINGS
+   - Parse the output for errors (exit code 1) and warnings
+   - Group findings by type:
+     - **Orphaned markers**: `@awa-impl`, `@awa-test`, or `@awa-component` referencing IDs not found in specs
+     - **Broken cross-references**: IMPLEMENTS/VALIDATES pointing to invalid targets
+     - **Schema violations**: Missing sections, wrong heading levels, missing content
+     - **Uncovered ACs**: Acceptance criteria without corresponding `@awa-test`
+
+3. FIX ERRORS
+   - For orphaned markers: locate the marker in code and either fix the ID or add the missing spec entry
+   - For broken cross-references: update the DESIGN spec to reference valid REQ IDs
+   - For schema violations: update the spec file to match the expected structure
+   - For uncovered ACs: add missing `@awa-test` markers or note as intentionally deferred
+
+4. RE-RUN CHECK
+   - Execute `awa check` again to verify all errors are resolved
+   - Repeat fix cycle until exit code is 0
+
+5. REPORT
+   - Summarize what was found and what was fixed
+   - Note any remaining warnings that do not block (exit code 0)
+
+## Outputs
+
+<cli>awa check output (text or JSON)</cli>
+- Fixed source code files (corrected markers)
+- Fixed spec files (corrected cross-references or structure)
+
+## Rules
+
+You SHALL run `awa check` before making any fixes to establish a baseline.
+You SHALL fix all errors (severity: error) before completing.
+You SHALL re-run `awa check` after fixes to confirm resolution.
+You SHALL NOT remove traceability markers to silence errors — fix the root cause instead.
+You SHOULD address warnings when straightforward, but warnings do not block completion.
+You MAY use `awa check --format json` for structured output when analyzing complex results.
+You MAY use todos and tools as needed.
+

package/templates/awa/_partials/awa.code.md

@@ -163,5 +163,6 @@ You SHALL use any tools you need to help write and test code (e.g. MCP tools for
 You MUST add traceability markers (`@awa-component`, `@awa-impl`, `@awa-test`) to all code and tests.
 You MUST ensure every feature implementation traces to at least one acceptance criterion.
 You MUST ensure every test file traces to at least one design property.
+You MUST run `awa check` after implementation to verify all traceability markers resolve to spec IDs and no acceptance criteria are left uncovered.
 You SHALL clarify open points with user.
 You MAY use todos and tools as needed.

package/templates/awa/_partials/awa.core.md

@@ -12,16 +12,16 @@ YOU follow the set of rules defined below, reminding yourself of the rules perio
   .awa/
   ├── .agent/
   │   └── schemas/
-  │       ├── ARCHITECTURE.schema.md
-  │       ├── FEAT.schema.md
-  │       ├── EXAMPLES.schema.md
-  │       ├── REQ.schema.md
-  │       ├── DESIGN.schema.md
-  │       ├── API.schema.md
-  │       ├── TASK.schema.md
-  │       ├── PLAN.schema.md
-  │       ├── README.schema.md
-  │       └── ALIGN_REPORT.schema.md
+  │       ├── ARCHITECTURE.schema.yaml
+  │       ├── FEAT.schema.yaml
+  │       ├── EXAMPLES.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
@@ -97,4 +97,18 @@ Any file exceeding 500 lines MUST be split logically into multiple files unless
 - 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>
 </awa>

package/templates/awa/_partials/awa.design.md

@@ -6,8 +6,8 @@
  <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" />
- <read path=".awa/.agent/schemas/DESIGN.schema.md" required="true" error="on not found" />
- <read path=".awa/.agent/schemas/REQ.schema.md" optional="true" />
+ <read path=".awa/.agent/schemas/DESIGN.schema.yaml" required="true" error="on not found" />
+ <read path=".awa/.agent/schemas/REQ.schema.yaml" optional="true" />
 </tool>
 
 ## User Input
@@ -50,6 +50,7 @@ You SHALL consider edge cases, UX, technical constraints, success criteria.
 You MUST identify areas where research is needed based on the feature requirements.
 You MUST conduct research and build up context in the conversation thread.
 You SHALL ensure the 3-letter {CODE} used in the filename is unique within the project.
+You SHALL ensure IMPLEMENTS and VALIDATES cross-references in design components resolve to real requirement IDs and AC IDs.
 You SHALL support reverse workflow: deriving design from existing code when requested.
 You SHALL clarify open points with user.
 You MAY use todos and tools as needed.

package/templates/awa/_partials/awa.documentation.md

@@ -6,7 +6,7 @@
  <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" />
- <read path=".awa/.agent/schemas/README.schema.md" required="true" error="on not found" />
+ <read path=".awa/.agent/schemas/README.schema.yaml" required="true" error="on not found" />
 </tool>
 
 ## User Input

package/templates/awa/_partials/awa.examples.md

@@ -6,7 +6,7 @@
  <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="if exists" />
- <read path=".awa/.agent/schemas/EXAMPLES.schema.md" required="true" error="on not found" />
+ <read path=".awa/.agent/schemas/EXAMPLES.schema.yaml" required="true" error="on not found" />
 </tool>
 
 ## User Input

package/templates/awa/_partials/awa.feature.md

@@ -6,7 +6,7 @@
  <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" />
- <read path=".awa/.agent/schemas/FEAT.schema.md" required="true" error="on not found" />
+ <read path=".awa/.agent/schemas/FEAT.schema.yaml" required="true" error="on not found" />
 </tool>
 
 ## User Input

package/templates/awa/_partials/awa.plan.md

@@ -6,7 +6,7 @@
  <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" />
- <read path=".awa/.agent/schemas/PLAN.schema.md" required="true" error="on not found" />
+ <read path=".awa/.agent/schemas/PLAN.schema.yaml" required="true" error="on not found" />
 </tool>
 
 ## User Input

package/templates/awa/_partials/awa.refactor.md

@@ -39,6 +39,7 @@ Refactor the specified cod or docs as instructed, following awa conventions.
 
 You SHALL preserve existing behavior unless explicitly asked to change it.
 You SHALL maintain all traceability markers (@awa-component, @awa-impl, @awa-test).
+You SHALL run `awa check` after refactoring to verify all traceability markers are preserved and still resolve correctly.
 You SHALL ensure tests pass before and after refactoring.
 You SHALL make incremental changes, not wholesale rewrites.
 You SHALL NOT change public interfaces without explicit approval.

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

@@ -6,7 +6,7 @@
  <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" />
- <read path=".awa/.agent/schemas/REQ.schema.md" required="true" error="on not found" />
+ <read path=".awa/.agent/schemas/REQ.schema.yaml" required="true" error="on not found" />
 </tool>
 
 ## User Input
@@ -45,6 +45,7 @@ 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}`).
 You SHALL support reverse workflow: deriving requirements from existing code when requested.
 You SHALL clarify open points with user.
 You MAY use todos and tools as needed.

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

@@ -6,9 +6,9 @@
  <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" />
- <read path=".awa/.agent/schemas/DESIGN.schema.md" optional="true" />
- <read path=".awa/.agent/schemas/REQ.schema.md" optional="true" />
- <read path=".awa/.agent/schemas/TASK.schema.md" required="true" error="on not found" />
+ <read path=".awa/.agent/schemas/DESIGN.schema.yaml" optional="true" />
+ <read path=".awa/.agent/schemas/REQ.schema.yaml" optional="true" />
+ <read path=".awa/.agent/schemas/TASK.schema.yaml" required="true" error="on not found" />
 </tool>
 
 ## User Input

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

@@ -6,13 +6,14 @@
  <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" />
- <read path=".awa/.agent/schemas/ARCHITECTURE.schema.md" required="true" error="on not found" />
- <read path=".awa/.agent/schemas/FEAT.schema.md" required="true" error="on not found" />
- <read path=".awa/.agent/schemas/EXAMPLES.schema.md" required="true" error="on not found" />
- <read path=".awa/.agent/schemas/REQ.schema.md" required="true" error="on not found" />
- <read path=".awa/.agent/schemas/DESIGN.schema.md" required="true" error="on not found" />
- <read path=".awa/.agent/schemas/TASK.schema.md" required="true" error="on not found" />
- <read path=".awa/.agent/schemas/PLAN.schema.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/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" />
+ <read path=".awa/.agent/schemas/PLAN.schema.yaml" required="true" error="on not found" />
+ <read path=".awa/.agent/schemas/ALIGN_REPORT.schema.yaml" required="true" error="on not found" />
 </tool>
 
 ## User Input
@@ -33,6 +34,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 <file type="api" path=".awa/specs/API-{CODE}-{feature-name}.md" required="if exists" />
 <file type="tasks" path=".awa/tasks/TASK-{CODE}-{feature-name}-{nnn}.md" required="if exists" />
 <file type="plan" path=".awa/plans/PLAN-{nnn}-{plan-name}.md" required="if exists" />
+<file type="align_report" path=".awa/alignment/ALIGN-{x}-WITH-{y}-{nnn}.md" required="if exists" />
 <file type="code" required="if relevant" />
 
 
@@ -41,11 +43,10 @@ You **MUST** consider the user input before proceeding (if not empty).
 Upgrade the specified specs to conform to their schemas and traceability rules.
 
 1) ORIENT: Confirm which artifacts to upgrade; clarify missing targets.
-2) AUDIT: Compare each document to its schema; rely on the schema for section structure, required/optional fields, and prohibited patterns.
-3) ALIGN: Update IDs and code refs to match schema patterns and current agent/code context (requirements, criteria, properties, tasks, components, trace markers). Adjust content to satisfy schema expectations.
-4) TRACEABILITY: Preserve and update code ref markers and any trace matrices when IDs change.
-5) VALIDATE: Re-scan against schemas; avoid empty placeholders; keep files under 500 lines.
-6) REPORT: Summarize changes and remaining questions before finalizing.
+2) CHECK: Run `awa check` in the terminal to identify schema violations and traceability errors across all target files. Parse the output to build a list of findings to fix.
+3) FIX: For each reported error, edit the file to resolve the violation — fix section structure, heading levels, missing required content, prohibited patterns, and broken trace IDs.
+4) RECHECK: Run `awa check` again to verify all errors are resolved. Repeat FIX → RECHECK until the check passes cleanly (warnings and info findings are acceptable).
+5) REPORT: Summarize changes and remaining questions before finalizing.
 
 ## Outputs
 

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

@@ -0,0 +1,265 @@
+# awa — Agent Workflow for AIs
+
+## What awa Is
+
+awa is a CLI tool and structured development workflow for AI-assisted coding. It generates agent configuration files from templates and defines a spec-driven development process with full traceability from requirements through code and tests.
+
+Key concepts:
+
+- **Templates**: Eta-based templates that produce agent config files (`.github/agents/`, `.claude/`, etc.) with conditional output via feature flags
+- **Workflow**: A structured pipeline from architecture through implementation, where every artifact traces to its origin
+- **Traceability**: Code markers (`@awa-impl`, `@awa-test`, `@awa-component`) link source code and tests back to requirements and design
+- **Validation**: `awa check` verifies that all markers resolve to spec IDs and that spec files conform to YAML schemas
+
+## The `.awa/` Directory
+
+All spec artifacts live in `.awa/`:
+
+    .awa/
+    ├── .agent/
+    │   ├── awa.core.md                    # Core system prompt (always read first)
+    │   └── schemas/
+    │       ├── ARCHITECTURE.schema.yaml
+    │       ├── FEAT.schema.yaml
+    │       ├── EXAMPLES.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                # System overview
+    │   ├── FEAT-{CODE}-*.md               # Feature context and motivation
+    │   ├── EXAMPLES-{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
+    ├── tasks/
+    │   └── TASK-{CODE}-*-{nnn}.md         # Implementation steps
+    ├── plans/
+    │   └── PLAN-{nnn}-*.md                # Ad-hoc plans
+    ├── align/
+    │   └── ALIGN-{x}-WITH-{y}-{nnn}.md   # Alignment reports
+    └── rules/
+        └── *.md                           # Project-specific rules
+
+## Workflow Stages
+
+    ARCHITECTURE → FEAT → REQUIREMENTS → DESIGN → TASKS → CODE & TESTS → DOCUMENTATION
+
+| Stage | Artifact | Purpose |
+|-------|----------|---------|
+| Architecture | `ARCHITECTURE.md` | System overview, components, constraints |
+| Feature | `FEAT-{CODE}-*.md` | Context, motivation, scenarios |
+| Requirements | `REQ-{CODE}-*.md` | What must be built (EARS/INCOSE format) |
+| Design | `DESIGN-{CODE}-*.md` | How it gets built — components, interfaces, properties |
+| Tasks | `TASK-{CODE}-*-{nnn}.md` | Step-by-step implementation work items |
+| 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.
+
+The workflow is flexible. Start top-down (architecture → code), bottom-up (code → extract requirements), or lateral (docs, refactors, ad-hoc plans).
+
+## Traceability Chain
+
+IDs and markers create explicit links between artifacts:
+
+    REQ-{CODE}-*.md
+      └── {CODE}-{n}: Requirement title
+            └── {CODE}-{n}_AC-{m}: Acceptance criterion
+                    │
+                    ▼
+    DESIGN-{CODE}-*.md
+      └── {CODE}-ComponentName
+            ├── IMPLEMENTS: {CODE}-{n}_AC-{m}
+            └── {CODE}_P-{n}: Correctness property
+                    │
+                    ▼
+    Source code
+      └── // @awa-component: {CODE}-ComponentName
+          └── // @awa-impl: {CODE}-{n}_AC-{m}
+                    │
+                    ▼
+    Tests
+      ├── // @awa-test: {CODE}_P-{n}          ← verifies property
+      └── // @awa-test: {CODE}-{n}_AC-{m}     ← verifies AC
+
+ID formats:
+
+- `{CODE}-{n}` — requirement (e.g. `DIFF-1`)
+- `{CODE}-{n}.{p}` — subrequirement (e.g. `DIFF-1.1`)
+- `{CODE}-{n}[.{p}]_AC-{m}` — acceptance criterion (e.g. `DIFF-1_AC-1`)
+- `{CODE}_P-{n}` — correctness property (e.g. `DIFF_P-2`)
+
+## CLI Commands
+
+awa may be installed locally. Detect the package manager 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>
+
+### awa init [output] / awa generate [output]
+
+Generate configuration files from templates. `init` and `generate` are aliases.
+
+| Option | Description |
+|--------|-------------|
+| `[output]` | Output directory (positional, optional if set in config) |
+| `-t, --template <source>` | Template source — local path or Git repo |
+| `-f, --features <flag...>` | Feature flags (repeatable) |
+| `--preset <name...>` | Preset names to enable (repeatable) |
+| `--remove-features <flag...>` | Feature flags to remove (repeatable) |
+| `--force` | Overwrite existing files without prompting |
+| `--dry-run` | Preview changes without modifying files |
+| `--delete` | Enable deletion of files listed in template |
+| `-c, --config <path>` | Path to configuration file |
+| `--refresh` | Force re-fetch of cached Git templates |
+| `--all` | Process all named targets from config |
+| `--target <name>` | Process a specific named target |
+| `--overlay <path...>` | Overlay directory paths (repeatable) |
+| `--json` | JSON output to stdout (implies --dry-run) |
+| `--summary` | Compact one-line counts summary |
+
+### awa diff [target]
+
+Compare generated template output against an existing target directory. Exit code 0 = match, 1 = differences.
+
+| Option | Description |
+|--------|-------------|
+| `[target]` | Target directory (positional, optional if set in config) |
+| `-t, --template <source>` | Template source — local path or Git repo |
+| `-f, --features <flag...>` | Feature flags (repeatable) |
+| `--preset <name...>` | Preset names to enable (repeatable) |
+| `--remove-features <flag...>` | Feature flags to remove (repeatable) |
+| `-c, --config <path>` | Path to configuration file |
+| `--refresh` | Force re-fetch of cached Git templates |
+| `--list-unknown` | Include files in target not present in templates |
+| `--all` | Process all named targets from config |
+| `--target <name>` | Process a specific named target |
+| `-w, --watch` | Watch template directory and re-diff on change |
+| `--overlay <path...>` | Overlay directory paths (repeatable) |
+| `--json` | JSON output to stdout |
+| `--summary` | Compact one-line counts summary |
+
+### awa check
+
+Check traceability chain integrity and spec schema conformance. Exit code 0 = clean, 1 = errors.
+
+| Option | Description |
+|--------|-------------|
+| `-c, --config <path>` | Path to configuration file |
+| `--ignore <pattern...>` | Glob patterns to exclude (repeatable, appends to config) |
+| `--format <format>` | Output format: `text` (default) or `json` |
+| `--allow-warnings` | Allow warnings without failing |
+| `--spec-only` | Run only spec-level checks; skip code-to-spec traceability |
+
+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`.
+
+### awa test
+
+Run template test fixtures. Exit code 0 = all pass, 1 = failures.
+
+| Option | Description |
+|--------|-------------|
+| `-t, --template <source>` | Template source — local path or Git repo |
+| `-c, --config <path>` | Path to configuration file |
+| `--update-snapshots` | Update stored snapshots with current output |
+
+Discovers `*.toml` fixtures in `_tests/`, renders per fixture, verifies expected files, compares against snapshots.
+
+### awa features
+
+Discover feature flags available in a template.
+
+| Option | Description |
+|--------|-------------|
+| `-t, --template <source>` | Template source — local path or Git repo |
+| `-c, --config <path>` | Path to configuration file |
+| `--refresh` | Force re-fetch of cached Git templates |
+| `--json` | JSON output |
+
+### Global Options
+
+`-v, --version` — display version. `-h, --help` — display help.
+
+## Configuration — `.awa.toml`
+
+Create `.awa.toml` in the project root. CLI arguments always override config values.
+
+    # Root options
+    output = ".github/agents"
+    template = "owner/repo"
+    features = ["copilot", "claude"]
+    overlay = ["./overlays/company", "./overlays/project"]
+    refresh = false
+    delete = false
+
+    # Named presets — expand into feature flags
+    [presets]
+    full = ["copilot", "claude", "cursor", "windsurf", "kilocode", "opencode", "gemini", "roo", "qwen", "codex", "agy", "agents-md"]
+    lite = ["copilot", "claude"]
+
+    # Per-agent targets — generate different configs in one command
+    [targets.claude]
+    output = "."
+    features = ["claude", "architect", "code"]
+
+    [targets.copilot]
+    output = "."
+    features = ["copilot", "code", "vibe"]
+
+    # Traceability check configuration
+    [check]
+    spec-globs = [".awa/specs/**/*.md"]
+    code-globs = ["src/**/*.{ts,js,tsx,jsx}"]
+    markers = ["@awa-impl", "@awa-test", "@awa-component"]
+    ignore = ["node_modules/**", "dist/**"]
+    ignore-markers = []
+    format = "text"
+    schema-dir = ".awa/.agent/schemas"
+    schema-enabled = true
+    allow-warnings = false
+    spec-only = false
+
+    # Update check configuration
+    [update-check]
+    enabled = true        # set to false to disable update checks
+    interval = 86400      # seconds between checks (default: 1 day)
+
+Target fields: `output`, `template`, `features`, `preset`, `remove-features`. Boolean flags (`force`, `dry-run`, `delete`, `refresh`) apply globally. Target features replace root features entirely.
+
+Feature resolution order: start with `--features`, expand `--preset` (append, deduplicate), remove `--remove-features`.
+
+Multi-target usage:
+
+    awa generate --all                  # process all targets
+    awa generate --target claude        # process one target
+    awa diff --all                      # diff all targets
+
+## Template Sources
+
+Templates can be a local path or a Git repository:
+
+- Local path: `./templates/awa`
+- GitHub shorthand: `owner/repo`
+- Full URL: `https://github.com/owner/repo`
+- SSH: `git@github.com:owner/repo`
+- With subdirectory: `owner/repo/path/to/templates`
+- With ref: `owner/repo#branch`, `owner/repo#v1.0.0`
+
+Git templates are cached in `~/.cache/awa/templates/`. Use `--refresh` to re-fetch.
+
+## Exit Codes
+
+| Command | 0 | 1 | 2 |
+|---------|---|---|---|
+| `awa init` / `awa generate` | Success | — | Internal error |
+| `awa diff` | All files match | Differences found | Internal error |
+| `awa check` | All checks pass | Errors found | Internal error |
+| `awa test` | All fixtures pass | Failures found | Internal error |
+| `awa features` | Success | Error | — |

package/templates/awa/_tests/claude.toml

@@ -0,0 +1,7 @@
+features = ["claude"]
+expected-files = [
+  "CLAUDE.md",
+  ".claude/agents/awa.md",
+  ".claude/skills/awa-code/SKILL.md",
+  ".awa/.agent/awa.core.md",
+]

package/templates/awa/_tests/copilot.toml

@@ -0,0 +1,6 @@
+features = ["copilot"]
+expected-files = [
+  ".github/agents/awa.agent.md",
+  ".github/skills/awa-code/SKILL.md",
+  ".awa/.agent/awa.core.md",
+]

package/templates/awa/.agent/skills/awa-validate-alignment/SKILL.md

@@ -1,3 +0,0 @@
-<% if (it.features.includes('agy')) { %>
-<%~ include('_partials/_skill.awa-validate-alignment.md', it) %>
-<% } %>

package/templates/awa/.agent/workflows/awa-validate-alignment.md

@@ -1,3 +0,0 @@
-<% if (it.features.includes('agy')) { %>
-<%~ include('_partials/_cmd.awa-validate-alignment.md', it) %>
-<% } %>

package/templates/awa/.agents/skills/awa-validate-alignment/SKILL.md

@@ -1,3 +0,0 @@
-<% if (it.features.includes('codex')) { %>
-<%~ include('_partials/_skill.awa-validate-alignment.md', it) %>
-<% } %>