# OpenSpec Best Practices

## Change Management

### Keep Changes Atomic

✅ **Good**: One focused change per folder
```
openspec/changes/add-2fa/
openspec/changes/add-profile-search/
```

❌ **Bad**: Multiple unrelated changes in one folder
```
openspec/changes/misc-improvements/  # Too vague
```

### Use Descriptive Names

✅ **Good**: Clear, specific names
- `add-2fa`
- `fix-login-timeout`
- `refactor-auth-flow`

❌ **Bad**: Generic or cryptic names
- `feature-123`
- `updates`
- `fix`

### Review Before Implementation

Always review and iterate on specs before coding:

1. Create proposal and specs
2. Review with stakeholders
3. Refine until agreement
4. Then implement

**Why**: Catching issues in specs is 10x cheaper than in code.

## Specification Writing

### Be Specific

✅ **Good**: Concrete, testable requirements
```markdown
### Requirement: Session Timeout
The system SHALL terminate sessions after 30 minutes of inactivity.

#### Scenario: Inactive session
- GIVEN a user is logged in
- WHEN 30 minutes pass with no activity
- THEN the session is terminated
- AND the user is redirected to login
```

❌ **Bad**: Vague requirements
```markdown
### Requirement: Security
The system should be secure.
```

### Include Edge Cases

✅ **Good**: Cover error scenarios
```markdown
#### Scenario: Invalid OTP
- WHEN a user submits an invalid OTP
- THEN an error message is displayed
- AND the user can retry up to 3 times
- AND after 3 failures, the account is locked

#### Scenario: Expired OTP
- WHEN a user submits an expired OTP (>5 minutes old)
- THEN an error message is displayed
- AND a new OTP can be requested
```

### Use Consistent Language

- **SHALL** - Mandatory requirement
- **MUST** - Mandatory requirement (stronger emphasis)
- **SHOULD** - Recommended but not mandatory
- **MAY** - Optional feature

## Task Management

### Break Down Large Tasks

✅ **Good**: Granular, actionable tasks
```markdown
## 2. Backend Implementation
- [ ] 2.1 Create OTP model with secret and expiry fields
- [ ] 2.2 Add OTP generation function using TOTP algorithm
- [ ] 2.3 Add OTP verification function with rate limiting
- [ ] 2.4 Update login endpoint to require OTP
- [ ] 2.5 Add OTP enrollment endpoint
```

❌ **Bad**: Vague, large tasks
```markdown
## 2. Backend
- [ ] 2.1 Implement 2FA
```

### Group Related Tasks

Organize tasks by phase or component:

```markdown
## 1. Database Setup
- [ ] 1.1 Add OTP secret column
- [ ] 1.2 Add OTP logs table
- [ ] 1.3 Create migration

## 2. Backend API
- [ ] 2.1 OTP generation endpoint
- [ ] 2.2 OTP verification endpoint

## 3. Frontend UI
- [ ] 3.1 OTP input component
- [ ] 3.2 Update login flow
```

### Update Tasks During Implementation

If scope changes during implementation, update tasks.md:

```markdown
## 2. Backend Implementation
- [x] 2.1 Create OTP model
- [x] 2.2 Add OTP generation
- [ ] 2.3 Add OTP verification
- [ ] 2.4 Add rate limiting (ADDED during implementation)
```

## Multi-Spec Changes

### When Changes Affect Multiple Components

Create deltas for each affected spec:

```
openspec/changes/add-user-roles/
├── proposal.md
├── tasks.md
└── specs/
    ├── auth/
    │   └── spec.md      # Auth changes
    ├── users/
    │   └── spec.md      # User model changes
    └── permissions/
        └── spec.md      # Permission system changes
```

### Reference Dependencies

In proposal.md, note cross-component dependencies:

```markdown
## Dependencies
- Auth spec changes depend on User model changes
- Permission checks require Auth changes to be complete
```

## Archiving

### Archive Promptly

Don't let completed changes accumulate in `openspec/changes/`:

```bash
# With CLI
openspec archive add-2fa --yes

# Without CLI - move to archive
mv openspec/changes/add-2fa openspec/archive/
```

### Keep Archive Organized

Archive folder structure:

```
openspec/archive/
├── 2024-01-add-2fa/
├── 2024-01-profile-search/
└── 2024-02-role-permissions/
```

Consider adding date prefixes for chronological ordering.

## Project Context

### Keep project.md Updated

Update `openspec/project.md` when:
- Tech stack changes
- New conventions are adopted
- Architecture evolves
- New guidelines are established

### Include Examples

Add examples to project.md:

```markdown
## Naming Conventions

### API Endpoints
- Use kebab-case: `/api/user-profiles`
- Use plural nouns: `/api/users` not `/api/user`
- Version with prefix: `/api/v1/users`

### Database Tables
- Use snake_case: `user_profiles`
- Use plural nouns: `users` not `user`
```

## AI Agent Collaboration

### Provide Context

When asking AI to create changes:

```
Create an OpenSpec change for adding role-based permissions.
Context: We have 3 roles (admin, editor, viewer) and need to restrict
access to certain API endpoints based on role.
```

### Iterate on Specs

Don't accept first draft:

```
The spec looks good, but can you add scenarios for:
1. What happens when a user has multiple roles?
2. How do we handle role changes for active sessions?
```

### Reference Existing Specs

When implementing:

```
Please implement the tasks in openspec/changes/add-roles/tasks.md
Make sure to follow the patterns established in openspec/specs/auth/spec.md
```

## Common Pitfalls

### ❌ Skipping Spec Review

Don't jump straight to implementation. Review specs first.

### ❌ Vague Requirements

Avoid "should work well" or "be fast". Be specific with numbers and behaviors.

### ❌ Missing Scenarios

Every requirement needs at least one scenario showing how it works.

### ❌ Forgetting to Archive

Clean up completed changes to keep the workspace organized.

### ❌ Mixing Concerns

Keep each change focused on one feature or fix.

