Coordinator Helper

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

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

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

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

2. Review Completed Work

1. Open explorer - ailang coordinator list
2. Select task - Enter task number
3. Review:
   • [d] View diff
   • [f] Browse files
   • [l] View logs
4. Decide - [a] Approve or [r] Reject

3. Task Routing

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