Begin Work

Craft a prompt that gives an agent everything it needs to start or continue work on a GitHub issue in an isolated worktree.

When to use

Use this pattern when delegating issue work to an agent, whether a fresh start or picking up where a previous agent (or human) left off. The goal is a self-contained prompt that lets the agent work autonomously without needing to ask clarifying questions.

The pattern

Gather context before writing the prompt

Collect this information in parallel:

# Issue details
gh issue view <number>

# Existing worktrees for this issue
git worktree list

# If a PR exists: full history and unresolved review threads
gh pr view <pr-number> --json title,body,comments,reviews
gh api graphql -f query='
  query {
    repository(owner: "OWNER", name: "REPO") {
      pullRequest(number: PR_NUMBER) {
        reviewThreads(first: 100) {
          edges {
            node {
              isResolved
              comments(first: 10) {
                nodes {
                  author { login }
                  body
                  path
                  line
                }
              }
            }
          }
        }
      }
    }
  }
' | jq '[.data.repository.pullRequest.reviewThreads.edges[]
  | select(.node.isResolved == false)
  | .node.comments.nodes[]
  | {author: .author.login, path, line, body}]'

# If a branch exists: commits and diff
git log --oneline main..<branch>
git diff --stat main..<branch>

Prompt structure

Line 1: issue anchor

#<number>: <title>

Always lead with this. It orients the agent and makes the prompt scannable.

Context section

Provide enough background for the agent to understand what it's walking into:

• Fresh issue, no prior work: Summarize the issue body. Include any solution brief or acceptance criteria from the issue.
• Existing branch/PR: Describe the current architecture, what's been built, and how far along it is. Include the branch name and worktree path.
• Prior review rounds: Summarize the review history (how many rounds, what changed, what the reviewer's main concerns were).

Current state section

Tell the agent exactly what exists right now:

• Branch name and worktree path (or note that one needs to be created)
• Commit history on the branch (summarized)
• Uncommitted changes (if any)
• Unrelated changes that need to be separated out

Unresolved feedback section

For PRs with review history, list each piece of unresolved feedback:

1. Quote or paraphrase the reviewer's comment
2. Note the file and line if available
3. Distinguish between feedback that's been addressed in code but not marked resolved vs. feedback that still needs work

What to do section

An ordered list of concrete steps. Be specific:

• "Read the current code in the worktree" (not "understand the codebase")
• "Address the glob matching feedback in linter.js:20" (not "fix review comments")
• "Run node --test linters/linter.test.js" (not "run the tests")
• "Push and reply to unresolved threads with 'Done'" (not "update the PR")

Worktree instructions

When a worktree already exists

Include the path and branch name:

The code is on branch `feature/auth` with a local worktree at
`feature/auth` (a directory in the repository container). Work there, not in
another worktree.

When a worktree needs to be created

No worktree exists yet. Create one following the git worktrees skill, from the
container root:
`git worktree add <branch-name> -b <branch-name> origin/main`

Scope control

If the branch contains unrelated changes (common with long-lived branches or agent-created PRs), call them out explicitly:

The branch also contains unrelated changes to X and Y. These need to be
separated out — the PR should only contain work related to this issue.

Copy to clipboard

Write the finished prompt to /tmp/begin-work-<issue-number>.md using the Write tool, then copy it to the clipboard:

LANG=en_US.UTF-8 pbcopy < /tmp/begin-work-<issue-number>.md

Do not use heredocs with pbcopy. Heredocs mangle backticks and special characters. And without LANG=en_US.UTF-8, pbcopy misinterprets UTF-8 multi-byte characters (e.g., em dashes render as —).

Trade-offs

• Too much context slows the agent down and wastes tokens on irrelevant detail. Summarize; don't paste raw API output.
• Too little context forces the agent to discover things itself, risking wrong assumptions. When in doubt, include it.
• Stale context is worse than no context. If the branch has been rebased or force-pushed since the review comments, note that.