# Shape Up

> Co-write a top-down design spec for software projects. Shape vague ideas into clear specs by working layer-by-layer — vision, scope, building blocks, then detail. Use when user wants to design a system, plan a project, write a design spec, or needs to see the big picture before diving into details. Use before /grill-design to prevent losing focus on large projects.

- Skill: `thaitype/shape-up` (Agent Skill)
- Install (CLI): `npx skillmds@latest add thaitype/shape-up`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thaitype/shape-up/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: thaitype (https://skillmd.com/u/thaitype)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/thaitype/shape-up

---

# Shape Up — Top-Down Design Spec

Shape a vague idea into a clear design spec by working **top-down**: start from the big picture, confirm alignment at each layer, then go deeper. This is NOT an interview — it's collaborative writing where the agent drafts and the user shapes.

## When to Use

- User says "shape up", "design spec", "let's design", "plan a system", "I need to think through this"
- User has a large or ambiguous project and needs to see the big picture first
- Before `/grill-design` — when the scope isn't clear enough to grill on details yet

## Core Principle

**One layer at a time. Confirm before going deeper. Never jump ahead.**

If the user can't answer something at the current layer, mark it `[TBD]` and move on. Don't drill down into unknowns — that's how people lose focus.

## Workflow

### Layer 1: Vision

Ask the user to describe what they're building in plain language. Then co-write a short vision block:

- **What** — one sentence describing the thing
- **Why** — what problem it solves, who it's for
- **Done looks like** — how you'd know it succeeded

Draft this as a short block (5-8 lines max). Show it to the user. Adjust until they say it's right.

Do NOT ask about tech stack, architecture, or implementation yet.

### Layer 2: Scope

Now that the vision is clear, co-write the scope:

- **In scope** — what this project will do (bullet list)
- **Out of scope** — what it explicitly won't do (bullet list)
- **Constraints** — timeline, tech, team, budget, dependencies
- **Users / Actors** — who interacts with it

Draft and show. The user cuts, adds, moves things between in/out scope. Keep going until scope feels tight.

If scope is getting too big, say so: *"This feels like it's growing — want to split it?"*

### Layer 3: Building Blocks

Break the in-scope work into 3-7 big blocks. Each block is a major component, feature area, or workstream. For each block:

- **Name** — short label
- **Purpose** — one line
- **Depends on** — which other blocks it needs

Show as a simple list or diagram. The user rearranges, renames, merges, splits. This is the skeleton — no detail yet.

If a block is unclear, mark it `[TBD]` and keep going. Don't stop the whole flow for one unknown.

### Layer 4: Draft Spec

For each block (in order the user chooses), co-write a short spec:

- What it does
- Key decisions or trade-offs
- Open questions

Each block spec should be **half a page to one page max**. If it's getting longer, it probably needs to be split into smaller blocks — go back to Layer 3.

The user can stop at any point and say "that's enough for now." Respect that. Not every block needs a spec in the first pass.

### Output

Write the spec to a file. The user decides the filename and location. If the user doesn't specify, suggest `design-spec.md` in the current directory.

The spec can have multiple drafts — e.g., `draft/phase-1.md`, `draft/final-spec.md`. Follow the user's lead on structure.

## How to Co-Write (not interview)

- **Draft first, ask second.** Don't open with a list of questions. Write a rough version based on what you know, then let the user correct it.
- **Show, don't ask.** Instead of "what should the scope be?", write a scope and say "this is what I'm hearing — what's wrong?"
- **Keep momentum.** If the user gives a vague answer, write your best interpretation and move on. They'll correct you if it's wrong.
- **Short blocks.** Each layer's output should fit on one screen. If you're writing more than that, you've gone too deep.

## What NOT to Do

- Don't start with 10 clarifying questions (that's grill-design's job)
- Don't discuss implementation details in Layer 1-2
- Don't expand `[TBD]` items unless the user asks
- Don't write a full spec in one shot — layer by layer
- Don't keep going deeper if the user hasn't confirmed the current layer