aw-spec-cli 0.1.2 → 0.1.4

package/README.md

@@ -0,0 +1,291 @@
+# aw-spec-cli
+
+**AppWeaver Spec-Driven Development CLI** — Scaffold projects with vertical slices, DDD, CQRS, and AI agent skills.
+
+[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+
+---
+
+## 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](https://dev.azure.com/bytestrone-labs/AppWeaver/_git/AppWeaver.Spec) reference implementation) into your target directory.
+
+---
+
+## Installation
+
+### Global Install (via Azure Artifacts / npm)
+```bash
+# From Azure Artifacts (after publishing)
+npm install -g aw-spec-cli
+
+# Or use via npx
+npx aw-spec-cli@latest init
+```
+
+### Local Development Install
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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](https://dev.azure.com/bytestrone-labs/AppWeaver/_git/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)
+```bash
+# 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:
+```bash
+# 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](https://dev.azure.com/bytestrone-labs/AppWeaver)
+
+---
+
+## Related
+
+- [AppWeaver.Spec](https://dev.azure.com/bytestrone-labs/AppWeaver/_git/AppWeaver.Spec) — Reference implementation & source of bundled assets
+- [Spec-Driven Development](https://dev.azure.com/bytestrone-labs/AppWeaver/_git/AppWeaver.Spec?path=/docs/spec-driven-development.md) — Methodology overview