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.

Preflight

Before each issue:

1. Check git status --short.
2. If dirty, stop and report the files unless the user explicitly allowed --allow-dirty.
3. Fetch the issue details if needed:

gh issue view <issue-number> --comments

4. Confirm the issue still has ready-for-agent. If it does not, skip it and report why.

Run one issue

Use the repo wrapper. Do not reimplement branch, commit, or PR creation manually.

yarn agents:issue:run <issue-number>

Allowed overrides:

• --dry-run when the user asks for a plan or simulation only.
• --draft when validation is blocked or intentionally deferred.
• --no-pr when the user explicitly wants implementation without PR publication.
• --codex-sandbox workspace-write for static-only issues where host-level simulator access is not needed.
• --allow-dirty only when the user explicitly accepts the current dirty state.

The wrapper is expected to create branch, run Codex, commit tracked repo changes, push, attach evidence when present, and create a ready PR by default.

Failure handling

If agents:issue:run fails:

1. Do not start another issue.
2. Summarize the failed step and the issue number.
3. Check whether .scratch/issues/<issue-number>/mobile-validation.md, codex-final.md, change-summary.md, or pr-notes.md explains the blocker.
4. If the issue is blocked by missing info or policy, suggest moving it out of ready-for-agent; do not change labels unless the user asked you to manage labels.
5. Leave the repo state visible with git status --short.

Completion report

At the end, report:

• issues processed;
• PR URLs or branch names created;
• issues skipped and why;
• validation status;
• any dirty worktree state;
• recommended next human action, if any.

Keep the report short and factual.