Shapeup

ShapeUp Skill — v2.1

Shape Up workflows for Claude Code — covering every stage from raw problem to wiring diagram to structured handoff documents. Run these before writing code.

Resource Files (Load On Demand)

This skill lazily loads detail from resource files. Read the relevant resource before executing any workflow:

| Sub-command | Resource to Read | |---|---| | /shapeup shaping | resources/shaping.md | | /shapeup spike | resources/spike.md | | /shapeup breadboarding | resources/breadboarding.md | | /shapeup framing-doc | resources/framing-doc.md | | /shapeup kickoff-doc | resources/kickoff-doc.md | | /shapeup breadboard-reflection | resources/breadboard-reflection.md | | /shapeup full | Read resources/shaping.md first, then resources/breadboarding.md before B-phases, and resources/context-compaction.md for the run digest |

> Resource paths are relative to this skill's directory (resources/ beside this SKILL.md, wherever the plugin is installed). > Multi-gate runs maintain a derived decision digest so each gate reads a compact slice instead of full prose — see resources/context-compaction.md and the "Run Workspace & Digest" section below.

---

Canonical Workflow Order

/shaping                    /breadboarding
─────────────────────────   ───────────────────────────────────
1. Problem frame             5. [optional] Fat marker sketch
2. Requirements (R)          6. Affordance tables + wiring
3. Solution shape (A)        7. SLICING → vertical scopes
4. Fit check (R ↔ A)
       ↓
   Spike docs
(for unknowns only)
       ↓
  breadboarding

The single most common mistake: putting slicing inside shaping. Slicing is the final phase of breadboarding — not shaping. Shaping ends at the fit check.

---

Which Sub-Command to Use

| You have... | Use... | |---|---| | A raw idea and want the full shaped pitch | /shapeup full | | A raw problem or feature idea | /shapeup shaping | | Shaped solution with unknowns to de-risk first | /shapeup spike | | Shaped solution ready for concrete wiring | /shapeup breadboarding | | A transcript of a problem/betting conversation | /shapeup framing-doc | | A transcript of a shaped project kickoff | /shapeup kickoff-doc | | An existing breadboard with design smells | /shapeup breadboard-reflection |

---

Invocation

# DEFAULT — no sub-command = runs full pipeline automatically
/shapeup

# Explicit full pipeline (same as default)
/shapeup full

# Individual phases
/shapeup shaping
/shapeup spike "Does zoneinfo cover our timezone needs, or do we need a network API?"
/shapeup breadboarding

# Document skills (team/collaborative contexts)
/shapeup framing-doc `:

| Root | Contents | Nature | Git |
|---|---|---|---|
| `shapeup/[slug]/shaping/` | shaping · breadboard · spike · pitch · kickoff | **durable source** | commit, shared |
| `shapeup/[slug]/spec/` | domain model · UC · contracts · tasks (ba-pitch-analyzer output) | **durable deliverable** | commit, shared |
| `.shapeup/[slug]/` | run-state · gate log · **digest.md** · orient/ · evaluation/ · qa/ · ledger | **ephemeral / derived** | **gitignore (hidden)** |

- **Shared** root `shapeup/[slug]/` = what the team contributes to
  (source + deliverable). **Local** root `.shapeup/[slug]/` = per-run scratch,
  hidden and fully gitignorable. Add **one** line to `.gitignore`: `.shapeup/`.
  No carve-out needed — everything machine-written at run time, including the
  harvest shards `.shapeup/metrics/*.jsonl`, lives under the local root.
- `digest.md` is the run's derived decision context (the 4-field, two-zone read
  model the gates consume). It is **never** the source of truth and never crosses
  a skill boundary — `ba-pitch-analyzer` reads `pitch.md`/`shaping.md`, never the
  digest.
- **Ripple-check rule (mandatory):** the digest carries **no `shaping: true`** —
  it is a sink, not a node. The ripple-check **must glob-exclude
  `.shapeup/`**, or it will scan the digest as a source and ripple
  incorrectly.

---

## Integration with ba-pitch-analyzer

/shapeup shaping → shaping.md /shapeup spike → spike-[part].md (as needed) /shapeup breadboarding → breadboard.md (with slices) ↓ /ba-pitch-analyzer shapeup/[feature-slug]/shaping/shaping.md ↓ shapeup/[feature-slug]/spec/ (domain model, contracts, use cases, tasks)

Reference affordance IDs (U[N], N[N]) in task descriptions and commit messages
to maintain traceability: breadboard → task → commit.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nguyenvanphituoc](https://github.com/nguyenvanphituoc)
- **Source:** [nguyenvanphituoc/shapeup-sdlc-plugin](https://github.com/nguyenvanphituoc/shapeup-sdlc-plugin)
- **License:** MIT
- **Homepage:** https://github.com/nguyenvanphituoc/shapeup-sdlc-plugin#readme

Install and usage instructions live in the source repository linked above.