openspec-workflow

OpenSpec ワークフロー

このリポジトリのポータブルなエージェントアセット、下流ツール、ドキュメント生成、フック、バンドルのメタデータ、または検証動作に関わる重要な変更では、OpenSpec を仕様および変更管理のコントロールプレーンとして使用します。

振り分け

$ARGUMENTS	アクション
空	リポジトリの OpenSpec クイックパスを表示します
doctor	OpenSpec ツールチェーンとプロジェクトの状態を診断します
init [tools]	下流の OpenSpec スキル／コマンドをローカルに展開します
status <change>	変更アーティファクトのステータスを JSON として読み取ります
instructions <artifact> <change>	AI が読み取れる次のステップの指示を取得します
validate	すべての OpenSpec 仕様と変更を検証します
archive <change>	完了した変更を検証してアーカイブします
自然言語による変更リクエスト	OpenSpec が必要かどうかを判断し、変更を作成または継続します

クイックパス

1. OpenSpec の作業を始める前にセットアップを診断します。

uv run python skills/openspec-workflow/scripts/openspec_cli.py doctor

2. 重要なリポジトリ変更では、利用可能な場合、生成済みの上流 OpenSpec スキル／コマンドを使って OpenSpec の変更を作成または継続します。

3. 生成済みの上流 OpenSpec スキルを利用できない場合は、リポジトリのラッパーを使って構造化された状態を確認します。

uv run python skills/openspec-workflow/scripts/openspec_cli.py status --change <change> --format json
uv run python skills/openspec-workflow/scripts/openspec_cli.py instructions <artifact> --change <change> --format json

4. 実装の完了またはアーカイブの前に検証します。

uv run python skills/openspec-workflow/scripts/openspec_cli.py validate

OpenSpec を使用する場面

次のいずれかに影響する変更では、OpenSpec を使用します。

• skills/、agents/、mcp/、mcp.json、またはファーストパーティの MCP 規約
• AGENTS.md、instructions/、またはプラットフォームブリッジファイル
• agent-bundle.json、プラグインマニフェスト、同期マニフェスト、または下流ハーネスのセットアップ
• ポータブルなスキル CLI の動作、生成される README／ドキュメントの出力、またはドキュメントのナビゲーション
• OpenSpec の仕様、スキーマ、または下流ツールのセットアップ生成

ユーザーのリクエストとリポジトリの規約によって結果が完全に定まり、変更が小規模で独立した誤字修正、または単一ファイル内のローカルな変更である場合は、OpenSpec を使用しません。

重要な変更の対象範囲や進め方に、ユーザーの判断が不可欠な分岐がある場合は、変更アーティファクトの作成または継続の前に、instructions/global.md の Depth ルーティングを適用し、/grill-me を実行します。

下流ツール

OpenSpec が生成する上流のスキルとコマンドは、デフォルトでローカルに生成されます。下流ツールでネイティブの OpenSpec ワークフローを利用できるようにする場合は、次のように展開します。

uv run python skills/openspec-workflow/scripts/openspec_cli.py init --apply
uv run python skills/openspec-workflow/scripts/openspec_cli.py update --apply

デフォルトのリポジトリマッピングは次のとおりです。

リポジトリエージェント	OpenSpec ツール
claude-code	claude
codex	codex
crush	crush
cursor	cursor
opencode	opencode

ユーザーが特定のアーティファクトをリポジトリ管理のソースとして明示的に採用しない限り、生成された .claude、.cursor、.opencode、.agent、.crush、または .codex の OpenSpec アーティファクトはコミットしないでください。

アーティファクトの順序

エージェントアセットの変更

このリポジトリのカスタム agent-asset-change スキーマでは、次の順序でアーティファクトを作成します。

1. proposal
2. affected-surfaces
3. design
4. validation-matrix
5. tasks

openspec status --json を使って、AI にアーティファクトの作成を依頼する前に、どのアーティファクトの準備ができているかを確認します。

アーカイブの準備

実装と検証が完了してからアーカイブします。proposal、affected surfaces、design、validation matrix、tasks を、最終的にリリースする状態に合わせて整合させてください。

標準用語

以下の標準用語をそのまま使用してください。

用語	意味
OpenSpec change	openspec/changes/ で追跡される、リポジトリの動作またはアセットの変更案
Artifact	提案、設計、タスクリスト、仕様の差分、または AI が読み取れる指示ドキュメント
Downstream tool setup	外部エージェントのハーネス向けに生成されるローカルのスキル、コマンド、または設定
Archive	完了した変更を確定し、永続的な仕様履歴に移すこと
Validation matrix	影響を受けるサーフェスと、必要な検証コマンドを対応付けるアーティファクト

検証契約

変更の完了を宣言する前に、このスキルのディレクトリから実行してください。

python scripts/check.py
uv run python skills/openspec-workflow/scripts/openspec_cli.py doctor --format json
uv run python skills/openspec-workflow/scripts/openspec_cli.py validate --format json

Node/OpenSpec ツールがないためにコマンドを実行できない場合は、障害となっている要因と、Node >=20.19.0 のインストール後に実行すべき正確なコマンドを報告してください。

完了条件：

1. scripts/check.py が 0 で終了すること。
2. openspec_cli.py doctor と validate が成功すること。そうでない場合は、障害となっている要因に正確な再実行コマンドを含めること。
3. スキルのディレクトリに、リポジトリのコントロールプレーン CLI への参照がないこと。
4. OpenSpec の判断が、リポジトリのポリシーと実際に影響を受けるファイルに基づいていること。
5. 必須のアーティファクトが存在すること。存在しない場合は、理由を明記して明示的にスキップすること。
6. 生成されたダウンストリームのアーティファクトは、明示的に昇格されない限りコミットしないこと。

重要なルール

1. 公開アセットの形式、ダウンストリームツール、ドキュメント生成、フック、バンドルのメタデータ、または検証動作に関する重要な変更には OpenSpec を使用してください。
2. 孤立した誤字の修正や、リポジトリの規約によって結果が完全に決まる単一ファイルのローカル編集には、OpenSpec を使用しないでください。
3. 別の AI ツールが機械可読な状態や指示を必要とする場合は、uv run python scripts/openspec_cli.py ... --format json を優先してください。
4. .claude、.cursor、.opencode、.github、.agent、.crush、.codex、.gemini の生成済み OpenSpec アーティファクトは、明示的に昇格されない限りコミットしないでください。
5. アーカイブの前に検証してください。タスク、仕様、または検証に未解決の問題がある変更は、決してアーカイブしないでください。
6. 生成されたダウンストリームのスキルとコマンドは、デフォルトでローカルに保ってください。
7. OpenSpec または Node のツールがない場合は、障害となっている要因として報告し、セットアップ後に再試行する正確なコマンドを示してください。