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.
Prompt Guide | Usage | Overview | Installation | Issues
npm install -g @clawplays/ospec-cliMost 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
Recommended prompt:
Use OSpec to initialize this project.
Claude / Codex skill mode:
Use $ospec to initialize this project.
Command line
ospec init .
ospec init . --summary "Internal admin portal for operations"
ospec init . --summary "Internal admin portal for operations" --tech-stack node,react,postgres
ospec init . --architecture "Single web app with API and shared auth" --document-language en-USCLI notes:
--summary: project overview text written into the generated docs--tech-stack: comma-separated stack list such asnode,react,postgres--architecture: short architecture description--document-language: generated doc language, usuallyen-USorzh-CN- if you pass these values, OSpec uses them directly when generating project docs
- if you do not pass them, OSpec reuses existing docs when possible and otherwise creates placeholder docs first
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.
Command line
ospec new docs-homepage-refresh .
ospec new fix-login-timeout .
ospec new update-billing-copy .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.
Command line
ospec verify changes/active/<change-name>
ospec finalize changes/active/<change-name>Archive notes:
- run your project-specific deploy, test, and QA flow first
- use
ospec verifyto confirm the active change is ready - use
ospec finalizeto rebuild indexes and archive the accepted change
┌─────────────────────────────────────────────────────────────────┐
│ 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 <change-name> │
│ ospec progress │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. DEPLOY + VALIDATE │
│ project deploy / test / QA │
│ ospec verify │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 5. ARCHIVE │
│ ospec finalize │
│ rebuild index + archive │
└─────────────────────────────────────────────────────────────────┘
| 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. |
- 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.
OSpec includes two optional plugins that extend the document-driven workflow with UI review and flow validation.
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.
Command line
ospec plugins enable stitch .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.
Command line
ospec plugins enable checkpoint . --base-url http://127.0.0.1:3000Notes:
--base-urlpoints to the running app used by automated checks
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
This project is licensed under the MIT License.