Worker Done - Task Completion Orchestrator

Orchestrates the full task completion pipeline by composing atomic commands.

Usage

/conductor:worker-done TabzChrome-abc

# Or if issue ID is in your task header:
/conductor:worker-done

Pipeline Overview

Step	Command	Blocking?	Mode-specific
0	Detect execution mode	No	Sets EXECUTION_MODE
0.5	Detect change types	No	Sets DOCS_ONLY
1	/conductor:verify-build	Yes - stop on failure	Skip if DOCS_ONLY
1a	plugin-validator agent	Yes - stop on failure	ONLY if DOCS_ONLY
2	/conductor:run-tests	Yes - stop on failure	Skip if DOCS_ONLY
3	/conductor:commit-changes	Yes - stop on failure	Always run
4	/conductor:create-followups	No - log and continue	Always run
5	/conductor:update-docs	No - log and continue	Always run
5.5	Record completion info	No - best effort	Always run
5.6	Update agent bead state	No - best effort	Worker mode only
6	/conductor:close-issue	Yes - report result	Always run
7	Notify conductor	No - best effort	Worker mode only
8	Standalone next steps	No - informational	Standalone mode only

CRITICAL: You MUST execute Step 7 after Step 6. Workers that skip Step 7 force the conductor to poll, wasting resources.

DOCS_ONLY mode: When all changes are markdown files (.md, .markdown), steps 1-2 are replaced with the plugin-validator agent. This validates markdown structure and content without running expensive build/test steps.

Code review happens at conductor level: Workers do NOT run code review. The conductor runs unified code review after merging all worker branches (see /conductor:wave-done). This prevents conflicts when multiple workers run in parallel.

---

Execute Pipeline

Step 0: Detect Execution Mode

CRITICAL: Run this FIRST before any other steps.

echo "=== Step 0: Detecting Execution Mode ==="

# Detection function
is_worker_mode() {
  # Method 1: CONDUCTOR_SESSION env var (set by bd-work/bd-swarm)
  [ -n "$CONDUCTOR_SESSION" ] && return 0

  # Method 2: Inside git worktree (bd-swarm creates these)
  COMMON_DIR=$(git rev-parse --git-common-dir 2>/dev/null)
  GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
  [ "$COMMON_DIR" != "$GIT_DIR" ] && return 0

  return 1  # Standalone mode
}

# Run detection
if is_worker_mode; then
  EXECUTION_MODE="worker"
  echo "╔══════════════════════════════════════════════════════════════╗"
  echo "║  WORKER MODE DETECTED                                        ║"
  echo "║  • Skipping code review (conductor handles after merge)      ║"
  echo "║  • Skipping push (conductor handles after merge)             ║"
  echo "║  • Will notify conductor on completion                       ║"
  echo "╚══════════════════════════════════════════════════════════════╝"
else
  EXECUTION_MODE="standalone"
  echo "╔══════════════════════════════════════════════════════════════╗"
  echo "║  STANDALONE MODE DETECTED                                    ║"
  echo "║  • Full pipeline with optional code review                   ║"
  echo "║  • You should push changes when done                         ║"
  echo "║  • No conductor to notify                                    ║"
  echo "╚══════════════════════════════════════════════════════════════╝"
fi

Mode determines pipeline behavior:

Aspect	Worker Mode	Standalone Mode
Code review	Skip (conductor handles)	Optional (user choice)
Push	Skip (conductor handles)	User should push
Notify conductor	Yes (Step 7)	No

---

Step 0.5: Detect Change Types

echo "=== Step 0.5: Detecting Change Types ==="
# Check if only markdown files changed (staged + unstaged)
git diff --cached --name-only
git diff --name-only

Detection logic:

1. Get list of all changed files (staged and unstaged)
2. Check if ALL changes are markdown files (.md, .markdown)
3. Set DOCS_ONLY=true if only markdown, otherwise DOCS_ONLY=false

# Detection check - if ANY file is non-markdown, run full pipeline
if git diff --cached --name-only | grep -qvE '\.(md|markdown)$' 2>/dev/null; then
  DOCS_ONLY=false
elif git diff --name-only | grep -qvE '\.(md|markdown)$' 2>/dev/null; then
  DOCS_ONLY=false
else
  # Check if there are actually any changes at all
  if [ -z "$(git diff --cached --name-only)$(git diff --name-only)" ]; then
    DOCS_ONLY=false  # No changes = run normal pipeline
  else
    DOCS_ONLY=true
  fi
fi

If DOCS_ONLY=true: Run Step 1a (plugin-validator), then skip to Step 3. If DOCS_ONLY=false: Continue with full pipeline (Steps 1, 2, 3...).

---

Step 1: Verify Build (skip if DOCS_ONLY)

echo "=== Step 1: Build Verification ==="

Run /conductor:verify-build. If passed: false -> STOP, fix errors, re-run.

Step 1a: Plugin Validator (ONLY if DOCS_ONLY)

When DOCS_ONLY=true, run the plugin-validator agent instead of build/test:

echo "=== Step 1a: Plugin Validation (markdown-only changes) ==="

Invoke the plugin-validator agent to validate the changed markdown files:

Task(subagent_type="plugin-dev:plugin-validator", prompt="Validate the following changed markdown files: <list files from git diff>. Check for: broken links, invalid YAML frontmatter, missing required sections, and consistent formatting.")

The agent will:

1. Check YAML frontmatter syntax in skill/agent files
2. Verify required fields are present (name, description, etc.)
3. Check for broken internal links
4. Validate markdown structure

If validation fails -> STOP, fix issues, re-run. If validation passes -> Skip to Step 3 (commit).

Step 2: Run Tests (skip if DOCS_ONLY)

echo "=== Step 2: Test Verification ==="

Run /conductor:run-tests. If passed: false -> STOP, fix tests, re-run.

Step 3: Commit Changes

echo "=== Step 3: Commit ==="

Run /conductor:commit-changes <issue-id>. Creates conventional commit with Claude signature.

Step 4-5: Non-blocking

echo "=== Step 4: Follow-up Tasks ==="
echo "=== Step 5: Documentation Check ==="

Run /conductor:create-followups and /conductor:update-docs. Log and continue.

Step 5.5: Record Completion Info

echo "=== Step 5.5: Record Completion Info ==="

# Get existing notes and append completion info
EXISTING_NOTES=$(bd show "$ISSUE_ID" --json 2>/dev/null | jq -r '.notes // ""')
COMMIT_SHA=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")

# Append completion info to existing notes
NEW_NOTES="${EXISTING_NOTES}
completed_at: $(date -Iseconds)
commit: $COMMIT_SHA"

bd update "$ISSUE_ID" --notes "$NEW_NOTES"

This creates an audit trail with start time (from spawn) and completion time + commit.

Step 5.6: Update Agent Bead (WORKER MODE ONLY)

Skip this step if EXECUTION_MODE=standalone.

If this worker has an associated agent bead, update its state:

echo "=== Step 5.6: Update Agent Bead ==="

# Get agent ID from issue notes (set by bd-swarm-auto)
AGENT_ID=$(bd show "$ISSUE_ID" --json 2>/dev/null | grep -oP 'agent_id:\s*\K[^\s"]+' || echo "")

if [ -n "$AGENT_ID" ]; then
  # Set agent state to done
  bd agent state "$AGENT_ID" done

  # Clear the hook slot (detach from issue)
  bd slot clear "$AGENT_ID" hook

  echo "Agent $AGENT_ID marked as done"
else
  echo "No agent bead associated with this worker (standalone or legacy)"
fi

This enables monitoring workers via bd list --type=agent and dead detection via heartbeat.

Step 6: Close Issue

echo "=== Step 6: Close Issue ==="

Run /conductor:close-issue <issue-id>. Reports final status.

Step 7: Notify Conductor (WORKER MODE ONLY)

Skip this step if EXECUTION_MODE=standalone.

DO NOT SKIP THIS STEP in worker mode. After closing the issue, notify the conductor:

IMPORTANT: Do not use # or other special shell characters at the START of notification messages. Shell interprets # as a comment, causing the message to not be submitted properly via tmux send-keys.

echo "=== Step 7: Notify Conductor ==="

SUMMARY=$(git log -1 --format='%s' 2>/dev/null || echo 'committed')
WORKER_SESSION=$(tmux display-message -p '#{session_name}' 2>/dev/null || echo 'unknown')

# Primary method: tmux send-keys (Claude Code queues messages, safe even mid-output)
CONDUCTOR_SESSION="${CONDUCTOR_SESSION:-}"
if [ -n "$CONDUCTOR_SESSION" ]; then
  tmux send-keys -t "$CONDUCTOR_SESSION" -l "WORKER COMPLETE: $ISSUE_ID - $SUMMARY"
  sleep 0.3
  tmux send-keys -t "$CONDUCTOR_SESSION" C-m
  echo "Notified conductor via tmux"
fi

# Secondary: API broadcast for browser UIs (WebSocket - conductor can't receive this)
TOKEN=$(cat /tmp/tabz-auth-token 2>/dev/null)
if [ -n "$TOKEN" ]; then
  curl -s -X POST http://localhost:8129/api/notify \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $TOKEN" \
    -d "{\"type\": \"worker-complete\", \"issueId\": \"$ISSUE_ID\", \"summary\": \"$SUMMARY\", \"session\": \"$WORKER_SESSION\"}" >/dev/null
fi

Why tmux is primary: Claude Code queues incoming messages even during output, so tmux send-keys is safe. The API broadcasts via WebSocket which browser UIs can receive, but tmux-based Claude sessions cannot.

Step 8: Standalone Next Steps (STANDALONE MODE ONLY)

Skip this step if EXECUTION_MODE=worker.

When running in standalone mode, display guidance for completing the workflow:

if [ "$EXECUTION_MODE" = "standalone" ]; then
  echo ""
  echo "╔══════════════════════════════════════════════════════════════╗"
  echo "║  STANDALONE COMPLETION - Next Steps                          ║"
  echo "╠══════════════════════════════════════════════════════════════╣"
  echo "║  Issue closed. Your changes are committed but NOT pushed.    ║"
  echo "║                                                              ║"
  echo "║  Recommended next steps:                                     ║"
  echo "║  1. [Optional] Run code review: /conductor:code-review       ║"
  echo "║  2. Sync and push: bd sync && git push                       ║"
  echo "╚══════════════════════════════════════════════════════════════╝"
fi

Why standalone doesn't auto-push: In standalone mode, you may want to run code review or make additional changes before pushing. The conductor handles push automatically for workers, but standalone users have full control.

---

Atomic Commands Reference

Command	Description
/conductor:verify-build	Run build, report errors
/conductor:run-tests	Run tests if available
/conductor:commit-changes	Stage + commit with conventional format
/conductor:create-followups	Create follow-up beads issues
/conductor:update-docs	Check/update documentation
/conductor:close-issue	Close beads issue

Note: /conductor:code-review is NOT used by workers. Code review runs at conductor level after merge (see /conductor:wave-done).

---

Custom Pipelines

Compose commands for custom workflows:

Standard worker completion:

/conductor:verify-build
/conductor:run-tests
/conductor:commit-changes
/conductor:close-issue <id>

Quick commit (skip tests):

/conductor:verify-build
/conductor:commit-changes
/conductor:close-issue <id>

---

Error Handling

Step	On Failure
Build	Show errors, stop pipeline
Tests	Show failures, stop pipeline
Commit	Show git errors, stop pipeline
Follow-ups	Non-blocking - log and continue
Docs	Non-blocking - log and continue
Close	Show beads errors
Notify	Non-blocking - log and continue

---

Re-running After Fixes

If the pipeline stopped:

1. Fix the issues
2. Run /conductor:worker-done again

The pipeline is idempotent - safe to re-run.

---

After Completion

Worker Mode

When /conductor:worker-done succeeds in worker mode:

• Issue is closed in beads
• Commit is on the feature branch
• Conductor notified via tmux
• Worker's job is done

The conductor then:

• Merges the feature branch to main
• Kills this worker's tmux session
• Removes the worktree (if bd-swarm)
• Deletes the feature branch

Workers do NOT kill their own session - the conductor handles cleanup after receiving the notification.

Standalone Mode

When /conductor:worker-done succeeds in standalone mode:

• Issue is closed in beads
• Commit is on current branch (not pushed)
• No conductor to notify

User should then:

• Optionally run /conductor:code-review for code review
• Run bd sync && git push to push changes

---

Review Policy

Workers do NOT do code review or visual review. All reviews happen at the conductor level after merge, not in individual workers.

Why reviews are conductor-level only:

Code Review:

• Parallel workers running code review simultaneously causes resource contention
• Unified review after merge catches cross-worker interactions and combined code patterns
• Avoids duplicate review effort (workers reviewed individually, then conductor reviews again)

Visual Review:

• Parallel workers opening browser tabs fight over the same browser window
• Workers cannot create isolated tab groups (tabz_claude_group_* uses a single shared group)
• Unified visual review after merge provides better coverage with no conflicts

Division of Responsibility

Worker focus: Implementation → Tests → Build → Commit → Close

Conductor handles: Merge → Unified Code Review → Visual QA → Final Push

See /conductor:wave-done for the full conductor pipeline.

---

Reference Files

File	Content
references/example-sessions.md	Example output for different scenarios

Execute this pipeline now.