/execute-issue

Execute a Linear issue end-to-end with parallel agent dispatch

02 Build Input: Linear issue ID (+ optional PR/branch context) Output: PR to staging or review fixes merged into PR branch

Step

Human

Claude Code Agent

External Systems

Route

"Execute this issue"

May include PR/branch context for review fixes

Fetches issue and gathers routing signals: current branch/PR, issue description, developer arguments

mcp__linear__get_issue, list_comments, list_issues, gh pr list

Issue + children fetched

Linear

Route Decision

Standard

No PR/branch signals
New work → PR to staging

Review‑fixes

Signals point to a PR
Fixes → existing PR branch

Signals conflict or can't resolve target → ask developer

Plan

Determines task structure: Work Package or Single Issue

Work Package if sub-issues exist. Single Issue otherwise — creates sub-issues automatically if 4+ checklist items. Sets blockedBy relations from Execution Analysis or file overlap.

Pre-flight check: verifies tasks exist and no unresolved questions

If not ready, runs /validate-issue in a subagent to prepare the issue, then re-fetches

Plans execution order using pre-computed analysis, Linear relations, or on-the-fly analysis

Parses Execution Analysis section if present; falls back to file-overlap and logical-dep analysis. Posts execution order comment. Moves parent to In Progress.

mcp__linear__save_comment, save_issue

Execution order posted, status → In Progress

Linear

Setup

Creates worktree and branch

Standard: branches from origin/staging. Review-fixes: branches from origin/<pr-branch>.

git worktree add ../$REPO-$ID -b $BRANCH origin/staging|<pr-branch>

Worktree + branch created

Git

Loads orchestrator metadata: test/build commands, language guide path, design doc IDs

Orchestrator stays lean — extracts only commands from CLAUDE.md. Agents load their own files, guidelines, and design docs.

Read (CLAUDE.md scan only), mcp__linear__list_documents

Design doc IDs listed (content not fetched)

Linear

Dispatch

Creates local tasks with dependencies from analysis, Linear relations, or file-overlap

TaskCreate, TaskUpdate (addBlockedBy)

Parallel Agent Dispatch Loop

Agent A

Task 1
read → code → test → commit

Agent B

Task 2
read → code → test → commit

Agent C

Task 3
(blocked, waits)

All ready tasks dispatched in ONE message. File overlap = sequential. Cross-task context passed via metadata.

Repeats until all tasks complete

One commit per task. Sub-issue/checklist ticked per task.

GitLinear

Processes results: verifies commits, updates tasks and Linear

Re-fetches description before ticking checkboxes (handles concurrent updates). On failure: posts blocker comment, asks user, doesn't block unrelated tasks.

TaskUpdate, mcp__linear__save_comment, save_issue

Finds next ready tasks (unblocked), dispatches next batch

Blocked tasks run once their dependencies complete

Route

Runs full test suite from worktree

Stops if any test fails — diagnose and fix before continuing

go test ./... -v (or language equivalent)

Ship Path — Based on Execution Mode

Standard

New work
PR → staging

Review‑fixes

Code review changes
Merge → PR branch

Mode was determined during initial routing. Each path has its own ship sequence below.

Ship (standard)

Pushes branch, creates PR to staging

PR body: summary, per-task changes, test results, Linear link

git push -u origin $BRANCH && gh pr create --base staging

PR created, link posted on parent issue

GitHubLinear

Exits worktree (kept on disk), moves parent to In Review

ExitWorktree(action: "keep"), mcp__linear__save_issue

Status → In Review

Linear

Reports summary: tasks completed, commits, test results, PR URL, worktree path

Includes next steps: review PR, verify locally, cleanup after merge

Ship (review‑fixes)

Pushes review-fix branch, presents diff relative to PR branch

Shows: fix count, files changed, test results, target PR link

git push -u origin $BRANCH, git log origin/$PR_BRANCH..HEAD

"Ready to merge these fixes into the PR branch?"

Developer must confirm before fixes are merged into the PR branch

Required

If approved: exits worktree, enters PR worktree, merges and pushes

If declined: reports worktree location and branch name. Hard stop either way.

ExitWorktree, EnterWorktree, git merge, git push

Fixes merged into PR branch. Issue → Done.

GitLinear

Reports summary: fixes completed, commits, test results, PR fixed, merge status

Hard stop — no further work offered

Human

Agent

External

Decision gate