@ncoderz/awa 1.7.2 → 1.8.0

package/templates/awa/_tests/claude/.claude/skills/awa-tasks/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: awa-tasks
+description: Create or update task list documents. Use this when asked to create tasks, generate implementation steps, or break down requirements and designs into work items.
+---
+
+# Create or Update Task List(s)
+
+## 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" />
+ <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
+
+```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-{CODE}-{feature-name}.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" />
+
+## Action
+
+Update or create the task list document(s) as specified in the instruction above, following awa conventions.
+
+## Process
+
+1. PARSE REQ
+   - Extract requirements ({CODE}-{n}) with priorities (must/should/could)
+   - Extract acceptance criteria ({CODE}-{n}[.{p}]_AC-{m}) with types
+   - Note dependencies between requirements
+   - Identify testable criteria
+
+2. PARSE DESIGN
+   - Extract components ({CODE}-{ComponentName}) and interfaces
+   - Map IMPLEMENTS references (component → ACs)
+   - Extract properties ({CODE}_P-{n}) and VALIDATES references
+   - Note architectural decisions and constraints
+   - Extract error types for error handling tasks
+
+3. IF ARCH PROVIDED
+   - Extract project structure for file paths
+   - Extract technology stack for setup tasks
+   - Note architectural rules as constraints
+
+4. GENERATE TASKS
+   - Phase 1: Setup (project initialization, dependencies)
+   - Phase 2: Foundation (shared types, core interfaces, error types)
+   - Phase 3+: One phase per requirement (priority order: must → should → could)
+   - Final Phase: Integration and polish
+   - Include test tasks based on properties and ACs
+
+5. VALIDATE
+   - Every AC has at least one implementing task
+   - Every P has a test task
+   - No orphan tasks (all trace to AC or P)
+   - Dependencies respect component order from DESIGN
+
+## Task Organization
+
+### From Requirements
+
+- Each requirement ({CODE}-{n}) becomes a phase (priority order)
+- All ACs for that requirement → tasks within its phase
+- Subrequirements ({CODE}-{n}.{p}) nest under parent phase
+
+### From Design Components
+
+- Each component → one or more implementation tasks
+- Component's IMPLEMENTS list → task's IMPLEMENTS line
+- Component interface → task description specifics
+
+### From Properties
+
+- Each property ({CODE}_P-{n}) → test task
+- Property's VALIDATES list → determines test assertions
+- Property type determines test approach:
+  - Invariants → property-based tests
+  - Specific behaviors → example-based tests
+
+### From Error Types
+
+- Each error type → error handling task in Foundation phase
+- Error variants → validation tasks in relevant requirement phases
+
+## Phase Structure
+
+### Phase 1: Setup
+
+- Project initialization
+- Dependency installation
+- Configuration scaffolding
+- No requirement labels, no IMPLEMENTS lines
+
+### Phase 2: Foundation
+
+- Core types from DESIGN dataModels
+- Error types from DESIGN errorHandling
+- Shared interfaces
+- No requirement labels, IMPLEMENTS only if AC covers foundation
+
+### Phase 3+: Requirements (priority order)
+
+Within each requirement phase:
+1. Types/models specific to this requirement
+2. Implementation tasks (component by component)
+3. Test tasks (properties first, then direct AC tests)
+
+Each phase should be independently testable after completion.
+
+### Final Phase: Polish
+
+- Integration tests across requirements
+- Cross-cutting concerns
+- No requirement labels
+
+### Documentation Phase
+
+- Documentation update tasks for any changed user-facing behavior, CLI, API, or configuration
+- If no user-facing changes, include a single task: "No doc changes — internal only"
+- No requirement labels, no IMPLEMENTS lines
+
+## Validation Checklist
+
+Before output, verify:
+
+- [ ] Every task has correct format (checkbox, ID, description, path)
+- [ ] Every AC appears in at least one IMPLEMENTS line
+- [ ] Every P appears in at least one TESTS line
+- [ ] Requirement labels only on requirement phase tasks
+- [ ] [P] markers only where truly parallelizable
+- [ ] Dependencies match DESIGN component order
+- [ ] Each requirement phase has clear test criteria
+- [ ] Trace summary accounts for all ACs and Ps
+- [ ] Documentation phase present with doc update tasks or explicit "no changes" task
+
+## Outputs
+
+<file path=".awa/tasks/TASK-{CODE}-{feature-name}-{nnn}.md" />
+
+## Rules
+
+You SHALL clarify open points with user.
+You MAY use todos and tools as needed.

package/templates/awa/_tests/claude/.claude/skills/awa-upgrade/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: awa-upgrade
+description: Upgrade specs to match current schemas. Use this when asked to upgrade, migrate, or update specification documents to conform to schema changes.
+---
+
+# Upgrade Specs to Current Schemas
+
+## 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" />
+ <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/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" />
+ <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
+
+```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-{CODE}-{feature-name}.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" />
+<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" />
+
+
+## Action
+
+Upgrade the specified specs to conform to their schemas and traceability rules.
+
+1) ORIENT: Confirm which artifacts to upgrade; clarify missing targets.
+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
+
+- Updated spec(s) and supporting templates (as applicable)
+
+## Rules
+
+You SHALL avoid destructive edits; propose clarifications when unsure.
+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 file line-limits; split logically if needed.
+You MAY use todos and tools as needed.

package/templates/awa/_tests/claude/.claude/skills/awa-usage/SKILL.md

@@ -0,0 +1,368 @@
+---
+name: awa-usage
+description: Understand awa, its CLI, and configuration. Use this when asked about awa itself, how to use it, or how to configure it.
+---
+
+# 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
+    │       ├── 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                # System overview
+    │   ├── FEAT-{CODE}-*.md               # Feature context and motivation
+    │   ├── 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
+    ├── 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): 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).
+
+## 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 template generate [output]
+
+Generate configuration files from templates. `init` is a top-level convenience command equivalent to `awa template generate`.
+
+| 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-targets` | Process all named targets from config |
+| `--target <name>` | Process a specific named target |
+| `--overlay <path...>` | Overlay directory paths (repeatable) |
+| `--json` | Output results as JSON (implies --dry-run) |
+| `--summary` | Compact one-line counts summary |
+
+### awa template 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-targets` | 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` | Output results as JSON |
+| `--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 |
+| `--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 |
+
+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
+
+Navigate the traceability chain and assemble context from specs, code, and tests. Use this to gather focused context before implementing, refactoring, or reviewing.
+
+    awa trace [ids...] [options]
+
+| Option | Description |
+|--------|-------------|
+| `[ids...]` | Traceability ID(s) to trace (e.g. `FEAT-1`, `FEAT-1_AC-2`, `FEAT_P-3`) |
+| `--all` | Trace all known IDs in the project |
+| `--scope <code>` | Limit results to a feature code (e.g. `--scope FEAT`) |
+| `--file <path>` | Resolve IDs from a source file's markers — useful to understand a file's spec connections before changing it |
+| `--task <path>` | Resolve IDs from a task file |
+| `--content` | Output actual file sections instead of locations |
+| `--list` | Output file paths only |
+| `--direction <dir>` | Traversal direction: `both` (default), `forward`, `reverse` |
+| `--depth <n>` | Maximum traversal depth |
+| `--no-code` | Exclude source code (spec-only context) |
+| `--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 |
+| `-c, --config <path>` | Path to configuration file |
+
+Scans specs and code for traceability IDs, builds a renumber map that closes gaps (e.g. 1, 3, 5 → 1, 2, 3), and propagates all ID changes across spec files, source code, and tests.
+
+### 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 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
+
+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 |
+| `--refresh` | Force re-fetch of cached Git templates |
+| `--overlay <path...>` | Overlay directory paths (repeatable) |
+| `--json` | Output results as JSON |
+| `--summary` | Compact one-line counts summary |
+
+Discovers `*.toml` fixtures in `_tests/`, renders per fixture, verifies expected files, compares against snapshots.
+
+### awa template 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 |
+| `--overlay <path...>` | Overlay directory paths (repeatable) |
+| `--json` | Output results as JSON |
+| `--summary` | Compact one-line counts summary |
+
+### 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"]
+    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
+    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 template generate --all-targets           # process all targets
+    awa template generate --target claude        # process one target
+    awa template diff --all-targets              # 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 template generate` | Success | — | Internal error |
+| `awa template diff` | All files match | Differences found | Internal error |
+| `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/_tests/claude/.claude/skills/awa-vibe/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: awa-vibe
+description: Implement an idea from start to finish using the full awa workflow. Use this when asked to take an idea through the complete development cycle.
+---
+
+# Vibe: Idea to Implementation
+
+## 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="if exists" />
+</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-{CODE}-{feature-name}.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" />
+<file type="tasks" path=".awa/tasks/TASK-{CODE}-{feature-name}-{nnn}.md" required="if relevant" />
+<file type="code" required="if relevant" />
+
+## Action
+
+Take an idea from concept to working implementation, flowing through the awa workflow in the standard direction.
+
+## Process
+
+1. UNDERSTAND: Clarify idea, scope, constraints. Determine starting point.
+2. Flow through stages, creating/updating specs as needed
+3. Checkpoint at each transition: confirm direction with user
+4. Implement code with traceability, write tests
+5. Verify all acceptance criteria satisfied
+
+## Checkpoints
+
+Pause at each stage transition unless user requests autonomous mode:
+- "Architecture defined. Proceed to feature context?"
+- "Feature context captured. Proceed to requirements?"
+- "Requirements captured. Proceed to design?"
+- "Design complete. Proceed to implementation?"
+- "Implementation complete. Update documentation?"
+
+## Outputs
+
+- Specs as needed (ARCHITECTURE, FEAT, REQ, DESIGN, TASK)
+- Implemented code with traceability markers
+- Tests covering acceptance criteria
+- Updated documentation if user-facing behavior changed
+
+## Rules
+
+You SHALL flow through stages in order, skipping only what exists or isn't needed.
+You SHALL pause at checkpoints unless user requests autonomous mode.
+You SHALL maintain traceability throughout.
+You SHOULD keep each stage minimal; avoid overengineering.
+You SHOULD ask clarifying questions early, not mid-implementation.
+You MAY collapse stages for trivial changes.
+You SHALL update user-facing documentation when implementation changes user-facing behavior, CLI, API, or configuration.
+You MAY use todos and tools as needed.