Meta Agent Tools
PT

Back to the catalog

cadence

Issue-driven, multi-agent development workflow with git worktrees, structured phases, and specialist delegation

Open source Open in the app JSON README (API)

About

Issue-driven, multi-agent development workflow with git worktrees, structured phases, and specialist delegation

Details

Kind
Plugins
Topic
AI, RAG & memory
Publisher
dokipen
Origin
gemini
Category
ferramentas
Version
0.1.0
Stars
1
Forks
1
Last push
2026-08-25T22:54:12Z
Repository state
ativo
Language
TypeScript
License
MIT
Added
2026-08-30 14:13:39
Updated
2026-08-30 14:13:39
Origin id
dokipen/claude-cadence

README

# Claude Cadence

An issue-driven, multi-agent development workflow plugin for [Claude Code](https://docs.anthropic.com/en/docs/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](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:

```bash
python3 scripts/sync-codex.py
```

## Installation

### Git clone (simplest)

```bash
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:

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

### Plugin marketplace

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

# Install the plugin
/plugin install claude-cadence
```

## Updating

### Git clone

```bash
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](https://github.com/anthropics/skills/tree/main/skills/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:

```markdown
## Verification
flutter analyze && flutter test
```

or:

```markdown
## 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`:

```json
{
  "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`:

```json
{
  "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:

```bash
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](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](services/issues/docs/INDEX.md) 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`](services/issues-mcp/README.md) for setup and `.mcp.json` configuration.

## License

MIT

More