itx-execute

Issue Execution

Execute the implementation plan for a GitHub issue.

Orchestrate Mode

Triggered by orchestrate as the first token in arguments (e.g. /itx-execute orchestrate 112). Use when the issue is a parent with linked subtasks and you want a hands-off, stacked-PR pipeline across all subtasks.

Preconditions

• Parent issue exists and has sub-issues linked (via GitHub addSubIssue). Detect via:

  gh issue view <parent> --json title,body,labels && \
  gh api graphql -f query='query($owner: String!, $repo: String!, $num: Int!) {
    repository(owner: $owner, name: $repo) {
      issue(number: $num) {
        subIssues(first: 50) { nodes { number title state } }
      }
    }
  }' -f owner="$OWNER" -f repo="$REPO" -F num=<parent>
  

• tmux available on the host. If not, fail with a clear message — orchestrate mode requires tmux.
• A plan file exists at .itx/<parent>/00_PLAN.md (created by /itx-plan-create). Refuse to start otherwise.

ATX availability is not a precondition. Children use the fallback chain in ATX Review below. Handoff is still keyed on PR-open — without ATX, that just means the child opens the PR after local make test + make lint pass instead of after an ATX rating clears.

Orchestration contract

The orchestrator (the claude session that runs orchestrate mode) does only these things:

1. Creates worktrees + branches + tmux windows for each subtask.
2. Spawns a child claude session per subtask via claude --dangerously-skip-permissions '/itx-execute <N>' in the subtask's worktree.
3. Polls subtask PR state every ~5 minutes.
4. When a subtask's PR appears (the child's handoff signal), spawns the next subtask with the correct stacked base.
5. Surfaces stuck children (PRs carrying [ITX-STUCK]) in the end-of-run summary table, but does not halt the pipeline waiting for user input — see "Stuck child" below.

The orchestrator does NOT:

• Touch source code.
• Run tests / lint directly.
• Merge PRs. Merging is the user's decision.
• Block on user input. If something requires a decision, the child records it as a Callout on its PR and proceeds.
• Bypass ATX when ATX is available; bypass --no-verify.
• Spawn all subtask windows up front. Windows are created on demand when the predecessor's PR is open.