Playbook: A Lightweight Orchestrator for Claude Code to Autonomously Handle GitHub Issues

Playbook is an AI Agent orchestration system based on Claude Code CLI. It automatically assigns coding, testing, and review tasks through tag-driven workflows to achieve end-to-end automated handling of GitHub Issues. As an orchestration layer, it schedules multiple Claude Code instances to collaborate, solving the problem where traditional human-driven models fail to fully utilize AI's 24/7 availability. This allows developers to complete the development process by only reviewing accumulated changes.

With the maturity of AI coding assistants like Claude Code, developers have begun to explore extending them from interactive sessions to autonomous workflows. The traditional human-driven model (opening IDE, launching AI assistant, describing requirements, reviewing code) is effective but fails to fully utilize AI's round-the-clock availability. Playbook was born as an orchestration layer to schedule, coordinate, and monitor multiple Claude Code instances, enabling them to collaborate like a team to handle software development tasks.

Playbook uses GitHub tags as triggers and status tags as the workflow engine. The process is as follows: Developers add the ai-ready tag to an Issue → A scheduled task (every 10 minutes) detects it and starts the coding Agent → The coding Agent creates a feature branch from the ai/dev branch, implements the requirements, submits a Draft PR, and marks it with ai-testing → The testing Agent runs the test suite; if passed, it marks the PR with ai-review-needed → The review Agent performs code review; upon confirmation, it marks the PR with ai-pr-ready and automatically merges it into ai/dev → Developers review the accumulated changes in the ai/dev branch and merge them into the main branch with one click. No manual intervention is required throughout the process.

Playbook adopts a specialized Agent division of labor model, with layered permissions to ensure security:

• Coding Agent: Has full write permissions, responsible for understanding requirements, designing implementations, writing code, and creating PRs (most capable, highest risk);
• Testing Agent: Has restricted permissions (read-only code, execute tests, modify test files), verifies whether the implementation meets requirements;
• Review Agent: Has read-only permissions, reviews PR quality, and prevents self-review bias. The layered permission design can catch errors from the coding Agent and ensure process security.

Technical Implementation: Built on a Python architecture, core components include:

• Orchestrator (periodically scans GitHub Issues and schedules Agents);
• Configuration system (supports flexible configurations like multi-repository and concurrency limits);
• GitHub client (encapsulates APIs to handle tags, PRs, etc.);
• Agent module (prompt templates and command construction logic);
• State management (records Agent status to prevent repeated starts);
• Notification system (Slack integration to send key events). Security Protection: Branch isolation (works on the ai/dev branch), concurrency control, timeout mechanism (60 mins for coding /30 mins for testing /30 mins for review), retry limit (3 cycles), file change limit (max 10 files per time), tool permission restrictions (via --allowedTools parameter).

Deployment Requirements: Python 3.11+, authenticated Claude Code CLI, GitHub personal access token, optional Slack webhook. Configuration Steps: Clone the repository → Set environment variables → Edit config.yaml to add target repositories → Create ai/dev branch → Configure GitHub tags → Add CLAUDE.md project description → Set up GitHub Actions. Operation Method: Set up scheduled tasks via crontab (run the orchestrator every 10 minutes, send activity summaries in the morning and evening). User Experience: Enables asynchronous development—developers can add the ai-ready tag before bed, and the system automatically completes coding/testing/review/merging overnight; the next day, they review the PR from ai/dev to main and merge it. Suitable for cross-timezone teams, batch standardized tasks, and rapid prototyping.

Limitations: Suitable for tasks with clear boundaries, explicit requirements, and good test coverage; complex tasks (design decisions, architecture changes, external coordination) require human intervention; teams need to accept the burden of AI code review and establish trust mechanisms and merge standards. Outlook: Represents the direction of AI-assisted development from interactive assistants to autonomous workflows; similar orchestration tools will become more common in the future. The project is in the early stage, but its architecture is clear and practical, making it a noteworthy starting point for exploring AI autonomous development workflows.