Step 1: Validate and Load Plan

Security: Validate plan_id format to prevent path traversal attacks:

# plan_id must match pattern: {org}-{project}-{subproject}-{timestamp}
# Only alphanumeric, hyphens, and underscores allowed
if plan_id contains ".." or "/" or "\" or special characters:
  ERROR: Invalid plan_id format

Read plan from logs/fractary/plugins/faber/plans/{plan_id}.json

If not found, error:

❌ Plan not found: {plan_id}

Check available plans:
  ls logs/fractary/plugins/faber/plans/

Step 2: Filter Items (if --items specified)

If items parameter provided:

items_to_run = plan.items.filter(i => items.includes(i.work_id))

Else:

items_to_run = plan.items

Step 3: Load Resume State (if --resume)

If resume is true:

For each item in items_to_run:
  state_path = "logs/fractary/plugins/faber/runs/{plan_id}/items/{item.work_id}/state.json"

  IF state file exists:
    state = read(state_path)
    item.resume_from = {
      "phase": state.current_phase,
      "step_index": state.current_step_index,
      "steps_completed": state.steps_completed,
      "run_id": state.run_id
    }
    item.is_resume = true
  ELSE:
    item.is_resume = false
    LOG "⚠️ No state found for item {item.work_id}, starting fresh"

State structure (read from file):

{
  "run_id": "fractary-claude-plugins-abc123",
  "plan_id": "fractary-claude-plugins-csv-export-20251208T160000",
  "work_id": 123,
  "current_phase": "build",
  "current_step_index": 2,
  "steps_completed": ["generate-spec", "create-branch"],
  "status": "in_progress"
}

Step 4: Update Plan Status

Update plan file:

{
  "execution": {
    "status": "running",
    "started_at": "2025-12-08T16:30:00Z",
    "is_resume": {resume}
  }
}

Step 5: Spawn Managers

Parallel Mode (default)

Spawn ALL managers in ONE message for parallel execution:

For each item in items_to_run:
  Task(
    subagent_type="fractary-faber:faber-manager",
    description="Execute FABER for #{item.work_id}",
    run_in_background=true,
    prompt='{
      "target": "{item.target}",
      "work_id": "{item.work_id}",
      "workflow_id": "{plan.workflow.id}",
      "resolved_workflow": {plan.workflow},
      "autonomy": "{plan.autonomy}",
      "phases": {plan.phases_to_run},
      "step_id": {plan.step_to_run},
      "additional_instructions": "{plan.additional_instructions}",
      "worktree": "{item.worktree}",
      "is_resume": {item.branch.status == "resume"},
      "resume_context": {item.branch.resume_from},
      "issue_data": {item.issue},
      "working_directory": "{working_directory}"
    }'
  )

Wait for all background agents to complete using the AgentOutputTool (retrieve results from Task agents spawned with run_in_background=true).

Serial Mode (--serial)

Spawn managers one at a time, wait for each before next.

Step 6: Collect Results

For each manager result:

{
  "work_id": "123",
  "status": "success|failed",
  "pr_url": "https://github.com/...",
  "error": null
}

Step 7: Update Plan with Results

Update plan file:

{
  "execution": {
    "status": "completed|partial|failed",
    "completed_at": "2025-12-08T17:00:00Z",
    "results": [
      {"work_id": "123", "status": "success", "pr_url": "..."},
      {"work_id": "124", "status": "failed", "error": "..."}
    ]
  }
}

Step 8: Trigger Worktree Cleanup

For each successful item:

• If PR was merged, cleanup worktree automatically
• Uses /repo:worktree-remove if worktree exists

Step 9: Return Summary

Output aggregated results.