Shaping Documents Keep Agent Work From Becoming Vibes

·https://github.com/rjs/shaping-skills
repoaiagentsclaude-codeshape-upshapingplanningagent-loopsworkflow-rig

The framing/kickoff docs and ripple hook map to joelclaw workload planning: keep shaped intent, affordances, fit checks, and work streams synchronized before agents write code.

Ryan Singer’s shaping-skills repo adapts Shape Up shaping and breadboarding for Claude Code. The clever bit is that it doesn’t ask an agent to “plan better” in the abstract. It gives the agent concrete commands: /framing-doc, /kickoff-doc, /shaping, and /breadboarding.

The document skills have a good boundary: they format and distill transcripts, but they don’t pretend to judge whether the thinking is any good. The README calls this out as GIGO, which is exactly the right amount of humility for agent-assisted planning. If the conversation was sloppy, you get a clean-looking sloppy doc. That’s not a bug. That’s a receipt.

The part worth stealing for joelclaw is the ripple hook. When Claude Code writes or edits a Markdown file with shaping: true in frontmatter, the hook reminds it to update the related affordance tables, fit checks, work streams, and other dependent sections. That’s the useful pattern: a shaping document shouldn’t be inert. If an agent changes the shape, the document should push back before the next beautifully formatted bullshit plan turns into code.

Key Ideas

  • Document skills and solo skills are split cleanly: /framing-doc and /kickoff-doc distill real collaboration, while /shaping and /breadboarding are for working directly with Claude Code.
  • The GIGO warning is the contract: these skills preserve and structure thinking; they don’t magically make weak thinking strong.
  • /shaping separates the problem and possible solution shapes before implementation, with fit checks for what’s solved and what isn’t.
  • /breadboarding maps UI affordances, code affordances, and wiring in one view, which makes vertical slicing easier to see.
  • The shaping-ripple.sh hook watches for shaping: true Markdown edits and prompts a ripple check after Claude Code Write or Edit operations.
  • The symlink install keeps each skill as a direct child of ~/.claude/skills/, so the repo can be updated with git pull without copying skill folders around.

Links

← All discoveries