Agent-Skills.md

Agent Skills: Shape Up

>

UncategorizedID: petekp/claude-code-setup/shape-up

Repository

petekp/claude-code-setup
petekpLicense: MIT
143

Install this agent skill to your local

pnpm dlx add-skill https://github.com/petekp/claude-code-setup/tree/HEAD/skills/shape-up

Skill Files

Browse the full folder contents for shape-up.

Download Skill

Loading file tree…

skills/shape-up/SKILL.md

Skill Metadata

Name
shape-up
Description
>

Shape Up

Orchestrate the full Shape Up workflow by invoking /shaping and /breadboarding at the right moments. Be proactive — after each step, explain what was accomplished and suggest the next move.

Prerequisites

Requires the /shaping and /breadboarding skills to be installed. If missing, instruct the user to install them from https://github.com/rjs/shaping-skills

Workflow Overview

Frame → Shape → Breadboard → Slice → Build

| Phase | Purpose | Sub-skill | Output | |-------|---------|-----------|--------| | Frame | Capture the "why" | /shaping | Problem + Outcome | | Shape | Separate problem from solution, iterate | /shaping | R (requirements) + selected Shape | | Breadboard | Map affordances and wiring | /breadboarding | Affordance tables + diagram | | Slice | Cut into demoable increments | /breadboarding | V1..V9 vertical slices | | Build | Implement slice by slice | — | Working software |

Entry Point Detection

Determine the project type, then follow the appropriate path:

New project (empty or new directory)? → Start at Phase 1: Frame Existing project with code? → Start at Phase 0: Map Current System

Phase 0: Map Current System (Existing Projects Only)

Before shaping a change to an existing codebase, understand what exists.

  1. Ask: "What workflow or area of the system does this change affect?"
  2. Read the relevant code to understand the current implementation
  3. Invoke /breadboarding to map the existing system as CURRENT:
    • Trace the affected workflow through the code
    • Produce affordance tables (UI + Code) for the current system
    • Generate a wiring diagram showing how it works today

This CURRENT breadboard becomes the baseline. Proposed shapes will modify it.

After completing: Present the CURRENT breadboard and say:

"Here's how the current system works. Now let's frame what we want to change. What problem are you trying to solve, or what outcome do you want?"

Phase 1: Frame

Capture source material and distill it into Problem and Outcome.

  1. Ask the user to describe what they want (or paste stakeholder quotes, requests, etc.)
  2. Invoke /shaping — capture the description as Source material
  3. Distill into:
    • Problem — What's broken, what pain exists
    • Outcome — What success looks like
  4. Write to shaping.md in .claude/ (or project root for standalone projects)

After completing: Present the frame and say:

"Here's the frame. Does this capture the problem and desired outcome? Once confirmed, we'll start extracting requirements and sketching a solution."

Phase 2: Shape

Iterate on problem (R) and solution (shapes) until a shape is selected.

  1. Invoke /shaping
  2. Offer both entry points:
    • Start from R — extract requirements from the frame
    • Start from S — if user already has a solution in mind, capture it as Shape A
  3. Run the shaping loop:
Extract R → Sketch shape(s) → Fit check → Spike unknowns → Iterate

Proactive Guidance During Shaping

After extracting initial R and Shape A, immediately show the fit check:

"Here's R x A — the fit between requirements and the proposed solution."

Then suggest based on what the fit check reveals:

| Fit check shows | Suggest | |----------------|---------| | Flagged unknowns (warning markers) | "A2 is flagged — want me to spike it?" | | Requirements failing | "R3 fails because [reason]. Should we revise the shape or adjust R3?" | | All green | "The shape looks solid. Ready to breadboard?" | | Multiple viable shapes | "Both A and B pass. Want to compare with show me A x R vs B x R?" |

Shorthand Commands

Teach the user these as you go:

| Command | What it does | |---------|-------------| | show me R x A | Fit check: requirements against shape A | | show me A x R | Rotated fit check: shape A against requirements | | spike A2 | Investigate a specific part in depth | | add R that... | Add a new requirement | | sketch shape B | Propose an alternative approach |

Phase complete when: A shape is selected (passes fit check, unknowns resolved).

"Shape [X] is selected and all requirements pass. Ready to breadboard?"

Phase 3: Breadboard

Detail the selected shape into concrete affordances with wiring.

  1. Invoke /breadboarding
  2. For existing projects: breadboard the mixture — existing + new affordances wired together
  3. For new projects: breadboard from the shape's parts
  4. Produce:
    • Places table
    • UI Affordances table
    • Code Affordances table
    • Wiring diagram (Mermaid)

After completing:

"The breadboard shows [N] UI affordances, [N] code affordances across [N] places. Ready to slice into vertical increments?"

Phase 4: Slice

Cut the breadboard into demoable vertical slices.

  1. Invoke /breadboarding slicing procedure
  2. Identify V1 as the minimal demoable increment
  3. Layer additional capabilities as V2..V9
  4. For each slice, define:
    • Which affordances it includes
    • What mechanism it demonstrates
    • A concrete demo statement

After completing: Present the slice summary and say:

"We have [N] slices. V1 demos '[demo statement]'. Want to start building V1?"

Phase 5: Build

Implement each slice, verify it works, then move to the next.

For each slice:

  1. Create an implementation plan (V[N]-plan.md)
  2. Build the slice
  3. Verify: run and test to confirm the demo works
  4. Update the Big Picture document with completion status

After each slice:

"V[N] is complete — [demo statement] is working. Ready for V[N+1]?"

File Management

| File | Purpose | Location | |------|---------|----------| | shaping.md | Ground truth for R, shapes, fit checks | .claude/ or project root | | spike-[topic].md | Investigation findings | .claude/ or project root | | big-picture.md | High-level summary of entire feature | .claude/ or project root | | V[N]-plan.md | Per-slice implementation plans | .claude/ or project root |

Resuming a Session

When invoked with an existing shaping.md:

  1. Read the shaping doc to understand current state
  2. Invoke /shaping — it will detect the existing doc and show the fit check for the selected shape
  3. Identify what needs attention (unsolved requirements, pending slices)
  4. Suggest the next action:
    • If shaping: "R4 is still undecided — want to discuss?"
    • If breadboarded: "Ready to slice?"
    • If sliced: "V3 is next — want to build it?"
    • If building: "V2 is complete. V3 demos '[statement]' — ready?"