/work-on-issue

Start focused work on a GitHub issue using TDD workflow.

EXECUTE THESE STEPS NOW

When this skill is invoked, you MUST execute these steps immediately. Do NOT just describe what will happen - actually do it.

Step 1: Parse Issue Number

Extract the issue number from $ARGUMENTS :

• Remove # prefix if present

• The issue number is: $ARGUMENTS

Step 2: Spawn Issue Worker Agent

Use the Task tool to spawn the issue-worker agent:

Task tool: subagent_type: issue-worker prompt: "Read GitHub issue #<NUMBER> and extract: 1. Goal - what the user wants to achieve 2. Acceptance criteria - specific testable requirements 3. Edge cases and constraints 4. Suggested PR split if complex"

Wait for the agent to return requirements.

Step 3: Create Worktree

After receiving requirements, run this command:

.claude/scripts/worktree-create.sh issue-<NUMBER>-<short-description>

Where <short-description> is 2-3 words from the goal (e.g., add-mcp-tools ).

Step 4: Activate TDD Enforcement

Activate TDD enforcement in the new worktree. This uses tdd-state.sh 's direct-execution mode so it works in a single Bash call:

cd .worktrees/issue-<NUMBER>-<short-description> && bash .claude/hooks/tdd-state.sh activate <NUMBER>

This writes .tdd-session.json to the worktree root, which all hooks check. Without this step, hooks would not block direct edits.

Step 5: Create Todos

Use TodoWrite to create a todo for EACH acceptance criterion:

TodoWrite: todos: - content: "Test: <acceptance criterion 1>" status: pending activeForm: "Testing <criterion 1>" - content: "Test: <acceptance criterion 2>" status: pending activeForm: "Testing <criterion 2>" ...

Step 6: Begin TDD Cycle

Immediately invoke /write-tests for the first todo.

DO NOT stop and wait for user input. Start the TDD cycle now.

When to Use

• Starting work on a GitHub issue

• You want TDD enforcement (opt-in via this skill)

• You want isolated work (no branch switching)

When NOT to Use

• Quick exploration (just stay in main repo)

• Already in a worktree for this issue

• Issue doesn't exist in GitHub

Workflow Overview

/work-on-issue #42 ↓ Step 1: Parse "42" from arguments ↓ Step 2: Spawn issue-worker → get requirements ↓ Step 3: Create worktree issue-42-<name> ↓ Step 4: Activate TDD enforcement (.tdd-session.json) ↓ Step 5: Create todos from acceptance criteria ↓ Step 6: Invoke /write-tests → begin TDD cycle

Important

This skill runs in the MAIN conversation context (not forked) because it needs to:

• Spawn the issue-worker agent and receive its results

• Run worktree-create.sh script

• Create todos that persist in the conversation

• Invoke /write-tests to continue the workflow

The issue-worker agent runs in a forked context and returns requirements.