OSpec is a document-driven workflow for AI-assisted development, helping you define requirements and changes in docs first, then drive implementation, validation, and archive through AI collaboration.
Overview
OSpec is a document-driven workflow for AI-assisted development, helping you define requirements and changes in docs first, then drive implementation, validation, and archive through AI collaboration.
README
English | 中文 | 日本語
OSpec is a document-driven workflow for AI-assisted development, helping you define requirements and changes in docs first, then drive implementation, validation, and archive through AI collaboration.
Docs | Prompt Guide | Usage | Overview | Installation | Issues
The project has been formally renamed to OSpec, and the primary repository is now https://github.com/clawplays/ospec.
Install With npm
npm install -g @clawplays/ospec-cli
Recommended Prompts
Most teams only need 3 steps to use OSpec:
- initialize OSpec in your project directory
- create and advance one change for a requirement, document update, or bug fix
- archive the accepted change after deployment and validation are complete
1. Initialize OSpec In Your Project Directory
Recommended prompt:
Use OSpec to initialize this project.
Claude / Codex skill mode:
Use $ospec to initialize this project.
2. Create And Advance A Change
Use this for requirement delivery, documentation updates, refactors, and bug fixes.
Recommended prompt:
Use OSpec to create and advance a change for this requirement.
Claude / Codex skill mode:
Use $ospec-change to create and advance a change for this requirement.
3. Archive After Acceptance
After the requirement has passed deployment, testing, QA, or other acceptance checks, archive the validated change.
Recommended prompt:
Use OSpec to archive this accepted change.
Claude / Codex skill mode:
Use $ospec to archive this accepted change.
How The OSpec Workflow Works
┌─────────────────────────────────────────────────────────────────┐
│ 1. USER REQUEST │
│ "Use OSpec to create and advance a change for this task." │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. INIT TO CHANGE-READY │
│ ospec init │
│ - .skillrc │
│ - .ospec/ │
│ - changes/active + changes/archived │
│ - root SKILL files and for-ai guidance │
│ - docs/project/* baseline knowledge docs │
│ - reuse docs or fall back to placeholders │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. EXECUTION │
│ ospec new │
│ ospec progress │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. DEPLOY + VALIDATE │
│ project deploy / test / QA │
│ ospec verify │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 5. ARCHIVE │
│ ospec finalize │
│ rebuild index + archive │
└─────────────────────────────────────────────────────────────────┘
Core Concepts
| Concept | What It Means |
|---|---|
| Protocol Shell | The minimum collaboration skeleton: .skillrc, .ospec/, changes/, root SKILL.md, SKILL.index.json, and for-ai/ guidance. |
| Project Knowledge Layer | Explicit project context such as docs/project/*, layered skill files, and index state that AI can read consistently. |
| Active Change | A dedicated execution container for one requirement, usually with proposal.md, tasks.md, state.json, verification.md, and review.md. |
Features
- Change-ready initialization:
ospec initcreates the protocol shell and baseline project knowledge docs in one pass. - Guided initialization: AI-assisted init can ask once for missing summary or tech stack; direct CLI init falls back to placeholder docs when context is missing.
- Docs maintenance:
ospec docs generaterefreshes or repairs project knowledge docs when you need it later. - Tracked requirement execution: each change can keep proposal, tasks, state, verification, and review files aligned.
- Queue helpers:
queueandrunsupport explicit multi-change execution when one active change is not enough. - Plugin workflow gates: built-in plugin commands support Stitch design review and Checkpoint automation.
- Skill management: install and inspect OSpec skills for Codex and Claude Code.
- Standard closeout:
finalizeverifies, rebuilds indexes, and archives the change before manual Git commit.
Plugin Features
OSpec includes two optional plugins that extend the document-driven workflow with UI review and flow validation.
Stitch
Use Stitch for page design review and preview collaboration, especially for landing pages, marketing pages, and UI-heavy changes.
AI conversation:
Use OSpec to enable the Stitch plugin.
Claude / Codex skill mode:
Use $ospec to enable the Stitch plugin.
Checkpoint
Use Checkpoint for app flow validation and automated checks, especially for submission flows, critical paths, and pre-acceptance runtime verification.
AI conversation:
Use OSpec to enable the Checkpoint plugin.
Claude / Codex skill mode:
Use $ospec to enable the Checkpoint plugin.
Documentation
Core Docs
Plugin Specs
Repository Structure
dist/ Compiled CLI runtime
assets/ Managed protocol assets, hooks, and skill payloads
docs/ Public documentation
scripts/ Release and installation helpers
.ospec/templates/hooks/ Hook templates shipped with the package
License
This project is licensed under the MIT License.
Recommended Tools
Try a different keyword or remove a filter.
Install
npx skillfish add henrydiaosi/dorado