Spec-driven development for AI coding assistants.

OpenSplx

Fork Notice: OpenSplx is a community fork of OpenSpec. It adds the plx command alias and extended features while maintaining full compatibility with the original OpenSpec workflow.

What's Different in OpenSplx

Feature	OpenSpec	OpenSplx
Command	openspec	openspec + plx alias
Task Structure	Single tasks.md	tasks/ directory with numbered files
Task Status	Checkbox-based	YAML frontmatter (to-do, in-progress, done)
Task Selection	Manual	plx get task for prioritized selection
Item Retrieval	—	get change, get spec, get tasks by ID
Content Filtering	—	--constraints, --acceptance-criteria flags
Auto-completion	—	Detects fully checked tasks, auto-advances
Architecture Docs	openspec/project.md	ARCHITECTURE.md
Issue Tracking	—	External issue tracking in proposals
Install	npm i -g @fission-ai/openspec	npm i -g @appboypov/opensplx

Task Directory Structure

OpenSplx uses a tasks/ directory with numbered task files instead of a single tasks.md:

tasks/
├── 001-<first-task>.md
├── 002-<second-task>.md
└── NNN-<last-task>.md

Each task file is scoped for one AI conversation. The apply command auto-detects the next incomplete task and processes only that one. Legacy tasks.md files are auto-migrated on first CLI access.

Get Command

OpenSplx extends the get command with subcommands for retrieving project artifacts:

# Task retrieval and workflow
plx get task                          # Get the next prioritized task
plx get task --id 001-implement       # Get specific task by filename
plx get task --did-complete-previous  # Mark current task done, get next
plx get task --constraints            # Show only Constraints section
plx get task --acceptance-criteria    # Show only Acceptance Criteria section

# Item retrieval by ID
plx get change --id add-feature       # Retrieve change proposal by ID
plx get spec --id user-auth           # Retrieve spec by ID
plx get tasks                         # List all open tasks
plx get tasks --id add-feature        # List tasks for specific change

# All commands support --json for machine-readable output

Prioritization logic:

1. Changes with highest completion percentage are prioritized first
2. When percentages are equal, older proposals (by birthtime) take precedence
3. Within a change, finds the first task with status: to-do or status: in-progress

Task status tracking: Tasks use YAML frontmatter for status:

---
status: to-do  # or: in-progress, done
---

Checkbox auto-completion: When using --did-complete-previous, all checkboxes in the ## Implementation Checklist section are automatically marked as complete. Checkboxes in ## Constraints and ## Acceptance Criteria sections are preserved unchanged.

Automatic task completion: When running plx get task, if the current in-progress task has all Implementation Checklist items checked, it is automatically marked as done and the next to-do task is marked as in-progress. The output shows the new task without repeating change documents. JSON output includes an autoCompletedTask field when this occurs.

Content filtering: Use --constraints and --acceptance-criteria to filter task output to specific sections. Combine flags to show multiple sections.

PLX Slash Commands

When you run plx init, these additional commands are installed:

• /plx/get-task - Get the next prioritized task across active changes
• /plx/init-architecture - Generate comprehensive ARCHITECTURE.md from codebase analysis
• /plx/update-architecture - Refresh architecture documentation based on current codebase state

Quick Start (OpenSplx)

npm install -g @appboypov/opensplx
plx --version  # or openspec --version

---

Original OpenSpec Documentation (click to expand)

Follow @0xTab on X for updates · Join the OpenSpec Discord for help and questions.

OpenSpec

OpenSpec aligns humans and AI coding assistants with spec-driven development so you agree on what to build before any code is written. No API keys required.

Why OpenSpec?

AI coding assistants are powerful but unpredictable when requirements live in chat history. OpenSpec adds a lightweight specification workflow that locks intent before implementation, giving you deterministic, reviewable outputs.

Key outcomes:

• Human and AI stakeholders agree on specs before work begins.
• Structured change folders (proposals, tasks, and spec updates) keep scope explicit and auditable.
• Shared visibility into what's proposed, active, or archived.
• Works with the AI tools you already use: custom slash commands where supported, context rules everywhere else.

How OpenSpec compares (at a glance)

• Lightweight: simple workflow, no API keys, minimal setup.
• Brownfield-first: works great beyond 0→1. OpenSpec separates the source of truth from proposals: openspec/specs/ (current truth) and openspec/changes/ (proposed updates). This keeps diffs explicit and manageable across features.
• Change tracking: proposals, tasks, and spec deltas live together; archiving merges the approved updates back into specs.
• Compared to spec-kit & Kiro: those shine for brand-new features (0→1). OpenSpec also excels when modifying existing behavior (1→n), especially when updates span multiple specs.

See the full comparison in How OpenSpec Compares.

How It Works

┌────────────────────┐
│ Draft Change       │
│ Proposal           │
└────────┬───────────┘
         │ share intent with your AI
         ▼
┌────────────────────┐
│ Review & Align     │
│ (edit specs/tasks) │◀──── feedback loop ──────┐
└────────┬───────────┘                          │
         │ approved plan                        │
         ▼                                      │
┌────────────────────┐                          │
│ Implement Tasks    │──────────────────────────┘
│ (AI writes code)   │
└────────┬───────────┘
         │ ship the change
         ▼
┌────────────────────┐
│ Archive & Update   │
│ Specs (source)     │
└────────────────────┘

1. Draft a change proposal that captures the spec updates you want.
2. Review the proposal with your AI assistant until everyone agrees.
3. Implement tasks that reference the agreed specs.
4. Archive the change to merge the approved updates back into the source-of-truth specs.

Getting Started

Supported AI Tools

Native Slash Commands (click to expand)

These tools have built-in OpenSpec commands. Select the OpenSpec integration when prompted.

Tool	Commands
Amazon Q Developer	@openspec-proposal, @openspec-apply, @openspec-archive (.amazonq/prompts/)
Antigravity	/openspec-proposal, /openspec-apply, /openspec-archive (.agent/workflows/)
Auggie (Augment CLI)	/openspec-proposal, /openspec-apply, /openspec-archive (.augment/commands/)
Claude Code	/openspec:proposal, /openspec:apply, /openspec:archive
Cline	Workflows in .clinerules/workflows/ directory (.clinerules/workflows/openspec-*.md)
CodeBuddy Code (CLI)	/openspec:proposal, /openspec:apply, /openspec:archive (.codebuddy/commands/) — see docs
Codex	/openspec-proposal, /openspec-apply, /openspec-archive (global: ~/.codex/prompts, auto-installed)
CoStrict	/openspec-proposal, /openspec-apply, /openspec-archive (.cospec/openspec/commands/) — see docs
Crush	/openspec-proposal, /openspec-apply, /openspec-archive (.crush/commands/openspec/)
Cursor	/openspec-proposal, /openspec-apply, /openspec-archive
Factory Droid	/openspec-proposal, /openspec-apply, /openspec-archive (.factory/commands/)
Gemini CLI	/openspec:proposal, /openspec:apply, /openspec:archive (.gemini/commands/openspec/)
GitHub Copilot	/openspec-proposal, /openspec-apply, /openspec-archive (.github/prompts/)
iFlow (iflow-cli)	/openspec-proposal, /openspec-apply, /openspec-archive (.iflow/commands/)
Kilo Code	/openspec-proposal.md, /openspec-apply.md, /openspec-archive.md (.kilocode/workflows/)
OpenCode	/openspec-proposal, /openspec-apply, /openspec-archive
Qoder (CLI)	/openspec:proposal, /openspec:apply, /openspec:archive (.qoder/commands/openspec/) — see docs
Qwen Code	/openspec-proposal, /openspec-apply, /openspec-archive (.qwen/commands/)
RooCode	/openspec-proposal, /openspec-apply, /openspec-archive (.roo/commands/)
Windsurf	/openspec-proposal, /openspec-apply, /openspec-archive (.windsurf/workflows/)

Kilo Code discovers team workflows automatically. Save the generated files under .kilocode/workflows/ and trigger them from the command palette with /openspec-proposal.md, /openspec-apply.md, or /openspec-archive.md.

AGENTS.md Compatible (click to expand)

These tools automatically read workflow instructions from openspec/AGENTS.md. Ask them to follow the OpenSpec workflow if they need a reminder. Learn more about the AGENTS.md convention.

Tools
Amp • Jules • Others

Install & Initialize

Prerequisites

• Node.js >= 20.19.0 - Check your version with node --version

Step 1: Install the CLI globally

npm install -g @fission-ai/openspec@latest

Verify installation:

openspec --version

Step 2: Initialize OpenSpec in your project

Navigate to your project directory:

cd my-project

Run the initialization:

openspec init

What happens during initialization:

• You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder,etc.); other assistants always rely on the shared AGENTS.md stub
• OpenSpec automatically configures slash commands for the tools you choose and always writes a managed AGENTS.md hand-off at the project root
• A new openspec/ directory structure is created in your project

After setup:

• Primary AI tools can trigger /openspec workflows without additional configuration
• Run openspec list to verify the setup and view any active changes
• If your coding assistant doesn't surface the new slash commands right away, restart it. Slash commands are loaded at startup, so a fresh launch ensures they appear

Optional: Populate Architecture Documentation

After openspec init completes, you'll receive a suggested prompt to help populate your architecture documentation:

Populate your architecture documentation:
"Please read ARCHITECTURE.md and help me fill it out with details about my project, tech stack, and conventions"

Use ARCHITECTURE.md (at project root) to define project-level context, conventions, standards, architectural patterns, and other guidelines that should be followed across all changes.

Create Your First Change

Here's a real example showing the complete OpenSpec workflow. This works with any AI tool. Those with native slash commands will recognize the shortcuts automatically.

1. Draft the Proposal

Start by asking your AI to create a change proposal:

You: Create an OpenSpec change proposal for adding profile search filters by role and team
     (Shortcut for tools with slash commands: /openspec:proposal Add profile search filters)

AI:  I'll create an OpenSpec change proposal for profile filters.
     *Scaffolds openspec/changes/add-profile-filters/ with proposal.md, tasks.md, spec deltas.*

2. Verify & Review

Check that the change was created correctly and review the proposal:

$ openspec list                             # Confirm the change folder exists
$ openspec validate add-profile-filters     # Validate spec formatting
$ openspec show add-profile-filters         # Review proposal, tasks, and spec delta

3. Refine the Specs

Iterate on the specifications until they match your needs:

You: Can you add acceptance criteria for the role and team filters?

AI:  I'll update the spec delta with scenarios for role and team filters.
     *Edits openspec/changes/add-profile-filters/specs/profile/spec.md and tasks.md.*

4. Implement the Change

Once specs look good, start implementation:

You: The specs look good. Let's implement this change.
     (Shortcut for tools with slash commands: /openspec:apply add-profile-filters)

AI:  I'll work through the tasks in the add-profile-filters change.
     *Implements tasks from openspec/changes/add-profile-filters/tasks.md*
     *Marks tasks complete: Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓...*

5. Archive the Completed Change

After implementation is complete, archive the change:

AI:  All tasks are complete. The implementation is ready.

You: Please archive the change
     (Shortcut for tools with slash commands: /openspec:archive add-profile-filters)

AI:  I'll archive the add-profile-filters change.
    *Runs: openspec archive add-profile-filters --yes*
     ✓ Change archived successfully. Specs updated. Ready for the next feature!

Or run the command yourself in terminal:

$ openspec archive add-profile-filters --yes  # Archive the completed change without prompts

Note: Tools with native slash commands (Claude Code, CodeBuddy, Cursor, Codex, Qoder, RooCode) can use the shortcuts shown. All other tools work with natural language requests to "create an OpenSpec proposal", "apply the OpenSpec change", or "archive the change".

Command Reference

openspec list               # View active change folders
openspec view               # Interactive dashboard of specs and changes
openspec show <change>      # Display change details (proposal, tasks, spec updates)
openspec validate <change>  # Check spec formatting and structure
openspec archive <change> [--yes|-y]   # Move a completed change into archive/ (non-interactive with --yes)

Example: How AI Creates OpenSpec Files

When you ask your AI assistant to "add two-factor authentication", it creates:

openspec/
├── specs/
│   └── auth/
│       └── spec.md           # Current auth spec (if exists)
└── changes/
    └── add-2fa/              # AI creates this entire structure
        ├── proposal.md       # Why and what changes
        ├── tasks.md          # Implementation checklist
        ├── design.md         # Technical decisions (optional)
        └── specs/
            └── auth/
                └── spec.md   # Delta showing additions

AI-Generated Spec (created in openspec/specs/auth/spec.md):

# Auth Specification

## Purpose
Authentication and session management.

## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT on successful login.

#### Scenario: Valid credentials
- WHEN a user submits valid credentials
- THEN a JWT is returned

AI-Generated Change Delta (created in openspec/changes/add-2fa/specs/auth/spec.md):

# Delta for Auth

## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- WHEN a user submits valid credentials
- THEN an OTP challenge is required

AI-Generated Tasks (created in openspec/changes/add-2fa/tasks.md):

## 1. Database Setup
- [ ] 1.1 Add OTP secret column to users table
- [ ] 1.2 Create OTP verification logs table

## 2. Backend Implementation  
- [ ] 2.1 Add OTP generation endpoint
- [ ] 2.2 Modify login flow to require OTP
- [ ] 2.3 Add OTP verification endpoint

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

Important: You don't create these files manually. Your AI assistant generates them based on your requirements and the existing codebase.

Understanding OpenSpec Files

Delta Format

Deltas are "patches" that show how specs change:

• ## ADDED Requirements - New capabilities
• ## MODIFIED Requirements - Changed behavior (include complete updated text)
• ## REMOVED Requirements - Deprecated features

Format requirements:

• Use ### Requirement: <name> for headers
• Every requirement needs at least one #### Scenario: block
• Use SHALL/MUST in requirement text

How OpenSpec Compares

vs. spec-kit

OpenSpec’s two-folder model (openspec/specs/ for the current truth, openspec/changes/ for proposed updates) keeps state and diffs separate. This scales when you modify existing features or touch multiple specs. spec-kit is strong for greenfield/0→1 but provides less structure for cross-spec updates and evolving features.

vs. Kiro.dev

OpenSpec groups every change for a feature in one folder (openspec/changes/feature-name/), making it easy to track related specs, tasks, and designs together. Kiro spreads updates across multiple spec folders, which can make feature tracking harder.

vs. No Specs

Without specs, AI coding assistants generate code from vague prompts, often missing requirements or adding unwanted features. OpenSpec brings predictability by agreeing on the desired behavior before any code is written.

Team Adoption

1. Initialize OpenSpec – Run openspec init in your repo.
2. Start with new features – Ask your AI to capture upcoming work as change proposals.
3. Grow incrementally – Each change archives into living specs that document your system.
4. Stay flexible – Different teammates can use Claude Code, CodeBuddy, Cursor, or any AGENTS.md-compatible tool while sharing the same specs.

Run openspec update whenever someone switches tools so your agents pick up the latest instructions and slash-command bindings.

Updating OpenSpec

1. Upgrade the package

   npm install -g @fission-ai/openspec@latest

2. Refresh agent instructions
   • Run openspec update inside each project to regenerate AI guidance and ensure the latest slash commands are active.

Contributing

• Install dependencies: pnpm install
• Build: pnpm run build
• Test: pnpm test
• Develop CLI locally: pnpm run dev or pnpm run dev:cli
• Conventional commits (one-line): type(scope): subject

License

MIT