claude-flow-novice 2.18.5 → 2.18.6

package/.claude/skills/cfn-loop-orchestration-v2/lib/orchestrator/SKILL.md

@@ -0,0 +1,418 @@
+---
+name: cfn-loop-orchestration
+description: CFN Loop workflow orchestration - three-loop structure management with gate checks and consensus
+version: 3.1.0
+tags: [orchestration, cfn-loop, workflow, consensus]
+status: production
+---
+
+# CFN Loop Orchestration Skill
+
+## Metadata
+- **Skill ID:** cfn-loop-orchestration
+- **Version:** 3.1.0
+- **Category:** Workflow Orchestration
+- **Dependencies:** redis-coordination, product-owner-decision, agent-output-processing
+- **Maturity:** Production
+- **Last Updated:** 2025-11-20
+- **Implementation:** TypeScript CLI (unified entry point, v1.0.0)
+
+## Implementation Status
+**Active:** TypeScript CLI v1.0.0 - Unified direct entry point
+- **Primary Entry:** `dist/cli/orchestrator-cli.js` (TypeScript, Node.js native)
+- **Core Engine:** `src/orchestrate.ts` compiled to `dist/orchestrate.js`
+- **No Bash Wrappers:** Direct CLI eliminates all bash wrapper overhead
+- **Benefits:** 612 lines of bash eliminated, type safety, direct invocation, native Node.js shebang
+- **Integration:** Coordinator → Direct CLI invocation (no bash wrapper needed)
+
+**Previous Implementation:** Bash wrappers (deprecated but preserved)
+- `orchestrate-wrapper.sh` - Parameter validation wrapper (DEPRECATED)
+- `orchestrate.sh` - Bash routing wrapper (DEPRECATED)
+- `helpers/orchestrate-ts.sh` - TS invocation wrapper (DEPRECATED)
+- Kept for reference, use CLI instead
+- Migration: All callers should use `dist/cli/orchestrator-cli.js`
+
+## Purpose
+Orchestrates the Complete Fail Never (CFN) Loop workflow, managing the three-loop structure:
+- Loop 3 (Primary Swarm - Implementation)
+- Loop 2 (Consensus Validators - Review)
+- Product Owner Decision (Strategic Approval)
+
+## Responsibilities
+1. Coordinate multi-agent CFN Loop execution
+2. Manage gate checks and consensus validation
+3. Handle iteration cycles with feedback injection
+4. Interface with Redis Coordination for agent synchronization
+5. Execute Product Owner decision flow
+6. Enforce dependency ordering (Loop 3 → Loop 2 → PO)
+
+## Interface
+
+### Primary Entry Point (TypeScript CLI)
+```bash
+# Direct Node.js invocation (recommended)
+./dist/cli/orchestrator-cli.js \
+  --task-id <id> \
+  --mode <mvp|standard|enterprise> \
+  --max-iterations <n> \
+  [--loop3-agents <agents>] \
+  [--loop2-agents <agents>] \
+  [--product-owner <agent>] \
+  [--success-criteria <enabled|disabled>]
+
+# Or via node directly
+node ./dist/cli/orchestrator-cli.js --task-id test --mode standard --max-iterations 10
+```
+
+### Parameters (7 arguments)
+**Required:**
+- `--task-id`: Unique identifier for this CFN Loop execution (alphanumeric, hyphens, underscores, max 256 chars)
+- `--mode`: Workflow mode: `mvp`, `standard`, or `enterprise` (determines thresholds)
+- `--max-iterations`: Maximum iteration cycles (1-100, required for parameter validation)
+
+**Optional:**
+- `--loop3-agents`: Comma-separated implementer agent IDs (e.g., `backend-dev,coder`)
+- `--loop2-agents`: Comma-separated validator agent IDs (e.g., `code-reviewer,tester`)
+- `--product-owner`: Agent ID for strategic decision (e.g., `cto-agent`)
+- `--success-criteria`: Validation flag - `enabled`, `disabled`, `true`, `false`, `yes`, `no`, `1`, `0`
+
+### Informational Parameters
+- `--help, -h`: Display usage information
+- `--version, -v`: Display version (1.0.0)
+
+### Return Values & Output
+- Exit Code 0: Success (orchestrator initialized, parameters validated)
+- Exit Code 1: Error (missing required parameters, invalid values, validation failed)
+- Exit Code 130: Interrupted (SIGINT/SIGTERM signal received)
+
+### Output Format
+Initial orchestrator state (JSON):
+```json
+{
+  "taskId": "auth-feature",
+  "mode": "enterprise",
+  "iteration": 0,
+  "currentPhase": "loop3",
+  "completedAgents": {},
+  "failedAgents": {},
+  "startTime": 1763621594885,
+  "lastUpdateTime": 1763621594885
+}
+```
+
+## Usage Examples
+
+### Basic Invocation
+```bash
+./dist/cli/orchestrator-cli.js \
+  --task-id test-task \
+  --mode standard \
+  --max-iterations 10
+```
+
+### Full Configuration
+```bash
+./dist/cli/orchestrator-cli.js \
+  --task-id auth-feature \
+  --mode enterprise \
+  --max-iterations 15 \
+  --loop3-agents backend-dev,coder \
+  --loop2-agents code-reviewer,tester \
+  --product-owner cto-agent \
+  --success-criteria enabled
+```
+
+### With MVP Mode
+```bash
+./dist/cli/orchestrator-cli.js \
+  --task-id quick-task \
+  --mode mvp \
+  --max-iterations 5 \
+  --loop3-agents developer
+```
+
+### Help and Version
+```bash
+# Show help
+./dist/cli/orchestrator-cli.js --help
+
+# Show version
+./dist/cli/orchestrator-cli.js --version
+```
+
+## Helper Scripts
+
+### 1. gate-check.sh
+Validates Loop 3 self-assessment against gate threshold.
+
+**Usage:**
+```bash
+./.claude/skills/cfn-loop-orchestration/helpers/gate-check.sh \
+  --task-id <id> \
+  --agents <agent1,agent2,...> \
+  --threshold <0.0-1.0> \
+  --min-quorum <n|n%|0.n>
+```
+
+**Returns:**
+- Exit 0: Gate passed (broadcast signal to Loop 2)
+- Exit 1: Gate failed (prepare Loop 3 iteration)
+
+### 2. consensus.sh
+Collects and validates Loop 2 consensus scores.
+
+**Usage:**
+```bash
+./.claude/skills/cfn-loop-orchestration/helpers/consensus.sh \
+  --task-id <id> \
+  --agents <agent1,agent2,...> \
+  --threshold <0.0-1.0> \
+  --min-quorum <n|n%|0.n>
+```
+
+**Returns:**
+- Exit 0: Consensus reached
+- Exit 1: Consensus failed
+
+### 3. iteration-manager.sh
+Manages iteration cycles and feedback injection.
+
+**Usage:**
+```bash
+./.claude/skills/cfn-loop-orchestration/helpers/iteration-manager.sh \
+  --task-id <id> \
+  --iteration <n> \
+  --agents <agent1,agent2,...> \
+  --feedback-source <redis-key>
+```
+
+**Returns:**
+- Exit 0: Agents awakened for next iteration
+- Exit 1: Iteration limit exceeded
+
+### 4. deliverable-verifier.sh
+Verifies expected deliverables were created.
+
+**Usage:**
+```bash
+./.claude/skills/cfn-loop-orchestration/helpers/deliverable-verifier.sh \
+  --expected-files <file1,file2,...> \
+  --task-type <keyword-detection>
+```
+
+**Returns:**
+- Exit 0: Deliverables verified
+- Exit 1: Missing deliverables (forced iteration)
+
+### 5. timeout-calculator.sh
+Calculates phase-specific timeouts.
+
+**Usage:**
+```bash
+./.claude/skills/cfn-loop-orchestration/helpers/timeout-calculator.sh \
+  --phase-id <phase-identifier>
+```
+
+**Returns:**
+- Timeout value in seconds (stdout)
+
+## CFN Loop Flow
+
+```
+1. Initialize Swarm Context (Redis)
+   ↓
+2. Spawn Loop 3 Agents (CLI)
+   ↓
+3. Collect Loop 3 Confidence Scores
+   ↓
+4. Gate Check (helpers/gate-check.sh)
+   ├─ PASS → Signal Loop 2 to start
+   └─ FAIL → Wake Loop 3 for iteration N+1 (goto step 2)
+   ↓
+5. Loop 2 Validates Loop 3 Work
+   ↓
+6. Collect Loop 2 Consensus Scores
+   ↓
+7. Verify Deliverables (helpers/deliverable-verifier.sh)
+   ↓
+8. Spawn Product Owner for Decision
+   ↓
+9. Parse Product Owner Decision
+   ├─ PROCEED → Exit success
+   ├─ ITERATE → Wake all agents (goto step 2)
+   └─ ABORT → Exit failure
+```
+
+## Redis Coordination Interface
+
+This skill consumes the following Redis Coordination primitives:
+
+### Context Storage
+```bash
+./.claude/skills/redis-coordination/invoke-waiting-mode.sh report \
+  --task-id "$TASK_ID" \
+  --agent-id "$AGENT_ID" \
+  --confidence <0.0-1.0> \
+  --iteration <n>
+```
+
+### Signal Broadcasting
+```bash
+redis-cli lpush "swarm:${TASK_ID}:gate-passed" "1"
+```
+
+### Agent Waiting/Waking
+```bash
+./.claude/skills/redis-coordination/invoke-waiting-mode.sh wake \
+  --task-id "$TASK_ID" \
+  --agent-id "$AGENT_ID" \
+  --reason <reason> \
+  --iteration <n> \
+  --feedback <feedback-string>
+```
+
+### Result Collection
+```bash
+./.claude/skills/redis-coordination/invoke-waiting-mode.sh collect \
+  --task-id "$TASK_ID" \
+  --agent-ids <comma-separated>
+```
+
+## Mode-Specific Thresholds
+
+| Mode | Gate Threshold | Consensus Threshold | Max Iterations | Validators |
+|------|----------------|---------------------|----------------|------------|
+| MVP | 0.70 | 0.80 | 5 | 2 |
+| Standard | 0.75 | 0.90 | 10 | 3-4 |
+| Enterprise | 0.75 | 0.95 | 15 | 5 |
+
+## Error Handling
+
+### Critical Failures
+- Redis unavailable: Exit immediately with error
+- Agent spawn failure: Retry with exponential backoff
+- Timeout exceeded: Log state, attempt graceful shutdown
+
+### Recoverable Failures
+- Gate check failure: Iterate Loop 3
+- Consensus failure: Iterate all agents
+- Missing deliverables: Force iteration with explicit feedback
+
+## Configuration
+
+### Environment Variables
+- `REDIS_HOST`: Redis server host (default: localhost)
+- `REDIS_PORT`: Redis server port (default: 6379)
+- `CFN_DEBUG`: Enable debug logging (default: 0)
+
+### Redis Keys Used
+- `swarm:{task-id}:epic-context`: Epic-level context
+- `swarm:{task-id}:phase-context`: Phase-level context
+- `swarm:{task-id}:success-criteria`: Acceptance criteria
+- `swarm:{task-id}:agent:{agent-id}:confidence`: Agent confidence score
+- `swarm:{task-id}:agent:{agent-id}:feedback`: Agent-specific feedback
+- `swarm:{task-id}:gate-passed`: Gate pass signal for Loop 2
+- `swarm:{task-id}:{agent-id}:done`: Agent completion signal
+
+## Testing
+
+Run comprehensive test suite:
+```bash
+./.claude/skills/cfn-loop-orchestration/test-cfn-orchestration.sh
+```
+
+Test scenarios:
+1. Gate pass → Consensus pass → PROCEED
+2. Gate fail → Loop 3 iteration
+3. Consensus fail → Full iteration
+4. Missing deliverables → Forced iteration
+5. Max iterations → ABORT
+6. User interrupt → Graceful shutdown
+
+## Migration Guide: Bash Wrappers → TypeScript CLI
+
+### Summary
+The orchestration layer has moved from 612 lines of bash wrapper code to a unified TypeScript CLI entry point. All functionality is preserved with improved type safety and direct invocation.
+
+### Files Affected
+**Deprecated (still available, do not use for new code):**
+- `orchestrate-wrapper.sh` (268 lines) - Parameter validation wrapper
+- `orchestrate.sh` (172 lines) - Bash routing wrapper
+- `helpers/orchestrate-ts.sh` (172 lines) - TypeScript invocation wrapper
+
+**New (use for all new integrations):**
+- `dist/cli/orchestrator-cli.js` - Direct TypeScript CLI entry point
+- `src/cli/orchestrator-cli.ts` - TypeScript source
+
+### Migration Steps
+
+**Before (bash wrapper):**
+```bash
+./orchestrate-wrapper.sh \
+  --task-id auth-feature \
+  --mode standard \
+  --loop3-agents backend-dev,coder \
+  --loop2-agents code-reviewer,tester \
+  --product-owner cto-agent \
+  --max-iterations 10
+```
+
+**After (TypeScript CLI):**
+```bash
+./dist/cli/orchestrator-cli.js \
+  --task-id auth-feature \
+  --mode standard \
+  --loop3-agents backend-dev,coder \
+  --loop2-agents code-reviewer,tester \
+  --product-owner cto-agent \
+  --max-iterations 10
+```
+
+### Key Differences
+1. **Direct Invocation:** No bash wrappers needed, direct Node.js execution
+2. **Parameter Validation:** Happens in TypeScript with proper error messages
+3. **Exit Codes:** Consistent exit code handling (0=success, 1=error, 130=interrupt)
+4. **Type Safety:** All parameters validated with TypeScript types
+5. **Performance:** Eliminates bash subprocess overhead (612 lines eliminated)
+
+### Compatibility Notes
+- All 7 parameters supported
+- Mode enum validation (mvp, standard, enterprise)
+- Max-iterations range validation (1-100)
+- Agent ID sanitization (alphanumeric, hyphens, underscores)
+- Task ID sanitization (alphanumeric, hyphens, underscores, colons, dots)
+- Help and version flags supported
+
+## Legacy Implementation Notes
+
+This skill previously replaced the monolithic `.claude/skills/redis-coordination/orchestrate-cfn-loop.sh` by:
+1. Extracting CFN-specific workflow logic
+2. Delegating Redis operations to redis-coordination skill
+3. Modularizing helper functions into standalone scripts
+4. Simplifying testing and maintenance
+
+**Bash Wrapper Deprecation:**
+Original bash wrappers are preserved for reference but should not be used for new code. The TypeScript CLI provides the same functionality with better performance and type safety.
+
+## Performance Characteristics
+
+- Average execution time: 15-45 minutes (phase-dependent)
+- Zero-token waiting between iterations (Redis BLPOP)
+- Agent spawn time: 5-15 seconds per agent
+- Context storage/retrieval: <100ms per operation
+
+## Success Criteria
+
+This skill is considered successful when:
+1. All existing CFN Loop slash commands work without modification
+2. Test suite achieves 100% pass rate
+3. No regression in iteration management or consensus collection
+4. Clear separation from Redis Coordination primitives
+5. Helper scripts are reusable across different workflow types
+
+## Confidence Score: 0.92
+
+- Architecture: 0.95 (clear separation, modular design)
+- Implementation Risk: 0.88 (complex logic extraction)
+- Testing Coverage: 0.93 (comprehensive test scenarios)
+- Backward Compatibility: 0.92 (existing workflows preserved)

package/.claude/skills/cfn-loop-orchestration-v2/lib/orchestrator/SPAWN_AGENTS_IMPLEMENTATION.md

@@ -0,0 +1,188 @@
+# Agent Spawning Module - TypeScript Implementation
+
+## Summary
+
+Successfully implemented `spawn-agents.ts` TypeScript module as specified in the DEPENDENCY_DIAGRAM.txt (Phase 2 Spawn & Context). This module wraps the CLI agent spawning functionality for orchestrator integration.
+
+## Implementation Details
+
+### File Locations
+- **Module**: `.claude/skills/cfn-loop-orchestration/src/helpers/spawn-agents.ts` (349 LOC)
+- **Tests**: `.claude/skills/cfn-loop-orchestration/tests/spawn-agents.test.ts` (284 LOC)
+
+### Type Definitions
+
+```typescript
+// Agent spawning result
+export interface SpawnResult {
+  agentId: string;
+  agentType: string;
+  success: boolean;
+  pid?: number | undefined;
+  error?: string | undefined;
+}
+
+// Spawn summary with metrics
+export interface SpawnSummary {
+  totalSpawned: number;
+  successCount: number;
+  failureCount: number;
+  results: SpawnResult[];
+  duration: number;
+}
+
+// Configuration interface
+export interface SpawnAgentsConfig {
+  taskId: string;
+  iteration: number;
+  agents: string[];
+  originalContext: string;
+  dryRun?: boolean;
+  logDir?: string;
+  projectRoot?: string;
+}
+```
+
+### Core Functions
+
+#### `spawnAgents(config: SpawnAgentsConfig): Promise<SpawnSummary>`
+Main agent spawning function with full validation and error handling.
+
+**Features:**
+- Agent type validation (loop3/loop2 only)
+- Input sanitization (prevents injection attacks)
+- Unique agent ID generation with iteration and instance tracking
+- CLI command formatting and validation
+- Dry-run mode for testing without execution
+- Comprehensive error handling
+- Duration tracking and result aggregation
+
+**Error Handling:**
+- Validates task ID is non-empty string
+- Validates iteration is non-negative integer
+- Validates agents array is non-empty
+- Validates original context is non-empty string
+- Validates all agent types before spawning
+- Graceful fallback on individual agent spawn failures
+
+#### `spawnLoop3Agents(taskId, iteration, context, dryRun?): Promise<SpawnSummary>`
+Convenience function for spawning single Loop 3 agent.
+
+#### `spawnLoop2Agents(taskId, iteration, context, dryRun?): Promise<SpawnSummary>`
+Convenience function for spawning single Loop 2 agent.
+
+### Helper Functions
+
+- **validateAgentType()**: Ensures agent type is 'loop3' or 'loop2'
+- **sanitizeInput()**: Removes dangerous characters while preserving valid input
+- **generateAgentId()**: Creates unique agent ID with format: `{type}-{iteration}-{instance}`
+- **formatSpawnCommand()**: Builds npx claude-flow-novice agent command array
+- **validateCommandFormat()**: Validates CLI command structure and required parameters
+- **logMessage()**: Logs to both console and file with timestamps
+- **spawnSingleAgent()**: Core spawning logic for individual agents
+
+### Key Design Decisions
+
+1. **Agent Type Validation**: Only 'loop3' and 'loop2' are valid types, preventing misconfiguration
+2. **Input Sanitization**: Uses regex to allow only safe characters: `[a-zA-Z0-9._:,\-]`
+3. **Unique IDs**: Tracks instance counts per agent type for parallel spawning
+4. **Dry-Run Mode**: Full test capability without actual command execution
+5. **Background Spawning**: Uses `spawn()` with `detached: true` and `unref()` for true background execution
+6. **Logging**: Both console output and file logging for debugging
+7. **Graceful Degradation**: Individual agent failures don't halt entire spawn operation
+
+## Test Coverage
+
+### Test Suites (19 tests)
+
+**Agent Type Validation (4 tests)**
+- Accepts loop3 agent type
+- Accepts loop2 agent type
+- Rejects invalid agent type
+- Validates all agents in array
+
+**CLI Command Formatting (3 tests)**
+- Formats valid spawn command for loop3
+- Formats valid spawn command for loop2
+- Sanitizes special characters in input
+
+**Dry-Run Mode (2 tests)**
+- Dry-run mode logs command without executing
+- Dry-run mode succeeds for multiple agents
+
+**Error Handling (4 tests)**
+- Throws error on missing task ID
+- Throws error on invalid iteration
+- Throws error on empty agents array
+- Throws error on missing context
+
+**Spawn Summary (2 tests)**
+- Returns accurate spawn summary
+- Counts failures correctly
+
+**Convenience Functions (2 tests)**
+- spawnLoop3Agents works correctly
+- spawnLoop2Agents works correctly
+
+**Iteration Tracking (2 tests)**
+- Tracks iteration numbers in agent IDs
+- Tracks instance numbers for duplicate agent types
+
+### Test Results
+```
+PASS tests/spawn-agents.test.ts
+✓ 19 passed
+✓ 0 failed
+Time: 7.648s
+```
+
+## TypeScript Compliance
+
+- **Strict Type Checking**: All strict mode flags enabled
+- **No `any` Types**: Full type coverage
+- **Null Safety**: Proper handling of optional properties with exactOptionalPropertyTypes
+- **Type Inference**: Strong inference reduces boilerplate
+- **JSDoc Comments**: Comprehensive documentation for all functions
+
+## Integration Points
+
+This module is designed for integration with:
+- **orchestrator.ts**: Loop 3 and Loop 2 agent spawning during orchestration
+- **context-injector.ts**: Context enrichment with broadcast messages
+- **iteration-manager.ts**: Iteration tracking across spawned agents
+
+## Dependency Analysis
+
+**No External Dependencies**: Module uses only Node.js built-ins:
+- `child_process` (spawn)
+- `path`
+- `fs/promises`
+
+**Phase Dependency**: Unblocks Phase 3 (Main Orchestrator implementation)
+
+## Exit Criteria Status
+
+✅ Agent type validation (loop3/loop2)
+✅ CLI command formatting with proper parameter sequencing
+✅ Dry-run mode for testing
+✅ Format validation before execution
+✅ Error handling for all failure cases
+✅ 19 unit tests covering all scenarios
+✅ Type-safe implementation with strict TypeScript
+✅ Comprehensive logging and metrics
+✅ Duration tracking for performance monitoring
+
+## Next Steps
+
+This module unblocks:
+1. **Phase 3 Orchestrator**: Can now spawn Loop 3 and Loop 2 agents
+2. **Gate Checking**: Can validate agent execution results
+3. **Consensus Validation**: Can spawn validator agents
+4. **Product Owner Decision**: Can integrate decision-making agents
+
+## Notes
+
+- Implementation follows existing code patterns in the orchestration framework
+- Error messages provide clear context for debugging
+- Logging includes timing information for performance optimization
+- Instance counter ensures unique IDs when multiple agents of same type are spawned