mas-compiler

name	mas-compiler
description	Compile a Multi-Agent System (MAS) into a Single-Agent System (SAS) by faithful pipeline compression. Implements the 3-phase compilation from arXiv 2601.04748. Takes a MAS codebase or description as input; produces a compiled SKILL.md with sequential [PHASE] sections and a tools/ directory. Invoke with /mas-compiler.

MAS Compiler

Implements the MAS→SAS compilation from arXiv 2601.04748 ("When Single-Agent with Skills Replace Multi-Agent Systems and When They Fail").

Input: a MAS codebase, paper, or description. Output: a compiled skill directory with SKILL.md + tools/.

See references/compilation_theory.md for the formal definitions (ℳ, 𝒮, Φ, C1–C3). See references/output_format.md for the exact output template.

---

Step 1 — Check Compilability (C1, C2, C3)

Before compiling, verify all three conditions hold. Report violations clearly.

C1 — Serializable communication: The communication graph 𝒢 admits a topological ordering. Fails if there are cycles (debate loops, circular routing, adversarial negotiation).

C2 — Shared history: Every agent's output depends only on the shared conversation history h; no agent maintains private state or hidden objectives.

C3 — Homogeneous backbone: All agents run on the same underlying model.

If a condition fails, state which condition and why. Ask whether to proceed with an approximation (e.g., serialize a near-cyclic step) before continuing.

---

Step 2 — Extract the Communication Graph

Read the MAS source and record:

For each agent aᵢ:

• name: identifier used in the codebase
• role ρᵢ: what this agent does (from its system prompt or role description)
• policy ϕᵢ: the behavioral instructions governing how it operates
• tools: any external libraries, APIs, or computation the agent calls

For the communication graph 𝒢:

• List all directed edges (aᵢ → aⱼ) — data flows from aᵢ to aⱼ
• List N_out(aᵢ) = {aⱼ | (aᵢ, aⱼ) ∈ E} for each agent
• Produce a topological ordering of agents

For each edge (aᵢ → aⱼ), record the output contract: what format does aᵢ produce, and what does aⱼ expect to receive?

---

Step 3 — Phase 1: Capability Decomposition

Apply Kᵢ = f_decomp(ρᵢ) to each agent.

For each agent aᵢ, extract its atomic capabilities κ — discrete, independently executable functions derived from its role description ρᵢ. One agent may yield 1–3 capabilities. Name each κ as a verb phrase (e.g., "decompose question", "explore schema", "generate SQL").

Produce a table: agent → [κ₁, κ₂, ...] for all agents.

---

Step 4 — Phase 2: Backend Assignment

Apply ξ = f_backend(κ) to each capability.

Condition	Backend	Action
κ requires external computation, data access, or a deterministic algorithm	External: ξ = t ∈ 𝒯	Write a tool in tools/
κ is purely cognitive (reasoning, generation, analysis)	Internal: ξ = ∅	Embed as policy text

For each externalized capability, write a tool file in tools/:

• One function per capability; inputs are JSON-serializable; return a flat dict
• No LLM calls inside tools
• All imports at top of file
• Wrap body in try/except Exception as e: return {"error": str(e)}

After each tool file, run:

python -c "import sys; sys.path.insert(0, '<SKILL_DIR>'); from tools.<module> import <fn>; print('OK')"

---

Step 5 — Phase 3: Topology Internalization

Apply πκ^final = f_inject(πκ^base, N_out(aᵢ)) to each capability.

For each capability κ from agent aᵢ with downstream set N_out(aᵢ):

πκ^final = πκ^base ⊕ ⋃_{aⱼ ∈ N_out(aᵢ)} Handover(aᵢ → aⱼ)

⊕ is string concatenation. The Handover block appended to each section's policy specifies:

• Required output fields: what the downstream phase needs
• Output format: structure (e.g., list of tuples, dict with keys X and Y)
• Completion signal: how the agent knows this phase is done

This replaces explicit inter-agent message passing with implicit output format constraints embedded in each section's policy.

---

Step 6 — Write the Compiled SKILL.md

Follow the template in references/output_format.md.

Each capability κ becomes one [PHASE_NAME] section. Sections are ordered by the topological sort of 𝒢. The compiled agent is instructed to execute phases in this order.

Each section contains:

• A [PHASE_NAME] header
• Role: 1–2 sentences from ρᵢ
• Execute: the finalized policy πκ^final (base policy + handover instruction)
• Tools (if ξ ≠ ∅): tool name, file location, one-line description
• Handover → NEXT_PHASE: the required output fields (omit on the final phase)

---

Step 7 — Validate

Check the compiled output:

1. One [PHASE] section per capability (matches the capability table from Step 3)
2. One tool file per externalized capability (from Step 4)
3. Every non-final section has a Handover block (from Step 5)
4. Sections are in topological order (matches 𝒢 from Step 2)

Report what was compiled. Note any approximations made (e.g., a near-cyclic step that was serialized, a partially private agent that was treated as shared-history).