Agent Workflow for AIs

What is awa?

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.

Structured Workflow

Architecture → Features → Requirements → Design → Tasks → Code & Tests → Documentation.

Full Traceability

Every line of code traces back to its requirement and acceptance criteria via @awa-impl and @awa-test markers.

awa check

Consistency is enforced. Spec structure is validated against YAML schemas and all spec marker mapping and consistency is checked.

awa trace

Assembles the marker traceability chain into context — specs, code, and tests — so AI navigates with confidence rather than guessing.

Spec Management

awa spec merge can fully tidy your specs with help of your AI without rewording or losing consistency. You can recode, renumber and tidy your specs with confidence.

AI Bootstrap

Eta-based templates with feature flags and presets generate agent configuration files like AGENTS.md for any AI tool — Copilot, Claude, Cursor, Windsurf, and more.

Template Diffs

awa template diff shows exactly what has changed in your agent configuration files vs. the templates — before you commit to update.

Agent-Agnostic

One template set. All agents. Copilot, Claude, Cursor, Windsurf, and more from a single source of truth.

Git or Local

Pull templates from GitHub, GitLab, Bitbucket, or use a local path. Cached locally for fast re-runs.

A Little Unstable

The tool has been developing fast. The awa.upgrade skill can be used to bring your project up to date with the latest awa.

The Problem: AI Drift

AI agents produce output that looks right but stuff is missing. Requirements and implementation drift from one-another, and are hard to resync. The AI doesn’t know when it has drifted from the original intent. You don’t either, until something breaks.

Agent configuration files diverge too: copy-pasted between projects, modified by hand, silently out of date.

How awa Solves It

awa provides a structured SDD workflow with full traceability using markers to link between specs, code, and tests:

ARCHITECTURE → FEAT → REQUIREMENTS → DESIGN → TASKS → CODE & TESTS → DOCUMENTATION

Tooling enforces spec structure and validates that every spec marker is consistent and maps to code and tests. The AI can use awa trace to assemble context from the chain so AI can navigate rather than guess. Agent configuration files are bootstrapped from templates.

Quick Start Install awa and generate your first configuration.

Workflow Guide Understand the awa SDD workflow and traceability chain.

CLI Reference All commands and options documented.

Traceability Guide Learn how markers keep your AI honest.