@ncoderz/awa 1.0.0 → 1.2.0

package/templates/awa/.awa/.agent/schemas/DESIGN.schema.yaml

@@ -0,0 +1,361 @@
+# Structural rules for DESIGN-{CODE}-{feature-name}.md files
+target-files: ".awa/specs/DESIGN-*.md"
+description: >
+  Design specification describing HOW to implement requirements (not WHAT).
+  Succinct language. Do not overspecify. Omit irrelevant information.
+  Each component has a name ({CODE}-{ComponentName}), description, IMPLEMENTS
+  trace, and interface code block. Correctness properties use {CODE}_P-{n} IDs
+  and link back to requirements via VALIDATES.
+line-limit: 500
+
+sections:
+  # Top-level heading: "Design Specification"
+  - heading: "Design Specification"
+    level: 1
+    required: true
+    description: "Document title. No metadata in this section."
+
+  # Overview section
+  - heading: "Overview"
+    level: 2
+    required: true
+    description: >
+      Technical approach and rationale. Reference REQ document, do not restate
+      requirements. Explain the design strategy and why it was chosen.
+
+  # Architecture section
+  - heading: "Architecture"
+    level: 2
+    required: true
+    description: >
+      System architecture with diagram, module layout, and key decisions.
+      Optional AFFECTED LAYERS line listing impacted layers.
+    children:
+      - heading: "High-Level Architecture"
+        level: 3
+        required: true
+        description: >
+          Description of the architecture with a mermaid diagram showing
+          components, data flow, and dependencies.
+        contains:
+          - code-block: true
+            label: "architecture diagram (mermaid)"
+            description: "Mermaid diagram (flowchart, sequence, etc.) showing architecture."
+      - heading: "Module Organization"
+        level: 3
+        required: true
+        description: "Directory tree showing file/module layout."
+        contains:
+          - code-block: true
+            label: "directory structure"
+            description: "Code block with directory tree (no mermaid, plain text tree)."
+      - heading: "Architectural Decisions"
+        level: 3
+        description: >
+          Key design decisions with rationale. Format:
+          - DECISION: rationale. Alternatives: alt1, alt2
+
+  # Components and Interfaces section
+  - heading: "Components and Interfaces"
+    level: 2
+    required: true
+    description: >
+      One H3 per component. Each component describes HOW it works (not WHAT),
+      lists which ACs it implements, and provides a code interface.
+    children:
+      - heading: ".*"
+        level: 3
+        repeatable: true
+        required: true
+        description: >
+          Component heading: ### {CODE}-{ComponentName}
+          Name pattern: {CODE}-{ComponentName} (e.g., CFG-ConfigLoader, CLI-Parser).
+          Must describe HOW the component works, include IMPLEMENTS trace, and
+          provide an interface code block.
+        contains:
+          - pattern: "IMPLEMENTS:"
+            label: "IMPLEMENTS trace line"
+            description: >
+              IMPLEMENTS: {CODE}-{n}[.{p}]_AC-{m}, ... — comma-separated list of
+              acceptance criteria this component implements.
+          - code-block: true
+            label: "interface definition"
+            description: "TypeScript/language interface showing the component's public API."
+
+  # Data Models section
+  - heading: "Data Models"
+    level: 2
+    required: true
+    description: >
+      Core types, entities, and data structures grouped by H3 subsection.
+      Each subsection contains named types (CAPITALS) with descriptions
+      and optional code blocks.
+    children:
+      - heading: ".*"
+        level: 3
+        repeatable: true
+        required: true
+        description: >
+          Data model group (e.g., ### Core Types, ### API Types).
+          Contains bullet list of named types in CAPITALS with descriptions,
+          and optional code blocks with type definitions.
+
+  # Correctness Properties section
+  - heading: "Correctness Properties"
+    level: 2
+    required: true
+    description: >
+      Formal invariants for property-based testing. Each property has an ID
+      ({CODE}_P-{n}), a short name in brackets, a description, and VALIDATES
+      trace back to ACs or requirements. Format:
+      - {CODE}_P-{n} [{ShortName}]: {one-line description}
+        VALIDATES: {CODE}-{n}[.{p}]_AC-{m}, ...
+      The [{ShortName}] is required and names the invariant (e.g., [CLI Override]).
+    contains:
+      - pattern: "_P-\\d+"
+        label: "property ID"
+        description: "Property ID in {CODE}_P-{n} format (e.g., CFG_P-1, GEN_P-2)."
+      - pattern: "VALIDATES:"
+        label: "VALIDATES trace line"
+        description: "VALIDATES: comma-separated list of AC or REQ IDs this property validates."
+
+  # Error Handling section
+  - heading: "Error Handling"
+    level: 2
+    required: true
+    description: >
+      Error types with named variants, and a Strategy subsection with PRINCIPLES.
+      Each error type is an H3 with variant bullet list, followed by ### Strategy.
+    children:
+      - heading: ".*"
+        level: 3
+        repeatable: true
+        description: >
+          Error type heading. Format: ### {ErrorTypeName}
+          Followed by a sentence describing the error category, then a bullet list
+          of named variants: - VARIANT_NAME: description.
+      - heading: "Strategy"
+        level: 3
+        required: true
+        description: "Error handling strategy with PRINCIPLES bullet list."
+        contains:
+          - pattern: "PRINCIPLES"
+            label: "PRINCIPLES keyword"
+            description: "The Strategy subsection must contain a PRINCIPLES bullet list."
+
+  # Testing Strategy section
+  - heading: "Testing Strategy"
+    level: 2
+    required: true
+    description: >
+      Testing approach with subsections for property-based testing (required),
+      unit testing, and integration testing.
+    children:
+      - heading: "Property-Based Testing"
+        level: 3
+        required: true
+        description: >
+          Defines the property testing framework, minimum iterations, tag format,
+          and example test code blocks. Format:
+          - FRAMEWORK: {name}
+          - MINIMUM_ITERATIONS: {number}
+          - TAG_FORMAT: @awa-test: {CODE}_P-{n}
+      - heading: "Unit Testing"
+        level: 3
+        description: "Unit testing strategy with AREAS list."
+      - heading: "Integration Testing"
+        level: 3
+        description: "Integration testing strategy with SCENARIOS list."
+
+  # Requirements Traceability section
+  - heading: "Requirements Traceability"
+    level: 2
+    required: true
+    description: >
+      Trace matrix grouped by source REQ file. Each H3 is a REQ file path,
+      containing bullet list entries mapping ACs to components and properties.
+      Format per entry: - {CODE}-{n}[.{p}]_AC-{m} → {CODE}-{ComponentName} ({CODE}_P-{n}) [{status}] {notes}
+    children:
+      - heading: ".*"
+        level: 3
+        repeatable: true
+        required: true
+        description: >
+          Source REQ file heading. Format: ### REQ-{CODE}-{feature}.md
+          Followed by bullet list of trace entries from that file.
+          Each entry: - {AC-ID} → {Component} ({Property}) [{status}] {notes}
+          Omit [{status}] if implemented. Omit ({Property}) if none.
+
+  # Library Usage section (optional)
+  - heading: "Library Usage"
+    level: 2
+    description: >
+      Framework features and external libraries used. Subsections:
+      ### Framework Features — - FEATURE: usage
+      ### External Libraries — - name (version): purpose
+    children:
+      - heading: "Framework Features"
+        level: 3
+        description: "Framework features used. Format: - FEATURE: usage description."
+      - heading: "External Libraries"
+        level: 3
+        description: "External libraries used. Format: - name (version): purpose."
+
+  # Change Log section (optional)
+  - heading: "Change Log"
+    level: 2
+    description: "Version history. Format: - {version} ({date}): {changes}"
+
+sections-prohibited:
+  - "**"
+  - "~~"
+
+example: |
+  # Design Specification
+
+  ## Overview
+
+  This design implements a CLI pipeline architecture for template-based code generation. The pipeline flows through argument parsing, configuration loading, template resolution, rendering, and file output with conflict resolution.
+
+  ## Architecture
+
+  AFFECTED LAYERS: CLI Layer, Core Engine, I/O Layer
+
+  ### High-Level Architecture
+
+  Sequential pipeline for predictable flow and error handling.
+
+  ```mermaid
+  flowchart LR
+      Args[CLI Args] --> Parser
+      Config[.awa.toml] --> ConfigLoader
+      Parser --> ConfigLoader
+      ConfigLoader --> Engine[TemplateEngine]
+      Engine --> Generator[FileGenerator]
+      Generator --> Files[Output]
+  ```
+
+  ### Module Organization
+
+  ```
+  src/
+  ├── cli/
+  │   └── index.ts
+  ├── core/
+  │   ├── config.ts
+  │   ├── template.ts
+  │   └── generator.ts
+  └── utils/
+      └── fs.ts
+  ```
+
+  ### Architectural Decisions
+
+  - PIPELINE OVER EVENT: Sequential pipeline for predictable flow and error handling. Alternatives: event-driven, middleware chain
+
+  ## Components and Interfaces
+
+  ### CFG-ConfigLoader
+
+  Loads TOML configuration from file, merges with CLI arguments (CLI wins), and produces resolved options with defaults applied.
+
+  IMPLEMENTS: CFG-1_AC-1, CFG-1_AC-2, CFG-4_AC-1
+
+  ```typescript
+  interface ConfigLoader {
+    load(configPath: string | null): Promise<FileConfig | null>;
+    merge(cli: RawCliOptions, file: FileConfig | null): ResolvedOptions;
+  }
+  ```
+
+  ## Data Models
+
+  ### Core Types
+
+  - RESOLVED_OPTIONS: Fully resolved configuration with all defaults applied
+
+  ```typescript
+  interface ResolvedOptions {
+    readonly output: string;
+    readonly template: string | null;
+    readonly features: readonly string[];
+    readonly force: boolean;
+  }
+  ```
+
+  ## Correctness Properties
+
+  - CFG_P-1 [CLI Override]: CLI arguments always override config file values for the same option
+    VALIDATES: CFG-4_AC-1, CFG-4_AC-2
+
+  - GEN_P-2 [Dry Run Immutable]: Dry-run mode never modifies the file system
+    VALIDATES: GEN-6_AC-1, GEN-6_AC-2
+
+  ## Error Handling
+
+  ### ConfigError
+
+  Configuration loading and parsing errors
+
+  - FILE_NOT_FOUND: Config file does not exist when --config provided
+  - PARSE_ERROR: TOML syntax error with line number
+
+  ### Strategy
+
+  PRINCIPLES:
+
+  - Fail fast on first error
+  - Provide actionable error messages with file paths
+  - Exit with non-zero code on any error
+
+  ## Testing Strategy
+
+  ### Property-Based Testing
+
+  - FRAMEWORK: fast-check
+  - MINIMUM_ITERATIONS: 100
+  - TAG_FORMAT: @awa-test: {CODE}_P-{n}
+
+  ```typescript
+  // @awa-test: CFG_P-1
+  test.prop([fc.string(), fc.string()])('CLI overrides config', (cliValue, configValue) => {
+    const cli = { output: cliValue };
+    const config = { output: configValue };
+    const result = configLoader.merge(cli, config);
+    expect(result.output).toBe(cliValue);
+  });
+  ```
+
+  ### Unit Testing
+
+  Test individual components in isolation
+
+  - AREAS: CFG-ConfigLoader merge logic, TPL-TemplateResolver type detection
+
+  ## Requirements Traceability
+
+  ### REQ-CFG-config.md
+
+  - CFG-1_AC-1 → CFG-ConfigLoader (CFG_P-1)
+  - CFG-4_AC-1 → CFG-ConfigLoader (CFG_P-1)
+
+  ### REQ-GEN-generator.md
+
+  - GEN-6_AC-1 → GEN-FileGenerator (GEN_P-2) [partial] pending review
+
+  ## Library Usage
+
+  ### Framework Features
+
+  - CITTY: Command definition, argument parsing, help generation
+
+  ### External Libraries
+
+  - citty (latest): CLI framework
+  - smol-toml (1.x): TOML parser
+
+  ## Change Log
+
+  - 1.0.0 (2025-01-10): Initial design
+
+  - 1.0.0 (2025-01-10): Initial design

package/templates/awa/.awa/.agent/schemas/EXAMPLES.schema.yaml

@@ -0,0 +1,98 @@
+# Structural rules for EXAMPLES-{CODE}-{feature-name}-{nnn}.md files
+target-files: ".awa/specs/EXAMPLES-*.md"
+description: >
+  Concrete usage examples for a feature. Detailed, hands-on, reproducible.
+  Use the same {CODE} as the corresponding FEAT/REQ for the feature.
+  Number files sequentially (-001, -002, ...) when splitting at the 500-line limit.
+  Each example must have a title, context, and code/demonstration block.
+  Marked [INFORMATIVE]. Prohibited: normative language (SHALL/SHOULD/MAY),
+  acceptance criteria, traceability IDs, design decisions.
+line-limit: 500
+
+sections:
+  # Top-level heading with INFORMATIVE marker
+  - heading: ".*\\[INFORMATIVE\\]"
+    level: 1
+    required: true
+    description: >
+      Document title including [INFORMATIVE] marker.
+      Format: # Usage Examples: {Feature Name} [INFORMATIVE]
+
+  # Prerequisites section (optional)
+  - heading: "Prerequisites"
+    level: 2
+    description: "Required tools, setup, or prior knowledge before running examples."
+
+  # At least one example heading
+  - heading: "Example \\d+:.*"
+    level: 2
+    required: true
+    repeatable: true
+    description: >
+      Individual example with title, context paragraph, and code block.
+      Format: ## Example N: {Title}
+      Context explaining when to use this and what it demonstrates.
+      Followed by a code or CLI demonstration block.
+      Optional: EXPECTED OUTPUT code block, NOTES bullet list.
+    contains:
+      - code-block: true
+        label: "code or CLI demonstration"
+        description: "Fenced code block with language tag (bash, typescript, etc.)."
+
+  # Change Log section (optional)
+  - heading: "Change Log"
+    level: 2
+    description: "Version history. Format: - {version} ({date}): {changes}"
+
+sections-prohibited:
+  - "SHALL "
+  - "SHOULD "
+  - "MAY "
+  - "**"
+  - "_AC-"
+  - "_P-"
+  - "IMPLEMENTS:"
+  - "VALIDATES:"
+
+example: |
+  # Usage Examples: Template Engine [INFORMATIVE]
+
+  ## Prerequisites
+
+  - Node.js 20 or higher
+  - awa CLI installed globally
+
+  ## Example 1: Basic Generation
+
+  Generate configuration files with default settings.
+
+  ```bash
+  awa generate
+  ```
+
+  EXPECTED OUTPUT:
+
+  ```
+  Created .github/agents/copilot.md
+  Created .github/agents/claude.md
+  ```
+
+  ## Example 2: Feature Flags
+
+  Enable specific features when generating.
+
+  ```bash
+  awa generate --features copilot,claude,cursor
+  ```
+
+  ## Example 3: Custom Template Source
+
+  Use a Git repository as the template source.
+
+  ```bash
+  awa generate --template owner/repo --features copilot
+  ```
+
+  ## Change Log
+
+  - 1.0.0 (2025-01-10): Initial examples

package/templates/awa/.awa/.agent/schemas/FEAT.schema.yaml

@@ -0,0 +1,143 @@
+# Structural rules for FEAT-{CODE}-{feature-name}.md files
+target-files: ".awa/specs/FEAT-*.md"
+description: >
+  Non-normative feature context. Explains WHAT the feature is and WHY it exists,
+  not HOW to implement it. Uses clear, accessible language. Marked [INFORMATIVE]
+  to distinguish from normative REQ/DESIGN documents.
+  Prohibited: normative language (SHALL/SHOULD/MAY), acceptance criteria,
+  traceability IDs, design decisions, bold formatting.
+line-limit: 500
+
+sections:
+  # Top-level heading with INFORMATIVE marker
+  - heading: ".*\\[INFORMATIVE\\]"
+    level: 1
+    required: true
+    description: >
+      Document title including [INFORMATIVE] marker.
+      Format: # Feature Context: {Feature Name} [INFORMATIVE]
+
+  # Problem section
+  - heading: "Problem"
+    level: 2
+    required: true
+    description: >
+      Why this feature exists. What pain point or gap it addresses.
+      Written from the user's perspective.
+
+  # Conceptual Model section
+  - heading: "Conceptual Model"
+    level: 2
+    required: true
+    description: >
+      How users should think about this feature. Mental model, key abstractions,
+      and relationships between concepts. May include diagrams.
+
+  # Scenarios section with repeatable scenario headings
+  - heading: "Scenarios"
+    level: 2
+    required: true
+    description: >
+      Concrete usage narratives illustrating the feature in action. Each
+      scenario describes a realistic user situation and expected outcome.
+    children:
+      - heading: "Scenario \\d+:.*"
+        level: 3
+        repeatable: true
+        required: true
+        description: >
+          Individual scenario. Format: ### Scenario N: {Title}
+          Contains a narrative paragraph describing the user situation.
+
+  # Optional sections
+  - heading: "Background"
+    level: 2
+    description: "Additional context: history, prior art, references."
+
+  - heading: "Glossary"
+    level: 2
+    description: "Domain terms. Format: - TERM: Definition"
+
+  - heading: "Stakeholders"
+    level: 2
+    description: "Roles related to this feature. Format: - ROLE: Relationship"
+
+  - heading: "Diagrams"
+    level: 2
+    description: "Supplementary mermaid diagrams for the conceptual model."
+
+  - heading: "Non-Normative Notes"
+    level: 2
+    description: "Recommendations, best practices, or explanatory content that is not testable."
+
+  - heading: "Change Log"
+    level: 2
+    description: "Version history. Format: - {version} ({date}): {changes}"
+
+sections-prohibited:
+  - "SHALL "
+  - "SHOULD "
+  - "MAY "
+  - "**"
+  - "_AC-"
+  - "_P-"
+  - "IMPLEMENTS:"
+  - "VALIDATES:"
+
+example: |
+  # Template Engine Feature Context [INFORMATIVE]
+
+  ## Problem
+
+  Developers need to generate AI agent configuration files across multiple
+  projects consistently. Manual creation is error-prone, time-consuming, and
+  leads to drift between projects. There is no standard way to conditionally
+  include or exclude configuration sections based on project needs.
+
+  ## Conceptual Model
+
+  The template engine treats configuration files as templates that can be
+  rendered with a set of feature flags. Users think of features as toggles —
+  enable "copilot" to get GitHub Copilot config, enable "claude" for Claude
+  config, etc. The engine resolves which template files to include, renders
+  them with the active feature set, and writes the output.
+
+  Key abstractions:
+  - TEMPLATE: A file with optional Eta expressions
+  - FEATURE FLAG: A named toggle that controls conditional rendering
+  - PARTIAL: A reusable template fragment included by other templates
+  - PRESET: A named bundle of feature flags
+
+  ## Scenarios
+
+  ### Scenario 1: First-time Setup
+
+  A developer starts a new project and wants to add AI agent configuration
+  for GitHub Copilot and Claude. They run `awa generate --features copilot,claude`
+  and get a complete set of configuration files tailored to those two agents.
+
+  ### Scenario 2: Adding a New Agent
+
+  An existing project already has Copilot configuration. The developer adds
+  Cursor support by running `awa generate --features copilot,cursor`. The engine
+  merges the new feature without disrupting existing configuration.
+
+  ### Scenario 3: Previewing Changes
+
+  Before applying changes, the developer runs `awa diff` to see what files
+  would be added, modified, or removed. This gives confidence before committing.
+
+  ## Background
+
+  Prior art includes tools like cookiecutter (Python), degit (JS), and Yeoman.
+  These focus on one-time scaffolding. awa differs by supporting re-generation.
+
+  ## Glossary
+
+  - ETA: The template rendering library used by awa
+  - FEATURE FLAG: A string identifier that enables conditional template content
+  - PARTIAL: A template file prefixed with `_` that can be included by other templates
+
+  ## Change Log
+
+  - 1.0.0 (2025-01-10): Initial feature context