Orchestrate Ready Issues

Orchestrate Ready Issues

Run the Bible Strong issue harness as a sequential orchestrator. Do not parallelize issue work unless the user explicitly changes the repo policy.

Source of truth

Read these before acting:

• docs/agents/orchestration.md
• docs/agents/issue-tracker.md
• docs/agents/triage-labels.md
• docs/agents/validation.md
• docs/agents/smoke-tests.md for mobile or UI-facing changes
• docs/agents/sensitive-areas.md when an issue touches auth, sync, storage, backup/import/export, native config, releases, external services, or user-owned data

Operating mode

Use mobile-sequential:

• one issue at a time;
• one dedicated codex/issue-<number>-<slug> branch per issue;
• current worktree only, no per-issue worktree by default;
• PRs are ready for review by default;
• use draft PRs only when validation is blocked or intentionally deferred;
• never continue to the next issue from a dirty or ambiguous repo state.

Queue discovery

List ready issues with GitHub CLI:

gh issue list --state open --label ready-for-agent --json number,title,labels,updatedAt --limit 50

If the user named specific issue numbers, treat those numbers as the initial queue roots. Otherwise, process all open ready-for-agent issues in ascending issue number unless the user gives a different priority.

Sub-issues and dependency discovery

Before starting implementation, expand each queue root into an execution queue.

1. Fetch the issue root:

gh issue view <issue-number> --comments --json number,title,body,labels,state,url

2. Check whether the root has GitHub sub-issues. Prefer GraphQL because the local gh issue view --json fields may not expose hierarchy:

gh api graphql \
  -F owner='<owner>' \
  -F repo='<repo>' \
  -F number=<issue-number> \
  -f query='
    query($owner: String!, $repo: String!, $number: Int!) {
      repository(owner: $owner, name: $repo) {
        issue(number: $number) {
          number
          title
          state
          url
          labels(first: 50) { nodes { name } }
          parent { number title state url labels(first: 50) { nodes { name } } }
          subIssues(first: 100) {
            nodes {
              number
              title
              state
              url
              labels(first: 50) { nodes { name } }
            }
          }
        }
      }
    }'

If this GraphQL query is rejected because the GitHub schema or token does not expose issue hierarchy, fall back to the issue body and comments. Look for explicit task lists or references such as Sub-issues, Sub issues, Children, Depends on, Blocked by, #123, or full GitHub issue URLs. Treat body/comment references as candidates and verify each candidate issue with gh issue view before adding it.

3. Check native issue dependencies for every queue candidate:

gh api repos/<owner>/<repo>/issues/<issue-number>/dependencies/blocked_by --paginate
gh api repos/<owner>/<repo>/issues/<issue-number>/dependencies/blocking --paginate

If dependency endpoints are unavailable for the repository or token, fall back to body/comment references using blocked by, depends on, after, before, and blocking language. Clearly report that dependency discovery used the fallback.

4. Build the execution queue:

• If a root issue has open sub-issues, process the open sub-issues instead of the root implementation issue, unless the root also has its own explicit implementation checklist.
• Process dependency blockers before blocked issues.
• For sibling sub-issues without dependencies, process in ascending issue number unless the root issue or user gives a different priority.
• Include only issues that are open and labeled ready-for-agent. Skip sub-issues that are closed, missing ready-for-agent, labeled needs-info, labeled ready-for-human, or blocked by unresolved dependencies outside the queue.
• If an issue is blocked by another open issue that is not ready-for-agent, stop before implementation and report the blocker instead of working around it.
• If an issue is a parent/epic issue with sub-issues, do not run yarn agents:issue:run on the parent until all required sub-issues are completed or the parent has explicit remaining implementation work.
• Never process both a parent issue and its sub-issues as duplicate work in the same run.

Before starting, report the planned queue briefly. Do not ask for approval unless the user requested a dry run or the repo state is risky.