🤝 Keiyaku

Keiyaku is an MCP server designed for the Architect-Minion workflow. It enforces a strict, review-driven protocol for iterative coding tasks.

Instead of messy, unstructured chat, Keiyaku turns every task into a formal "Keiyaku": a branch-based, multi-round journey with a clear beginning, a traced middle, and a definitive end.

🚀 Why Keiyaku?

• Zero Mess: Every task lives in its own keiyaku/* branch. Your main branch stays pristine.
• Traceable Logic: Every iteration is documented in KEIYAKU_TRACE.md. You can literally see the AI's "learning curve" (or mistakes).
• Strict Guardrails: No "Done" until you say so. No merging until the criteria are met.
• Human-in-the-Loop: Designed for humans who actually want to review the code before it hits production.

🔄 The Lifecycle

The workflow is a simple, non-negotiable loop:

1. Start: Initiate the keiyaku. Creates a branch, locks the mission in KEIYAKU.md, and starts Round 1.
2. Iterate (N times): Review the work, give feedback, and launch the next round.
3. Verdict: The final verdict. DONE (merge & clean) or DROP (nuke the branch).

Note: Tool names are preset-dependent. The defaults are shown in the next section.

🛠 Available Tools

| Tool | Action | Description | | :--- | :--- | :--- | | summon | Start | Define the goal, constraints, and criteria. Starts the first round. | | drive | Iterate | Provide feedback based on the previous round's output. | | ask | Reason | Pure read-only analysis session. No code changes, just brain power. | | present | Finish | Finalize the task. Requires a quality check (the "Oath"). | | help | Help | Show the current rules + preset usage guide. |

🎨 Flavor Your Workflow

Bored with generic tool names? Keiyaku supports Term Presets.

How to set

Set KEIYAKU_TERM_PRESET in the MCP server env (recommended), or in your shell before launching the server.

• Valid values: default, pocket, mischief (case-insensitive). If omitted, defaults to default.

• default: summon → drive → present (Professional)

• pocket: choose_you → command → capture (Gotta code 'em all)

• mischief: oi → neh → yoshi (For those who like a little attitude)

ask is also renamed by preset (ask / pokedex / eeto). help stays help across presets.

What it changes (and what it doesn't)

• Changes: tool names/titles/descriptions, the "identity" label, and the set of allowed profile display names (see next section).
• Doesn't change: core behavior (branching, protocol files, verdict rules).

Choose a profile name

Each run/round can pick a profile via tool input name, or globally via KEIYAKU_SUBAGENT_NAME_OVERRIDE.

• default: B-tier, A-tier, S-tier (also accepts internal names agent-a|agent-b|agent-c)
• pocket: grub, sparky, titan
• mischief: imp, minion, mastermind

📦 Setup

1. Install

npm install -g keiyaku

2. Configure MCP (Example: Claude Desktop)

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "keiyaku": {
      "command": "npx",
      "args": ["-y", "keiyaku"],
      "env": {
        "KEIYAKU_TERM_PRESET": "mischief" 
      }
    }
  }
}

📜 Protocol Files

When a keiyaku is active, two files are maintained in your repo:

• KEIYAKU.md: The immutable "Constitution" of the task.
• KEIYAKU_TRACE.md: The history of every round, feedback, and result.

Project-level law lives in:

• .keiyaku/base-constraints.md: Global constraints inherited by every keiyaku.
• ask also injects .keiyaku/base-constraints.md as reference context (it may be unrelated to some asks).

Note: These files are automatically cleaned up (or committed) when you present (or preset equivalent) the keiyaku.

"Keep your branches clean and your minions in line." — Mischief preset