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

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

信頼できる情報源。 機械可読で、ゲートによって強制される契約は、src/apothem/schemas/ 配下のクラスごとの JSON Schema（agent.schema.json、command.schema.json、skill.schema.json、…）です。スキルとコマンドのスキーマは additionalProperties: false を宣言しているため未知のキーを拒否します。エージェント、出力スタイル、プランのスキーマは additionalProperties: true を宣言しています。 本ページと frontmatter-schema.mdx は、これらのスキーマを人間が読める形にした 2 つの投影です。本ページはクラスごとのテンプレートと実例を扱い、frontmatter-schema は簡潔な必須キーの索引を扱います。ページが JSON Schema と食い違う場合は、スキーマが優先されます。

概要Copy Anchor Link

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

普遍的なルール:

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

バージョニング規約（バージョンを持つアーティファクトクラス — コマンド、ヘルパー、スキル、CLAUDE.md）:

• version はセマンティック（MAJOR.MINOR.PATCH）です。互換性のないスキーマまたは契約の変更では MAJOR を上げます。互換性を壊さない追加的な変更（新しい任意フィールド、追加のセクション、追加のアンチパターン）では MINOR を上げます。契約を壊さずに既存の指令を修正する挙動の変更では PATCH を上げます。
• 誤字の修正、リンクの修正、整形、コメントのみ、またはドキュメントのみの編集では、version は変わりません。挙動の変更のみがバージョンを上げます。
• updated は、直近の編集の ISO 8601 日付（YYYY-MM-DD）です。version を上げるたびに必ず変更しなければならず、バージョンを上げない誤字やリンクの修正でも変更されます。
• 新しいアーティファクトは v0.Y.Z から始まります。vX.Y.Z への昇格は、アーティファクトの契約が公開のコミットメントとして十分に安定していることを示します。
• プランスイートは、この規約の対象外です。プランスイートの誤字修正は、スイートのバージョンの PATCH 番号を上げ（vX.Y.Z から vX.Y.(Z+1) へ）、改訂履歴の行を追加します。開発者ガイドは、プランスイートの改訂のセクションで、プランスイートのルールを説明しています。

スキーマ: ルールCopy Anchor Link

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

目的: 振る舞いに関するマンデートと運用上の指令。

必須フィールドCopy Anchor Link

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

任意フィールドCopy Anchor Link

ルールには任意のフロントマターフィールドがなく、また他のアーティファクトクラスとは異なり、version / updated / scope / portability フィールドもありません。上記の 4 つの必須フィールドが、frontmatter_grep によって強制されるルールのフロントマター契約のすべてです。

例Copy Anchor Link

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

# Rule: Operational Mandates
...

スキーマ: コマンドCopy Anchor Link

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

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

必須フィールドCopy Anchor Link

---
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: "Read, Glob, Grep"
---

任意フィールドCopy Anchor Link

コマンドには任意のフロントマターフィールドがありません — 上記の 8 つの必須フィールドが、command.schema.json（additionalProperties: false）によって強制されるコマンドのフロントマター契約のすべてです。

例Copy Anchor Link

---
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: "Read, Glob, Grep"
---

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

スキーマ: ヘルパーCopy Anchor Link

パスパターン:

src/apothem/agents/*.md

目的: 並列探索、監査、品質ゲートのための永続的なヘルパー定義（委任ワーカーとも呼ばれます）。

必須フィールドCopy Anchor Link

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

任意フィールドCopy Anchor Link

permissionMode: "default"       # Permission handling
memory: user | project | local  # Persistent-memory scope; omit for none
pattern: "Research" | "Audit" | "Implementation" | "Quality"  # Agent team pattern
portability: "universal"

例Copy Anchor Link

---
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"
portability: "universal"
---

You are a codebase exploration specialist...

スキーマ: スキルCopy Anchor Link

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

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

必須フィールドCopy Anchor Link

---
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, Glob, Grep"
---

任意フィールドCopy Anchor Link

argument-hint: "[args...]"                           # Usage pattern if userInvocable

例Copy Anchor Link

---
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: false
allowed-tools: "Read, Glob, Grep, Agent, TodoWrite"
argument-hint: "[--focus area] [--fix]"
---

## Purpose
...

スキーマ: フックCopy Anchor Link

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

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

設定ファイルのスキーマCopy Anchor Link

トップレベルキー hooks は、イベント名をマッチャーブロックの配列に対応付けます:

"hooks": {
  "<EventName>": [
    {
      "matcher": "<pattern>",
      "hooks": [
        {
          "type": "command",
          "command": "${PYTHON_BIN}",
          "args": ["${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py", "<EventName>", "<message-name>"],
          "timeout": <seconds>,
          "statusMessage": "<short human-readable label>"
        }
      ]
    }
  ]
}

-m apothem.hooks.dispatch 形式は、PYTHONPATH=src を使ってソースチェックアウトから開発する場合のものです。

必須イベントCopy Anchor Link

Claude Code テンプレートは、SessionStart、PreToolUse、PostToolUse、Stop の 4 つのイベントを登録します。scripts/dev/validate_hooks.py は、下の表にある 5 つのイベント（先の 4 つとは異なる集合）について settings.json を確認し、見つからなかったイベントをそれぞれ、失敗ではなく警告として報告します。PostToolUse は登録されていますが、その 5 つには含まれません。PreCompact と PostCompact はその 5 つに含まれますが、Claude Code には登録されていない（フックのリファレンス）ため、チェッカーは Claude Code ではこの 2 つについて警告します。

タイムアウト値は正規のフックイベント予算を反映しています — 下の表は読者の便宜のためにそれらを再掲したものであり、正規のソースが優先されます。

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

Python レイヤーCopy Anchor Link

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

検証Copy Anchor Link

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

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

スキーマ: CLAUDE.mdCopy Anchor Link

パス: CLAUDE.md（ルート）

目的: プロジェクトスコープの Claude Code 向け指示。

必須の YAML フロントマターCopy Anchor Link

---
name: "CLAUDE"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "Project-scoped Claude Code instructions for the Apothem source repository"
scope: "project"
portability: "project-local"
---

セクションCopy Anchor Link

CLAUDE.md は散文のセクションで書かれており、その内容は CLAUDE.md で説明されています。固定のセクション一覧を要求するバリデーターはありません。scripts/dev/validate_ecosystem.py は、上記のフロントマターのキーを確認します。

検証チェックリストCopy Anchor Link

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

フロントマターの検証Copy Anchor Link

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

コンテンツの検証Copy Anchor Link

• コンテンツが、閉じる --- の後の新しい行から始まる。Markdown 系のファイルでは、その直後の最初のコンテンツが正規の SPDX ヘッダー行である
• プラン内部への参照がない（CM-7 準拠）
• 相互参照が解決する（他のアーティファクトを列挙する場合）
• リンクがスラッシュ区切りの相対パスを使用している

ポータビリティの検証Copy Anchor Link

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

注記Copy Anchor Link

• セキュリティとしての一貫性: 正規のフロントマターは、自動検証、ツール化、アーティファクト横断の検証を可能にします。逸脱はすぐに積み重なります。
• ポータビリティの宣言: すべてのアーティファクトがユニバーサルになれるわけではありません。制約を明示的に宣言してください —— 気づかれないバグを出荷するよりも、注意書きを文書化するほうが良いのです。
• 名前には kebab-case: URL、スクリプト、コマンドラインの文脈で使いやすいためです。名前にはスペース、アンダースコア、camelCase を使わないでください。
• バージョン引き上げの衛生: 挙動を変えるすべての編集は、version と updated を一緒に上げなければなりません。誤字の修正、リンクの修正、整形の変更ではバージョンは変わりません。新しい任意セクションやアンチパターンは MINOR を上げ、構造の再編成や契約の変更は MAJOR を上げます。