Shape Up

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

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:

Shorthand Commands

Teach the user these as you go:

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

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?"