openspec

# OpenSpec — Spec-Driven Development OpenSpec structures AI-assisted development into trackable changes with artifacts (proposal, specs, design, tasks) that guide implementation. ## Setup ```bash # Install globally npm install -g @fission-ai/openspec@latest # Initialize in a project cd /path/to/project openspec init --tools claude # Update after CLI upgrade openspec update ``` ## Core Workflow Each change follows: **new → plan → apply → verify → archive** ### 1. Start a Change ```bash # Create change folder with default schema openspec new change <name> # With specific schema openspec new change <name> --schema tdd-driven ``` ### 2. Plan (Create Artifacts) Use the CLI `instructions` command to get enriched prompts for each artifact: ```bash # Get instructions for next artifact openspec instructions --change <name> --json # Check progress openspec status --change <name> --json ``` **Artifact sequence (spec-driven schema):** 1. `proposal.md` — Why and what (intent, scope, approach) 2. `specs/` — Requirements + scenarios (Given/When/Then) 3. `design.md` — Technical approach and architecture decisions 4. `tasks.md` — Implementation checklist with checkboxes ### 3. Implement Read `tasks.md` and work through items, marking `[x]` as complete. ### 4. Verify ```bash openspec validate --change <name> --json ``` Checks completeness, correctness, and coherence. ### 5. Archive ```bash openspec archive <name> --yes ``` Merges delta specs into main `openspec/specs/` and moves change to archive. ## Agent Workflow (How to Use as an AI Agent) When the user asks to build/migrate/refactor something with OpenSpec: 1. **Check project state:** ```bash openspec list --json # Active changes openspec list --specs --json # Current specs openspec schemas --json # Available schemas ``` 2. **Create the change:** ```bash openspec new change <name> [--schema <schema>] ``` 3. **For each artifact**, get instructions and create the file: ```bash openspec instructions <artifact> --change <name> --json openspec status --change <name> --json ``` Then write the artifact file to `openspec/changes/<name>/`. 4. **Implement** tasks from `tasks.md`. 5. **Validate and archive:** ```bash openspec validate <name> --json openspec archive <name> --yes ``` ## CLI Quick Reference | Command | Purpose | |---------|---------| | `openspec list [--specs] [--json]` | List changes or specs | | `openspec show <name> [--json]` | Show change/spec details | | `openspec status --change <name> [--json]` | Artifact completion status | | `openspec instructions [artifact] --change <name> [--json]` | Get enriched creation instructions | | `openspec validate [name] [--all] [--json]` | Validate changes/specs | | `openspec archive <name> [--yes]` | Archive completed change | | `openspec schemas [--json]` | List available schemas | | `openspec templates [--json]` | Show template paths | | `openspec config` | View/modify settings | Always use `--json` for programmatic/agent use. ## Custom Schemas Schemas define artifact sequences. Create custom ones for different workflows: ```bash # Fork built-in schema openspec schema fork spec-driven my-workflow # Create from scratch openspec schema init my-workflow # Validate openspec schema validate my-workflow ``` Schema files live in `openspec/schemas/<name>/schema.yaml` with templates in `templates/`. For schema structure details, see [references/schemas.md](references/schemas.md). ## Project Structure ``` project/ ├── openspec/ │ ├── config.yaml # Project config (default schema, context, rules) │ ├── specs/ # Source of truth — current system behavior │ ├── changes/ # Active changes (one folder each) │ │ └── <change-name>/ │ │ ├── .openspec.yaml │ │ ├── proposal.md │ │ ├── specs/ # Delta specs (what's changing) │ │ ├── design.md │ │ └── tasks.md │ └── schemas/ # Custom schemas └── .claude/skills/ # Auto-generated Claude integration ``` ## Spec Format Specs use RFC 2119 keywords (SHALL/MUST/SHOULD/MAY) with Given/When/Then scenarios: ```markdown ### Requirement: User Authentication The system SHALL issue a JWT token upon successful login. #### Scenario: Valid credentials - GIVEN a user with valid credentials - WHEN the user submits login form - THEN a JWT token is returned ``` ## Delta Specs Changes don't rewrite specs — they describe deltas (ADDED/MODIFIED/REMOVED) that merge into main specs on archive. ## Config `openspec/config.yaml` sets defaults: ```yaml schema: spec-driven # or tdd-driven, rapid, custom context: | Tech stack: TypeScript, React, Node.js Testing: Jest rules: proposal: - Include rollback plan specs: - Use Given/When/Then format ```