What Really Happens When You Use Superpowers to Build a Multi‑File PDF Merger?

What is Superpowers?

Superpowers is a plug‑in that imposes a standardized AI‑development workflow. It guides the user through four mandatory stages: brainstorming → design‑document generation → execution‑plan creation → code generation . Each stage requires explicit confirmation before proceeding, which makes the process appear engineering‑like and controllable.

Pitfall 1: A complete design document does not guarantee a working solution

When the workflow was used to build a web tool that merges multiple Markdown files into a PDF, the generated design document looked thorough but the implementation failed to handle complex GitHub‑Flavored Markdown (GFM) features. Specific problems observed in the PDF output included:

Malformed tables

Missing or blank URL‑based images

Mermaid diagrams rendered as raw text instead of graphics

Code blocks displayed without syntax highlighting

These issues stemmed from the fact that the requirement‑clarification stage did not explicitly ask for full GFM support, so the AI omitted the necessary rendering logic.

Pitfall 2: AI may skip the prescribed process

Even after explicitly stating the need to follow the full chain, Superpowers sometimes bypassed the design‑document and execution‑plan steps and jumped straight to code generation. To prevent this, the user must embed a hard rule in the initial prompt, for example:

Must complete brainstorming, generate a full design document, produce a detailed execution plan, and only then write code. No stage may be skipped.

Enforcing this rule forces the model to pause after each stage and wait for user confirmation.

Pitfall 3: Subagent mode is overkill for small projects

Superpowers offers two execution modes:

Subagent mode : The task is split into multiple subtasks, each handled by separate agents (e.g., one writes code, two perform format and consistency checks). This yields a highly structured output but dramatically increases latency—e.g., a simple PDF‑merger was divided into eight tasks with three agents each, causing the run time to become impractically long.

Direct execution mode : The model generates the entire codebase in a single pass, which is faster and sufficient for small utilities.

Subagent mode primarily validates code format and alignment with the design document; it does not automatically verify functional correctness such as proper rendering of Markdown elements.

Practical recommendations

During the brainstorming stage, explicitly list all core requirements, e.g., "support full GFM syntax, render URL images, process Mermaid diagrams, preserve code‑block formatting".

Insert a non‑negotiable rule that forbids skipping any stage, as shown above.

For lightweight tools, prefer the direct execution mode to avoid unnecessary overhead.

After code generation, manually test the produced artifact (e.g., render the PDF) to confirm that complex Markdown features are handled correctly.

By combining strict step‑by‑step enforcement with clear requirement specification, Superpowers can accelerate development while avoiding the common pitfalls observed in the Markdown‑to‑PDF case.