astroville/sprout / .claude/skills/spec-composition
spec-composition
VerifiedWhen work would produce 2+ related specs, prefer initiative-first composition over `/design` × N siblings. Carries the canonical "multiple related specs" phrasing that both interactive triage (`/roadmap-review`) and design-time routing (`/design`) quote.
What I do
Hold the canonical doctrine — and one specific paste-ready sentence — for the "multiple related specs" condition: when the body of work in front of the user is two or more topically related specs with no shared initiative parent.
Two surfaces consume me:
/roadmap-review(interactive triage) — surfaces orphan clusters that already exist in the planning corpus and offers to/composethem into an initiative./design(multi-spec routing, sibling specmulti-spec-design-routing) — catches the condition at design time, before the second or third related spec lands, and routes the user toward/composefirst.
Both surfaces quote the same canonical sentence from me. I exist so the wording stays consistent across the two moments and neither surface re-invents it.
Goal
When two or more related specs would be created (or already exist
unparented), prefer initiative-first composition — /compose into
a parent with phased children — over scaffolding N flat sibling
features. Flat orphans become discoverable only by accident; an
initiative parent makes the work legible as a unit.
This is composition discipline, not sizing. A medium cluster of
three orphans is a composition problem; the size ladder doesn't model
it. That's why this skill exists separately from spec-sizing.
Canonical phrasing
The sentence both surfaces quote verbatim, substituting the slugs:
<slug-a>,<slug-b>, and<slug-c>look topically related and none of them have an initiative parent. If they're one body of work,/composelifts them into a shared initiative. If they're genuinely independent, no action needed. Want me to/composethem?
Do not paraphrase. Quoting keeps the user's mental model of the nudge stable across the design-time and triage-time surfaces.
Triggers
The nudge fires when any of the following is true during a
/design invocation. These are deliberately not AND-ed — each one
independently signals a composition moment, and a single trigger is
enough.
-
Explicit multi-deliverable phrasing. The
/designrequest names ≥ 2 distinct deliverables. Pattern recognition the agent already does — no NLP, no learned model.- "design X, Y, and Z"
- "spec out these three things"
- "I need specs for A and B"
- "design these four features"
- "and also" / "plus" / "along with" when each side names a discrete deliverable
-
Lead-identified sub-deliverables. While clarifying the request, the lead recognizes ≥ 2 independent sub-deliverables that would each warrant their own spec — different surfaces, different acceptance criteria, could ship independently. This is design judgment, not a mechanical rule. Lean toward not firing if uncertain.
-
Rolled-up size ≥
large. If the lead can estimate the deliverables' sizes individually, and the midpoint-sum across them rolls up tolargeor higher on the shared ladder (per the midpoint-sum mechanic ininternal/snapshot/rollup.go), the cluster wants an initiative parent regardless of how the request was phrased. Fall back to triggers #1 / #2 when there isn't enough information to estimate.
Any-of. One trigger is sufficient.
Phrasing
Paste-ready text the lead quotes when a trigger fires. Direct,
non-hedging — name the alternative and ask. The canonical sentence
under ## Canonical phrasing above is the orphan-cluster variant
used by /roadmap-review; the variants below are the design-time
variants, parameterized by which trigger fired.
Trigger #1 — request names multiple deliverables
You named N deliverables here (
<thing-a>,<thing-b>,<thing-c>). I'd recommend running/composeinstead — that creates an initiative with N child stubs, ready for individual/designpasses when each is up. The alternative is N flat sibling specs with no parent, which usually gets reparented later anyway. Want me to/composethis, or proceed with the siblings here?
Trigger #2 — lead spotted sub-deliverables during clarification
Listening to this, it sounds like ≥ 2 independent pieces of work (
<piece-a>,<piece-b>) — each could ship on its own and each wants its own acceptance criteria. I'd recommend/composeinstead — scaffold an initiative parent now and/designeach child when you're ready to flesh it out. Want to switch, or stay in/designand ship this as a single spec?
Trigger #3 — rolled-up size ≥ large
This is shaping up as ≥
largerolled up across multiple deliverables. That's initiative territory — I'd recommend/composeinstead, which scaffolds the parent and lets you sequence the children. Want to switch, or stay in/designand ship this as a single spec?
Substitute the slugs / deliverable names inline; otherwise quote verbatim. The wording is short and decision-oriented — a fired nudge should be a 5-second yes/no, not a conversation.
Stance
The recommendation is advisory, never a block. Same stance as
the sizing nudge in spec-sizing ("user always wins"), word-for-word
on the override behavior:
- The lead surfaces the recommendation once per
/designinvocation. - The user can answer "no, just do them as siblings" / "proceed" / "stay in design" / "ship it" — any clear decline — and the lead resumes the design flow as if the nudge had not fired.
- The lead records the user's choice in the session so the rest of the session does not re-litigate it. One decline covers the whole session (see Suppression).
- On "yes, compose," the lead hands off cleanly into the existing
/composeflow with the user's original/designrequest as the initiative input — it does not simulate/composeor scaffold flat siblings.
The nudge is friction with an off-ramp, not a gate. A loud linter warning, not a build failure.
Precedence
When the routing nudge (this skill) and the sizing nudge
(spec-sizing) would both fire on the same /design request, the
routing nudge fires first, and the sizing nudge stands down for
that moment.
Concretely:
- Routing nudge: "Your request describes ≥ 2 specs — consider
/composeto scaffold the cluster as an initiative." - Sizing nudge: "This individual spec is
large/x-large/giant— consider/splitor/composefor this spec specifically."
They describe different moments — composition shape vs. individual spec size — but the user shouldn't get both at once.
- If the user accepts routing and pivots to
/compose, the sizing nudges resurface naturally inside the per-child/designpasses as each child is fleshed out. Each child is sized on its own when it lands, so the sizing nudge fires per-child at the natural moment. - If the user declines routing and proceeds with N siblings,
the sizing nudge fires per-sibling as usual — each sibling is
sized when written, and the sizing nudge fires per the schedule
in
spec-sizing.
Either way, the two stances stay consistent ("user always wins") and
exactly one nudge fires per moment. spec-sizing cross-references
this precedence rule so the two skills agree.
Suppression
Three suppression rules keep the nudge from re-firing at the wrong moments:
-
Already in a
/composeflow. If the/designinvocation was itself launched from/compose(e.g., the user is now fleshing out a freshly-scaffolded child stub of an initiative), the composition decision has already been made. Do not fire. -
User declined earlier in this session. If the user has already declined the routing nudge in this session ("no, siblings is fine" / "ship as siblings" / similar) on a prior
/design, the lead suppresses re-firing for the rest of the session. One decline covers the whole session — do not re-litigate on each sibling. -
The sizing nudge would also fire. Per the Precedence rule above: when both would fire on the same
/designrequest, the routing nudge claims the slot first. The sizing nudge stands down for that moment and fires per-child later (either inside the/composechild specs, or per-sibling if the user declined routing).
These three suppressions are inclusive — any one of them stops the nudge. The lead does not need to walk all three before deciding to stay quiet.
Cross-skill references
spec-sizing— the size ladder. This skill does not duplicate the per-type bands or the tier definitions; sizing remains the source of truth for "how big is this." Composition discipline is a separate axis.roadmap-review— interactive triage that fires the canonical phrasing above when priority-4 findings (orphan clusters) surface.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |