claude-task-master 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7dbcfc3c4a723e88aec42f1982dfec744e7a2e341279b3e3d34c4500500a8579
+  data.tar.gz: d40ffdfcd238845e784184b08bd4068ec1e757e3e8b461b13ecbed9bac70e732
+SHA512:
+  metadata.gz: fd790d64324ad5ce56e7e3ffcc00fe73f049881f788e67dd566e972a6a38041d6090349eb75d86d568e3e90f078e4b9b2048efa1698cb11301f3389acca5bc02
+  data.tar.gz: 481b06664e4c243f87aef1130b708835f25d50f6ae2a6719d922201f8d2cf2e2e807c76e25f7e70d3ff063b7d9f9223de2a70424250804b12e1e9a13cdfac293

data/CLAUDE.md

@@ -0,0 +1,192 @@
+# CLAUDE.md
+
+Instructions for Claude Code when working on this repository.
+
+## Project Overview
+
+**claude-task-master** — Autonomous task loop for Claude Code.
+
+A lightweight Ruby harness that keeps Claude working until success criteria are met. It's not trying to make Claude smarter—Claude is already smart. It just keeps the loop going:
+
+```
+plan → work → check → work → check → ... → done
+```
+
+## Core Philosophy
+
+1. **Claude does the work AND the checking** - The harness just keeps calling Claude
+2. **State via files** - Everything persists in `.claude-task-master/`
+3. **Generic review system** - Works with CodeRabbit, Copilot, or any review tool
+4. **Shift handoff pattern** - Each Claude invocation is like a new engineer taking over
+
+## Architecture
+
+```
+bin/claude-task-master     # CLI entry point
+lib/
+  claude_task_master.rb    # Main require file
+  claude_task_master/
+    cli.rb                 # Thor CLI commands
+    loop.rb                # Main work loop
+    state.rb               # State management (.claude-task-master/)
+    claude.rb              # Claude CLI wrapper
+    github.rb              # GitHub operations (gh CLI)
+    reviewers/
+      base.rb              # Base reviewer interface
+      coderabbit.rb        # CodeRabbit implementation
+      copilot.rb           # GitHub Copilot implementation
+      generic.rb           # Generic PR comment reviewer
+    providers/
+      ci.rb                # Generic CI status checker
+      sentry.rb            # Sentry error monitoring
+```
+
+## Commands
+
+```bash
+# Start fresh with a goal
+claude-task-master "build a REST API with user auth"
+
+# Resume previous work
+claude-task-master              # No args = resume
+claude-task-master --resume
+
+# Check status
+claude-task-master status
+```
+
+## State Directory
+
+All state lives in `.claude-task-master/` within the project:
+
+```
+.claude-task-master/
+├── goal.txt              # What we're building
+├── criteria.txt          # Success criteria
+├── plan.md               # Generated plan with [ ]/[x] checkboxes
+├── state.json            # Machine state (current task, PR #, etc.)
+├── progress.md           # Human-readable progress notes
+├── context.md            # Accumulated learnings (fed to Claude)
+└── logs/
+    ├── session-001.md    # Full log per Claude invocation
+    └── session-002.md
+```
+
+## The Loop
+
+```ruby
+# Pseudocode - this is the entire thing
+def run
+  setup_or_resume
+
+  loop do
+    # Build context from state files
+    context = build_context
+
+    # Call Claude with full autonomy
+    invoke_claude(context)
+
+    # Check if done
+    break if success_criteria_met?
+
+    # Brief pause between invocations
+    sleep 2
+  end
+
+  puts "Done!"
+end
+```
+
+## Claude Invocation
+
+Each Claude call gets:
+1. The goal and success criteria
+2. Current state (what task we're on, PR status, etc.)
+3. Context from previous sessions
+4. Instructions to update state files when done
+
+```bash
+claude -p \
+  --dangerously-skip-permissions \
+  --allowedTools "Bash,Edit,Read,Write,Glob,Grep" \
+  "#{context_and_instructions}"
+```
+
+## Review System
+
+The harness is agnostic to review tools. It checks:
+
+1. **CI status**: `gh pr checks --watch` (waits for completion)
+2. **Review comments**: Fetches PR comments, filters by reviewer
+3. **Unresolved threads**: Uses GitHub GraphQL for resolution status
+
+Claude reads comments and decides what to fix. The harness just reports.
+
+## Key Files
+
+### cli.rb
+Thor CLI with commands: `start`, `resume`, `status`
+
+### loop.rb
+Main loop logic. Calls Claude repeatedly until done.
+
+### state.rb
+Reads/writes `.claude-task-master/` files. Handles resume.
+
+### claude.rb
+Wrapper around `claude` CLI. Builds prompts, captures output.
+
+### github.rb
+GitHub operations via `gh` CLI:
+- Create PR: `gh pr create`
+- Check CI: `gh pr checks`
+- Get comments: `gh api repos/:owner/:repo/pulls/:pr/comments`
+- Merge: `gh pr merge`
+
+### reviewers/base.rb
+Interface for review systems:
+```ruby
+class Base
+  def fetch_comments(pr_number) = raise NotImplementedError
+  def unresolved_comments(pr_number) = raise NotImplementedError
+  def resolve_comment(comment_id) = raise NotImplementedError
+end
+```
+
+## Code Style
+
+- Ruby 3.1+
+- Single Responsibility Principle (SRP) - each file does one thing
+- No metaprogramming magic
+- Explicit over implicit
+- Files under 200 lines
+
+## Testing
+
+```bash
+bundle exec rspec
+```
+
+Tests use fixtures and mocked Claude calls. No real API calls in tests.
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run locally
+bundle exec bin/claude-task-master "test goal"
+
+# Run tests
+bundle exec rspec
+
+# Lint
+bundle exec rubocop
+```
+
+## Security
+
+- Uses `--dangerously-skip-permissions` - only run in trusted environments
+- No credentials stored in state files
+- Uses `gh` CLI for auth (inherits user's GitHub auth)

data/README.md

@@ -0,0 +1,231 @@
+# claude-task-master
+
+Autonomous task loop for Claude Code. Keep Claude working until the job is done.
+
+## The Loop
+
+```
+plan → work → check → work → check → ... → done
+```
+
+Claude does the work AND the checking. The task master just keeps the loop going.
+
+## Quick Start
+
+```bash
+# Install
+gem install claude-task-master
+
+# Start a new task
+claude-task-master start "build a REST API with user authentication"
+
+# Enter success criteria when prompted:
+> tests pass, PR merged, no sentry errors for 10 minutes
+
+# Let it run. Come back later.
+# Press Ctrl+C to pause anytime.
+
+# Resume
+claude-task-master resume
+# Or just:
+claude-task-master
+```
+
+## How It Works
+
+1. **Planning Phase**: Claude analyzes your codebase, creates a plan with tasks
+2. **Work Loop**: Claude implements tasks one by one
+3. **PR Cycle**: Create PR → wait for CI → fix review comments → repeat → merge
+4. **Success Check**: Verifies success criteria are met
+5. **Next Task**: Moves to next task until all done
+
+All state persists in `.claude-task-master/` so you can:
+- Pause and resume anytime
+- Inspect progress in human-readable files
+- Kill and restart without losing work
+
+## Commands
+
+```bash
+# Start fresh
+claude-task-master start "your goal here"
+
+# Resume previous work
+claude-task-master resume
+claude-task-master  # shorthand
+
+# Check status
+claude-task-master status
+
+# View the plan
+claude-task-master plan
+
+# View session logs
+claude-task-master logs
+claude-task-master logs --last 3
+claude-task-master logs --session 5
+
+# View context/progress
+claude-task-master context
+claude-task-master progress
+
+# PR comments (uses current PR if not specified)
+claude-task-master comments        # all comments
+claude-task-master comments 123    # specific PR
+claude-task-master comments -a     # actionable only
+claude-task-master comments -u     # unresolved threads
+
+# PR management
+claude-task-master pr status       # PR info
+claude-task-master pr checks       # CI status
+claude-task-master pr merge        # merge current PR
+
+# Clean up and start fresh
+claude-task-master clean
+claude-task-master clean -f  # skip confirmation
+
+# Check prerequisites
+claude-task-master doctor
+```
+
+## Options
+
+```bash
+# Use different model
+claude-task-master start "goal" --model opus
+
+# Provide criteria inline
+claude-task-master start "goal" --criteria "tests pass, deploys to staging"
+
+# Don't auto-merge PRs (require manual review and merge)
+claude-task-master start "goal" --no-merge
+
+# Limit number of work sessions
+claude-task-master start "goal" --max-sessions 10
+claude-task-master resume -m 5  # shorthand
+
+# Pause after creating each PR for review
+claude-task-master start "goal" --pause-on-pr
+
+# Verbose output
+claude-task-master start "goal" --verbose
+
+# Combine options
+claude-task-master start "goal" --no-merge --max-sessions 20 --model opus
+```
+
+## State Directory
+
+Everything lives in `.claude-task-master/`:
+
+```
+.claude-task-master/
+├── goal.txt          # What you asked for
+├── criteria.txt      # Success criteria
+├── plan.md           # Tasks with checkboxes
+├── state.json        # Machine state
+├── progress.md       # Human-readable progress
+├── context.md        # Learnings across sessions
+└── logs/
+    └── session-*.md  # Full log per Claude invocation
+```
+
+## Works With Any Review System
+
+The task master is agnostic to code review tools:
+
+- **CodeRabbit** - Detects comments from `coderabbitai[bot]`
+- **GitHub Copilot** - Detects suggestions and reviews
+- **Human reviewers** - Claude reads and addresses any PR comments
+- **Generic** - Any comment on the PR gets attention
+
+Claude reads the comments and decides what to fix. The harness just reports.
+
+## Requirements
+
+- Ruby 3.1+
+- [Claude Code CLI](https://claude.ai/code) (`npm install -g @anthropic-ai/claude-code`)
+- [GitHub CLI](https://cli.github.com/) (`gh`) - for PR features
+- `--dangerously-skip-permissions` - only use in trusted environments
+
+## How It Calls Claude
+
+```bash
+claude -p \
+  --dangerously-skip-permissions \
+  --model sonnet \
+  "Your context and instructions here"
+```
+
+Each invocation is independent. State persists via files.
+
+## Example Session
+
+```
+$ claude-task-master start "add user authentication to the API"
+Starting claude-task-master...
+Goal: add user authentication to the API
+
+What are your success criteria?
+(e.g., 'tests pass, deploys to staging, no sentry errors for 10min')
+> tests pass, PR merged
+
+Phase 1: Planning...
+....................
+Plan created. Check .claude-task-master/plan.md
+
+Phase 2: Working...
+Press Ctrl+C to pause (can resume later)
+
+[Session 1] Working on: Set up authentication dependencies
+  Completed in 45.2s
+
+[Session 2] Working on: Create user model and migrations
+  Completed in 89.1s
+  PR created: #42
+
+[Session 3] Working on: Fix CodeRabbit comments
+  Completed in 32.5s
+
+[Session 4] Working on: Address remaining review feedback
+  Completed in 28.3s
+
+[Session 5] Working on: Merge and verify
+  Completed in 15.0s
+
+SUCCESS!
+All tasks completed. Check .claude-task-master/progress.md
+```
+
+## Development
+
+```bash
+git clone https://github.com/developerz-ai/claude-task-master
+cd claude-task-master
+bundle install
+
+# Run locally
+bundle exec bin/claude-task-master start "test goal"
+
+# Run tests
+bundle exec rspec
+```
+
+## Philosophy
+
+Claude is smart. It can:
+- Read code and understand patterns
+- Make decisions about implementation
+- Create PRs and fix review comments
+- Know when it's done
+
+The task master just:
+- Keeps calling Claude
+- Persists state between calls
+- Detects success/blocked
+
+That's it. ~300 lines of Ruby. Claude does the thinking.
+
+## License
+
+MIT

data/bin/claude-task-master

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/claude_task_master'
+
+ClaudeTaskMaster::CLI.start(ARGV)