CLI and Workflow¶

CLI commands¶

Create a new change¶

# Create structure for a new change
mkdir -p openspec/changes/add-barcode-scanning/specs/warehouse

# Create base files
touch openspec/changes/add-barcode-scanning/proposal.md
touch openspec/changes/add-barcode-scanning/tasks.md
touch openspec/changes/add-barcode-scanning/specs/warehouse/spec.md

Validate a change¶

# Validate a specific change
openspec validate add-barcode-scanning --strict

# Validate all active changes
openspec validate --changes

# JSON output for CI/CD
openspec validate add-barcode-scanning --json

Show status¶

# List active changes with progress bars
openspec list

# Output:
# Changes:
#   add-barcode-scanning     ████████░░░░ 8/16 tasks
#   fix-invoice-validation   ████████████ 4/4 tasks ✓

# Detail of a specific change
openspec show add-barcode-scanning

# Delta operations only
openspec show add-barcode-scanning --deltas-only

Archive a completed change¶

# Verify everything is done
openspec validate add-barcode-scanning --strict

# Archive (applies delta to specs/)
openspec archive add-barcode-scanning --yes

# Output:
# Applying changes to openspec/specs/warehouse/spec.md:
#   + 2 added
#   ~ 1 modified
#   - 0 removed
#
# Change 'add-barcode-scanning' archived as '2025-02-15-add-barcode-scanning'

Workflow for AI agents¶

Slash command: /openspec:proposal¶

**Guardrails**
- Identify ambiguities and ASK BEFORE creating files
- DO NOT write code in this phase
- Refer to openspec/AGENTS.md if unsure

**Steps**
1. Read openspec/project.md for project context
2. Run `openspec list` and `openspec list --specs`
3. Choose a unique change-id (verb-led, kebab-case)
4. Create proposal.md, tasks.md
5. Create design.md if needed
6. Create delta specs with ADDED/MODIFIED/REMOVED
7. Validate: `openspec validate <id> --strict`

Slash command: /openspec:apply¶

**Guardrails**
- Implement ONLY what is in proposal.md and specs/
- Do not change scope without a new proposal
- Mark tasks as done immediately after completion

**Steps**
1. Read proposal.md, design.md, tasks.md
2. Work through tasks sequentially
3. After finishing a task update tasks.md: `- [x]`
4. Run tests relevant to the change
5. Validate: `openspec validate <id> --strict`

Slash command: /openspec:archive¶

**Guardrails**
- Archive ONLY when all tasks are done
- Verify implementation matches the specification

**Steps**
1. Get the change ID from context or `openspec list`
2. Verify completion: `openspec show <id>`
3. Run: `openspec archive <id> --yes`
4. Check output for applied changes
5. Final validation: `openspec validate --specs`

Example end-to-end workflow¶

1. Client sends a request¶

"We need warehouse staff to scan barcodes instead of searching products manually."

2. Create the proposal¶

mkdir -p openspec/changes/add-barcode-scanning/specs/warehouse
# Write proposal.md, tasks.md, specs/warehouse/spec.md (delta)

3. Review and approval¶

openspec validate add-barcode-scanning --strict
openspec show add-barcode-scanning

4. Implementation¶

# Builder agent implements according to tasks.md
# Marks tasks as done along the way

5. Testing¶

# QA agent generates tests from Gherkin
# Runs Playwright tests

6. Archive¶

openspec archive add-barcode-scanning --yes

➡️ For AI agent architecture overview see AI Agent Architecture.