Superpowers Best Practices: 7‑Step Workflow from Requirements to Production‑Ready Code

Problem: lack of engineering discipline in AI coding

Developers often treat AI coding tools like an intern—provide a requirement, receive a code snippet, and merge it if it runs. The result is code that "runs" but is not trustworthy because design, testing, and review are missing.

AI is not for writing code; it is for enforcing strict engineering standards.

Superpowers core philosophy

"Skills are not prose — they are code that shapes agent behavior." Superpowers implements 14 mandatory Skills that the agent must use for every activity.

Three‑layer architecture

Agent Integration Layer : connects to Claude Code, Cursor, Codex, OpenCode, Gemini CLI, Copilot CLI.

Workflow Layer : linear process – brainstorming → worktrees → plans → sub‑agent → test‑driven development → code review → finish.

Skills Layer : 14 independent SKILL.md files, discoverable and composable.

Skill categories

Testing : test‑driven development, verification‑before‑completion.

Debugging : systematic debugging with a four‑stage root‑cause analysis.

Collaboration : brainstorming, writing plans, executing plans, sub‑agent‑driven development, parallel‑agent dispatch, code‑review requests, git worktrees, branch finishing.

Meta‑skills : writing skills, using Superpowers (custom skills and onboarding).

Closed‑loop workflow

brainstorming → using-git-worktrees → writing-plans → subagent-driven-development → test-driven-development (per task) → requesting-code-review (per task) → finishing-development-branch

Each stage is automatically triggered; attempts to skip a stage are rejected by the agent.

Practical example: Coupon redemption API

Brainstorming

"Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it."

Socratic dialogue extracts hidden questions:

Agent: "优惠券有几种类型？满减、折扣、还是固定金额？"
User: "满减和折扣两种。"
Agent: "一张券能用几次？一次性还是可多次使用？"
User: "一次性。"
Agent: "并发场景怎么处理？两张订单同时用一张券，期望行为是什么？"
User: "只有一个能成功。"
Agent: "核销失败的券，状态应该恢复为可用，还是标记为异常？"

The skill also enforces a HARD‑GATE that rejects the assumption "This is too simple to need a design".

Design alternatives for concurrency control

Redis distributed lock – strong consistency, good performance, adds a new dependency.

Database optimistic lock – eventual consistency, simple implementation, many retries under high concurrency.

Database pessimistic lock – strong consistency, stable, coarse lock granularity, poorer performance.

Git worktrees

Choose directory (e.g., .worktrees/ → worktrees/ → CLAUDE.md configuration).

Verify the directory is listed in .gitignore to avoid polluting the main repository.

Create an isolated worktree that shares the same Git repository.

Auto‑detect project type and install dependencies.

Run baseline tests to confirm a clean start.

# Agent commands
git worktree add .worktrees/coupon-redeem feature/coupon-redeem
cd .worktrees/coupon-redeem
npm install
npm test  # ensure all tests pass

Writing plans (2‑5 minute actions)

Task 1: Define CouponRedeemRequest DTO
  1. Write failing test for DTO validation
  2. Implement DTO
  3. Run test, ensure GREEN, then commit

Task 2: Redemption status validation
  ... (similar TDD flow) ...

Task 3: Concurrency control – optimistic lock
  1. Write failing concurrency test
  2. Add version field
  3. Implement lock logic
  4. Verify

Three mandatory rules are enforced:

No "TBD" – every step must contain concrete code.

No references to other tasks – each sub‑agent receives a self‑contained description.

Self‑check three aspects: coverage, placeholder scan, type consistency.

Sub‑agent execution

"Fresh subagent per task + two‑stage review = high quality, fast iteration"

Each task spawns a new sub‑agent that does not inherit any prior context, ensuring isolation.

TDD RED‑GREEN‑REFACTOR

"NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST"

Example failing test for concurrency safety:

describe('CouponService.redeem - concurrent safety', async () => {
  const coupon = await Coupon.create({id: 'cpn_001', type: 'FIXED_DISCOUNT', value: 10, status: 'ACTIVE', version: 0});
  const [r1, r2] = await Promise.allSettled([
    CouponService.redeem({couponId: 'cpn_001', orderId: 'ord_001'}),
    CouponService.redeem({couponId: 'cpn_001', orderId: 'ord_002'})
  ]);
  const successCount = [r1, r2].filter(r => r.status === 'fulfilled').length;
  expect(successCount).toBe(1);
});

GREEN stage adds the optimistic‑lock update logic; REFACTOR cleans up duplication without changing behavior.

Code review

"Review early, review often."

The requesting-code-review skill triggers three mandatory review points: after each sub‑agent finishes, after major features, and before merging to main. Review output example:

Critical (must fix now):
  - Concurrent failure returns HTTP 500, spec requires 409 → fix status mapping
Important (fix before continue):
  - Magic number 0 for affected rows should be a constant
  - Missing log for redemption failure
Minor (later):
  - Extract redeem logic into a separate service

Branch completion verification

# Final verification sequence
npm test      # full test suite
npm run lint  # style check
npm run typecheck  # type check
# Agent reads output, ensures 0 failures and 0 errors

Only when all four steps succeed can the work be declared finished.

Effect comparison: disciplined vs. undisciplined

Community feedback: a 15‑file feature written with Claude Code alone required a full git rollback, whereas the same task completed autonomously with Superpowers following the disciplined workflow.

Design phase : forced brainstorming vs. direct coding.

Development environment : isolated worktree vs. changes on main.

Task granularity : atomic 2‑5 minute actions vs. one large implementation.

Testing strategy : RED‑GREEN‑REFACTOR vs. adding tests after code.

Quality assurance : automated two‑stage review & verification gate vs. manual checks.

Code review : mandatory after each task vs. optional.

Concurrency safety : failing test first vs. guesswork.

The key difference is controllability: Superpowers turns AI output from uncertain to predictable.

Model selection guidance

Mechanical implementation (e.g., DTO definition) – use fast/cheap model (1–2 files, complete spec).

Integration judgment (multi‑file coordination) – use standard model.

Architecture / review – use strongest model.

Never use a flagship model for simple DTO definitions.

Common pitfalls

Skipping brainstorming → requirement misunderstanding → rework.

Leaving "TODO" in plans → sub‑agent produces unpredictable code.

Writing code before tests → tests become decorative.

Skipping spec review → missing or extra functionality.

Parallel implementer agents → merge conflicts.

Resources

GitHub repository: https://github.com/obra/superpowers Chinese enhanced version: https://github.com/jnMetaCode/superpowers-zh Original blog post by Jesse Vincent:

https://blog.fsck.com/2025/10/09/superpowers/