name: openspec-feature-dev
description: OpenSpec-driven feature development workflow. Enforces spec-first approach where requirements are documented BEFORE code is written. Use when starting new features, planning refactors, or implementing changes that need clear requirements. Triggers on requests like "add feature X", "implement Y", "refactor Z", "start new feature", or when working on complex multi-step implementations. Requires OpenSpec initialized in project (openspec init).

OpenSpec Feature Development Skill

Spec-first feature development using OpenSpec framework. Forces agreement on what to build before writing any code.

Philosophy

"Fluid not rigid, iterative not waterfall."

OpenSpec uses a delta-based approach suitable for brownfield projects. Instead of rewriting entire specs, you describe ADDED/MODIFIED/REMOVED requirements.

Prerequisites

# Install OpenSpec CLI
npm install -g openspec

# Initialize in project (first time only)
openspec init

Directory Structure

After initialization, your project will have:

openspec/
├── .openspec.yaml        # Project configuration
├── specs/                # SOURCE OF TRUTH (current system behavior)
│   ├── auth/spec.md
│   └── ui/spec.md
└── changes/              # WORK IN PROGRESS
    ├── add-dark-mode/    # Self-contained change folder
    │   ├── .openspec.yaml
    │   ├── proposal.md   # The "Why" and "What"
    │   ├── design.md     # The "How"
    │   ├── tasks.md      # The "Steps"
    │   └── specs/        # Delta specs for this change
    │       └── ui/spec.md
    └── archive/          # Completed changes

Core Workflow

Phase 1: Start a Change

/opsx:new <feature-name>

Creates a new change folder under openspec/changes/<feature-name>/.

Phase 2: Generate Planning Artifacts

/opsx:ff

"Fast Forward" - generates all artifacts in sequence:
1. proposal.md - Intent and scope
2. specs/*.md - Delta requirements (ADDED/MODIFIED/REMOVED)
3. design.md - Technical approach
4. tasks.md - Implementation checklist

Or use /opsx:continue to generate one artifact at a time.

Phase 3: Implement

/opsx:apply

Executes tasks from tasks.md, writing code and checking off items.

IMPORTANT: Clear your AI context window before this phase to prevent hallucinations.

Phase 4: Verify

/opsx:verify

Checks if implementation matches the specs and design.

Phase 5: Archive

/opsx:archive

Merges delta specs into main specs and moves the change folder to archive/.

Artifact Details

Proposal (proposal.md)

The Why and What. Captures:
- Problem statement
- User stories / use cases
- Success criteria
- Out of scope items

Specs (specs/*.md)

Uses RFC 2119 keywords (MUST, SHALL, SHOULD) and GIVEN/WHEN/THEN scenarios.

Delta Format (for changes):

## ADDED Requirements

### REQ-001: Dark Mode Toggle
The system MUST provide a toggle in Settings to switch between light and dark themes.

#### Scenarios
GIVEN the user is on the Settings page
WHEN they tap the "Dark Mode" toggle
THEN the app theme MUST change immediately

## MODIFIED Requirements

### REQ-042: Theme Colors (Original: REQ-042)
[Copy entire original requirement, then modify]

## REMOVED Requirements

### REQ-015: Legacy Theme Selector
[Reason for removal]

Design (design.md)

The How. Technical decisions:
- Architecture approach
- Component breakdown
- Data flow
- API changes
- Migration strategy (if applicable)

Tasks (tasks.md)

Implementation checklist:

- [ ] Create ThemeManager class
- [ ] Add dark mode color palette to theme.xml
- [ ] Update Settings UI with toggle switch
- [ ] Implement theme persistence in SharedPreferences
- [ ] Update all screens to use dynamic theme colors
- [ ] Write unit tests for ThemeManager
- [ ] Write UI tests for theme switching

Slash Commands Reference

CLI Commands

openspec init      # Initialize OpenSpec in project
openspec update    # Refresh AI instructions
openspec status    # Check active changes state
openspec list      # List all changes

Best Practices

1. Context Hygiene

Clear your AI context window before /opsx:apply phase. Large context = more hallucinations.

2. Model Selection

Use high-reasoning models for planning phases:
- Claude Opus/Sonnet for specs
- GPT-4o for design decisions

3. Atomic Changes

Keep changes small. If tasks.md grows beyond 15-20 items, split into multiple changes.

4. Review Before Apply

ALWAYS read and approve:
- proposal.md - Does it capture your intent?
- specs/*.md - Are requirements complete?
- design.md - Is the approach sound?

Only then run /opsx:apply.

5. Delta Discipline

When modifying existing specs, copy the entire requirement block into ## MODIFIED section to preserve context.

6. Spec-First Debugging

When a bug is found:
1. First update specs to clarify expected behavior
2. Then fix code to match specs
3. Never just fix code without spec clarity

Integration with Development Workflow

Starting a Feature

1. Discuss requirements with stakeholders
2. /opsx:new feature-name
3. /opsx:ff to generate artifacts
4. Review and iterate on proposal/specs
5. Get approval on design
6. /opsx:apply to implement
7. /opsx:verify to validate
8. Code review & merge
9. /opsx:archive to close

Handling Scope Creep

If requirements change during implementation:
1. Stop current work
2. Update proposal.md and specs/*.md
3. Regenerate design.md and tasks.md if needed
4. Continue implementation

Brownfield Projects

For existing codebases without specs:
1. Run /opsx:onboard to get familiar
2. Create baseline specs for affected areas
3. Then proceed with delta-based changes

Common Patterns

Feature Flag Gated Release

## ADDED Requirements

### REQ-101: Feature Flag for Dark Mode
The Dark Mode feature MUST be gated behind a feature flag `dark_mode_enabled`.

#### Scenarios
GIVEN the feature flag is disabled
WHEN the user opens Settings
THEN the Dark Mode toggle MUST NOT be visible

A/B Testing Consideration

### REQ-102: Dark Mode Analytics
The system MUST track theme toggle events with:
- Event name: `theme_changed`
- Properties: `from_theme`, `to_theme`, `trigger_location`

Migration Path

## Design: Migration Strategy

### Phase 1: Shadow Mode
- Deploy dark colors alongside light
- No user-facing changes

### Phase 2: Opt-in Beta
- Enable for beta users via feature flag

### Phase 3: General Availability
- Enable for all users
- Remove feature flag

Troubleshooting

References

• references/spec-writing-guide.md - How to write good specifications
• references/delta-patterns.md - Common delta spec patterns
• references/workflow-examples.md - End-to-end workflow examples