Quick Start

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

Install

Global install
npx (no install)

npm install -g @ncoderz/awa

npx @ncoderz/awa generate .

Generate Your First Configuration

Navigate to your project
Terminal window
```
cd my-project
```
Generate files using the default awa template
Terminal window
```
awa generate .
```
This generates agent configuration files into the current directory using awa’s bundled default template.
Generate with specific AI tool features
Terminal window
```
awa generate . --features copilot claude cursor
```
Feature flags control which sections are included. Enable only what you need.
Preview before writing (dry run)
Terminal window
```
awa generate . --dry-run
```
Check for drift later
Terminal window
```
awa diff .
```
After templates are updated, use awa diff to see what would change in your project.

Common Usage Patterns

Using a Preset

# Enable all supported AI tools
awa generate . --preset full

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

Using a Custom Template

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

# From a GitHub repository
awa generate . --template owner/repo

# From a specific branch or tag
awa generate . --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 generate

What Gets Generated

By default, awa generates files into .github/agents/ (configurable). These include:

Agent configuration files (e.g., awa.agent.md)
Prompt files in .github/prompts/
Workflow rules in .awa/rules/

The exact output depends on your template and feature flags.

Next Steps

Workflow Guide — understand the awa workflow stages and traceability
CLI Reference — all commands and options
Template Engine — write your own templates
Configuration — .awa.toml reference