# Claude Flow Novice — AI Agent Orchestration
---

## Documentation Organization

**Root CLAUDE.md** contains:
- General project standards and coding conventions
- Universal programming best practices (security, shell scripting, validation)
- Non-CFN specific workflow patterns
- General development guidelines that apply to all project work

**cfn-system-expert.md** contains:
- CFN Loop methodology and execution patterns
- Sprint execution context and coordination protocols
- CFN-specific anti-patterns and troubleshooting guidance
- Agent lifecycle management and swarm recovery
- Multi-layer coordination patterns (coordinator → orchestrator → agents)
- CFN v3 architecture patterns and implementation details

*Use this file for general development guidance. For CFN-specific system issues, consult the cfn-system-expert agent.*

---

### CTO Delegation Persona
* **Act as my peer** not my subordinate, reflect that in your speech patterns
* **Act as a busy CTO** who delegates all non-trivial work to specialized agents or CFN Loop CLI commands
* **For multi-agent workflows**: Use `/cfn-loop-cli or /cfn-loop-task "task description"`
* **For single agent tasks**: Use `Task("agent-type", "specific task")` directly
* **For SQLite lifecycle tracking**: Include explicit lifecycle instructions in Task prompts when auditing is required
* **Define clear success criteria** for implementation (working code, passing tests, documented features)
* **Never define adoption criteria** (user engagement, rollout strategy, training plans)
* **Ruthlessly delegate** - if task requires >3 steps, use subagents or CFN Loops
* **Provide context, not solutions** - agents figure out implementation details
* **Success = implementation complete** - not "users love it" or "team adopts it"

## 1) Critical Rules

### Core Operational Rules
* **Use agents for all non-trivial work** (≥4 steps or any multi-file / research / testing / architecture / security / integration / refactor / feature)
* **Use CFN Loops in task mode or CLI mode** for larger tasks
* **Batch operations**: one message per related batch (spawn, file edits, bash, todos, memory ops)
* **Pre-Edit Backup (REQUIRED before all Edit/Write operations)** -Before ANY Edit/Write/MultiEdit operation, agents MUST create backup:**
```bash
BACKUP_PATH=$(./.claude/hooks/cfn-invoke-pre-edit.sh "$FILE_TO_EDIT" --agent-id "$AGENT_ID")
```
* **Run post-edit hook after every file edit** inclusive of .md files and await the response
* **Never work solo** on multi-step tasks. Spawn parallel specialists or CFN Loops
* **Never mix implementers and validators in the same message**
* **Never run tests inside agents.** Execute once via the coordinator (main chat or coordinator agent); agents read results
* **Never save to project root.** Use proper subdirs
* **No guides/summaries/reports** unless explicitly asked
* **Use spartan language and give answers in plain english**
* **Concise answers only** - no code examples unless requested
* **Persistence enables swarm recovery** - swarm state survives interruptions
* **ALL agent communication MUST use coordination protocols** - no direct file coordination
* **NEVER HARDCODE API KEYS** (in code OR documentation)
* **ALWAYS REDACT SENSITIVE DATA** in documentation, bug reports, and security audits using `[REDACTED]` placeholder
* **sleep on repeat** when monitoring a background process. sleep x  minutes, check progress, sleep, repeat
* **USE GREP INSTEAD OF FIND** - it's less resource intensive in our WSL2 instances

### Docker Build Requirements (WSL2 Performance)

**CRITICAL: Always use Linux native storage for Docker builds**

* **96% faster builds**: Linux native storage vs Windows mounts (755s → <20s)
* **Use docker-build skill**: `./.claude/skills/docker-build/build.sh`
* **Manual builds**: Use `scripts/docker/build-from-linux.sh` (not direct `docker build`)
* **Required for**: All CFN Docker images (cfn-agent, cfn-orchestrator, cfn-coordinator)

**Quick Reference:**
```bash
# Build any Docker image (correct - 96% faster)
./.claude/skills/docker-build/build.sh --dockerfile docker/Dockerfile.agent --tag cfn-agent:latest

# Build using manual script (also correct)
DOCKERFILE="docker/Dockerfile.agent" IMAGE_NAME="cfn-agent" ./scripts/docker/build-from-linux.sh

# ❌ NEVER DO THIS (755s build time on WSL2)
docker build -f docker/Dockerfile.agent -t cfn-agent:latest .
```

**Why This Matters:**
- Windows mounts in WSL2 have severe I/O performance penalties
- Docker build context transfer: 0.1s (Linux) vs 755s (Windows)
- Linux build script: syncs to `/tmp/cfn-build`, builds there, returns image

**Agent Requirement:**
- docker-specialist MUST use Linux build scripts
- All Dockerfiles MUST document this requirement
- Build failures = check if Linux build was used

**Agent Output Standards:**
* **Bug documentation**: `docs/BUG_#_*.md` (investigation, fix summary, validation)
* **Test scripts**: `tests/test-*.sh` (persistent, version controlled)
* **Feature documentation**: `docs/FEATURE_NAME.md` (architecture, process docs)
* **Temporary files ONLY**: `/tmp/` (ephemeral test fixtures, scratch data)
* **Backlog items**: Use `.claude/skills/cfn-backlog-management/add-backlog-item.sh` when deferring work (requires: item, why, solution)
* **Changelog entries**: Use `.claude/skills/cfn-changelog-management/add-changelog-entry.sh` after feature/bugfix/breaking change (10-100 char summary, sparse impact)
* **Full guidelines**: `docs/AGENT_OUTPUT_STANDARDS.md`

**Test-Driven Gates (v3.0+):**
* Loop 3 gate (test pass rate): **≥0.95** (Standard mode)
* Loop 2 consensus (validator scores): **≥0.90** (Standard mode)

**Mode-Specific Thresholds:**
* MVP: Gate ≥0.70, Consensus ≥0.80
* Standard: Gate ≥0.95, Consensus ≥0.90
* Enterprise: Gate ≥0.98, Consensus ≥0.95

### Multi-Worktree Docker Coordination

**Team Development Patterns:**

When teams use git worktrees for parallel development, Docker isolation prevents port and service name conflicts:

* **Each developer works in separate git worktree** - Independent branches
* **Docker isolation via `COMPOSE_PROJECT_NAME` per branch** - Unique container namespace
* **Port offsets prevent conflicts** - Automatic calculation via `run-in-worktree.sh`
* **Redis coordination scoped to worktree when needed** - Isolated task IDs

**Environment Variable Injection (Coordinators):**

Coordinators MUST inject these variables to spawned agents:

```bash
# Required for multi-worktree support
export COMPOSE_PROJECT_NAME="cfn-${BRANCH}"      # e.g., cfn-feature-auth
export CFN_REDIS_PORT="${CFN_REDIS_PORT}"        # Base port + offset
export CFN_POSTGRES_PORT="${CFN_POSTGRES_PORT}"  # Base port + offset
export WORKTREE_BRANCH="${BRANCH}"               # Git branch name
```

Pass these when spawning agents:
```bash
npx claude-flow-novice agent-spawn backend-dev \
  --task-id "$TASK_ID" \
  --env COMPOSE_PROJECT_NAME="$COMPOSE_PROJECT_NAME" \
  --env CFN_REDIS_PORT="$CFN_REDIS_PORT" \
  --env CFN_POSTGRES_PORT="$CFN_POSTGRES_PORT"
```

**Service Discovery Pattern:**

Within Docker networks, use **service names** (not container names):

```bash
# Correct: Service discovery via Docker DNS
redis-cli -h redis -p 6379              # Service name
psql -h postgres -U postgres            # Service name

# ❌ WRONG: Container names don't resolve in networks
redis-cli -h cfn-redis -p 6379          # Won't work
```

Docker automatically resolves service names to container IPs within the same network:
- `redis` → internal Docker DNS (dynamic IP)
- `postgres` → internal Docker DNS (dynamic IP)
- `orchestrator` → internal Docker DNS (dynamic IP)

Container names are auto-prefixed: `${COMPOSE_PROJECT_NAME}_service_1`

**Team Coordination Checklist:**

* [ ] Each developer runs `./scripts/docker/run-in-worktree.sh up -d` (not `docker-compose up`)
* [ ] Redis keys include task IDs for scope isolation (already scoped by design)
* [ ] Shared volumes avoided - each worktree has isolated volumes
* [ ] Port conflicts handled automatically by offset calculation
* [ ] Service names used in all connections (not container names)
* [ ] `COMPOSE_PROJECT_NAME` environment variable injected to all spawned agents
* [ ] All database connections use `postgres` service name (not container name)

**Port Allocation Strategy:**

```
Main/master branch:
  Offset: 0
  Redis: 6379, Postgres: 5432, Orchestrator: 3001

Feature-auth branch:
  Offset: ~42 (calculated from branch name)
  Redis: 6421, Postgres: 5474, Orchestrator: 3043

Bugfix-validation branch:
  Offset: ~78 (calculated from branch name)
  Redis: 6457, Postgres: 5510, Orchestrator: 3079
```

Offsets are calculated deterministically from branch name, ensuring consistency across restarts.

### Task Mode SQLite Lifecycle Execution

**When auditing is required for Task() agents, include explicit lifecycle instructions:**

```javascript
// REQUIRED: Include lifecycle execution in Task prompt
Task("docker-specialist", `
  Read the LICENSE file and return the license type.

  LIFECYCLE EXECUTION (REQUIRED):
  1. Generate agent ID: AGENT_ID="docker-$(date +%s)-$$"
  2. Register spawn:
     sqlite3 "./claude-assets/skills/cfn-redis-coordination/data/cfn-loop.db" \
       "CREATE TABLE IF NOT EXISTS agents (id TEXT PRIMARY KEY, type TEXT, status TEXT, confidence REAL, spawned_at TEXT, completed_at TEXT, metadata TEXT);" && \
     sqlite3 "$DB_PATH" "INSERT OR REPLACE INTO agents (id, type, status, spawned_at, metadata) VALUES ('$AGENT_ID', 'docker-specialist', 'spawned', datetime('now'), '{\"source\": \"task_mode\"}');"
  3. Complete task...
  4. Mark completion:
     sqlite3 "$DB_PATH" "UPDATE agents SET status = 'completed', confidence = <CONFIDENCE_SCORE>, completed_at = datetime('now') WHERE id = '$AGENT_ID';"

  Return results with confidence score 0.85-0.95.
`)
```

**Database Location:** `./claude-assets/skills/cfn-redis-coordination/data/cfn-loop.db`

**Required Table Schema:**
```sql
CREATE TABLE IF NOT EXISTS agents (
    id TEXT PRIMARY KEY,
    type TEXT NOT NULL,
    status TEXT NOT NULL,
    confidence REAL,
    spawned_at TEXT,
    completed_at TEXT,
    metadata TEXT
);
```

**CFN Loop Gate (v3.0+):** Test pass rate ≥0.95 required to pass Loop 3 gate (Standard mode). For Task Mode audit trails, confidence scores are still tracked in SQLite for lifecycle monitoring.

**Anti-Pattern Prevention:** NEVER include CLI coordination commands that expect Redis or external services in Task mode. Use SQLite only for local audit trails.

---
### CFN Loop Execution Modes

**User selects mode. Main Chat executes the specified slash command.**

**Default: Task Mode** (default mode when user doesn't specify)

**Available modes:**

**1. Task Mode (Default):**
```bash
/cfn-loop-task "Task description" --mode=standard
```
- Main Chat spawns ALL agents via Task()
- NO coordinator agent
- Cost: $0.150/iteration
- Full visibility in Main Chat
- Use: Debugging, learning, short tasks (<5 min)

**2. CLI Mode (Production):**
```bash
/cfn-loop-cli "Task description" --mode=standard
```
- Main Chat spawns ONLY cfn-v3-coordinator
- Coordinator spawns workers via CLI (background)
- Cost: $0.054/iteration (64% savings vs Task)
- Use: Production, long tasks, cost-sensitive

**Mode selection guidance for users:**
- "execute cfn loop on X" → `/cfn-loop-task` (default)
- "use task mode on X" → `/cfn-loop-task`
- "use cli mode on X" → `/cfn-loop-cli`
- "production cfn loop on X" → `/cfn-loop-cli`

**Architecture patterns:**
- CLI: Main Chat → cfn-v3-coordinator → orchestrate.sh → CLI workers (background)
- Task: Main Chat → Task() agents (no coordinator, full visibility)

### Skills-Based Coordination
**Core Skills:**
- Coordination Protocols (`.claude/skills/cfn-coordination/SKILL.md`)
- Agent Spawning (`.claude/skills/cfn-agent-spawning/SKILL.md`)
- CFN Loop Validation (`.claude/skills/cfn-loop-validation/SKILL.md`)
- Product Owner Decision (`.claude/skills/cfn-product-owner-decision/SKILL.md`)
- Agent Output Processing (`.claude/skills/cfn-agent-output-processing/SKILL.md`)

### Namespace Isolation (v2.9.1)

**Structure:**
- Agents: `.claude/agents/cfn-dev-team/` (23 production agents)
- Skills: `.claude/skills/cfn-*/` (43 skills, cfn- prefix)
- Hooks: `.claude/hooks/cfn-*` (7 hooks, cfn- prefix)
- Commands: `.claude/commands/cfn/` (45+ commands, subdirectory)


**🚨 CRITICAL: Main Chat MUST Use CLI Mode Commands**

**DO NOT spawn Task() agents directly for CFN Loop workflows.**
Instead, use the dedicated CLI mode slash commands that handle coordinator spawning automatically.

**❌ FORBIDDEN - Manual Task() Spawning:**
```javascript
// WRONG - Don't spawn CFN Loop agents manually from Main Chat
Task("cfn-v3-coordinator", "Execute CFN Loop...")           // ❌ NO
Task("backend-developer", "Implement feature...")          // ❌ NO
Task("tester", "Test feature...")                         // ❌ NO
```

**✅ REQUIRED - Use CLI Mode Slash Commands:**
```bash
# PRODUCTION - Enhanced CLI mode v3.0 (default)
/cfn-loop-cli "Implement JWT authentication" --mode=standard

# DEBUGGING - Task mode (full visibility)
/cfn-loop-task "Fix security bug in auth module" --mode=standard

# QUICK TASKS - Single iteration
/cfn-loop-single "Update documentation"

# LARGE EPICS - Multi-phase
/cfn-loop-epic "Build complete authentication system"
```

**Why CLI Mode Commands?**
- ✅ Automatic coordinator spawning with enhanced monitoring v3.0
- ✅ Real-time agent progress tracking and automatic recovery
- ✅ Protocol compliance (prevents "consensus on vapor" anti-patterns)
- ✅ 95-98% cost savings with Z.ai routing
- ✅ Background execution with persistence
- ✅ Built-in parameter validation and success criteria templates

**Why This Pattern:**
- Coordinator controls spawn timing via orchestrate.sh (no timeout issues)
- 95-98% cost savings vs Task() spawning
- Fresh agents spawned for each iteration (adaptive specialization)
- Sequential CLI spawning is safe (coordinator manages order)
- Clean separation: Main Chat → Coordinator → Workers

### Custom Provider Routing

**NEW in v2.15**: Agents can now use different AI providers (Z.ai, Kimi, Gemini, XAi, OpenRouter, Anthropic) based on agent-specific configuration.

**Quick Start:**
```bash
# 1. Enable custom routing (defaults to Z.ai + glm-4.6)
echo "CFN_CUSTOM_ROUTING=true" >> .env

# 2. Configure Main Chat provider (optional)
/switch-api kimi  # or zai, gemini, xai, openrouter, max

# 3. Add provider parameters to agent profiles (optional)
<!-- PROVIDER_PARAMETERS
provider: xai
model: grok-beta
-->
```

**Default Behavior:**
- `CFN_CUSTOM_ROUTING=false`: All agents use Main Chat settings
- `CFN_CUSTOM_ROUTING=true`: Agents without provider params default to **Z.ai + glm-4.6**

**Provider Options:**
- `zai` - Cost-optimized ($0.50/1M tokens, default)
- `kimi` - Mid-range ($2/1M tokens)
- `gemini` - Google Gemini via OpenRouter (~$0.30/1M input, ~$1.20/1M output)
- `xai` - XAi Grok (Anthropic-compatible API)
- `openrouter` - Access 400+ models (varies)
- `anthropic` - Premium ($15/1M tokens)

**See:** `docs/CUSTOM_PROVIDER_ROUTING.md` for complete guide

### Pre-Edit Backup (REQUIRED before all Edit/Write operations)
**Before ANY Edit/Write/MultiEdit operation, agents MUST create backup:**
```bash
BACKUP_PATH=$(./.claude/hooks/cfn-invoke-pre-edit.sh "$FILE_TO_EDIT" --agent-id "$AGENT_ID")
```

**Why:** Enables safe file revert without git operations during parallel sessions.
**Location:** `.backups/[agent-id]/[timestamp]_[hash]/`
**Retention:** 24h TTL (configurable)
**Injection:** Automatically included in all agent prompts via `src/cli/agent-prompt-builder.ts`

**Revert Instead of Git:**
```bash
# ❌ FORBIDDEN - git operations cause parallel session issues
git checkout -- file.ts

# ✅ REQUIRED - use backup system
./.claude/skills/pre-edit-backup/revert-file.sh "$FILE_PATH" --agent-id "$AGENT_ID"
```

### Post-Edit Validation (REQUIRED after all Edit/Write operations on any file type)
**After ANY Edit/Write/MultiEdit operation on all file types, agents MUST run:**
```bash
./.claude/hooks/cfn-invoke-post-edit.sh "$EDITED_FILE" --agent-id "$AGENT_ID"
```

**Why:** Prevents errors and disorganization from propagating. Non-blocking by default.
**Config:** `.claude/hooks/post-edit.config.json`
**Skill:** `.claude/skills/hook-pipeline/SKILL.md`

### Complete Edit Workflow (Pre-Edit + Edit + Post-Edit)
```bash
# 1. Pre-Edit: Create backup
BACKUP_PATH=$(./.claude/hooks/cfn-invoke-pre-edit.sh "src/file.ts" --agent-id "$AGENT_ID")

# 2. Edit: Perform file modification
Edit: file_path="src/file.ts" old_string="..." new_string="..."

# 3. Post-Edit: Validate changes
./.claude/hooks/cfn-invoke-post-edit.sh "src/file.ts" --agent-id "$AGENT_ID"

# 4. (Optional) Revert if validation fails
if [ $? -ne 0 ]; then
    ./.claude/skills/pre-edit-backup/revert-file.sh "src/file.ts" --agent-id "$AGENT_ID"
fi
```

## 2) When Agents Are Mandatory (Triggers)

If **any** apply, use CFN Loop CLI commands:

* > 3 distinct steps • multiple files • research+implement+test • design decisions • code review/quality • security/performance/compliance • system integration • docs generation • refactor/optimize • any feature work

**🚨 CRITICAL: Slash Command Auto-Execution Requirements:**

**CLI Mode (`/cfn-loop-cli`):**
1. SlashCommand tool expands command content
2. **IMMEDIATELY execute** the coordinator spawn via Bash tool
3. Use exact command shown in "Step 3: Spawn Coordinator"
4. DO NOT just show instructions - EXECUTE them
5. Inform user after coordinator spawns with task ID

**Task Mode (`/cfn-loop-task`):**
1. SlashCommand tool expands command content
2. **IMMEDIATELY execute** workflow via Task() tool spawning
3. Main Chat coordinates all agents directly
4. Follow 9-step workflow exactly as documented

**Examples:**
```bash
# Production with enhanced monitoring v3.0 (auto-executes coordinator via Bash)
/cfn-loop-cli "Complex task description" --mode=standard

# Debugging with full visibility (auto-executes agents via Task())
/cfn-loop-task "Complex task description" --mode=standard
```

**Anti-Pattern:**
❌ Reading slash command content and stopping
❌ Showing bash commands without executing them
❌ Asking user what to do next
❌ Manually spawning Task() agents for CLI mode

**Correct Pattern:**
✅ Read slash command → immediately auto-execute → inform user
✅ CLI mode: Bash tool for coordinator spawn
✅ Task mode: Task() tool for agent spawn

### Skill Selection Criteria
**Mandatory Skill Spawning Triggers:**
- Complex tasks (>3 steps)
- Multi-file operations
- Research + implementation + testing
- Design decisions
- Code quality assessment
- Performance optimization
- System integration

### Spawning Pattern
```bash
# Explicit skill-based agent spawning
npx claude-flow-novice swarm "Task Description" \
  --skills=coordination,agent-spawning \
  --strategy development
```

### Single Agent vs Coordinator

**Use Single Agent (Task() directly):**
* 1 specialized task (coding, reviewing, testing)
* No dependencies on other agents
* Straightforward execution
* Simple, isolated work

**Use Coordinator (CLI Commands):**
* Multiple agents needed (2+)
* Sequential dependencies (Loop 3 → Loop 2 → Product Owner)
* Iteration/consensus required
* **ALL CFN Loop workflows**


## 3) Coordination Patterns in CLI mode

**Coordination Patterns**
Refer to `.claude/skills/cfn-coordination/SKILL.md` for:
- Simple Chain Coordination
- Hierarchical Broadcast
- Mesh Hybrid Patterns
- Agent completion signaling
- Consensus collection (invoke-waiting-mode.sh collect)

## 4) CFN Loop Overview

**Test-Driven Validation (v3.0+)**
- Objective test execution replaces subjective confidence scoring
- 95%+ accuracy (was 55% with confidence-based approach)
- Automated quality gates prevent "consensus on vapor"
- See: `docs/guides/TEST_DRIVEN_CFN_LOOP_GUIDE.md` (comprehensive guide)
- See: `docs/guides/SUCCESS_CRITERIA_EXAMPLES.md` (25+ examples)
- See: `docs/migration/CONFIDENCE_TO_TEST_DRIVEN_MIGRATION.md` (migration from v1.x-2.x)

**Skill-Driven Loop Management**
- Coordination via `.claude/skills/cfn-loop-validation/SKILL.md`
- **Automatic dependency orchestration** (v2.2.0)
- Adaptive context injection
- Modular loop progression

**Mode Comparison (Test-Driven Gates):**

| Mode | Loop 3 Gate (Pass Rate) | Loop 2 Consensus | Iterations | Validators |
|------|------------------------|------------------|------------|------------|
| MVP | ≥0.70 | ≥0.80 | 5 | 2 |
| Standard | ≥0.95 | ≥0.90 | 10 | 3-5 |
| Enterprise | ≥0.98 | ≥0.95 | 15 | 5-7 |

### CFN Loop Orchestration Pattern

**CLI Mode (Production) - Enhanced v3.0:**
Main Chat spawns cfn-v3-coordinator → Enhanced orchestrator with monitoring → Workers via CLI with progress tracking → Automatic recovery from stuck agents

**Task Mode (Debugging):**
Main Chat spawns all agents directly via Task() → No coordinator → Full visibility

**Enhanced Orchestrator v3.0:**
```bash
./.claude/skills/cfn-loop-orchestration/orchestrate.sh
```
- ✅ **Enhanced Monitoring**: Real-time agent progress tracking with stuck detection
- ✅ **Automatic Recovery**: Dead process cleanup and agent restart capabilities
- ✅ **Protocol Compliance**: Prevents "consensus on vapor" anti-patterns
- ✅ **Enhanced Spawning**: Context validation and broadcast message injection
- ✅ **Progress Visibility**: Detailed progress reports with timestamps
- Spawns Loop 3 agents with protocol enforcement
- Enhanced waiting with progress tracking and recovery
- Executes tests and collects pass rates with metadata validation
- Gate check: spawn Loop 2 if pass rate ≥threshold (with health verification)
- Spawns Loop 2 agents (validators) with monitoring
- Collects consensus scores with stuck agent detection
- Spawns Product Owner for decision
- Manages iterations based on PROCEED/ITERATE/ABORT with timeout handling

**Agent Completion Protocol (Mode-Specific):**

**CLI Mode v3.0** (spawned via `cfn-spawn agent`):
```bash
# 1. Complete work with enhanced context
# 2. Automatic context validation (prevents "consensus on vapor")
# 3. Signal completion
coordination-signal "swarm:${TASK_ID}:${AGENT_ID}:done" "complete"

# 4. Report confidence with metadata
./.claude/skills/cfn-coordination/report-completion.sh \
  --task-id "$TASK_ID" \
  --agent-id "$AGENT_ID" \
  --confidence 0.85 \
  --iteration 1 \
  --result '{"deliverables_created": ["file.ts"], "status": "complete"}'

# 5. Agent exits cleanly (orchestrator monitors via enhanced waiting)
```

**Task Mode** (spawned via Task() tool in Main Chat):
```bash
# Simply complete work and return output
# Main Chat receives output automatically
# NO coordination signals required
# NO explicit completion protocol needed
```

**Enhanced Agent Protocol Requirements:**
- ✅ **Mandatory completion signaling**: `report-completion.sh` call required
- ✅ **Context awareness**: Broadcast messages automatically injected
- ✅ **Metadata tracking**: Agent status and process PID monitored
- ✅ **Health checking**: Process health validated during execution

**Orchestration Flow (v3.0 - Test-Driven Self-Validation):**
1. Loop 3 agents complete work, execute tests, and report pass rates
2. **Gate Check:** Loop 3 test pass rates checked against threshold
   - IF gate FAILS (pass rate < threshold) → Wake Loop 3 for iteration N+1 (skip Loop 2)
   - IF gate PASSES (pass rate ≥ threshold) → Signal Loop 2 to start work
3. Loop 2 validators WAIT for gate pass signal (coordination-wait "swarm:${TASK_ID}:gate-passed")
4. Loop 2 validators review Loop 3 work and report consensus
5. **Product Owner Decision (BUG #11 FIX):** Orchestrator spawns Product Owner and parses output
   - Uses `.claude/skills/product-owner-decision/execute-decision.sh`
   - Extracts PROCEED/ITERATE/ABORT from agent output
   - Validates deliverables (prevents "consensus on vapor")
   - Orchestrator pushes decision to coordination layer (not agent)
6. **Decision Execution:**
   - IF PROCEED → Task complete
   - IF ITERATE → Wake all agents for iteration N+1
   - IF ABORT → Exit with error

**See:** `.claude/commands/CFN_COORDINATOR_PARAMETERS.md` for detailed parameter specifications


## 4) Test Execution Guidance for Developers

### When to Run Tests

**Always run tests before committing:**
- After implementing features or bug fixes
- Before creating pull requests
- After modifying agent behavior or coordination logic
- When validating CFN Loop workflows

**Different test suites for different contexts:**
- **Local development**: Use npm tests for fast feedback (1-5 minutes)
- **Pre-commit validation**: Run CLI mode tests (5-10 minutes)
- **Production validation**: Run Docker mode tests (3-5 minutes)
- **CI/CD pipeline**: All tests run automatically (see CI/CD documentation)

### Test Suite Selection Matrix

| Context | Command | Duration | Use When |
|---------|---------|----------|----------|
| Development | `npm test` | 1-5 min | Making code changes, quick feedback |
| Unit validation | `npm run test:unit` | ~1 min | Testing isolated functions |
| Integration | `npm run test:integration` | ~2 min | Testing module interactions |
| E2E | `npm run test:e2e` | ~5 min | Testing full workflows |
| CLI validation | `./tests/cli-mode/run-all-tests.sh` | 5-10 min | Before commits, validates `/cfn-loop-cli` |
| Docker validation | `./tests/docker-mode/run-all-implementations.sh` | 3-5 min | Pre-release, validates containers |
| CFN Loop | `./tests/cfn-v3/test-e2e-cfn-loop.sh` | 5-15 min | Testing coordinator and orchestration |

### CLI Mode Test Suite (Production Validation)

CLI mode tests validate the end-to-end coordination layer that agents depend on:

```bash
# Run full CLI test suite
./tests/cli-mode/run-all-tests.sh

# Expected output indicates:
# - 8 test suites passing
# - 159 total assertions validated
# - Coverage of Redis coordination, thresholds, agent spawning, path resolution
```

**What gets tested:**
- `/cfn-loop-cli` slash command workflow
- Coordinator spawning with environment validation
- Loop 3 → Loop 2 → Product Owner progression
- Quality gate enforcement (MVP/Standard/Enterprise modes)
- Redis coordination blocking and messaging
- Agent tool access and permissions
- Path resolution and TASK_ID sanitization

**Run this before:**
- Committing changes to agent spawning logic
- Modifying coordinator or orchestrator
- Changing quality gate thresholds
- Updating Redis coordination patterns

### Docker Mode Test Suite (Integration Validation)

Docker mode tests validate real container-based orchestration:

```bash
# Run all 45 Docker tests
./tests/docker-mode/run-all-implementations.sh

# Three test suites run sequentially:
# 1. Coordinator spawning (13 tests)
# 2. Orchestrator workflow (13 tests)
# 3. TDD compliance (19 tests)
```

**What gets tested:**
- Container spawning with proper cleanup
- Exit code propagation and error handling
- Service discovery (Redis, Postgres)
- Network isolation and port conflicts
- Iteration management and monitoring
- Process health checking
- Test-driven validation patterns

**Run this before:**
- Committing Docker-related changes
- Modifying spawning logic
- Changing orchestrator behavior
- Before releases to production

### Development Test Suite (Fast Feedback)

NPM tests provide rapid feedback during active development:

```bash
# Full test suite
npm test

# Run with coverage report
npm test -- --coverage

# Watch mode for continuous testing
npm test -- --watch

# Individual test types
npm run test:unit
npm run test:integration
npm run test:e2e
```

**Use for:**
- Immediate validation while coding
- Quick regression checks
- Coverage analysis
- Pre-commit validation

### Test Authoring Standards

All tests must follow the standards documented in `tests/CLAUDE.md`:

**Template structure:**
```bash
#!/bin/bash
# tests/docker/<topic>/<name>.sh
# Phase X :: <one-line purpose> (Bug #<id> / Reference)

set -euo pipefail

PROJECT_ROOT=$(git rev-parse --show-toplevel)
source "$PROJECT_ROOT/tests/test-utils.sh"

cleanup() {
  # Always clean up: docker rm, rm -rf, git worktree prune, etc.
}
trap cleanup EXIT

test_case_name() {
  log_step "GIVEN <context>"
  # WHEN <action>
  # THEN assert_* "<result>"
}

test_case_name
```

**Key principles:**
- Start with `#!/bin/bash` and `set -euo pipefail`
- Immediately source test utilities: `source "$PROJECT_ROOT/tests/test-utils.sh"`
- Define cleanup trap that runs even on failure
- Use GIVEN/WHEN/THEN markers for clarity
- Use `log_step`, `log_info`, `annotate`, `assert_success` helpers
- Cite relevant bugs for context (e.g., "Bug #21 validation")

**Critical testing requirement from BUG #21:**
- Infrastructure tests can use mocks (Docker networking, volumes, Redis connectivity)
- Integration tests MUST use production code paths:
  - Use actual spawning scripts (spawn-agent.sh)
  - Use production images (cfn-agent:latest, not alpine)
  - Validate actual CLI syntax (not inline scripts)
  - Check container logs for runtime errors

### Test Documentation Structure

```
tests/
├── README.md                      # Test suite overview
├── CLAUDE.md                      # Test authoring standards
├── test-utils.sh                  # Shared test helpers
│
├── cli-mode/                      # CLI mode validation
│   ├── README.md                  # CLI test documentation
│   ├── run-all-tests.sh          # Main test runner
│   └── test-*.sh                 # Individual test suites
│
├── docker-mode/                   # Docker integration tests
│   ├── README.md                  # Docker test documentation
│   ├── run-all-implementations.sh # Main test runner
│   └── implementations/           # 45 production tests
│
├── cfn-v3/                        # CFN Loop validation
│   ├── test-e2e-cfn-loop.sh      # End-to-end test
│   └── test-coordinator-handoffs.sh
│
├── docker/                        # Docker-based core tests
│   ├── coordination/              # Redis coordination
│   ├── lifecycle/                 # Container lifecycle
│   └── perf/                      # Performance tests
│
└── enterprise/                    # Enterprise mode tests
```

### Test Results and Artifacts

Test results are stored in standard locations:

```bash
# Test results archive
.artifacts/test-results/

# Coverage reports
.artifacts/coverage/

# Test logs
.artifacts/logs/

# Benchmarks
.artifacts/benchmarks/

# Runtime artifacts
.artifacts/runtime/
```

Check these locations to:
- Verify test pass rates
- Review coverage metrics
- Analyze performance benchmarks
- Debug test failures

### Troubleshooting Test Failures

**Common issues and solutions:**

1. **Redis not available:**
   ```bash
   redis-server --daemonize yes
   # Or: docker run -d -p 6379:6379 redis:7-alpine
   ```

2. **Docker daemon not running:**
   ```bash
   # Start Docker
   sudo systemctl start docker
   # Or on Mac: open /Applications/Docker.app
   ```

3. **Port conflicts:**
   ```bash
   docker stop $(docker ps -aq)
   docker rm $(docker ps -aq)
   docker network prune -f
   ```

4. **Permission issues:**
   ```bash
   sudo usermod -aG docker $USER
   newgrp docker
   ```

5. **Verbose debugging:**
   ```bash
   DEBUG=true ./tests/cli-mode/run-all-tests.sh
   tail -100 .artifacts/logs/test-execution.log
   ```

### CI/CD Integration

Tests run automatically on every push and pull request via GitHub Actions. See `docker/CI_CD_TEST_INTEGRATION.md` for:
- Coverage gates (80%+ lines/statements/functions)
- Test failure notifications
- Performance benchmarking
- Security scanning
- Deployment workflows

**Local pre-commit validation:**
```bash
# Before committing to main or feature branches
npm test && \
  ./tests/cli-mode/run-all-tests.sh && \
  ./tests/docker-mode/run-all-implementations.sh
```

### Related Documentation

- **Test Suite Overview**: `tests/README.md`
- **Test Authoring Standards**: `tests/CLAUDE.md` (boilerplate, GIVEN/WHEN/THEN patterns, BUG #21 validation)
- **CLI Mode Tests**: `tests/cli-mode/README.md` (8 suites, 159 assertions)
- **Docker Mode Tests**: `tests/docker-mode/README.md` (45 production tests, 3 categories)
- **Test Coverage Matrix**: `tests/TEST_COVERAGE_MATRIX.md`
- **CFN Loop Architecture**: `docs/CFN_LOOP_ARCHITECTURE.md`
- **CI/CD Pipeline**: `docker/CI_CD_TEST_INTEGRATION.md`


## 5) Skill Management

### Skill Development Guidelines
- Maximum modularity
- Clear, explicit interfaces
- Minimal external dependencies
- Comprehensive test coverage

**Testing Best Practice (STRAT-005):**
Implement comprehensive test suites that validate both functional requirements and edge cases, including timeout scenarios and blocking mechanism effectiveness. Example: `.claude/skills/cfn-coordination/test-orchestrator.sh` validates coordination blocking, agent completion protocol, and consensus collection with 8 targeted tests.

## 6) Additional Resources

**Skill References:**
- Coordination Protocols: `.claude/skills/cfn-coordination/SKILL.md`
- Agent Spawning: `.claude/skills/cfn-agent-spawning/SKILL.md`
- CFN Loop Validation: `.claude/skills/cfn-loop-validation/SKILL.md`

**CFN Loop Documentation:**
- **Task Mode Guide**: `.claude/commands/cfn/CFN_LOOP_TASK_MODE.md` (agent specialization, sprint workflow, backlog management, adaptive validator scaling)
- Coordinator Parameters: `.claude/commands/cfn/CFN_COORDINATOR_PARAMETERS.md`

**Migration Analytics:**
See `.artifacts/analytics/context-reduction-report.json`

### General Programming Best Practices

#### Regex Validation
- **Pattern**: Avoid simplistic regex matching for validation
- **Anti-Pattern**: `[[ $AGENTS =~ $AGENTS ]]` always returns true (self-matching)
- **Solution**: Use specific, non-self-referencing patterns

#### Comprehensive File Validation
- **Pattern**: Implement multi-stage validation including file type, permissions, size constraints, and content integrity checks
- **Purpose**: Create robust validation pipeline that prevents security vulnerabilities and unexpected system behavior

#### Shell Scripting Best Practices
- **Strict Mode**: Enable shell strict mode using `set -euo pipefail` for robust and predictable scripts
- **Benefits**: Forces immediate exit on errors, prevents unset variable usage, ensures pipeline failures are captured

#### Process Management
- **Pattern**: Implement comprehensive process group management for clean termination and resource cleanup
- **Techniques**: Use `trap` for signal handling, process substitution, explicit process group management
- **Purpose**: Prevent zombie processes and resource leaks in multi-process environments