A Claude Code plugin providing 127 specialized AI agents with:
- Interview-driven planning - Clarify requirements before work begins
- Codebase research - Investigate patterns and blockers before implementation
- SQLite state management - Reliable session tracking and cost analytics
- Model escalation - Automatic haiku → sonnet → opus progression
- Bug Council - 5-agent diagnostic team for complex issues
- Eco mode - Cost-optimized execution mode for simpler tasks
- Quality gates - Tests, types, lint, security, coverage enforcement
This is a Claude Code plugin composed of:
- Markdown agent instructions (
agents/*.md) — Claude Code reads these and follows them as subagent prompts via the Task tool - YAML configuration (
.devteam/*.yaml) — defines capabilities, thresholds, and agent selection triggers - Shell scripts (
scripts/*.sh,hooks/*.sh) — handle state persistence (SQLite), event logging, hook lifecycle, and database management - Slash commands (
commands/*.md,skills/*/SKILL.md) — user-facing commands that orchestrate agent workflows
There is no separate executable orchestrator. Claude Code itself is the runtime — it reads the agent markdown files, selects appropriate agents based on task characteristics, and executes them as subagents. The shell scripts provide supporting infrastructure (database, hooks, state tracking) but the orchestration logic lives in the agent instructions themselves.
Task Loop is the iterative quality enforcement system that ensures every task is completed to specification:
┌─────────────────────────────────────────────────────────────┐
│ TASK LOOP │
│ │
│ Execute → Quality Gates → Pass? → Complete │
│ ↑ │ │
│ │ Fail │
│ │ ↓ │
│ └─── Fix Tasks ← Model Escalation (if needed) │
│ │
│ Loop until: ALL QUALITY GATES PASS │
└─────────────────────────────────────────────────────────────┘
Features:
- Automatic model escalation (haiku → sonnet → opus) after failures
- Stuck loop detection with Bug Council activation
- Quality gates: tests, types, lint, security, coverage
- Anti-abandonment system prevents agents from giving up
- Maximum 10 iterations with human notification
The /devteam:implement command automatically selects the best agents for your task:
/devteam:implement "Add user authentication with JWT tokens"The /devteam:implement command analyzes your task description, file types involved, and project context to select appropriate agents. It considers keyword matches, file extensions, task type (feature vs. bug), and detected language/framework.
For complex bugs, the Bug Council convenes 5 specialized analysts:
┌─────────────────────────────────────────────────────────────┐
│ BUG COUNCIL │
├─────────────────────────────────────────────────────────────┤
│ Root Cause Analyst │ Error analysis, stack traces │
│ Code Archaeologist │ Git history, regression detection │
│ Pattern Matcher │ Similar bugs, anti-patterns │
│ Systems Thinker │ Dependencies, integration issues │
│ Adversarial Tester │ Edge cases, security vectors │
└─────────────────────────────────────────────────────────────┘
↓
Synthesized Solution
Activation Triggers:
- Critical/high severity bugs
- 3+ failed opus attempts
- Complexity score ≥ 10
- Explicit
bug_council: trueflag
Agents are strictly confined to their assigned scope:
scope:
allowed_files:
- "src/auth/*.py"
forbidden_directories:
- "src/billing/"
max_files_changed: 56 Enforcement Layers:
- Task scope definition in YAML
- Agent prompt constraints
- Scope validator agent with VETO power
- Pre-commit hook blocking
- Runtime file access control
- Out-of-scope observations logging
Agents cannot give up. The persistence system ensures completion:
Abandonment Attempt → Detected → Re-engagement Prompt
↓
Still stuck?
↓
Model Escalation (haiku → sonnet → opus)
↓
Still stuck?
↓
Bug Council Activation
↓
Still stuck?
↓
Human Notification (but keep trying)
| Category | Agents | Capabilities |
|---|---|---|
| SRE | Site Reliability Engineer | SLOs, incident response, chaos engineering |
| SRE | Platform Engineer | Internal developer platforms, golden paths |
| SRE | Observability Engineer | Metrics, logging, tracing, alerting |
| Security | Penetration Tester | OWASP testing, API security, vuln assessment |
| Security | Compliance Engineer | SOC2, HIPAA, GDPR, PCI-DSS |
| Product | Product Manager | PRDs, roadmaps, user research |
| Quality | Accessibility Specialist | WCAG 2.1, screen readers, inclusive design |
| DevRel | Developer Advocate | Technical content, community, DX |
| Agent | Purpose |
|---|---|
| Autonomous Controller | Execution loop management, state transitions, circuit breaker |
| Bug Council Orchestrator | Multi-perspective bug analysis |
| Code Review Coordinator | Cross-agent code review orchestration |
| Quality Gate Enforcer | Run and aggregate quality gate results |
| Requirements Validator | Validate acceptance criteria met |
| Scope Validator | Enforce scope boundaries |
| Sprint Loop | Sprint-level quality validation after all tasks |
| Sprint Orchestrator | Sprint execution management, task sequencing |
| Task Loop | Iterative quality loop for single task execution |
| Track Merger | Merge parallel worktree tracks |
| Workflow Compliance | Meta-validator auditing orchestration process |
| Agent | Specialty |
|---|---|
| Root Cause Analyst | Error analysis, hypothesis generation |
| Code Archaeologist | Git history, regression detection |
| Pattern Matcher | Similar bugs, anti-pattern identification |
| Systems Thinker | Dependencies, architectural issues |
| Adversarial Tester | Edge cases, security vulnerabilities |
Backend (by language):
- Python (FastAPI, Django, Flask)
- TypeScript (Express, NestJS, Fastify)
- Go (Gin, Echo, Fiber)
- Java (Spring Boot, Micronaut)
- C# (ASP.NET Core)
- Ruby (Rails, Sinatra)
- PHP (Laravel, Symfony)
Frontend:
- React, Vue, Svelte, Angular specialists
- Accessibility specialist
- Performance auditor
Database:
- Schema designers
- Query optimization specialists
- Migration specialists
DevOps:
- CI/CD Specialist (GitHub Actions, Jenkins, GitLab CI)
- Docker Specialist
- Kubernetes Specialist
- Terraform Specialist
| Agent | Focus |
|---|---|
| Test Writer | Unit, integration, e2e tests |
| Security Auditor | OWASP Top 10, vulnerability scanning |
| Performance Auditor | Profiling, optimization, load testing |
| Accessibility Specialist | WCAG compliance, inclusive design |
| E2E Tester | Playwright, Cypress, browser testing |
# Plan a new feature (interview → research → PRD → tasks → sprints)
/devteam:plan --feature "Add user authentication with OAuth"
# Execute the plan
/devteam:implement
# Or execute specific sprint
/devteam:implement --sprint 1The system will:
- Interview - Clarify requirements with targeted questions
- Research - Analyze codebase, identify patterns and blockers
- Plan - Generate PRD, tasks, and sprints
- Execute - Run with Task Loop quality loop and model escalation
- Verify - Pass all quality gates before completion
# Fix a local bug (interview → diagnose → fix → verify)
/devteam:bug "Login fails for guest users"
# Fix a GitHub issue
/devteam:issue 123
# Force Bug Council for complex issues
/devteam:bug "Memory leak in image processor" --council# Use eco mode (lower-cost models for simpler tasks)
/devteam:implement --eco
/devteam:bug "Minor CSS issue" --eco# Check status, costs, progress
/devteam:status
# List plans and tasks
/devteam:list
# Reset stuck sessions
/devteam:resetloop_settings:
max_iterations: 10
model_escalation:
enabled: true
consecutive_failures:
haiku_to_sonnet: 2
sonnet_to_opus: 2
opus_max_failures: 3 # Then Bug Council
quality_gates:
required:
tests_passing: true
type_check: true
lint: true
security:
on_finding: create_fix_task# In task definition
scope:
allowed_files:
- "src/auth/*.py"
allowed_patterns:
- "tests/auth/**/*.py"
forbidden_directories:
- "src/billing/"
- "src/admin/"
max_files_changed: 10categories:
security:
agents:
- id: penetration_tester
triggers:
keywords: [pentest, security testing, vulnerability]
task_types: [security_testing]The system uses Claude Code hooks for autonomous execution. All hooks support both Linux/macOS (Bash) and Windows (PowerShell).
| Hook | Linux/macOS | Windows | Purpose |
|---|---|---|---|
| Stop Hook | stop-hook.sh |
stop-hook.ps1 |
Blocks exit without EXIT_SIGNAL: true |
| Persistence Hook | persistence-hook.sh |
persistence-hook.ps1 |
Detects and prevents abandonment |
| Scope Check | scope-check.sh |
scope-check.ps1 |
Validates commits stay in scope |
| Pre-Compact | pre-compact.sh |
pre-compact.ps1 |
Preserves state before context compaction |
| Pre-Tool-Use | pre-tool-use-hook.sh |
pre-tool-use-hook.ps1 |
Pre-execution validation |
| Post-Tool-Use | post-tool-use-hook.sh |
post-tool-use-hook.ps1 |
Post-execution logging |
| Session Start | session-start.sh |
session-start.ps1 |
Session initialization |
| Session End | session-end.sh |
session-end.ps1 |
Session cleanup |
| Install | install.sh |
install.ps1 |
Hook installation script |
When installed via the marketplace or as a plugin, all hooks are configured automatically through hooks/hooks.json. No manual settings.json editing is required.
See hooks/README.md for hook details and troubleshooting.
| Complexity | Model | Characteristics | Use Case |
|---|---|---|---|
| 1-4 | Haiku | Fast, lowest cost | Simple fixes, docs |
| 5-8 | Sonnet | Balanced | Standard features |
| 9-14 | Opus | Most capable, highest cost | Complex architecture |
Task starts at complexity-appropriate tier
│
▼
Attempt #1
│
FAIL? ──────────────────┐
│ │
▼ ▼
Attempt #2 Same tier
│ + more context
FAIL? ──────────────────┐
│ │
▼ ▼
Attempt #3 Same tier
│ + alt approach
FAIL? ──────────────────┐
│ │
▼ ▼
ESCALATE Upgrade tier
│ (haiku→sonnet→opus)
▼
Continue with higher tier
User Request
│
▼
┌─────────────────┐
│ /devteam:implement │ ← Automatic agent selection
└────────┬────────┘
│
▼
┌─────────────────┐
│ Task Loop │ ← Iterative quality loop per task
└────────┬────────┘
│
▼
┌─────────────────┐
│ TASK LOOP │ ← Quality loop wrapper
│ ┌───────────┐ │
│ │ Execute │ │ ← Selected agents work
│ │ Agents │ │
│ └─────┬─────┘ │
│ │ │
│ ▼ │
│ ┌───────────┐ │
│ │ Quality │ │ ← Tests, lint, security
│ │ Gates │ │
│ └─────┬─────┘ │
│ │ │
│ PASS│ FAIL │
│ │ │ │
│ │ ▼ │
│ │ ┌────┐ │
│ │ │Fix │ │ ← Create fix tasks
│ │ └──┬─┘ │
│ │ │ │
│ │ ▼ │
│ │ Escalate? → Model upgrade if needed
│ │ │ │
│ └────┴───┘
│ │
└─────────────┘
│
▼
EXIT_SIGNAL: true
.devteam/
├── config.yaml # Main project configuration
├── task-loop-config.yaml # Task Loop quality loop config
├── agent-capabilities.yaml # Agent registry with triggers
├── agent-selection.md # Selection algorithm docs
├── persistence-config.yaml # Anti-abandonment rules
├── scope-enforcement.md # Scope system docs
├── model-selection.md # Dynamic model assignment
├── parallel-execution.md # Concurrent task handling
├── plan-management.md # Plan lifecycle tracking
├── sprint-loop-config.yaml # Sprint validation settings
├── task-loop-config.yaml # Task execution settings
├── code-review-config.yaml # Code review standards
├── database-config.yaml # Database setup
├── frontend-config.yaml # Frontend-specific settings
├── performance-config.yaml # Performance audit thresholds
├── test-config.yaml # Test framework configuration
├── testing-config.yaml # Test execution config
├── ux-config.yaml # UX validation rules
├── validation-config.yaml # Requirements validation rules
├── refactoring-config.yaml # Refactoring guidelines
├── devteam.db # SQLite execution state + circuit breaker tracking (runtime)
└── plans/ # Multi-plan storage (runtime)
agents/
├── orchestration/ # 11 orchestration agents
│ ├── autonomous-controller.md
│ ├── bug-council-orchestrator.md
│ ├── code-review-coordinator.md
│ ├── quality-gate-enforcer.md
│ ├── requirements-validator.md
│ ├── scope-validator.md
│ ├── sprint-loop.md
│ ├── sprint-orchestrator.md
│ ├── task-loop.md
│ ├── track-merger.md
│ └── workflow-compliance.md
├── planning/ # PRD & sprint planning (3)
├── research/ # Codebase research (1)
├── diagnosis/ # Bug Council agents (5)
├── backend/ # Backend API developers (16)
├── frontend/ # Frontend developers (3)
├── database/ # Database specialists (12)
├── quality/ # Testing & QA (26)
├── devops/ # CI/CD, Docker, K8s (5)
├── mobile/ # iOS, Android, Flutter, RN (8)
├── security/ # Security & Compliance (10)
├── sre/ # Site Reliability Engineering (2)
├── ux/ # Design system agents (12)
├── accessibility/ # A11y specialists (2)
├── architecture/ # System architecture (1)
├── data-ai/ # Data & ML engineering (2)
├── devrel/ # Developer advocacy (1)
├── product/ # Product management (1)
├── specialized/ # Observability (1)
├── support/ # Dependency management (1)
├── infrastructure/ # Configuration management (1)
├── python/ # Python utilities (1)
├── scripting/ # Shell & PowerShell (2)
└── templates/
└── base-agent.md
commands/ # 20 slash commands
├── devteam-plan.md
├── devteam-implement.md
├── devteam-bug.md
├── devteam-issue.md
├── devteam-issue-new.md
├── devteam-status.md
├── devteam-reset.md
├── devteam-config.md
├── devteam-logs.md
├── devteam-help.md
├── devteam-list.md
├── devteam-select.md
├── devteam-design.md
├── devteam-design-drift.md
├── devteam-review.md
├── devteam-test.md
├── merge-tracks.md
├── worktree-status.md
├── worktree-list.md
└── worktree-cleanup.md
skills/ # 20 skill definitions (SKILL.md per directory)
├── devteam-plan/
├── devteam-implement/
├── devteam-bug/
├── ... (one directory per command)
└── worktree-cleanup/
.claude/
└── rules/ # 11 path-specific rule files
└── *.md
agent-registry.json # Agent and command registry (127 agents, 20 commands)
settings.json # Plugin default settings
.mcp.json # Bundled MCP server configs (GitHub, Memory)
.lsp.json # Language server configs (8 languages)
hooks/ # Cross-platform hooks
├── stop-hook.sh / .ps1 # Exit control
├── persistence-hook.sh / .ps1
├── scope-check.sh / .ps1
├── pre-compact.sh / .ps1
├── pre-tool-use-hook.sh / .ps1
├── post-tool-use-hook.sh / .ps1
├── session-start.sh / .ps1
├── session-end.sh / .ps1
├── install.sh / .ps1
├── lib/ # Shared hook utilities
├── tests/ # Hook test suite
└── README.md
mcp-configs/ # MCP server configurations
├── required.json
├── recommended.json
├── optional.json
├── lsp-servers.json
└── README.md
| Command | Description |
|---|---|
/devteam:plan |
Interactive planning with interview, research, and sprint generation |
/devteam:implement |
Execute plans, sprints, tasks, or ad-hoc work |
/devteam:bug "<desc>" |
Fix bugs with diagnostic workflow and Bug Council |
/devteam:issue <#> |
Fix GitHub issues with interview if needed |
/devteam:status |
Display system health, progress, and costs |
/devteam:reset |
Reset stuck sessions and recover from errors |
/devteam:plan # Interactive planning
/devteam:plan --feature "desc" # Plan specific feature
/devteam:plan --from spec.md # Plan from spec file
/devteam:plan --skip-research # Skip research phase/devteam:implement # Execute current plan
/devteam:implement --sprint 1 # Execute specific sprint
/devteam:implement --all # Execute all sprints
/devteam:implement --task TASK-001 # Execute specific task
/devteam:implement "ad-hoc task" # One-off task with interview
/devteam:implement --eco # Cost-optimized mode/devteam:bug "description" # Fix with interview
/devteam:bug "desc" --council # Force Bug Council
/devteam:bug "desc" --severity critical
/devteam:bug "desc" --eco # Cost-optimized| Command | Description |
|---|---|
/devteam:review |
Run cross-agent code review |
/devteam:test |
Run test coordination and execution |
/devteam:design |
Design system generation and validation |
/devteam:design-drift |
Detect design system drift |
| Command | Description |
|---|---|
/devteam:list |
List plans, sprints, and tasks |
/devteam:select <plan> |
Select active plan |
/devteam:issue-new "<desc>" |
Create new GitHub issue |
/devteam:config |
View and modify configuration |
/devteam:logs |
View execution logs |
/devteam:help |
Get help on any topic |
| Command | Description |
|---|---|
/devteam:worktree-status |
Show worktree status |
/devteam:worktree-list |
List all worktrees |
/devteam:worktree-cleanup |
Clean up worktrees |
/devteam:merge-tracks |
Merge parallel tracks |
See commands/README.md for detailed documentation.
Every task must pass:
| Gate | Requirement |
|---|---|
| Tests | 100% of tests passing |
| Types | No type errors (mypy, tsc) |
| Lint | No lint errors |
| Security | No high/critical findings |
| Coverage | ≥80% code coverage |
| Scope | All changes within scope |
No task completes without all gates passing.
/devteam:implement "Add user profile page with avatar upload"System automatically:
- Detects React frontend + FastAPI backend
- Selects: frontend_developer, api_developer_python, test_writer
- Creates scoped subtasks for each
- Executes with Task Loop
- Security audit on file upload
- Completes when all tests pass
/devteam:implement "Fix: Users can't login after password reset"System automatically:
- Detects bug-type task
- Assigns root_cause_analyst first
- If initial fix fails, activates Bug Council
- 5 perspectives analyze the issue
- Synthesized solution implemented
- Regression tests added
/devteam:implement "Audit authentication system"System automatically:
- Selects: security_auditor, penetration_tester, compliance_engineer
- Runs OWASP Top 10 checks
- Creates fix tasks for findings
- Verifies fixes
- Generates compliance report
The easiest way to install DevTeam is directly from within Claude Code:
# 1. Add the DevTeam marketplace
/plugin marketplace add https://github.com/michael-harris/devteam
# 2. Install the plugin
/plugin install devteam@devteam-marketplace
# 3. Verify installation
/devteam:statusThat's it. The database is auto-initialized on first use. Hooks, agents, skills, and rules are all configured automatically.
For contributing or local development:
# 1. Clone the repository
git clone https://github.com/michael-harris/devteam.git
# 2. Install as a local plugin
/plugin install /path/to/devteam
# 3. Verify installation
/devteam:status- Claude Code CLI
- SQLite3
- Bash 4.0+ (Linux/macOS) or PowerShell 5.1+ (Windows)
- Git
To enable Agent Teams (parallel multi-agent execution), set this environment variable before starting Claude Code:
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1Q: What stops agents from giving up?
A: The persistence system detects "give up" language and blocks it, forcing continued effort with escalating re-engagement prompts, model upgrades, and Bug Council activation.
Q: How does model escalation work?
A: After 2 consecutive failures at a tier, the model upgrades (haiku→sonnet→opus). After 3 opus failures, Bug Council activates.
Q: Can agents modify files outside their scope?
A: No. The scope validator has VETO power and blocks all out-of-scope changes. Agents log observations for out-of-scope issues instead.
Q: What triggers the Bug Council?
A: Critical bugs, 3+ failed opus attempts, complexity ≥10, or explicit flag.
Q: How do I customize agent selection?
A: Edit .devteam/agent-capabilities.yaml to add triggers, keywords, and file patterns.
Contributions welcome! Areas of interest:
- Additional language support
- New enterprise agent roles
- Improved selection algorithms
- Integration with more tools
This project draws inspiration from and builds upon several pioneering projects in the AI-assisted development space.
These projects directly influenced our design and implementation:
| Project | What We Learned | Link |
|---|---|---|
| ralph-claude-code | The Ralph autonomous loop concept, EXIT_SIGNAL pattern, circuit breaker for stagnation detection, dual-condition exit gates, .ralph/ directory structure pattern |
github.com/frankbria/ralph-claude-code |
| everything-claude-code | Specialized agent delegation pattern, cross-platform hook architecture, subagent orchestration strategies, skill/agent separation | github.com/affaan-m/everything-claude-code |
| awesome-claude-skills | Skill organization patterns, YAML frontmatter structure, category-based skill taxonomy | github.com/ComposioHQ/awesome-claude-skills |
| wshobson/agents | Tiered model assignment (Opus/Sonnet/Haiku), plugin architecture patterns, token efficiency strategies, 72-plugin modular design | github.com/wshobson/agents |
| ui-ux-pro-max-skill | Design system generation patterns, industry-specific rule sets, Master+Overrides architecture concept | github.com/nextlevelbuilder/ui-ux-pro-max-skill |
While inspired by these projects, we developed original implementations:
| Feature | Inspiration Source | Our Original Addition |
|---|---|---|
| Task Loop | ralph-claude-code's autonomous loop | Added model escalation (haiku→sonnet→opus), Bug Council activation, quality gates integration |
| Model Escalation | wshobson/agents tier concept | Automatic escalation after consecutive failures, complexity-based initial selection, de-escalation after success |
| Bug Council | Original concept | 5-agent multi-perspective debugging system with synthesized solutions |
| Scope Enforcement | Original concept | 6-layer enforcement with VETO power, out-of-scope observations logging |
| Anti-Abandonment | Original concept | Persistence hooks detecting "give up" patterns, escalating re-engagement prompts |
| Agent Selection | everything-claude-code delegation | Task-aware agent selection based on keywords, file types, task type, and language |
| Enterprise Agents | wshobson/agents categories | SRE, Platform Engineer, Compliance Engineer, Penetration Tester, and 8 other enterprise roles |
| Project | Inspiration | Link |
|---|---|---|
| Aider | Iterative code refinement and "linting loops" | github.com/paul-gauthier/aider |
| AutoGPT | Multi-agent orchestration patterns | github.com/Significant-Gravitas/AutoGPT |
| MetaGPT | Role-based agents, "committee of experts" | github.com/geekan/MetaGPT |
| GPT-Engineer | PRD-to-code workflows | github.com/gpt-engineer-org/gpt-engineer |
| Sweep AI | Automated bug fixing patterns | github.com/sweepai/sweep |
| OpenHands | Agent-computer interfaces | github.com/All-Hands-AI/OpenHands |
| SWE-agent | Software engineering agent design | github.com/princeton-nlp/SWE-agent |
- OWASP Top 10 - Security testing methodology
- WCAG 2.1 - Accessibility compliance standards
- SOC2/HIPAA/GDPR/PCI-DSS - Compliance frameworks
- Google SRE - Site Reliability Engineering practices
- The Twelve-Factor App - Modern application design principles
All code in this repository was written from scratch. While we adopted concepts and patterns from the above projects (particularly the Ralph loop concept from frankbria/ralph-claude-code), our implementations are original:
- Our hooks use different file structures (
.devteam/vs.ralph/) - Our config uses YAML with model escalation (original uses INI without escalation)
- Our agent definitions follow a different structure
- Bug Council, scope enforcement, and anti-abandonment are entirely original systems
MIT License - See LICENSE file.
Built for Claude Code