gh-taskmaster

name

gh-taskmaster

description

GitHub-TaskMaster integration skill. Autonomous issue management with intelligent TaskMaster config recommendations, budget-driven execution, state machine workflow automation, and background scheduling. Detects issues missing TaskMaster configs, recommends budgets/deadlines, manages issue lifecycle (To-Do → Ready → In-Progress → Review → Done), spawns TaskMaster sub-agents with budget constraints, monitors for human feedback, and creates PRs on completion.

GitHub-TaskMaster Integration Skill

Transform GitHub issue management with autonomous TaskMaster integration. This skill bridges GitHub issues and the TaskMaster project manager, enabling intelligent task decomposition, budget-constrained execution, and fully automated workflows.

Core Capabilities

🤖 Intelligent Issue Analysis

• Auto-detect issues missing TaskMaster config
• Extract complexity signals (bug/feature/refactor, scope keywords)
• Identify acceptance criteria (checkboxes, BDD, explicit sections)
• Recommend TaskMaster configs with budget + deadline estimation
• Confidence scoring for recommendations

💰 Budget-Driven Execution

• Simple tasks: $0.50, 1 hour
• Moderate tasks: $1, 2 hours
• Complex tasks: $3, 4 hours
• Epic tasks: $10, 1 day
• Enforce budget constraints throughout execution
• Automatic escalation on budget overrun

🔄 Intelligent Workflow Automation

• 5-state issue lifecycle: To-Do → Ready → In-Progress → Review → Done
• Label-based state transitions (e.g., status/ready → Ready)
• Comment-based approvals ("let's go", "@taskmaster start")
• Auto-detect human feedback on PRs/comments
• Incorporate change requests into running tasks
• Complete audit trail with timestamps + actor info

⏱️ Background Task Scheduling

• Analyzer (every 30 min): Scan repo, recommend configs, post comments
• Executor (every 30 min): Pick up Ready issues, spawn TaskMaster sub-agents, enforce budgets
• Listener (every 30 min): Monitor In-Progress issues for human interrupts (pause/resume/cancel/update)
• Reviewer (every 30 min): Detect completion, create PRs, move to Review → Done
• Retry logic with exponential backoff
• Metrics collection for monitoring

Architecture

┌─────────────────────────────────────────┐
│     GitHub Webhooks / Cron Scheduler    │
└──────────────┬──────────────────────────┘
               │
               ├─── Analyzer ────────┐
               │                     ├──→ Issue comments w/ recommendations
               ├─── Executor ────────┤
               │                     ├──→ Spawn TaskMaster sub-agents
               ├─── Listener ────────┤
               │                     ├──→ Monitor + route interrupts
               └─── Reviewer ────────┘
                                     └──→ Create PRs, manage workflow

Quick Start

1. Installation

git clone https://github.com/jrholco-beepboop-bot/gh-taskmaster.git
cd gh-taskmaster
pip install -r requirements.txt

2. Configuration

Create .env:

GITHUB_TOKEN=ghp_...
GITHUB_REPO=username/repo-name
OPENCLAW_GATEWAY_URL=http://localhost:18789

3. Enable in OpenClaw

Add to gateway.config.yaml:

skills:
  - name: gh-taskmaster
    path: ./skills/gh-taskmaster
    handlers:
      - job_analyzer
      - job_executor
      - job_listener
      - job_reviewer

4. Start Cron Jobs

The background scheduler will activate automatically. To manually trigger:

openclaw cron add --job job_analyzer --schedule "every 5 minutes"
openclaw cron add --job job_executor --schedule "every 2 minutes"
openclaw cron add --job job_listener --schedule "every 2 minutes"
openclaw cron add --job job_reviewer --schedule "every 5 minutes"

Usage Workflow

Issue Lifecycle

1. Create Issue (To-Do)

Issue created → Analyzer runs → Detects missing TaskMaster config
→ Posts recommendation comment with:
  - Recommended budget ($2/$10/$25/$50+)
  - Estimated deadline (1d/3d/5d/1-2w)
  - Confidence score
  - Reasoning (e.g., "Complex due to DB migration signals")

2. Approve Config (To-Do → Ready)

Human: "Let's go" / Add "status/ready" label / "@taskmaster start"
→ Issue moves to Ready
→ TaskMaster config is locked

3. Execute (Ready → In-Progress)

Executor picks up issue
→ Spawns TaskMaster sub-agent with:
  - Budget limit from config ($X)
  - Deadline from config
  - Task decomposition from issue description
→ Issue moves to In-Progress
→ Sub-agent begins work

4. Monitor (In-Progress)

Sub-agent executes tasks, posts status updates to issue comment thread
→ Human comments: "pause"/"resume"/"cancel"/"update X" 
→ Listener detects, routes interrupt to sub-agent
→ Sub-agent adapts execution

5. Review (In-Progress → Review)

Sub-agent completes work
→ Creates PR with issue reference
→ Issue moves to Review
→ Human performs code review
→ Human comments: "looks good" / requests changes
→ Reviewer incorporates feedback

6. Done (Review → Done)

PR merged
→ Issue auto-closes
→ Moved to Done
→ Cost tracking updated

Data Models

Issue

@dataclass
class Issue:
    id: int
    title: str
    body: str
    labels: List[str]
    repo: str
    has_taskmaster_config: bool
    complexity: Complexity  # simple/moderate/complex/epic
    acceptance_criteria: List[str]
    created_at: datetime

TaskMasterConfig

@dataclass
class TaskMasterConfig:
    budget: float  # tokens/$
    deadline: datetime
    tasks: List[Task]
    approval_status: ApprovalStatus  # pending/approved/executing/completed
    created_by: str
    created_at: datetime

WorkflowState

@dataclass
class WorkflowState:
    issue_id: int
    current_phase: WorkflowPhase  # To-Do, Ready, In-Progress, Review, Done
    transitions: List[Transition]  # audit trail
    last_modified: datetime
    last_modified_by: str

Budget

@dataclass
class Budget:
    limit: float  # max tokens
    spent: float
    remaining: float
    history: List[Consumption]
    overrun_escalated: bool

Module Reference

models/

• issue.py — Issue, TaskMasterConfig, Complexity enums
• workflow.py — WorkflowState, Transition, WorkflowPhase
• budget.py — Budget, Consumption tracking
• task.py — Task, TaskStatus

agents/

• analyzer.py — IssueAnalyzer, parse + decompose issues
• recommender.py — Recommender, budget + deadline estimation
• executor.py — Executor, spawn TaskMaster sub-agents
• reviewer.py — Reviewer, human approval gates

workflows/

• state_machine.py — 5-state workflow, transition guards
• event_handler.py — GitHub webhook routing, orchestration

utils/

• github_api.py — GitHub API wrapper (labels, comments, PRs)
• scheduler.py — Background job scheduler, cron coordination
• formatters.py — GitHub markdown formatting, comment builders

config/

• cron_config.yaml — Job definitions, schedules, payloads
• budget_templates.yaml — Budget profiles by complexity
• parsing_rules.yaml — Acceptance criteria detection rules

Integration Points

GitHub Webhooks

Register webhook on repo settings:

• Payload URL: http://your-openclaw.local/webhooks/github
• Events: issues, issue_comment, pull_request
• Content type: application/json

OpenClaw Handlers

4 async handlers process cron messages:

async def job_analyzer(message):
    """Scan for unconfigured issues, post recommendations"""
    
async def job_executor(message):
    """Pick up Ready issues, spawn TaskMaster sub-agents"""
    
async def job_listener(message):
    """Monitor In-Progress for human feedback"""
    
async def job_reviewer(message):
    """Create PRs on completion, manage Review→Done"""

TaskMaster Sub-Agent Spawning

When Executor picks up a Ready issue:

sessions_spawn(
    task=f"Execute issue #{issue_id}: {issue.title}",
    budget=config.budget,
    deadline=config.deadline,
    label=f"gh-taskmaster:{issue_id}"
)

Configuration

Budget Profiles

budgets:
  simple:
    tokens: 0.50
    hours: 1
  moderate:
    tokens: 1
    hours: 2
  complex:
    tokens: 3
    hours: 4
  epic:
    tokens: 10
    hours: 24

Complexity Detection

signals:
  bugs:
    simple: ["typo", "formatting", "one-liner"]
    complex: ["race condition", "security", "data loss"]
  features:
    simple: ["UI", "docs", "config"]
    complex: ["API", "database", "auth"]
  refactors:
    moderate: ["module split", "cleanup"]
    epic: ["architecture", "migration", "rewrite"]

Monitoring & Metrics

Track via OpenClaw metrics or Prometheus:

gh_taskmaster_issues_analyzed_total
gh_taskmaster_configs_recommended_total
gh_taskmaster_issues_executing
gh_taskmaster_budget_overruns_total
gh_taskmaster_task_completion_time_seconds
gh_taskmaster_human_feedback_latency_seconds

Error Handling

• Missing config: Recommender posts comment, waits for approval
• Budget overrun: Executor pauses, escalates to taskmaster-alerts channel
• Sub-agent failure: Retry with exponential backoff (30s → 60s → 120s), escalate after 3 failures
• Webhook timeout: Queue and retry on next cron run
• GitHub API rate limit: Defer job, retry on next cycle

Security & Access Control

• GitHub token via environment variable (never logged)
• Issue/PR access scoped to configured repo only
• Human approval required before Ready → In-Progress transition
• All state changes logged with actor + reason
• Budget overruns require human sign-off before continuing

Testing

# Unit tests
pytest tests/test_analyzer.py -v
pytest tests/test_state_machine.py -v
pytest tests/test_scheduler.py -v

# Integration tests
pytest tests/integration/ -v

# Full workflow test (requires test repo)
python tests/e2e_workflow_test.py

Deployment

Local Development

export GITHUB_TOKEN=ghp_...
export GITHUB_REPO=username/test-repo
python -m pytest tests/

Staging

# Deploy to staging OpenClaw instance
openclaw skill add gh-taskmaster --path ./gh-taskmaster
openclaw skill enable gh-taskmaster
openclaw cron list  # Verify jobs scheduled

Production

# Deploy to production OpenClaw