Introduction

Open Source BSD-3-Clause License

awa (Agent Workflow for AIs) is an open-source CLI tool for structured, traceable AI-assisted development. It enforces a Software Design Document (SDD) workflow with full end-to-end traceability, validated by awa check and navigable via awa trace. Agent configuration files are bootstrapped from templates with feature flags.

The Problem

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.

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

The Solution

awa provides a structured SDD workflow:

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

Every artifact carries an explicit traceability marker (@awa-impl, @awa-test, @awa-component) linking it 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 navigate with confidence rather than guessing.

Agent configuration files are bootstrapped from templates with feature flags — making the SDD workflow available in any project immediately.

Key Features

SDD & Traceability

• Structured SDD workflow from architecture through documentation
• Requirements written in EARS format (INCOSE) — structured, testable, unambiguous
• Every requirement has an ID; every line of code links back via @awa-impl and @awa-test markers
• awa check validates spec structure via YAML schemas and flags uncovered acceptance criteria
• awa check auto-fixes Requirements Traceability sections and the Feature Codes table
• awa trace assembles context from specs, code, and tests for AI agents
• awa spec codes lists all feature codes with requirement counts and scope summaries
• awa spec renumber closes gaps in traceability ID numbering
• awa spec recode rewrites IDs from one feature code to another
• awa spec merge merges two feature codes into one (recode + content merge + cleanup)
• Spec artifacts (requirements, designs, tasks, plans, rules) all live in .awa/

Template Bootstrap

• Eta templates with conditionals, loops, and partials
• Feature flags and presets to turn content on/off per project
• awa template diff shows exactly what changed before you commit
• awa template features discovers all feature flags in a template
• awa template test verifies templates against test fixtures and snapshots
• Template overlays to layer customizations over a base template
• Multi-target configuration for generating different agent setups in one command
• Pull templates from GitHub, GitLab, Bitbucket, or use a local path
• Optional .awa.toml config, or just use CLI flags

Philosophy

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.

awa is agent-agnostic: it generates configuration for GitHub Copilot, Claude, Cursor, Windsurf, and more — all from a single template set. It makes no assumptions about which AI tool you use or how you use it.

Next Steps

• Quick Start — install awa and generate your first configuration in minutes
• Workflow Guide — understand the full workflow and traceability chain
• CLI Reference — all commands, options, and configuration