Openspec workflow

Skill ToruAI/toru-claude-agents/skills/openspec-workflow

Write the spec before the code, then check the built thing against it — so agents build what was agreed, not what they invented.From its SKILL.md

Install

npx -y skills add ToruAI/toru-claude-agents --skill openspec-workflow

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

15 stars15 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
runs commandsInstructs the agent to run 2 commands, including `openspec archive <change-id>` and 1 more.

SKILL.md

3.0 KB, 696 tokens by cl100k_base, as published. Nobody here has run it

OpenSpec Workflow - Specification-Driven Development

OpenSpec ensures AI agents build what was planned, not what they invented.

Directory Structure

project/
└── openspec/
    ├── specs/           # Source of truth (what IS built)
    ├── changes/         # Proposals & WIP (what SHOULD change)
    ├── ideas/           # Quick-capture for later
    └── project.md       # Project conventions

The Three-Stage Workflow

Stage 1: Proposal

Create a change proposal before implementing anything significant.

openspec/changes/add-feature-x/
├── proposal.md     # What and why
├── tasks.md        # Numbered implementation steps
├── design.md       # Technical approach
└── specs/          # Delta specs (what will change)

Stage 2: Implementation

Work through tasks.md sequentially. Keep specs in sync with code.

Stage 3: Archive

When complete: openspec archive <change-id> Specs merge to source of truth. Change moves to archive.

CLI Commands

# List all changes
openspec list

# Show specific change details
openspec show <change-id>

# Validate a change
openspec validate <change-id> --strict

# Archive completed change
openspec archive <change-id> --yes

# List specs
openspec spec list --long

Creating a Proposal

proposal.md format:

# Feature Name

## Summary
One paragraph: what this change does.

## Motivation
Why we need this. What problem it solves.

## Scope
- What's included
- What's explicitly NOT included

## Dependencies
- Other changes this depends on
- External requirements

tasks.md format:

# Implementation Tasks

## Phase 1: Foundation
- [ ] Task 1.1: Description
- [ ] Task 1.2: Description

## Phase 2: Core Implementation
- [ ] Task 2.1: Description
...

Rules

Proposal before code - For anything non-trivial, write proposal.md first
Tasks are sequential - Complete in order unless explicitly parallel
Validate before archive - openspec validate --strict must pass
Specs are truth - Code follows specs, not vice versa
Ideas are cheap - Capture in ideas/ freely, promote to changes/ when ready

When to Use OpenSpec

YES - Use OpenSpec for:

New features (more than a few files)
Architectural changes
Multi-step implementations
Anything that needs review

NO - Skip OpenSpec for:

Bug fixes (unless complex)
Typo corrections
Single-file changes
Exploratory work

Integration with megg

OpenSpec tracks WHAT gets built. megg tracks WHY decisions were made.

Use both:

OpenSpec for implementation specs
megg for decision rationale and context

Validation Checklist

Before marking a change complete:

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 0 of the 12 instructions most automation workflows skills give in 696 tokens

Counted across 813 of the 1,214 authors here whose files we hold, read 2026-09-06

Use conventional commit message formatin 38 of 813, across 34 files
Write tests before implementing codein 26 of 813, across 12 files
Achieve at least 80 percent test coveragein 24 of 813, across 11 files
Mock external dependencies for unit testsin 22 of 813, across 10 files
Read product marketing context before asking questionsin 21 of 813, across 6 files
Implement rollback plans for every deploymentin 21 of 813, across 9 files
Follow the arrange-act-assert patternin 20 of 813, across 9 files
Delete branches after mergingin 20 of 813, across 18 files
Test all edge cases and error scenariosin 20 of 813, across 8 files
Use semantic selectors for UI testsin 19 of 813, across 7 files
Define sequence type and audience contextin 18 of 813, across 5 files
Monitor feature drift and prediction distribution driftin 18 of 813, across 5 files

Said here and by no other author read

Create a proposal before implementing significant changes
Write proposal.md for non-trivial tasks
Follow tasks.md sequentially
Keep specifications in sync with code
Validate changes with strict mode before archiving
Capture ideas in the ideas directory

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.