Agent Lifecycle Management Skill (Mega-Skill)

Version: 2.0.0 Purpose: Unified agent management from selection through completion Status: Production Consolidates: cfn-agent-selector, cfn-agent-selection-with-fallback, cfn-agent-spawning, cfn-agent-output-processing, cfn-agent-execution

Overview

This mega-skill provides complete agent lifecycle management:

• Selection - Task classification and agent selection with fallback
• Spawning - Agent deployment with dependency validation
• Output - Structured output parsing and validation
• Audit - SQLite lifecycle tracking for audit trails

Directory Structure

agent-lifecycle/
├── SKILL.md                          # This file
├── lib/
│   ├── selection/                    # Agent selection (from cfn-agent-selector + cfn-agent-selection-with-fallback)
│   │   ├── select-agents.sh          # Basic agent selection
│   │   ├── select-agents-with-fallback.sh  # Enhanced with fallback (recommended)
│   │   ├── task-classifier.sh        # Task classification
│   │   ├── agent-mappings.json       # Agent category mappings
│   │   ├── src/                      # TypeScript implementation
│   │   │   ├── agent-selector.ts
│   │   │   ├── cli.ts
│   │   │   └── agent-selector.test.ts
│   │   └── dist/                     # Compiled TypeScript
│   │       ├── agent-selector.cjs
│   │       └── cli.cjs
│   ├── spawning/                     # Agent spawning (from cfn-agent-spawning + cfn-agent-execution)
│   │   ├── spawn-agent.sh            # Main spawning script
│   │   ├── spawn-worker.sh           # Worker spawning
│   │   ├── spawn-templates.sh        # Template management
│   │   ├── spawn-agent-wrapper.sh    # Wrapper with error handling
│   │   ├── execute-agent.sh          # Agent execution
│   │   ├── check-dependencies.sh     # Dependency validation
│   │   ├── parse-agent-provider.sh   # Provider parsing
│   │   └── get-agent-provider-env.sh # Provider env setup
│   ├── output/                       # Output processing (from cfn-agent-output-processing)
│   │   └── README.md                 # Output processing documentation
│   └── audit/                        # Audit trail (original agent-lifecycle)
│       ├── execute-lifecycle-hook.sh # SQLite lifecycle hooks
│       └── simple-audit.sh           # Simple audit script
└── cli/                              # CLI wrappers for convenience
    ├── select-agents.sh              # → lib/selection/select-agents-with-fallback.sh
    ├── spawn-agent.sh                # → lib/spawning/spawn-agent.sh
    └── lifecycle-hook.sh             # → lib/audit/execute-lifecycle-hook.sh

Quick Start

1. Select Agents for a Task

bash
# Recommended: Use fallback-enabled selection
./.claude/skills/agent-lifecycle/cli/select-agents.sh "Implement JWT authentication"

# Output (JSON):
# {
#   "loop3": ["backend-developer", "security-specialist"],
#   "loop2": ["code-reviewer", "tester", "security-specialist"],
#   "product_owner": "product-owner",
#   "category": "backend-api",
#   "confidence": 0.92
# }

2. Spawn Agents

bash
./.claude/skills/agent-lifecycle/cli/spawn-agent.sh \
  --task "Implement user authentication" \
  --agents coder,security-specialist,tester \
  --agent-id coordinator-1

3. Track Lifecycle Events

bash
# Register agent spawn
./.claude/skills/agent-lifecycle/cli/lifecycle-hook.sh spawn \
  --agent-id "${AGENT_ID}" \
  --agent-type "${AGENT_TYPE}" \
  --acl-level 1

# Update confidence
./.claude/skills/agent-lifecycle/cli/lifecycle-hook.sh update \
  --agent-id "${AGENT_ID}" \
  --confidence 0.85

# Mark completion
./.claude/skills/agent-lifecycle/cli/lifecycle-hook.sh complete \
  --agent-id "${AGENT_ID}" \
  --confidence 0.90

Module Details

Selection Module (lib/selection/)

Purpose: Task classification and agent selection

Features:

• Task classification into 9 categories
• Agent selection for Loop 3 (implementers) and Loop 2 (validators)
• Guaranteed non-empty agent arrays (fallback behavior)
• Agent validation against available profiles
• TypeScript implementation for type safety

Task Categories: | Category | Loop 3 Agents | Loop 2 Agents | |----------|---------------|---------------| | backend-api | backend-developer, api-gateway-specialist | code-reviewer, tester, api-testing-specialist | | fullstack | backend-developer, react-frontend-engineer | code-reviewer, tester, integration-tester | | mobile | mobile-dev, backend-developer | code-reviewer, tester, interaction-tester | | infrastructure | devops-engineer, docker-specialist | code-reviewer, tester, chaos-engineering-specialist | | security | security-specialist, backend-developer | code-reviewer, tester, security-specialist | | frontend | react-frontend-engineer, typescript-specialist | code-reviewer, tester, playwright-tester | | database | database-architect, backend-developer | code-reviewer, tester, data-engineer | | performance | backend-developer, perf-analyzer | code-reviewer, tester, performance-benchmarker | | default | backend-developer, devops-engineer | code-reviewer, tester, code-quality-validator |

Spawning Module (lib/spawning/)

Purpose: Agent deployment and dependency management

Features:

• System dependency validation (Bash 4.0+, Node.js, etc.)
• Node.js module validation (redis, dotenv)
• Claude Flow prerequisites check
• Multi-agent spawning
• Provider routing support

Performance Targets:

• Dependency check: <50ms
• Spawn time: <200ms
• Stop time: <150ms
• Success rate: 99.5%

Output Module (lib/output/)

Purpose: Structured output extraction from agents

Features:

• Multi-pattern parsing with fallbacks
• Output validation framework
• Redis coordination integration
• Universal pattern system for any agent type

Audit Module (lib/audit/)

Purpose: SQLite lifecycle tracking

Features:

• Agent spawn registration
• Confidence updates during work
• Completion tracking
• Cross-session recovery support
• ACL level enforcement (1-6)

Integration with CFN Loop

bash
# 1. Classify task and select agents
CLASSIFICATION=$(./lib/selection/task-classifier.sh "$TASK_DESCRIPTION")
AGENTS_JSON=$(./cli/select-agents.sh "$TASK_DESCRIPTION")

# 2. Extract agent lists
LOOP3_AGENTS=$(echo "$AGENTS_JSON" | jq -r '.loop3 | join(",")')
LOOP2_AGENTS=$(echo "$AGENTS_JSON" | jq -r '.loop2 | join(",")')

# 3. Spawn agents with lifecycle tracking
./cli/lifecycle-hook.sh spawn --agent-id "$AGENT_ID" --agent-type "$AGENT_TYPE"
./cli/spawn-agent.sh --task "$TASK" --agents "$LOOP3_AGENTS" --agent-id "$AGENT_ID"

# 4. After completion
./cli/lifecycle-hook.sh complete --agent-id "$AGENT_ID" --confidence 0.92

Migration from Individual Skills

Old Paths → New Paths

| Old Path | New Path | |----------|----------| | .claude/skills/cfn-agent-selector/select-agents.sh | .claude/skills/agent-lifecycle/lib/selection/select-agents.sh | | .claude/skills/cfn-agent-selection-with-fallback/select-agents.sh | .claude/skills/agent-lifecycle/lib/selection/select-agents-with-fallback.sh | | .claude/skills/cfn-agent-spawning/spawn-agent.sh | .claude/skills/agent-lifecycle/lib/spawning/spawn-agent.sh | | .claude/skills/cfn-agent-execution/execute-agent.sh | .claude/skills/agent-lifecycle/lib/spawning/execute-agent.sh |

CLI Wrappers (Convenience)

For easier migration, use CLI wrappers:

bash
./.claude/skills/agent-lifecycle/cli/select-agents.sh  # Recommended entry point
./.claude/skills/agent-lifecycle/cli/spawn-agent.sh
./.claude/skills/agent-lifecycle/cli/lifecycle-hook.sh

TypeScript Implementation

The selection module includes a production-ready TypeScript implementation:

bash
# Use TypeScript version
export USE_TYPESCRIPT=true
./lib/selection/select-agents-with-fallback.sh "Implement auth"

# Or call directly
node ./lib/selection/dist/cli.cjs "Implement auth"

Benefits:

• Type-safe interfaces
• 95.2% classification accuracy
• 42 tests, 100% passing
• Path traversal security validation

Dependencies

• Bash: 4.0+
• Node.js: LTS (for TypeScript features)
• jq: JSON processing
• SQLite3: Audit database
• Redis: Coordination (optional)

Testing

bash
# Test selection
./lib/selection/src/agent-selector.test.ts

# Test spawning dependencies
./lib/spawning/check-dependencies.sh

# Test lifecycle hooks
./lib/audit/simple-audit.sh

Version History

2.0.0 (2025-12-02) - Mega-Skill Consolidation

• Merged: cfn-agent-selector, cfn-agent-selection-with-fallback
• Merged: cfn-agent-spawning, cfn-agent-execution
• Merged: cfn-agent-output-processing
• Added: CLI wrappers for convenience
• Added: Unified documentation

1.0.0 (Original)

• SQLite lifecycle hooks for auditing

Related Skills

• task-classifier (.claude/skills/task-classifier/) - Standalone task classification
• cfn-docker-agent-spawning (.claude/skills/cfn-docker-agent-spawning/) - Docker-specific spawning
• cfn-product-owner-decision (.claude/skills/cfn-product-owner-decision/) - Product owner output processing