@ncoderz/awa 1.0.0 → 1.1.0

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/_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) %>
-<% } %>

package/templates/awa/.awa/.agent/schemas/ALIGN_REPORT.schema.md

@@ -1,156 +0,0 @@
-<schema target-files=".awa/alignment/ALIGN-{x}-WITH-{y}-{nnn}.md">
-
-<definitions>
-  x = source artifact (what is being validated).
-  y = target artifact (what x is validated against).
-  <severity>
-    CRITICAL: MUST/SHALL violation, security, data integrity
-    MAJOR: SHOULD violation, UX, performance
-    MINOR: MAY not implemented, orphan traces, optional
-    INFO: superset additions, suggestions
-  </severity>
-  <confidence>
-    CERTAIN: explicit trace (IMPLEMENTS, VALIDATES, @awa-*)
-    LIKELY: naming convention or strong inference
-    UNCERTAIN: semantic inference only → flag for human review
-  </confidence>
-  <finding-type>
-    MISSING | DIFFERENCE | CONFLICT | INCOMPLETE | UNTESTED | ORPHAN | SUPERSET
-  </finding-type>
-  <trace_matrix>
-    <trace in="DESIGN component" marker="IMPLEMENTS: {CODE}-{n}[.{p}]_AC-{m}" to="REQ AC" />
-    <trace in="DESIGN property" marker="{CODE}_P-{n} VALIDATES: {CODE}-{n}[.{p}]_AC-{m} | {CODE}-{n}" to="REQ" />
-    <trace in="code" marker="@awa-component: {CODE}-{ComponentName}" to="DESIGN component" />
-    <trace in="code" marker="@awa-impl: {CODE}-{n}[.{p}]_AC-{m}" to="REQ AC" />
-    <trace in="tests" marker="@awa-test: {CODE}_P-{n}" to="DESIGN property" />
-    <trace in="tests" marker="@awa-test: {CODE}-{n}[.{p}]_AC-{m}" to="REQ AC" />
-    <infer target="semantic_traces" when="markers missing" confidence="LIKELY|UNCERTAIN" />
-  </trace_matrix>
-</definitions>
-
-```json
-{
-  "description": "Render as Markdown per $rendering.",
-  "type": "object",
-  "required": ["source", "target", "findings"],
-  "properties": {
-    "source": { "type": "string", "description": "x artifact path or identifier" },
-    "target": { "type": "string", "description": "y artifact path or identifier" },
-    "findings": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["severity", "confidence", "type", "sourceRef", "problem"],
-        "properties": {
-          "severity": { "enum": ["critical", "major", "minor", "info"] },
-          "confidence": { "enum": ["certain", "likely", "uncertain"] },
-          "type": { "enum": ["missing", "difference", "conflict", "incomplete", "superset", "orphan", "untested"] },
-          "sourceRef": {
-            "type": "object",
-            "required": ["location"],
-            "properties": {
-              "location": { "type": "string" },
-              "text": { "type": "string" }
-            }
-          },
-          "targetRef": {
-            "type": "object",
-            "properties": {
-              "location": { "type": "string" },
-              "text": { "type": "string" }
-            }
-          },
-          "problem": { "type": "string" },
-          "traceability": { "enum": ["explicit-implements", "explicit-validates", "explicit-awa-component", "explicit-awa-impl", "explicit-awa-test", "naming", "semantic"], "description": "How the trace was established" },
-          "resolution": { "type": "string" }
-        }
-      }
-    }
-  },
-  "$rendering": {
-    "templates": {
-      "withFindings": [
-        "# ALIGNMENT REPORT",
-        "{source} ↔ {target}",
-        "",
-        "{for each finding: templates.finding}",
-        "",
-        "## Summary",
-        "CRITICAL: {count}",
-        "MAJOR: {count}",
-        "MINOR: {count}",
-        "INFO: {count}",
-        "STATUS: {PASSED ✅ | FAILED ❌}"
-      ],
-      "noFindings": [
-        "# ALIGNMENT REPORT",
-        "{source} ↔ {target}",
-        "All checks passed. No alignment issues found.",
-        "**STATUS: PASSED ✅**"
-      ],
-      "finding": [
-        "- [ ] {n}. {SEVERITY} [{CONFIDENCE}] {TYPE}",
-        "",
-        "  SOURCE: {sourceRef.location}",
-        "  > {sourceRef.text}",
-        "",
-        "  TARGET: {targetRef.location}",
-        "  > {targetRef.text}",
-        "",
-        "  ISSUE: {problem}",
-        "",
-        "  RESOLUTION: {resolution}",
-        "",
-        "  *Traced via: {traceability}*"
-      ]
-    },
-    "statusRules": [
-      "FAILED if any CRITICAL or MAJOR findings",
-      "PASSED otherwise"
-    ],
-    "templateSelection": [
-      "No findings → noFindings",
-      "Findings exist → withFindings"
-    ],
-    "omissionRules": [
-      "Omit source blockquote if sourceRef.text absent",
-      "Omit TARGET: line entirely if targetRef absent → show 'TARGET: (not found)'",
-      "Omit target blockquote if targetRef.text absent",
-      "Omit *Traced via* if traceability starts with 'explicit-'",
-      "Omit RESOLUTION: if resolution absent"
-    ]
-  }
-}
-```
-
-<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 with @awa-impl: WKS-1_AC-1.
-  RESOLUTION: Add @awa-component: WKS-WorkspaceConfig and @awa-impl: WKS-1_AC-1 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<(), ValidationError> but implementation returns bool, losing error context.
-  RESOLUTION: Update validator.rs to return Result<(), ValidationError> as specified in design
-
-## Summary
-
-CRITICAL: 1
-MAJOR: 1
-MINOR: 0
-INFO: 0
-
-STATUS: FAILED ❌
-</example>
-
-</schema>

package/templates/awa/.awa/.agent/schemas/API.schema.md

@@ -1,4 +0,0 @@
-<schema target-files=".awa/specs/API-{api-name}.tsp">
-- You MUST write API specs in TypeSpec format unless requested otherwise.
-- If written in TypeSpec, API specifications follow TypeSpec format conventions.
-</schema>

package/templates/awa/.awa/.agent/schemas/ARCHITECTURE.schema.md

@@ -1,176 +0,0 @@
-<schema target-file=".awa/specs/ARCHITECTURE.md">
-- You MUST write API specs in TypeSpec format unless requested otherwise.
-- If written in TypeSpec, API specifications follow TypeSpec format conventions.
-
-```json
-{
-  "description": "Architecture only. Succinct language. Do not overspecify. Omit irrelevant information.",
-  "required": ["projectPurpose", "systemOverview", "technologyStack", "architectureDiagram", "directoryStructure", "componentDetails", "componentInteractions", "architecturalRules", "developerCommands"],
-  "properties": {
-    "projectPurpose": { "type": "single paragraph: core problem and primary functionality" },
-    "systemOverview": { "type": "array of software layers/subsystems" },
-    "technologyStack": { "type": "array", "items": { "properties": { "technology": { "type": "name with major version only" }, "purpose": {} } } },
-    "architectureDiagram": { "type": "mermaid diagram showing components, data flow, dependencies" },
-    "directoryStructure": { "type": "array", "items": { "properties": { "path": {}, "description": {} } } },
-    "componentDetails": { "type": "array", "items": { "$ref": "#/$defs/component" } },
-    "componentInteractions": {
-      "required": ["description"],
-      "properties": {
-        "description": {},
-        "diagrams": { "type": "array", "items": { "properties": { "title": {}, "mermaid": {} } } }
-      }
-    },
-    "architecturalRules": { "type": "array covering performance, scaling, maintainability, security, testing" },
-    "releaseStatus": { "type": "string: current release phase (e.g., Alpha, Beta, RC, GA) with brief description" },
-    "developerCommands": { "type": "array", "items": { "properties": { "command": {}, "description": {} } } },
-    "metadata": { "properties": { "changeLog": { "type": "array", "items": { "properties": { "version": {}, "date": {}, "changes": {} } } } } }
-  },
-  "$defs": {
-    "component": {
-      "required": ["name", "description", "responsibilities"],
-      "properties": {
-        "name": {},
-        "description": { "type": "single sentence" },
-        "responsibilities": { "type": "array of strings" },
-        "constraints": { "type": "array of strings" }
-      }
-    }
-  },
-  "$render": {
-    "template": "# Architecture\n\n## Project Purpose\n{projectPurpose}\n\n## System Overview\n{systemOverview→'- {}'}\n\n## Technology Stack\n{technologyStack→'- `{technology}` — {purpose}'}\n\n## High-Level Architecture\n```mermaid\n{architectureDiagram}\n```\n\n## Directory Structure\n```\n{directoryStructure→'{path}  # {description}'}\n```\n\n## Component Details\n{componentDetails→'### {name}\n\n{description}\n\nRESPONSIBILITIES\n{responsibilities→\"- {}\"}\n\nCONSTRAINTS\n{constraints?→\"- {}\"}'}\n\n## Component Interactions\n{componentInteractions.description}\n{componentInteractions.diagrams→'### {title}\n```mermaid\n{mermaid}\n```'}\n\n## Architectural Rules\n{architecturalRules→'- {}'}\n\n## Release Status\n{releaseStatus}\n\n## Developer Commands\n{developerCommands→'- `{command}` — {description}'}\n\n## Change Log\n{metadata.changeLog→'- {version} ({date}): {changes}'}",
-    "omit": ["CONSTRAINTS section if empty", "diagrams section if empty"],
-    "prohibited": ["**bold** — use CAPITALS", "minor versions in tech stack (major only)", "non-architecture directories", "detailed implementation in component descriptions"]
-  }
-}
-```
-
-<example>
-# Architecture
-
-## Project Purpose
-
-awa CLI generates AI coding agent configuration files from templates, enabling developers to quickly scaffold consistent agent setups across projects.
-
-## System Overview
-
-- CLI Layer
-- Core Engine
-- Template System
-- I/O Layer
-
-## Technology Stack
-
-- `Node.js 20` — Runtime environment
-- `TypeScript 5` — Type-safe development
-- `Eta 3` — Template rendering
-- `Citty` — CLI framework
-
-## High-Level Architecture
-
-```mermaid
-flowchart LR
-    subgraph Input
-        Args[CLI Args]
-        Config[.awa.toml]
-        Templates[Templates]
-    end
-    subgraph Core
-        Parser[ArgumentParser]
-        Engine[TemplateEngine]
-        Generator[FileGenerator]
-    end
-    subgraph Output
-        Files[Generated Files]
-    end
-    Args --> Parser
-    Config --> Parser
-    Parser --> Engine
-    Templates --> Engine
-    Engine --> Generator
-    Generator --> Files
-```
-
-## Directory Structure
-
-```
-src/           # Source code
-src/cli/       # CLI entry and commands
-src/core/      # Core engine logic
-src/utils/     # Shared utilities
-templates/     # Bundled templates
-```
-
-## Component Details
-
-### CLI Layer
-
-Handles argument parsing and command dispatch.
-
-RESPONSIBILITIES
-
-- Parse CLI arguments and options
-- Load and merge configuration
-- Dispatch to appropriate command handlers
-
-CONSTRAINTS
-
-- Must fail fast on invalid arguments
-- Must support --help and --version
-
-### Template Engine
-
-Renders templates with feature flag context.
-
-RESPONSIBILITIES
-
-- Load templates from local or remote sources
-- Render with Eta templating
-- Detect empty output for conditional file creation
-
-## Component Interactions
-
-The CLI parses arguments, loads configuration, then passes resolved options to the template engine which renders files through the generator.
-
-### Generate Command Flow
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant CLI
-    participant Engine
-    participant Generator
-    User->>CLI: awa generate
-    CLI->>Engine: render(templates, features)
-    Engine->>Generator: write(files)
-    Generator-->>User: Success summary
-```
-
-## Architectural Rules
-
-- All file I/O must go through the I/O layer
-- Core engine must not depend on CLI layer
-- Templates must be stateless and deterministic
-- Errors must provide actionable messages with file paths
-- All public APIs must have TypeScript types
-
-## Release Status
-
-STATUS: Alpha
-
-Core functionality implemented. API may change without notice.
-
-## Developer Commands
-
-- `npm install` — Install dependencies
-- `npm run dev` — Run in development mode
-- `npm test` — Run test suite
-- `npm run lint` — Run linter
-- `npm run build` — Build for production
-
-## Change Log
-
-- 1.0.0 (2025-01-10): Initial architecture
-- 1.1.0 (2025-01-15): Added diff command
-</example>
-
-</schema>