aw-spec-cli

AppWeaver Spec-Driven Development CLI — Scaffold projects with vertical slices, DDD, CQRS, and AI agent skills.

Overview

aw-spec-cli initializes new projects with the AppWeaver Spec-Driven Development structure:

• Vertical Slice Architecture — Feature-oriented, decoupled modules
• Domain-Driven Design (DDD) — Rich domain models, bounded contexts
• CQRS — Command/Query separation for scalable reads/writes
• AI Agent Skills — Ready-to-use skills for Claude Code, Antigravity, and KiloCode

The CLI copies a battle-tested project skeleton (from the AppWeaver.Spec reference implementation) into your target directory.

Installation

Global Install (via Azure Artifacts / npm)

# From Azure Artifacts (after publishing)
npm install -g aw-spec-cli

# Or use via npx
npx aw-spec-cli@latest init

Local Development Install

# From the cloned repository
git clone https://dev.azure.com/bytestrone-labs/AppWeaver/_git/appweaver
cd platform/Appweaver.Spec.Cli
npm install
npm run build
# Then run via node
dist/index.js init

Requires Node.js ≥ 18.

Quick Start

# Create a new project in the current directory
aw-spec init

# Or specify a target directory
aw-spec init my-project

# Non-interactive (uses Claude skills by default)
aw-spec init -y

# Choose agent explicitly
aw-spec init --agent antigravity
aw-spec init --agent kilocode

# Preview what would be copied (no changes)
aw-spec init --dry-run

After initialization:

# Verify the installation
aw-spec doctor

# Start spec-driven development
aw-spec specify "Your feature description"

Commands

aw-spec init [directory]

Initialize a new AppWeaver Spec project.

| Option | Description | |--------|-------------| | directory | Target directory (default: current directory) | | -a, --agent <agent> | Agent skills to include: claude, antigravity, kilocode (default: prompt) | | -y, --yes | Skip prompts, use defaults (Claude) | | --dry-run | Show what would be copied without making changes |

Copied structure:

target-dir/
├── .aw-spec/              # Core spec configuration
│   ├── extensions.yml     # Extension registry
│   ├── feature.json       # Feature tracking
│   ├── workflows/         # Workflow definitions
│   ├── templates/         # Spec/plan/task templates
│   └── scripts/           # Bash/PowerShell helpers
├── docs/                  # Documentation scaffold
│   ├── architecture/
│   ├── domain/
│   ├── governance/
│   ├── security/
│   ├── domainspecs/
│   ├── glossary/
│   ├── VerticalSlice/     # Vertical slice packaging
│   └── ...
└── .claude/skills/        # Or .agents/skills/, .kilocode/
    ├── aw-spec-specify/
    ├── aw-spec-plan/
    ├── aw-spec-implement/
    └── ... (13 skills total)

aw-spec doctor

Verify the project structure is complete and valid.

| Option | Description | |--------|-------------| | -v, --verbose | Show detailed output (lists all skills, missing items) |

Checks performed:

• Required folders: .aw-spec/, docs/
• Required config files: extensions.yml, feature.json, init-options.json, integration.json, workflow-registry.json
• Agent skills folder (.claude/skills or .agents/skills) with all 13 skills
• Documentation structure (architecture/, domain/, governance/, security/, domainspecs/, glossary/, VerticalSlice/)
• Vertical Slice packaging scripts (pack-foundation.sh, unpack-foundation.sh, PACKAGING.md)
• .aw-spec subdirectories (extensions/, templates/, scripts/, workflows/, integrations/, memory/)

Agent Support

| Agent | Folder | Skills | |-------|--------|--------| | Claude Code | .claude/skills/ | 13 skills (specify, plan, implement, tasks, clarify, analyze, checklist, foundation, constitution, select-domain, agent-context-update, addcomponent, taskstoissues) | | Antigravity | .agents/skills/ | Same 13 skills, Antigravity-compatible format | | KiloCode | .kilocode/ | Workflow definitions (.md files) |

Choose based on your AI assistant. Skills provide guided workflows for spec-driven development:

• aw-spec-specify — Write feature specifications
• aw-spec-plan — Create implementation plans
• aw-spec-implement — Generate code from plans
• aw-spec-tasks — Break down into executable tasks
• ... and more

Project Structure (After Init)

my-project/
├── .aw-spec/
│   ├── extensions.yml
│   ├── feature.json
│   ├── init-options.json
│   ├── integration.json
│   ├── workflows/
│   │   └── workflow-registry.json
│   ├── extensions/
│   │   └── agent-context/
│   │       ├── scripts/
│   │       └── commands/
│   ├── templates/
│   │   ├── spec-template.md
│   │   ├── plan-template.md
│   │   └── tasks-template.md
│   ├── scripts/
│   │   └── bash/
│   │       └── common.sh
│   ├── integrations/
│   └── memory/
├── docs/
│   ├── architecture/
│   ├── domain/
│   ├── governance/
│   ├── security/
│   ├── domainspecs/
│   ├── glossary/
│   ├── interop/
│   ├── ModularMonolith/
│   ├── VerticalSlice/
│   │   ├── VerticalSlice.pack.txt
│   │   ├── PACKAGING.md
│   │   ├── pack-foundation.sh
│   │   └── unpack-foundation.sh
│   ├── command.txt
│   ├── components/
│   ├── pharma-constitution.my-ref.md
│   ├── requirement-spec.txt
│   ├── technology-constitution.md
│   └── README.md
└── .claude/skills/          # Or .agents/skills/, .kilocode/
    ├── aw-spec-addcomponent/
    ├── aw-spec-agent-context-update/
    ├── aw-spec-analyze/
    ├── aw-spec-checklist/
    ├── aw-spec-clarify/
    ├── aw-spec-constitution/
    ├── aw-spec-foundation/
    ├── aw-spec-implement/
    ├── aw-spec-plan/
    ├── aw-spec-select-domain/
    ├── aw-spec-specify/
    ├── aw-spec-tasks/
    └── aw-spec-taskstoissues/

Development

Prerequisites

• Node.js ≥ 18
• The AppWeaver.Spec repository cloned as a sibling directory (for bundling assets)

Scripts

| Command | Description | |---------|-------------| | npm run build | Compile TypeScript to dist/ | | npm run bundle:content | Copy assets from ../AppWeaver.Spec → assets/ | | npm run prepack | Build + bundle (runs automatically on npm publish) | | npm test | Run unit tests (Vitest) | | npm run test:watch | Watch mode | | npm run lint | ESLint on src/ | | npm run doctor | Run CLI doctor on current directory |

Setup (Local Development)

# Clone the main repository
git clone https://dev.azure.com/bytestrone-labs/AppWeaver/_git/appweaver
cd platform/Appweaver.Spec.Cli
npm install

# Ensure AppWeaver.Spec is available for bundling
# Either clone it as a sibling directory:
#   git clone https://dev.azure.com/bytestrone-labs/AppWeaver/_git/AppWeaver.Spec ../AppWeaver.Spec
# Or the bundling script will fall back to published assets in dist/assets/

Setup (After Publishing to Azure Artifacts)

Once published to Azure Artifacts, consumers can install via:

# From Azure Artifacts / npm registry (after publishing)
npm install -g aw-spec-cli

# Or use directly via npx
npx aw-spec-cli@latest init

How It Works

1. Asset Bundling (scripts/bundle-content.ts) — On publish, copies the AppWeaver.Spec reference implementation into assets/ (excludes build artifacts, secrets, VCS folders).

2. Asset Resolution (src/utils/paths.ts) — At runtime, finds assets in priority order:

   • dist/assets/ (published package)
   • ../AppWeaver.Spec (local development)
   • packageRoot/assets (fallback)

3. Project Initialization (src/commands/init.ts) — Copies .aw-spec/, docs/, and the selected agent's skills to the target directory with overwrite protection.

4. Validation (src/commands/doctor.ts) — Comprehensive structure verification with colored output.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make changes with tests
4. Run npm run build && npm test && npm run lint
5. Submit a PR

License

MIT © AppWeaver Team

Related

• AppWeaver.Spec — Reference implementation & source of bundled assets
• Spec-Driven Development — Methodology overview