アーティファクトスキーマ仕様

Apothem エコシステムのすべてのアーティファクトに対する正規の YAML フロントマターと必須フィールド。

概要

Apothem ソースツリー内（src/apothem/ 配下とルート設定サーフェス）のすべての アーティファクトは、そのアーティファクトタイプに固有の必須フィールドおよび 任意フィールドを持つ YAML フロントマターブロック（--- デリミタ間）を 含まなければなりません。本ドキュメントは各タイプの正規スキーマを定義します。

普遍的ルール：

• フロントマターは YAML 1.2 準拠
• すべての文字列値は、空でない限りダブルクォートを使用
• フィールド順序：必須フィールドを先頭に、任意フィールドは関連性ごとにグループ化
• フロントマター内のコメントはスペースつきの # を使用：# comment
• パス値は相対（先頭の / なし）でなければならず、クロスプラットフォーム互換のためにスラッシュ（/）を使用する

バージョニング規約（アーティファクトタイプを問わず普遍的）：

• version はセマンティック（MAJOR.MINOR.PATCH）です。破壊的なスキーマまたは契約の変更では MAJOR を、後方互換のある追加的変更（新しい任意フィールド、追加のセクション、追加のアンチパターン）では MINOR を、振る舞いを変えない明確化・整形修正・ドキュメントのみの編集では PATCH を上げます。
• updated は最も最近の編集の ISO 8601 日付（YYYY-MM-DD）です。version を上げるたびに変更されなければならず、バージョンを上げないリンク更新では独立して更新してかまいません。
• 新しいアーティファクトは v0.Y.Z で開始します。vX.Y.Z への昇格は、そのアーティファクトの契約が公開コミットメントとなるに十分なほど安定したことを示します。

スキーマ：ルール

パスパターン： src/apothem/rules/*.md

目的： 振る舞いの命令および運用上の指令。

必須フィールド

---
name: "kebab-case-identifier"
description: "One-line description"
pathFilter: "**/*.py, **/*.toml"
alwaysApply: true | false
---

任意フィールド（該当する場合）

Rules carry no optional frontmatter fields, and — unlike other artifact classes — no version / updated / scope / portability fields either. The four mandatory fields above are the complete rule frontmatter contract enforced by frontmatter_grep.

例

---
name: "operational-mandates"
description: "Behavioral definitions for CM-1 through CM-10: violation indicators and recovery actions"
pathFilter: ""
alwaysApply: true
---

# Rule: Operational Mandates
...

スキーマ：コマンド

パスパターン： src/apothem/commands/*.md

目的： スラッシュコマンド定義（/plan-execute、/freshify など）。

必須フィールド

---
name: "command-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this command does"
argument-hint: "[argument-pattern]"
disable-model-invocation: true | false
portability: "universal"
allowed-tools: "*"
---

任意フィールド

Commands carry no optional frontmatter fields — the eight mandatory fields above are the complete command frontmatter contract enforced by command.schema.json (additionalProperties: false).

例

---
name: "plan-execute"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Executes a specific phase from a Master Plan Suite with conformity checking and quality gates"
argument-hint: "[path/to/plan-suite/] [phase-id] [--dry-run]"
disable-model-invocation: true
portability: "universal"
allowed-tools: "*"
---

# /plan-execute — Execute a Specific Phase
...

スキーマ：ヘルパー

パスパターン：

src/apothem/agents/*.md

目的： 並列探索、監査、品質ゲートのための永続的なヘルパー定義。

必須フィールド

---
name: "agent-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this agent specializes in"
tools: "Tool1, Tool2, Tool3"
disallowedTools: "Write, Edit"
maxTurns: 20
effort: "high" | "medium" | "low"
---

任意フィールド

permissionMode: "default"       # Permission handling
memory: true | false                    # If true, agent retains memory across sessions
pattern: "Research" | "Audit" | "Implementation" | "Quality"  # Agent team pattern
portability: "universal"

例

---
name: "codebase-explorer"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Deep codebase exploration — find patterns, trace dependencies, discover conventions, map architecture"
tools: "Read, Glob, Grep, Bash"
disallowedTools: "Write, Edit, TodoWrite"
maxTurns: 20
effort: "high"
permissionMode: "default"
memory: false
portability: "universal"
---

You are a codebase exploration specialist...

スキーマ：スキル

パスパターン： src/apothem/skills/*/SKILL.md

目的： 検出シグナルと実行手順を備えた再利用可能なテクニック定義。

必須フィールド

---
name: "skill-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this skill teaches"
archetype: "workflow-template"
userInvocable: true | false
disable-model-invocation: true | false
allowed-tools: "Read, Write, Glob"
---

任意フィールド

argument-hint: "[args...]"                           # Usage pattern if userInvocable
effort: "low" | "medium" | "high" | "xhigh" | "max" # Optional effort level

例

---
name: "ecosystem-audit"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Comprehensive blind audit of the apothem ecosystem"
archetype: "audit-template"
userInvocable: true
disable-model-invocation: true
allowed-tools: "Read, Write, Edit, Glob, Grep, Bash"
argument-hint: "[--focus area] [--fix]"
effort: "max"
---

## Purpose
...

スキーマ：フック

パスパターン： settings.json の hooks ブロックと、src/apothem/hooks/ 配下の Python 実装。

目的： ホストが明確に定義されたライフサイクルポイントで呼び出す、 イベントトリガーのバリデーターと状態管理ハンドラーを宣言する。

設定ファイルスキーマ

hooks トップレベルキーは、イベント名をマッチャーブロックの配列にマッピングします：

"hooks": {
  "<EventName>": [
    {
      "matcher": "<pattern>",
      "hooks": [
        {
          "type": "command",
          "command": "python",
          "args": ["-m", "apothem.hooks.dispatch", "<EventName>", "<message-name>"],
          "timeout": <seconds>,
          "statusMessage": "<short human-readable label>"
        }
      ]
    }
  ]
}

必須イベント

出荷されるテンプレートは以下のイベントを登録します。バリデーターが PASS を 報告するには、5 つすべてが必須です：

タイムアウト値は正規のフックイベント予算を反映します — 以下のテーブルは 読者の便宜のためにそれらを再掲したものです。正規のソースが支配します。

dispatch.py は、前方互換性のために UserPromptSubmit と Notification も イベントホワイトリストで受け付けます。どちらも出荷テンプレートでは配線されて いません。同じ exec 形式パターンのマッチャーブロックを追加して有効化します。

Python レイヤー

すべてのフックコマンドは同じ Python ディスパッチャーを経由します：

検証

scripts/dev/validate_hooks.py はフック契約を強制します：

• settings.json が JSON としてパースされ、すべての必須イベントを宣言している。
• 3 つすべての Python スクリプトが存在し、有効な Python としてパースされる。
• --context-file 引数が参照するすべてのメッセージファイルが存在する。
• ハードコードされた絶対ユーザーパス（C:\Users\... など）が src/apothem/hooks/**.py に現れない。
• src/apothem/hooks/ と scripts/ 配下のシェルアーティファクトは、承認されたロケーター／ブートストラップスタブに限定される。

スキーマ：CLAUDE.md

パス： CLAUDE.md（ルート）

目的： グローバルなエコシステム設定インデックス。

必須 YAML フロントマター

---
name: "CLAUDE"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "Global Claude Code ecosystem configuration and mandate index"
scope: "always-on"
portability: "universal"
---

必須セクション（順序どおり）

1. §1 プランスイート — テンプレートの場所への参照
2. §2 認知アイデンティティ — 創造的アーキテクチャの命令
3. §3 アーティファクトディレクトリ — パスと目的のテーブル
4. §4 シリアスネススケール統治 — 4 レベルの定義
5. §5 運用指令 — 問題解決、コミュニケーションの原則
6. §6 横断的命令 — CM-1–28 の概観
7. §7 レジストリ — アーティファクトのテーブル：
   • 7.1 コマンド
   • 7.2 ルール
   • 7.3 ヘルパー
   • 7.4 フック
   • 7.5 スキル
   • 7.6 アーティファクト進化

検証チェックリスト

すべてのアーティファクトは以下のチェックを満たさなければなりません：

フロントマター検証

• YAML が構文的に有効（パースエラーなし）
• アーティファクトタイプに対するすべての必須フィールドが存在
• name が kebab-case 規約に従う
• version がセマンティック（MAJOR.MINOR.PATCH）
• updated が ISO 8601 日付形式（YYYY-MM-DD）
• description が空でない単一行の文字列
• 任意フィールドが期待される enum 値に一致（該当する場合）
• フィールド名にタイポがない（スキーマの正規名を使用）
• 余分な空白や整形上の問題がない

コンテンツ検証

• コンテンツが閉じる --- の直後の新しい行から始まる
• プラン内部の参照がない（CM-7 準拠）
• クロスリファレンスが解決する（他のアーティファクトを列挙する場合）
• リンクがスラッシュ付きの相対パスを使用

ポータビリティ検証

• ハードコードされた絶対パスがない（相対を使用）
• universal スコープのアーティファクトに Windows 固有の構文がない
• パス区切り文字がスラッシュを使用
• 環境変数がプラットフォーム非依存の形式（${VAR} またはツールネイティブ）を使用

注記

• セキュリティとしての一貫性： 正規のフロントマターは、自動検証、ツーリング、 クロスアーティファクト検証を可能にします。逸脱は急速に蓄積します。
• ポータビリティ宣言： すべてのアーティファクトが universal になれるわけでは ありません。制約を明示的に宣言してください — サイレントなバグを出荷するよりも 注意点を文書化するほうが良いのです。
• 名前には kebab-case： URL、スクリプト、コマンドラインコンテキストで使いやすい。 名前にスペース、アンダースコア、camelCase を避けてください。
• バージョンバンプの衛生： すべての振る舞いを変える編集は version と updated を 一緒に上げなければなりません。純粋な整形やタイポ修正は PATCH を、新しい任意セクションや アンチパターンは MINOR を、構造的な再編成や契約の変更は MAJOR を上げます。