How Design Documents Are Named and Structured in Superpowers

Superpowers stores every design specification as a Markdown file under docs/plans/ following the strict naming convention YYYY-MM-DD-<topic>-design.md and enforces a standardized structure including Overview, Features, and Acceptance Criteria sections.

The Superpowers framework requires rigorous documentation before any implementation begins. Understanding how design documents are named and structured in Superpowers is essential for contributors and AI agents working within the ecosystem, as the framework automates document creation through its built-in skills.

Naming Convention for Design Documents in Superpowers

All design specifications live in the docs/plans/ directory and follow a machine-readable pattern that enables automatic discovery and versioning.

Breaking Down the Filename Pattern

The complete filename structure is:

docs/plans/YYYY-MM-DD-<topic>-design.md

• YYYY-MM-DD – The ISO-8601 date when the design is created, ensuring chronological sorting.
• <topic> – A short, hyphen-separated identifier describing the feature or project (e.g., svelte-todo, go-fractals).
• -design.md suffix – Guarantees uniqueness and signals that the file contains a design specification rather than an implementation plan or test suite.

This naming rule is enforced by the brainstorming skill, which records the requirement at line 30 in skills/brainstorming/SKILL.md: "Write design doc — save to docs/plans/YYYY-MM-DD-<topic>-design.md and commit."

Standard Structure of Superpowers Design Documents

A design document serves as a human-readable specification that guides the subsequent implementation phase. While exact headings can vary by project, all Superpowers design docs follow the same high-level layout.

Required Sections

Every design document must include:

• # <Title> – A human-readable title (e.g., "# Svelte Todo List – Design").

• ## Overview – One-paragraph description of the feature, its goals, and the problem it solves.

• ## Features – Bullet-point list of functional capabilities.

• ## Acceptance Criteria – Concrete, testable conditions that must be met before the design is considered complete.

Optional Sections

Depending on the project complexity, design documents may also include:

• ## User Interface – ASCII diagram or description of the UI layout.

• ## Components – Tree of source files or component hierarchy.

• ## Data Model – TypeScript/Go structs, JSON schema, or other data definitions.

• ## Architecture – High-level modules, directories, or runtime flow.

• ## Dependencies – External libraries, runtimes, or services required.

Real-World Examples from the Superpowers Repository

Two canonical examples illustrate this pattern in practice:

• tests/subagent-driven-dev/svelte-todo/design.md – A UI-centric design featuring a UI diagram, component tree, TypeScript data model, and detailed acceptance criteria.
• tests/subagent-driven-dev/go-fractals/design.md – A CLI-focused specification showing command structure, flags, architecture diagram, dependencies, and acceptance criteria.

Automated Creation via the Brainstorming Skill

The Superpowers framework automates design document creation through the brainstorming skill. When initiating a new feature, the skill generates the file at the exact path docs/plans/YYYY-MM-DD-<topic>-design.md before any implementation skill runs.

This enforcement is documented in RELEASE-NOTES.md at line 442: "Design documents now written to docs/plans/YYYY-MM-DD-<topic>-design.md before implementation."

Code Examples for Creating Design Documents

Shell Script for Design Document Creation

The following pattern matches the automation used by the brainstorming skill:

# Example: create a design doc for a new feature called "svelte-todo"

DATE=$(date +%F)                     # e.g. 2025-11-28

TOPIC="svelte-todo"
FILENAME="docs/plans/${DATE}-${TOPIC}-design.md"

cat > "$FILENAME" <<'EOF'

# Svelte Todo List – Design

## Overview

A simple todo list application built with Svelte...

## Features

- Add new todos
- Mark todos as complete/incomplete
...

## Acceptance Criteria

1. Can add a todo by typing and pressing Enter or clicking Add
2. Can toggle todo completion by clicking checkbox
...
EOF
git add "$FILENAME"
git commit -m "Add design for $TOPIC ($DATE)"

Minimal Design Document Skeleton

For agents and contributors needing a quick start:

# <Feature Name> – Design

## Overview

<Brief description of the problem and intended solution.>

## Features

- <Feature 1>
- <Feature 2>
...

## Acceptance Criteria

1. <First testable requirement>
2. <Second testable requirement>
...

Summary

• Superpowers enforces a strict naming convention: docs/plans/YYYY-MM-DD-<topic>-design.md.
• The brainstorming skill automates creation and commits the file before implementation begins.
• Required sections include Title, Overview, Features, and Acceptance Criteria.
• Optional sections cover UI diagrams, component trees, data models, architecture, and dependencies.
• Real-world examples in tests/subagent-driven-dev/ demonstrate both UI-centric and CLI-focused patterns.

Frequently Asked Questions

What is the exact filename format for Superpowers design documents?

The exact format is docs/plans/YYYY-MM-DD-<topic>-design.md, where YYYY-MM-DD is the ISO-8601 creation date, <topic> is a hyphen-separated feature identifier, and the -design.md suffix distinguishes it from implementation or test files.

Where must design documents be stored in a Superpowers project?

All design documents must be stored in the docs/plans/ directory at the repository root. This location is hard-coded in the brainstorming skill and referenced in the release notes as the canonical path for design specifications.

Which sections are mandatory in a Superpowers design document?

Every design document must include four core sections: a Title (# <Title>), Overview (## Overview), Features (## Features), and Acceptance Criteria (## Acceptance Criteria). These sections ensure the document provides sufficient context for implementation and testing.

How does Superpowers enforce the design document naming convention?

The brainstorming skill enforces the convention by automatically generating the filename using the pattern docs/plans/YYYY-MM-DD-<topic>-design.md when creating new design documents. This enforcement is documented at line 30 of skills/brainstorming/SKILL.md and in RELEASE-NOTES.md at line 442.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}