cg-plan

name

cg-plan

description

Invoke when the user wants to plan a feature by identifying which parts should be widgets and which parts should stay as app glue. Fires on "plan this feature", "break this feature into widgets", "what widgets would I need for X", "how should I decompose Y", "what parts of this are reusable". Works per-feature, not per-app — if the user brings a whole app, narrow to one feature first. Does NOT fire once implementation has started, or for one-off fixes. Does NOT teach widget design patterns, glue gotchas, or authoring (that's widget creation, not identification). Does NOT teach the cloud layer (cg-cloud), change config (cg-config), or review proposals (cg-proposals).

cg-plan — identify what should be a widget

This skill has one job: given a feature the user wants to build, identify which pieces should be widgets and which should stay as app-specific glue. The output is a roadmap, not an implementation.

It fights two failure modes at once:

• Under-extraction — leaving reusable logic buried inside app code because it "looks routine."
• Over-extraction — promoting consumer-shaped refactors into widgets when the only justification is "the current app hardcodes this."

If the conversation drifts into actually writing widget code, this skill ends. The user takes the roadmap into the widget-authoring flow.

Tool boundary

Prefer Cartograph MCP tools when they cover the action. Use registry_widget search and registry_widget inspect for registry lookup, registry_widget install when a match should be installed, and widget_status for installed widget state. installed_widget is for upgrade/uninstall actions, not search.

Use the cartograph CLI only for capabilities not exposed by the MCP surface or when the user explicitly asks for CLI behavior.

Scope: one feature at a time

This skill plans a single feature. If the user frames the ask as a whole app ("help me plan this app"), narrow first:

"A full app is too wide to decompose in one pass. Pick one feature — we'll walk it, you'll see the pattern, and we can do the next separately."

Then start with that one feature. Don't compromise.

The walk

1. State the feature

One or two sentences. What it does, what the consumer is. Just enough to ground the next steps. Don't design yet.

2. Brainstorm candidates

List every piece of logic that could conceivably be a widget. Be generous — at this step the filter is off. Aim for 5–12 candidates for a real feature. Small things count. "Looks routine" does NOT disqualify at this stage.

3. Classify each candidate

Two moves per candidate. Both always apply.

The from-scratch test — a positive identifier.

Ask: "Would a shared base implementation of this benefit from being iterated on across projects?"

Two signals, either one sufficient to flag as a widget candidate:

• Painful to redo. Non-trivial logic, tricky edge cases, easy to get wrong the first time. Dreading the rewrite is the flag.
• Improves with iteration. Each new consumer would reveal better APIs, missing edge cases, or small performance wins. This is often the stronger signal — it catches simple logic that's still worth centralizing because it hardens through use.

This test fights under-extraction. It catches logic hiding in what looks like app-specific code. Things that feel like ordinary business logic often contain the real work: retry semantics, pagination, dedup, validation, auth flows, formatting rules.

The consumer-shape red flag — a disqualifier.

If the only justification for making this a widget is "the current app hardcodes it" or *"this bit of the current consumer should be factored out," that's consumer reasoning, not domain reasoning. Kill the candidate. It can be refactored in-place without becoming a widget.

A second form of the same red flag: small patterns composited into a bigger-sounding abstraction to make them pass the from-scratch test. The composite has to pass on its own. If it only passes as a bundle, the bundle isn't real.

Both moves run on every candidate. A candidate survives if the from-scratch test says yes AND the red flag doesn't trip.

4. Search the library (informational)

For each survivor, search the library once with registry_widget search using 2–3 terms drawn from the candidate's generic framing. If local installed state matters, use widget_status. Not a gate — information.

Three outcomes per survivor:

• Already covered → install the existing widget, no new work.
• Partial match → improve the existing widget (closer look at the gap). If the gap is genuinely app-specific, that part stays in glue.
• Needs creation → new widget, framed generically.

Descriptions stand alone — when you check matches, judge them on their own text. Don't rely on name-adjacency.

5. Deliver the roadmap

Four buckets for the feature:

• install — existing widgets to install as-is.
• improve — existing widgets to extend, with a one-line note on the gap.
• create — new widgets, each framed generically in one line. Include both "obviously generic" candidates and "looked app-specific until we ran the from-scratch test."
• glue — what intentionally stays in the app. Brief one-liners so the user sees what's NOT a widget and why.

For candidates that survived via the from-scratch test's "improves with iteration" signal, note that framing explicitly — it signals to the user that this widget will start small and harden across consumers rather than arriving fully formed.

That's the output. Stop there.

Generic framing

Every widget description — in the roadmap and eventually in the widget itself — must stand alone without naming the current consumer. Examples of the shift:

• "LLM token pricing" → "metered pricing"
• "user checkout flow" → "multi-step form with validation"
• "dashboard data loader" → "paginated resource fetcher"

If you can't frame a candidate generically, that's a signal — either the framing needs work, or the candidate is actually glue.

What not to do

• Don't try to plan a whole app in one pass. Narrow to one feature.
• Don't apply the from-scratch test to a candidate and accept a consumer-shaped justification. The test asks about the logic's value across projects, not about what the current app does.
• Don't skip the red-flag check. Over-extraction creates widget sprawl.
• Don't composite small patterns into a bigger-sounding one to force a pass. The composite has to stand on its own.
• Don't use search as a gate. The roadmap exists independent of library state; search just tells the user what already exists.
• Don't cross into implementation. This skill stops at the roadmap. Widget authoring is a separate step.
• Don't name-drop sibling widget_ids in descriptions or reasoning. Each widget stands on its own framing.

Scope

Per-feature widget identification. That's the whole surface. If the user wants to talk about how to design a widget's API, author it, wire it in, handle contamination scanner issues, or anything downstream of the roadmap — that's outside this skill. Hand off cleanly.