name: ospec description: Document-driven OSpec workflow for initialization, change/goal routing, validation, archiving, and durable project knowledge. tags: [cli, workflow, automation, ospec]

OSpec Router

Use this root skill as a compact router. Keep invariant safety and workflow-selection rules here; load detailed commands and stage protocols from the initialized project's indexed files only when that stage is active.

Default Entry

When the user asks to initialize a project, run ospec init [path]. In AI-assisted initialization, pass the explicit or conversational language with --document-language. If useful context is missing, ask once for a short project summary or tech stack; if the user skips it, continue with placeholders. Verify the generated files on disk and stop before creating work unless the user explicitly asks for a change or goal.

Initialization is change-ready only when .skillrc, the managed .ospec/ or classic OSpec directory, active and archived change directories, SKILL.md, SKILL.index.json, the index builder, for-ai/ protocol files, and baseline docs/project/ knowledge files exist.

Do not hand-write an approximation of ospec init. Do not assume a web stack, apply business scaffold, generate docs/project/bootstrap-summary.md, create queue work, or create the first change without explicit intent.

Workflow Router

• Use ospec new / ospec-change for routine, scoped work. Its source of truth is changes/active/<change>/proposal.md, changes/active/<change>/tasks.md, state.json, verification.md, and review.md.
• Use ospec goal / ospec-goal for complex, cross-cutting, high-risk, parallel, or evidence-heavy work. It additionally owns changes/active/<change>/design.md, changes/active/<change>/implementation-plan.md, changes/active/<change>/artifacts/agents/task-graph.json, worker/reviewer artifacts, and evidence gates.
• Do not silently promote a change to a goal or create goal-only artifacts for a classic change. A routing recommendation may explain why one workflow fits, but the user's explicit choice remains authoritative.
• Enter queue mode only when the user explicitly asks to queue or execute multiple changes.

For an initialized project, read in this order:

1. .skillrc for layout, language, workflow policy, plugins, adaptive review policy, and model profiles.
2. SKILL.index.json and docs/project/feature-index.md as routers.
3. The current session brief, bootstrap, dispatch, review, or repair packet.
4. Only the indexed project documents, change files, and target files named by that packet.

Do not load every historical change or every protocol file by default. Open for-ai/ai-guide.md for general execution rules and for-ai/execution-protocol.md only when entering the full goal controller layer. Use ospec help or subcommand help instead of carrying the complete CLI catalog in context.

Visibility And Decisions

• Announce-Before-Act: before workflow actions, state the OSpec workflow and stage, the command and artifact it writes, native agent count/mechanism, and any blocking gate.
• Brainstorm-First: before locking a goal design, surface open direction, architecture, API, data, UI, risk, and scope decisions one at a time. Prefer a durable required decision over a silent assumption.
• Zero-Setup: the user states the requirement; the AI runs OSpec controller commands and the user only answers decisions. Do not ask the user to operate routine setup commands.
• Required pending decisions block worker dispatch. Preserve PENDING, NEEDS_CONTEXT, BLOCKED, DONE_WITH_CONCERNS, and DONE rather than hiding uncertainty.

In Claude Code, install the managed hook once with ospec session hook --target claude --apply when missing. Static workflow context is injected on startup, clear, and compact; prompt hooks should stay silent unless a required decision is pending. PreToolUse(Task) remains the hard dispatch gate.

Goal Controller Invariants

Use the full ospec execute ... layer only for goal work or when the user explicitly requests agent/worker execution for a change.

• Start or resume with ospec session and ospec execute bootstrap.
• Complete design review before plan review under the configured document review policy. The default always policy requires independent review; adaptive may use deterministic inline preflight only when the target document explicitly declares risk_level: low (or none) and no risk signal exists. Missing or unparseable risk context requires specialist review.
• Resolve required decisions and workspace isolation before dispatch.
• Dispatch scoped worker packets, use the launch plan with the current harness native agent mechanism, record completion, then perform one combined task review.
• A worker profile is logical (mechanical, standard, strong_reasoning, review, final_review). Harness-specific model names come from .skillrc; absence is explicit and falls back to the harness default.
• Record optional provider usage sidecars through the supported completion command. Metrics are evidence, not an archive gate unless project policy says otherwise.
• When final review requires changes, group all findings into one repair wave and one repair task, run its covering verification once, then run one combined task review and one final re-review.
• Keep reviewers independent: they read scoped evidence, do not edit implementation, do not accept hidden severity downgrades, and report findings before summaries. Record actionable findings in both Markdown and the sibling structured *.findings.json.
• Do not archive while task graph, review, decision, documentation, optional-step, worker-status, or verification gates are unresolved.

Detailed goal artifacts live under changes/active/<change>/artifacts/agents/ and artifacts/reviews/. Read their current packet or for-ai/execution-protocol.md for exact paths and commands instead of expanding the entire inventory here.

Documentation And Archive

Every finalized change and goal automatically receives a generated docs/project/changes/<archive-path>.md knowledge document with its summary, affected areas, implementation files, verification commands, durable project documents, and archived evidence. This guarantees one indexed document per archived change. Before moving the active change, archive preflight refuses to overwrite a human-owned file at that generated path and verifies the managed output directories are writable. Behavior, architecture, module, API, or operational changes must additionally update the relevant human-maintained docs/project/ files. When the task graph enables the documentation contract, every task declares documentation_updates; use [] only when no project documentation changes are needed, include each declared document in target_files, and preserve dispatch-to-completion evidence of a meaningful normalized-content change.

Use ospec verify for the active workflow. For normal closeout, use ospec finalize [changes/active/<change>]; use ospec archive --check only for preview. Finalize must verify completeness, archive, rebuild docs/project/feature-index.md, and rebuild SKILL.index.json so its documents and archived_changes sections locate the completed behavior and link declared durable project documents. Git commit remains separate.

After archive, verify:

• the completed behavior is discoverable through docs/project/feature-index.md;
• the generated per-change knowledge document exists under docs/project/changes/ and is linked from both indexes;
• project docs and archived change records are present in SKILL.index.json;
• section offsets are stable under LF-normalized content;
• no required documentation update was omitted.

Use ospec docs generate for a docs-only repair or refresh. Do not create a change merely to repair project knowledge unless the user asks for one.

Compact Command Routes

Initialize:  ospec init [path] -> verify generated project shell
Change:      ospec new <name> -> implement -> ospec verify -> ospec finalize
Goal:        ospec goal <name> -> session/bootstrap -> design/plan reviews -> dispatch/review -> verify/finalize
Docs:        ospec docs generate [path] -> ospec docs status -> ospec index check
Resume:      ospec session [path] -> read brief/index -> run the persisted next safe command
Troubleshoot: ospec status [path] -> ospec help

Use CLI commands for initialization, verification, index generation, and archive. Do not replace managed operations with ad hoc filesystem edits.

Completion Discipline

Before claiming completion:

1. Verify the active workflow and fresh project checks.
2. Confirm relevant docs and documentation contracts.
3. Confirm worker/reviewer/decision/evidence gates for goals.
4. Confirm skills and indexes when knowledge changed.
5. After archive, confirm the feature and its documents are discoverable without replaying conversation history.

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.

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.
• You choose how much it may do automatically — L1 only checks, L2 may edit but pauses for important choices, and L3 may continue within limits you set. Progress is saved 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.

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

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.

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/<goal-name>
ospec execute workspace changes/active/<goal-name>
ospec execute status changes/active/<goal-name>
ospec execute dispatch changes/active/<goal-name> --limit 2
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 execute review changes/active/<goal-name> --task <task-id>
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.

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

Goal: Use It For Work That Needs More Care

Use a goal when the work touches several parts of the project, has important design choices, changes an API or data, carries security or migration risk, or will take several rounds to finish. For a small, well-defined edit, use ospec new instead.

Start from a terminal:

ospec goal improve-checkout --level L2 --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