digraph orchestration {
    "Issues provided?" -> "Prompt user" [label="no"];
    "Issues provided?" -> "Fetch issues" [label="yes"];
    "Prompt user" -> "Fetch issues";
    "Fetch issues" -> "Create feature branch";
    "Create feature branch" -> "Resolve dependencies";
    "Resolve dependencies" -> "For each group";
    "For each group" -> "Create context branch" [label="parallel"];
    "Create context branch" -> "Launch task agents";
    "Launch task agents" -> "Collect results";
    "Collect results" -> "Run consensus review";
    "Run consensus review" -> "Remediate findings?" [shape=diamond];
    "Remediate findings?" -> "Apply fixes" [label="yes"];
    "Remediate findings?" -> "Save checkpoint" [label="no"];
    "Apply fixes" -> "Run consensus review" [label="re-review"];
    "Save checkpoint" -> "More groups?" [shape=diamond];
    "More groups?" -> "For each group" [label="yes"];
    "More groups?" -> "RALPH reflection" [label="no"];
    "RALPH reflection" -> "Create PR";
    "Create PR" -> "Final summary";
}

AskUserQuestion(
  questions: [{
    question: "Which issues or epic would you like to orchestrate?",
    header: "Issues",
    options: [
      { label: "Enter issue numbers", description: "Comma-separated list (e.g., 42,43,44)" },
      { label: "Select an epic", description: "Epic issue that contains sub-issues" },
      { label: "Current milestone", description: "All open issues in current milestone" }
    ],
    multiSelect: false
  }]
)

gh issue list --milestone "$(gh api repos/:owner/:repo/milestones --jq '.[0].title')" --json number,title
-> Present list for confirmation

1. Fetch issue details:
   gh issue view <number> --json number,title,body,labels,milestone

2. For epics (single issue with sub-issues):
   gh api graphql -f query='{ repository(owner:"X", name:"Y") {
     issue(number: N) { trackedIssues(first: 50) { nodes { number title } } }
   }}'

3. Extract task information:
   - number -> Task ID
   - title -> Task name
   - body -> Agent prompt (look for ## Agent Prompt or ## Description)
   - labels -> Priority (P0, P1, P2), type (feature, bug, etc.)
   - "Depends On: #XX" in body -> Dependencies

4. Record to memory:
   memory_record(title: "Orchestration: Issues #{list}", ...)

1. Generate branch name from epic/issue:
   branch_name = "feature/issue-{epic_number}-{sanitized_title}"
   Example: "feature/issue-123-locomo-benchmark"

2. Create and checkout feature branch:
   git checkout -b {branch_name}

3. Verify branch:
   git branch --show-current
   → Must NOT be "main" or "master"

4. If already on main with uncommitted changes:
   git stash
   git checkout -b {branch_name}
   git stash pop

1. Read engineering practices:
   Read("CLAUDE.md"), Read("engineering-practices.md")

2. Search past orchestrations:
   memory_search(project_id, "orchestration", limit: 5)

3. If resuming:
   checkpoint_list(session_id: "orchestrate-{issue_ids}")
   checkpoint_resume(checkpoint_id)

4. Create main context branch:
   branch_create(description: "Orchestration: #{issue_ids}", budget: 16384)

5. Save initial checkpoint:
   checkpoint_save(name: "orchestrate-start")

1. Build dependency graph from issue relationships
2. Generate parallel groups (topological sort)
3. Validate no circular dependencies

Example:
  #42 depends on nothing -> Group 1
  #43 depends on nothing -> Group 1
  #44 depends on #42 -> Group 2
  #45 depends on #43, #44 -> Group 3

1. Create context branch (budget: 8192)
   branch_create(description: "Group {n}: #{issue_numbers}")

2. Launch parallel task agents for issues in group:
   Task(
     subagent_type: "contextd:task-agent",
     prompt: |
       # Issue #{number}: {title}

       {issue_body}

       ## Contextd Integration
       - Record decisions with memory_record
       - Record fixes with remediation_record
       - Update issue with progress comments via `gh issue comment`
     description: "Issue #{number}: {title}",
     run_in_background: true
   )

3. Monitor and collect results:
   TaskOutput(task_id, block=false)
   branch_status(branch_id) -> check budget

4. Return from branch:
   branch_return(message: "Group complete: {summary}")

1. Launch review agents in parallel:
   Task(subagent_type: "fs-dev:security-reviewer", ...)
   Task(subagent_type: "fs-dev:vulnerability-reviewer", ...)
   Task(subagent_type: "fs-dev:code-quality-reviewer", ...)
   Task(subagent_type: "fs-dev:documentation-reviewer", ...)
   Task(subagent_type: "fs-dev:go-reviewer", ...)  # if Go code

2. Collect verdicts using result synthesis patterns
   - Parse findings from each reviewer
   - Detect conflicts between reviewers
   - Record to memory_record

3. Calculate consensus:
   consensus_score = (approvals / total_reviewers) * 100

4. Apply veto threshold:
   - strict: ALL findings must be fixed (100% consensus required)
   - standard: CRITICAL/HIGH must be fixed (security/vulnerability have veto power)
   - advisory: Log only, continue

5. If consensus < 100% OR any veto:
   - Create remediation tasks for all blocking findings
   - Fix issues
   - Re-run full review
   - Loop until 100% consensus

1. Search past remediations:
   remediation_search(query: "{finding.type}")

2. Apply fixes, run tests

3. Record new remediation:
   remediation_record(error_signature, root_cause, solution)

4. Re-run review if needed

checkpoint_save(
  name: "orchestrate-group-{n}-complete",
  summary: "Completed: #{issues}, Remaining: #{remaining}"
)

1. Analyze patterns:
   reflect_analyze(project_id, period_days: 1)

2. Consolidate similar learnings:
   memory_consolidate(similarity_threshold: 0.8)

3. Generate report:
   reflect_report(format: "markdown")

1. Return from main branch:
   branch_return(message: "Orchestration complete: {metrics}")

2. Push feature branch to remote:
   git push -u origin {branch_name}

3. Create pull request:
   gh pr create \
     --title "feat: {epic_title}" \
     --body "## Summary
   Orchestrated implementation of #{epic_number}.

   ## Issues Completed
   - #{issue_list}

   ## Consensus Review
   All groups passed {threshold} review.

   ## Test Results
   {test_summary}"

4. Update issues with PR link:
   gh issue comment <number> --body "Implementation PR: #{pr_url}"

5. Record final memory:
   memory_record(title: "Orchestration Complete", outcome: "success")

6. Save final checkpoint:
   checkpoint_save(name: "orchestrate-complete")

## Description
Brief description of what this issue accomplishes.

## Agent Prompt
Detailed instructions for the task agent.

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Dependencies
Depends On: #42, #43

/contextd:orchestrate --resume "group-2-complete"

-> Loads checkpoint state
-> Skips completed groups
-> Continues from saved point

{
  "per_group_budget": {
    "group_1": { "allocated": 10000, "used": 8500, "issues": [42, 43] },
    "group_2": { "allocated": 10000, "used": 6200, "issues": [44] },
    "group_3": { "allocated": 10000, "used": 0, "issues": [45] }
  }
}

Every 5 minutes OR after each task:
  1. branch_status(branch_id) -> get token usage
  2. Compare to thresholds (70% warning, 90% critical)
  3. If warning: checkpoint_save(auto_created: true)
  4. If critical: pause, notify, wait for user

{
  "issue_concurrency": {
    "max_parallel_agents": 4,
    "max_per_group": 2,
    "queue_overflow": "wait",
    "timeout_minutes": 30,
    "priority_labels": ["P0", "P1", "P2"]
  }
}

{
  "dlq_entry": {
    "task_id": "task_abc123",
    "issue_number": 42,
    "failure_reason": "timeout after 30 minutes",
    "error_message": "Agent did not complete within budget",
    "retry_count": 2,
    "max_retries": 3,
    "github_comment": true
  }
}

dlq_analyze() for issues:
  - Correlated issues (same dependency failing)
  - Label patterns (bug issues failing more)
  - Recommendations (increase budget, split issues)

<org>/<project>/orchestrations/<orchestration_id>

Examples:
  fyrsmithlabs/contextd/orchestrations/epic-42
  fyrsmithlabs/marketplace/orchestrations/v1.6-release

<orchestration_namespace>/groups/<group_id>/tasks/<task_id>

Example:
  fyrsmithlabs/contextd/orchestrations/epic-42/groups/1/tasks/issue-43

# Group 1 (parallel - no issue dependencies)
task_42 = Task(prompt: "Execute issue #42", run_in_background: true)
task_43 = Task(prompt: "Execute issue #43", run_in_background: true)

# Group 2 (issue #44 depends on #42)
task_44 = Task(prompt: "Execute issue #44", addBlockedBy: [task_42.id])

# Group 3 (issue #45 depends on #43 and #44)
task_45 = Task(prompt: "Execute issue #45", addBlockedBy: [task_43.id, task_44.id])

{
  "hook_type": "PreToolUse",
  "tool_name": "Bash",
  "condition": "orchestration_active AND command.matches('git push --force|rm -rf')",
  "prompt": "Dangerous operation during orchestration. Checkpoint first and confirm with user."
}

{
  "hook_type": "PostToolUse",
  "tool_name": "Task",
  "condition": "task_completed AND orchestration_active",
  "prompt": "Task completed. Record to memory_record, update issue with progress comment."
}

{
  "event": "orchestration_started",
  "payload": {
    "orchestration_id": "epic-42",
    "issues": [42, 43, 44, 45],
    "groups": 3,
    "estimated_duration": "2 hours"
  },
  "notify": ["workflow", "consensus-review"]
}