Start

Start

Begins a new piece of work. Two modes — the skill determines which applies:

• User provides an issue number, URL, or reference → EXISTING ISSUE mode
• User provides a description of what needs doing → NEW ISSUE mode

For branch naming and commit format, follow the conventions skill.

Step 0 — Auth & Identity

Check for a GitHub MCP server in available tools. If none, run:

gh auth status

If neither is available, stop: "I need the GitHub MCP server or gh CLI authenticated to continue. Run gh auth login or connect the GitHub MCP server."

Confirm identity — use mcp__github__get_me if the GitHub MCP server is available, otherwise:

gh api user --jq '"@\(.login) — \(.name)"'

Show the result and ask: "I'll be acting as @username — is that right?" Wait for confirmation before continuing.

EXISTING ISSUE Mode

Step 1 — Fetch the Issue

From the issue number or URL, fetch the issue:

gh issue view <number> --json number,title,body,labels,url

Display the issue number, title, and first few lines of the body. Ask: "Is this the right issue to work on?" Wait for confirmation.

Step 2 — Start from Main

git checkout main
git pull origin main
git status --porcelain   # must be empty — abort if dirty

Step 3 — Cut the Branch

Derive the slug from the issue title: lowercase, hyphenated, 2–4 meaningful words, no stop words.

Determine branch prefix from issue labels:

• bug label → fix/
• enhancement or feature label → feature/
• Anything else → feature/ by default

git checkout -b <prefix><issue-number>-<slug>

Example: feature/14-add-handoff-skill or fix/23-vault-scribe-toc

Report: "Branch feature/14-add-handoff-skill created from main. You're ready to work."

NEW ISSUE Mode

Step 1 — Classify the Work

From the user's description, determine: is this a feature (new capability, new skill, enhancement) or a bug (something broken, incorrect behaviour, wrong output)?

If ambiguous, ask one question: "Is this adding something new or fixing something broken?"

Step 2 — Draft the Issue

Read the appropriate template from .github/ISSUE_TEMPLATE/:

• Feature → .github/ISSUE_TEMPLATE/feature_request.md
• Bug → .github/ISSUE_TEMPLATE/bug_report.md

Fill in every section of the template from the user's description. Show the completed draft to the user. Ask: "Does this capture what you need? Edit anything before I submit it." Wait for approval.

Step 3 — Create the Issue

gh issue create \
  --title "<title>" \
  --body "<filled template body>" \
  --label "<enhancement|bug>"

Use enhancement for features (matches feature_request.md template label), bug for bugs.

Capture the returned issue number and URL. Report: "Issue #N created: "

Step 4 — Cut the Branch

Proceed identically to EXISTING ISSUE Steps 2–3, using the new issue number.