Phases Agents

phases-agents

English · フランス語

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

サーバーは 1 つ。ツールは 5 つ。知らないうちに実行されるものはありません。

理由

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

phases-agents は即興をなくします。ローカルプロジェクトのプロファイルを作成し、厳格な契約に照らしてスキルカタログを検証し、再実行可能な計画を返します。同じ対象、同じカタログ、同じパラメーターなら、同じ判断になります。

原則

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

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

アーキテクチャ

モジュールは src/phases_agents/ にあります。

ファイル	役割
validator.py	公式契約と検証済みスナップショット
skill_loader.py	制限付きのローカル検出
skill_runtime.py	信頼されたルートと検証済みキャッシュ
skill_types.py	不変の型と制限
registry.py	検証済みの不変レジストリ
detector.py	対象のローカルプロファイル
planner.py	決定論的な選択と順序付け
server.py	JSON-RPC/MCP トランスポート
capabilities.py	クライアント機能の語彙
profile_facts.py	バージョン管理されたプロファイル事実の語彙
skill_gaps.py	ギャップルール（skills_missing）

規範となる契約は src/phases_agents/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" }
  ]
}

pip install -e .
phases-agents --skills-config /absolute/path/to/skills-roots.json

pip install -e . を実行すると、phases-agents コマンドがインストールされます。インストールせずに起動する場合も、同じサーバーを PYTHONPATH=src python -m phases_agents.server で起動できます。

サーバーは標準入力から 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" はバージョン管理された形式の名前であり、サーバーのバージョンではありません。公式スキーマは src/phases_agents/core/PLAN_B3_SCHEMA.json です。新しい作業にはこちらを使用してください。plan_version を指定しない場合、従来の形式で手順のフラットなリストが返されます。既存の呼び出し元に影響しないよう維持されていますが、削除前に非推奨となる予定です。client_capabilities は B3 でのみ受け付けられます。クライアントができることの宣言が意味を持つのは、この形式だけだからです。

MCP クライアントへの接続

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

{
  "mcpServers": {
    "phases-agents": {
      "command": "phases-agents",
      "args": [
        "--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 未満に収まります。

最初の呼び出しで検証済みレジストリが構築されます。2 回目以降の呼び出しでは、内容を再読み込みせずにメタデータを検証します。refresh_skills を実行すると再構築されます。

スキルパッケージの作成

各パッケージはルートの直接の子ディレクトリで、少なくとも次のものを含みます。

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

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

SKILL.md frontmatter

使用できるキーは5つです。いずれも省略可能で、記載されている場合はすべて検証されます。

キー	制約
name	phases.json.id と一致する必要があります
description	長さに上限がある自由記述です
version	phases.json.version と一致する必要があります
owner	自由形式の作成者識別情報です。不可視文字は使用できません
license	Apache-2.0、MIT、BSD-2-Clause、BSD-3-Clause のいずれかです

必須セクション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 は、検出器が出力できる次の値と少なくとも1つが一致する必要があります：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。

提供される機能は開放型の語彙です。各カタログで提供する機能を指定し、形式のみが検証されます（^[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 に記述されており、これが引き続き信頼できる唯一の情報源である点です。バージョンルールがその例です： 1.0 のマニフェストでは provides_capabilities は禁止され、1.1 では必須です。このルールは適用され、テストもされていますが、スキーマでは表現できません。required が契約のすべてだと解釈しないでください。

SKILL.md だけのパッケージは失敗します。無効なパッケージは、問題を黙って無視するのではなく、レジストリをブロックします。

ID

phases.json.id が識別子であり、SKILL.md.name はこれと一致する必要があります。ディレクトリにも同じキーを付与する必要があります。キーは NFKC で正規化した後に casefold されるため、同形異字で別の識別子を紛れ込ませることはできません。衝突が1つでもあれば、ビルド全体がブロックされます。パッケージが恣意的に選ばれることはありません。

選定

レジストリ内の有効なスキルはすべて、理由とともに必ず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

期待される結果は、全プラットフォームで収集テスト778件、失敗0件です。

Linux           : 771 passed, 7 skipped
Windows (CI)    : 778 passed, 0 skipped
Windows (local) : 776 passed, 2 skipped

スキップされるのはプラットフォームの機能によるもので、失敗ではありません。Linuxでは、POSIXに相当するものがないWindowsジャンクションのテストがスキップされます。Windowsでは、シンボリックリンクを作成するためのローカル権限がない場合に限り、2件のシンボリックリンクテストがスキップされます。そのため、その権限を持つランナーではスキップは一切報告されません。上記の件数はすべて実際の実行結果です。Windowsの2行は、GitHub Actionsのランナーとローカルマシンの結果です。

規範テキストはLF改行でチェックアウトされるよう、.gitattributes で指定されています。Windowsのシンボリックリンクテストのうち数件は、Windowsのローカル権限が必要なためスキップされます。Windowsジャンクションは実際にテストされます。

証明のレベル

バリデーターが確認するのは、次の1点だけです。

STRUCTURALLY_VALIDATED

実際の対象は検証しません。V1では TARGET_VERIFIED は引き続き禁止されています。

セキュリティ

ローダーはリパースポイントを拒否します。読み取りは上限が設けられ、許可された範囲内に制限されます。出力はソートされ、決定的です。

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

保証しないこと

• あらゆるケースに通用するセマンティックな関連性
• 外部スキルの自動承認
• スクリプト内容の監査
• 実際にマウントされた対象の証明
• Windowsでの完全なアトミック性
• あらゆるケースに通用するHTMLの認識
• あらゆるケースに通用するシークレットの検出
• 法令遵守の保証
• マーケットプレイスなし、リモートソースなし

ライセンス

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