creating-workflows-using-claude-flow

What this skill does

# Creating Workflows Skill

Comprehensive guidance for building automated development workflows using claude-flow orchestration, multi-agent coordination, and intelligent verification systems.

## When to Use This Skill

This skill should be triggered when:

- Creating multi-phase development workflows (implementation + verification)
- Building automated CI/CD pipelines with intelligent agents
- Implementing retry loops with context injection
- Setting up verification steps with failure detection
- Orchestrating multiple agents for parallel/sequential task execution
- Creating workflows that need checkpoint recovery
- Implementing silent failure detection (processes that pretend to succeed)
- Building developer experience tooling with dry-run capabilities
- Documenting complex automated workflows
- Migrating manual processes to automated orchestration

## Key Concepts

### Shell Context Independence & jelmore Execution

**Critical Requirement**: Workflow scripts must not depend on interactive shell configuration.

**Why**: Shell aliases and functions don't propagate to subprocess environments (n8n workflows, cron jobs, systemd services).

#### jelmore: Convention-Based LLM Execution Primitive

**jelmore** provides a unified CLI for LLM invocations with shell context independence built-in. Use jelmore instead of calling LLM clients directly when building workflows.

**Why Use jelmore in Workflows**:

- ✅ Shell-context-free (no alias dependencies)
- ✅ Convention over configuration (auto-infer client/MCP servers)
- ✅ Detached Zellij sessions with immediate return
- ✅ Built-in iMi worktree integration
- ✅ Native Bloodbank event publishing
- ✅ Unified interface across all LLM clients

**Location**: `/home/delorenj/code/jelmore`

**Basic Usage in Workflows**:

```bash
# Instead of: npx claude-flow@alpha swarm "$objective" --claude
# Use jelmore with auto-inference:
uv run jelmore execute -p "$objective" --auto

# Instead of: gptme --model $KK "$task"
# Use jelmore with explicit client:
uv run jelmore execute -f task.md --client gptme --model-tier balanced

# For PR review workflows:
uv run jelmore execute --config pr-review.json --var PR_NUMBER=$pr_num --json
```

**Implementation Patterns**:

- Place scripts in `~/.local/bin/` with explicit PATH exports
- Replace aliases with direct command invocations or jelmore CLI
- Use jelmore for LLM invocations (inherits detached Zellij pattern)
- Return session identifiers immediately for observability

**See**:

- `ecosystem-patterns` skill - jelmore architecture and patterns
- `bloodbank-n8n-event-driven-workflows` skill - Event-driven integration
- `/home/delorenj/code/jelmore/CLI.md` - Complete CLI reference

### Multi-Phase Workflows

Workflows split into distinct phases with different execution strategies:

- **Phase 1 (Kickoff)**: Implementation via multi-agent orchestration (parallel execution)
- **Phase 2 (Verification)**: System state validation (sequential execution)
- **Phase N**: Additional phases as needed (testing, deployment, etc.)

### Retry Loops with Context Injection

When Phase 2 fails, retry Phase 1 with failure context:

- Append failure details to context string
- Increment attempt counter
- Enforce max retry limit
- Provide comprehensive failure summary on exhaustion

### Silent Failure Detection

Processes that don't properly report errors require explicit monitoring:

- Log pattern matching (success indicators)
- Error pattern matching (failure indicators)
- Timeout enforcement
- Background process monitoring

### Claude-Flow Integration

**Critical**: `claude-flow@alpha` v2.7.26+ does NOT support `workflow execute` command.

**Available Commands**:

- `swarm <objective>` - Multi-agent coordination with parallel execution
- `sparc <mode>` - SPARC methodology (spec, architect, tdd, integration)
- `stream-chain` - Chain multiple Claude instances with context preservation
- `agent <action>` - Agent management (spawn, list, terminate)

## Quick Reference

### 1. Basic Workflow Script Structure

```bash
#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"

# Colors for output
GREEN='\033[0;32m'
RED='\033[0;31m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

# Parse CLI arguments
TASK_FILE="${PROJECT_ROOT}/TASK.md"
PHASE="all"
MAX_RETRIES=2
RETRY_ENABLED=true
DRY_RUN=false

# Parse flags (--task, --phase, --max-retries, --no-retry, --dry-run, --help)
# Implement usage() function
# Validate inputs
```

### 2. Phase 1: Implementation with jelmore (Recommended)

```bash
run_phase1() {
  local attempt=$1
  local context_override="${2:-$CONTEXT}"

  echo -e "${GREEN}Running Phase 1: Implementation${NC}"

  if [[ $attempt -gt 1 ]]; then
    echo -e "${BLUE}Retry attempt $((attempt - 1))/${MAX_RETRIES}${NC}"
  fi

  # jelmore execution with JSON output
  local jelmore_output
  jelmore_output=$(uv run jelmore execute \
    --file "$TASK_FILE" \
    --auto \
    --json 2>&1)

  local exit_code=$?

  # Parse jelmore response
  if [[ $exit_code -eq 0 ]]; then
    local session_name=$(echo "$jelmore_output" | jq -r '.session_name')
    local execution_id=$(echo "$jelmore_output" | jq -r '.execution_id')
    local log_path=$(echo "$jelmore_output" | jq -r '.log_path')

    echo -e "${GREEN}✓ Execution started${NC}"
    echo "  Session: $session_name"
    echo "  Execution ID: $execution_id"
    echo "  Logs: $log_path"
    echo ""
    echo "  Attach: zellij attach $session_name"

    # Store for later reference
    export JELMORE_SESSION="$session_name"
    export JELMORE_EXECUTION_ID="$execution_id"
    export JELMORE_LOG_PATH="$log_path"
  else
    echo -e "${RED}Error: jelmore execution failed${NC}"
    echo "$jelmore_output"
    return 1
  fi

  return 0
}
```

**Alternative: Phase 1 with Claude-Flow Swarm (Legacy Pattern)**

```bash
run_phase1_legacy() {
  local attempt=$1
  local context_override="${2:-$CONTEXT}"

  echo -e "${GREEN}Running Phase 1: Implementation${NC}"

  if [[ $attempt -gt 1 ]]; then
    echo -e "${BLUE}Retry attempt $((attempt - 1))/${MAX_RETRIES}${NC}"
  fi

  # Read task content
  local task_content
  if [[ -f "$TASK_FILE" ]]; then
    task_content=$(cat "$TASK_FILE")
  else
    echo -e "${RED}Error: Task file not found: $TASK_FILE${NC}"
    return 1
  fi

  # Build objective with context
  local objective="$task_content"
  if [[ -n "$context_override" ]]; then
    objective="$objective\n\nAdditional Context: $context_override"
  fi

  # Execute swarm (opens Claude Code CLI)
  npx claude-flow@alpha swarm "$objective" \
    --strategy development \
    --parallel \
    --max-agents 5 \
    --claude

  return $?
}
```

### 3. Phase 2: Verification with Silent Failure Detection

```bash
run_phase2() {
  echo -e "${GREEN}Running Phase 2: Verification${NC}"
  local phase2_failed=false

  # Step 1: Backend startup with log monitoring
  echo -e "${BLUE}[Step 1/N] Starting backend...${NC}"

  # Start process in background
  your_start_command > /tmp/backend.log 2>&1 &
  local backend_pid=$!

  # Watch logs for success indicator (30s timeout)
  local timeout=30
  local elapsed=0
  local backend_started=false

  while [[ $elapsed -lt $timeout ]]; do
    # Check for success pattern
    if grep -q "SUCCESS_PATTERN" /tmp/backend.log 2>/dev/null; then
      backend_started=true
      echo -e "${GREEN}✓ Backend started${NC}"
      break
    fi

    # Check for error patterns
    if grep -qi "error\|failed" /tmp/backend.log 2>/dev/null; then
      echo -e "${RED}✗ Backend errors detected${NC}"
      cat /tmp/backend.log
      phase2_failed=true
      break
    fi

    sleep 1
    elapsed=$((elapsed + 1))
  done

  if [[ "$backend_started" == "false" && "$phase2_failed" == "false" ]]; then
    echo -e "${RED}✗ Backend startup timed out${NC}"
    cat /tmp/backend.log
    phase2_failed=true
  fi

  if [[ "$phase2_failed" == "true" ]]; then
    return 1
  fi

  # Step 2: Additional verification ste