mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
docs: add VitePress documentation site
- Add docs directory with VitePress configuration - Add GitHub Actions workflow for docs build and deploy - Support bilingual (English/Chinese) documentation - Include search, custom theme, and responsive design
This commit is contained in:
catlog22
524
docs/agents/builtin.md
Normal file
524
docs/agents/builtin.md
Normal file
@@ -0,0 +1,524 @@
|
||||
# Built-in Agents
|
||||
|
||||
CCW includes **21 specialized agents** organized across 5 categories, each designed for specific development tasks. Agents can work independently or be orchestrated together for complex workflows.
|
||||
|
||||
## Categories Overview
|
||||
|
||||
| Category | Count | Primary Use |
|
||||
|----------|-------|-------------|
|
||||
| [CLI](#cli-agents) | 6 | CLI-based interactions, exploration, and planning |
|
||||
| [Development](#development-agents) | 5 | Code implementation and debugging |
|
||||
| [Planning](#planning-agents) | 4 | Strategic planning and issue management |
|
||||
| [Testing](#testing-agents) | 3 | Test generation, execution, and quality assurance |
|
||||
| [Documentation](#documentation-agents) | 3 | Documentation and design systems |
|
||||
|
||||
---
|
||||
|
||||
## CLI Agents
|
||||
|
||||
### cli-explore-agent
|
||||
|
||||
**Purpose**: Specialized CLI exploration with 3 analysis modes
|
||||
|
||||
**Capabilities**:
|
||||
- Quick-scan (Bash only)
|
||||
- Deep-scan (Bash + Gemini)
|
||||
- Dependency-map (graph construction)
|
||||
- 4-phase workflow: Task Understanding → Analysis Execution → Schema Validation → Output Generation
|
||||
|
||||
**Tools**: `Bash`, `Read`, `Grep`, `Glob`, `ccw cli (gemini/qwen/codex)`, `ACE search_context`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
prompt: "Analyze authentication module dependencies"
|
||||
})
|
||||
```
|
||||
|
||||
### cli-discuss-agent
|
||||
|
||||
**Purpose**: Multi-CLI collaborative discussion with cross-verification
|
||||
|
||||
**Capabilities**:
|
||||
- 5-phase workflow: Context Prep → CLI Execution → Cross-Verify → Synthesize → Output
|
||||
- Loads discussion history
|
||||
- Maintains context across sessions
|
||||
|
||||
**Tools**: `Read`, `Grep`, `Glob`, `ccw cli`
|
||||
|
||||
**Calls**: `cli-explore-agent` for codebase discovery before discussions
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-discuss-agent",
|
||||
prompt: "Discuss architecture patterns for microservices"
|
||||
})
|
||||
```
|
||||
|
||||
### cli-execution-agent
|
||||
|
||||
**Purpose**: Intelligent CLI execution with automated context discovery
|
||||
|
||||
**Capabilities**:
|
||||
- 5-phase workflow: Task Understanding → Context Discovery → Prompt Enhancement → Tool Execution → Output Routing
|
||||
- Background execution support
|
||||
- Result polling
|
||||
|
||||
**Tools**: `Bash`, `Read`, `Grep`, `Glob`, `ccw cli`, `TaskOutput`
|
||||
|
||||
**Calls**: `cli-explore-agent` for discovery before execution
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-execution-agent",
|
||||
prompt: "Execute security scan on authentication module"
|
||||
})
|
||||
```
|
||||
|
||||
### cli-lite-planning-agent
|
||||
|
||||
**Purpose**: Lightweight planning for quick task breakdowns
|
||||
|
||||
**Capabilities**:
|
||||
- Creates simplified task JSONs without complex schema validation
|
||||
- For straightforward implementation tasks
|
||||
|
||||
**Tools**: `Read`, `Write`, `Bash`, `Grep`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-lite-planning-agent",
|
||||
prompt: "Plan user registration feature"
|
||||
})
|
||||
```
|
||||
|
||||
### cli-planning-agent
|
||||
|
||||
**Purpose**: Full-featured planning for complex implementations
|
||||
|
||||
**Capabilities**:
|
||||
- 6-field schema with context loading
|
||||
- Flow control and artifact integration
|
||||
- Comprehensive task JSON generation
|
||||
|
||||
**Tools**: `Read`, `Write`, `Bash`, `Grep`, `Glob`, `mcp__ace-tool__search_context`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-planning-agent",
|
||||
prompt: "Plan microservices architecture migration"
|
||||
})
|
||||
```
|
||||
|
||||
### cli-roadmap-plan-agent
|
||||
|
||||
**Purpose**: Strategic planning for roadmap and milestone generation
|
||||
|
||||
**Capabilities**:
|
||||
- Creates long-term project plans
|
||||
- Generates epics, milestones, and delivery timelines
|
||||
- Issue creation via ccw
|
||||
|
||||
**Tools**: `Read`, `Write`, `Bash`, `Grep`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-roadmap-plan-agent",
|
||||
prompt: "Create Q1 roadmap for payment system"
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development Agents
|
||||
|
||||
### code-developer
|
||||
|
||||
**Purpose**: Core code execution for any implementation task
|
||||
|
||||
**Capabilities**:
|
||||
- Adapts to any domain while maintaining quality standards
|
||||
- Supports analysis, implementation, documentation, research
|
||||
- Complex multi-step workflows
|
||||
|
||||
**Tools**: `Read`, `Edit`, `Write`, `Bash`, `Grep`, `Glob`, `Task`, `mcp__ccw-tools__edit_file`, `mcp__ccw-tools__write_file`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "code-developer",
|
||||
prompt: "Implement user authentication with JWT"
|
||||
})
|
||||
```
|
||||
|
||||
### tdd-developer
|
||||
|
||||
**Purpose**: TDD-aware code execution for Red-Green-Refactor workflows
|
||||
|
||||
**Capabilities**:
|
||||
- Extends code-developer with TDD cycle awareness
|
||||
- Automatic test-fix iteration
|
||||
- CLI session resumption
|
||||
|
||||
**Tools**: `Read`, `Edit`, `Write`, `Bash`, `Grep`, `Glob`, `ccw cli`
|
||||
|
||||
**Extends**: `code-developer`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "tdd-developer",
|
||||
prompt: "Implement payment processing with TDD"
|
||||
})
|
||||
```
|
||||
|
||||
### context-search-agent
|
||||
|
||||
**Purpose**: Specialized context collector for brainstorming workflows
|
||||
|
||||
**Capabilities**:
|
||||
- Analyzes existing codebase
|
||||
- Identifies patterns
|
||||
- Generates standardized context packages
|
||||
|
||||
**Tools**: `mcp__ace-tool__search_context`, `mcp__ccw-tools__smart_search`, `Read`, `Grep`, `Glob`, `Bash`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "context-search-agent",
|
||||
prompt: "Gather context for API refactoring"
|
||||
})
|
||||
```
|
||||
|
||||
### debug-explore-agent
|
||||
|
||||
**Purpose**: Debugging specialist for code analysis and problem diagnosis
|
||||
|
||||
**Capabilities**:
|
||||
- Hypothesis-driven debugging with NDJSON logging
|
||||
- CLI-assisted analysis
|
||||
- Iterative verification
|
||||
- Traces execution flow, identifies failure points, analyzes state at failure
|
||||
|
||||
**Tools**: `Read`, `Grep`, `Bash`, `ccw cli`
|
||||
|
||||
**Workflow**: Bug Analysis → Hypothesis Generation → Instrumentation → Log Analysis → Fix Verification
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "debug-explore-agent",
|
||||
prompt: "Debug memory leak in connection handler"
|
||||
})
|
||||
```
|
||||
|
||||
### universal-executor
|
||||
|
||||
**Purpose**: Versatile execution for implementing any task efficiently
|
||||
|
||||
**Capabilities**:
|
||||
- Adapts to any domain while maintaining quality standards
|
||||
- Handles analysis, implementation, documentation, research
|
||||
- Complex multi-step workflows
|
||||
|
||||
**Tools**: `Read`, `Edit`, `Write`, `Bash`, `Grep`, `Glob`, `Task`, `mcp__ace-tool__search_context`, `mcp__exa__web_search_exa`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "universal-executor",
|
||||
prompt: "Implement GraphQL API with authentication"
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Planning Agents
|
||||
|
||||
### action-planning-agent
|
||||
|
||||
**Purpose**: Pure execution agent for creating implementation plans
|
||||
|
||||
**Capabilities**:
|
||||
- Transforms requirements and brainstorming artifacts into structured plans
|
||||
- Quantified deliverables and measurable acceptance criteria
|
||||
- Control flags for execution modes
|
||||
|
||||
**Tools**: `Read`, `Write`, `Bash`, `Grep`, `Glob`, `mcp__ace-tool__search_context`, `mcp__ccw-tools__smart_search`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "action-planning-agent",
|
||||
prompt: "Create implementation plan for user dashboard"
|
||||
})
|
||||
```
|
||||
|
||||
### conceptual-planning-agent
|
||||
|
||||
**Purpose**: High-level planning for architectural and conceptual design
|
||||
|
||||
**Capabilities**:
|
||||
- Creates system designs
|
||||
- Architecture patterns
|
||||
- Technical strategies
|
||||
|
||||
**Tools**: `Read`, `Write`, `Bash`, `Grep`, `ccw cli`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "conceptual-planning-agent",
|
||||
prompt: "Design event-driven architecture for order system"
|
||||
})
|
||||
```
|
||||
|
||||
### issue-plan-agent
|
||||
|
||||
**Purpose**: Issue resolution planning with closed-loop exploration
|
||||
|
||||
**Capabilities**:
|
||||
- Analyzes issues and generates solution plans
|
||||
- Creates task JSONs with dependencies and acceptance criteria
|
||||
- 5-phase tasks from exploration to solution
|
||||
|
||||
**Tools**: `Read`, `Write`, `Bash`, `Grep`, `mcp__ace-tool__search_context`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "issue-plan-agent",
|
||||
prompt: "Plan resolution for issue #123"
|
||||
})
|
||||
```
|
||||
|
||||
### issue-queue-agent
|
||||
|
||||
**Purpose**: Solution ordering agent for queue formation
|
||||
|
||||
**Capabilities**:
|
||||
- Receives solutions from bound issues
|
||||
- Uses Gemini for intelligent conflict detection
|
||||
- Produces ordered execution queue
|
||||
|
||||
**Tools**: `Read`, `Write`, `Bash`, `ccw cli (gemini)`, `mcp__ace-tool__search_context`, `mcp__ccw-tools__smart_search`
|
||||
|
||||
**Calls**: `issue-plan-agent`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "issue-queue-agent",
|
||||
prompt: "Form execution queue for issues #101, #102, #103"
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Agents
|
||||
|
||||
### test-action-planning-agent
|
||||
|
||||
**Purpose**: Specialized agent for test planning documents
|
||||
|
||||
**Capabilities**:
|
||||
- Extends action-planning-agent for test planning
|
||||
- Progressive L0-L3 test layers (Static, Unit, Integration, E2E)
|
||||
- AI code issue detection (L0.5) with CRITICAL/ERROR/WARNING severity
|
||||
- Project-specific templates
|
||||
- Test anti-pattern detection with quality gates
|
||||
|
||||
**Tools**: `Read`, `Write`, `Bash`, `Grep`, `Glob`
|
||||
|
||||
**Extends**: `action-planning-agent`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "test-action-planning-agent",
|
||||
prompt: "Create test plan for payment module"
|
||||
})
|
||||
```
|
||||
|
||||
### test-context-search-agent
|
||||
|
||||
**Purpose**: Specialized context collector for test generation workflows
|
||||
|
||||
**Capabilities**:
|
||||
- Analyzes test coverage
|
||||
- Identifies missing tests
|
||||
- Loads implementation context from source sessions
|
||||
- Generates standardized test-context packages
|
||||
|
||||
**Tools**: `mcp__ccw-tools__codex_lens`, `Read`, `Glob`, `Bash`, `Grep`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "test-context-search-agent",
|
||||
prompt: "Gather test context for authentication module"
|
||||
})
|
||||
```
|
||||
|
||||
### test-fix-agent
|
||||
|
||||
**Purpose**: Execute tests, diagnose failures, and fix code until all tests pass
|
||||
|
||||
**Capabilities**:
|
||||
- Multi-layered test execution (L0-L3)
|
||||
- Analyzes failures and modifies source code
|
||||
- Quality gate for passing tests
|
||||
|
||||
**Tools**: `Bash`, `Read`, `Edit`, `Write`, `Grep`, `ccw cli`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "test-fix-agent",
|
||||
prompt: "Run tests for user service and fix failures"
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation Agents
|
||||
|
||||
### doc-generator
|
||||
|
||||
**Purpose**: Documentation generation for technical docs, API references, and code comments
|
||||
|
||||
**Capabilities**:
|
||||
- Synthesizes context from multiple sources
|
||||
- Produces comprehensive documentation
|
||||
- Flow_control-based task execution
|
||||
|
||||
**Tools**: `Read`, `Write`, `Bash`, `Grep`, `Glob`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "doc-generator",
|
||||
prompt: "Generate API documentation for REST endpoints"
|
||||
})
|
||||
```
|
||||
|
||||
### memory-bridge
|
||||
|
||||
**Purpose**: Documentation update coordinator for complex projects
|
||||
|
||||
**Capabilities**:
|
||||
- Orchestrates parallel CLAUDE.md updates
|
||||
- Uses ccw tool exec update_module_claude
|
||||
- Processes every module path
|
||||
|
||||
**Tools**: `Bash`, `ccw tool exec`, `TodoWrite`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "memory-bridge",
|
||||
prompt: "Update CLAUDE.md for all modules"
|
||||
})
|
||||
```
|
||||
|
||||
### ui-design-agent
|
||||
|
||||
**Purpose**: UI design token management and prototype generation
|
||||
|
||||
**Capabilities**:
|
||||
- W3C Design Tokens Format compliance
|
||||
- State-based component definitions (default, hover, focus, active, disabled)
|
||||
- Complete component library coverage (12+ interactive components)
|
||||
- Animation-component state integration
|
||||
- WCAG AA compliance validation
|
||||
- Token-driven prototype generation
|
||||
|
||||
**Tools**: `Read`, `Write`, `Edit`, `Bash`, `mcp__exa__web_search_exa`, `mcp__exa__get_code_context_exa`
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "ui-design-agent",
|
||||
prompt: "Generate design tokens for dashboard components"
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Orchestration Patterns
|
||||
|
||||
Agents can be combined using these orchestration patterns:
|
||||
|
||||
### Inheritance Chain
|
||||
|
||||
Agent extends another agent's capabilities:
|
||||
|
||||
| Parent | Child | Extension |
|
||||
|--------|-------|-----------|
|
||||
| code-developer | tdd-developer | Adds TDD Red-Green-Refactor workflow, test-fix cycle |
|
||||
| action-planning-agent | test-action-planning-agent | Adds L0-L3 test layers, AI issue detection |
|
||||
|
||||
### Sequential Delegation
|
||||
|
||||
Agent calls another agent for preprocessing:
|
||||
|
||||
| Caller | Callee | Purpose |
|
||||
|--------|--------|---------|
|
||||
| cli-discuss-agent | cli-explore-agent | Codebase discovery before discussion |
|
||||
| cli-execution-agent | cli-explore-agent | Discovery before CLI command execution |
|
||||
|
||||
### Queue Formation
|
||||
|
||||
Agent collects outputs from multiple agents and orders them:
|
||||
|
||||
| Collector | Source | Purpose |
|
||||
|-----------|--------|---------|
|
||||
| issue-queue-agent | issue-plan-agent | Collect solutions, detect conflicts, produce ordered queue |
|
||||
|
||||
### Context Loading Chain
|
||||
|
||||
Agent generates context packages used by execution agents:
|
||||
|
||||
| Context Provider | Consumer | Purpose |
|
||||
|------------------|----------|---------|
|
||||
| context-search-agent | code-developer | Provides brainstorming context packages |
|
||||
| test-context-search-agent | test-fix-agent | Provides test context packages |
|
||||
|
||||
### Quality Gate Chain
|
||||
|
||||
Sequential execution through validation gates:
|
||||
|
||||
```
|
||||
code-developer (IMPL-001)
|
||||
→ test-fix-agent (IMPL-001.3 validation)
|
||||
→ test-fix-agent (IMPL-001.5 review)
|
||||
→ test-fix-agent (IMPL-002 fix)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Selection Guide
|
||||
|
||||
| Task | Recommended Agent | Alternative |
|
||||
|------|------------------|-------------|
|
||||
| Explore codebase | cli-explore-agent | context-search-agent |
|
||||
| Implement code | code-developer | tdd-developer |
|
||||
| Debug issues | debug-explore-agent | cli-execution-agent |
|
||||
| Plan implementation | cli-planning-agent | action-planning-agent |
|
||||
| Generate tests | test-action-planning-agent | test-fix-agent |
|
||||
| Review code | test-fix-agent | doc-generator |
|
||||
| Create documentation | doc-generator | ui-design-agent |
|
||||
| UI design | ui-design-agent | - |
|
||||
| Manage issues | issue-plan-agent | issue-queue-agent |
|
||||
|
||||
---
|
||||
|
||||
## Tool Dependencies
|
||||
|
||||
### Core Tools
|
||||
|
||||
All agents have access to: `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`
|
||||
|
||||
### MCP Tools
|
||||
|
||||
Specialized agents use: `mcp__ace-tool__search_context`, `mcp__ccw-tools__smart_search`, `mcp__ccw-tools__edit_file`, `mcp__ccw-tools__write_file`, `mcp__ccw-tools__codex_lens`, `mcp__exa__web_search_exa`
|
||||
|
||||
### CLI Tools
|
||||
|
||||
CLI-capable agents use: `ccw cli`, `ccw tool exec`
|
||||
|
||||
### Workflow Tools
|
||||
|
||||
Coordinating agents use: `Task`, `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskOutput`, `TodoWrite`, `SendMessage`
|
||||
|
||||
::: info See Also
|
||||
- [Agents Overview](./index.md) - Agent system introduction
|
||||
- [Custom Agents](./custom.md) - Create custom agents
|
||||
- [Team Skills](../skills/core-skills.md#team-skills) - Multi-agent team skills
|
||||
:::
|
||||
263
docs/agents/custom.md
Normal file
263
docs/agents/custom.md
Normal file
@@ -0,0 +1,263 @@
|
||||
# Custom Agents
|
||||
|
||||
Guide to creating and configuring custom CCW agents.
|
||||
|
||||
## Agent Structure
|
||||
|
||||
```
|
||||
~/.claude/agents/my-agent/
|
||||
├── AGENT.md # Agent definition
|
||||
├── index.ts # Agent logic
|
||||
├── tools/ # Agent-specific tools
|
||||
└── examples/ # Usage examples
|
||||
```
|
||||
|
||||
## Creating an Agent
|
||||
|
||||
### 1. Define Agent
|
||||
|
||||
Create `AGENT.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-agent
|
||||
type: development
|
||||
version: 1.0.0
|
||||
capabilities: [react, typescript, testing]
|
||||
---
|
||||
|
||||
# My Custom Agent
|
||||
|
||||
Specialized agent for React component development with TypeScript.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Generate React components with hooks
|
||||
- TypeScript type definitions
|
||||
- Vitest testing setup
|
||||
- Tailwind CSS styling
|
||||
|
||||
## Usage
|
||||
|
||||
\`\`\`javascript
|
||||
Task({
|
||||
subagent_type: "my-agent",
|
||||
prompt: "Create a user profile component"
|
||||
})
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 2. Implement Agent Logic
|
||||
|
||||
Create `index.ts`:
|
||||
|
||||
```typescript
|
||||
import type { AgentContext, AgentResult } from '@ccw/types'
|
||||
|
||||
export async function execute(
|
||||
prompt: string,
|
||||
context: AgentContext
|
||||
): Promise<AgentResult> {
|
||||
// Analyze request
|
||||
const intent = analyzeIntent(prompt)
|
||||
|
||||
// Execute based on intent
|
||||
switch (intent.type) {
|
||||
case 'generate-component':
|
||||
return await generateComponent(intent.options)
|
||||
case 'add-tests':
|
||||
return await addTests(intent.options)
|
||||
default:
|
||||
return await handleGeneral(prompt)
|
||||
}
|
||||
}
|
||||
|
||||
function analyzeIntent(prompt: string) {
|
||||
// Parse user intent from prompt
|
||||
// Return structured intent object
|
||||
}
|
||||
```
|
||||
|
||||
## Agent Capabilities
|
||||
|
||||
### Code Generation
|
||||
|
||||
```typescript
|
||||
async function generateComponent(options: ComponentOptions) {
|
||||
return {
|
||||
files: [
|
||||
{
|
||||
path: 'src/components/UserProfile.tsx',
|
||||
content: generateReactComponent(options)
|
||||
},
|
||||
{
|
||||
path: 'src/components/UserProfile.test.tsx',
|
||||
content: generateTests(options)
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Analysis
|
||||
|
||||
```typescript
|
||||
async function analyzeCodebase(context: AgentContext) {
|
||||
const files = await context.filesystem.read('src/**/*.ts')
|
||||
const patterns = identifyPatterns(files)
|
||||
return {
|
||||
patterns,
|
||||
recommendations: generateRecommendations(patterns)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```typescript
|
||||
async function generateTests(options: TestOptions) {
|
||||
return {
|
||||
framework: 'vitest',
|
||||
files: [
|
||||
{
|
||||
path: `${options.file}.test.ts`,
|
||||
content: generateTestCode(options)
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Agent Tools
|
||||
|
||||
Agents can define custom tools:
|
||||
|
||||
```typescript
|
||||
export const tools = {
|
||||
'my-tool': {
|
||||
description: 'My custom tool',
|
||||
parameters: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
input: { type: 'string' }
|
||||
}
|
||||
},
|
||||
execute: async (params) => {
|
||||
// Tool implementation
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Agent Communication
|
||||
|
||||
Agents communicate via message bus:
|
||||
|
||||
```typescript
|
||||
// Send message to another agent
|
||||
await context.messaging.send({
|
||||
to: 'tester',
|
||||
type: 'task-complete',
|
||||
data: { files: generatedFiles }
|
||||
})
|
||||
|
||||
// Receive messages
|
||||
context.messaging.on('task-complete', async (message) => {
|
||||
if (message.from === 'executor') {
|
||||
await startTesting(message.data.files)
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## Agent Configuration
|
||||
|
||||
Configure agents in `~/.claude/agents/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"my-agent": {
|
||||
"enabled": true,
|
||||
"priority": 10,
|
||||
"capabilities": {
|
||||
"frameworks": ["react", "vue"],
|
||||
"languages": ["typescript", "javascript"],
|
||||
"tools": ["vitest", "playwright"]
|
||||
},
|
||||
"limits": {
|
||||
"maxFiles": 100,
|
||||
"maxSize": "10MB"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Agent Best Practices
|
||||
|
||||
### 1. Clear Purpose
|
||||
|
||||
Define specific, focused capabilities:
|
||||
|
||||
```markdown
|
||||
# Good: Focused
|
||||
name: react-component-agent
|
||||
purpose: Generate React components with TypeScript
|
||||
|
||||
# Bad: Too broad
|
||||
name: fullstack-agent
|
||||
purpose: Handle everything
|
||||
```
|
||||
|
||||
### 2. Tool Selection
|
||||
|
||||
Use appropriate tools for tasks:
|
||||
|
||||
```typescript
|
||||
// File operations
|
||||
context.filesystem.read(path)
|
||||
context.filesystem.write(path, content)
|
||||
|
||||
// Code analysis
|
||||
context.codebase.search(query)
|
||||
context.codebase.analyze(pattern)
|
||||
|
||||
// Communication
|
||||
context.messaging.send(to, type, data)
|
||||
```
|
||||
|
||||
### 3. Error Handling
|
||||
|
||||
```typescript
|
||||
try {
|
||||
const result = await executeTask(prompt)
|
||||
return { success: true, result }
|
||||
} catch (error) {
|
||||
return {
|
||||
success: false,
|
||||
error: error.message,
|
||||
recovery: suggestRecovery(error)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Agents
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect } from 'vitest'
|
||||
import { execute } from '../index'
|
||||
|
||||
describe('my-agent', () => {
|
||||
it('should generate component', async () => {
|
||||
const result = await execute(
|
||||
'Create a UserCard component',
|
||||
mockContext
|
||||
)
|
||||
expect(result.success).toBe(true)
|
||||
expect(result.files).toHaveLength(2) // component + test
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
::: info See Also
|
||||
- [Built-in Agents](./builtin.md) - Pre-configured agents
|
||||
- [Agents Overview](./index.md) - Agent system introduction
|
||||
:::
|
||||
315
docs/agents/index.md
Normal file
315
docs/agents/index.md
Normal file
@@ -0,0 +1,315 @@
|
||||
# Agents
|
||||
|
||||
CCW provides specialized agents for different development workflows.
|
||||
|
||||
## What are Agents?
|
||||
|
||||
Agents are specialized AI assistants with specific expertise and tools for different aspects of software development. They are invoked via the `Task` tool in skills and workflows.
|
||||
|
||||
## Built-in Agents
|
||||
|
||||
### Execution Agents
|
||||
|
||||
#### code-developer
|
||||
|
||||
Pure code execution agent for implementing programming tasks and writing tests.
|
||||
|
||||
**Expertise:**
|
||||
- Feature implementation
|
||||
- Code generation and modification
|
||||
- Test writing
|
||||
- Bug fixes
|
||||
- All programming languages and frameworks
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "code-developer",
|
||||
prompt: "Implement user authentication API",
|
||||
run_in_background: false
|
||||
})
|
||||
```
|
||||
|
||||
#### tdd-developer
|
||||
|
||||
TDD-aware execution agent supporting Red-Green-Refactor workflow.
|
||||
|
||||
**Expertise:**
|
||||
- Test-first development
|
||||
- Red-Green-Refactor cycle
|
||||
- Test-driven implementation
|
||||
- Refactoring with test safety
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "tdd-developer",
|
||||
prompt: "Execute TDD task IMPL-1 with test-first development",
|
||||
run_in_background: false
|
||||
})
|
||||
```
|
||||
|
||||
#### test-fix-agent
|
||||
|
||||
Executes tests, diagnoses failures, and fixes code until tests pass.
|
||||
|
||||
**Expertise:**
|
||||
- Test execution and analysis
|
||||
- Failure diagnosis
|
||||
- Automated fixing
|
||||
- Iterative test-fix cycles
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "test-fix-agent",
|
||||
prompt: "Run tests and fix any failures",
|
||||
run_in_background: false
|
||||
})
|
||||
```
|
||||
|
||||
#### universal-executor
|
||||
|
||||
Universal executor for general-purpose execution tasks.
|
||||
|
||||
**Expertise:**
|
||||
- General task execution
|
||||
- Document generation
|
||||
- Multi-step workflows
|
||||
- Cross-domain tasks
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "universal-executor",
|
||||
prompt: "Generate documentation for the API",
|
||||
run_in_background: false
|
||||
})
|
||||
```
|
||||
|
||||
### Analysis Agents
|
||||
|
||||
#### context-search-agent
|
||||
|
||||
Intelligent context collector for development tasks.
|
||||
|
||||
**Expertise:**
|
||||
- Codebase exploration
|
||||
- Pattern discovery
|
||||
- Context gathering
|
||||
- File relationship analysis
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "context-search-agent",
|
||||
prompt: "Gather context for implementing user authentication",
|
||||
run_in_background: false
|
||||
})
|
||||
```
|
||||
|
||||
#### debug-explore-agent
|
||||
|
||||
Hypothesis-driven debugging agent with NDJSON logging.
|
||||
|
||||
**Expertise:**
|
||||
- Root cause analysis
|
||||
- Hypothesis generation and testing
|
||||
- Debug logging
|
||||
- Systematic troubleshooting
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "debug-explore-agent",
|
||||
prompt: "Debug the WebSocket connection timeout issue",
|
||||
run_in_background: false
|
||||
})
|
||||
```
|
||||
|
||||
#### cli-explore-agent
|
||||
|
||||
CLI-based code exploration agent.
|
||||
|
||||
**Expertise:**
|
||||
- CLI code analysis
|
||||
- External tool integration
|
||||
- Shell-based exploration
|
||||
- Command-line workflows
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
prompt: "Explore codebase for authentication patterns",
|
||||
run_in_background: false
|
||||
})
|
||||
```
|
||||
|
||||
### Planning Agents
|
||||
|
||||
#### action-planning-agent
|
||||
|
||||
Creates implementation plans based on requirements and control flags.
|
||||
|
||||
**Expertise:**
|
||||
- Task breakdown
|
||||
- Implementation planning
|
||||
- Dependency analysis
|
||||
- Priority sequencing
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "action-planning-agent",
|
||||
prompt: "Create implementation plan for OAuth2 authentication",
|
||||
run_in_background: false
|
||||
})
|
||||
```
|
||||
|
||||
#### issue-plan-agent
|
||||
|
||||
Planning agent specialized for issue resolution.
|
||||
|
||||
**Expertise:**
|
||||
- Issue analysis
|
||||
- Solution planning
|
||||
- Task generation
|
||||
- Impact assessment
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "issue-plan-agent",
|
||||
prompt: "Plan solution for GitHub issue #123",
|
||||
run_in_background: false
|
||||
})
|
||||
```
|
||||
|
||||
### Specialized Agents
|
||||
|
||||
#### team-worker
|
||||
|
||||
Unified team worker agent for role-based collaboration.
|
||||
|
||||
**Expertise:**
|
||||
- Multi-role execution (analyst, writer, planner, executor, tester, reviewer)
|
||||
- Team coordination
|
||||
- Lifecycle management
|
||||
- Inter-role communication
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "team-worker",
|
||||
description: "Spawn executor worker",
|
||||
team_name: "my-team",
|
||||
name: "executor",
|
||||
run_in_background: true,
|
||||
prompt: "## Role Assignment\nrole: executor\n..."
|
||||
})
|
||||
```
|
||||
|
||||
#### doc-generator
|
||||
|
||||
Documentation generation agent.
|
||||
|
||||
**Expertise:**
|
||||
- API documentation
|
||||
- User guides
|
||||
- Technical writing
|
||||
- Diagram generation
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "doc-generator",
|
||||
prompt: "Generate documentation for the REST API",
|
||||
run_in_background: false
|
||||
})
|
||||
```
|
||||
|
||||
## Agent Categories
|
||||
|
||||
| Category | Agents | Purpose |
|
||||
|----------|--------|---------|
|
||||
| **Execution** | code-developer, tdd-developer, test-fix-agent, universal-executor | Implement code and run tasks |
|
||||
| **Analysis** | context-search-agent, debug-explore-agent, cli-explore-agent | Explore and analyze code |
|
||||
| **Planning** | action-planning-agent, issue-plan-agent, cli-planning-agent | Create plans and strategies |
|
||||
| **Specialized** | team-worker, doc-generator, ui-design-agent | Domain-specific tasks |
|
||||
|
||||
## Agent Communication
|
||||
|
||||
Agents can communicate and coordinate with each other:
|
||||
|
||||
```javascript
|
||||
// Agent sends message
|
||||
SendMessage({
|
||||
type: "message",
|
||||
recipient: "tester",
|
||||
content: "Feature implementation complete, ready for testing"
|
||||
})
|
||||
|
||||
// Agent receives message via system
|
||||
```
|
||||
|
||||
## Team Workflows
|
||||
|
||||
Multiple agents can work together on complex tasks:
|
||||
|
||||
```
|
||||
[analyst] -> RESEARCH (requirements analysis)
|
||||
|
|
||||
v
|
||||
[writer] -> DRAFT (specification creation)
|
||||
|
|
||||
v
|
||||
[planner] -> PLAN (implementation planning)
|
||||
|
|
||||
+--[executor] -> IMPL (code implementation)
|
||||
| |
|
||||
| v
|
||||
+-----------[tester] -> TEST (testing)
|
||||
|
|
||||
v
|
||||
[reviewer] -> REVIEW (code review)
|
||||
```
|
||||
|
||||
## Using Agents
|
||||
|
||||
### Via Task Tool
|
||||
|
||||
```javascript
|
||||
// Foreground execution
|
||||
Task({
|
||||
subagent_type: "code-developer",
|
||||
prompt: "Implement user dashboard",
|
||||
run_in_background: false
|
||||
})
|
||||
|
||||
// Background execution
|
||||
Task({
|
||||
subagent_type: "code-developer",
|
||||
prompt: "Implement user dashboard",
|
||||
run_in_background: true
|
||||
})
|
||||
```
|
||||
|
||||
### Via Team Skills
|
||||
|
||||
Team skills automatically coordinate multiple agents:
|
||||
|
||||
```javascript
|
||||
Skill({
|
||||
skill: "team-lifecycle",
|
||||
args: "Build user authentication system"
|
||||
})
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
Agent behavior is configured via role-spec files in team workflows:
|
||||
|
||||
```markdown
|
||||
---
|
||||
role: executor
|
||||
prefix: IMPL
|
||||
inner_loop: true
|
||||
subagents: [explore]
|
||||
---
|
||||
```
|
||||
|
||||
::: info See Also
|
||||
- [Skills](../skills/) - Reusable skill library
|
||||
- [Workflows](../workflows/) - Orchestration system
|
||||
- [Teams](../workflows/teams.md) - Team workflow reference
|
||||
:::
|
||||
Reference in New Issue
Block a user