Protocols

protocols-plugin

Agent behavioral protocols for Claude Code, Codex CLI, and Gemini CLI, with mechanical tool restriction enforcement via ward where supported.

What This Does

Provides 13 behavioral protocol skills that define operational modes for Claude Code, Codex CLI, and Gemini CLI agents. Each protocol constrains agent behavior — what tools are available, what workflow to follow, what the agent's role is.

Protocols that restrict tools (foreman, adversary, researcher) include ward gate rules that mechanically enforce those restrictions at the PreToolUse hook level, preventing accidental violations.

Codex and Gemini do not use Claude's plugin marketplace, so this repository also ships a script-based installer that links the protocol skill directories into their user skill roots.

Protocols

Protocol	Description
foreman	Coordination only — dispatch subagents, do not execute code
subagent	How to write and launch subagent prompts (auto-invocable)
gauntlet	Scout -> Coder -> Analyst -> Verifier pipeline for high-risk changes
investigation	Structured debugging with competing hypotheses and escalation levels
experiment	Controlled benchmark experiments with baseline, gates, records, and promote/abandon decisions
phases	Parallel/sequential workflow phases with filesystem-based coordination
iterations	Tracked iteration cycles for reducing failures with regression detection
cleanup-refactor	Deletion-first fixed-point cleanup for refactors, migrations, helper removal, and ownership repair
adversary	Read-only design review against project principles
researcher	Pre-implementation research with web access
external-agents	Using Codex/Gemini CLIs as external reviewers
spec-updating	Spec update workflow with discovery, draft, and review gates
RE	Reverse engineering — documentation is the work product

Ward Integration

Protocols that restrict tools use ward for mechanical enforcement:

1. SessionStart hook automatically registers this plugin's ward-rules/ directory via WARD_RULES_PATH
2. When a protocol is activated (e.g., ward set foreman), ward's session.phase is set
3. Ward gate rules fire on every tool call, denying tools that the protocol forbids

Gate Rules

Rule	Phase	Denies
foreman-gate.yaml	foreman	Bash, Edit, Write (except prompts/ and notes-*)
adversary-gate.yaml	adversary	Edit, Write, Bash
researcher-gate.yaml	researcher	Edit (Write allowed for reports)

Installation

Claude plugin install

claude plugin marketplace add ctoth/protocols-plugin
claude plugin install protocols@protocols-marketplace

Script-based installer for Codex and Gemini

Use the bundled installer when you want the protocol skills installed into Codex and/or Gemini user skill directories:

uv run scripts/install_skills.py doctor
uv run scripts/install_skills.py install --platform codex --platform gemini

What the installer does:

• discovers every plugins/*/skills/*/SKILL.md directory;
• installs Codex skills into both ~/.agents/skills and ~/.codex/skills/protocols-plugin;
• installs Gemini skills into ~/.gemini/skills;
• uses symlinks when possible and managed copies when symlinks are unavailable;
• refuses to overwrite unmanaged destinations unless --force is supplied.

Common commands:

uv run scripts/install_skills.py install
uv run scripts/install_skills.py install --platform codex
uv run scripts/install_skills.py install --platform gemini
uv run scripts/install_skills.py install --platform claude
uv run scripts/install_skills.py uninstall

install --platform claude uses Claude's native claude plugin marketplace add/install flow under the hood. Omitting --platform installs all supported targets.

Requirements

• ward must be installed and configured as a PreToolUse hook
• Ward must support WARD_RULES_PATH for loading rules from plugin directories
• uv is required for the script-based installer

Usage

Activate a protocol by invoking it as a skill:

/protocols:foreman      # Enter foreman coordination mode
/protocols:gauntlet     # Start a scout->coder->analyst->verifier pipeline
/protocols:investigation # Begin structured debugging
/protocols:experiment   # Run a controlled benchmark experiment
/protocols:cleanup-refactor # Run deletion-first fixed-point cleanup
/protocols:adversary    # Run read-only principle alignment check
/protocols:researcher   # Enter research mode with web access

The subagent protocol is auto-invocable — it provides background knowledge whenever you dispatch agents.

Protocols that restrict tools will instruct you to run ward set <protocol> to activate mechanical enforcement.

License

MIT