gregoryho/arc-coordinating

Coordinator

Overview

Use the Node.js CLI (scripts/coordinator.js) for worktree lifecycle and cross-session coordination.

When to Use

• Multi-epic projects needing parallel development
• Worktree creation/merge automation
• DAG status tracking across sessions
• Merging from an epic worktree when .arcforge-epic exists and epic id should be inferred

Single-epic projects: Use arc-implementing directly (except merge in a worktree).

If already in a worktree: Use arc-implementing, except for merge (allowed).

DAG requirement: specs/<spec-id>/dag.yaml must exist and be committed before running coordinator commands. In base-side sessions with multiple specs, commands that cannot aggregate (next, parallel, expand, loop) require --spec-id <id>; merge / cleanup accept positional epic ids as disambiguator.

Commands

| Command | Purpose | CLI Mapping | |---------|---------|-------------| | expand | Create worktrees for ready epics | arcforge expand | | merge | Merge completed epics | arcforge merge | | status | Show workflow progress | arcforge status | | cleanup | Remove merged worktrees | arcforge cleanup | | sync | Synchronize worktree ↔ DAG state | arcforge sync | | next | Show next ready task | arcforge next | | parallel | Show parallelizable tasks | arcforge parallel | | block | Mark a task blocked in DAG | arcforge block | | reboot | Generate 5-Question context | arcforge reboot |

CLI Usage

IMPORTANT: Set SKILL_ROOT to the absolute path from the skill loader header (# SKILL_ROOT: ...).

: "${SKILL_ROOT:=${ARCFORGE_ROOT:-}/skills/arc-coordinating}"
if [ ! -d "$SKILL_ROOT" ]; then
  echo "ERROR: SKILL_ROOT=$SKILL_ROOT does not exist. Set ARCFORGE_ROOT or SKILL_ROOT manually." >&2
  exit 1
fi

Then use node "${SKILL_ROOT}/scripts/coordinator.js" <command> for all commands:

node "${SKILL_ROOT}/scripts/coordinator.js" status
node "${SKILL_ROOT}/scripts/coordinator.js" expand
node "${SKILL_ROOT}/scripts/coordinator.js" merge

JSON output: Add --json flag for machine-readable output:

node "${SKILL_ROOT}/scripts/coordinator.js" status --json

Standard Workflow

Workflow:

1. Set SKILL_ROOT: From the skill loader header
2. Check Exit Code: If exit 1, report blocked format and stop
3. Execute Command: Use node "${SKILL_ROOT}/scripts/coordinator.js" <command>
4. Never Fallback: Do NOT attempt manual operations if CLI fails

Merge From Worktree (Auto-Detect)

If the current directory is an arcforge-managed worktree (contains .arcforge-epic):

1. Infer epic id from .arcforge-epic
2. Find base worktree via git worktree list --porcelain — the coordinator automatically recognizes which entries are arcforge-managed worktrees and picks the base for you
3. Infer base branch from the base worktree HEAD
4. Merge the epic into base, and mark epic completed in dag.yaml

If base worktree cannot be found or base branch cannot be inferred → report blocked and STOP.

Completion Format

✅ Coordinator: expand complete

• Worktrees created: 3
• Ready for development: epic-auth, epic-api, epic-ui

Blocked Format

⚠️ Coordinator: merge blocked

• Epic: epic-auth
• Conflict: src/types.py
• Action: Manual resolution required

⚠️ Coordinator: blocked

• Issue: Node.js CLI not available
• Checked: ${SKILL_ROOT}/scripts/coordinator.js
• Action: Ensure Node.js is available, then retry

⚠️ Coordinator: merge blocked

• Issue: Base worktree not found or base branch not inferred
• Checked: git worktree list --porcelain, base worktree HEAD
• Action: Ensure a main worktree exists and has a valid branch checked out, then retry

When NOT to Use

• Single feature implementation → arc-implementing
• No dag.yaml → arc-planning first
• Already in worktree → stay in arc-implementing