cfn-agent-lifecycle

name: cfn-agent-lifecycle description: "Unified agent management from selection through completion - spawning, execution, output processing. Use when selecting agents for tasks, spawning agents with dependency validation, processing agent outputs, or tracking agent lifecycle events with audit trails." version: 2.0.0 tags: [mega-skill, agent-management, lifecycle, spawning] status: production

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

# 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

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

# 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:

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

# 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

CLI Wrappers (Convenience)

For easier migration, use CLI wrappers:

./.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:

# 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

# 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