Skip to content

README.md

Latest commit

 

History

History
197 lines (156 loc) · 5.98 KB

README.md

File metadata and controls

197 lines (156 loc) · 5.98 KB

Custom Agents

Custom orchestration agents and skills for Claude Code development workflow.

Quick Start

# Initialize task system in your project
/custom-agents:init

# Plan a feature (creates epic + tasks)
/custom-agents:plan Build a user authentication system

# Start working on tasks
/custom-agents:work ca-1-abc

# Check progress
/custom-agents:status

Architecture

Claude Code uses a 2-tier architecture:

  • Main Thread (Orchestrator): Routes tasks to specialists, never implements directly
  • Specialist Agents: Perform actual implementation work

There are no intermediate "controller" agents - subagents cannot spawn other subagents.

Slash Commands

Command Description
/custom-agents:init Initialize task system with optional --memory and --review flags
/custom-agents:plan Create epic with decomposed tasks from a feature request
/custom-agents:work Execute tasks using worker agent with re-anchoring
/custom-agents:status Show system state and progress
/custom-agents:next Get next actionable task (with optional --start)

Plugins

Plugin Agents Description
controllers 1 Orchestration system with taskctl, worker agent, and skills
frontend 15+ Frontend/UI development specialists
backend 15+ Backend/API development specialists
creative 12+ Design, content, and creative specialists
discovery 17+ Research, planning, analysis, and scout specialists
devops 10+ DevOps, testing, and quality specialists
utilities 15+ Cross-cutting utility specialists

Controllers Plugin (v2.2.0)

The controllers plugin provides a complete task orchestration system:

Features

Feature Description
taskctl CLI Epic/task state management with dependencies
Worker Agent Re-anchoring protocol for drift-free execution
Review Gating QA verdicts (SHIP/NEEDS_WORK/MAJOR_RETHINK)
Guard Hooks Workflow enforcement via PreToolUse/PostToolUse
Parallel Scouts Token-efficient codebase exploration
Memory System Pattern learning from implementations

Task Lifecycle

/custom-agents:init     →  Create .tasks/ directory
        ↓
/custom-agents:plan     →  Epic + decomposed tasks
        ↓
/custom-agents:work     →  Worker executes with re-anchoring
        ↓
    [Review Loop]       →  QA verdict (if enabled)
        ↓
/custom-agents:status   →  Track progress

Worker Protocol

The worker agent follows a strict re-anchoring protocol:

  1. Re-Anchor: Read epic spec, task spec, git state
  2. Implement: Follow specification exactly
  3. Verify: Check acceptance criteria
  4. Review: Submit for QA (if enabled)
  5. Complete: Commit and mark done

Orchestration System

5-Phase Multi-Track Orchestration

For complex tasks, the system uses a sophisticated 5-phase approach:

ASSESS → DECOMPOSE → EXECUTE → SYNTHESIZE → FOLLOW-UP
  1. ASSESS: Detect complexity, determine orchestration mode
  2. DECOMPOSE: Break into component-based tracks
  3. EXECUTE: Spawn agents per track in parallel waves
  4. SYNTHESIZE: Combine outputs into cohesive deliverables
  5. FOLLOW-UP: Auto-spawn quality agents until complete

Complexity Modes

Mode Score Action
SIMPLE 0-2 Direct single-agent routing
MODERATE 3-4 2-3 parallel tracks
COMPLEX 5+ Full multi-track orchestration

Key Principle: Component-Based Decomposition

Decomposition is based on WHAT is needed, not WHO builds it.

Wrong:

Track 1: @page-builder
Track 2: @css-architect

Correct:

Track 1: layout-structure → @react-engineer
Track 2: design-tokens → @css-architect
Track 3: api-integration → @api-architect

Installation

/plugins install <github-username>/custom-agents

Documentation

See plugins/controllers/HOW-TO.md for comprehensive usage guide.

Directory Structure

plugins/
├── controllers/
│   ├── agents/
│   │   └── worker.md           # Re-anchoring worker agent
│   ├── commands/
│   │   └── custom-agents/      # Slash commands
│   │       ├── init.md
│   │       ├── plan.md
│   │       ├── work.md
│   │       ├── status.md
│   │       └── next.md
│   ├── hooks/
│   │   ├── hooks.json          # Hook configuration reference
│   │   ├── pre-edit-guard.sh
│   │   ├── pre-write-guard.sh
│   │   └── post-bash-guard.sh
│   ├── scripts/
│   │   ├── taskctl             # CLI entry point
│   │   ├── taskctl.py          # Task management CLI
│   │   └── state_schema.py     # State type definitions
│   ├── skills/
│   │   ├── complexity-detection.md
│   │   ├── multi-track-orchestration.md
│   │   ├── re-anchoring.md
│   │   ├── review-gating.md
│   │   ├── guard-hooks.md
│   │   ├── memory-management.md
│   │   ├── parallel-research.md
│   │   └── ...
│   ├── plugin.json
│   └── HOW-TO.md               # Comprehensive guide
├── frontend/
│   ├── agents/                 # Frontend specialists
│   └── skills/
├── backend/
│   ├── agents/                 # Backend specialists
│   └── skills/
├── creative/
│   ├── agents/                 # Creative specialists
│   └── skills/
├── discovery/
│   ├── agents/                 # Research/planning + scout specialists
│   └── skills/
├── devops/
│   ├── agents/                 # DevOps/QA specialists
│   └── skills/
└── utilities/
    ├── agents/                 # Cross-cutting specialists
    └── skills/

Version

controllers: v2.2.0