proffesor-for-testing__agentic-qe/docs/phase3/agent-template-extraction.md

# Agent Template Extraction - Summary

## Task Completed

Successfully extracted agent template copying logic from `src/cli/commands/init.ts` into a new dedicated module `src/cli/init/agents.ts`.

## What Was Extracted

### Main Export Function

```typescript
export async function copyAgentTemplates(
  config?: FleetConfig,
  force: boolean = false
): Promise<void>
```

**Purpose**: Copy agent templates from agentic-qe package to user's `.claude/agents` directory

**Features**:
- Searches multiple possible package locations (npm, monorepo, local dev)
- Copies all agent definition files (.md) individually
- Handles subagent definitions in `subagents/` folder
- Creates missing agents programmatically if templates not found
- Validates all 18 expected agents are present
- Supports force flag to overwrite existing files
- Provides detailed logging and progress information

### Supporting Functions

1. **`createBasicAgents(force: boolean)`**
   - Creates all 18 agent definitions programmatically
   - Used as fallback when package templates not found
   - Generates complete agent markdown files with Q-learning integration docs

2. **`createMissingAgents(targetPath, existingFiles, force)`**
   - Creates only missing agents to reach expected count of 18
   - Smart detection to avoid duplicates
   - Preserves existing customizations

3. **`countAgentFiles(dirPath: string)`**
   - Counts `.md` files in directory
   - Used for validation and progress reporting

4. **`getAgentDescription(agentName: string)`**
   - Returns detailed description for each of 17 QE agents
   - Maps agent names to capabilities and features

5. **`getAgentSkills(agentName: string)`**
   - Returns array of skills for each agent
   - Maps to Claude Code skill names

6. **`getSkillDocumentation(agentName: string)`**
   - Generates formatted skill documentation
   - Includes descriptions for each skill

## Agent List (18 Total)

### Core Testing (5)
- `qe-test-generator` - AI-powered test generation with sublinear optimization
- `qe-test-executor` - Multi-framework parallel execution
- `qe-coverage-analyzer` - Sublinear gap detection
- `qe-quality-gate` - Risk assessment and validation
- `qe-quality-analyzer` - Metrics analysis and trends

### Performance & Security (2)
- `qe-performance-tester` - Load testing and bottleneck detection
- `qe-security-scanner` - SAST/DAST vulnerability scanning

### Strategic Planning (3)
- `qe-requirements-validator` - BDD scenario generation
- `qe-production-intelligence` - Incident replay and RUM
- `qe-fleet-commander` - Hierarchical fleet coordination

### Deployment (1)
- `qe-deployment-readiness` - Risk assessment for go/no-go

### Advanced Testing (4)
- `qe-regression-risk-analyzer` - Predictive test selection
- `qe-test-data-architect` - Realistic data generation
- `qe-api-contract-validator` - OpenAPI/GraphQL contract testing
- `qe-flaky-test-hunter` - Statistical flaky test detection

### Specialized (2)
- `qe-visual-tester` - Visual regression with AI diff
- `qe-chaos-engineer` - Fault injection and resilience

## Template Features

Each agent template includes:
- **Frontmatter**: name and description
- **Q-Learning Integration**: Complete observability methods
- **Skills Documentation**: Auto-generated from skill map
- **Coordination Protocol**: AQE hooks usage
- **Code Execution Workflows**: WASM-accelerated patterns
- **CLI Integration**: Direct execution examples
- **Memory Coordination**: Namespace documentation
- **Programmatic Usage**: TypeScript examples

## File Locations

### Source (Package)
Searches in order:
1. `dist/cli/init/../../../.claude/agents` (from compiled code)
2. `node_modules/agentic-qe/.claude/agents` (npm install)
3. `../agentic-qe/.claude/agents` (monorepo)

### Target (User Project)
- Main agents: `.claude/agents/*.md`
- Subagents: `.claude/agents/subagents/*.md`

## Copy Strategy

1. **Skip if same file**: Prevents copying to itself in monorepo
2. **Merge strategy**: Only copies missing files by default
3. **Force mode**: Overwrites all files when `force=true`
4. **Validation**: Ensures 18 agents exist, creates missing ones
5. **Subagents**: Automatically copies 8 TDD subagent definitions

## Error Handling

- Logs detailed search paths and results
- Warns when templates not found (falls back to programmatic)
- Defensive null checks on agent names
- Try/catch with error logging
- Continues on individual file failures

## Integration Points

### Current Usage in init.ts
```typescript
// Called during directory structure setup
await this.copyAgentTemplates(force);
```

### After Refactor (Recommended)
```typescript
import { copyAgentTemplates } from './init/agents';

// In InitCommand.setupDirectories()
await copyAgentTemplates(fleetConfig, force);
```

## Next Steps

1. **Update init.ts**: Import and use the new module
2. **Remove old code**: Delete extracted methods from init.ts
3. **Add tests**: Unit tests for the new module
4. **Documentation**: Update developer docs to reference new location

## Benefits of Extraction

✅ **Modularity**: Agent logic separated from init command
✅ **Reusability**: Can be used by other CLI commands
✅ **Testability**: Easier to unit test in isolation
✅ **Maintainability**: Single responsibility principle
✅ **Documentation**: Clear API with JSDoc comments
✅ **Type Safety**: Proper TypeScript types and interfaces

## File Size Comparison

- **Before**: init.ts was 31,567 tokens (too large to read at once)
- **After**:
  - `init/agents.ts`: ~500 lines (focused module)
  - `init.ts`: Will be reduced by ~400 lines

## Dependencies

```typescript
import chalk from 'chalk';        // Console colors
import * as fs from 'fs-extra';   // File operations
import * as path from 'path';     // Path utilities
import { FleetConfig } from '../../types';  // Type definitions
```

Zero external dependencies - all from existing package.json.

## Signature Summary

```typescript
// Main export
export async function copyAgentTemplates(
  config?: FleetConfig,
  force?: boolean
): Promise<void>

// Internal helpers (not exported)
async function createBasicAgents(force: boolean): Promise<void>
async function createMissingAgents(targetPath: string, existingFiles: string[], force: boolean): Promise<void>
async function countAgentFiles(dirPath: string): Promise<number>
function getAgentDescription(agentName: string): string
function getAgentSkills(agentName: string): string[]
function getSkillDocumentation(agentName: string): string
```

---

**Status**: ✅ Complete
**Location**: `/workspaces/agentic-qe-cf/src/cli/init/agents.ts`
**Lines of Code**: ~560 lines
**Test Coverage**: Pending (next phase)