@ncoderz/awa 0.2.0

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

@@ -0,0 +1,46 @@
+# Refactor Code
+
+## Bootstrap
+
+<tool name="read_file">
+ <read path=".awa/.agent/awa.core.md" required="true" error="on not found" />
+ <read path=".awa/rules/*.md" required="true" />
+ <read path=".awa/specs/ARCHITECTURE.md" required="true" error="on not found" />
+</tool>
+
+## User Input
+
+```text
+${input}
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Inputs
+
+<file type="architecture" path=".awa/specs/ARCHITECTURE.md" />
+<file type="requirements" path=".awa/specs/REQ-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="design" path=".awa/specs/DESIGN-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="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
+
+Refactor the specified cod or docs as instructed, following awa conventions.
+
+## Outputs
+
+- Refactored source code files with preserved markers
+- Updated test files if structure changed
+- Refactored documentation
+
+## Rules
+
+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 ensure tests pass before and after refactoring.
+You SHALL make incremental changes, not wholesale rewrites.
+You SHALL NOT change public interfaces without explicit approval.
+You SHALL clarify scope and risks with user before major refactors.
+You MAY use todos and tools as needed.

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

@@ -0,0 +1,50 @@
+# Create or Update Requirements
+
+## 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/REQ.schema.md" required="true" error="on not found" />
+</tool>
+
+## User Input
+
+```text
+${input}
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Inputs
+
+<file type="architecture" path=".awa/specs/ARCHITECTURE.md" />
+<file type="feat" path=".awa/specs/FEAT-{CODE}-{feature-name}.md" required="true" />
+<file type="examples" path=".awa/specs/EXAMPLES-{CODE}-{feature-name}-{nnn}.md" required="if relevant" />
+<file type="requirements" path=".awa/specs/REQ-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="code" required="if reverse workflow" />
+
+## Action
+
+Create or update the requirements document(s) as specified in the instruction above, following awa conventions.
+
+If deriving from existing code (reverse workflow), analyze the codebase to extract implicit requirements, acceptance criteria, and behavioral expectations.
+
+## Outputs
+
+<file path=".awa/specs/REQ-{CODE}-{feature-name}.md" />
+
+## Rules
+
+You SHALL read the corresponding FEAT document before writing requirements.
+You SHALL solidify requirements with respect to architecture, feature context, and existing requirements.
+You SHALL create set of requirements in EARS format (INCOSE-compliant) based on the feature context.
+You SHALL identify existing requirements to update, or new requirements to create.
+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 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

@@ -0,0 +1,147 @@
+# 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.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" />
+</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/EXAMPLES-{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
+- Documentation updates
+- Cross-cutting concerns
+- No requirement labels
+
+## 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
+
+## 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/_partials/awa.upgrade.md

@@ -0,0 +1,63 @@
+# 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.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" />
+</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/EXAMPLES-{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="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) 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.
+
+## Outputs
+
+- Updated spec(s) and supporting templates (as applicable)
+
+## Rules
+
+You SHALL avoid destructive edits; propose clarifications when unsure.
+You SHALL add to any change log sections as needed.
+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 500-line limit; split logically if needed.
+You MAY use todos and tools as needed.

package/templates/awa/_partials/awa.validate-alignment.md

@@ -0,0 +1,62 @@
+# Validate alignment of Source(x) with Target(y)
+
+## 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/ALIGN_REPORT.schema.md" required="true" error="on not found" />
+</tool>
+
+## User Input
+
+```text
+${input}
+```
+
+Format: `<source> [<target>]` where:
+- **Source (x)**: The artifact being validated. If not specified, use the last completed work.
+- **Target (y)**: The artifact to validate against. If not specified, it is implied according to these rules:
+
+1. x is plan → ask for clarification
+2. previous work against a plan → use that plan
+3. else → walk UP workflow toward architecture
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Definitions
+
+x = source artifact (what is being validated) = design(s).
+y = target artifact (what x is validated against) = requirement(s).
+
+## 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/EXAMPLES-{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="plan" path=".awa/plans/PLAN-{nnn}-{plan-name}.md" required="if relevant" />
+<file type="code_and_tests" path="various" required="if relevant" />
+
+## Action
+
+Validate that the specified source:x aligns with the target:y, and if not, report all differences.
+Follow awa conventions.
+
+## Outputs
+
+<file path=".awa/align/ALIGN-{x}-WITH-{y}-{nnn}.md" />
+<cli>STATUS: {PASSED ✅ | FAILED ❌}</cli>
+
+## Rules
+
+You SHALL validate alignment of source:y with target:y.
+You SHALL report all differences.
+You SHALL consider traceability.
+You SHALL report missing trace IDs.
+You MAY use todos and tools as needed.
+

package/templates/awa/_partials/awa.vibe.md

@@ -0,0 +1,64 @@
+# 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/EXAMPLES-{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?"
+
+## Outputs
+
+- Specs as needed (ARCHITECTURE, FEAT, REQ, DESIGN, TASK)
+- Implemented code with traceability markers
+- Tests covering acceptance criteria
+
+## 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 MAY use todos and tools as needed.

package/templates/example/.github/agents/example.agent.md

@@ -0,0 +1,14 @@
+# Example Usage
+
+This file demonstrates:
+
+- Feature flag conditionals
+- Empty file handling
+- Directory structure preservation
+
+<% if (it.features.includes('advanced')) { %>
+
+## Advanced Features
+
+This section only appears when 'advanced' feature is enabled.
+<% } %>

package/templates/example/_README.md

@@ -0,0 +1,43 @@
+# awa CLI Templates
+
+This directory contains the default templates bundled with awa CLI.
+
+## Structure
+
+- `agent.md` - Main agent configuration template
+- `_partials/` - Reusable template fragments (not output directly)
+- `.github/agents/` - Example nested directory structure
+
+## Template Syntax
+
+Templates use [Eta](https://eta.js.org/) syntax:
+
+- `<%= expression %>` - Output expression (escaped)
+- `<%~ expression %>` - Output expression (raw/unescaped)
+- `<% code %>` - Control flow (if/else, loops, etc.)
+
+## Available Context
+
+Templates receive a `features` array via `it.features`:
+
+```eta
+<% if (it.features.includes('feature-name')) { %>
+  Content for feature-name
+<% } %>
+```
+
+## Empty File Marker
+
+To create an empty file explicitly, use:
+
+```html
+<!-- AWA:EMPTY_FILE -->
+```
+
+## Partials
+
+Include partials from `_partials/`:
+
+```eta
+<%~ include('_partials/planning', it) %>
+```

package/templates/example/_partials/planning.md

@@ -0,0 +1,5 @@
+<% if (it.features.includes('planning')) { %>
+# Planning Guide
+
+This partial provides planning assistance.
+<% } %>

package/templates/example/agent.md

@@ -0,0 +1,72 @@
+# <%= it.agentName || 'awa' %> Agent
+
+> AI Coding Agent Configuration
+
+## Purpose
+
+<% if (it.features.includes('planning')) { %>
+This agent assists with software planning, design, and architecture decisions.
+<% } %>
+
+<% if (it.features.includes('implementation')) { %>
+This agent helps with code implementation, refactoring, and optimization.
+<% } %>
+
+<% if (it.features.includes('testing')) { %>
+This agent supports test creation, debugging, and quality assurance.
+<% } %>
+
+<% if (it.features.includes('documentation')) { %>
+This agent generates and maintains project documentation.
+<% } %>
+
+<% if (!it.features.length) { %>
+This is a general-purpose AI coding agent that can assist with various development tasks.
+<% } %>
+
+## Capabilities
+
+<% if (it.features.includes('planning')) { %>
+- Requirements analysis
+- Architecture design
+- API design
+<% } %>
+
+<% if (it.features.includes('implementation')) { %>
+- Code generation
+- Refactoring
+- Performance optimization
+<% } %>
+
+<% if (it.features.includes('testing')) { %>
+- Unit test creation
+- Integration test design
+- Bug fixing
+<% } %>
+
+<% if (it.features.includes('documentation')) { %>
+- README generation
+- API documentation
+- Code comments
+<% } %>
+
+## Configuration
+
+**Agent Name:** <%= it.agentName || 'awa' %>
+
+**Enabled Features:**
+<% if (it.features.length > 0) { %>
+<% it.features.forEach(function(feature) { %>
+- <%= feature %>
+<% }) %>
+<% } else { %>
+- all (no specific features selected)
+<% } %>
+
+## Usage
+
+Invoke this agent through your development environment's AI integration.
+
+---
+
+Generated by awa CLI