Capstone: design your own stack

Workshop chapter 6 of 6. Setup → Lab 1 → Lab 2 → Lab 3 → Lab 4 → Capstone (you are here).

The starter repo was a toy. The barrel-import rule was a toy. The point of the labs wasn’t the rule — it was the shape of the solution: prompt as the written source of truth, hook as the deterministic block, subagent as the dynamic auditor, skill as the named handle.

This chapter is the homework. Pick one rule you have been leaving in PR comments and design its four-layer stack.

The worksheet

Open a notes file. Answer six questions. Spend two minutes per question — not more.

1. The rule, in one sentence

The version you’d say out loud to a teammate. Not the prose for CLAUDE.md yet. Examples:

• “Don’t import from MUI directly — use our wrapper.”
• “Don’t use useEffect for data fetching — use React Query.”
• “Every new database column needs a migration test.”
• “No any in new code unless it’s wrapped in // @ts-expect-error with a reason.”

2. The mechanical shape

What’s the pattern a grep could find? Be specific. If you can’t write the regex, the rule isn’t mechanical enough for a hook — that’s fine, it might be subagent-shaped instead.

Example: from ['\"]@mui/(material|icons-material)['\"]

3. The hook

Given the regex from (2), what does the hook reject and what does it tell the agent? Sketch the stderr message — that’s what the agent will read on retry, and what a future teammate will read when they trip the guard.

✗ rejection: any from '@mui/material' in *.tsx message: “Import from @/components/mui-wrapper instead. We need the theme override.”

If question (2) had no clean regex, skip this. Hooks aren’t for fuzzy patterns.

4. The subagent

What’s the judgement version of the rule? Examples:

• Hook says no MUI imports. Subagent says: “Of the existing MUI imports, which ones can use the wrapper as-is, which need new wrapper variants, and which justify keeping the direct import (chart library bridges, etc)?”
• Hook says no useEffect for data. Subagent says: “Of the existing useEffects, which are data-fetching shaped, which are subscription-shaped (legitimate), and which are doing both badly?”

Pin the output format. A table is almost always right. Restrict the tool surface to read-only.

5. The skill

Name the verb. /migrate-mui, /audit-effects, /add-migration-test. Then write the procedure in five steps or fewer:

1. Call which subagent?
2. Walk rows / files in what order?
3. What do you ask the user to confirm partway through?
4. What’s the validation step at the end (typecheck, tests, lint)?
5. What does the final summary look like?

If the procedure needs more than five steps, split it. Skills should be the size that a teammate can hold in their head while they invoke one.

6. The first cut

Which layer would you ship first, alone? The answer is almost always the hook — it’s the smallest, the most reversible, and it stops the bleeding. But the rule will tell you. Some rules have no clean hook and start at the subagent.

A worked example

A rule from a codebase I work on: “No new useEffect for data fetching — use React Query.”

Question	Answer
Rule	No useEffect whose body calls fetch/axios/an api client.
Mechanical shape	Hard. A useEffect calling fetch is the pattern, but fetch can be wrapped in any helper. The mechanical version would catch only the most obvious cases.
Hook	Narrow: reject only useEffect whose body literally contains fetch( or await api.. Stderr points at the React Query example file. Catches ~70% of cases.
Subagent	effect-data-fetching-auditor — read-only, walks every useEffect in the codebase, classifies as “data-fetch (migrate)”, “subscription (keep)”, “ambiguous (review)”. Returns table.
Skill	/migrate-effect <file> — runs the auditor on one file, opens the React Query reference doc, walks the row(s), runs typecheck + the file’s tests.
Ship first	The hook. It’s two hours of work, it catches the obvious case forever, and it doesn’t block anyone from shipping legitimate effects.

That’s the entire design. About fifteen minutes. The hook gets written this week; the subagent next week if the hook proves the rule sticks; the skill only if a teammate ends up running the auditor more than once.

What this stack is not for

Three traps to avoid as you design:

Trap 1: building all three at once. Most rules don’t earn all three layers. Hooks are nearly free; subagents pay off when a rule needs codebase-wide context; skills pay off when a workflow needs to be discoverable. If a rule is hook-only, ship the hook and stop.

Trap 2: skills that just call one tool. /run-tests is not a skill — it’s an alias. Skills earn their existence by composing two or more layers, or by encoding a multi-step procedure a teammate would otherwise have to remember.

Trap 3: hooks that try to make judgements. If the regex needs three modes, four exceptions, and a state machine, you’ve reinvented a subagent badly. Step back. Write the subagent. Leave the hook for the truly mechanical core, if anything.

You’re done

Five chapters. One hook, one subagent, one skill. Sixty-five minutes of hands-on, ten minutes of design.

If this is your first time wiring all three, ship one rule to a real codebase this week — the smallest one you can find. The full template you just built will fit on a single PR: one shell script, one .claude/agents/*.md, one .claude/commands/*.md, plus the settings.json patch to wire the hook. That’s the minimum viable agent-ready setup. Everything from here is iteration on the same three shapes.

Where to go next

• The four trilogy posts cover each layer in more depth — read whichever you skimmed.
• The Marp deck is suitable for a 25-minute talk if you want to teach this in your own team.
• The starter repo’s solution branch has the finished hook, subagent, and skill if you want to diff your work against the reference.

I’d like to see what you built

If you wire your own triple after the workshop, I genuinely want to read it — the worksheet from the capstone, the hook script, the subagent prompt. Send it via the contact page or @ me on LinkedIn. I’ll keep a running list of community-contributed triples linked from this post over time.

If a teammate would benefit from the workshop, the most useful share is the workshop landing — the deck and labs are linked from there.

Open one PR. Wire one triple. The rest is muscle memory.