ai-blueprint: Skill for Claude Code

brief - understand a feature before you spec it

Context reuse: Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed.

Where this sits in the workflow:

build-plan + overview  ->  [brief]  ->  /feature  ->  /implement
(what exists)              (read-only    (spec it)     (build it)
                            explainer)

This skill answers one question: what does this feature actually involve, before I commit to spec'ing it? It reads the two files that describe the work and prints a short briefing so you can decide whether to spec it now, reorder it, split it, or clear a blocker first. It is the read-only precursor to /feature.

It never writes anything: no spec, no edits to build-plan.md, no branch, no commit. /feature is the mutating step that turns a briefing into a spec; this one just explains.

How it differs from its neighbors:

• /status reports the whole project: progress, current work, git, next action. /brief zooms into one feature and explains it in depth.
• /feature writes the spec (and may split the item in build-plan.md). /brief previews what /feature would tackle, changing nothing.

Input

A feature from build-plan.md, by number or name - e.g. /brief 4 or /brief "validator".

With no argument, brief the next one - the first unchecked leaf in build-plan.md, the same target /feature would pick.

If build-plan.md is still a placeholder stub or the overview is missing, say so plainly and point at /overview (or filling the plans) rather than inventing a briefing.

What it reads

Gather these, then synthesize. Don't dump file contents; explain.

1. The target - the feature's line in blueprint/build-plan.md, plus whether a parent was already split into sub-items (4a, 4b, ...).
2. Full context - blueprint/context/project-overview.md: the data model, routes/endpoints, stack, UI/UX, conventions, and open questions that touch this feature.
3. What already exists - earlier checked build-plan items and, if useful, git history, to ground the dependency read (what must be in place first, what this unblocks later).
4. Design reference - if prototypes/ exists and the feature is UI-facing, note which mockups apply (that /feature will link them and port theme.css).