OpenSpec

OpenSpec エージェント契約 ​

openspec CLIの機械可読なインターフェースであり、src/に対して検証済み（capstone監査、2026-06-11）。以下の各形状は、出力コードから文書化されています。

1. 一般規約 ​

  • 呼び出しごとに1つのJSONドキュメント。 --jsonモードでは、stdoutには正確に1つのJSONドキュメント（2スペースの整形表示）が含まれます。人間向けの文章、スピナー、ストアバナーはstderrに出力されます。
  • ストアバナー。 ヒューマンモードでは、ストアによって選択されたルートがUsing OpenSpec root: <id> (<path>)をstderrに出力します。JSONモードでは出力されません。
  • キーのケーシングはサーフェス依存です（既知の不整合を参照）：store/doctor/contextペイロードはsnake_caseを使用し、ワークフローペイロード（status、instructions、new change、validate、list）はcamelCaseを使用しますが、埋め込みのrootオブジェクトは常にstore_idを使用します。
  • ほとんどのペイロードでは、オプショナルキーはnullではなく省略されます（例：root.store_id、member.path）。明示的なnullを使用する例外は、シェイプごとに明記されています（store doctor git.*、失敗ペイロード）。

2. 診断エンベロープ ​

すべての機械可読診断（StoreDiagnostic）で共通のエンベロープ形状が使用されます：

json
{
  "severity": "error" | "warning" | "info",
  "code": "snake_case_string",
  "message": "human sentence",
  "target": "dotted.surface (optional)",
  "fix": "one actionable sentence/command (optional)"
}

診断は2つの位置に出現します：status 配列（トップレベルまたは各エントリごとに status: StoreDiagnostic[]）はヘルスチェック結果用、スローされたエラーはコマンド失敗時に単一要素の status 配列に変換されます。

3. ルート選択と RootOutput ​

すべてのルート解決コマンド（list、show、validate、status、instructions、instructions apply、instructions archive、new change、archive、doctor、context、schemas）は、以下の優先順位で1つの OpenSpec ルートを選択します：

  1. --store <id> → 登録済みストアのルート（source: "store"）。
  2. それ以外の場合、openspec/ を持つ最上位の祖先ディレクトリ：planning 形状 → source: "nearest"（store: ポインタは無視され、stderr に警告が表示されます）；store: ポインタが有効な config-only ディレクトリ → そのストア、source: "declared"。
  3. 最上位ルートなし + グローバル defaultStore が設定済み（openspec config set defaultStore <id>）→ そのストア、source: "global_default"；期限切れの id は基盤ストアエラーと openspec config unset defaultStore を示す fix で失敗します。
  4. 最上位ルートなし、デフォルトなし + 登録済みストアが存在 → エラー no_root_with_registered_stores。
  5. ルートなし、デフォルトなし、ストアなし：コマンドは cwd を source: "implicit" として扱う場合があります；doctor、context、list、一括 validate は代わりに no_openspec_root で失敗します。list は openspec/project.md を持つレガシープロジェクトに対して implicit フォールバックを維持します。

成功した JSON ペイロードは通常ルートを含みます；成功した schemas --json は §4.13 で文書化されている互換性のための素の配列のままです：

json
"root": { "path": "/abs/path", "source": "store" | "declared" | "global_default" | "nearest" | "implicit", "store_id": "id (only when store-selected)" }

ルート失敗の契約：JSON モードでは、解決失敗時に { ...commandNullShape, "status": [diagnostic] } が stdout に出力され、終了コード 1 で終了します。

4. コマンド JSON 形状 ​

4.1 list --json ​

{ "changes": [ { "name", "completedTasks", "totalTasks", "lastModified", "status": "no-tasks"|"complete"|"in-progress" } ], "root": RootOutput } — 各 change の status はここでは文字列 enum です。--specs：{ "specs": [ { "id", "requirementCount" } ], "root" }。

4.2 show <item> --json ​

Change：{ "id", "title", "deltaCount", "deltas": [...], "root" }。Spec：{ "id", "title", "overview", "requirementCount", "requirements": [...], "metadata": { "version", "format", "sourcePath"? }, "root" }。

4.3 validate --json ​

{ "items": [ { "id", "type": "change"|"spec", "valid", "issues": [ { "level", "path", "message", "line"?, "column"? } ], "durationMs" } ], "summary": { "totals": {items,passed,failed}, "byType": {...} }, "version": "1.0", "root" }。いずれかの item が失敗すると終了コード 1。

4.4 status --json ​

{ "changeName", "schemaName", "planningHome"?: { "kind", "root", "changesDir", "defaultSchema" }, "changeRoot", "artifactPaths": { "<id>": {outputPath, resolvedOutputPath, existingOutputPaths} }, "nextSteps": ["..."], "actionContext": { "mode": "repo-local", "sourceOfTruth": "repo", "planningArtifacts", "linkedContext", "allowedEditRoots", "requiresAffectedAreaSelection", "constraints" }, "isPlanningComplete", "isComplete", "applyRequires", "artifacts": [ {id, outputPath, status: "done"|"skipped"|"ready"|"blocked", requires, missingDeps?} ], "root" }。isPlanningComplete は、スキップされていないすべてのプランニングアーティファクトが存在することを意味します；スキップされたアーティファクトは作成されなくても満たされたものとみなされます。実装タスクが完了したことを意味しません。isComplete は同じ値を持つ互換性エイリアスとして保持されています。各アーティファクトの requires は直接依存関係の id です（すべての status で存在するため、アーティファクトが done の場合でも推移的に必要なセットを計算できます）；missingDeps は blocked の場合のみ出現します。artifacts 配列は依存関係の順序で並び、同時に準備完了となるアーティファクト間のタイブレークにはスキーマの artifacts: 宣言順序が使用されます（アルファベット順ではありません）。したがって、最初の ready エントリが次に書き込むべきアーティファクトです；missingDeps も同じ順序を使用します。"skipped" は、.openspec.yaml で skip_specs: true を宣言した change において generates パスが specs/ 配下にあるアーティファクトを示します；依存関係は満たされますが、作成すべきではありません。アクティブな変更がない場合：{ "changes": [], "message", "root" }、終了コード 0。

--all（バッチ、--change と排他的 — 組み合わせると { "changes": [], "root": null, "status": [d] } の null 形状でエラー）：{ "changes": [ <各 change の status オブジェクト、各 change の root なし>, ... ], "root" }、change 名でソート。読み込みに失敗した change は { "changeName", "status": [d] } をその位置に含みます；スイープは継続し、完全なエンベロープを維持し、テキストモードと JSON モードの両方で終了コード 1 で終了します。無効な --schema は、変更が存在しない場合でも全体を null 形状で失敗させます。

4.5 instructions <artifact> --json ​

{ "changeName", "artifactId", "schemaName", "changeDir", "planningHome"?, "outputPath", "resolvedOutputPath", "existingOutputPaths", "description", "instruction"?, "context"?, "rules"?, "references"?: ReferenceIndexEntry[], "skipped"?, "warning"?, "template", "dependencies": [{id,done,path,description,skipped?}], "unlocks", "root" }。unlocks はこのアーティファクトが準備完了にするアーティファクトを、スキーマの宣言順序で（status が推奨するのと同じ順序）列挙します。"skipped": true（"warning" 付き）は、change が skip_specs: true を宣言しこのアーティファクトがスキップされた場合に出現します — そのファイルを作成しないでください。skipped: true の依存エントリはファイルなしで満たされます — そのパスを読み込もうとしないでください。

ReferenceIndexEntry：{ "store_id", "root"?, "specs"?: [{id,summary}], "fetch"?, "status": [] } — 解決済みエントリは root/specs/fetch を持ち、未解決は store_id + 警告 status を持ちます。インデックスは 50KB 上限（reference_index_truncated）。

4.6 instructions apply --json ​

{ "changeName", "changeDir", "schemaName", "contextFiles": { "<artifactId>": ["/abs", ...] }, "progress": {total,complete,remaining}, "tasks": [{id,description,done}], "state": "blocked"|"all_done"|"ready", "missingArtifacts"?, "missingPrerequisites"?, "warnings"?, "instruction", "references"?, "context"?, "operationGuidance"?, "root" }。missingArtifacts は apply がブロックするもの（スキーマの apply.requires）です；missingPrerequisites は apply が実行される前にまだビルドが必要なすべてで、ビルド順序 — その requires の推移的閉包です。そのためより長いリストになる場合があります。warnings は change 自体の非ブロッキングな問題を列挙します — 現在、デルタスペックなしで skip_specs: true もない状態で実装準備完了の change、つまり openspec validate が拒否する状態です。両方の任意ルートフィールド（context、operationGuidance）は各呼び出しで選択されたルートから読み込まれます。context は関連するプロジェクト事実、慣習、制約が適用されるべき必須のプロンプトレベル入力です；operationGuidance は適用可能かつ組み込みワークフローと互換性がある場合のみ従う参考情報入力です。両者は state、tasks、progress、context ファイル、組み込み instruction と分離されます。

4.7 instructions archive --json ​

{ "changeName", "context"?, "operationGuidance"?, "root" }。解決された repo/store ルートで有効な --change を必要とし、apply と同じ必須 context/参考 guidance セマンティクスを使用します。これは読み取り専用のランタイム入力サーフェスです：静的アーカイブワークフローを返さず、デルタスペックを検査またはマージせず、メインスペックを書き込まず、変更を移動しません。

4.8 new change <name> --json ​

成功：{ "change": { "id", "path", "metadataPath", "schema" }, "root" }。失敗：{ "change": null, "status": [d] }、終了コード 1。

4.9 archive <name> --json ​

成功：{ "archive": { "change", "archivedAs": "YYYY-MM-DD-name", "path", "specsUpdated", "totals"?, "warnings"? }, "root" }。失敗：{ "archive": null, "root"?, "status": [d] }、終了コード 1。specsUpdated は少なくとも1つのスペックファイルが書き込まれたまたは廃止された場合のみ true です（change が最後の要件を削除したキャパビリティのスペックは削除されますが、これは change の .openspec.yaml で retire_capabilities: true を必要とします；すべての廃止は warnings に記載され、スペックが呼び出し元のチェックアウトに存在した場合のみ貼り付け可能な Git 復旧コマンドが付きます）；同期済みの change は全ゼロの合計でアーカイブされ、スキップは warnings に記載されます。JSON モードは厳密に非対話的です：すべてのプロンプトポイントは archive_* コードに変換されます。

4.10 doctor --json ​

{ "root": { "path", "source", "store_id"?, "healthy", "status": [] }, "store": { "id", "metadata": {present,valid,remote?}, "origin_url"?, "drift"?: {ahead,behind}, "status": [] } | null, "references": [...], "status": [] }。drift（アップストリーム追跡リファレンスを持つ git ベースのストアチェックアウトでのみ存在）は、ライブリモートではなく最終フェッチ時のアップストリームに対する ahead/behind カウントです。いかなる重大度のヘルスチェック結果でも終了コード 0。失敗ペイロード：{ "root": null, "store": null, "references": [], "status": [d] }、終了コード 1。

4.11 context --json ​

{ "root": { "path", "source", "store_id"?, "role": "openspec_root" }, "members": [ { "role": "referenced_store", "id", "path"?, "remote"?, "fetch"?, "status": [] } ], "status": [] }。AVAILABLE = パスが存在 AND status が空。--code-workspace <path> は {folders:[{name,path}]} を書き込みます（利用可能な参照ストアのみ、ref: プレフィックス付き）；JSON モードでは書き込みは出力前に実行されるため、書き込み失敗時も stdout に正確に1つのドキュメントが保持されます。失敗：{ "root": null, "members": [], "status": [d] }、終了コード 1。

4.12 store ... --json ​

setup/register：{ "store": {id, root, metadata_path?}, "registry": {path, registered, already_registered}, "git": {is_repository, initialized, committed}, "created_files": [], "status": [] }。unregister/remove：{ "store", "registry": {path, removed}, "files": {deleted, deleted_path, left_on_disk}, "status": [] }。list：{ "stores": [{id, root}], "status": [] }。doctor：{ "stores": [ { id, root, metadata_path?, openspec_root: {...healthy, status}, metadata: {present, valid, id?, remote}, git: {is_repository, has_commits, has_uncommitted_changes, has_remote, origin_url}, status } ], "status": [] }（null = 不明/未プローブ）。ヘルスチェック結果は終了コード 0；失敗は対応する null 形状で終了コード 1。プロンプトキャンセルは終了コード 130。

4.13 schemas --json / templates --json ​

schemas：成功時は素の配列 [ {name, description, artifacts, source} ] のままです；正規のルート選択優先順位を解決し、--store <id> を受け入れます。ルート選択失敗：{ "schemas": [], "root": null, "status": [d] }、終了コード 1。templates：キー付きオブジェクト { "<artifactId>": {path, source} }、引き続き cwd ベースで root/status キーなし。

5. 終了コード契約 ​

状況終了コード標準出力
成功（doctor/context/store doctor の健全性の所見を含む）0ペイロード
--json モードでのコマンド失敗1status: [d] とコマンドの null-shape を持つ1つのJSON文書
失敗項目がある validate1完全なレポート
プロンプトのキャンセル（store グループ、ヒューマンモード）130標準エラー出力のみ

6. 診断コードカタログ ​

解決 ​

no_openspec_root, no_root_with_registered_stores, no_registered_stores, unknown_store, store_identity_mismatch, unhealthy_store_root, store_path_not_supported, invalid_store_pointer, initiative_option_removed, areas_option_removed; パススルー: invalid_store_id, invalid_store_registry, invalid_store_metadata.

OpenSpecルートの健全性（エラー、修正なし） ​

openspec_store_root_missing, openspec_store_root_not_directory, openspec_root_missing, openspec_root_not_directory, openspec_config_missing, openspec_config_not_file, openspec_specs_not_directory, openspec_changes_not_directory, openspec_archive_not_directory. ストアのベータ期間中、openspec/specs/、openspec/changes/、openspec/changes/archive/ は健全なルートに存在しなくてもよい。それらは、存在するがディレクトリでない場合にのみ健全性エラーとなる。

ストアレジストリ/識別情報/状態 ​

invalid_store_id, invalid_store_registry, invalid_store_metadata, store_registry_busy, store_not_found, no_store_registry, store_registry_changed, store_metadata_missing, store_metadata_id_mismatch, store_metadata_invalid, store_id_conflict, store_path_conflict, store_already_registered（情報）.

ストアのセットアップ/登録/削除 ​

store_setup_id_required, store_setup_path_required, store_setup_path_not_directory, store_setup_inside_git_repo, store_setup_non_empty_directory, store_setup_cancelled, store_path_required, store_path_missing, store_path_not_directory, store_root_pointer_declared, store_register_root_unhealthy, store_register_identity_confirmation_required, store_register_cancelled, store_remote_empty, store_remote_requires_hand_edit, store_remove_confirmation_required, store_remove_cancelled, store_remove_path_not_directory, store_remove_metadata_missing, store_root_missing（removeでは警告、doctorではエラー）, store_root_not_directory.

ストアのGit ​

store_git_init_failed, store_git_identity_missing, store_git_commit_failed, store_git_no_commits（警告）, store_clone_fragile_directories（警告）, store_remote_divergence（情報、doctor）, store_checkout_drift（情報、doctor）.

参照（警告） ​

reference_invalid_id, reference_registry_unreadable, reference_unresolved, reference_root_unhealthy, reference_index_truncated.

リレーションシップ（警告、doctor、コンテキストはレジストリのもののみ保持） ​

relationship_registry_unreadable, root_pointer_ignored, root_pointer_invalid, pointer_declarations_inert.

アーカイブ（JSONモード） ​

archive_change_name_required, archive_change_not_found, archive_change_symlink, archive_validation_failed, archive_confirmation_required, archive_tasks_incomplete, archive_spec_update_failed, archive_spec_validation_failed, archive_target_exists, archive_error.

コンテキストの書き込み ​

context_file_exists, context_output_dir_missing.

フォールバック ​

doctor_failed, context_failed, store_error, change_error, archive_error.

既知の不整合 ​

キャップストーン監査によって記録されたもの。公開キーの名前変更はこのリリースを超えて延期された製品上の決定である：

  1. --json モードでは、いくつかの失敗パスが JSON 文書なしで標準エラー出力のみを出力していた。 キャップストーンガントレットラウンドで修正済み: show/validate の未知および曖昧な項目は {status:[{code: unknown_item | ambiguous_item, ...}]} を出力する。status/instructions/list/show/validate でスローされたエラーは JSON 対応の失敗ヘルパー（コマンドの null-shape + status）を通る。store <未知のサブコマンド> --json は {status:[{code: unknown_store_subcommand}]} を出力する。list は解決失敗時に {changes|specs: [], root: null} の null-shape を保持する。
  2. store_root_missing は2つの重大度で出力される（removeでは警告、store doctorではエラー）— コンテキスト依存であり、上記に文書化されている。
  3. snake_case（ストア系）と camelCase（ワークフロー系）のキー命名規則。root.store_id はすべての場所で snake_case である。
  4. src には4つの並行するエンベロープ型宣言が存在し、アーカイブ診断は target を運ばない。
  5. list --json は変更ごとに status キーを文字列列挙型として再利用する。
  6. validate の出力のみが version フィールドを保持する。
  7. templates はルート選択を無視する（cwd ベース、--store なし）。
  8. 非推奨の名詞形（change/spec サブコマンド）は root/status なしの非エンベロープペイロードを出力する。