claude-overseer

claude-overseer

⚠️ Active development — pre-1.0. Schemas, hook semantics, and slash-command shapes may change without deprecation notice. Pin to a specific commit SHA in your marketplace add (/plugin marketplace add 3dotline/claude-overseer@<sha>) if you need stability. Issues and feedback welcome.

A Claude Code plugin that ships a protocol-disciplined agent orchestration system: two session-role modes (/overseer and /thearchitect), five dispatchable workers (implementer, platform, debugger, reviewer, scribe), wire-format contracts (TaskSpec / WorkerReport / ReviewVerdict), and a path-enforcement hook that prevents agents from writing outside their lane.

Drop into any project with two commands. Generic — no stack assumptions; works for Node, Python, Go, Rust, monorepos, and anything else Claude Code can touch.

What you get

• /overseer — promotes the main session to a pure orchestrator. Decomposes user requests into TaskSpecs, dispatches workers (in worktrees when parallel), pauses for a user gate, optionally dispatches reviewer, runs Context Sync.
• /thearchitect — promotes the main session to the agent-creator role. Owns .claude/**, docs/contracts/**, docs/superpowers/specs/**. Writes specs first for non-trivial system changes; smoke-tests every hook change.
• /setup — bootstraps the plugin into a new project (copies role manuals, durable rules, contracts, GUIDE; prints the permission snippet you need to paste).
• 5 dispatchable subagents: implementer (product code, TDD where testable), platform (deps / framework / CI / containers), debugger (read-only investigator), reviewer (verifies every WorkerReport), scribe (root CLAUDE.md reconciliation).
• 2 hooks: restrict-agent-paths.sh (per-agent path allowlists, hard-enforced via PreToolUse) and load-rules.sh (injects durable rules at SessionStart, prefers project override over plugin default).

Install

Add the plugin marketplace from this repo (the repo must already exist on GitHub and contain .claude-plugin/marketplace.json):

/plugin marketplace add 3dotline/claude-overseer
/plugin install claude-overseer@claude-overseer

For local development before pushing to GitHub, use an absolute path:

/plugin marketplace add /absolute/path/to/claude-overseer
/plugin install claude-overseer@claude-overseer

Bootstrap your project:

/setup

Paste the permission snippet /setup prints into .claude/settings.local.json → permissions.allow (the plugin cannot auto-grant permissions — Claude Code requires user consent for shell command patterns).

Restart Claude Code. The /overseer and /thearchitect commands are now live.

Why a plugin instead of a template repo?

Plugins are first-class in Claude Code: hooks register automatically via hooks/hooks.json, slash commands appear in the picker, and updates ship via /plugin update. You get one-command install, namespaced commands, and no settings.json wrangling for hook entries.

Files the plugin model does NOT cover (session-role markdowns, durable rules, wire-format contracts) are bootstrapped into the consumer project by /setup. Once copied they're project-owned — edit them freely; the plugin won't overwrite.

What's in the box

.claude-plugin/plugin.json           # manifest
agents/                              # 5 dispatchable subagents
  debugger.md  implementer.md  platform.md  reviewer.md  scribe.md
commands/                            # slash commands
  overseer.md  overseer-off.md
  thearchitect.md  thearchitect-off.md
  setup.md
hooks/
  hooks.json                         # PreToolUse + SessionStart registration
  load-rules.sh                      # SessionStart: inject rules.md as context
  restrict-agent-paths.sh            # PreToolUse: per-agent path enforcement
scripts/
  setup.sh                           # invoked by /setup
assets/                              # copied to consumer project by /setup
  roles/  rules.md  GUIDE.md  contracts/

Hook smoke tests

Run from the plugin repo root before publishing: