Sheldon

Multi-agent missions for Claude Code

A Claude Code plugin that runs missions — a multi-agent workflow where an Orchestrator drafts a validation contract, a Worker implements it on a dedicated branch, and a Validator adversarially verifies the result. Ship features atomically, with proof.

Get started

How it works

Orchestrator (opus)

Plans the feature, writes the validation contract, and drives the mission loop.

Worker (sonnet)

Implements the feature on a dedicated mission/<id> branch.

Validator (haiku)

Adversarially verifies the implementation against the contract.

Built for serious work

Missions

Every feature ships as a mission: Orchestrator drafts the contract, Worker implements on a dedicated mission/<id> branch, Validator adversarially verifies. Branch-per-mission isolation keeps main clean.

Validation contracts

Every change is gated by a contract of executable assertions. The Validator runs each check command and fails the mission if any assertion does not pass — no merge without proof.

The brain

A persistent learning layer accumulates conventions, lessons, and capability proposals per project. The Orchestrator consults the brain before drafting contracts so the same mistake never ships twice.

Lifecycle hooks

PreToolUse and PostToolUse hooks enforce contract immutability, scope discipline, and pre-merge scope-creep advisories. The system is self-policing by design.

/sheldon: slash commands

Drive the entire workflow from the Claude Code chat: /sheldon:mission-new, /sheldon:mission-approve, /sheldon:mission-retro, and more — no context-switching required.

Epics

Decompose a vague brief into 3–7 candidate sub-missions. The Epic Planner researches the codebase in parallel and writes .epics/<id>/epic.md for review. Promote any subset into real missions with /sheldon:epic-promote.

Slash commands at a glance

Mission lifecycle

/sheldon:mission-new <goal> — draft a contract and start a mission
/sheldon:mission-approve [id] — approve contract and dispatch Worker
/sheldon:mission-status [id] — show current phase and assertion results
/sheldon:mission-list [--phase=<phase>] — list missions with optional filter
/sheldon:mission-abort <id> [reason] — abort an in-flight mission
/sheldon:mission-retro <id> — retrospective summary of a completed mission

Epics

/sheldon:epic-new <brief> — decompose a brief into candidate sub-missions
/sheldon:epic-list — list all epics and their status
/sheldon:epic-promote <epic_id> <issue_id> — promote an epic item into a real mission

Brain

/sheldon:brain-recall [topic] — surface relevant lessons from the brain
/sheldon:brain-learn <id> — extract and store lessons from a completed mission
/sheldon:brain-list — list all stored brain entries
/sheldon:brain-dedup [--threshold] [--type] — deduplicate overlapping brain entries

Tooling

/sheldon:contract-lint <path> — validate a contract file for syntax errors
/sheldon:missions-report — generate a status report across all missions
/sheldon:missions-gc [--days <N>] [--apply] — garbage-collect stale mission branches

From prompt to merge

$ /sheldon:mission-new "add dark mode toggle"
Orchestrator: drafted contract with 5 assertions. Run /sheldon:mission-approve <id>.

$ /sheldon:mission-approve 01K...
Worker → implementing on mission/01K...
Validator → 5/5 assertions passed.
Orchestrator → merged mission/01K... into main.

$ /sheldon:mission-retro 01K...
Mission 01K... (done): added dark mode toggle.
Built across 4 commits, 11.3m end-to-end, validator passed on first try.
Clean happy-path merge.

Install

Recommended: install via the Claude Code plugin marketplace

claude plugin marketplace add sebiko3/sheldon
claude plugin install sheldon

That's it — Sheldon is available in every Claude Code session, no --plugin-dir needed. Update later with claude plugin update sheldon.

For development (working on Sheldon itself)

git clone https://github.com/sebiko3/sheldon $SHELDON_DIR
cd $SHELDON_DIR
npm install
claude --plugin-dir "$(pwd)"

Verify your setup at any time: bin/sheldon doctor