AITP Research Protocol v2

AITP (AI-assisted Theoretical Physics) is a stage-machine protocol implemented as an MCP server. Any MCP-compatible agent — Claude Code, Kimi Code, Copilot, or a custom wrapper — can drive theoretical-physics research through it.

The protocol enforces:

• Layered evidence boundaries — exploratory notes never become trusted results without explicit validation
• Stage gates — the agent cannot skip stages or fabricate confidence
• Human-approval promotion — nothing enters long-term trusted memory without your say-so
• Cross-session durability — topics survive session resets; resume days later with full context

1. You describe what you want to study, in plain language.
2. AITP boots a topic with a bounded question, scope, and validation plan.
3. The agent works through stages — reading sources, sketching derivations, analyzing — inside the protocol's gate model.
4. When results look promising, AITP runs validation checks before asking for your review.
5. Only after your approval does material enter reusable memory.

L1 (read/frame) -> L3 (ideation -> planning -> analysis -> integration -> distillation) -> L4 (validate) -> L2 (trusted) -> L5 (write)

aitp-v2-refactor/
  brain/
    mcp_server.py       # FastMCP server — ~25 tools, all prefixed mcp__aitp__aitp_*
    state_model.py      # Stage evaluation, gate logic, artifact templates
    PROTOCOL.md         # Agent-facing operating manual (single source of truth)
  skills/
    skill-read.md       # Per-stage skill files loaded by the agent
    skill-frame.md
    skill-l3-*.md       # 5 L3 subplane skills
    skill-validate.md
    skill-promote.md
    skill-write.md
  scripts/
    create_topics_from_scattered.py   # Migrate existing research into AITP topics
    migrate_v0_to_v2.py              # Migrate from v0 kernel format
  hooks/                              # Claude Code hook examples
  tests/                              # Test suite

The MCP server exposes tools like:

• aitp_bootstrap_topic — create a new research topic
• aitp_get_execution_brief — check current stage, gate status, and what to do next
• aitp_list_topics — list all topics with metadata
• aitp_advance_to_l3 / aitp_advance_l3_subplane — stage transitions
• aitp_register_source / aitp_ingest_knowledge — source management
• aitp_submit_candidate / aitp_create_validation_contract / aitp_submit_l4_review — validation flow
• aitp_request_promotion / aitp_promote_candidate — human-gated L2 promotion
• aitp_advance_to_l5 — writing pipeline (flow notebook generated by agent during L3 distillation)

• Python 3.10+
• An MCP-compatible AI agent (Claude Code, Kimi Code, etc.)

1. Clone this repo:

git clone https://github.com/bhjia-phys/AITP-Research-Protocol.git
cd AITP-Research-Protocol

2. Install dependencies:

pip install fastmcp pyyaml

3. Configure your agent's MCP settings to launch the server:

{
  "mcpServers": {
    "aitp": {
      "command": "python",
      "args": ["D:/path/to/AITP-Research-Protocol/brain/mcp_server.py"]
    }
  }
}

4. Point topics_root to where you want research topics stored. The default used in tools is your project's research/aitp-topics/ directory.

Add to settings.json under hooks:

• UserPromptSubmit hook for keyword-based AITP routing
• PreToolUse hook for write-guard on topic files
• SessionStart hook for skill injection

See hooks/ for ready-made Python hooks.

Kimi Code supports MCP servers natively. Add the same MCP config to Kimi's settings. The protocol works identically — all routing is done through MCP tool calls.

The protocol is agent-agnostic. Any client that can:

1. Connect to an MCP stdio server
2. Call tools with JSON parameters
3. Read tool responses

...can drive AITP research end-to-end.

research/aitp-topics/<topic-slug>/
  state.md                   # YAML frontmatter: stage, posture, lane, subplane
  L0/sources/                # Registered source metadata
  L1/                        # source_basis, question_contract, conventions, anchors, contradictions
  L3/
    ideation/active_idea.md
    planning/active_plan.md
    analysis/active_analysis.md
    result_integration/active_integration.md
    distillation/active_distillation.md
    candidates/              # Submitted distilled claims
    tex/flow_notebook.tex    # Derivation trail
  L4/
    validation_contract.md
    reviews/
  L5_writing/
    outline.md, provenance/, draft/
  runtime/                   # Execution state

• Evidence before confidence — sources stay separate from speculation
• Bounded steps, not freestyle — every work unit has a clear question and scope
• Humans own trust — nothing becomes reusable memory without explicit approval
• Durable by default — research state survives session resets
• Agent-agnostic — any MCP client can drive the protocol

MIT License — see LICENSE file for details.

• brain/PROTOCOL.md — full agent-facing operating manual
• brain/mcp_server.py — MCP tool implementations
• brain/state_model.py — gate logic and stage evaluation