Superpowers Multi-Dev Workflow

How we split planning and implementation across developers using Claude Code + Superpowers.

Makro Agency · Internal Process · May 2026

Roles

Role	Who	Owns
Planner	Senior dev / architect	Brainstorm → Spec → Plan
Implementer	Dev assigned to build	Execute plan → PR

The Flow

PLANNER                              IMPLEMENTER
───────                              ───────────
1. Create feature branch
2. Run /brainstorming skill
3. Write spec → commit
4. Run /writing-plans skill
5. Embed constraints in plan (!)
6. Commit plan → push branch
7. Notify implementer
                                     8.  Pull feature branch
                                     9.  Read spec (understand WHY)
                                     10. Run /subagent-driven-development
                                         (or /executing-plans)
                                     11. Claude Code executes plan
                                     12. Push commits → open PR
13. Review PR (or phase-gated
    review for high-risk work)
                                     14. Address review feedback
                                         (/receiving-code-review)
15. Approve & merge

Planner Responsibilities

1. Brainstorm & write spec

Run the /brainstorming skill. Commit spec to docs/superpowers/specs/<feature>-design.md.

Every spec must include a "Constraints & Design Decisions" section:

Example — spec constraints

## Constraints & Design Decisions
- Use existing OrderService — do NOT create a new service class
- No new npm dependencies
- Prices in cents, convert only at display layer
- Do not refactor the webhook handler — separate ticket

2. Write the plan

Run /writing-plans. Commit plan to docs/superpowers/plans/<feature>.md.

Critical: embed constraints in the plan itself. The executing skill reads the plan file — not the spec. If constraints are only in the spec, Claude Code never sees them during execution.

Add this block at the top of every plan:

Plan header template

## Context
- Spec: docs/superpowers/specs/<feature>-design.md
- Branch: feature/<name>
- Risk level: normal | high-risk
- Estimated effort: [S/M/L per task]

## Constraints (from spec — do not violate)
- [paste from spec's Constraints section]
- [these are read by Claude Code during execution]

## Known Unknowns
- [thing planner couldn't fully specify + resolution rule]
- e.g., "If API returns 404, use fallback endpoint in config.ts"

3. Push & hand off

Push branch. Notify implementer with: branch name, one-line summary, risk level (normal / high-risk).

Implementer Responsibilities

1. Pull & read

Pull the feature branch. Read the spec file first — understand the WHY before executing the HOW.

Note: Claude Code will invoke using-git-worktrees automatically when you start execution — it creates an isolated workspace from the feature branch. Don't override this.

2. Execute

Open Claude Code on the feature branch.

Default: invoke /subagent-driven-development — dispatches subagents per task with automated spec compliance + code quality review. Continuous execution, no need to pause between tasks.
Use /executing-plans only if you want manual checkpoints between tasks (e.g., unfamiliar codebase, want to review each step yourself).

3. Handle deviations

If Claude Code cannot follow a plan step as written:

STOP. Do not self-correct silently.
Write a deviation note: docs/superpowers/deviations/<feature>.md
Include: which step, what went wrong, what you'd propose instead.
Ask the planner before proceeding — or flag in the PR.

4. Open PR

Run /finishing-a-development-branch when all tasks complete. Use /requesting-code-review for automated first-pass review before the planner sees it.

Risk Levels

Level	Review Style	When to Use
Normal	Full PR review after completion	Most features
High-risk	Phase-gated: commit per phase, planner reviews between phases	Core integrations, data migrations, auth changes

Tradeoff: High-risk phase-gated review puts the planner in the critical path between phases — speed gain is sacrificed for safety. If turnaround matters, switch to async draft-PR reviews (implementer keeps building, planner reviews when available).

What Goes Where

File	Scope	Changes How Often
`CLAUDE.md`	Project conventions, stack rules, deviation protocol	Rarely
`docs/superpowers/specs/`	Feature WHY + constraints	Once per feature
`docs/superpowers/plans/`	Feature HOW + embedded constraints	Once per feature
`docs/superpowers/deviations/`	Drift from plan (if any)	During implementation

No merge conflicts. CLAUDE.md stays stable across branches. Feature-specific context lives in spec + plan files on the feature branch.

CLAUDE.md Addition

Add this once to your project's CLAUDE.md (project-wide):

## Deviation Protocol
If you cannot follow a plan step as written, STOP.
Do not silently self-correct.
Write a deviation note to docs/superpowers/deviations/<feature>.md explaining:
what step failed, why, and your proposed alternative.
Wait for guidance.

Quick Reference

Planner creates

spec → plan (with embedded constraints) → pushes branch

Implementer runs

pull branch → read spec → /subagent-driven-development → PR

Key rule: Constraints must be in the plan file, not just the spec. The execution skill reads the plan — the spec is for human understanding.

Templates

Spec header template

Copy into every spec:

# [Feature Name] — Design Spec

## Summary
[1-2 sentences: what this feature does and why]

## Constraints & Design Decisions
- [hard rule 1]
- [hard rule 2]
- [what NOT to do and why]

## [remaining spec sections as needed]

Plan header template

Copy into every plan:

# [Feature Name] — Implementation Plan

## Context
- Spec: docs/superpowers/specs/YYYY-MM-DD-<feature>-design.md
- Branch: feature/<name>
- Risk level: normal | high-risk
- Estimated effort: [S/M/L per task]

## Constraints (from spec — do not violate)
- [paste from spec's Constraints section]
- [these are read by Claude Code during execution]

## Known Unknowns
- [thing planner couldn't fully specify + resolution rule]
- e.g., "If API returns 404, use fallback endpoint in config.ts"

## Tasks
[task breakdown follows]