checkmate

Mate in the fewest moves.

Goal-driven mode for AI coding agents. Reach the user's win condition in the fewest steps and lowest token count.

What is checkmate?

checkmate gives AI coding agents a relentless, goal-driven personality. Instead of generating conversational filler, presenting menus of hypothetical options, or introducing speculative abstractions, checkmate guides the agent to:

1. Identify the win condition silently before taking action.
2. Take the shortest path that completely satisfies the goal.
3. Spend the fewest tokens—no preambles, recaps, or unrequested closing offers.
4. Verify the solution against actual requirements and tests before declaring done.

Before & After

Here is the difference checkmate makes on a typical coding task:

Prompt: "Add a function slugify(text) in src/utils.js that converts strings to URL-friendly slugs."

Without checkmate (Standard AI Agent)

Certainly! I would be delighted to help you implement a URL-friendly slug generator.

There are several standard ways we could design this function depending on your needs:
1. Basic Regex approach (fast, ASCII-only)
2. Unicode Normalization approach (handles accents and umlauts via NFKD)
3. External dependency approach (e.g. using @sindresorhus/slugify)
4. Comprehensive slug options configuration (custom delimiters, casing, trim)

I have gone ahead and created a flexible `SlugService` class in `src/slug-service.js` along with
a configuration interface in `src/slug-config.json` so you can customize delimiters and casing.
I also created a test suite in `tests/slug.test.js` and added docs in `docs/slugify.md`.

Here is the code... [150 lines of boilerplate, interfaces, and unused options]

Summary of changes:
- Created SlugService with 4 configurable options
- Exported helper utility in src/utils.js
- Added configuration defaults

Would you like me to write more tests, add Unicode transliteration tables, or integrate
this with your routing framework? Let me know how you would like to proceed!

Result: ~850 output tokens, 4 unrequested files, option menu paralysis, unverified assumptions.

With checkmate

// src/utils.js
export function slugify(text) {
  return String(text)
    .normalize('NFKD')
    .replace(/[\u0300-\u036f]/g, '')
    .toLowerCase()
    .trim()
    .replace(/[^a-z0-9]+/g, '-')
    .replace(/^-+|-+$/g, '');
}

node -e "import { slugify } from './src/utils.js'; console.assert(slugify('Hello World!') === 'hello-world');"

done

Result: ~120 output tokens, 1 target file modified, zero conversational fluff, verified against the goal.

Multi-Agent Installation

checkmate is designed as a single source of truth (rules/checkmate.md) with deterministic build generators for all major coding agent platforms.

1. Claude Code

From Marketplace

/plugin install checkmate --marketplace rover-001/checkmate

From Local Directory

# Add as a persistent plugin:
claude plugin add /path/to/checkmate

# Or load directly for a session:
claude --plugin-dir /path/to/checkmate

2. Cursor

Cursor rules are pre-built at dist/cursor/.cursor/rules/checkmate.mdc with alwaysApply: true.

# Copy into your repository rules:
mkdir -p .cursor/rules
cp dist/cursor/.cursor/rules/checkmate.mdc .cursor/rules/checkmate.mdc

3. OpenCode

OpenCode command templates and instructions are pre-built at dist/opencode/.

# Copy OpenCode commands and root instructions:
cp -r dist/opencode/.opencode .
cp dist/opencode/AGENTS.md .

4. Codex

Codex agent instructions and companion skills are pre-built at dist/codex/.

# Copy instructions to your workspace root:
cp dist/codex/AGENTS.md .

Trigger checkmate in Codex prompts with @checkmate or natural language ("checkmate mode").

Usage

When installed in Claude Code, checkmate activates automatically via the SessionStart hook.

Modes

Commands

• /checkmate — Activate checkmate with default mode (full).
• /checkmate lite — Switch to lite intensity.
• /checkmate full — Switch to full intensity.
• /checkmate ultra — Switch to ultra intensity.
• /checkmate off — Turn off checkmate for the session.

Natural Language Off Switch

You can also disable checkmate at any time in natural conversation by saying:

• "stop checkmate"
• "normal mode"

Configuration & Precedence

Checkmate determines its active mode using the following strict precedence hierarchy:

CHECKMATE_DEFAULT_MODE (environment variable)
  ↳ ~/.config/checkmate/state.json (session / CLI state)
      ↳ ~/.config/checkmate/config.json (user configuration)
          ↳ full (built-in default)

Configuration File Paths

Example config.json

{
  "defaultMode": "ultra"
}

Environment Variable Override

export CHECKMATE_DEFAULT_MODE=ultra

Sibling Skills

In addition to core goal-driven execution, checkmate includes three companion skills:

1. checkmate-review

Audits a diff, file, or prior agent response for detours, scope creep, and token waste.

• Trigger: /checkmate-review [file/diff] or "review for detours"
• Taxonomy: Emits structured findings (scope-creep, abstraction, option-menu, preamble, recap, premature-complexity, unverified).
• Verdict: Ends with verdict: clean or verdict: N findings. Read-only; edits nothing.

2. checkmate-help

Displays a quick reference card summarizing modes, commands, configuration paths, and precedence rules.

• Trigger: /checkmate-help or "checkmate help"
• Scope: One-shot informational display; does not alter state.

3. checkmate-gain

Displays the efficiency scoreboard comparing checkmate against the unassisted baseline.

• Trigger: /checkmate-gain or "checkmate gain"
• Output: Reports goal-pass rate, median output tokens, median total tokens, and step reductions directly from benchmark data. Read-only.

How It Works

A SKILL.md file alone does not reliably activate in modern AI agents. Independent benchmarks (such as JetBrains' study of agent behavior) revealed that agents rarely self-invoke skill definitions unprompted.

checkmate guarantees activation through a native SessionStart hook (hooks/checkmate-instructions.js):

1. Runs instantaneously (<5ms script logic) on session startup and resume.
2. Resolves the active mode across environment variables, state files, and user config.
3. If mode is off, outputs nothing and exits cleanly.
4. Otherwise, injects the core rules plus the selected mode delta directly into the agent's context.
5. All operations are local, zero-dependency, and safe against crashes (fails closed silently).

The 9 Rules

# checkmate

Goal-driven mode. Reach the user's win condition in the fewest moves.

1. GOAL. Before acting, identify the win condition: what must be true when this is done. Do this silently. State it only if ambiguous.
2. SHORTEST PATH. Choose the least complex solution that fully meets the goal. No extra features, abstractions, config, or options nobody asked for.
3. TOKENS. Answer first. No preamble, no restating the question, no recap, no closing offers. Stop when the goal is met.
4. DECIDE. Pick one approach. If a tradeoff matters, state it in one line. Never present a menu unless asked.
5. ASK RARELY. Ask only when blocked and no safe assumption exists. One question max. Otherwise state the assumption in one line and proceed.
6. FINISH. Partial work is not done. Continue until the goal is met or a real blocker exists. Do not stop to ask permission for obvious next steps.
7. VERIFY. Before declaring done, check the result against the goal (run it, test it, re-read the requirement), not against how it looks. When writing tests, verify actual behavioral logic and state transitions—never write superficial assertions that merely check prompt text, log strings, or mock return values.
8. EARN COMPLEXITY. Add complexity only when a concrete failure or stated requirement forces it. Say which.
9. CLOSE. Last line: done, not done: <why>, or blocked: <what's needed>.

Off switch: if the user says "stop checkmate" or "normal mode", stop applying these rules.

Overrides: safety, correctness, and explicit user requests (e.g. "explain in detail") always win over brevity.

Benchmark Results

checkmate is rigorously evaluated across a 40-task benchmark suite spanning 4 distinct categories:

• feature: Implementation tasks verified by hidden automated unit tests.
• bugfix: Real-world bug repros with failing tests that must be made green.
• refactor: Code refactoring under strict invariant preservation and structural constraints.
• qa: Precise technical queries with exact checkable answers.

Integrity & Measurement Principles

• Pass rate first, tokens second: An agent that fails quickly is not efficient; it is broken. Pass rate is the primary metric.
• Conditioned on success: Token, step, and wall-clock medians and IQRs are computed strictly among passed runs. Failures cannot "win" on brevity.
• Honest reporting: No unmeasured claims or fabricated percentages.

Benchmark summary generated at 2026-10-24T15:59:32.863Z using model claude-opus-5-5 (3 run(s)/task).

Shared Task Intersection (All Arms Passed)

Paired comparison across 21 task(s) where all evaluated arms passed 100% of runs (eliminating survivorship bias).

Relationship to ponytail

checkmate is inspired by ponytail (the "lazy senior dev" skill). Key differences:

Contributing

Contributions are welcome! Please ensure that all changes adhere to checkmate's design constraints:

1. Zero external runtime dependencies: Keep hooks and utilities lightweight and native.
2. Byte budget: Injected rules must remain under 2 KB.
3. Idempotent builds: npm run build must produce deterministic distributions across all agent platforms.
4. All tests pass: Run npm test (including behavior scenarios B1–B9 and stats verification).

git clone https://github.com/rover-001/checkmate.git
cd checkmate
npm test
npm run build

License

MIT © Parth Sharma