ospec

<h1><a href="https://ospec.ai/" target="_blank" rel="noopener noreferrer">OSpec.ai</a></h1> <p align="center"> <a href="https://www.npmjs.com/package/@clawplays/ospec-cli"><img src="https://img.shields.io/npm/v/%40clawplays%2Fospec-cli?style=for-the-badge&logo=npm&label=npm" alt="npm"></a> <a href="https://www.npmjs.com/package/@clawplays/ospec-cli"><img src="https://img.shields.io/npm/dm/%40clawplays%2Fospec-cli?style=for-the-badge&logo=npm&label=downloads&cacheSeconds=300" alt="npm downloads"></a> <a href="https://github.com/clawplays/ospec/stargazers"><img src="https://img.shields.io/github/stars/clawplays/ospec?style=for-the-badge&logo=github" alt="GitHub stars"></a> <a href="LICENSE"><img src="https://img.shields.io/github/license/clawplays/ospec?style=for-the-badge&color=green" alt="License"></a> </p> <p align="center"> <img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 18+"> <img src="https://img.shields.io/badge/npm-8%2B-CB3837?style=flat-square&logo=npm&logoColor=white" alt="npm 8+"> <img src="https://img.shields.io/badge/language-TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"> <img src="https://img.shields.io/badge/workflow-3_steps-0F766E?style=flat-square" alt="3-step workflow"> </p> <p align="center"> <strong>English</strong> | <a href="docs/README.zh-CN.md">中文</a> | <a href="docs/README.ja.md">日本語</a> | <a href="docs/README.ar.md">العربية</a> </p>

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.

<p align="center"> <a href="docs/prompt-guide.md">Prompt Guide</a> | <a href="docs/usage.md">Usage</a> | <a href="docs/project-overview.md">Overview</a> | <a href="docs/installation.md">Installation</a> | <a href="docs/skills-installation.md">Skills Installation</a> | <a href="https://github.com/clawplays/ospec/issues">Issues</a> </p>

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 for larger or riskier work — describe the result you need; the AI asks important questions, writes an inspectable plan, implements the work, runs tests, requests an independent review, updates project docs, and continues until the result is proven.
• One predictable Goal workflow — every Goal uses the same fast quality path, pauses for material user decisions, and saves progress in the repository so a later session can resume it.

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.

<details> <summary>Command line</summary>

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 change, 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/<change-name>, but the physical path in nested projects is .ospec/changes/active/<change-name>
• 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

</details>

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.

<details> <summary>Command line</summary>

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

</details>

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/<goal-name>
ospec execute workspace changes/active/<goal-name>
ospec execute status changes/active/<goal-name>
ospec execute dispatch changes/active/<goal-name> --limit 3
ospec execute launch changes/active/<goal-name> --task <task-id> --target codex
ospec execute complete <task-id> changes/active/<goal-name> --status DONE --summary "..."
ospec loop tick changes/active/<goal-name> # issues task/final reviews with executor provenance
ospec execute verify changes/active/<goal-name> --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 plus bounded wait_agent, Claude Code uses bounded background Task polling when available, Gemini uses @generalist, and OpenCode uses @mention. Every native adapter returns from one wait within 60 seconds, refreshes heartbeats, persists each completed child immediately, and re-ticks. The 60-second boundary limits one controller poll, not the AI task runtime: a live child continues across polls up to its configurable absolute action deadline. OSpec never starts Orca, Codex, Claude, or another agent CLI as a fallback. If the current model harness cannot provide native subagents, executable dispatch blocks until a supported harness reports a fresh capability.

For a controller-owned Goal, task and final reviews are always issued by ospec loop tick so the dispatch is atomically bound to the real reviewer executor. Use ospec execute review directly only in a non-controller workflow.

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.

<details> <summary>Command line</summary>

ospec verify changes/active/<change-name>
ospec finalize changes/active/<change-name>

Explicit incomplete archive, only after the user accepts the unresolved risk:

ospec finalize changes/active/<change-name> --force-archive --confirm-force-archive <exact-change-name> --reason "Accepted unresolved verification risk"

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
• force archive is never automatic: it requires the force flag, an exact change-name confirmation, and an audit reason; it refuses any missing, issued, or running Loop item, but may preserve an unconsumed pointer whose items are all terminal; the archive is marked forced, incomplete, and accepted-risk instead of completed
• new nested projects archive under .ospec/changes/archived/YYYY-MM/YYYY-MM-DD/<change-name>; CLI shorthand under changes/archived/... still works
• existing flat archives are reorganized by ospec update

</details>

Goal: Use It For Work That Needs More Care

Use a Goal only when you choose the full workflow. A user-selected Change remains a Change regardless of complexity, file count, risk, or batch size; create it with ospec change (ospec new remains an alias).

A Change uses compact stage-aware guidance, one lightweight current-AI review, and derived closeout state. When verification, documentation, and review gates pass, APPROVED or APPROVED_WITH_CONCERNS may finalize and archive automatically; explicit batches stay sequential in the queue.

Start from a terminal:

ospec goal improve-checkout --target codex --execution-model controller --harness-interactive true --native-subagents supported

Then tell the AI what outcome you need in ordinary language. You can also skip the terminal command and say: "Use OSpec goal for this requirement and carry it through to completion."

That is all a normal user needs to operate. The AI will:

1. Ask only the choices that materially change the result.
2. Write the proposal, design, and implementation plan, then run deterministic design and plan preflights without launching reviewer children.
3. Derive the task graph and run one independent combined planning review across requirements, architecture, task boundaries, dependencies, and verification coverage.
4. If that review finds issues, repair the planning set once as a group and run one fresh combined planning review. A repeated failure stops instead of looping.
5. Run conflict-safe implementation workers, independent task reviews, an integration-focused final review, verification, documentation sync, and archive.

You remain in control. The AI explains what it is about to do, pauses when it needs a decision, and records task, review, repair, verification, and loop progress in the repository so a fresh worker or later session can co