Claude Dev Team

A FAANG-style AI dev team plugin for Claude Code and opencode. Gives you seven specialized agents with persistent per-project memory, plus a full spec management workflow and project scaffolding — all wired together.

Install

Claude Code

/plugin marketplace add cold-dark-void/claude-dev-team
/plugin install dev-team

dev-team tracks the stable channel — a stable branch promoted from master after a soak period. Want changes the moment they ship instead? Install dev-team-edge (same plugin, tracks master directly) from the same marketplace.

opencode

git clone https://github.com/cold-dark-void/claude-dev-team.git
cd claude-dev-team
bash install.sh

The opencode install script symlinks commands/ and generates opencode-valid agent files (Claude Code's string tools: field is stripped — opencode rejects it) into your opencode config directory (~/.config/opencode/). Re-run bash install.sh after editing an agent. Skills are added via opencode.json skills.paths.

Use --dry-run to preview every change without writing anything (bash install.sh --dry-run, also supported by uninstall.sh). The script auto-detects opencode (binary on PATH or an existing config dir) and skips cleanly with a warning if neither is found. It also warns if your opencode agent tree is nearing the ~100-agent cap. Uninstall with bash uninstall.sh.

Documentation

Guide	What's in it
Documentation hub	Index of every command, runbook, and guide — start here
Setup & Configuration	Prerequisites, /setup, memory config, remote embeddings, troubleshooting
Onboarding runbook	"Just cloned the repo" → agents ready to take tickets
Telegram Intercom setup	Per-dev BotFather bot, pairing, Topics on/off, host poller
Memory runbook	How memory works, distillation, search, hygiene
Command reference	Per-command pages (usage, flags, examples)
CHANGELOG	Release history — start here to discover new features
Upgrading	Existing projects: what to re-run (usually nothing beyond plugin update)
Migrate to v1.0.0	0.x → 1.0.0 consumer checklist (doctor, schema, hooks, stubs)

What You Get

Agents

Agent	Model	Role
pm	Opus	Requirements, user stories, acceptance criteria, prioritization
tech-lead	Opus	Architecture, system design, cross-cutting concerns, unblocking ICs
ic5	Sonnet	Complex implementation — ambiguous problems, hard bugs, new systems
ic4	Sonnet	Well-defined tasks — extending patterns, tests, simple fixes
devops	Sonnet	Deployments, CI/CD, infrastructure, monitoring, incident response
qa	Sonnet	Test planning, validation, bug reports, release gating
ds	Opus	Data analysis, ML/AI pipelines, A/B testing, metrics, statistical modeling
advisor	Opus	Read-only adjudicator with per-agent memory — post-council appeal + BC-diagnosis claims, spawned only by the orchestrator (SPEC-039; opt-in --with-advisor[=<model>])

The first seven rows are the behavioral/team agents you route work to, and they are the ones with persistent per-project memory. Seven internal agents are never routed to directly. finder, debugger, project-init, distiller, council-judge, and council-scribe are invoked by specific commands (/council and /bug-hunt, /debug, /setup team, /memory distill, /council again for the judge and the scribe) and carry no memory, cortex, or directives — finder and debugger are read-only investigators; council-scribe is a tool-less internal council role. advisor (SPEC-039) is the orchestrator-only adjudicator with per-agent memory: post-council appeals and critical-claim checks during unsupervised runs, opt-in via --with-advisor[=<model>].

Memory

Each agent remembers what it learns about your project, so the team stops re-reading the codebase from scratch every session. Storage is SQLite with semantic search when available (after /setup team downloads the embedding extensions, ~29MB), and falls back transparently to per-agent markdown files when it isn't. Per-worktree task progress always lives in context.md.

Domain glossary (separate): optional committed CONTEXT.md (or docs/domain/CONTEXT.md) holds the project's ubiquitous language — preferred term names and aliases to avoid. /brainstorm and /kickoff load and update it; this is not agent memory and needs no extra tooling.

See the Memory runbook for storage layout, tiers, and distillation, and the Setup Guide for configuration and remote-embedding options.

Commands

The command index below is exhaustive (docs-drift cmd-index checked). Full per-command docs live in docs/commands/ when a page exists; skills-backed Surfaces without a page still appear here.

opencode: Commands are namespaced under /dev-team/ (e.g., /dev-team/handoff). Claude Code uses the bare name (e.g., /handoff).

Core

First-ticket lifecycle: install → health → plan → execute → review → ship.

Command	When to use
/setup	Onboard a project — project · orchestration · team · models
/doctor	Diagnose install/config health (PASS/WARN/FAIL); read-only default, --fix allowlist
/audit	Instruction-stack inventory + skill-size WARN; approve-then-apply
/kickoff	Parallel PM+TL planning → spec → implementation plan → task graph
/orchestrate	Full lifecycle: issue → worktree → agents → review → ship/PR
/debug	Phase-gated bug fix (patch/arch) or ticket pipeline (ticket)
/bug-hunt	Unknown-defect discovery — discover → refute → plan + proceed-gated materialize → phase handoff emit-only (stages 1–4)
/council	Adversarial tribunal — reality-check a claim, session slice, or diff

Advanced

Program / multi-ticket work, session tuning, and quality gates.

Command	When to use
/epic	Decompose an umbrella into sequenced children for /kickoff or /orchestrate
/backlog	Manage backlog items (Linear-first dual-write when MCP is up); sweep purges + walks the open set
/brainstorm	Socratic design refinement before planning (--grill for one-Q-at-a-time)
/craft-loop	Design reviewed loop programs for the host /loop//goal
/release-train	Multi-branch release queue — register, freeze, land via /release
/retro	Scan past sessions for friction; propose directive adjustments (runbook)
/handoff	STM packet / compact seed (State now → Through-line → appendix); cold print core + path, warm file-only

Optional host SAST: if semgrep (and/or CodeQL with an existing DB) is on PATH, /review-and-commit and the council security flavor run a fail-open scan first (skills/security-scan; SECURITY_SCAN=0 to skip). Not required to install.

Internal

Agent protocols (agent-memory, memory-store, memory-recall), council/orchestrate engines, gates (docs-drift, skill-lint, …), and tools/ helpers are not user-invoked Surfaces — they run under Core/Advanced commands or CI. Internal agents finder, debugger, project-init, distiller, council-judge, and council-scribe are reached only via /council and /bug-hunt, /debug ticket, /setup team, /memory distill, and /council again for the judge and the scribe; advisor (SPEC-039) is reached only through the orchestrator's ask.sh seam.

Migration (historical)

W1–W3 deprecation command stubs were deleted in v1.1.0. Use the live hubs only.

0.x → 1.0.0 consumer checklist: Migrating an existing project to v1.0.0. Full old→new table: CHANGELOG v1.0.0.

Old command	Use instead
/init-team · /init-orchestration · /scaffold-project	/setup team · /setup orchestration · /setup project
/focus · /blunt	/mode focus · /mode blunt
/metrics · /standup	/status metrics · /status standup
/fix-ticket	/debug ticket
/blind-review	/council --blind
/create-spec · /update-spec · /find-spec · /list-specs · /check-specs · /generate-specs · /generate-tests · /reflect-specs	/spec <sub>
/memory-config · /memory-distill · /memory-export · /memory-search · /memory-stats · /validate-memory	/memory <sub>
/incident · /demo · /local-do	removed (use /debug / /setup+/kickoff / normal IC flow)

/worktree list and /worktree status moved to /status worktree; live mutate path is /worktree release <slug> only.

Quick Start

Heads up: /setup team downloads sqlite-vec, sqlite-lembed, and an embedding model (~29MB) for semantic memory search — 1–2 minutes, needs internet. On a restricted or air-gapped network, use /setup team --no-extensions for keyword-only search.

New project:

/setup project             # Sets up AGENTS.md, specs/TDD.md, .claude/plans/
/setup team                # Bootstraps all agent memories from your codebase
/setup orchestration       # Enable Agent Teams: env var + quality-gate hook + AGENTS.md

Existing project:

/setup team                # Run once — reads AGENTS.md, code, CI, infra, writes per-agent memory

Starting a task:

/kickoff POC-123 "Add user avatar upload with S3 storage"

Runs PM + Tech Lead in parallel, creates a spec, produces an implementation plan, and generates a task graph — all in one command. For full lifecycle automation (branch, implement, review, PR), use /orchestrate POC-123.

You can also invoke agents directly (Use the ic5 subagent to implement: …) or just describe the task — Claude routes to the right agent based on their descriptions.

/setup project and /setup orchestration generate a local .claude/settings.json that pre-approves common operations so agents run without permission prompts. See Autonomy & Permissions below.

Typical Workflow

PM  ──► defines requirements + acceptance criteria
         │
Tech Lead ──► architecture direction, unblocks ICs
         │
IC5 / IC4 ──► implement (IC5: complex, IC4: simple)
         │
QA  ──► validates all acceptance criteria ─── BLOCK if issues ──► back to IC
         │ GO
DevOps ──► deploy + monitor

Task type	Agent
Ambiguous / hard / new system	IC5
Clear pattern extension / tests / config	IC4
Design question / architecture	Tech Lead
Bug investigation + fix	IC5
Infrastructure, deploy, CI	DevOps
Spec validation, release gate	QA
Requirements, scoping	PM

Specs

Specs live in specs/ and are tracked in specs/TDD.md. QA reads them as acceptance criteria; the IC agents read them before implementation. Create with /spec create, audit with /spec check, and run a full health check with /spec reflect. Categories:

Prefix	Category
SPEC-	Core behavior
PERF-	Performance
SAFE-	Safety / concurrency
COMPAT-	Compatibility
ARCH-	Architecture

See the Specs runbook for the full workflow.

Autonomy & Permissions

Process state under .claude/ (settings, hooks, plans, memory, backlog, …) is local runtime only — gitignored and never committed as product delivery (never upstream). Each machine regenerates it via /setup.

.claude/settings.json is written by /setup project (interactive/solo) or /setup orchestration (Agent Teams). It pre-approves common operations so agents run without prompting for every tool call:

• Interactive (/setup project) — defaultMode: "acceptEdits" plus a curated Bash allowlist (dev tools, agent-bootstrap patterns, read-only utilities, sqlite3, curl). rm and wget are excluded and fall through to the host's default ask. The canonical list lives in skills/scaffold-project/SKILL.md — the single source of truth.
• Orchestration (/setup orchestration) — grants the matrix allow set (Bash(*) + Read/Write/Edit/Glob/Grep/Agent/Task) under auto with sandbox enabled + autoAllowBashIfSandboxed (matrix winner Cell D / CDT-75; evidence in docs/internal/permission-posture-matrix.md). The OS sandbox is the boundary; auto evaluates tools within policy (Linear MCP works without static mcp__* allow entries).

Extend for your stack by adding entries (Bash(terraform:*), Bash(kubectl:*), …) to .claude/settings.json. Full details in the Setup Guide.

Plugin contributors: live .claude/hooks/*.sh are generated, not package-tracked. Edit the fenced templates in skills/init-orchestration/SKILL.md (sole source of truth), then re-run /setup orchestration to regenerate hooks locally.

Adding to a Team

Claude Code

The generated .claude/settings.json is gitignored, so to share the plugin with teammates, add the marketplace entry to a settings file you do commit:

{
  "extraKnownMarketplaces": {
    "cold-dark-void": {
      "source": { "source": "github", "repo": "cold-dark-void/claude-dev-team" }
    }
  },
  "enabledPlugins": {
    "dev-team@cold-dark-void": true
  }
}

The key under extraKnownMarketplaces is the marketplace name (name in .claude-plugin/marketplace.json — cold-dark-void), not the plugin name. enabledPlugins auto-enables the plugin after the marketplace is known.

opencode

For opencode, clone the repo and run bash install.sh to install into your opencode config directory (commands are symlinked; agents are copied with the Claude Code tools: field stripped, since opencode rejects it — re-run after editing an agent). Commands are accessible as /dev-team/<command-name> (e.g., /dev-team/handoff, /dev-team/recall).

bash install.sh --dry-run prints every planned change (removals, dirs, symlink, model pins left unchanged, agent copies) and writes nothing — exits 0. Both scripts auto-detect opencode first: if neither an opencode binary on PATH nor an existing config dir is found, install skips with a warning instead of writing into a dead config dir. Install also warns when the opencode agent tree has 100+ agent .md files, since opencode may silently ignore agents past that point.

Uninstall with bash uninstall.sh. It removes the commands/dev-team symlink only when that symlink points at this clone's commands/ directory, removes the generated agents/dev-team directory, and deletes the dev-team model pins in opencode.json. bash uninstall.sh --dry-run prints would remove: <path> / not found: <path> per target and removes nothing. An unknown flag on either script exits 64 and writes nothing. A default bash install.sh does not change existing model pins; bash install.sh --reset clears the dev-team pins.

These Surfaces have a commands/<name>.md file. After install they are /dev-team/<name>: adjust-agent, audit, bug-hunt, compact-transcript, council, craft-loop, debug, doctor, epic, handoff, memory, mode, recall, release-train, retro, setup, spec, status, tdd-gate, worktree.

These Surfaces are skills only. They have no commands/<name>.md file, so install does not create a /dev-team/<name> command for them. Add this clone's skills/ directory to skills.paths (the block below) and invoke the skill by the name in its SKILL.md: kickoff, orchestrate, brainstorm, backlog, release, ci-watch, refactor, review-and-commit, wrap-ticket.

For skills, add your clone's skills/ directory to opencode.json (skills are not symlinked by install.sh — they are loaded in place from the clone):

{
  "skills": {
    "paths": ["~/claude-dev-team/skills"]
  }
}

For teammates, add the plugin paths to opencode.json. Agents and commands resolve from the install.sh symlinks under ~/.config/opencode/; skills still load from the clone's skills/ directory:

{
  "skills": {
    "paths": ["~/claude-dev-team/skills"]
  }
}

Agents and commands need no extra keys: opencode auto-discovers the ~/.config/opencode/agents/ and ~/.config/opencode/commands/ directories that install.sh populates. (skills.paths is a real opencode.json key; agents.paths / commands.paths are not.)

Note: opencode command names are namespaced as /dev-team/<command> (e.g., /dev-team/handoff instead of /handoff) to avoid conflicts with other plugins and opencode's built-in commands.

/council

Adversarial tribunal that reality-checks claims with material evidence. Spawns blind read-only investigators, a prosecutor, a devil's advocate, and a tool-less council-judge, then issues per-claim verdicts (VERIFIED, PARTIALLY_VERIFIED, UNVERIFIED, CONTRADICTED, FABRICATED) with confidence scores — every verdict backed by investigator evidence or struck. Shares an engine with /review-and-commit (diff-mode preset).

Full docs: docs/commands/council.md · Contract: specs/core/SPEC-013-adversarial-council-tribunal.md.

Requirements

• Claude Code 2.x+ (Claude Code install)
• opencode 1.x+ (opencode install)
• Git (for worktree-aware memory path resolution)
• sqlite3 recommended for the SQLite memory backend — agents fall back to .md files without it

Changelog

See CHANGELOG.md. Maintained by the /release skill.

Versioning

Plugin version is kept in lockstep across plugin.json and CHANGELOG.md. marketplace.json pins install channels via git refs (stable / master), not a version field. Use /release to bump, commit, tag, and push — do not edit the version pair by hand. Contract: SPEC-002.

License

MIT — see LICENSE.

Security

Supported versions and vulnerability reporting: SECURITY.md.