Quick Start

Get up and running with awa in just a few minutes.

Install

Global install
npx (no install)

bash npm install -g @ncoderz/awa

bash npx @ncoderz/awa init

Generate Agent Configuration Files

awa’s core value: one command generates AI agent configuration files for every tool your team uses — GitHub Copilot, Claude, Cursor, Gemini, and more — from a single template.

Navigate to your project
Terminal window
```
cd my-project
```
Generate files using the default awa template
Terminal window
```
awa init
```
This generates agent configuration files into the current directory using awa’s bundled default template.
Generate with specific AI tool features
Terminal window
```
awa init --features copilot claude cursor
```
Feature flags control which sections are included. Enable only what you need.
Preview before writing (dry run)
Terminal window
```
awa init --dry-run
```
Discover available features
Terminal window
```
awa template features
```
Lists all feature flags available in the template.
Check for drift after a template update
Terminal window
```
awa template diff .
```
See what would change in your project if you re-generated from the latest template.

Common Usage Patterns

Using a Preset

# Enable all supported AI tools
awa init --preset full

# Enable a subset
awa init --preset full --remove-features roo agy

Using a Custom Template

# From a local directory
awa init --template ./my-templates

# From a GitHub repository
awa init --template owner/repo

# From a specific branch or tag
awa init --template owner/repo#v1.0.0

Using a Config File

Create .awa.toml in your project root:

output = ".github/agents"
template = "owner/repo"
features = ["copilot", "claude"]

Then simply run:

awa init

What Gets Generated

By default, awa generates files into the project root (configurable). These typically include:

Agent instruction files (e.g., CLAUDE.md, AGENTS.md)
Prompt files in .github/prompts/
Workflow skills in .github/skills/

The exact output depends on your template and feature flags.

Traceability and the awa Workflow

awa check and awa trace are separate from template generation — they are used when following the awa structured workflow for spec-driven development.

awa check — validates that traceability markers in your code reference real spec IDs, and flags uncovered acceptance criteria. Run this as part of your structured development workflow, not as part of template setup.
awa trace <ID> — assembles the full trace for a requirement or component: spec text, implementation, and tests in one view. Useful when working on a feature or investigating coverage.

# Check traceability coverage across your codebase
awa check

# Trace a specific requirement or component
awa trace FEAT-1

These commands require spec files (.awa/specs/) to be present. See the Workflow Guide for how to set up the full awa development workflow.

Spec Management Commands

Once you’re using the awa workflow, additional commands help manage your specifications:

# List all feature codes in your project
awa spec codes

# Renumber IDs to close gaps (e.g. after deleting requirements)
awa spec renumber DIFF

# Recode a feature code to a new name
awa spec recode OLD NEW

# Merge two feature codes into one
awa spec merge SRC TGT

See the CLI Reference for full details on all spec management commands.

Next Steps

Workflow Guide — understand the awa workflow stages and traceability
Traceability — how IDs and markers connect everything
CLI Reference — all commands and options
Template Engine — write your own templates
Template Testing — verify templates with fixtures and snapshots
Configuration — .awa.toml reference