scrum-punk

A Claude Code plugin that runs a full Scrum-based SDLC with a team of 9 AI agents — autonomously, end to end, while you stay in the customer seat.

---

Features

• 9-agent AI team covering every engineering discipline from product ownership to SRE
• Scrum ceremonies — Planning Poker (Fibonacci, max 2 rounds), Retrospective (KPT), ADR Meetings — run autonomously
• Human oversight via GitHub — every decision lands in Issues, PRs, and Comments; nothing is hidden in agent memory
• Human-in-the-loop gates — PRD approval and release authorization always go to the human customer via AskUserQuestion
• Scaled Trunk-Based Development — squash merge to main, worktree-isolated branches per agent, daily rebase
• Harness engineering — Guides (feedforward constraints) + Sensors (feedback checks) + self-correction loops baked into hooks
• Quality gates — TDD, SOLID, Tidy First, Clean Code enforced by pre-commit hooks, CI/CD, and code review policy
• Metrics — Burndown, Burnup, and Feature Count vs Implementation Time charts generated each Retrospective
• Context efficiency — layered skill loading, role-scoped documents, and agent definition deduplication keep token cost low
• Sprint state persistence — sprint state is saved and restored across context compactions automatically

---

Agent Team

Agent	Role	Key Responsibility
product-owner	Product Owner	PRD authoring, acceptance review, release decision
scrum-master	Scrum Master (lead/orchestrator)	Ceremonies, event routing, team coordination, merge execution
tech-lead	Tech Lead	Architecture, ADRs, feature decomposition, Planning Poker tiebreaker
dev-frontend	Frontend SDE	UI/UX implementation
dev-backend	Backend SDE	API and server-side implementation
dev-data	Data Engineer	Pipelines, ETL, data infrastructure
dev-data-scientist	Data Scientist	Analysis, modeling, experimentation
dev-ai-ml	AI/ML Engineer	ML pipelines, LLM integration
dev-sre	SRE	CI/CD, IaC, deployment, repository foundation

The Scrum Master is the Claude Code session lead. All other agents are teammates spawned via TeamCreate.

---

How It Works

Human (Customer)
    |
    | requirement
    v
Product Owner  ──── PRD (GitHub Wiki) ──────────────> Human approval
    |
    | Epic + Feature Issues (GitHub)
    v
Tech Lead  ──── ADR Meetings ──── Chore decomposition
    |
    v
Planning Meeting (SM facilitates)
    - PO presents backlog
    - Tech Lead explains issues
    - SDEs estimate via Planning Poker (max 2 rounds)
    - SM assigns to Iteration Milestone
    |
    v
SDEs work in parallel (worktree-isolated branches)
    - TDD: Red → Green → Refactor
    - Tidy First: structural and behavioral commits separated
    - Self-correction: linter/test sensor → auto-fix loop
    |
    v
Pull Request
    - SM assigns 2 reviewers
    - Max 2 review rounds → pair session if unresolved
    - Feature/Bug: PO acceptance review (AC check)
    - Chore: 2 approvals → SM squash merges
    |
    v
Release Issue ──── PO review ──── Human approval ──── SRE deploys
    |
    v
Retrospective (KPT)
    - Metrics: Burndown, Burnup, Feature Count vs Time
    - Keep / Problem / Try
    - Velocity adjustment
    - Harness re-examination

All inter-agent coordination flows through two channels:

• GitHub Issues/PRs/Comments — durable, human-readable record of every decision
• SendMessage — ephemeral ad-hoc coordination; decisions are always back-referenced to GitHub

Every SendMessage is prefixed with the sender's identity: [agent-name / pane N] (tmux) or [agent-name] (in-process), so the main agent always knows who is speaking and where to find them.

Hooks automate the mechanical parts: GitHub event routing, merge guards, idle agent re-tasking, task completion quality gates, and sprint state sync.

---

Getting Started

Prerequisites

• Claude Code with agent teams experimental feature enabled
• GitHub CLI (gh) authenticated with repo, workflow, and project permissions
• Environment variable set: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
• Display mode (choose one):
  • tmux panes (recommended): install tmux, run Claude inside tmux new-session, or set "teammateMode": "tmux" in ~/.claude.json. When a teammate goes idle (e.g., waiting for your answer), the plugin waits 3 minutes before notifying the main agent — giving you time to respond in the teammate's pane. Notifications include the agent name and pane number: [product-owner / tmux pane 2] has been idle for 3 minutes.
  • in-process: all agents in one terminal, cycle with Shift+Down. No tmux needed. Set "teammateMode": "in-process" or use claude --teammate-mode in-process. When a teammate asks a question, it is immediately forwarded to the main agent with the agent name: [product-owner] went idle.
  • auto (default): tmux panes if in a tmux session, otherwise in-process

Installation

Option A: Development / Testing (load directly)

claude --plugin-dir /path/to/scrum-punk

# Optional: for tmux split-pane views, start inside tmux first
# tmux new-session -s scrum-punk && claude --plugin-dir /path/to/scrum-punk

Option B: Install via marketplace

# Add the scrum-punk GitHub repo as a marketplace
/plugin marketplace add writeAheadLog/scrum-punk

# Install the plugin
/plugin install scrum-punk@writeAheadLog-scrum-punk

# Reload to activate
/reload-plugins

Updating

Option A (--plugin-dir): Pull the latest changes:

cd /path/to/scrum-punk && git pull

Changes take effect on the next Claude Code session.

Option B (marketplace):

# Update marketplace listings
/plugin marketplace update writeAheadLog-scrum-punk

# Reinstall to get the latest version
/plugin install scrum-punk@writeAheadLog-scrum-punk

# Reload
/reload-plugins

Starting a Project

Open a new Claude Code session (with the plugin loaded) and run:

/scrum-punk:start-project

Note: Commands are namespaced by plugin name. Use /scrum-punk:start-project, not /start-project.

The Scrum Master will:

1. Verify GitHub authentication and permissions
2. Create the agent team (TeamCreate, team name: scrum-punk)
3. Spawn the Product Owner
4. PO interviews you (the customer) to gather requirements
5. PO drafts a PRD and presents it for your approval
6. On approval: GitHub repo is created, SRE sets up the repository foundation, Tech Lead decomposes features, SM convenes the first Planning Meeting

From that point forward, the team operates autonomously. You monitor progress via GitHub and respond when approval is requested.

Submitting New Requirements Mid-Project

/scrum-punk:new-requirement

This routes a new requirement to the Product Owner, who will clarify, update the backlog, and coordinate with the team.

---

Plugin Structure

scrum-punk/
├── CLAUDE.md                        # Plugin-level instructions (loaded by Claude Code)
├── COLLABORATION.md                 # Communication rules for all agents
├── package.json
│
├── agents/                          # Agent persona definitions
│   ├── scrum-master.md
│   ├── product-owner.md
│   ├── tech-lead.md
│   ├── developer-frontend.md
│   ├── developer-backend.md
│   ├── developer-data.md
│   ├── developer-data-scientist.md
│   ├── developer-ai-ml.md
│   ├── developer-sre.md
│   └── code-reviewer.md
│
├── commands/                        # Slash commands
│   ├── start-project.md             # /start-project
│   └── new-requirement.md           # /new-requirement
│
├── skills/                          # Layered skill library (loaded on demand)
│   ├── scrum-master/
│   ├── product-owner/
│   ├── tech-lead/
│   ├── developer/                   # SDE constitution (shared)
│   ├── code-reviewer/
│   ├── iteration-planning/
│   ├── retrospective/
│   ├── release-management/
│   ├── repository-foundation/
│   ├── merge-coordination/
│   ├── agent-communication/
│   └── deploy-{local,cloud,kubernetes}/
│
├── hooks/                           # Automation hooks
│   ├── hooks.json                   # Hook configuration
│   ├── github-event-router.sh       # Routes GitHub events to SM (PostToolUse)
│   ├── merge-guard.sh               # Blocks unsafe merges (PreToolUse)
│   ├── save-sprint-state.sh         # Persists sprint state (PreCompact)
│   ├── restore-sprint-state.sh      # Restores sprint state (PostCompact)
│   ├── sync-sprint-state.sh         # Syncs state across agents (FileChanged)
│   └── cleanup-agent-pane.sh        # Cleans up worktrees (WorktreeRemove)
│
└── docs/
    ├── specs/
    └── plans/

---

Scrum Process

Issue Types

Type	Purpose	Template Highlights
Feature	User-facing capability	User Story, AC (Given/When/Then), SP range
Bug	Defect	Current vs expected behavior, repro steps, fix AC
Chore	Technical work	Tech context, definition of done, no user story required
Release	Deployment event	Included features/fixes, release checklist, HITL approval

Branch naming convention: <type>/<issue-number>-<short-description>

Examples: feature/42-user-auth, bug/17-null-pointer-fix, chore/58-add-lint-config

Ceremonies

Planning Meeting (start of each iteration)

• PO presents the priority-sorted backlog
• Tech Lead explains context and dependencies per issue
• All SDEs estimate simultaneously via Planning Poker (Fibonacci: 1, 2, 3, 5, 8)
• Two rounds maximum; if no consensus after round 2, Tech Lead makes the final call
• Issues with 13+ SP are split before estimation
• SM creates the GitHub Milestone and broadcasts the iteration start

ADR Meeting (on-demand, Tech Lead-initiated)

• Convened when a hard-to-reverse architectural decision must be made
• Tech Lead presents context and 2–3 options with trade-offs
• All agents discuss and reach consensus
• ADR is written in Nygard format and committed to docs/adr/

Retrospective (end of each iteration)

• SM collects metrics: Burndown, Burnup, Feature Count vs Implementation Time
• All agents submit KPT (Keep / Problem / Try) via SendMessage
• SM synthesizes patterns, converts Try items to action items or Chore issues
• Velocity is adjusted for the next iteration
• Harness controls are re-examined — redundant controls are removed
• Planning and Retrospective notes are posted to GitHub Wiki (not Issues) for long-term reference

Iteration Flow (Project Board Columns)

Icebox → Backlog → Current Iteration → In Progress → In Review → Done

---

Quality and Harness Engineering

SDE Constitution

All SDE agents operate under a shared engineering constitution:

• Never commit directly to main. All work happens on topic branches.
• TDD: Red → Green → Refactor. Tests before implementation, always.
• Tidy First: Structural changes (rename, extract, move) and behavioral changes (features, fixes) in separate commits. Structural first.
• Commit discipline: All tests pass, all linter warnings resolved, single logical unit per commit.
• SOLID, KISS, YAGNI, DRY: Applied consistently. Patterns used only when they solve a real problem.
• Branch cleanup: After squash merge, local branches are deleted with git branch -D (squash merge requires -D, not -d).

Harness Engineering

Inspired by Anthropic's and Martin Fowler's harness engineering principles, the plugin wraps agent behavior with:

Guides (Feedforward)

• Role-scoped skill files loaded on demand — agents only see what they need
• Pre-Implementation Contract between implementer and reviewer before code is written
• ADR index consulted before any architectural work begins
• Planning Poker round cap (2) prevents endless estimation loops

Sensors (Feedback)

• PostToolUse hook routes every GitHub event to the SM for action
• PreToolUse merge guard blocks unsafe merge operations before they execute
• TaskCompleted hook verifies tests pass, linter is clean, and PR template is filled
• TeammateIdle hook suggests the next best task when an agent goes idle

Self-Correction Loops

• Linter or test failure → agent auto-fixes and re-runs before requesting review
• Code review: maximum 2 rounds → unresolved items trigger a pair session (not a third round)
• PO decline — minor fix: PO re-reviews directly; major fix: full code review cycle restarts
• Planning Poker no-consensus: Tech Lead decides rather than cycling indefinitely

Sprint State Resilience

• Sprint state is saved to .claude/sprint-state.json before context compaction (PreCompact)
• Restored immediately after (PostCompact)
• Changes synced across all agent worktrees via FileChanged hook

Code Review Policy

• SM assigns 2 reviewers: 1 from a different expertise area, 1 from the same area or Tech Lead
• Since all agents share one GitHub account, reviewers are identified by comment prefix: **[agent-name / Reviewer N]**:
• Reviewer 1 executes the test plan from the PR description; Reviewer 2 verifies
• Architecture PRs always include Tech Lead
• Maximum 2 review-revise rounds; 3rd unresolved issue → pair session

Security Policy

Zero secrets in code — no exceptions.

• No passwords, API keys, tokens, or credentials are ever hardcoded in source code
• All secrets loaded via environment variables (os.environ, process.env)
• .env files are always in .gitignore — never committed
• .env.example with placeholders documents required variables
• CI/CD uses GitHub Actions Secrets (${{ secrets.NAME }})
• Code reviewers block any PR that contains hardcoded secrets
• Accidentally committed secret → rotate immediately, remove from git history, notify SM

CI/CD

Repositories created by scrum-punk include:

• ci.yml — triggered on pull request: lint → type check → test
• cd.yml — triggered on release published: build → deploy
• pre-commit hooks — linter, formatter, type checker run locally before every commit

Operational Rules

• CI/CD failure — SM creates a priority Chore issue. CI must be green before further merges.
• README maintenance — when an SDE's work affects the README, they create a Chore issue and update via normal PR flow.

---

Inspired By

scrum-punk is built on the shoulders of practitioners who defined the craft:

• Kent Beck — Test-Driven Development, Tidy First, XP practices
• Martin Fowler — Refactoring patterns, Trunk-Based Development, harness engineering
• Robert C. Martin (Uncle Bob) — SOLID principles, Clean Code, Clean Architecture
• David Thomas and Andrew Hunt — The Pragmatic Programmer (DRY, Design by Contract)
• Michael Nygard — Architecture Decision Records (Nygard format), stability patterns

Further reading:

• Anthropic: Multi-agent harness engineering
• Martin Fowler: Harness Engineering

---

License

MIT License. Copyright (c) 2026 scrum-punk contributors.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

Contributing

Contributions are welcome. The project follows its own process — please work within it:

1. Open a GitHub Issue describing what you want to add or fix. Use the appropriate issue template (Feature, Bug, or Chore).
2. Wait for discussion and acceptance before starting implementation.
3. Follow the SDE Constitution: TDD, Tidy First, SOLID, KISS, YAGNI, DRY.
4. Branch naming: <type>/<issue-number>-<short-description>
5. Separate structural and behavioral changes into distinct commits.
6. Open a PR against main. All tests must pass. All linter warnings must be resolved.
7. PRs require 2 approving reviews before merge.

If you are proposing an architectural change (new hook type, agent communication model, skill loading strategy), open a discussion issue first — hard-to-reverse decisions deserve deliberate review.