execute-task

Execute Task

Implement a Linear task end-to-end: build it, QA it, ship a PR, pass CI, and hand off for review.

This skill supports parallel execution — multiple Claude sessions can each run /execute-task simultaneously. Each session works in an isolated git worktree and claims tasks atomically in Linear to avoid collisions. If a session is interrupted, a new session will automatically resume the incomplete work.

Discovered Tasks

Throughout execution, you may notice things that need to be done but are out of scope for the current task — missing pages, broken links, inconsistencies, TODO comments, accessibility gaps, etc. Do not fix these inline. Instead, keep a running list of discovered items (a mental note is fine — you'll surface them in Phase 6). Each item needs: a short title, a 1-2 sentence description, and which task it was discovered during.

---

Step 0: Get the Task

If a task ID, title, and description were provided in your prompt:

1. Enter a worktree for isolation:

   EnterWorktree with name: "task-main-XXX"
   

2. Update the status line:

   echo '{"linear":"<TASK-ID>","linear_url":"https://linear.app/<workspace>/issue/<TASK-ID>"}' > /tmp/claude-session-meta-$PPID
   

3. Rename the session to the Linear ticket ID (e.g. MAIN-123) using /rename.
4. Set up the branch and draft PR inside the worktree, then skip to Step 1 (Triage).

If no task was specified — read references/task-discovery.md and follow it. It handles task discovery, atomic claiming, worktree entry, branch setup, and the status line update. Then return here for Step 1.

---

Step 1: Triage — How Big Is This Task?

Read the task description and acceptance criteria. Classify the scope:

Trivial — Single file, < ~10 lines of changes. Examples: adding a config entry, fixing a typo, updating a meta tag, changing a URL. → Stay on this page. Follow Phase 1 (Gather Context) then Phase 2 (Implement) below, doing the work directly.

Substantial — New page, multi-file changes, new feature with JS/CSS/HTML coordination, or any task with 3+ discrete work items. → Read references/parallel-workflow.md for the full parallel orchestration workflow. That file covers research agents, task decomposition, parallel subagent execution, and integration. After completing its phases, return here for Phase 3 (QA) onward.

---

Phase 1: Gather Context

1. Task description — provided in your prompt. This is the primary specification. Read every section, especially acceptance criteria.
2. CLAUDE.md — loaded automatically. Contains all build rules, project architecture, design references, and Linear configuration. Treat it as law.
3. Design references — if the task involves building a page or component, check CLAUDE.md for design reference information (e.g., design file node IDs, mockups, or style guides). Inspect the designs before implementing.

Phase 2: Implement

Follow the task description's requirements and acceptance criteria precisely. Respect every rule in CLAUDE.md. Use any available skills that are appropriate for the work.

Write tests if infrastructure exists

Check if testing infrastructure is set up (look for tests/ directory and test deps in package.json):

• Unit tests — for any new logic
• E2E tests — for any new pages or flows

If no testing infrastructure exists yet, skip this.

Phase 3: Quality Assurance

Run project checks

Run the project's build and lint commands (see CLAUDE.md for the exact commands). These are blocking requirements. If any fail:

1. Read the error output carefully
2. Fix the issues
3. Re-run until they pass
4. Do NOT proceed with failing checks

Run code simplifier

Invoke the /simplify skill to review the implementation for clarity, consistency, and maintainability. Review its changes — accept improvements that preserve behavior, revert anything that changes functionality.

Verify acceptance criteria

Re-read the task's acceptance criteria section. Go through each criterion explicitly and verify it's met. If any isn't met, fix it before proceeding.

Phase 4: Commit & PR

Commit

Invoke the /commit-commands:commit skill to stage and commit. The commit body should reference the Linear issue (e.g., "Implements MAIN-XXX: task title").

Push and update PR

The draft PR was already created during task discovery (Step 6) with the correct base branch. Do NOT create a new PR — update the existing one.

git push origin <branch-name>

Update the PR title and body with the final implementation details:

gh pr edit <pr-number> \
  --title "<MAIN-XXX>: <concise title>" \
  --body "$(cat <<'EOF'
## Summary
<2-3 bullet points of what was implemented>

Closes <MAIN-XXX>

## Changes
<list of files added/modified and why>

## Test plan
- [ ] Build and lint checks pass
- [ ] <task-specific acceptance criteria as checklist items>

Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Mark the PR as ready for review:

gh pr ready <pr-number>

Update the status line with the PR URL:

echo '{"linear":"<TASK-ID>","linear_url":"https://linear.app/<workspace>/issue/<TASK-ID>","pr":"<pr-url>"}' > /tmp/claude-session-meta-$PPID

Phase 5: CI & Copilot Review Loop

Step 1: Monitor CI checks

Poll for CI status (timeout after 10 minutes):

gh pr checks <pr-number> --json name,state,bucket

Check every 30 seconds. Wait until all checks have a bucket of pass or fail (not pending). If still pending after 10 minutes, add a PR comment noting the timeout and proceed.

If any check fails, invoke the /pr-fix-ci skill to diagnose and fix the failures.

Step 2: Browser QA via Playwright CLI

IMPORTANT: Use ONLY the /playwright-cli skill for all browser QA. Do NOT use mcp__claude-in-chrome__* tools, mcp__claude-in-chrome__navigate, or any other Chrome/browser MCP tools. Playwright CLI runs headless and works reliably in automated workflows. Chrome MCP tools require an active browser session and are not appropriate here.

Once CI passes, check if a deploy preview is available (e.g., Netlify, Vercel):

DEPLOY_URL=$(gh api repos/{owner}/{repo}/statuses/$(gh pr view <pr-number> --json headRefOid --jq '.headRefOid') \
  --jq '[.[] | select(.target_url | test("deploy-preview"))] | first | .target_url // empty')

If a deploy preview URL is available, run browser QA using the /playwright-cli skill:

1. Open the preview and verify it loads:

   playwright-cli open "$DEPLOY_URL"
   playwright-cli snapshot --filename=deploy-preview-check.yml
   

2. Check for console errors:

   playwright-cli console error
   

3. Take a screenshot for visual reference:

   playwright-cli screenshot --filename=deploy-preview-screenshot.png
   

4. Clean up:

   playwright-cli close
   

If browser QA finds issues (max 2 fix rounds):

1. Fix the code locally
2. Run project build/lint checks to verify the fix
3. Commit: fix: address browser QA issue — <description>
4. Push and wait for the new deploy preview

After 2 failed fix rounds, add a PR comment describing the issue and proceed.

If no deploy preview is available, skip browser QA.

Step 3: Copilot review

Request Copilot review:

gh pr edit <pr-number> --add-reviewer @copilot

Poll every 30 seconds (timeout after 10 minutes):

gh api repos/{owner}/{repo}/pulls/<pr-number>/reviews \
  --jq '[.[] | select(.user.login == "copilot-pull-request-reviewer[bot]")] | last | .state'

Wait until the review state is COMMENTED, CHANGES_REQUESTED, or APPROVED. If still pending after 10 minutes, proceed to handoff.

If Copilot leaves comments, invoke the /pr-fix-comments skill to triage and address them.

Step 4: Final CI check

After the last push, re-verify CI passes before proceeding to handoff.

Phase 6: Handoff

Update Linear state

Move the task to In Review and link the PR. Use the Linear agent name from CLAUDE.md:

linear issue update <TASK-ID> --agent <agent-name> --state "In Review"
linear comment add <TASK-ID> --agent <agent-name> --body "Implementation complete. PR: <pr-url>"

Request human review

Request review from the reviewer specified in CLAUDE.md:

gh pr edit <pr-number> --add-reviewer <reviewer-username>

If gh errors on the username, add a PR comment instead requesting review.

Surface discovered tasks

If you noted any out-of-scope items during execution, present them now. For each item, use AskUserQuestion to ask whether to create a Linear issue for it. Batch up to 4 items per question (the tool's limit), using multiSelect so the user can approve several at once.

Example:

AskUserQuestion:
  question: "I found these out-of-scope items during MAIN-XXX. Create Linear issues for any of them?"
  header: "New tasks"
  multiSelect: true
  options:
    - label: "<short title>"
      description: "<1-2 sentence description of what needs doing>"
    - label: "<short title>"
      description: "<description>"
    ...

For each approved item, create a Linear issue in the same project (get project name and agent from CLAUDE.md):

linear issue create --agent <agent-name> \
  --title "<title>" \
  --description "<description>\n\nDiscovered during: MAIN-XXX" \
  --project "<project-name>" \
  --team "<team-name>" \
  --state "Backlog"

If no items were discovered, skip this step.

Stay in the worktree

Do NOT exit the worktree. The session remains in the worktree so follow-up skills (/pr-fix-comments, /pr-fix-ci) can operate on the same branch without re-checking it out or losing worktree isolation. The worktree will be cleaned up by a future /execute-task session once the PR is merged and the Linear issue is Done (see Step 0 in task-discovery.md).

Print summary

Task: MAIN-XXX — <title>
Branch: <branch-name>
PR: <pr-url>
Worktree: <worktree-path> (kept for follow-up)
Discovered tasks created: <N>
Status: Ready for human review — session is available for /pr-fix-comments or /pr-fix-ci

Error Recovery

If an unrecoverable error occurs:

1. Comment on the Linear issue explaining the failure:

   linear comment add <TASK-ID> --agent <agent-name> --body "Agent encountered an error: <brief description>. Task left In Progress for retry."
   

2. Leave the task In Progress and the worktree intact — the next /execute-task session will detect the In Progress task assigned to build-agent, find the existing worktree, and resume it automatically.
3. Do NOT exit the worktree — stay in it so the session (or a follow-up) can retry.
4. Do NOT move the task backward or mark it as Todo again.

Important Constraints

• Never force-push or amend commits.
• Never skip build/lint checks — they're blocking gates.
• Never git add -A — always stage specific files.
• Never commit secrets — no API keys, no .env files, no webhook tokens.
• CLAUDE.md is law — every build rule must be followed. When in doubt, re-read it.
• Linear CLI — always use the agent name specified in CLAUDE.md for all linear commands.
• Browser QA uses /playwright-cli only — never use mcp__claude-in-chrome__* or other Chrome MCP tools for browser testing.
• Self-contained Linear management — this skill manages its own Linear state transitions (In Progress → In Review). No external orchestrator is assumed.