Issue-Driven Development

A Claude Code plugin for autonomous, GitHub-native software development. Work through issues, create PRs, and ship code - all without manual intervention.

New to Claude Code? Install the plugin, run claude-autonomous, and watch it work through your GitHub issues.

Experienced developer? Full TDD, strict typing, IPv6-first networking, parallel workers, and crash recovery included.

Quick Start

One-Line Install

curl -fsSL https://raw.githubusercontent.com/troykelly/claude-skills/main/install.sh | bash

This installs everything: dependencies, Claude Code CLI, the plugin, and CLI tools.

First Use

claude-autonomous

That's it. Claude will find your open GitHub issues and start working through them autonomously.

Plugin-Only Install (Existing Claude Code Users)

/plugin marketplace add troykelly/claude-skills
/plugin install issue-driven-development@troykelly-skills

Restart Claude Code after installation.

What's Included

CLI Tools

51 Skills

Skills guide Claude through disciplined workflows. They're automatically invoked based on what you're doing.

Full skills reference below

9 Agents

Specialized agents for specific tasks:

Multi-Account Management

The claude-account tool lets you switch between Claude accounts without re-authenticating each time. When running autonomously, the plugin automatically switches accounts when plan limits are reached.

Commands

claude-account capture           # Save current logged-in account
claude-account list              # Show all saved accounts
claude-account list --available  # Show accounts not in cooldown
claude-account current           # Show active account
claude-account switch            # Rotate to next account
claude-account switch <email>    # Switch to specific account
claude-account next              # Print next available account (for scripts)
claude-account status            # Show exhaustion status of all accounts
claude-account remove <email>    # Remove saved account

How It Works

1. Capture: After logging into Claude Code (/login), run claude-account capture to save credentials
2. Store: Credentials are saved to .env in your project (gitignored) and platform credential storage
3. Switch: Use claude-account switch to swap between saved accounts instantly

Platform Support

Devcontainer Workflow

For persistent accounts across container rebuilds:

1. Capture accounts: claude-account capture
2. Sync .env to 1Password or another secrets manager
3. On rebuild, restore .env and run claude-account switch <email>

.env Format

# Managed by claude-account - accounts derived from CLAUDE_ACCOUNT_*_EMAILADDRESS variables
CLAUDE_ACCOUNT_USER_EXAMPLE_COM_EMAILADDRESS="[email protected]"
CLAUDE_ACCOUNT_USER_EXAMPLE_COM_ACCESSTOKEN="sk-ant-oat01-..."
CLAUDE_ACCOUNT_USER_EXAMPLE_COM_REFRESHTOKEN="sk-ant-ort01-..."
# ... additional fields per account

Automatic Plan Limit Switching

When running with claude-autonomous, the plugin automatically detects plan limits and switches accounts:

1. Detection: A Stop hook monitors for plan limit patterns (rate limit, quota exceeded, 429 errors, etc.)
2. Mark Exhausted: The current account is marked as exhausted with a timestamp
3. Switch: Automatically rotates to the next available account (round-robin)
4. Resume: Work continues with the new account
5. Cooldown: Exhausted accounts become available again after 5 minutes (configurable)

Session startup shows account status:

Checking Claude account status...
  ✓ Current account: [email protected]
  ✓ Multi-account switching: enabled
  │ Total accounts: 3
  │ Available (not exhausted): 3

  Account switch order:
    [email protected] (current)
    → [email protected] → [email protected]

Environment variables:

Flap protection: If all accounts are exhausted (rapid switching detected), the system waits for cooldown before continuing.

Autonomous Mode

Basic Usage

claude-autonomous                    # Work on all open issues
claude-autonomous --epic 42          # Focus on specific epic
claude-autonomous --pr               # Resolve open PRs (CI fixes, reviews, merges)
claude-autonomous --new              # Start fresh, wait for instructions
claude-autonomous --continue         # Resume most recent session
claude-autonomous --resume           # Open session picker
claude-autonomous --list             # Show session history

Options

What It Does

1. Creates isolated worktree from origin/main for safe parallel work
2. Finds open issues in your GitHub project
3. Works through them following TDD, code review, and PR creation
4. Recovers from crashes automatically with session resumption
5. Detects crash loops and adjusts approach after repeated failures

Parallel Workers

Run multiple agents on different epics simultaneously:

# Terminal 1
claude-autonomous --epic 10

# Terminal 2
claude-autonomous --epic 15

# Terminal 3
claude-autonomous

Each agent works in its own isolated worktree.

Session Management

Sessions are stored by Claude Code in ~/.claude/projects/<encoded-path>/ and are directory-scoped. The script handles this automatically:

1. Worktrees are preserved on crash - Non-zero exits keep the worktree intact to avoid losing uncommitted work
2. Worktrees are recreated on resume - If the worktree was deleted, it's recreated at the same path before resuming
3. Run resume from the original repository - The script needs git context to recreate worktrees

# View session history (our worktree log)
claude-autonomous --list

# Resume most recent session (uses our logged session ID)
claude-autonomous --continue

# Open Claude's interactive session picker
claude-autonomous --resume

# Resume specific session by ID
claude-autonomous --resume <uuid-from-list>

Our log at /tmp/claude-sessions.txt tracks worktree sessions with format: timestamp session_id repo_name worktree_path details

How It Survives

1. Crash Recovery: The while loop auto-restarts Claude with --resume using the same session ID
2. Context Compaction: ActiveOrchestration marker in MCP Memory triggers automatic resume
3. State Persistence: All work state lives in GitHub (project board, issues, PRs) - nothing is lost

What The Orchestrator Does

1. Bootstrap: Resolve any existing open PRs before starting new work
2. Detect Scope: Find all open issues, epics, and milestones
3. Spawn Workers: Run up to 5 parallel workers in isolated git worktrees
4. Monitor CI: Watch PR checks, auto-merge when passing (with review artifacts)
5. Handle Failures: Research and retry failed tasks up to 3 times before blocking
6. Sleep/Wake: Enter sleep mode when waiting on CI, wake on next session
7. Complete: Exit when no issues, PRs, or in-progress work remains

Crash Recovery

Monitoring Progress

# View session log
tail -f /tmp/claude-sessions.txt

# Check GitHub project status
gh project item-list $GITHUB_PROJECT_NUM --owner "$GH_PROJECT_OWNER" --format json | \
  jq '.items[] | {number: .content.number, title: .content.title, status: .status.name}'

# Check orchestration tracking issue
gh issue list --label "orchestration-tracking" --json number,title,state

Stopping Autonomous Mode

To gracefully stop:

1. Create a do-not-merge label on any PR to pause merging
2. Close the orchestration tracking issue
3. Or simply Ctrl+C - state is preserved in GitHub, resume anytime

<details> <summary><strong>Manual Autonomous Script</strong></summary>

For customization or debugging, here's the full script with crash loop detection:

SESSION_ID=$(uuidgen || cat /proc/sys/kernel/random/uuid) && \
REPO_ROOT=$(git rev-parse --show-toplevel) && \
REPO_NAME=$(basename "${REPO_ROOT}") && \
WORKTREE_DIR="/tmp/claude-worktrees/${REPO_NAME}/${SESSION_ID}" && \
echo "$(date -Iseconds) ${SESSION_ID}" >> /tmp/claude-sessions.txt && \
git fetch origin main && \
git worktree add "${WORKTREE_DIR}" origin/main && \
cleanup() { \
  echo "Cleaning up worktree ${WORKTREE_DIR}..."; \
  cd "${REPO_ROOT}" && \
  git worktree remove --force "${WORKTREE_DIR}" 2>/dev/null; \
  echo "Session ${SESSION_ID} ended at $(date -Iseconds)"; \
} && \
trap cleanup EXIT && \
cd "${WORKTREE_DIR}" && \
clear && \
echo "Session ID: ${SESSION_ID}" && \
echo "Worktree: ${WORKTREE_DIR}" && \
if [ -n "${WORK_EPIC}" ]; then \
  echo "Focus Epic: #${WORK_EPIC}"; \
  EPIC_INSTRUCTION="Focus exclusively on Epic #${WORK_EPIC} and its child issues. Do not work on unrelated issues."; \
else \
  EPIC_INSTRUCTION="Work through all open epics and issues in priority order."; \
fi && \
INITIAL_PROMPT="You are working in an isolated git worktree at: ${WORKTREE_DIR}

This worktree was created from origin/main to allow multiple agents to work in parallel without conflicts. Your session ID is ${SESSION_ID}.

IMPORTANT WORKFLOW NOTES:
- You have your own isolated copy of the codebase - other agents may be working in parallel
- Create feature branches for your work and push them to origin
- Open PRs when work is complete - do not merge directly to main
- If you need latest changes from main, you can pull origin/main into your worktree

TASK: Use your issue driven development skill to work wholly autonomously until all assigned work is complete.

${EPIC_INSTRUCTION}" && \
CRASH_TIMES=() && \
CRASH_WINDOW=60 && \
CRASH_THRESHOLD=3 && \
claude --dangerously-skip-permissions --session-id "${SESSION_ID}" "${INITIAL_PROMPT}" || \
while true; do \
  NOW=$(date +%s) && \
  CRASH_TIMES+=("$NOW") && \
  RECENT_CRASHES=0 && \
  for T in "${CRASH_TIMES[@]}"; do \
    if (( NOW - T < CRASH_WINDOW )); then \
      ((RECENT_CRASHES++)); \
    fi; \
  done && \
  if (( RECENT_CRASHES >= CRASH_THRESHOLD )); then \
    echo "Warning: Rapid crash loop detected ($RECENT_CRASHES crashes in ${CRASH_WINDOW}s)"; \
    MSG="CRITICAL: You have crashed $RECENT_CRASHES times in the last ${CRASH_WINDOW} seconds. This indicates a crash loop - something you are repeatedly doing is causing you to crash (likely OOM from large test output, or a runaway process). STOP and think carefully: What were you doing? Do NOT repeat the same action. Consider: 1) Running smaller test subsets, 2) Adding output limits, 3) Taking a different approach entirely. Explain your analysis before proceeding."; \
    sleep 10; \
  else \
    echo "Restarting after crash... (Session: ${SESSION_ID})"; \
    MSG="You crashed or ran out of memory. This happens occasionally - continue where you left off autonomously."; \
    sleep 3; \
  fi && \
  claude --dangerously-skip-permissions --resume "${SESSION_ID}" "$MSG" && break; \
done

</details>

Configuration

Environment Variables

Required:

Optional:

GitHub Project Fields

Your project needs these custom fields:

Create them via GitHub UI or CLI:

GH_PROJECT_OWNER="@me"  # Use org name for org projects

gh project field-create $GITHUB_PROJECT_NUM --owner "$GH_PROJECT_OWNER" \
  --name "Verification" --data-type "SINGLE_SELECT" \
  --single-select-options "Not Verified,Failing,Partial,Passing"

gh project field-create $GITHUB_PROJECT_NUM --owner "$GH_PROJECT_OWNER" \
  --name "Priority" --data-type "SINGLE_SELECT" \
  --single-select-options "Critical,High,Medium,Low"

gh project field-create $GITHUB_PROJECT_NUM --owner "$GH_PROJECT_OWNER" \
  --name "Type" --data-type "SINGLE_SELECT" \
  --single-select-options "Feature,Bug,Chore,Research,Spike"

<details> <summary><strong>All Field Creation Commands</strong></summary>

gh project field-create $GITHUB_PROJECT_NUM --owner "$GH_PROJECT_OWNER" --name "Criteria Met" --data-type "NUMBER"
gh project field-create $GITHUB_PROJECT_NUM --owner "$GH_PROJECT_OWNER" --name "Criteria Total" --data-type "NUMBER"
gh project field-create $GITHUB_PROJECT_NUM --owner "$GH_PROJECT_OWNER" --name "Last Verified" --data-type "DATE"
gh project field-create $GITHUB_PROJECT_NUM --owner "$GH_PROJECT_OWNER" --name "Verified By" --data-type "TEXT"

</details>

Labels

gh label create "parent" --color "0E8A16" --description "Issue has sub-issues"
gh label create "sub-issue" --color "1D76DB" --description "Issue is child of parent"
gh label create "blocked" --color "D93F0B" --description "Cannot proceed"
gh label create "needs-research" --color "FBCA04" --description "Research required"
gh label create "verified" --color "0E8A16" --description "E2E verification passed"

Required CLI Tools

Optional CLI Tools

Required MCP Servers

Recommended MCP Servers

Required Plugins

Skills Reference

<details> <summary><strong>Workflow & Orchestration</strong> (8 skills)</summary>

</details>

<details> <summary><strong>Issue & Project Management</strong> (5 skills)</summary>

</details>

<details> <summary><strong>Work Planning & Architecture</strong> (4 skills)</summary>

</details>

<details> <summary><strong>Development Standards</strong> (7 skills)</summary>

</details>

<details> <summary><strong>Code Review</strong> (3 skills)</summary>

</details>

<details> <summary><strong>PR & CI</strong> (3 skills)</summary>

</details>

<details> <summary><strong>Research & Memory</strong> (3 skills)</summary>

</details>

<details> <summary><strong>Branch & Git</strong> (2 skills)</summary>

</details>

<details> <summary><strong>Documentation Enforcement</strong> (3 skills)</summary>

</details>

<details> <summary><strong>Database</strong> (4 skills) - PostgreSQL 18, PostGIS 3.6.1, TimescaleDB 2.24.0</summary>

</details>

<details> <summary><strong>Recovery & Environment</strong> (3 skills)</summary>

</details>

<details> <summary><strong>Other Skills</strong></summary>

</details>

The 13-Step Workflow

This is the master process that issue-driven-development implements:

 1. ISSUE CHECK      → Ensure GitHub issue exists
 2. READ COMMENTS    → Check for context and updates
 3. SIZE CHECK       → Break large issues into sub-issues
 4. MEMORY SEARCH    → Find previous work on related issues
 5. RESEARCH         → Gather needed information
 6. BRANCH CHECK     → Create/switch to feature branch
 7. TDD DEVELOPMENT  → Write tests first, then code
 8. VERIFICATION     → Verify acceptance criteria
 9. CODE REVIEW      → Review against 7 criteria
10. IMPLEMENT FIXES  → Apply all review findings
11. RUN TESTS        → Full test suite
12. RAISE PR         → Create with complete documentation
13. CI MONITORING    → Watch CI, resolve issues

Issue updates happen continuously throughout, not as a separate step.

Verification Report Format

When verifying acceptance criteria, post structured comments to issues:

## Verification Report
**Run**: 2024-12-02T14:30:00Z
**By**: agent

### Results
| Criterion | Status | Notes |
|-----------|--------|-------|
| User can click "New Chat" button | PASS | |
| New conversation appears in sidebar | PASS | |
| Chat area shows welcome state | FAIL | Welcome message not rendering |
| Previous conversation is preserved | PARTIAL | Works but slow |

### Summary
- **Passing**: 2/4
- **Failing**: 1/4
- **Partial**: 1/4

### Next Steps
- Investigate welcome message rendering issue
- Profile conversation preservation performance

Philosophy

This plugin enforces disciplined, issue-driven development based on Anthropic's research on effective harnesses for long-running agents.

Core Principles

Absolute Rules

These override any other instructions:

• Disregard token minimization - Work thoroughly, not quickly
• Disregard time pressure - Quality over speed
• No deferred work - No TODOs, no "we'll fix this later"

Troubleshooting

<details> <summary><strong>MCP Server Installation</strong></summary>

If MCP servers don't start:

# Git server
pip install mcp-server-git

# Node.js servers
pnpm add -g @modelcontextprotocol/server-memory
pnpm add -g @modelcontextprotocol/server-github
npx playwright install --with-deps chromium

</details>

<details> <summary><strong>Configure CLAUDE.md for Your Project</strong></summary>

For best results, configure your project's CLAUDE.md with instructions that reinforce the issue-driven workflow. Copy the following prompt and paste it into a Claude Code session in your project directory:

Please update my CLAUDE.md file with development instructions optimized for the issue-driven-development plugin.

IMPORTANT: First, remove any existing sections that might conflict with issue-driven development workflows (sections about commit styles, PR processes, testing workflows, code review, documentation requirements, or development methodology). Keep any project-specific configuration like API keys, server addresses, or domain-specific knowledge.

Then add the following instructions:

---

## Development Methodology

This project uses the `issue-driven-development` plugin. All work MUST follow its skills and protocols.

### Foundational Rules

1. **No work without an issue** - Every change requires a GitHub issue first
2. **Never work on main** - All work happens in feature branches
3. **Research before action** - Your training data is stale; research current patterns before coding
4. **Skills are mandatory** - If a skill exists for what you're doing, you MUST use it
5. **Verify before claiming** - Prove things work with evidence before stating completion

### Anti-Shortcut Enforcement

These behaviors are FAILURES that require stopping and redoing:

| Prohibited Behavior | Why It's Wrong |
|---------------------|----------------|
| Skipping code review | Review artifacts are required for PR creation |
| Skipping tests | TDD is mandatory; tests come first |
| Skipping documentation | Inline docs and feature docs are required |
| Batch updates at end | Issues must be updated continuously as work happens |
| Assuming API behavior | Research current APIs; don't trust training data |
| Skipping validation | All generated artifacts must be validated |
| Claiming completion without proof | Show test output, verification results |
| Working without an issue | Create the issue first, always |

### Mandatory Skill Usage

Before ANY of these actions, invoke the corresponding skill:

| Action | Required Skill |
|--------|----------------|
| Starting work | `session-start` |
| Any coding task | `issue-driven-development` |
| Creating a PR | `pr-creation` (requires review artifact) |
| Code review | `comprehensive-review` |
| After 2 failures | `research-after-failure` |
| Large task | `issue-decomposition` |
| Debugging | `systematic-debugging` |

### Quality Standards

- **Full typing always** - No `any` types; everything fully typed
- **Complete inline documentation** - JSDoc/docstrings on all public APIs
- **TDD with coverage** - Write tests first, maintain coverage
- **Atomic commits** - One logical change per commit
- **IPv6-first** - IPv6 is primary; IPv4 is legacy support only

### Verification Requirements

Before claiming ANY task is complete:

1. Tests pass (show output)
2. Linting passes (show output)
3. Build succeeds (show output)
4. Acceptance criteria verified (post verification report to issue)
5. Review artifact posted (for PRs)

### Issue Lifecycle

Issues must be updated CONTINUOUSLY, not at the end:

- Comment when starting work
- Comment when hitting blockers
- Comment when making progress
- Comment when tests pass/fail
- Update status fields in GitHub Project

---

Make sure to preserve any existing project-specific configuration (environment variables, API endpoints, domain knowledge) that doesn't conflict with these instructions.

After running this, your project will have consistent instructions that reinforce the plugin's workflow.

</details>

Contributing

These skills are opinionated by design. If you disagree with a principle, fork and adapt. The goal is consistency within a project, not universal agreement.

References

• Effective harnesses for long-running agents - Anthropic Engineering
• Claude Code Best Practices - Anthropic Engineering