Claude Cadence

An issue-driven, multi-agent development workflow plugin for Claude Code.

Claude Cadence provides a structured development workflow with git worktrees, phased implementation, specialist agent delegation, and GitHub issue tracking — all stack-agnostic and customizable per project.

This repo also includes a thin Codex compatibility layer that reuses the existing Claude prompts, scripts, and CLAUDE.md as the source of truth. See docs/codex-compatibility.md.

Codex

Codex support is packaged as a compatibility layer rather than a second copy of the workflow docs:

• .codex-plugin/plugin.json registers the plugin for Codex
• codex/skills/ contains generated thin wrappers for commands, shared skills, and specialist roles
• scripts/sync-codex.py regenerates those wrappers from the canonical Claude source files

When updating Cadence workflows, edit the existing Claude files first and then run:

python3 scripts/sync-codex.py

Installation

Git clone (simplest)

git clone https://github.com/dokipen/claude-cadence.git
claude --plugin-dir ./claude-cadence

To always load the plugin, add --plugin-dir to your shell alias or config:

claude() { command claude --plugin-dir /path/to/claude-cadence "$@"; }

Plugin marketplace

# Add the marketplace (once)
/plugin marketplace add dokipen/claude-cadence

# Install the plugin
/plugin install claude-cadence

Updating

Git clone

cd /path/to/claude-cadence && git pull

Plugin marketplace

Run claude plugin update cadence@claude-cadence to update, then restart Claude Code.

What You Get

Commands (user-invoked)

Command	Purpose
/lead	Coordinate implementation through 8 structured phases (0–7)
/refine or /refine 123	Refine issues to quality standards

Skills (model-invoked)

Skill	Purpose
new-work	Create a git worktree for isolated development
create-pr	Create a PR with pre-flight verification
create-skill	Bootstrap new Claude Code skills
skill-iterate	Evaluate, benchmark, and iteratively improve an existing skill using Anthropic's skill-creator
project-ops	Shared worktree management utilities

Agents (specialist delegation)

Agent	Role
code-reviewer	PR reviews, code quality, best practices
tester	Test execution, bug reproduction, coverage
security-engineer	Security audits, dependency checks
performance-engineer	Performance profiling, optimization
claude-specialist	Claude Code configuration, agent/skill design
ticket-refiner	Issue quality assurance

Project Integration

Claude Cadence agents read your project's CLAUDE.md to discover stack-specific commands. Add a ## Verification section:

## Verification
flutter analyze && flutter test

or:

## Verification
go vet ./... && go test ./...

The agents and scripts will use this command automatically.

Machine-Local Ticket Provider Config (~/.claude/cadence.json)

You can set provider configuration in ~/.claude/cadence.json to avoid repeating it in every project's CLAUDE.md. Configuration precedence (highest to lowest):

1. Per-repo overrides (.repos["owner/repo"]) — overrides CLAUDE.md
2. CLAUDE.md — project-level config checked into the repo
3. Global defaults (top-level fields) — fallback when CLAUDE.md has no provider config
4. Built-in default — provider: github

Global default — applies to any repo that has no ## Ticket Provider section in CLAUDE.md:

{
  "provider": "issues-api",
  "project_id": "my-default-project",
  "api_url": "https://issues.example.com"
}

Per-repo override — overrides CLAUDE.md for a specific repo, identified by owner/repo slug derived from git remote get-url origin:

{
  "repos": {
    "owner/repo": {
      "provider": "issues-api",
      "project_id": "my-project"
    }
  }
}

Both can be combined in one file. Per-repo entries take precedence over CLAUDE.md; global defaults only apply when CLAUDE.md has no provider config. api_url is not overridable per-repo — it belongs in CLAUDE.md or the global default. Use ISSUES_API_URL for QA/local api_url overrides.

Adding Project-Specific Agents

Add domain-specific agents to your project's .claude/agents/ directory. They layer on top of the plugin's core agents:

your-project/.claude/
├── agents/
│   ├── designer.md              # Your custom agent
│   ├── game-mechanics-engineer.md  # Your custom agent
│   └── tester.md                # Overrides plugin's generic tester

Same-name agents in your project override the plugin version.

Workflow Overview

The /lead command orchestrates structured phases:

1. Phase 0: Worktree setup (isolated branch)
2. Phase 1: Planning (research, task breakdown, design review)
3. Phase 2: Implementation (specialist delegation)
4. Phase 3: Pre-PR verification (tests, lint)
5. Phase 4-5: PR creation and code review gate
6. Phase 6-7: Manual QA, merge, and cleanup

Issues must be refined (/refine) before implementation — this covers estimation, acceptance criteria, and labeling.

Conventions

• Git: All work in worktrees, never on default branch
• Branches: <issue-number>-<description> (e.g., 42-add-auth)
• Issues: Descriptive titles, categorized via labels
• Estimation: Fibonacci scale (1, 2, 3, 5, 8, 13) — applied by /refine
• Communication: Issue comments pre-PR, PR comments post-PR
• GitHub: Always use gh CLI

Services

Dev Environment

Bring up the full local stack for manual PR QA with a single command:

cp .env.dev.example .env.dev  # fill in your secrets
docker compose -f docker-compose.dev.yml up --build

Then open http://localhost. See docs/dev-environment.md for full setup instructions, GitHub OAuth configuration, and how to test a specific PR branch.

Issue Microservice

A GraphQL-based ticket tracking service with CLI client. See the Issue Microservice Documentation for setup, deployment, and usage.

Issues MCP Server

An MCP server that exposes the issues API as structured tools for Claude Code and other MCP-compatible agents — no CLI binary required. See services/issues-mcp/README.md for setup and .mcp.json configuration.

License

MIT