{
  "markdown": "<!-- mcp-name: io.github.Cherridsaid/phases-agents -->\n\n# phases-agents\n\n*English · [Français](README.fr.md)*\n\n![phases-agents: select, block, prove](https://raw.githubusercontent.com/Cherridsaid/phases-agents/main/docs/banner.png)\n\nA local MCP server that discovers, validates and selects skills\ndeterministically. Python standard library only, no runtime dependencies.\n\nOne server. Five tools. Nothing executed behind your back.\n\n## Why\n\nAI agents improvise. Ask the same question twice and you get two different\nplans. That is fine for brainstorming, and unacceptable for audit and\ncompliance work.\n\nphases-agents removes the improvisation. It profiles a local project,\nvalidates a catalogue of skills against a strict contract, and returns a plan\nthat can be replayed. Same target, same catalogue, same parameters, same\ndecision.\n\n## Principle\n\n![Same inputs, same plan](https://raw.githubusercontent.com/Cherridsaid/phases-agents/main/docs/determinism.png)\n\n```text\nconfigured root identifiers\n→ bounded discovery\n→ official validation\n→ immutable registry\n→ verified cache\n→ detector profile\n→ deterministic selection\n→ MCP plan\n```\n\nThe server selects and exposes. The calling model reads the selected skills\nand decides what to do with them, using its own tools. **The server never\nexecutes a skill.**\n\n## Architecture\n\nThe modules live in `src/phases_agents/`.\n\n| File | Role |\n|---|---|\n| `validator.py` | official contracts and validated snapshots |\n| `skill_loader.py` | bounded local discovery |\n| `skill_runtime.py` | trusted roots and verified cache |\n| `skill_types.py` | immutable types and limits |\n| `registry.py` | validated, immutable registry |\n| `detector.py` | local profile of the target |\n| `planner.py` | deterministic selection and ordering |\n| `server.py` | JSON-RPC/MCP transport |\n| `capabilities.py` | client capability vocabulary |\n| `profile_facts.py` | versioned profile-fact vocabulary |\n| `skill_gaps.py` | gap rules (`skills_missing`) |\n\nThe normative contract lives in `src/phases_agents/core/SKILLS_CONTRACT.md`\n(French).\n\n## Quick start\n\nAn example package ships in `examples/skills/`. Three steps produce a real\nplan.\n\n```bash\ngit clone https://github.com/Cherridsaid/phases-agents && cd phases-agents\n```\n\nCreate `skills-roots.json` pointing at the example root:\n\n```json\n{\n  \"config_version\": \"1.0\",\n  \"roots\": [\n    { \"id\": \"demo\", \"path\": \"/absolute/path/to/phases-agents/examples/skills\" }\n  ]\n}\n```\n\n```bash\npip install -e .\nphases-agents --skills-config /absolute/path/to/skills-roots.json\n```\n\n`pip install -e .` installs the `phases-agents` command. Without installing,\nthe same server starts with `PYTHONPATH=src python -m phases_agents.server`.\n\nThe server reads JSON-RPC line by line on standard input. A\n`phases_agents_plan` call against a Python project then selects\n`hello-python`:\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"phases_agents_plan\",\n \"arguments\":{\"root_ids\":[\"demo\"],\"target\":\"/absolute/path/to/a/project\",\n \"today\":\"2026-08-27\",\"plan_version\":\"B3\",\n \"client_capabilities\":[\"filesystem_read\",\"filesystem_search\"]}}}\n```\n\nTwo plan formats coexist. `\"B3\"` names the versioned **format**, not a server\nversion; its official schema is\n`src/phases_agents/core/PLAN_B3_SCHEMA.json`. Use it for new\nwork. Without `plan_version`, the legacy format returns a flat list of steps;\nit is kept so existing callers do not break, and will be deprecated before\nremoval. `client_capabilities` is only accepted in B3, since declaring what\nthe client can do only makes sense in that format.\n\n### Connecting an MCP client\n\nClaude Code (`.mcp.json` at the root of your project):\n\n```json\n{\n  \"mcpServers\": {\n    \"phases-agents\": {\n      \"command\": \"phases-agents\",\n      \"args\": [\n        \"--skills-config\",\n        \"/absolute/path/to/skills-roots.json\"\n      ]\n    }\n  }\n}\n```\n\nCodex uses the same command/arguments pair in its own configuration file. No\ntoken and no environment variable is required.\n\n## MCP tools\n\n```text\ndetect(target)\nlist_skills(root_ids, today)\nget_skill(root_ids, today, skill_id)\nplan(root_ids, target, today, constraints?)\nplan(root_ids, target, today, plan_version, client_capabilities?)\nrefresh_skills(root_ids, today)\n```\n\n`today` is injected rather than read from a clock, so every call is\nreplayable. `get_skill` takes an identifier, never a path, and its content\ncomes from the validated snapshot. Absolute paths and detected secrets are\nmasked in public output. Any encoded JSON-RPC response stays under 1 MiB.\n\nThe first call builds the validated registry. Warm calls verify metadata\nwithout re-reading contents. `refresh_skills` forces a rebuild.\n\n## Writing a skill package\n\nEach package is a direct child of a root and contains at least:\n\n```text\n<root>/<skill-id>/SKILL.md\n<root>/<skill-id>/phases.json\n```\n\nThe fastest way to start is to copy `examples/skills/hello-python/` and rename\nthe identifier.\n\n### SKILL.md frontmatter\n\nFive keys are allowed. All optional, all checked when present.\n\n| Key | Constraint |\n|---|---|\n| `name` | must equal `phases.json.id` |\n| `description` | bounded free text |\n| `version` | must equal `phases.json.version` |\n| `owner` | free author identity, no invisible characters |\n| `license` | `Apache-2.0`, `MIT`, `BSD-2-Clause` or `BSD-3-Clause` |\n\n### The fourteen required sections\n\nEach is a Markdown heading (`##`), in any order. **Section titles are French**,\nbecause they belong to the contract; the body is yours to write in any\nlanguage.\n\n`Loi centrale` · `Ce que ce skill fait` · `Ce que ce skill ne fait pas` ·\n`Conditions d'activation` · `Conditions d'exclusion` ·\n`Capacites necessaires` · `Interdictions` · `Methode d'audit` ·\n`Contrat de preuve` · `Format de sortie` · `Conditions de blocage` ·\n`Limites connues` · `Exemples d'entree` · `Exemple de sortie attendue`\n\n### phases.json fields\n\nAll required: `schema_version`, `id`, `version`, `title`, `description`,\n`domain`, `project_types`, `platforms`, `activation`, `exclusions`,\n`requires_capabilities`, `optional_capabilities`, `forbidden_capabilities`,\n`execution_mode`, `human_approval`, `output_schema`, `rules_path`,\n`references_path`, `scripts_path`, `tests_path`, `files`.\n\n`output_schema` uses the symbolic form `core:SCHEMA_NAME.json`.\n\n### Closed vocabularies\n\n`project_types` must intersect what the detector can emit: `apk`, `python`,\n`skill_package`, `solana`, `web`.\n\n`activation.any` uses profile facts: `collects_personal_data`, `has_api`,\n`has_apk`, `has_authentication`, `has_database`, `has_ecommerce`,\n`has_eu_context`, `has_file_upload`, `has_javascript`, `has_python`,\n`has_rust`, `has_skill_packages`, `has_solana`, `has_source_code`,\n`has_typescript`, `has_web`, `uses_ai`, `uses_payments`.\n\n`requires_capabilities`, `optional_capabilities` and\n`forbidden_capabilities` use: `browser`, `dependency_installation`,\n`filesystem_read`, `filesystem_search`, `filesystem_write`, `human_question`,\n`shell`, `target_code_execution`, `web`.\n\n**Provided** capabilities are an **open** vocabulary: each catalogue names what\nit brings, and only the shape is enforced (`^[a-z][a-z0-9_]{0,63}$`). Only\n**client** capabilities are closed, because they describe the protocol rather\nthan your domain.\n\nA `domain` of `legal`, `juridique`, `regulatory` or `compliance` triggers an\nextra regime: every rule cited must carry an official source, a jurisdiction\nand a verification date.\n\n### What the schema does and does not say\n\n`SKILL_MANIFEST_SCHEMA.json` describes the **shape** of `phases.json`:\nrequired fields, types, closed vocabularies.\n\nThe schema engine is deliberately minimal. It applies `enum`, `minLength` and\n`minItems`, and nothing else: no `pattern`, no `if`/`then`, no `oneOf`. A\nschema using those keywords would itself be rejected.\n\nThe consequence matters: **conditional rules live in `validator.py`**, which\nremains the source of truth. The version rule is the example:\n`provides_capabilities` is *forbidden* in a `1.0` manifest and *required* in a\n`1.1` one. That rule is enforced and tested, but it is not expressible in the\nschema. Do not read `required` as the whole contract.\n\nA package with only `SKILL.md` fails. An invalid package blocks the registry\nrather than degrading silently.\n\n## Identity\n\n`phases.json.id` is the identity, and `SKILL.md.name` must match it. The\ndirectory must carry the same key. Keys are normalised with NFKC then\n`casefold`, so homoglyphs cannot smuggle in a second identity. Any collision\nblocks the whole build; no package is elected arbitrarily.\n\n## Selection\n\n![Every skill is classified and justified](https://raw.githubusercontent.com/Cherridsaid/phases-agents/main/docs/classification.png)\n\nEvery valid skill in the registry lands in exactly one category, with its\nreason. Nothing is discarded silently.\n\nThe only proven automatic signal is:\n\n```text\nproject_types ∩ profile.types\n```\n\nPlatform, domain and capabilities filter only when the caller supplies those\nconstraints. A forbidden capability rejects the skill. No semantic score is\ninvented, and the plan is sorted by identifier.\n\nAn empty plan is explicitly valid: it carries `NO_COMPATIBLE_SKILL`.\n\nThe `B3` plan classifies every installed skill across `skills_selected`,\n`skills_not_applicable` and `skills_blocked`; each skill appears exactly once.\n`skills_missing` lists capabilities with no executable provider, derived from\nconfirmed facts only. **A gap never proves non-compliance**: it says an audit\ndeemed necessary is not covered.\n\n## Limits\n\n- 16 roots maximum\n- direct depth only\n- 1,000 packages maximum\n- 10,000 entries per root\n- `SKILL.md` capped at 256 KiB\n- a single reference capped at 256 KiB, 1 MiB in total\n- snapshots capped at 16 MiB\n- public result capped at 1 MiB\n- 100 issues per package\n- fingerprint capped at 100,000 nodes\n\nCallers may only lower these limits, never raise them.\n\n## Runtime constraints\n\n- Python `>=3.11`\n- no third-party runtime dependency\n- no implicit network\n- no runtime shell\n- no target code executed\n- no implicit clock\n- no telemetry\n- no skill downloaded\n\n`pytest` is a development dependency only.\n\n## Tests\n\n```bash\npython -m pytest -q\n```\n\nExpected result, 778 collected, 0 failed on every platform:\n\n```text\nLinux           : 771 passed, 7 skipped\nWindows (CI)    : 778 passed, 0 skipped\nWindows (local) : 776 passed, 2 skipped\n```\n\nThe skips are platform capabilities, not failures. Linux skips the\nWindows-junction tests, which have no POSIX equivalent. Windows skips the two\nsymlink tests only when the local privilege to create symlinks is missing, so a\nrunner that holds it reports no skip at all. Every count above comes from a real\nrun: the two Windows lines are the GitHub Actions runner and a local machine.\n\nNormative texts are checked out with LF endings, enforced by `.gitattributes`.\nA couple of Windows symlink tests are skipped: they need a local Windows\nprivilege. Windows junctions are genuinely tested.\n\n## Level of proof\n\nThe validator confirms one thing only:\n\n```text\nSTRUCTURALLY_VALIDATED\n```\n\nIt does not verify the real target. `TARGET_VERIFIED` stays forbidden in V1.\n\n## Security\n\nThe loader refuses reparse points. Reads are bounded and confined. Output is\nsorted and deterministic.\n\nOne design decision deserves your attention: `detect` and `plan` take a\n`target` path that is **not** confined to the configured roots, because the\npoint is to profile an arbitrary project. Run this server under an account\nwhose reach you accept, and connect it only to a trusted client. The full\nthreat model is in [SECURITY.md](SECURITY.md).\n\n## Non-guarantees\n\n- no universal semantic relevance\n- no external skill approved automatically\n- no audit of script contents\n- no genuinely mounted target proof\n- no total Windows atomicity\n- no universal HTML recognition\n- no universal secret detection\n- no guaranteed legal compliance\n- no marketplace, no remote source\n\n## Licence\n\nApache-2.0. See `LICENSE` and `NOTICE`.\n",
  "bytes": 11940,
  "sha": "c57b4dbfb5a5ae882526721ea339c17607baf9ddf6ddbb5d642b842a6446e8f4",
  "repo_slug": "cherridsaid/phases-agents",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cherridsaid_phases_agents_033a3082/readme"
}