# OpenSpec Workflow Guide

## Overview

OpenSpec implements spec-driven development (SDD) where specifications are agreed upon before implementation. This workflow works with or without the OpenSpec CLI.

## Core Workflow

```
┌────────────────────┐
│ Draft Change       │
│ Proposal           │
└────────┬───────────┘
         │ share intent with your AI
         ▼
┌────────────────────┐
│ Review & Align     │
│ (edit specs/tasks) │◀──── feedback loop ──────┐
└────────┬───────────┘                          │
         │ approved plan                        │
         ▼                                      │
┌────────────────────┐                          │
│ Implement Tasks    │──────────────────────────┘
│ (AI writes code)   │
└────────┬───────────┘
         │ ship the change
         ▼
┌────────────────────┐
│ Archive & Update   │
│ Specs (source)     │
└────────────────────┘
```

## Coordination with Beads and .augment/

OpenSpec specs can include YAML frontmatter to coordinate with Beads tasks and `.augment/` rules:

```markdown
---
id: features/profile-search
relatedTasks: [bd-xyz, bd-abc]
relatedRules: [module-development.md]
status: active
---

# Profile Search Specification
...
```

**Benefits**:
- **Traceability**: Link specs to implementing tasks
- **Context**: AI agents load relevant rules automatically
- **Coordination**: Integration with coordination manifest

See `.augment/rules/coordination-system.md` for details.

---

## Step 1: Draft Change Proposal

### With CLI

Ask your AI agent:

```
Create an OpenSpec change proposal for adding profile search filters by role and team
```

Or use slash command (if supported):

```
/openspec:proposal Add profile search filters
```

### Without CLI

Ask your AI agent:

```
Create a new change folder in openspec/changes/add-profile-filters/ with:
1. proposal.md - describing the change
2. tasks.md - implementation checklist
3. specs/ - folder with spec deltas for affected components
```

### What Gets Created

```
openspec/changes/add-profile-filters/
├── proposal.md       # Why this change, what it does
├── tasks.md          # Checklist of implementation steps
└── specs/
    └── profile/
        └── spec.md   # Delta showing additions/modifications
```

## Step 2: Review & Align

### Validate (CLI only)

```bash
openspec validate add-profile-filters
```

### Review

```bash
# With CLI
openspec show add-profile-filters

# Without CLI - manually review files
cat openspec/changes/add-profile-filters/proposal.md
cat openspec/changes/add-profile-filters/tasks.md
cat openspec/changes/add-profile-filters/specs/profile/spec.md
```

### Iterate

Ask your AI to refine:

```
Can you add acceptance criteria for the role and team filters?
```

```
The tasks look good, but can you break down task 2.1 into smaller steps?
```

Continue until specs match your requirements.

## Step 3: Implement Tasks

### With CLI

```
The specs look good. Let's implement this change.
```

Or use slash command:

```
/openspec:apply add-profile-filters
```

### Without CLI

```
Please implement the tasks in openspec/changes/add-profile-filters/tasks.md
Mark each task complete as you finish it.
```

### AI Implementation Pattern

The AI agent will:

1. Read the spec deltas to understand requirements
2. Work through tasks.md sequentially
3. Mark tasks complete: `- [x] 1.1 Add role filter component`
4. Reference specs when making decisions
5. Update tasks.md if scope changes

## Step 4: Archive Completed Change

### With CLI

```bash
openspec archive add-profile-filters --yes
```

Or ask AI:

```
Please archive the add-profile-filters change
```

### Without CLI

Manually merge the changes:

1. Copy spec deltas from `openspec/changes/add-profile-filters/specs/` to `openspec/specs/`
2. Apply ADDED/MODIFIED/REMOVED sections to source specs
3. Move change folder to archive: `openspec/archive/add-profile-filters/`

## Commands Reference

### With CLI

| Command | Action |
|---------|--------|
| `openspec init` | Initialize OpenSpec in project |
| `openspec list` | View active change folders |
| `openspec show <change>` | Display change details |
| `openspec validate <change>` | Check spec formatting |
| `openspec archive <change>` | Merge change into specs |
| `openspec update` | Refresh AI agent instructions |

### Without CLI

All operations are manual file operations. AI agents can create/edit files directly.

## Best Practices

1. **One Change Per Folder**: Keep changes focused and atomic
2. **Review Before Implementation**: Catch issues in specs, not code
3. **Update Tasks During Implementation**: Reflect actual work done
4. **Archive Promptly**: Keep changes/ folder clean
5. **Use Descriptive Names**: `add-2fa` not `feature-123`

## Next Steps

- See `spec-format.md` for specification syntax
- See `manual-setup.md` for CLI-free setup
- See `best-practices.md` for advanced patterns

