Shape Up
Orchestrate the full Shape Up workflow by invoking
and
at the right moments. Be proactive — after each step, explain what was accomplished
and suggest the next move.
Prerequisites
Requires the
and
skills to be installed. If missing,
instruct the user to install them from
https://github.com/rjs/shaping-skillsWorkflow Overview
Frame → Shape → Breadboard → Slice → Build
| Phase | Purpose | Sub-skill | Output |
|---|
| Frame | Capture the "why" | | Problem + Outcome |
| Shape | Separate problem from solution, iterate | | R (requirements) + selected Shape |
| Breadboard | Map affordances and wiring | | Affordance tables + diagram |
| Slice | Cut into demoable increments | | 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.
- Ask: "What workflow or area of the system does this change affect?"
- Read the relevant code to understand the current implementation
- Invoke to map the existing system as :
- 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
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.
- Ask the user to describe what they want (or paste stakeholder quotes, requests, etc.)
- Invoke — capture the description as Source material
- Distill into:
- Problem — What's broken, what pain exists
- Outcome — What success looks like
- Write to in (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.
- Invoke
- 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
- 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 vs ?" |
Shorthand Commands
Teach the user these as you go:
| Command | What it does |
|---|
| Fit check: requirements against shape A |
| Rotated fit check: shape A against requirements |
| Investigate a specific part in depth |
| Add a new requirement |
| 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.
- Invoke
- For existing projects: breadboard the mixture — existing + new affordances wired together
- For new projects: breadboard from the shape's parts
- 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.
- Invoke slicing procedure
- Identify V1 as the minimal demoable increment
- Layer additional capabilities as V2..V9
- 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:
- Create an implementation plan ()
- Build the slice
- Verify: run and test to confirm the demo works
- 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 |
|---|
| Ground truth for R, shapes, fit checks | or project root |
| Investigation findings | or project root |
| High-level summary of entire feature | or project root |
| Per-slice implementation plans | or project root |
Resuming a Session
When invoked with an existing
:
- Read the shaping doc to understand current state
- Invoke — it will detect the existing doc and show the fit check for the selected shape
- Identify what needs attention (unsolved requirements, pending slices)
- 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?"