gatekeeper

Gatekeeper

Beta — Gatekeeper is under active development. Expect breaking changes.

A Claude Code plugin for spec-driven development with cryptographic verifier loops, TDD-first execution, and concurrent opencode agents.

How It Works

Gatekeeper orchestrates software projects through a structured pipeline where no task can be marked complete without passing independent verification:

1. Plan (/quest) -- Deep discovery + plan.yaml with phases, tasks, must_haves, TDD test specs, and per-task prompt files
2. Assess Phase -- Phase assessor creates format contracts (API shapes, data structures, wiring) so independently-written tests produce compatible interfaces
3. Test -- Tester agent researches the domain (WebSearch + Context7), writes comprehensive tests following format contracts, passes assessor quality gate (TQG token)
4. Execute (/cross-team) -- TDD-first implementation with parallel opencode agents, wave-based dispatch, and session continuations
5. Verify -- Independent verifier in a fresh context checks tests, inspects code, and runs Playwright visual verification. A 128-bit cryptographic Gatekeeper token is issued only on full pass
6. Verify Phase -- Phase verifier checks integration contracts, cross-phase wiring, and end-to-end data flows. PVG token gates the next phase
7. Iterate -- Failed verifications loop back through execution with evolutionary intelligence informing retry strategies

Prerequisites

Dependency	Minimum Version	Purpose
Node.js	>= 18.0.0	MCP servers, hook scripts, installer
npm	(bundled with Node)	Package management
Python 3	>= 3.8	Plan utilities, evolution engine, validation
git	any recent	Cloning, submodules
jq	any recent	JSON parsing in hook scripts
Claude Code	latest	The CLI tool that runs the plugin
OpenCode	latest	Agent dispatch for gk-builder agents
ANTHROPIC_API_KEY	--	Auto-detected from subscription or set manually (see below)

Authentication

Assessor and verifier agents are spawned as Claude Code Task subagents. Authentication is resolved automatically:

1. ANTHROPIC_API_KEY env var -- if set, used directly
2. OAuth token from ~/.claude/.credentials.json -- if you're logged in to Claude Code with a subscription (Pro/Max), the OAuth access token is read and used automatically

Most users don't need to do anything -- just be logged in to Claude Code. If auto-detection fails:

export ANTHROPIC_API_KEY=sk-ant-...  # https://console.anthropic.com/settings/keys

Check prerequisites

node --version    # >= 18.0.0
python3 --version # >= 3.8
git --version
jq --version
claude --version  # Claude Code CLI
opencode version  # OpenCode CLI
echo $ANTHROPIC_API_KEY  # Optional if logged in via subscription

Installation

Quick Install (automated)

git clone --recurse-submodules https://github.com/RhizomaticRobin/gatekeeper.git
cd gatekeeper
bash scripts/bootstrap.sh

The bootstrap script checks prerequisites, builds the MCP servers, installs the plugin to Claude Code, and verifies the installation.

Manual Install (step by step)

1. Install Claude Code

If Claude Code is not installed:

# Via npm (recommended)
npm install -g @anthropic-ai/claude-code

# Verify
claude --version

See Claude Code docs for alternative installation methods.

2. Install OpenCode

If OpenCode is not installed:

# Via the official installer
curl -fsSL https://opencode.ai/install | bash

# Verify
opencode version

OpenCode installs to ~/.opencode/bin/. Make sure it's on your PATH.

3. Clone the repository

git clone --recurse-submodules https://github.com/RhizomaticRobin/gatekeeper.git
cd gatekeeper

If you already cloned without --recurse-submodules:

git submodule update --init --recursive

4. Build the OpenCode MCP server

cd Better-OpenCodeMCP
npm install --production=false
npm run build
cd ..

Verify: ls Better-OpenCodeMCP/dist/index.js should exist.

5. Install the Evolve MCP server dependencies

pip install fastmcp

6. Build hook scripts

npm install
npm run build:hooks

Verify: ls hooks/dist/intel-index.js should exist.

7. Install the plugin into Claude Code

Option A: Via the plugin system (recommended)

# From inside Claude Code
/plugin marketplace add /path/to/gatekeeper
/plugin install gatekeeper

Or via the CLI:

claude plugin marketplace add /path/to/gatekeeper
claude plugin install gatekeeper --scope user

Use --scope project for a single project, or --scope local for project-local (gitignored).

Option B: Via the legacy npx installer

# From the gatekeeper directory
node bin/install.js --global