Ospec

OSpec.ai

English | 中文 | 日本語 | العربية

The official OSpec CLI package is @clawplays/ospec-cli, and the official command is ospec. OSpec is a spec-driven, agentic workflow framework for AI coding agents — it brings spec-driven development (SDD) and Loop Engineering (a verifiable plan → act → verify goal loop) to Claude Code, Codex, Gemini, OpenCode, MCP-based agents, and plain CLI workflows.

Prompt Guide | Usage | Overview | Installation | External Plugins | Plugin Release | Issues

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.

• Spec-driven work, saved to your repo — OSpec turns a request into files (proposal, design, plan, tasks, reviews, verification evidence) that live in your repo instead of in chat history, so any assistant (Codex/GPT, Claude Code, Gemini, OpenCode, or plain CLI) can pick up exactly where the last one stopped.
• ospec change — the everyday fast flow — one requirement becomes one active change on a short init -> change -> verify/finalize path, kept lightweight and easy to review.
• ospec goal — engineering-grade discipline — brainstorm and lock the design before any code, split the work into a task graph, dispatch parallel sub-agents, enforce TDD and code review by a separate reviewer, and require durable test/verification evidence before anything counts as done.
• ospec goal runs as a loop — it plans, acts, and verifies in rounds until tests prove the work, at a safety level you choose (--level L1|L2|L3: report-only → assisted → unattended); drive it with ospec loop … and surface findings to a triage inbox with ospec triage ….

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.

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-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 / managed for-ai/* guidance / 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
• new projects initialized by ospec init default to the nested layout: root .skillrc and README.md, with OSpec-managed files under .ospec/
• plain init does not create optional knowledge maps such as .ospec/knowledge/src/ or .ospec/knowledge/tests/; those appear only when a project already has legacy knowledge content to migrate or when future explicit knowledge-generation flows create them
• CLI commands still accept shorthand like changes/active/, but the physical path in nested projects is .ospec/changes/active/
• 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-goal create and advance a full goal for this requirement.

Command line

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

Agent Execution (Goal Workflow)

The classic change flow above stays simple: proposal.md → tasks.md → implement → verification.md → review.md, with no controller layer. The agent controller layer — parallel worker dispatch, reviewer gates, and durable evidence — belongs to the full goal workflow. Use it with ospec goal, or on a single change only when you explicitly opt into agent/worker execution. OSpec keeps the controller state in repo artifacts, and the current AI harness starts native worker agents when available.

ospec session .
ospec execute bootstrap changes/active/
ospec execute workspace changes/active/
ospec execute status changes/active/
ospec execute dispatch changes/active/ --limit 2
ospec execute launch changes/active/ --task  --target codex
ospec execute complete  changes/active/ --status DONE --summary "..."
ospec execute review changes/active/ --task 
ospec execute verify changes/active/ --command "npm test" --status PASSED --exit-code 0

launch writes artifacts/agents/launch-plan.md; it does not start workers by itself. Codex/GPT use spawn_agent / wait_agent / close_agent, Claude Code uses Task, Gemini uses @generalist, and OpenCode uses @mention. Use launch --run --command or orchestrate --command only when the current harness cannot start native subagents.

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.

Command line

ospec verify changes/active/
ospec finalize changes/active/

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 nested projects archive under .ospec/changes/archived/YYYY-MM/YYYY-MM-DD/; CLI shorthand under changes/archived/... still works
• existing flat archives are reorganized by ospec update

Goal Workflow — Full Flow & Hard Enforcement

Use ospec goal (or just say "OSpec, create and advance a full goal for this requirement") for complex, cross-cutting, or high-risk work that needs the full OSpec workflow: design doc, implementation plan, task graph, parallel worker dispatch, document and code review, and durable TDD / debug / verification evidence.

You only start a goal and describe the requirement. The AI runs every ospec command itself; you just answer questions in chat (Zero-Setup).

A goal runs as a session-bound loop: it plans, acts, and verifies in rounds until the work is done and proven by tests. You choose a safety level when you start it (--level L1|L2|L3, default L1):

• L1 — report only: findings go to a triage inbox, nothing is changed.
• L2 — makes changes but pauses at key decisions for your approval.
• L3 — runs unattended within an allowlist you set.

Drive and watch it with ospec loop run/watch/status/pause/resume/level, review findings with ospec triage list/claim/promote, and stop it by pausing, dropping a STOP file, or closing your session. When the harness has a native /goal (Claude, Codex) the loop uses it; otherwise it falls back automatically. ospec change stays the classic fast flow. See [docs/loop-engineering.md](docs/loop-engineering.md).

Experience contracts the AI follows on every goal:

• Announce-Before-Act — the AI states which skill and stage it is in, which ospec execute … command it is about to run and the artifact it writes, and how many subagents it dispatches — so you always see what is happening.
• Brainstorm-First — before locking design it surfaces the open decisions (direction, architecture, API, data, UI, risk, scope) and asks you one at a time through the harness-native question UI (Claude Code: AskUserQuestion) instead of silently assuming.
• Durable decision gates — open choices are recorded with ospec execute decision …; required decisions block worker dispatch until you answer.

Claude Code hard enforcement (one-time; the AI runs this for you automatically in a Claude Code harness):

ospec session hook --target claude --apply

This writes a hook bundle under .ospec/hooks/claude/ and merges it into .claude/settings.json (idempotent and reversible). The hooks:

• announce every subagent dispatch and every ospec command at the tool level,
• hard-block subagent dispatch while a required decision is still pending,
• re-affirm the Announce-Before-Act / Brainstorm-First contract on every turn.

Hooks load at session start, so they take effect from the next Claude Code session.

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. It also repairs older OSpec projects that still have an OSpec footprint but are missing newer core runtime directories, refreshes managed skills and archive layout metadata, and syncs project assets for already-enabled plugins. For nested projects that still carry legacy knowledge under .ospec/src/ or .ospec/tests/, ospec update migrates those paths into .ospec/knowledge/src/ and .ospec/knowledge/tests/. When an already-enabled plugin has a newer compatible npm package version available, ospec update upgrades that global plugin package automatically and prints the version transition. It does not upgrade the CLI itself, and it does not enable plugins or migrate active / queued changes automatically. It also does not switch a classic project layout to nested automatically. If you want to convert an older classic project to the new layout, run ospec layout migrate --to nested explicitly.

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                                                 │
│     - README.md                                                │
│     - .ospec/                                                  │
│     - .ospec/changes/active + .ospec/changes/archived          │
│     - .ospec/SKILL.md + .ospec/SKILL.index.json + .ospec/for-ai│
│     - .ospec/docs/project/* baseline knowledge docs            │
│     - reuse docs or fall back to placeholders                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  3. EXECUTION                                                  │
│     ospec new       # classic fast change          │
│     ospec goal        # full goal workflow           │
│     ospec brainstorm / plan (optional pre-change aids)         │
│     ospec session                                              │
│     ospec session hook                                         │
│     ospec progress                                             │
│     ospec execute bootstrap / handoff / doc-review / status    │
│     ospec execute next                                         │
│     ospec execute workspace / worktree / worktree --create     │
│     ospec execute worktree --cleanup / finish                  │
│     ospec execute dispatch / launch / collect / retry / review │
│     ospec execute debug                                        │
│     ospec execute tdd                                          │
│     ospec execute verify                                       │
│     ospec execute sync                                         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  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: root .skillrc and README.md, plus managed OSpec files under .ospec/ for change state, SKILL docs, index state, for-ai/ guidance, and project docs. | | 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 small or routine requirement, using the classic fast files: proposal.md, tasks.md, state.json, verification.md, and review.md, plus plugin artifacts when activated. | | Active Goal | A full-workflow execution container created with ospec goal, adding design.md, implementation-plan.md, artifacts/agents/task-graph.json, handoff artifacts, document-review artifacts, launch-plan artifacts, worker-run artifacts, reviewer-run artifacts, retry artifacts, review artifacts, artifacts/agents/worker-status.md, and evidence artifacts. |

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: small changes keep proposal, tasks, state, verification, and review files aligned; full goals also keep design, implementation plan, task graph, handoff, review, worker status, and evidence artifacts al

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: clawplays
• Source: clawplays/ospec
• License: MIT
• Homepage: https://ospec.ai

Install and usage instructions live in the source repository linked above.