|
|
|
@@ -1,302 +0,0 @@
|
|
|
|
|
---
|
|
|
|
|
description: OpenSpec conventions and workflow for Cursor agents working in this repo
|
|
|
|
|
alwaysApply: false
|
|
|
|
|
---
|
|
|
|
|
# OpenSpec Rules for Cursor Agents
|
|
|
|
|
|
|
|
|
|
Instructions for AI coding assistants using OpenSpec for spec-driven development.
|
|
|
|
|
|
|
|
|
|
## Three-Stage Workflow
|
|
|
|
|
|
|
|
|
|
### Stage 1: Creating Changes
|
|
|
|
|
Create proposal when you need to:
|
|
|
|
|
- Add features or functionality
|
|
|
|
|
- Make breaking changes (API, schema)
|
|
|
|
|
- Change architecture or patterns
|
|
|
|
|
- Optimize performance (changes behavior)
|
|
|
|
|
- Update security patterns
|
|
|
|
|
|
|
|
|
|
Skip proposal for:
|
|
|
|
|
- Bug fixes (restore intended behavior)
|
|
|
|
|
- Typos, formatting, comments
|
|
|
|
|
- Dependency updates (non-breaking)
|
|
|
|
|
- Configuration changes
|
|
|
|
|
- Tests for existing behavior
|
|
|
|
|
|
|
|
|
|
### Stage 2: Implementing Changes
|
|
|
|
|
1. **Read proposal.md** - Understand what's being built
|
|
|
|
|
2. **Read design.md** (if exists) - Review technical decisions
|
|
|
|
|
3. **Read tasks.md** - Get implementation checklist
|
|
|
|
|
4. **Implement tasks sequentially** - Complete in order
|
|
|
|
|
5. **Mark complete immediately** - Update `- [x]` after each task
|
|
|
|
|
|
|
|
|
|
### Stage 3: Archiving Changes
|
|
|
|
|
After deployment, create separate PR to:
|
|
|
|
|
- Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/`
|
|
|
|
|
- Update `specs/` if capabilities changed
|
|
|
|
|
- Use `openspec archive [change] --skip-specs` for tooling-only changes
|
|
|
|
|
|
|
|
|
|
## Before Any Task
|
|
|
|
|
|
|
|
|
|
**Context Checklist:**
|
|
|
|
|
- [ ] Read relevant specs in `specs/[capability]/spec.md`
|
|
|
|
|
- [ ] Check pending changes in `changes/` for conflicts
|
|
|
|
|
- [ ] Read `openspec/project.md` for conventions
|
|
|
|
|
- [ ] Run `openspec list` to see active changes
|
|
|
|
|
- [ ] Run `openspec list --specs` to see existing capabilities
|
|
|
|
|
|
|
|
|
|
**Before Creating Specs:**
|
|
|
|
|
- Always check if capability already exists
|
|
|
|
|
- Prefer modifying existing specs over creating duplicates
|
|
|
|
|
- Use `openspec show [spec]` to review current state
|
|
|
|
|
|
|
|
|
|
## Quick Start
|
|
|
|
|
|
|
|
|
|
### CLI Commands
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# Essential commands
|
|
|
|
|
openspec list # List active changes
|
|
|
|
|
openspec list --specs # List specifications
|
|
|
|
|
openspec show [item] # Display change or spec
|
|
|
|
|
openspec diff [change] # Show spec differences
|
|
|
|
|
openspec validate [item] # Validate changes or specs
|
|
|
|
|
openspec archive [change] # Archive after deployment
|
|
|
|
|
|
|
|
|
|
# Project management
|
|
|
|
|
openspec init [path] # Initialize OpenSpec
|
|
|
|
|
openspec update [path] # Update instruction files
|
|
|
|
|
|
|
|
|
|
# Interactive mode
|
|
|
|
|
openspec show # Prompts for selection
|
|
|
|
|
openspec validate # Bulk validation mode
|
|
|
|
|
|
|
|
|
|
# Debugging
|
|
|
|
|
openspec show [change] --json --deltas-only
|
|
|
|
|
openspec validate [change] --strict
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Command Flags
|
|
|
|
|
|
|
|
|
|
- `--json` - Machine-readable output
|
|
|
|
|
- `--type change|spec` - Disambiguate items
|
|
|
|
|
- `--strict` - Comprehensive validation
|
|
|
|
|
- `--no-interactive` - Disable prompts
|
|
|
|
|
- `--skip-specs` - Archive without spec updates
|
|
|
|
|
|
|
|
|
|
## Directory Structure
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
openspec/
|
|
|
|
|
├── project.md # Project conventions
|
|
|
|
|
├── specs/ # Current truth - what IS built
|
|
|
|
|
│ └── [capability]/ # Single focused capability
|
|
|
|
|
│ ├── spec.md # Requirements and scenarios
|
|
|
|
|
│ └── design.md # Technical patterns
|
|
|
|
|
├── changes/ # Proposals - what SHOULD change
|
|
|
|
|
│ ├── [change-name]/
|
|
|
|
|
│ │ ├── proposal.md # Why, what, impact
|
|
|
|
|
│ │ ├── tasks.md # Implementation checklist
|
|
|
|
|
│ │ ├── design.md # Technical decisions (optional)
|
|
|
|
|
│ │ └── specs/ # Delta changes
|
|
|
|
|
│ │ └── [capability]/
|
|
|
|
|
│ │ └── spec.md # ADDED/MODIFIED/REMOVED
|
|
|
|
|
│ └── archive/ # Completed changes
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Creating Change Proposals
|
|
|
|
|
|
|
|
|
|
### Decision Tree
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
New request?
|
|
|
|
|
├─ Bug fix restoring spec behavior? → Fix directly
|
|
|
|
|
├─ Typo/format/comment? → Fix directly
|
|
|
|
|
├─ New feature/capability? → Create proposal
|
|
|
|
|
├─ Breaking change? → Create proposal
|
|
|
|
|
├─ Architecture change? → Create proposal
|
|
|
|
|
└─ Unclear? → Create proposal (safer)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Proposal Structure
|
|
|
|
|
|
|
|
|
|
1. **Create directory:** `changes/[descriptive-name]/`
|
|
|
|
|
|
|
|
|
|
2. **Write proposal.md:**
|
|
|
|
|
```markdown
|
|
|
|
|
## Why
|
|
|
|
|
[1-2 sentences on problem/opportunity]
|
|
|
|
|
|
|
|
|
|
## What Changes
|
|
|
|
|
- [Bullet list of changes]
|
|
|
|
|
- [Mark breaking changes with **BREAKING**]
|
|
|
|
|
|
|
|
|
|
## Impact
|
|
|
|
|
- Affected specs: [list capabilities]
|
|
|
|
|
- Affected code: [key files/systems]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
3. **Create spec deltas:** `specs/[capability]/spec.md`
|
|
|
|
|
```markdown
|
|
|
|
|
## ADDED Requirements
|
|
|
|
|
### Requirement: New Feature
|
|
|
|
|
The system SHALL provide...
|
|
|
|
|
|
|
|
|
|
#### Scenario: Success case
|
|
|
|
|
- **WHEN** user performs action
|
|
|
|
|
- **THEN** expected result
|
|
|
|
|
|
|
|
|
|
## MODIFIED Requirements
|
|
|
|
|
### Requirement: Existing Feature
|
|
|
|
|
[Complete modified requirement]
|
|
|
|
|
|
|
|
|
|
## REMOVED Requirements
|
|
|
|
|
### Requirement: Old Feature
|
|
|
|
|
**Reason**: [Why removing]
|
|
|
|
|
**Migration**: [How to handle]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
4. **Create tasks.md:**
|
|
|
|
|
```markdown
|
|
|
|
|
## 1. Implementation
|
|
|
|
|
- [ ] 1.1 Create database schema
|
|
|
|
|
- [ ] 1.2 Implement API endpoint
|
|
|
|
|
- [ ] 1.3 Add frontend component
|
|
|
|
|
- [ ] 1.4 Write tests
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Spec File Format
|
|
|
|
|
|
|
|
|
|
### Critical: Scenario Formatting
|
|
|
|
|
|
|
|
|
|
**CORRECT** (use #### headers):
|
|
|
|
|
```markdown
|
|
|
|
|
#### Scenario: User login success
|
|
|
|
|
- **WHEN** valid credentials provided
|
|
|
|
|
- **THEN** return JWT token
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**WRONG** (don't use bullets or bold):
|
|
|
|
|
```markdown
|
|
|
|
|
- **Scenario: User login** ❌
|
|
|
|
|
**Scenario**: User login ❌
|
|
|
|
|
### Scenario: User login ❌
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Every requirement MUST have at least one scenario.
|
|
|
|
|
|
|
|
|
|
### Delta Operations
|
|
|
|
|
|
|
|
|
|
- `## ADDED Requirements` - New capabilities
|
|
|
|
|
- `## MODIFIED Requirements` - Changed behavior
|
|
|
|
|
- `## REMOVED Requirements` - Deprecated features
|
|
|
|
|
- `## RENAMED Requirements` - Name changes
|
|
|
|
|
|
|
|
|
|
Headers matched with `trim(header)` - whitespace ignored.
|
|
|
|
|
|
|
|
|
|
## Troubleshooting
|
|
|
|
|
|
|
|
|
|
### Common Errors
|
|
|
|
|
|
|
|
|
|
**"Change must have at least one delta"**
|
|
|
|
|
- Check `changes/[name]/specs/` exists with .md files
|
|
|
|
|
- Verify files have operation prefixes (## ADDED Requirements)
|
|
|
|
|
|
|
|
|
|
**"Requirement must have at least one scenario"**
|
|
|
|
|
- Check scenarios use `#### Scenario:` format (4 hashtags)
|
|
|
|
|
- Don't use bullet points or bold for scenario headers
|
|
|
|
|
|
|
|
|
|
**Silent scenario parsing failures**
|
|
|
|
|
- Exact format required: `#### Scenario: Name`
|
|
|
|
|
- Debug with: `openspec show [change] --json --deltas-only`
|
|
|
|
|
|
|
|
|
|
### Validation Tips
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# Always use strict mode for comprehensive checks
|
|
|
|
|
openspec validate [change] --strict
|
|
|
|
|
|
|
|
|
|
# Debug delta parsing
|
|
|
|
|
openspec show [change] --json | jq '.deltas'
|
|
|
|
|
|
|
|
|
|
# Check specific requirement
|
|
|
|
|
openspec show [spec] --json -r 1
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Best Practices
|
|
|
|
|
|
|
|
|
|
### Simplicity First
|
|
|
|
|
- Default to <100 lines of new code
|
|
|
|
|
- Single-file implementations until proven insufficient
|
|
|
|
|
- Avoid frameworks without clear justification
|
|
|
|
|
- Choose boring, proven patterns
|
|
|
|
|
|
|
|
|
|
### Complexity Triggers
|
|
|
|
|
Only add complexity with:
|
|
|
|
|
- Performance data showing current solution too slow
|
|
|
|
|
- Concrete scale requirements (>1000 users, >100MB data)
|
|
|
|
|
- Multiple proven use cases requiring abstraction
|
|
|
|
|
|
|
|
|
|
### Clear References
|
|
|
|
|
- Use `file.ts:42` format for code locations
|
|
|
|
|
- Reference specs as `specs/auth/spec.md`
|
|
|
|
|
- Link related changes and PRs
|
|
|
|
|
|
|
|
|
|
### Capability Naming
|
|
|
|
|
- Use verb-noun: `user-auth`, `payment-capture`
|
|
|
|
|
- Single purpose per capability
|
|
|
|
|
- 10-minute understandability rule
|
|
|
|
|
- Split if description needs "AND"
|
|
|
|
|
|
|
|
|
|
## Tool Selection Guide
|
|
|
|
|
|
|
|
|
|
| Task | Tool | Why |
|
|
|
|
|
|------|------|-----|
|
|
|
|
|
| Find files by pattern | Glob | Fast pattern matching |
|
|
|
|
|
| Search code content | Grep | Optimized regex search |
|
|
|
|
|
| Read specific files | Read | Direct file access |
|
|
|
|
|
| Explore unknown scope | Task | Multi-step investigation |
|
|
|
|
|
|
|
|
|
|
## Error Recovery
|
|
|
|
|
|
|
|
|
|
### Change Conflicts
|
|
|
|
|
1. Run `openspec list` to see active changes
|
|
|
|
|
2. Check for overlapping specs
|
|
|
|
|
3. Coordinate with change owners
|
|
|
|
|
4. Consider combining proposals
|
|
|
|
|
|
|
|
|
|
### Validation Failures
|
|
|
|
|
1. Run with `--strict` flag
|
|
|
|
|
2. Check JSON output for details
|
|
|
|
|
3. Verify spec file format
|
|
|
|
|
4. Ensure scenarios properly formatted
|
|
|
|
|
|
|
|
|
|
### Missing Context
|
|
|
|
|
1. Read project.md first
|
|
|
|
|
2. Check related specs
|
|
|
|
|
3. Review recent archives
|
|
|
|
|
4. Ask for clarification
|
|
|
|
|
|
|
|
|
|
## Quick Reference
|
|
|
|
|
|
|
|
|
|
### Stage Indicators
|
|
|
|
|
- `changes/` - Proposed, not yet built
|
|
|
|
|
- `specs/` - Built and deployed
|
|
|
|
|
- `archive/` - Completed changes
|
|
|
|
|
|
|
|
|
|
### File Purposes
|
|
|
|
|
- `proposal.md` - Why and what
|
|
|
|
|
- `tasks.md` - Implementation steps
|
|
|
|
|
- `design.md` - Technical decisions
|
|
|
|
|
- `spec.md` - Requirements and behavior
|
|
|
|
|
|
|
|
|
|
### CLI Essentials
|
|
|
|
|
```bash
|
|
|
|
|
openspec list # What's in progress?
|
|
|
|
|
openspec show [item] # View details
|
|
|
|
|
openspec diff [change] # What's changing?
|
|
|
|
|
openspec validate --strict # Is it correct?
|
|
|
|
|
openspec archive [change] # Mark complete
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Remember: Specs are truth. Changes are proposals. Keep them in sync.
|
Tabish Bidiwale