OSpec の公式 CLI パッケージは @clawplays/ospec-cli、公式コマンドは ospec です。OSpec は AI coding agents と CLI ワークフロー向けに、spec-driven development（SDD）と document-driven development を支援します。
プロンプトガイド | 使い方 | 概要 | インストール | 外部プラグイン | プラグイン公開 | Issues
AI コーディングアシスタントは強力ですが、要件がチャット履歴にしか残らないと、確認・レビュー・クローズアウトが難しくなります。OSpec は軽量なワークフローレイヤーを加えることで、コードを書く前とリリース後の両方で change の文脈をリポジトリに残します。
- 実装前に合意できる: proposal、tasks、state、verification、review をリポジトリ内で追える
- 要件ごとに明示できる: デフォルトでは 1 つの要件を 1 つの active change で進める
- 軽量に保てる: 通常フローを
init -> change -> verify/finalizeに絞る - 既存のアシスタントを活かせる: Codex、Claude Code、CLI ワークフローを前提にしている
npm install -g @clawplays/ospec-cli公式パッケージ: @clawplays/ospec-cli
公式コマンド: ospec
インストール確認: ospec --help
OSpec の利用は、この 3 ステップだけです：
- プロジェクトディレクトリで OSpec を初期化する
- 要件、ドキュメント更新、バグ修正のための change を作成して進める
- 受け入れ完了後にその change をアーカイブする
推奨プロンプト:
OSpec でこのプロジェクトを初期化してください。
Claude / Codex skill:
/ospec でこのプロジェクトを初期化してください。
コマンドライン
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 ja-JPメモ:
--summary: 生成ドキュメントに書き込むプロジェクト概要--tech-stack:node,react,postgresのようなカンマ区切りの技術スタック--architecture: 短いアーキテクチャ説明--document-language: 生成ドキュメントの言語。en-US、zh-CN、ja-JP、arから選択- 言語解決優先順位: 明示的な
--document-language-> 既存のプロジェクト文書 /.ospec/for-ai/*（または旧for-ai/*） / asset manifest ->en-US - 通常の
initでは.ospec/knowledge/src/や.ospec/knowledge/tests/のような任意の知識マップは生成されません - 値を渡した場合はその内容を使ってドキュメントを生成します
- 値を渡さない場合は既存ドキュメントを優先利用し、無ければ補完用のプレースホルダを生成します
要件実装、ドキュメント更新、リファクタ、バグ修正はこの流れを使います。
推奨プロンプト:
OSpec でこの要件の change を作成して進めてください。
Claude / Codex skill:
/ospec-change でこの要件の change を作成して進めてください。
コマンドライン
ospec new docs-homepage-refresh .
ospec new fix-login-timeout .
ospec new update-billing-copy .デプロイ、テスト、QA、またはその他の受け入れ確認が終わった後に、確認済みの change をアーカイブします。
推奨プロンプト:
OSpec で承認済みの change をアーカイブしてください。
Claude / Codex skill:
/ospec で承認済みの change をアーカイブしてください。
コマンドライン
ospec verify changes/active/<change-name>
ospec finalize changes/active/<change-name>新規プロジェクトでは ospec init の既定レイアウトは nested です。リポジトリ直下に残るのは .skillrc と README.md だけで、change や SKILL、for-ai などの管理ファイルは .ospec/ 配下に置かれます。
CLI は changes/active/<change-name> の短縮パスも受け付けますが、nested プロジェクトでの実体パスは .ospec/changes/active/<change-name> です。
メモ:
- 先にプロジェクト固有のデプロイ、テスト、QA を実行します
ospec verifyで change がアーカイブ可能か確認しますospec finalizeでインデックスを再構築し、change をアーカイブします
既存の OSpec プロジェクトでは、npm で CLI をアップグレードしたあと、プロジェクトディレクトリで次のコマンドを実行してプロジェクト内の OSpec ファイルを更新します:
ospec updateospec update は classic レイアウトを nested レイアウトへ自動移行しません。古い classic プロジェクトを新しいレイアウトへ切り替えたい場合は、ospec layout migrate --to nested を明示的に実行してください。
┌─────────────────────────────────────────────────────────────────┐
│ 1. USER REQUEST │
│ "OSpec, create and advance a change for this task." │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. INIT TO CHANGE-READY │
│ ospec init │
│ - .skillrc │
│ - .ospec/ │
│ - README.md │
│ - .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 <change-name> │
│ ospec progress │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. DEPLOY + VALIDATE │
│ project deploy / test / QA │
│ ospec verify │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 5. ARCHIVE │
│ ospec finalize │
│ rebuild index + archive │
└─────────────────────────────────────────────────────────────────┘
| 概念 | 説明 |
|---|---|
| Protocol Shell | ルートの .skillrc と README.md、そして change 状態、SKILL、index、for-ai、project docs を含む .ospec/ 配下の managed files から成る最小の協調骨格 |
| Project Knowledge Layer | docs/project/*、レイヤード skill ファイル、index 状態など AI が継続的に参照するコンテキスト |
| Active Change | 1 つの要件専用の実行コンテナ。通常 proposal.md、tasks.md、state.json、verification.md、review.md を持つ |
- change-ready 初期化:
ospec initが protocol shell と基礎ドキュメントを一度に生成 - ガイド付き初期化: AI 支援時は不足している概要や技術スタックを 1 回だけ確認可能
- ドキュメント保守:
ospec docs generateで後から知識レイヤを更新・修復 - change 実行の追跡: proposal、tasks、state、verification、review を継続的に揃える
- キュー支援:
queueとrunで複数 change の明示的な実行を管理 - プラグインゲート: Stitch のデザインレビューと Checkpoint の自動化チェックをサポート
- 標準クローズアウト:
finalizeが検証、インデックス再構築、アーカイブを行う
OSpec には、文書駆動ワークフローに UI レビューとフロー検証を追加する 2 つのオプションプラグインがあります。
Stitch はページデザインレビューとプレビュー共有に使います。ランディングページや UI 変更が多い change に向いています。
AI 対話:
OSpec で Stitch プラグインを有効にし、Codex/Gemini で接続してください。
Claude / Codex skill:
/ospec で Stitch プラグインを有効にし、Codex/Gemini で接続してください。
コマンドライン
ospec plugins enable stitch .Checkpoint は画面フロー検証と自動チェックに使います。重要フローや受け入れ前のランタイム検証に向いています。
AI 対話:
OSpec で Checkpoint プラグインを有効にしてください。
Claude / Codex skill:
/ospec で Checkpoint プラグインを有効にしてください。
コマンドライン
ospec plugins enable checkpoint . --base-url http://127.0.0.1:3000メモ:
--base-urlは自動チェック対象となる起動中アプリの URL を指定します- 内蔵 Checkpoint runner を有効にすると、OSpec は対象プロジェクトに
playwright、pixelmatch、pngjsを自動インストールします - AI 対話で「Checkpoint プラグインを有効にする」と依頼した場合、この依存関係のインストール完了まで含めてはじめて有効化成功とみなします
- Checkpoint を無効化しても、プロジェクトにインストール済みのこれらの依存関係は自動削除しません
- Prompt Guide
- Usage
- Project Overview
- Installation
- Skills Installation
- External Plugins
- Plugin Release
ospec plugins listospec plugins install <plugin>ospec plugins enable <plugin> [path]- 会話で「Stitch / Checkpoint を開いて」と頼まれた場合は、まずグローバルインストール済みか確認し、未インストールならインストールし、その後に有効化する
dist/ コンパイル済み CLI ランタイム
assets/ 管理対象プロトコル資産、hooks、skill payload
docs/ 公開ドキュメント
scripts/ リリースとインストール補助スクリプト
.ospec/templates/hooks/ パッケージ同梱の Git hook テンプレート
This project is licensed under the MIT License.