Indie Devlog #06: Superpowers — How We Use Design Specs and Implementation Plans
Every feature I build starts as two documents. A design spec that argues about the problem, goals, and locked decisions. Then an implementation plan that breaks the work into concrete, testable steps. Only after both are written does any code get written.
I call this the Superpowers methodology, and it is the single biggest productivity multiplier in my development workflow. Not because the documents are valuable on their own — they are not, they are ephemeral — but because the process of writing them forces clarity before execution.
Why two documents
A design spec answers "what are we building and why." An implementation plan answers "how do we build it, step by step." Separating them prevents a common failure mode: jumping to implementation details before the problem is understood.
The spec is structured with five sections:
- Problem — what is broken or missing, with concrete evidence
- Goals — measurable outcomes this feature must achieve
- Non-goals — what is explicitly out of scope (harder than writing goals)
- Locked decisions — architectural choices that are settled before a line of code is written
- Approach — the proposed solution at a high level
The plan converts the approach into tasks with checkboxes, grouped by dependency, with explicit test strategies.
Spec before code
Here is the spec header for the product bootstrap system I wrote about last time:
# Microbyte Product Bootstrap — design (2026-05-24)
**Status:** Approved
**Approach:** Hub personal skill + monorepo runbooks + existing leaf skills
**Manifest:** bootstrap.jsonc + docs/bootstrap/bootstrap.schema.json
**Agents (v1):** Cursor, Claude Code, Hermes Agent
The Problem section documents the concrete pain point:
Each Microbyte product repeats the same operational setup: pre-dev docs, marketing website, local pre-commit, GitHub CI, Coolify deploy, App Store screenshots, store listing, mobile scaffold. Work is split across personal skills, shared packages, and ad hoc copying. There is no single orchestrated workflow, no durable record of what is done per product, and templates drift.
From reading that paragraph, anyone — including my future self six months from now — knows exactly why the system exists and what gap it fills.
The Locked Decisions table is the most valuable section. It captures trade-off analysis that would otherwise be lost:
| Topic | Decision |
|---|---|
| Scenarios | Greenfield + harden via same orchestrator |
| Template default | Fiscify |
| Screenshot layout exception | TipFolio path, not Fiscify |
| Skill location | Personal (microbyte-product-bootstrap) |
| Manifest format | JSONC + JSON Schema |
These decisions were debated and settled before the first runbook was written. When someone asks "why not YAML?" the answer is in the spec, not in someone's memory.
Plans as executable checklists
The implementation plan is deliberately mechanical. It is a list of tasks with clear completion criteria, designed to be executed by an AI agent or a human with equal success:
## Task 1: Schema and template manifest
- [x] Create `bootstrap.schema.json` (JSON Schema v7)
- [x] Create `templates/bootstrap.jsonc` matching schema
- [x] Validate template against schema (manual `npx ajv-cli`)
- [x] Test: edit `template.bootstrap.jsonc` → invalid → schema rejects
## Task 2: Discovery and runbooks
- [x] Write `discovery.md` (filesystem → phase mapping)
- [x] Write phase runbooks 01–08 under `phases/`
The checkboxes map directly to implementation work. No ambiguity about what "done" means.
How AI agents use these documents
This is where the methodology gets its name. The spec and plan are designed to be consumed by AI agents as much as by humans.
When I start working on a feature, I load the spec into the agent's context first. The agent reads the problem, goals, and locked decisions. Then I load the plan. The agent executes tasks in order, checking off each box, and asks for clarification only when a task has ambiguity the documents did not resolve.
The locked decisions are particularly useful for agents. Without them, an agent might suggest a fundamentally different architecture than what was agreed upon. With them, the agent stays within the established boundaries and spends its effort on implementation, not re-architecture.
What the process filters out
Writing a spec before coding has an unexpected side effect: it kills bad ideas cheaply.
Some features sound great in conversation but collapse under the weight of writing them down. When you force yourself to articulate the problem, goals, and non-goals, the features that do not hold up reveal themselves before you invest a single hour of coding. I have scrapped more features during the spec phase than during implementation, and each scrapped spec saved days of wasted work.
The non-goals section is the most powerful filter. Writing "we are not building X" forces you to acknowledge trade-offs explicitly. When a stakeholder asks for X later, you point to the spec and say "we decided against that here, and here is why."
The template
I keep a minimal spec template that I copy for every new feature:
# Feature Name — design (YYYY-MM-DD)
**Status:** Draft | Approved | Superseded
**Approach:** <one-line summary>
**Spec:** <link to any upstream spec>
---
## 1. Problem
## 2. Goals
## 3. Non-goals
## 4. Locked decisions
| Topic | Decision |
## 5. Approach
That is it. About 15 lines of structure that save weeks of rework.
The real superpower
The documentation is not the point. The point is that the analysis happens once, comprehensively, before anyone touches a codebase. The spec becomes the single source of truth for why decisions were made. The plan becomes the executable roadmap. And the 24+ spec/plan pairs in the Fiscify repo alone form an architectural journal of every meaningful feature decision across the product's lifetime.
When I return to a feature six months later to add something, the spec tells me what the original designer was thinking. I can disagree with their choices, but I cannot claim ignorance of them.
For suggestions and queries, just contact me.