phases-agents

English · Français

스킬을 결정론적으로 발견, 검증, 선택하는 로컬 MCP 서버입니다. Python 표준 라이브러리만 사용하며, 런타임 의존성이 없습니다.

서버 하나. 도구 다섯 개. 당신 모르는 사이에 실행되는 것은 없습니다.

배경

AI 에이전트는 즉흥적으로 행동합니다. 같은 질문을 두 번 하면 서로 다른 두 계획을 받게 됩니다. 브레인스토밍에는 괜찮지만, 감사 및 규정 준수 작업에는 용납할 수 없습니다.

phases-agents는 즉흥성을 제거합니다. 로컬 프로젝트를 프로파일링하고, 엄격한 계약에 따라 스킬 카탈로그를 검증하며, 재생 가능한 계획을 반환합니다. 같은 대상, 같은 카탈로그, 같은 매개변수, 같은 결정.

원리

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

서버는 선택하고 노출할 뿐입니다. 호출하는 모델은 선택된 스킬을 읽고 자신의 도구를 사용해 어떻게 처리할지 결정합니다. 서버는 스킬을 절대 실행하지 않습니다.

아키텍처

표준 계약은 core/SKILLS_CONTRACT.md(프랑스어)에 있습니다.

빠른 시작

examles/skills/에 예제 패키지가 포합되어 있습니다. 세 단계를 거치면 실제 계획이 생성됩니다.

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를 한 줄씩 읽습니다. 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"]}}}

두 가지 계획 포맷이 공존합니다. "B3"는 서버 버전이 아니라 버전이 지정된 포맷을 가리킵니다. 공식 스키마는 core/PLAN_B3_SCHEMA.json입니다. 새 작업에는 이 포맷을 사용하세요.

plan_version이 없으면 레거시 포맷이 단순한 단계 목록을 반환합니다. 기존 호출자가 깨지지 않도록 유지되며, 제거 전에 폐기 예정(deprecated)입니다.

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는 자체 구성 파일에서 동일한 command/arguments 쌍을 사용합니다. 토큰이나 환경 변수가 필요하지 않습니다.

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 응답은 항상 1MiB 미만으로 유지됩니다.

첫 번째 호출은 검증된 레지스트리를 구축합니다. 웜 호출은 내용을 다시 읽지 않고 메타데이터를 검증합니다. refresh_skills는 재구축을 강제합니다.

스킬 패키지 작성

각 패키지는 루트의 직접적인 하위 항목이며 최소한 다음을 포함합니다:

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

가장 빠른 시작 방법은 examples/skills/hello-python/을 복사하고 식별자를 바꾸는 것입니다.

SKILL.md 프론트매터

다섯 개의 키가 허용됩니다. 모두 선택 사항이며, 존재하면 모두 검사됩니다.

열네 개의 필수 섹션

각 섹션은 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.

제공되는 기능은 개방형 용어집입니다. 각 카탈로그가 가져오는 것을 명명하며, 형태만 강제됩니다(^[az][az0-9_]{0,63}$). 클라이언트 기능만 폐형입니다. 이는 도메인이 아인 프로토콜을 설명하기 때문입니다.

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되므로, 호모글리프가 두 번재 정체성을 몰래 들여올 수 없습니다. 충돌이 생기면 전제 빌드가 차단되며, 어떤 패키지도 임의로 선택되지 않습니다.

선택

레지스트리의 모든 유효한 스킬은 이유와 함께 정확히 하나의 카테고리에 속합니다. 어떤 것도 조용히 버려지지 않습니다.

유일하게 입증된 자동 신호는 다은과 같습니다:

project_types ∩ profile.types

플랫폼, 도메인 및 기능은 호출자가 해당 제약 조건을 제공할 때만 필터링합니다. 금지된 기능은 스킬을 거부합니다. 의미론적 점수는 임의로 만들어지지 않으며, 계획은 식별자 기준으로 정렬됩니다.

빈 계획은 명시적으로 유효합니다: NO_COMPATIBLE_SKILL을 포함합니다.

B3 계획은 설치된 모든 스킬을 skills_selected, skills_not_applicable, skills_blocked로 분류합니다; 각 스킬은 정확히 한 번 나타납니다. 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 심볼릭 링크 테스트 몇 개는 건너니다. 로컬 Windows 권한이 필요하기 때문입니다. Windows junction은 실제로 테스트됩니다.

증명 수준

검증기는 단 한 가지만 확인합니다:

STRUCTURALLY_VALIDATED

실제 대상을 검증하지 않습니다. TARGET_VERIFIED는 V1에서 계속 금지됩니다.

보안

로더는 reparse point를 거부합니다. 읽기는 제한되고 격리됩니다. 출릭은 정렬되고 결정적입니다.

주의를 기울여야 할 설계 결정 하나가 있습니다: detect와 plan은 구성된 트에 제한되지 않은 target 경로를 받습니다. 임의의 프로젝트를 프로파일링하는 것이 목적이기 때문입니다. 이 서버를 허용 가능한 범위의 계정으로 실해하고, 신할 수 있는 클라이언트에만 연결하십시오. 전제 위협 모델은 SECURITY.md에 있습니다.

보장되지 않는 사항

• 보편적인 의미론적 관련성 없음

• 외부 스킬이 자동으로 승인되지 않음

• 스크립트 내용 감사 없음

• 실제로 마운트된 대상 증명 없음

• 완전한 Windows 원자성 없음

• 보편적인 HTML 인식 없음

• 보편적인 비밀 감지 없음

• 보장된 법적 준수 없음

• 마켓플레이스 없음, 원격 소스 없음

라이선스

Apache-2.0. LICENSE 및 NOTICE를 참조하십시오.