From Legacy Coding to AI‑Assisted Development: A Hands‑On Guide to Using Superpowers and OpenSpec

1. Two Key Tools and Their Roles

OpenSpec (40.9k Stars on GitHub) is a specification‑driven development (SDD) framework that converts requirements into machine‑readable spec files. These specs enable AI and humans to reach consensus before any code is written.

Superpowers (158k Stars) provides a complete AI‑coding methodology: it enforces test‑driven development (TDD), isolates sub‑agents, and applies a two‑stage code review.

In short, OpenSpec governs the requirement layer, while Superpowers governs the execution layer.

2. Role Redistribution

2.1 Architect

Generate change proposals with /opsx:propose, translating business needs into AI‑understandable specs.

Review design.md for technical decisions and legacy pitfalls.

Validate implementations against the design using /opsx:verify.

The architect becomes the start and end point of the specification chain.

2.2 Backend Development

Consume tasks.md generated by OpenSpec and clarify task boundaries with Superpowers’ brainstorming.

Write code within Superpowers’ TDD loop.

Handle legacy compatibility issues that AI cannot resolve automatically.

2.3 Frontend Development

Consume design.md for interface contracts and start page development early.

Parallelize component development using Superpowers sub‑agents.

Synchronize API changes via OpenSpec’s incremental specs.

The three roles now collaborate through auditable, reviewable spec files rather than informal conversations.

3. Four‑Stage Closed‑Loop Workflow

3.1 Stage 1 – Legacy Code Analysis

Install OpenSpec and initialise the project:

# Install OpenSpec
npm install -g @fission-ai/openspec@latest

# Initialise in project root
openspec init

Run /opsx:explore to let AI map the existing codebase and produce a spec snapshot in openspec/specs/.

The architect reviews the snapshot and adds hidden business rules that AI missed (e.g., non‑atomic stock deduction, dual price storage, Redis session TTL).

Output: a set of specifications describing data models, APIs, and core business flows.

3.2 Stage 2 – Requirement Specification

Execute /opsx:propose to create proposal.md, design.md, and tasks.md under openspec/changes/.

Review design.md for compatibility, non‑breaking API changes, and performance considerations.

Validate task granularity (2‑5 minutes per task) in tasks.md.

OpenSpec’s Delta Spec marks changes as ADDED , MODIFIED , or REMOVED , making impact visible.

3.3 Stage 3 – Code Generation & Injection

Install the Superpowers plugin (e.g., /plugin install superpowers@claude-plugins-official).

Feed tasks.md into Superpowers, which runs a seven‑step workflow:

Brainstorming – Socratic questioning to clarify task details.

Git worktree – Create an isolated branch.

Writing‑plans – Split into minute‑sized sub‑tasks.

Sub‑agent execution – AI handles each sub‑task.

TDD loop – RED → GREEN → REFACTOR.

Two‑stage code review – spec compliance then code quality.

Branch finalisation – Verify, merge, and archive.

Human reviewers fix style mismatches (e.g., replace @Autowired with constructor injection) and verify compatibility with legacy code.

3.4 Stage 4 – Collaborative Synchronisation

When one side updates an interface, modify the incremental spec in OpenSpec.

Run /opsx:sync to merge changes into the main spec.

Both sides consume the updated spec; run /opsx:archive to keep the spec directory tidy.

The loop repeats, continuously updating openspec/specs/ for the next iteration.

4. Real‑World Walkthrough: Adding a Flash‑Sale Module to an Old E‑Commerce System

4.1 Baseline Analysis

Initialise OpenSpec, explore the code, and capture a snapshot. The architect adds three hidden rules:

Stock deduction is not atomic – risk of overselling under high concurrency.

Product price exists in both the product table and the order snapshot; both must be updated.

User sessions are stored in Redis with a 30‑minute TTL.

4.2 Define Flash‑Sale Specification

Run /opsx:propose with the description “Add a time‑limited flash‑sale feature supporting activity creation, stock pre‑deduction, and fast order confirmation.” OpenSpec generates design.md with key decisions:

Decouple flash‑sale stock from the main product stock.

Use Redis for pre‑deduction and an MQ for asynchronous persistence.

Expose a separate flash‑sale order API.

Sample tasks.md entries (estimated time, owner):

Create flash_sale table – 3 min – Backend

Implement Redis stock pre‑deduction API – 5 min – Backend

Create flash‑sale order API – 5 min – Backend

Flash‑sale list page – 4 min – Frontend

Countdown component – 3 min – Frontend

Real‑time stock display component – 3 min – Frontend

Delta Spec marks the new API and data model as ADDED and modifies the product query to include a flash‑sale price field.

4.3 Code Generation

Superpowers processes the “Redis stock pre‑deduction” task:

Brainstorming clarifies that stock is independent and oversell must be rejected.

Creates an isolated branch feature/flash-sale-stock.

Writes a plan that expands into sub‑tasks such as creating RedisStockService, implementing a Lua script for atomic deduction, and writing tests.

Runs the TDD loop automatically.

During code review, a style mismatch ( @Autowired vs constructor injection) is corrected manually.

Frontend developers consume the updated design.md and parallel‑develop the flash‑sale page and countdown component.

4.4 Integration & Sync

A mismatch is discovered: the backend returns timestamps in seconds while the frontend expects milliseconds. The backend updates the spec with a MODIFIED entry, and the frontend pulls the change via /opsx:sync without code changes. After verification, /opsx:archive archives the change.

The entire process, which could take a week manually, is completed by a three‑person team in a fraction of that time, demonstrating that the real benefit lies in shared specifications rather than raw AI‑generated code.

5. Practical Pitfall Guide

5.1 Code‑Style Conflicts

AI prefers modern let/const and exception throwing, while the legacy code uses var and error‑code returns. Add a style spec in openspec/specs/ so Superpowers reads it before each task.

5.2 Incompatible Legacy Dependencies

Spring Boot 1.x vs 2.x APIs and jQuery version mismatches cause breakage. Record dependency versions in the system spec and inform AI of the target version during brainstorming.

5.3 Over‑Designing Specs

Writing exhaustive design documents defeats the iterative intent of OpenSpec. Keep each change focused; split large task lists (>10) into separate change sets.

5.4 Lack of Tests in Legacy Code

Superpowers enforces TDD, but the old code may lack a test framework. Two approaches are recommended:

Develop new features with Superpowers’ TDD (tests are generated automatically).

Add targeted tests only for modified legacy functions using the verification‑before‑completion skill.

This aligns with the Strangler Fig pattern: new code follows the new spec, legacy code is migrated incrementally.

6. Tool Installation & Resources

Both tools can be installed side‑by‑side:

# Install OpenSpec
npm install -g @fission-ai/openspec@latest

# Initialise in project directory
cd your-project && openspec init

# Install Superpowers (Claude Code example)
/plugin install superpowers@claude-plugins-official

Superpowers also works on Cursor ( /add-plugin superpowers), Codex CLI, and OpenCode. OpenSpec supports 25+ AI coding assistants, including Claude Code, Cursor, and Windsurf. Both are MIT‑licensed and free.