granite.build: Command for Claude Code

Start Work on a GitHub Issue

You are helping a developer start work on a GitHub issue. You will verify pre-conditions, create an isolated git worktree, load the issue and architecture documentation, assess what's already been implemented, and plan the work. Follow these steps in order, stopping if any step fails.

Issue number: $ARGUMENTS

Defaults

These values can be overridden by the user but apply by default:

ARCH_DOC_1=docs/plans/2026-02-23-architecture.md
ARCH_DOC_2=docs/plans/2026-02-18-standalone-deployment-design.md
WORKTREE_BASE=../granite.build-worktrees

Derive the fork owner and repo:

FORK_OWNER=$(git remote get-url origin | sed -E 's|.*[:/]([^/]+)/.*|\1|')
FORK_REPO=$(git remote get-url origin | sed -E 's|.*[:/][^/]+/(.*)$|\1|' | sed 's/\.git$//')

Step 0: Pre-flight checks

1. If $ARGUMENTS is empty or not a number, show usage and stop:

   Usage: /start-issue <issue-number>
   Example: /start-issue 42
   

2. Confirm we are on the main branch:

   git branch --show-current
   

   If not on main, warn the user and ask whether to switch (git checkout main) or abort.
3. Check for uncommitted changes:

   git status --porcelain
   

   If there are uncommitted changes, ask the user what to do:
   • Commit them before proceeding (always use git commit -s — the upstream repo enforces the DCO check)
   • Stash them (git stash push -m "stash before issue-$ARGUMENTS")
   • Abort and let the user handle it manually
4. Fetch the latest upstream:

   git fetch upstream
   

Step 1: Create branch and worktree

1. Fetch the issue title to verify the issue exists and to derive the branch name:

   gh issue view $ARGUMENTS --repo "$FORK_OWNER/$FORK_REPO" --json title --template '{{.title}}'
   

   If the command fails (issue doesn't exist), report the error and stop.

2. Slugify the title: lowercase, replace non-alphanumeric characters with hyphens, collapse consecutive hyphens, strip leading/trailing hyphens, truncate the slug so the total branch name (issue-$ARGUMENTS-<slug>) stays under 50 characters. Branch name: issue-$ARGUMENTS-<slug>