# OpenSpec Workflow Module

**Spec-driven development (SDD) for AI coding assistants.**

## Overview

OpenSpec provides a structured workflow for managing changes in AI-assisted development. It ensures humans and AI agents agree on specifications before implementation, reducing rework and improving code quality.

## Key Benefits

- **Alignment Before Implementation**: Agree on specs before writing code
- **Structured Change Management**: Proposals, specs, and tasks in organized folders
- **Brownfield-Friendly**: Excellent for modifying existing features (1→n), not just greenfield (0→1)
- **Version Controlled**: All specs stored in git alongside code
- **AI Agent Compatible**: Works with any tool that reads AGENTS.md

## Installation Options

### Option 1: With CLI (Recommended)

Install the OpenSpec CLI for full features:

```bash
# npm
npm install -g @fission-ai/openspec@latest

# Nix
nix run github:Fission-AI/OpenSpec -- init

# Initialize in your project
cd your-project
openspec init
```

**Benefits**: Validation, archiving, slash commands, auto-generated AGENTS.md

### Option 2: Without CLI (Manual)

Follow the workflow manually without installing the CLI. See `rules/manual-setup.md` for instructions.

**Benefits**: No installation required, works immediately

**Limitations**: No validation, manual archiving, no slash commands

## Directory Structure

```
your-project/
├── openspec/
│   ├── AGENTS.md              # AI agent instructions (auto-generated)
│   ├── project.md             # Project context and conventions
│   ├── specs/                 # Current specifications (source of truth)
│   │   └── auth/
│   │       └── spec.md
│   └── changes/               # Proposed changes
│       └── add-2fa/
│           ├── proposal.md    # Why and what
│           ├── tasks.md       # Implementation checklist
│           ├── design.md      # Technical decisions (optional)
│           └── specs/         # Spec deltas (changes)
│               └── auth/
│                   └── spec.md
```

## Workflow

See `rules/workflow.md` for complete workflow documentation.

**Quick Summary**:

1. **Draft Proposal** - Create change proposal with AI
2. **Review & Align** - Iterate on specs until agreement
3. **Implement** - AI implements tasks referencing specs
4. **Archive** - Merge approved changes into source specs

## Character Count

This module contains comprehensive OpenSpec workflow documentation that exceeds the standard `.augment/` folder character limit.

**Total**: ~25,000 characters across all rule files

## Contents

- `rules/workflow.md` - Complete workflow guide
- `rules/spec-format.md` - Specification format and delta syntax
- `rules/manual-setup.md` - Manual setup without CLI
- `rules/commands.md` - CLI command reference
- `rules/best-practices.md` - Tips and patterns
- `examples/` - Example specs and changes

## Learn More

- **Homepage**: https://openspec.dev/
- **GitHub**: https://github.com/Fission-AI/OpenSpec
- **Documentation**: See `rules/` directory in this module

