phases-agents

English · Français

スキルを決定論的に発見・検証・選択するローカルMCPサーバー。Python標準ライブラリのみで、実行時の依存関係はありません。

1つのサーバー。5つのツール。背後で何かを実行することはありません。

なぜ

AIエージェントは即興で動きます。同じ質問を2回すると、2つの異なる計画が返ってきます。ブレインストーミングには問題ありませんが、監査やコンプライアンスの作業では許容できません。

phases-agents は即興性を排除します。ローカルプロジェクトをプロファイリングし、厳格な契約に照らしてスキルカタログを検証し、リプレイ可能な計画を返します。同じターゲット、同じカタログ、同じパラメータ、同じ決定。

原理

configured root identifiers
→ bounded discovery
→ official validation
→ immutable registry
→ verified cache
→ detector profile
→ deterministic selection
→ MCP plan

サーバーは選択して公開します。呼び出し元のモデルは、選択されたスキルを読み取り、自身のツールを使ってそれらをどう扱うかを決定します。サーバーがスキルを実行することは決してありません。

アーキテクチャ

規範となる契約は core/SKILLS_CONTRACT.md（フランス語）にあります。

クイックスタート

examples/skills/ にサンプルパッケージが同梱されています。3つのステップで実際の計画が生成されます。

git clone https://github.com/Cherridsaid/phases-agents && cd phases-agents

サンプルルートを指す skills-roots.json を作成します：

{
  "config_version": "1.0",
  "roots": [
    { "id": "demo", "path": "/absolute/path/to/phases-agents/examples/skills" }
  ]
}

python server.py --skills-config /absolute/path/to/skills-roots.json

サーバーは標準入力からJSON-RPCを1行ずつ読み取ります。Pythonプロジェクトに対する phases_agents_plan 呼び出しは、hello-python を選択します：

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"phases_agents_plan",
 "arguments":{"root_ids":["demo"],"target":"/absolute/path/to/a/project",
 "today":"2026-08-27","plan_version":"B3",
 "client_capabilities":["filesystem_read","filesystem_search"]}}}

2つの計画フォーマットが共存します。"B3" はバージョン管理されたフォーマットの名前であり、サーバーバージョンではありません。その公式スキーマは core/PLAN_B3_SCHEMA.json です。新規作業にはこれを使用してください。plan_version がない場合、レガシーフォーマットはフラットなステップリストを返します。これは既存の呼び出し元を壊さないために維持されており、削除前に非推奨化される予定です。client_capabilities はB3でのみ受け付けられます。クライアントが何をできるかを宣言することは、そのフォーマットでのみ意味を持つからです。

MCPクライアントの接続

Claude Code（プロジェクトのルートにある .mcp.json）：

{
  "mcpServers": {
    "phases-agents": {
      "command": "python",
      "args": [
        "/absolute/path/to/phases-agents/server.py",
        "--skills-config",
        "/absolute/path/to/skills-roots.json"
      ]
    }
  }
}

Codex も自身の設定ファイルで同じコマンド/引数のペアを使用します。トークンも環境変数も必要ありません。

MCPツール

detect(target)
list_skills(root_ids, today)
get_skill(root_ids, today, skill_id)
plan(root_ids, target, today, constraints?)
plan(root_ids, target, today, plan_version, client_capabilities?)
refresh_skills(root_ids, today)

today は時計から読み取られるのではなく注入されるため、すべての呼び出しがリプレイ可能です。get_skill はパスではなく識別子を受け取り、その内容は検証済みスナップショットから取得されます。公開出力では、絶対パスと検出されたシークレットはマスクされます。エンコードされたJSON-RPCレスポンスはすべて1 MiB未満に保たれます。

最初の呼び出しで検証済みレジストリが構築されます。ウォームコールはコンテンツを再読み取りせずにメタデータを検証します。refresh_skills は再ビルドを強制します。

スキルパッケージの作成

各パッケージはルートの直接の子であり、少なくとも以下を含みます：

<root>/<skill-id>/SKILL.md
<root>/<skill-id>/phases.json

最も早く始めるには、examples/skills/hello-python/ をコピーして識別子をリネームします。

SKILL.md フロントマター

許可されるキーは5つです。すべて任意ですが、存在する場合はすべてチェックされます。

必須の14セクション

それぞれはMarkdownの見出し（##）で、順序は任意です。セクションタイトルはフランス語です。タイトルは契約に属するためです。本文はどの言語で書いても構いません。

Loi centrale · Ce que ce skill fait · Ce que ce skill ne fait pas · Conditions d'activation · Conditions d'exclusion · Capacites necessaires · Interdictions · Methode d'audit · Contrat de preuve · Format de sortie · Conditions de blocage · Limites connues · Exemples d'entree · Exemple de sortie attendue

phases.json のフィールド

すべて必須：schema_version、id、version、title、description、domain、project_types、platforms、activation、exclusions、requires_capabilities、optional_capabilities、forbidden_capabilities、execution_mode、human_approval、output_schema、rules_path、references_path、scripts_path、tests_path、files。

output_schema はシンボリック形式の core:SCHEMA_NAME.json を使用します。

クローズド語彙

project_types は検出器が出力できるものと交差する必要があります：apk、python、skill_package、solana、web。

activation.any はプロファイルファクトを使用します：collects_personal_data、has_api、has_apk、has_authentication、has_database、has_ecommerce、has_eu_context、has_file_upload、has_javascript、has_python、has_rust、has_skill_packages、has_solana、has_source_code、has_typescript、has_web、uses_ai、uses_payments。

requires_capabilities、optional_capabilities、forbidden_capabilities は次を使用します：browser、dependency_installation、filesystem_read、filesystem_search、filesystem_write、human_question、shell、target_code_execution、web。

Provided ケイパビリティはオープンな語彙です。各カタログは自身がもたらすものを命名し、強制されるのは形状のみです（^[a-z][a-z0-9_]{0,63}$）。クローズドなのはクライアントケイパビリティだけです。それらはあなたのドメインではなくプロトコルを記述するからです。

domain が legal、juridique、regulatory、compliance のいずれかの場合、追加の制度が発動します。引用されるすべてのルールには、公式情報源、管轄、検証日が必須です。

スキーマが言うことと言わないこと

SKILL_MANIFEST_SCHEMA.json は phases.json の形状を記述します：必須フィールド、型、クローズド語彙。

スキーマエンジンは意図的に最小限に設計されています。適用されるのは enum、minLength、minItems のみで、それ以外はありません：pattern も if/then も oneOf もありません。これらのキーワードを使用するスキーマは、それ自体が拒否されます。

その帰結は重要です：条件付きルールは validator.py にあり、そこが真実の源泉であり続けます。バージョンルールがその例です — provides_capabilities は 1.0 マニフェストでは禁止され、1.1 では必須です。このルールは強制されテストされていますが、スキーマでは表現できません。required を契約の全体として読まないでください。

SKILL.md だけのパッケージは失敗します。無効なパッケージは、静かに劣化するのではなく、レジストリをブロックします。

アイデンティティ

phases.json.id がアイデンティティであり、SKILL.md.name はそれと一致する必要があります。ディレクトリも同じキーを持つ必要があります。キーはNFKCで正規化された後 casefold されるため、ホモグリフが2つ目のアイデンティティを忍び込ませることはできません。衝突があればビルド全体がブロックされます。パッケージが恣意的に選ばれることはありません。

選択

レジストリ内のすべての有効なスキルは、その理由とともに、ちょうど1つのカテゴリに分類されます。何も黙って破棄されることはありません。

証明された唯一の自動シグナルは次のとおりです：

project_types ∩ profile.types

プラットフォーム、ドメイン、ケイパビリティは、呼び出し元がそれらの制約を指定した場合にのみフィルタリングします。禁止されたケイパビリティはスキルを拒否します。意味的スコアはでっち上げられず、計画は識別子でソートされます。

空の計画は明示的に有効です：NO_COMPATIBLE_SKILL を持ちます。

B3 計画は、インストールされたすべてのスキルを skills_selected、skills_not_applicable、skills_blocked に分類します。各スキルは正確に1回だけ出現します。skills_missing は、実行可能なプロバイダを持たないケイパビリティを、確認済みのファクトのみから導出してリストします。ギャップが不適合を証明することは決してありません — それは、必要と判断された監査がカバーされていないことを示すだけです。

制限

• ルートは最大16

• 直接の深さのみ

• パッケージは最大1,000

• ルートごとに10,000エントリまで

• SKILL.md は256 KiB上限

• 個々の参照は256 KiB上限、合計1 MiBまで

• スナップショットは16 MiB上限

• 公開結果は1 MiB上限

• パッケージごとに100件の問題まで

• フィンガープリントは100,000ノード上限

呼び出し元はこれらの制限を下げることのみ可能で、上げることはできません。

ランタイム制約

• Python >=3.11

• サードパーティのランタイム依存なし

• 暗黙のネットワークなし

• ランタイムシェルなし

• ターゲットコードは実行されない

• 暗黙のクロックなし

• テレメトリなし

• スキルのダウンロードなし

pytest は開発依存のみです。

テスト

python -m pytest -q

期待される結果：

729 passed, 2 skipped
0 failed

規範テキストは、.gitattributes によってLF行末でチェックアウトされます。Windowsのシンボリックリンクのテストは2件スキップされます：それらはローカルWindows特権を必要とするためです。Windowsジャンクションは実際にテストされています。

証明のレベル

バリデータが確認するのはただ1つのことだけです：

STRUCTURALLY_VALIDATED

実際のターゲットは検証しません。TARGET_VERIFIED はV1では禁止されたままです。

セキュリティ

ローダーはリパースポイントを拒否します。読み取りは制限され、封じ込められます。出力はソートされ、決定論的です。

1つの設計判断に注意が必要です：detect と plan は、設定されたルートに制限されない target パスを受け取ります。任意のプロジェクトをプロファイリングすることが目的だからです。このサーバーは、影響範囲を受け入れられるアカウントで実行し、信頼できるクライアントにのみ接続してください。完全な脅威モデルは SECURITY.md にあります。

非保証事項

• 普遍的な意味的関連性の保証なし

• 外部スキルの自動承認なし

• スクリプト内容の監査なし

• 実際にマウントされたターゲットの証明なし

• 完全なWindowsアトミック性なし

• 普遍的なHTML認識なし

• 普遍的なシークレット検出なし

• 法的コンプライアンスの保証なし

• マーケットプレイスなし、リモートソースなし

ライセンス

Apache-2.0。LICENSE と NOTICE を参照してください。