Coordinator Helper

Manage the coordinator daemon for autonomous task delegation, approval workflows, and monitoring agent work.

Quick Start

Most common usage:

# User says: "Delegate this bug fix to an agent"
# This skill will:
# 1. Check if coordinator daemon is running
# 2. Send the task via ailang messages
# 3. Monitor the task status
# 4. Guide you through approval when complete

# User says: "What tasks are pending?"
# This skill will:
# 1. Run ailang coordinator list --pending
# 2. Show interactive task explorer
# 3. Let you review diffs, logs, and approve/reject

When to Use This Skill

Invoke this skill when:

User asks to "delegate a task" or "send to coordinator"
User wants to "check task status" or "see what's running"
User asks to "review agent work" or "approve/reject tasks"
User says "start the coordinator" or "stop the daemon"
User wants to "clean up worktrees" or manage coordinator state

Available Scripts

`scripts/check_daemon.sh`

Check if the coordinator daemon is running and show status.

`scripts/delegate_task.sh <type> <title> <description>`

Send a task to the coordinator for autonomous execution.

`scripts/quick_status.sh`

Show a quick summary of pending, running, and completed tasks.

Core Commands

Starting/Stopping the Daemon

# Start coordinator + server (recommended)
make services-start

# Or just coordinator
ailang coordinator start

# Check status
ailang coordinator status

# Stop all
make services-stop

Delegating Tasks

# Send a task
ailang messages send coordinator "Fix the null pointer bug in parser.go" \
  --title "Bug: Parser NPE" --from "claude-code" --type bug

Monitoring & Approving

# Interactive task list
ailang coordinator list

# Filter by status
ailang coordinator list --pending
ailang coordinator list --running

# Approve from list: select task, press [a]
# Or directly: ailang coordinator approve <task-id>

Task Lifecycle

pending → queued → running → pending_approval → completed
                          ↘ failed
                          ↘ rejected → [feedback] → pending (iteration 2) → running → ...

Feedback Loop (v0.6.4+): When rejecting, the task can be re-triggered with feedback up to 3 iterations. Claude uses --resume to continue with full conversation context.

Unified Approvals (v0.6.5+)

When an agent has trigger_on_complete configured with auto_approve_handoffs: false, approvals are combined:

Approval Type	Description	On Approve
`merge`	Simple merge only	Merges code to dev branch
`merge_handoff`	Combined merge + handoff	Merges code AND triggers next agent

CLI display shows:

⏳ [1] [merge+handoff] → sprint-planner  task-12345678
       Title: Agent completed work on: Fix parser bug

What happens on approve:

Code is merged to dev branch
Handoff message is sent to next agent's inbox with session_id for continuity
Worktree is cleaned up

What happens on reject:

Worktree is preserved
Feedback is sent to same agent's inbox
Agent resumes with --resume <sessionId> (same context, same worktree)
Iteration counter increments (max 3 attempts)

GitHub-Driven Workflow (v0.6.2+)

For tasks linked to GitHub issues, the coordinator supports a fully GitHub-native approval workflow.

How It Works

GitHub Issue
    ↓ (import)
DESIGN STAGE → posts design doc to GitHub → needs-design-approval label
    ↓ (human adds: design-approved)
SPRINT STAGE → posts sprint plan to GitHub → needs-sprint-approval label
    ↓ (human adds: sprint-approved)
IMPLEMENTATION → posts file changes → needs-merge-approval label
    ↓ (human adds: merge-approved)
Changes merged, issue auto-closed

GitHub Labels Reference

You Add This Label	What Happens
`design-approved`	Advances to sprint planning
`sprint-approved`	Advances to implementation
`merge-approved`	Merges changes, closes issue
`needs-revision`	Pauses pipeline for changes

Quick Commands for GitHub Workflow

# Import GitHub issues as tasks
ailang messages import-github

# Check which issues are being watched
tail -100 ~/.ailang/logs/coordinator.log | grep -i "watching issue"

# Fallback: approve locally if labels aren't detected
ailang coordinator approve <task-id>

# Check pending approvals
ailang coordinator pending

Why Use GitHub Workflow?

Review in GitHub UI - See design docs and diffs alongside issue discussion
Mobile-friendly - Approve from GitHub mobile app
Team collaboration - Multiple reviewers can discuss in comments
Audit trail - All approvals tracked in issue history

Workflow

1. Delegate a Task

Describe clearly - Be specific about what needs to be done
Choose type - bug, feature, docs, research, refactor, test
Send message - ailang messages send coordinator "..." --type bug

2. Review Completed Work

Open explorer - ailang coordinator list
Select task - Enter task number
Review:
- [c] View chat history (turn-by-turn conversation with tool calls)
- [d] View diff
- [f] Browse files
- [l] View logs
Decide:
- [a] Approve - merge changes to dev branch
- [r] Reject - prompt for feedback, re-trigger task with context

3. Task Routing

Type	Executor	Use Case
bug-fix	Claude Code	Code fixes
feature	Claude Code	New functionality
docs	Gemini	Documentation
research	Gemini	Investigation
script	Shell	Deterministic workflows (v0.6.4+)

4. Script Agents (v0.6.4+)

For deterministic tasks that don't need AI inference:

# In ~/.ailang/config.yaml
coordinator:
  agents:
    - id: echo-demo
      inbox: echo-demo
      invoke:
        type: script
        command: "./scripts/coordinator/echo_payload.sh"
        env_from_payload: true
        timeout: "1m"
      output_markers:
        - "ECHO_COMPLETE:"

Test the demo:

ailang messages send echo-demo '{"model": "gpt5", "benchmark": "fizzbuzz"}' \
  --title "Echo test" --from "user"

What happens:

JSON {"model": "gpt5"} → env var MODEL=gpt5
Nested JSON {"db": {"host": "x"}} → env var DB_HOST=x
Auto-injected: AILANG_TASK_ID, AILANG_MESSAGE_ID, AILANG_WORKSPACE
Cost: $0.00 (no AI inference)

Chain Execution Monitoring (v0.8.1+)

ailang chains is the canonical CLI for examining multi-agent workflows. Works offline (direct SQLite).

Find a Chain

# Find by coordinator task ID
ailang chains find --task-id task-29404032

# Find by message UUID
ailang chains find --message-id 29404032-74b3-40c6-acc3-23d6bbe14b68

# Find by GitHub issue
ailang chains find --github sunholo-data/ailang#131
ailang chains find --github sunholo-data/ailang#131 --json

Filter Chains

# By agent
ailang chains list --agent design-doc-creator
ailang chains list --agent sprint-executor --since 7d

# By time
ailang chains list --since 24h        # Last 24 hours
ailang chains list --since 7d         # Last week
ailang chains list --since 2026-02-01 # Since specific date

# Combined
ailang chains list --agent sprint-executor --status failed --since 7d --json

View Code Changes

# Git diff across all stages in a chain
ailang chains diff <chain-id>

# Diffstat summary only
ailang chains diff <chain-id> --stat

Recommended Timeouts by Agent Type

Two timeout types (v0.8.1+):

timeout (hard ceiling): Max wall-clock time, regardless of activity. Default: 60m.
idle_timeout: Kill if agent produces no output for this long. Default: 3m.

An agent actively writing code for 45 minutes stays alive. An agent that crashes or loops silently dies after 3 minutes.

Configure in ~/.ailang/config.yaml:

coordinator:
  agents:
    - id: design-doc-creator
      timeout: "20m"         # Hard ceiling
      idle_timeout: "3m"     # Kill if no output for 3m
    - id: sprint-planner
      timeout: "15m"
      idle_timeout: "2m"
    - id: sprint-executor
      timeout: "60m"         # Allow up to 1 hour
      idle_timeout: "5m"     # But kill if stuck for 5m

Auditing Agent Work

After a task completes, audit what the agent actually did before approving:

# View conversation per turn (shows agent reasoning + tool calls)
ailang coordinator logs <task-id> --limit 1000 --json | python3 -c "
import json, sys
data = json.load(sys.stdin)
events = data.get('events', [])
turns = {}; tools = {}
for evt in events:
    tn = evt.get('turn_num', 0); st = evt.get('stream_type', '')
    if st == 'text': turns.setdefault(tn, []).append(evt.get('text', ''))
    elif st == 'tool_use': tools.setdefault(tn, []).append(evt.get('tool_name', '?'))
for tn in sorted(turns.keys()):
    text = ''.join(turns[tn]).strip()
    if len(text) > 20:
        print(f'=== Turn {tn} (tools: {\", \".join(tools.get(tn, []))}) ===')
        print(text[:600]); print()
"

# View chain execution flow (recommended)
ailang chains view <chain-id> --spans
ailang chains tree <chain-id> --detailed

# View tool timeline with spans (requires server)
ailang dashboard spans --task-id <task-id> --limit 200

# View git changes
ailang coordinator diff <task-id>

Audit checklist:

Did the agent modify internal/ code or just create examples/docs?
What model was used? (Check executor.model in spans - Haiku may be too weak)
Did it run ailang run (runtime test) or just ailang check (compile test)?
Did it mark tasks as "already working" without verifying the specific bug scenario?

Per-agent model config (v0.8.0+): Set model: opus in agent config for complex coding tasks:

agents:
  - id: sprint-executor
    model: opus

Troubleshooting

Daemon won't start: Check ailang coordinator status, then make services-stop && make services-start

Task stuck: View logs with [l] in task explorer

Worktree limit: git worktree list then git worktree remove <path> --force

GitHub labels not detected: The ApprovalWatcher may not be detecting labels. Use CLI fallback:

ailang coordinator pending    # List tasks waiting for approval
ailang coordinator approve <task-id>   # Approve locally (syncs label to GitHub)

No logs from ApprovalWatcher: Check coordinator logs for "GitHub approval watcher started". If missing, verify ~/.ailang/config.yaml has github_sync.enabled: true.

Resources

See resources/reference.md for complete CLI reference and advanced options.

Notes

Coordinator uses isolated git worktrees per task
Worktrees auto-cleanup after approval
Events stream to dashboard at http://localhost:1957
State stored in ~/.ailang/state/coordinator.db

coordinator-helper

SKILL.md.claude/skills/coordinator-helper/SKILL.md