run-tasks

Run Tasks Skill

Purpose

Execute implementation tasks through coordinated sub-agents with optional TDD workflow:

1. Get ready work from beads (no blockers)
2. Check TDD configuration and enforce test-first gating if enabled
3. Group tasks for parallel execution (with git worktree isolation)
4. Spawn agents based on agent:* labels
5. Monitor completion and run verification
6. Handle failures with debug loop (TDD mode) or blocking
7. Update beads status and merge completed work
8. Repeat until truly done (stop hook prevents premature exit)
9. Present "What's next?" prompt to guide user to next workflow step

Key guarantee: The stop hook ensures ALL tasks complete before exit. Claude queries beads state each cycle rather than tracking in context, enabling token-efficient persistence.

Telemetry Capture

Required after each agent completes:

1. Parse agent output JSON (last line): {"s":"s","t":1200,"m":[...],"c":[...]}
2. Insert into agent_telemetry table immediately
3. Continue even if telemetry insert fails (log warning, don't block)

This enables retrospective analysis via /retro. Telemetry MUST be captured after EACH agent completes, not just at the end of the batch.

When to Use

• After /approve-spec has created tasks
• User says "run tasks", "start implementation", "execute"
• There are open tasks in beads

Arguments

/run-tasks [epic-id]       # Run tasks for specific epic
/run-tasks                  # Run all ready tasks

---

Process Overview

Step 0a: Path Detection

Determine the location of discovery.db to support both new .parade/ structure and legacy project root:

# Path detection for .parade/ structure
if [ -f ".parade/discovery.db" ]; then
  DISCOVERY_DB=".parade/discovery.db"
else
  DISCOVERY_DB="./discovery.db"
fi

All subsequent database operations in this skill use $DISCOVERY_DB instead of hardcoded discovery.db.

Step 0b: Check TDD Configuration

Before starting task execution, check if TDD is enabled:

cat project.yaml | grep -A 1 "workflow:"

If tdd_enabled: true, enforce test-first gating workflow (see TDD Protocol). If tdd_enabled: false, use standard workflow without gating.

Step 0a: Git Setup (Epic Branch)

Create an epic integration branch to isolate all work for this epic:

# Ensure main is up to date
git checkout main
git pull origin main

# Create epic branch
git checkout -b epic/<epic-id>
git push -u origin epic/<epic-id>

All task branches will be created from this epic branch, enabling:

• Clean parallel execution without affecting main
• Atomic epic-level rollback if needed
• Single merge commit when epic completes

See Git Strategy for complete branching and commit workflow.

Step 1: Get Ready Work

bd ready --json

This returns tasks that:

• Have status open
• Have no blocking dependencies (or all blockers are closed)

If epic-id is provided, filter:

bd list --parent <epic-id> --status open --json

Step 1a: Apply TDD Gating (if tdd_enabled)

For each ready task, check metadata and labels:

bd show <task-id> --json

TDD Gating Rules:

• If task has skip_tests label → ALLOW immediately (no TDD gating)
• If task has test_task_id metadata and test task is NOT closed → EXCLUDE from ready batch
• Test tasks (those without test_task_id) can run immediately
• Implementation tasks wait for their test tasks to close (RED phase verified)

See TDD Protocol for complete gating details.

Step 2: Identify Parallel Batches

Tasks can run in parallel if they don't depend on each other.

CRITICAL: Apply batch size limit to prevent context overflow.

# Check project config for max parallel tasks (default: 3)
MAX_PARALLEL=$(grep -A1 "workflow:" project.yaml | grep "max_parallel_tasks:" | awk '{print $2}')
MAX_PARALLEL=${MAX_PARALLEL:-3}

From the ready work, group tasks with size limit:

• Sub-batch 1: First MAX_PARALLEL ready tasks
• Sub-batch 2: Next MAX_PARALLEL ready tasks
• Continue until all ready tasks are batched

Why this matters: Each agent returns ~2-3K tokens. Running 8+ agents in parallel returns 16-24K tokens simultaneously, overwhelming context and preventing compaction.

Example with MAX_PARALLEL=3:

Ready now (8 tasks):
- bd-x7y8.1 [agent:sql]
- bd-x7y8.2 [agent:swift]
- bd-x7y8.3 [agent:typescript]
- bd-x7y8.4 [agent:typescript]
- bd-x7y8.5 [agent:sql]
- bd-x7y8.6 [agent:swift]
- bd-x7y8.7 [agent:typescript]
- bd-x7y8.8 [agent:test]

Split into sub-batches:
- Sub-batch 1: [.1, .2, .3] → execute, wait, collect telemetry
- Sub-batch 2: [.4, .5, .6] → execute, wait, collect telemetry
- Sub-batch 3: [.7, .8] → execute, wait, collect telemetry

Execution pattern:

1. Spawn sub-batch agents in parallel
2. Wait for ALL agents in sub-batch to complete
3. Capture telemetry for each (see Step 4a)
4. Proceed to next sub-batch
5. After all sub-batches: check for newly unblocked tasks

Step 3: Spawn Agents for Batch

For each task in the current batch:

1. Get task details:

bd show <task-id> --json

2. Identify agent from labels: Look for agent:* label (e.g., agent:swift, agent:sql, agent:test)

3. Create output directory:

# Ensure the epic folder exists
mkdir -p docs/features/<epic-id>

The output path pattern is: docs/features/<epic-id>/<task-id>.md

4. Create worktrees for parallel isolation (multi-task batches):

# Create isolated worktree from epic branch
bd worktree create agent-<task-id> --branch agent/<task-id> --base epic/<epic-id>

5. Update epic status (first batch only):

bd update <epic-id> --status in_progress

6. Update task status:

bd update <task-id> --status in_progress

7. Spawn appropriate agent:

See Agent Spawning Reference for:

• Agent type mapping
• Prompt templates for each agent (including output path specification)
• Git worktree isolation for parallel execution
• Parallel execution using run_in_background: true

Step 4: Collect Results

Wait for all agents in batch to complete.

For each agent result:

• PASS: Continue to verification
• FAIL: Handle based on task type and mode

Step 4a: Capture Telemetry (REQUIRED AFTER EACH AGENT)

CRITICAL: Telemetry MUST be captured immediately after EACH agent completes, not just at batch end.

This is essential for:

• Retrospective analysis via /retro
• Debugging workflow bottlenecks
• Tracking agent performance metrics
• Understanding failure patterns

Failure Impact: If telemetry is not captured:

• /retro cannot analyze execution patterns
• Workflow improvements cannot be informed by data
• Bottlenecks go undetected

Process

1. Parse agent output - Look for compact JSON on last line:

{"s":"s","t":1200,"m":["src/file.ts"],"c":["src/new.ts"]}

2. Record to database IMMEDIATELY - Execute this SQL for EACH completed agent:

INSERT INTO agent_telemetry (
  id, task_id, epic_id, agent_type, status, token_count,
  duration_ms, files_modified, files_created, error_type,
  error_summary, debug_attempts, started_at, completed_at
) VALUES (
  'tel-' || hex(randomblob(4)),  -- Generate unique ID
  '<task-id>',
  '<epic-id>',
  '<agent-type>',                 -- e.g., 'typescript', 'swift', 'sql'
  CASE '<status>' WHEN 's' THEN 'PASS' WHEN 'f' THEN 'FAIL' ELSE 'UNKNOWN' END,
  <token_count>,                  -- From 't' field in JSON
  <duration_ms>,                  -- Calculate from start/end time
  '<files_modified_json>',        -- From 'm' field
  '<files_created_json>',         -- From 'c' field
  '<error_type>',                 -- From 'e' field if present
  '<error_summary>',              -- From 'x' field if present
  0,                              -- debug_attempts (increment on retries)
  '<started_at>',
  datetime('now')
);

3. Error Handling - If telemetry insert fails:

   • Log a warning with the error details
   • Continue with workflow (do not block)
   • The task completion will still proceed normally
   • This ensures workflow robustness even if instrumentation fails

4. Compact Output Key Reference: | Key | Meaning | Values | |-----|---------|--------| | s | status | "s" (success), "f" (fail), "b" (blocked) | | t | tokens | estimated token count used | | m | modified | array of modified file paths | | c | created | array of created file paths | | e | error | "t" (test), "b" (build), "o" (timeout) | | x | error msg | truncated error message (max 200 chars) |

If agent output lacks JSON: Record with status='UNKNOWN', token_count=NULL. This indicates agents need prompt updates.

Checklist for Step 4a:

• Agent completed and returned result
• JSON parsed from last line of output
• SQL insert executed (immediately, before verification)
• If insert fails, logged warning and continued (not blocked)
• Workflow proceeds to Step 5 (verification)

Step 5: Run Verification

Standard Mode

When agent reports completion, verify acceptance criteria are met:

1. Run verification commands (from acceptance criteria if specified)
2. Check output for success/failure indicators
3. Update status based on results

TDD Mode - RED Phase (Test Tasks)

When test-writer-agent reports completion:

1. Verify tests exist
2. Run tests and verify they FAIL
3. Expected outcome: Tests should fail with "not implemented" errors
4. RED Phase Validation:
   • If tests fail correctly: Close test task, unblock implementation task
   • If tests pass (wrong!): Mark test task as blocked
   • If syntax errors: Spawn test-writer-agent again to fix

# On successful RED phase
bd close <test-task-id>

TDD Mode - GREEN Phase (Implementation Tasks)

When implementation agent reports com

---

Content truncated.