@ncoderz/awa 1.7.1 → 1.8.0

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

@@ -0,0 +1,142 @@
+# 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: 800
+
+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.
+
+  # Scope Boundary section (optional, after Conceptual Model)
+  - heading: "Scope Boundary"
+    level: 2
+    description: >
+      Single sentence defining the feature's scope boundary — what this feature
+      owns and where it ends.
+
+  # 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."
+
+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 template 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 template 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 template 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

package/templates/awa/_tests/copilot/.awa/.agent/schemas/PLAN.schema.yaml

@@ -0,0 +1,146 @@
+# Structural rules for PLAN-{nnn}-{plan-name}.md files
+target-files: ".awa/plans/PLAN-*.md"
+description: >
+  Ad-hoc plan for features, improvements, refactors, or other work.
+  Succinct language. Break down work into actionable steps (checkbox items).
+  Status and direction metadata required. Structure is flexible —
+  organize sections as the plan demands. Plans should not contain significant
+  code (short snippets for explanation are fine).
+  Traceability links to REQ/DESIGN/code/tests are optional but encouraged.
+line-limit: 800
+
+sections:
+  # H1 title with status/direction metadata
+  - heading: ".*"
+    level: 1
+    required: true
+    description: >
+      Plan title. Descriptive but concise (e.g., "Refactor Config Loader",
+      "Add Diff Preview Feature"). Followed immediately by STATUS and
+      DIRECTION metadata lines, and optional TRACEABILITY links.
+    contains:
+      - pattern: "^STATUS:"
+        label: "STATUS declaration"
+        description: >
+          Current plan status. One of: in-progress, completed, blocked.
+          Format: STATUS: in-progress
+      - pattern: "^DIRECTION:"
+        label: "DIRECTION declaration"
+        description: >
+          Workflow direction for this plan. One of: top-down (architecture
+          first), bottom-up (implementation first), lateral (cross-cutting).
+          Format: DIRECTION: top-down
+
+  # Context section (optional)
+  - heading: "Context"
+    level: 2
+    description: >
+      Why this plan exists. What problem or goal it addresses.
+      Brief — one or two paragraphs. Reference FEAT/REQ docs if they exist
+      rather than restating.
+
+  # Steps section (optional — steps may also appear in domain-specific H2s)
+  - heading: "Steps"
+    level: 2
+    description: >
+      Actionable steps as checkbox items. The core of the plan.
+      Format: - [ ] Step description
+      Mark completed steps with [x]. Group with H3 subsections if needed.
+      Each step should be concrete and verifiable.
+
+  # Risks section (optional)
+  - heading: "Risks"
+    level: 2
+    description: >
+      Known risks, unknowns, or potential blockers. Bullet list.
+      Include mitigation strategies where possible.
+
+  # Dependencies section (optional)
+  - heading: "Dependencies"
+    level: 2
+    description: >
+      Prerequisites or upstream work that must complete first.
+      Reference other plans, tasks, or external factors.
+
+  # Completion Criteria section (optional)
+  - heading: "Completion Criteria"
+    level: 2
+    description: >
+      How to know when this plan is done. Concrete, verifiable conditions.
+      Format: - [ ] Criterion description
+
+  # Open Questions section (optional)
+  - heading: "Open Questions"
+    level: 2
+    description: >
+      Unresolved questions needing clarification from the user or team.
+      Format: - [ ] Question (resolved questions marked [x] with answer).
+
+  # References section (optional)
+  - heading: "References"
+    level: 2
+    description: >
+      Links to related artifacts: REQ, DESIGN, TASK, FEAT, code files,
+      external docs. Format: - {artifact}: {path or description}
+
+sections-prohibited:
+  - "**"
+
+example: |
+  # Refactor Config Loader
+
+  STATUS: in-progress
+  DIRECTION: bottom-up
+  TRACEABILITY: REQ-CFG-config.md, DESIGN-CFG-config.md
+
+  ## Context
+
+  The config loader has grown organically and now mixes parsing, validation,
+  and merging in a single function. This makes it hard to test and extend.
+  Split into discrete pipeline stages.
+
+  ## Steps
+
+  - [x] Extract TOML parsing into standalone function
+  - [x] Extract validation into ConfigValidator
+  - [ ] Extract merge logic into ConfigMerger
+  - [ ] Update all call sites to use new pipeline
+  - [ ] Remove old monolithic load function
+
+  ### Testing
+
+  - [ ] Add property tests for ConfigMerger (CLI overrides file)
+  - [ ] Add unit tests for ConfigValidator edge cases
+  - [ ] Verify integration test still passes end-to-end
+
+  ### Documentation
+
+  - [ ] Update docs/configuration.md with new pipeline stages
+  - [ ] No README changes needed (no user-facing behavior change)
+
+  ## Risks
+
+  - Merge logic has implicit ordering assumptions that may break when extracted
+  - Call sites in CLI layer may depend on intermediate state
+
+  ## Dependencies
+
+  - TASK-CFG-config-001.md Phase 3 must be complete (defines the types)
+
+  ## Completion Criteria
+
+  - [ ] All existing tests pass
+  - [ ] New property tests cover merge invariants
+  - [ ] No function exceeds 40 lines
+  - [ ] Config pipeline is documented in DESIGN
+
+  ## Open Questions
+
+  - [x] Should validation happen before or after merge? — After merge (validate final state)
+  - [ ] Do we need a separate error type for merge failures?
+
+  ## References
+
+  - REQ: .awa/specs/REQ-CFG-config.md
+  - DESIGN: .awa/specs/DESIGN-CFG-config.md
+  - Code: src/core/config.ts

package/templates/awa/_tests/copilot/.awa/.agent/schemas/README.schema.yaml

@@ -0,0 +1,137 @@
+# Structural rules for README.md
+target-files: "README.md"
+description: >
+  Project README. Succinct, user-facing language. Link to detailed docs in
+  /docs folder rather than including lengthy content inline. Required sections:
+  title, description, installation, and usage. Keep it concise — the README
+  is the front door, not the whole house.
+line-limit: 800
+
+sections:
+  # Project title (H1)
+  - heading: ".*"
+    level: 1
+    required: true
+    description: >
+      Project name as H1. Optionally followed by badge images and a one-paragraph
+      description of what the project does and why it exists.
+
+  # Features section (optional)
+  - heading: "Features"
+    level: 2
+    description: "Bullet list of key features. Keep to 5-10 items."
+
+  # Installation section
+  - heading: "Installation"
+    level: 2
+    required: true
+    description: >
+      How to install the project. May contain Prerequisites and Install
+      subsections. Include code blocks with shell commands.
+    contains:
+      - code-block: true
+        label: "install command"
+        description: "Shell command(s) to install the project."
+
+  # Usage section
+  - heading: "Usage"
+    level: 2
+    required: true
+    description: >
+      Quick start example showing minimal usage. Include at least one code block.
+      Additional examples can be H3 subsections.
+    contains:
+      - code-block: true
+        label: "usage example"
+        description: "Code block demonstrating basic usage."
+
+  # Documentation section (optional)
+  - heading: "Documentation"
+    level: 2
+    description: >
+      Links to detailed documentation in /docs folder.
+      Format: - [Title](docs/file.md) - Description
+
+  # Contributing section (optional)
+  - heading: "Contributing"
+    level: 2
+    description: "Brief instructions or link to CONTRIBUTING.md."
+
+  # License section (optional)
+  - heading: "License"
+    level: 2
+    description: "License name and link to LICENSE file."
+
+  # Acknowledgments section (optional)
+  - heading: "Acknowledgments"
+    level: 2
+    description: "Credits to libraries, tools, or contributors."
+
+example: |
+  # awa CLI
+
+  [![npm version](https://img.shields.io/npm/v/awa-cli.svg)](https://www.npmjs.com/package/awa-cli)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+  awa CLI generates AI coding agent configuration files from templates, enabling developers to quickly scaffold consistent agent setups across projects.
+
+  ## Features
+
+  - Template-based configuration generation
+  - Feature flag support for conditional content
+  - Multiple output formats (Markdown, YAML, JSON)
+  - Diff mode to preview changes before applying
+  - Local and remote template sources
+
+  ## Installation
+
+  ### Prerequisites
+
+  - Node.js 20 or higher
+  - npm or pnpm
+
+  ### Install
+
+  ```bash
+  npm install -g awa-cli
+  ```
+
+  ## Usage
+
+  ```bash
+  # Generate configuration from default template
+  awa template generate
+
+  # Generate with specific features enabled
+  awa template generate --features typescript,testing
+
+  # Preview changes without writing files
+  awa template diff
+  ```
+
+  ### Examples
+
+  #### Custom Template
+
+  ```bash
+  awa template generate --template ./my-templates --output ./.ai
+  ```
+
+  ## Documentation
+
+  - [Configuration Guide](docs/configuration.md) — Configure templates and options
+  - [Template Authoring](docs/templates.md) — Create custom templates
+  - [CLI Reference](docs/cli-reference.md) — Complete command documentation
+
+  ## Contributing
+
+  See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+  ## License
+
+  [MIT](LICENSE)
+
+  ## Acknowledgments
+
+  - Eta templating engine
+  - Citty CLI framework

package/templates/awa/_tests/copilot/.awa/.agent/schemas/REQ.schema.yaml

@@ -0,0 +1,160 @@
+# Structural rules for REQ-{CODE}-{feature-name}.md files
+target-files: ".awa/specs/REQ-*.md"
+description: >
+  Requirements specification using EARS (Easy Approach to Requirements Syntax).
+  Succinct language. Do not overspecify. Omit irrelevant information.
+  Each requirement has an ID ({CODE}-{n}), a user story (AS A/I WANT/SO THAT),
+  and acceptance criteria with INCOSE-compliant types.
+  Subrequirements use dotted IDs ({CODE}-{n}.{p}).
+line-limit: 800
+
+sections:
+  # Top-level heading: "Requirements Specification"
+  - heading: "Requirements Specification"
+    level: 1
+    required: true
+    description: "Document title. No metadata in this section."
+
+  # Introduction section
+  - heading: "Introduction"
+    level: 2
+    required: true
+    description: "Brief context for the requirements. One or two paragraphs."
+
+  # Glossary section (optional)
+  - heading: "Glossary"
+    level: 2
+    description: >
+      Domain terms in TERM: definition format. Use CAPITALS for term names.
+      Format: - TERM: Definition
+
+  # Stakeholders section (optional)
+  - heading: "Stakeholders"
+    level: 2
+    description: >
+      Roles that interact with or are affected by this feature.
+      Format: - ROLE: Description
+
+  # Requirements section with repeatable requirement headings
+  - heading: "Requirements"
+    level: 2
+    required: true
+    description: >
+      Container for all requirements. Each child heading is a requirement
+      with ID, title, optional priority, user story, and acceptance criteria.
+    children:
+      - heading: "[A-Z]+-\\d+.*"
+        level: 3
+        required: true
+        repeatable: true
+        description: >
+          Individual requirement heading. Format: ### {CODE}-{n}: Title [{PRIORITY}]
+          where PRIORITY is MUST, SHOULD, COULD, or WONT (optional).
+          Contains a user story, optional rationale blockquote, ACCEPTANCE CRITERIA
+          heading, AC items, and optional DEPENDS ON line.
+        contains:
+          # User story format
+          - pattern: "AS AN? .*, I WANT .*, SO THAT"
+            label: "user story"
+            description: >
+              User story in AS A(N) {role}, I WANT {want}, SO THAT {benefit} format.
+              One sentence. Role, want, and benefit are all required.
+          # Acceptance criteria heading
+          - pattern: "ACCEPTANCE CRITERIA"
+            label: "AC heading"
+            description: "Literal text ACCEPTANCE CRITERIA (no markdown heading, just text)."
+          # At least one AC item
+          - list:
+              pattern: "_AC-\\d+\\s*\\[(ubiquitous|event|state|conditional|optional|complex)\\]"
+              min: 1
+              label: "acceptance criteria items"
+            description: >
+              Acceptance criteria items. Format:
+              - {CODE}-{n}_AC-{m} [{type}]: {statement} - {notes}
+              Types (EARS/INCOSE):
+              - ubiquitous: always true, no trigger ("The system SHALL ...")
+              - event: triggered by a stimulus ("WHEN x THEN system SHALL ...")
+              - state: true while a condition holds ("WHILE x THE system SHALL ...")
+              - conditional: depends on a boolean condition ("IF x THEN system SHALL ...")
+              - optional: feature activated by trigger ("WHERE x IS ENABLED THE system SHALL ...")
+              - complex: combines multiple EARS patterns
+
+  # Assumptions section (optional)
+  - heading: "Assumptions"
+    level: 2
+    description: "Bullet list of assumptions underlying the requirements."
+
+  # Constraints section (optional)
+  - heading: "Constraints"
+    level: 2
+    description: "Bullet list of constraints on the implementation."
+
+  # Out of Scope section (optional)
+  - heading: "Out of Scope"
+    level: 2
+    description: "Bullet list of explicitly excluded functionality."
+
+sections-prohibited:
+  - "**"
+
+example: |
+  # Requirements Specification
+
+  ## Introduction
+
+  Core engine requirements for game framework.
+
+  ## Glossary
+
+  - GAME LOOP: Core cycle of update-render that drives the engine
+  - CONTEXT: Runtime state container for engine subsystems
+
+  ## Stakeholders
+
+  - GAME DEVELOPER: Builds games using the engine API
+  - ENGINE MAINTAINER: Maintains and extends engine internals
+
+  ## Requirements
+
+  ### ENG-1: Core Engine Framework [MUST]
+
+  AS A game developer, I WANT a game loop, SO THAT predictable execution.
+
+  > Foundation for all games.
+
+  ACCEPTANCE CRITERIA
+
+  - ENG-1_AC-1 [event]: WHEN engine initializes THEN system SHALL create context
+  - ENG-1_AC-2 [event]: WHEN `--verbose` flag is provided THEN system SHALL enable debug logging
+  - ENG-1_AC-3 [ubiquitous]: The system SHALL maintain 60fps minimum frame rate
+
+  ### ENG-1.1: Subsystem Registration [SHOULD]
+
+  AS A engine maintainer, I WANT subsystems to self-register, SO THAT modular architecture.
+
+  ACCEPTANCE CRITERIA
+
+  - ENG-1.1_AC-1 [event]: WHEN subsystem loads THEN it SHALL register with context
+
+  ### ENG-2: Resource Management [MUST]
+
+  AS A game developer, I WANT automatic resource loading, SO THAT simplified asset management.
+
+  ACCEPTANCE CRITERIA
+
+  - ENG-2_AC-1 [event]: WHEN resource requested THEN system SHALL load asynchronously
+  - ENG-2_AC-2 [ubiquitous]: The system SHALL cache loaded resources
+
+  DEPENDS ON: ENG-1
+
+  ## Assumptions
+
+  - Target platform supports OpenGL 3.3 or higher
+
+  ## Constraints
+
+  - Must run on Windows, macOS, and Linux
+
+  ## Out of Scope
+
+  - Mobile platform support