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

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

// Called during directory structure setup
await this.copyAgentTemplates(force);

After Refactor (Recommended)

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

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

// 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)