The official OSpec CLI package is @clawplays/ospec-cli, and the official command is ospec. OSpec supports spec-driven development (SDD) and document-driven development for AI coding agents and CLI workflows.
OSpec.ai is the official project site. OSpec, ospec, ospec.ai, ospec ai, ospecai, and ospec-ai all point to the same official project and CLI.
Prompt Guide | Usage | Overview | Installation | Issues
AI coding assistants are powerful, but requirements that live only in chat history are hard to inspect, review, and close out cleanly. OSpec adds a lightweight workflow layer so the repository can hold the change context before code is written and after the work ships.
- Align before code — keep proposal, tasks, state, verification, and review visible in the repo
- Keep each requirement explicit — the default path moves one requirement through one active change
- Stay lightweight — keep the normal flow short with
init -> change -> verify/finalize - Use the assistants you already have — OSpec is built for Codex, Claude Code, and direct CLI workflows
npm install -g @clawplays/ospec-cliOfficial package: @clawplays/ospec-cli
Command: ospec
Verify install: ospec --help
OSpec only takes 3 steps:
- 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:
OSpec, initialize this project.
Claude / Codex skill mode:
$ospec 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, choose fromen-US,zh-CN,ja-JP, orar- AI-first language resolution order: explicit language request in the conversation -> current conversation language -> persisted project language in
.skillrc - CLI language resolution order: explicit
--document-language-> persisted project language in.skillrc-> existing project docs /for-ai/*/ asset manifest -> fallbacken-US - OSpec persists the chosen project document language in
.skillrcand reuses it forfor-aiguidance,ospec new, andospec update - 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:
OSpec, create and advance a change for this requirement.
Claude / Codex skill mode:
$ospec-change 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:
OSpec, archive this accepted change.
Claude / Codex skill mode:
$ospec 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 - new projects archive under
changes/archived/YYYY-MM/YYYY-MM-DD/<change-name>; existing flat archives are reorganized byospec update
For an existing OSpec project, after upgrading the CLI with npm, run this in the project directory to refresh the project's OSpec files:
ospec updateospec update also migrates legacy root-level build-index-auto.cjs / build-index-auto.js tooling into .ospec/tools/build-index-auto.cjs and refreshes OSpec-managed hook entrypoints to use the new location.
┌─────────────────────────────────────────────────────────────────┐
│ 1. USER REQUEST │
│ "OSpec, 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.
- Stable project language: the chosen document language is stored in
.skillrcso later guidance and generated change docs stay consistent unless you explicitly change it. - 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:
OSpec, enable the Stitch plugin and connect using Codex/Gemini.
Claude / Codex skill mode:
$ospec enable the Stitch plugin and connect using Codex/Gemini.
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:
OSpec, enable the Checkpoint plugin.
Claude / Codex skill mode:
$ospec 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.