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.

Why OSpec?

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

Install With npm

npm install -g @clawplays/ospec-cli

Official package: @clawplays/ospec-cli
Command: ospec
Verify install: ospec --help

Quick Start

OSpec only takes 3 steps:

1. initialize OSpec in your project directory
2. create and advance one change for a requirement, document update, or bug fix
3. archive the accepted change after deployment and validation are complete

1. Initialize OSpec In Your Project Directory

Recommended prompt:

OSpec, initialize this project.

Claude / Codex skill mode:

$ospec initialize this project.

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-US

CLI notes:

• --summary: project overview text written into the generated docs
• --tech-stack: comma-separated stack list such as node,react,postgres
• --architecture: short architecture description
• --document-language: generated doc language, choose from en-US, zh-CN, ja-JP, or ar
• 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 -> fallback en-US
• OSpec persists the chosen project document language in .skillrc and reuses it for for-ai guidance, ospec new, and ospec 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

2. Create And Advance A Change

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.

ospec new docs-homepage-refresh .
ospec new fix-login-timeout .
ospec new update-billing-copy .

3. Archive After Acceptance

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.

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 verify to confirm the active change is ready
• use ospec finalize to 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 by ospec update

Update With npm

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 update

ospec 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.

How The OSpec Workflow Works

┌─────────────────────────────────────────────────────────────────┐
│  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                                    │
└─────────────────────────────────────────────────────────────────┘

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 init creates 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 .skillrc so later guidance and generated change docs stay consistent unless you explicitly change it.
• Docs maintenance: ospec docs generate refreshes 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: queue and run support 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: finalize verifies, 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:

OSpec, enable the Stitch plugin and connect using Codex/Gemini.

Claude / Codex skill mode:

$ospec enable the Stitch plugin and connect using Codex/Gemini.

ospec plugins enable stitch .

Checkpoint

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.

ospec plugins enable checkpoint . --base-url http://127.0.0.1:3000

Notes:

• --base-url points to the running app used by automated checks
• Enabling the built-in Checkpoint runner automatically installs playwright, pixelmatch, and pngjs into the target project
• If a user asks an AI assistant to enable Checkpoint, that install step must complete before the plugin should be considered successfully enabled
• Disabling Checkpoint only turns off the plugin configuration; it does not uninstall those project dependencies

Documentation

Core Docs

• Prompt Guide
• Usage
• Project Overview
• Installation
• Skills Installation

Plugin Specs

• Stitch Plugin Spec
• Checkpoint Plugin Spec

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.