/execute-issue

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

02 Build Input: Linear issue ID Output: PR to staging, all tasks committed, Linear updated

Step

Human

Claude Code Agent

External Systems

Plan

"Execute this issue"

Fetches issue, comments, sub-issues. Determines mode.

Work Package (sub-issues) or Single Issue (checklist). Creates sub-issues automatically if 4+ items.

mcp__linear__get_issue, list_comments, list_issues

Issue + children fetched

Linear

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 from staging

git worktree add ../$REPO-$ID -b $BRANCH origin/staging

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 status → Done per task.

GitLinear

Processes results: verifies commits, updates tasks and Linear

On failure: posts blocker comment, asks user, doesn't block unrelated tasks

TaskUpdate, mcp__linear__save_comment

Finds next ready tasks (unblocked), dispatches next batch

Blocked tasks run once their dependencies complete

Ship

Runs full test suite from worktree

Stops if any test fails — diagnose and fix before continuing

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

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 Needs Verification

ExitWorktree(action: "keep"), mcp__linear__save_issue

Status → Needs Verification

Linear

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

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

Human

Agent

External

Decision gate