# How Design Documents Are Named and Structured in Superpowers

> Learn how Superpowers names and structures design documents using Markdown files under docs plans with a YYYY-MM-DD topic design format and standardized sections for clarity.

- Repository: [Jesse Vincent/superpowers](https://github.com/obra/superpowers)
- Tags: best-practices
- Published: 2026-02-16

---

**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`](https://github.com/obra/superpowers/blob/main/-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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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`](https://github.com/obra/superpowers/blob/main/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:

```bash

# 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:

```markdown

# <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`](https://github.com/obra/superpowers/blob/main/-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`](https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md) and in [`RELEASE-NOTES.md`](https://github.com/obra/superpowers/blob/main/RELEASE-NOTES.md) at line 442.