shapeup

Shape Up Skills for Claude Code

Four Claude Code skills that teach your AI agent the Shape Up methodology. Fixed time, variable scope, zero hand-waving.

Frame the problem. Shape the solution. Build the code. Ship the knowledge.

Why?

Backlogs are where ideas go to die. Shape Up replaces the infinite todo list with a simple bet: pick a time budget, shape the work to fit, build it, ship it. This project gives Claude Code the vocabulary and guardrails to run that process with you — interactively, one feature at a time.

The Skills

Skill	What it does	Gate
/shapeup:frame	Turns a vague idea into a locked problem statement with appetite	Frame Go
/shapeup:shape	Deep codebase analysis → requirements, affordance tables, fit check matrix, Package	Shape Go
/shapeup:build	TDD via RED/GREEN behavioral tests, hill charts, scope hammering, handovers for multi-session work	Ready to Ship
/shapeup:ship	Extracts ADRs, updates architecture docs, archives the feature folder	Done

Each skill is self-contained with its own reference docs — no external dependencies, no magic.

Quick Start

In Claude Code, run:

/plugin marketplace add tiago-peixoto/claude-shapeup
/plugin install shapeup

Type /shapeup:frame and follow the conversation.

What Happens at Runtime

.shapeup/
├── 2026-04-20-csv-import-framing/       # Active: being framed
│   └── frame.md
├── 2026-04-18-auth-refresh-shaped/      # Ready: waiting for a build bet
│   ├── frame.md
│   └── package.md
├── 2026-04-15-dashboard-v2-building/    # In progress
│   ├── frame.md
│   ├── package.md
│   ├── hillchart.md
│   ├── scopes/
│   └── handover-01.md
├── 2026-04-10-search-shipped/           # Done: decisions archived
└── index.md                             # Auto-generated dashboard

Multiple features can run in parallel. Each folder is a date-slug key — YYYY-MM-DD-<slug> — with a status suffix (-framing, -shaped, -building, -shipped, -discarded). Date-slug keys are collision-free across teammates: two developers can frame features on separate branches without colliding on a shared counter. If two teammates pick the same slug on the same day, the second folder gets a 4-hex disambiguator (2026-04-20-csv-import-bc89-framing).

Inside a -building feature, each scopes/<scope>.md tracks user-noticeable behaviors as [RED] → [GREEN] (vertical slices the user can observe) rather than technical task checkboxes. A scope is done when its must-have behaviors are [GREEN]. Legacy [ ]/[x] scope files are still accepted for one release.

Invoke downstream skills with any of these key forms:

• Full date-slug: /shapeup:build 2026-04-20-csv-import
• Short slug: /shapeup:build csv-import (works when the slug is unique across the project)
• Legacy numeric: /shapeup:build 001 (back-compat for features created before date-slug)

Hooks

The plugin installs three hooks:

• phase-guard.sh (UserPromptSubmit) — blocks /shape, /build, /ship when gates haven't been passed. Resolves any accepted key form to the correct feature folder and verifies Frame Go / Shape Go / build-summary.md exists.
• ripple-check.sh (PostToolUse) — watches .shapeup/**/*.md edits and nudges the agent when a change to one document likely affects another. Advisory only.
• commit-gate.sh (PreToolUse) — intercepts git commit and blocks a scope-completion commit when the scope files, hill chart, and behavior states disagree. Runs the consistency audit on the staged .shapeup/ diff so drift can't be committed.

Verification Scripts

Shared libraries under hooks/lib/ back the "trust but verify" pattern that shape/build/ship and the commit gate use:

• resolve-feature.sh — accepts any key form, returns the feature folder path.
• check-consistency.sh — audits a feature folder for drift between scope behavior states ([RED]/[GREEN], or legacy checkboxes), hill chart symbols, and the pre-ship gate. Skills call it before marking a scope done and as the gate into /ship; FAILs must be resolved, not silenced.
• commit-gate.sh — the gate library the commit-gate hook runs on the staged .shapeup/ diff (see Hooks above).

Project Structure

.claude-plugin/
├── plugin.json
└── marketplace.json
hooks/
├── hooks.json
├── phase-guard.sh
├── ripple-check.sh
├── commit-gate.sh
└── lib/
    ├── resolve-feature.sh
    ├── check-consistency.sh
    └── commit-gate.sh
references/                      # 9 shared methodology docs (00-glossary … 08-framing)
skills/
├── frame/
│   ├── SKILL.md
│   └── scripts/init-feature.sh
├── shape/
│   ├── SKILL.md
│   └── scripts/validate-package.sh
├── build/
│   ├── SKILL.md
│   └── scripts/update-hillchart.sh
└── ship/
    ├── SKILL.md
    └── scripts/regenerate-index.sh

Acknowledgments