@ncoderz/awa 1.4.0 → 1.5.0

package/README.md

@@ -4,9 +4,9 @@
 [![npm version](https://img.shields.io/npm/v/@ncoderz/awa.svg)](https://www.npmjs.com/package/@ncoderz/awa)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-`Supercharge your AI development.`
+`Structured, traceable AI development.`
 
-awa is an Agent Workflow for AIs. It is also a CLI tool to powerfully manage agent workflow files using templates, awa's or yours.
+awa is an Agent Workflow for AIs. It provides a Spec-Driven Design (SDD) workflow with full end-to-end traceability, with tools to enforced consistency and help the AI follow the connections. It is also a powerful templating tool for agent configuration files.
 
 > awa was written by awa (AI-assisted development using its own workflows). The workflows themselves are designed and crafted by a human who uses Copilot. If something is wrong, let's fix it together.
 
@@ -14,42 +14,42 @@ awa is an Agent Workflow for AIs. It is also a CLI tool to powerfully manage age
 
 ## The Problem
 
-Divergence.
+AI agents produce output that looks right but isn't connected. Requirements live in one place, implementation in another, tests in a third — nothing links them. The AI doesn't know when it has drifted from the original intent. You don't either, until something breaks.
 
-Developing with AI agents requires process. Configuration files that define this process get copy-pasted between projects, then diverge. Requirements live in one place, implementation in another, tests in a third — nothing connects them. They diverge too.
-
-Without structure, work drifts and nobody, including the AI, can trace what happened or why.
+Agent configuration files diverge too: copy-pasted between projects, modified by hand, silently out of date.
 
 ## How awa Solves It
 
-awa does two thing. Firstly, it generates agent configuration files from **templates**. Secondly, the generated output includes a powerful spec-driven development workflow with full traceability:
+awa provides a structured SDD workflow:
 
 ```
 ARCHITECTURE → FEAT → REQUIREMENTS → DESIGN → TASKS → CODE & TESTS → DOCUMENTATION
 ```
 
-Every code and test artifact traces back to its requirement and acceptance criteria origin through explicit markers (`@awa-impl`, `@awa-test`, `@awa-component`). Any line of code traces back to the requirement that motivated it. Any requirement traces forward to the tests that verify it.
+Every code and test artifact carries an explicit traceability marker (`@awa-impl`, `@awa-test`, `@awa-component`) that links it back to its originating requirement and acceptance criterion. Any line of code traces back to why it was written. Any requirement traces forward to the tests that verify it.
+
+`awa check` enforces this chain — validating spec structure via YAML schemas and ensuring every acceptance criterion maps to code and tests. `awa trace` assembles the chain into context so AI agents can navigate it rather than guess.
 
-Not only this, but awa actively checks that specs match a high quality schema, and that all requirements and acceptance criteria map to code and tests. This helps guide the AI to produce higher quality output.
+Agent configuration files are generated from **templates** — and can be added to your project or updated consistently with a single `awa init` call.
 
-## Workflow Features
+## SDD & Traceability Features
 
 - **Structured workflow with full traceability** - every requirement, acceptance critera and property test has an ID, every line of code links back via `@awa-component`, `@awa-impl` and `@awa-test` code markers
 - **`awa check`** - allows AI or humans to enforces spec structure via YAML schemas, and to validate traceability markers against spec IDs
 - **`awa trace`** - allows AI or humans to explore traceability chains and quickly assemble context from specs, code, and tests
 - **Agent-agnostic** - Copilot, Claude, Cursor, Windsurf, and more from a single template set
 
-## Template Features
+## Template Bootstrap Features
 
 - **[Eta](https://eta.js.org/) templates** with conditionals, loops, and partials for AI configuration files
-- **Feature flags and presets** - to turn content on/off per project
-- **Template overlays** - to layer customizations without forking
-- **`awa template diff`** - shows exactly what changed before you commit; `--watch` re-diffs on template changes
-- **`awa template test`** - verifies templates against fixtures and snapshots
-- **`awa template features`** - discovers available feature flags and presets
-- **Multi-target configuration** - for generating different agent setups in one command
-- **Git or local** - template sources — GitHub, GitLab, Bitbucket, or local path
-- **`--json` and `--summary`** - flags for CI integration
+- **Feature flags and presets** — turn content on/off per project
+- **Template overlays** — layer customizations without forking
+- **`awa template diff`** — shows exactly what changed before you commit; `--watch` re-diffs on template changes
+- **`awa template test`** — verifies templates against fixtures and snapshots
+- **`awa template features`** — discovers available feature flags and presets
+- **Multi-target configuration** — for generating different agent setups in one command
+- **Git or local** — template sources (GitHub, GitLab, Bitbucket, or local path)
+- **`--json` and `--summary`** — flags for CI integration
 
 See the **[full documentation](https://awa.ncoderz.com)** for details.
 
@@ -80,25 +80,28 @@ awa init . --features copilot claude cursor
 
 See the **[Quick Start guide](https://awa.ncoderz.com/guides/quick-start/)** for more.
 
-## Alternatives
-
-Several tools address parts of the AI-assisted development workflow. Here's how they compare:
-
-| | awa | [Kiro](https://kiro.dev) | [Spec Kit](https://github.com/github/spec-kit) | [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) | [AI RPI Protocol](https://github.com/MiguelAxcar/ai-rpi-protocol) | Manual files |
-|---|---|---|---|---|---|---|
-| **What it is** | CLI that generates agent config from templates | IDE with built-in spec-driven development | Python CLI for Spec-Driven Development | Agile workflow with role-based AI skills | Markdown rules for AI behavior governance | Hand-written CLAUDE.md, .cursorrules, etc. |
-| **Structured workflow** | Architecture →</br> Features →</br> Requirements →</br> Design →</br> Tasks →</br> Code & Tests →</br> Docs | Requirements →</br> Design →</br> Tasks | Specify →</br> Plan →</br> Tasks →</br> Implement | Analysis →</br> Planning →</br> Solutioning →</br> Implementation | Research →</br> Plan →</br> Implement | Whatever you put in the file |
-| **Workflow flexibility** | ✅ Start at any stage, skip what's not needed | ⚠️ Two variants (Req-First or Design-First), always 3 phases | ⚠️ Optional clarify/analyze steps, otherwise fixed order | ⚠️ Project levels determine required phases | ⚠️ Hard gates between phases, escape commands to bypass | ✅ No workflow to constrain you |
-| **Traceability** | ✅ Requirement IDs →</br> design →</br> `@awa-impl` / `@awa-test` code markers</br> + `awa check` | ❌ | ❌ | ❌ | ❌ | ❌ |
-| **Template engine** | ✅ Eta with conditionals, loops, partials | ❌ | ❌ Static templates copied on init | ❌ Static skill files | ❌ Static markdown | ❌ |
-| **Feature flags** | ✅ Enable/disable content per project | ❌ | ❌ | ❌ | ⚠️ Lite/Full modes | ❌ |
-| **Presets** | ✅ Named flag bundles | ❌ | ❌ | ⚠️ Complexity levels | ⚠️ Operation levels | ❌ |
-| **AI Instructions Drift detection** | ✅ `awa template diff` shows what changed vs. templates | ❌ | ❌ | ❌ | ⚠️ Manual compliance checklist | ❌ |
-| **Re-generation** | ✅ Generates from templates on every run | ❌ Specs created per feature | ❌ One-time `specify init` | ❌ One-time install | ❌ One-time copy | ❌ One-time manual creation |
-| **Agent hooks** | ❌ | ✅ Event-driven agent triggers on file save | ❌ | ❌ | ❌ | ❌ |
-| **Built-in IDE** | ❌ | ✅ VS Code-compatible IDE | ❌ | ❌ | ❌ | ❌ |
-| **Runtime** | Node + CLI | Standalone IDE + CLI | Python 3.11+ / uv | Shell / Python / yq | None (markdown only) | None |
-| **Agent support** | Agent-agnostic (generate config for any agent) | Kiro only | 18+ agents | Codex-focused | Cursor, VS Code, Claude Code, Windsurf | One agent at a time |
+## Related Tools
+
+Several tools address AI-assisted development workflows. Each brings different strengths:
+
+| Tool | Description | Runtime |
+|---|---|---|
+| **awa** | Templated agent config generation with spec-driven workflow and traceability | Node + CLI |
+| **[Kiro](https://kiro.dev)** | IDE with built-in spec-driven development and agent hooks | Standalone IDE + CLI |
+| **[Spec Kit](https://github.com/github/spec-kit)** | Python CLI for structured specs with broad agent support (18+) | Python 3.11+ / uv |
+| **[BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD)** | Agile workflow with role-based AI personas | Shell / Python / yq |
+| **[AI RPI Protocol](https://github.com/MiguelAxcar/ai-rpi-protocol)** | Zero-dependency markdown rules for disciplined AI development | None (markdown only) |
+
+### What each tool does well
+
+- **Kiro** — Deep IDE integration with agent hooks that trigger on file save, giving a seamless spec-driven experience without leaving your editor
+- **Spec Kit** — Supports 18+ agents out of the box and brings GitHub's backing; great if you work in Python and want broad compatibility
+- **BMAD Method** — Role-based AI personas (architect, PM, developer) that mirror agile team structures, useful for larger or more formal projects
+- **AI RPI Protocol** — Works instantly with no tooling to install; a simple, proven mental model for disciplined AI-assisted development
+
+### Where awa fits
+
+awa focuses on two things other tools don't combine: **end-to-end traceability** (every line of code links back to a requirement via `@awa-impl` / `@awa-test` markers, validated by `awa check`) and **templateable agent configuration** (feature flags, presets, overlays, diff detection). It's agent-agnostic — one template set generates config for Copilot, Claude, Cursor, Windsurf, and more.
 
 
 ## Development

package/dist/index.js

@@ -24,7 +24,7 @@ import { Command } from "commander";
 // src/_generated/package_info.ts
 var PACKAGE_INFO = {
   "name": "@ncoderz/awa",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "author": "Richard Sewell <richard.sewell@ncoderz.com>",
   "license": "MIT",
   "description": "awa is an Agent Workflow for AIs. It is also a CLI tool to powerfully manage agent workflow files using templates."