The Ship It
Graduate
Deck.
You know the alphabet. Now let’s write with it. Same widget, second time through, but this time with a proper site office behind you.
First, a quick
memory check.
Tap each card and try to say the answer out loud before you reveal it. Saying it aloud is how the knowledge sets in the concrete, rather than staying as scaffolding.
If you got four or more without peeking, you’re ready. If not, no shame. Flip back to Part 1 for ten minutes, then come back. This deck builds on every one of those.
API keys,
but safely.
Before anything else we’re going to sort out API keys. Think of them as the security passes you wear on site: one each for the services we’ll use, kept in a locked safe, scanned when needed.
Doppler is a free online safe for your API keys. It stops you ever pasting one into a file and accidentally committing it to the public internet (which happens to everyone eventually).
Get your passes, put them in the safe.
Good news: you can ask Claude to do most of this for you. “Run doppler setup for the tfl-widget project” will work. The steps below are just so you know what it’s doing.
Never paste an API key into a file. Never commit one. Never put one in a screenshot. If you ever do, rotate it immediately (the provider’s website has a “regenerate” button). Keys leaked to the public internet get abused within minutes.
Meet the Ship It repo.
Ship It is a project bible someone (hello) wrote after building one app the hard way. It’s not code. It’s a folder full of guides, templates, and reusable skills you copy into any new project. It saves you the mistakes.
How to use it.
You won’t be copying folders by hand. You tell Claude, and it handles the ceremony. Paste this into a fresh project folder:
Copy templates/ into my new project folder, copy the core skills from skills/ into .claude/commands/, and tell me when you’re done.
Four files Claude
writes for itself.
Every project has a pulse: where you left off yesterday, what’s in flight, what went wrong last time, what you decided and why. These four files carry that pulse between sessions so nothing gets lost.
NOW.md
book-keeping/NOW.md
Where we left off and what’s next. The “pick up the pencil” note. Claude reads it at the start of every session so you don’t have to re-explain yourself.
IMPLEMENTATION_PROGRESS.md
book-keeping/IMPLEMENTATION_PROGRESS.md
Running phase-completion tracker. Which phases are done, which are in flight, which haven’t started yet. Keeps everyone (you, Claude, future you) on the same page.
KNOWN_PITFALLS.md
book-keeping/KNOWN_PITFALLS.md
Traps the team fell into, so future-Claude doesn’t fall into them again. Grows slowly, one lesson at a time. Invaluable at month three.
DECISION_LOG.md
book-keeping/DECISION_LOG.md
The “why we chose X over Y” record. When someone asks six months later why the API is shaped this way, you have an answer with reasoning.
Like the daily site log, the variation register, the lessons-learned log, and the decision-and-variation log. Every serious construction project has them. Pretending you don’t need them is how projects go wrong.
Two more files live alongside these and come alive once you’re mid-build: OPEN_QUESTIONS.md (things you haven’t yet decided, so they don’t get forgotten) and FUTURE_IDEAS.md (things worth coming back to later). Don’t worry about those yet.
Ask Claude: “Based on what we did today, please draft a NOW.md for tomorrow.” Read what it writes. Tomorrow you’ll start where you left off.
Same discipline
as a drawing set.
Your repo has three scales, like a drawing set does:
The root folder. Shows what the whole project is about. Contains CLAUDE.md, SPECS.md, and top-level folders.
Feature folders. Each one contains everything about one feature: its spec, its rules, its tests. Self-contained.
Individual files. One thing each. A small function, a single page, a single skill. Tight scope.
Good structure lets Claude work without getting lost. Claude can open just the detail it needs, without loading the whole project onto its whiteboard. Same reason you don’t carry the site plan to decide a door ironmongery schedule.
Drawings reference
spec clauses.
On a real project, a floor plan doesn’t restate a spec clause. It says “see spec section 07 21 16” and your eye jumps to the right place. When the spec changes, the drawing still points correctly.
Ship It does the same. Every file that mentions a rule references it by name, not by copying it. Change the rule in one place, and every reference still works.
The wrong way
Do not quote user content longer than 40 characters.
# report_mode.md
Do not quote user content longer than 40 characters.
# voice_mode.md
Do not quote user content longer than 40 characters.
Three places to update. Two will be forgotten.
The Ship It way
Follow SPECS.md > Privacy > Quoting.
# report_mode.md
Follow SPECS.md > Privacy > Quoting.
# voice_mode.md
Follow SPECS.md > Privacy > Quoting.
One place to update. Every reference follows.
A drawing that says “fire rating: 60 minutes” will drift. A drawing that says “refer to fire strategy, 60-minute compartment” stays right forever, because there’s one fire strategy and everyone reads it.
Five skills,
one widget.
Ship It ships with dozens of skills. You don’t need dozens today. You need five. They chain together beautifully. Read each one slowly, they’re the vocabulary of the next forty minutes.
The conversational brief-taker.
Walks you through a Socratic conversation, one question at a time, to produce a proper product spec (SPECS.md). It draws out edge cases, failure modes, and things you hadn’t thought of. At the end it hands you a written brief so solid that no builder can misinterpret it.
The CLAUDE.md starter.
Scans your project and drafts a sensible first-pass CLAUDE.md, the file Claude reads at the start of every session. You refine from there. Ships with Claude Code, so it’s always available.
The feature architect.
Takes one feature and plans it properly: produces a spec, a contract of what it does and doesn’t do, its states, and its acceptance criteria. Think of it as pulling one detail drawing out of the site plan.
The revision-stamper.
Reads what you just did, writes a clean commit message, and saves the checkpoint locally. It does not push to GitHub or open a pull request, those are separate on purpose. For pushing, say “please push” to Claude. To commit + push + open a PR in one go when deliberately closing a pack, use /commit-push-pr.
The second pair of eyes.
Spins up specialist sub-agents to review your recent changes for bugs, silent failures, sloppy types, drifted names, and missing tests. They all run in parallel and report back. It’s like having your whole review team on call, on tap.
A real build day is richer than it looks here. The short version: /spec-writer once at the start, /init straight after, then for each phase: /feature-plan → build → /commit when something works → /review before opening a PR. At session end, /wrap tidies your book-keeping files; a separate push sends your commits to GitHub. Part 3 opens each step up properly.
Start every session with
a guide on your shoulder.
Ship It has one skill that’s different from the others. It’s not a tool, it’s a teacher. Run it first thing every session.
On invocation it actively reads your NOW.md and progress tracker, then tells you where you left off and what comes next.
Before you say “ready for the next phase”, it quietly runs a visual-phase gate: have you completed the design audit for this phase? Are there device screenshots committed? Has the context-budget been checked? If any of those are missing, it refuses to greenlight. Not punitive, protective.
In practice it might say: “You’re about to move to Phase 3 but I don’t see a design-audit artefact from Phase 2. Shall we do that first?” Or: “Context is at 78%. Consider a /wrap and fresh session before the next phase.”
It’s like having a senior architect beside you on every site visit. Not doing your job, just making sure you don’t miss the obvious.
Six stages.
One rhythm.
Same rhythm you already know: understand, plan, build, check, hand over. Each stage has one or two skills that live there naturally.
Spec
Blueprint
Plan
Build
Review
Ship
You don’t have to remember the names. Just notice the rhythm: understand, plan, build, save, check, ship. Over and over again, for every feature you add.
Part 3 goes inside each stage and shows the real moving parts. For today, knowing the rhythm is enough.
Now rebuild the widget,
the grown-up way.
Last time we shipped it with three prompts. That was enough to prove the idea. Now we’ll do it again, using the skills you just learned. You’ll notice two things: it’s slower to start, and it’s much, much faster to finish.
You’re rebuilding deliberately, not because Part 1 failed, but because the second time through is where the pattern sticks. This is the same reason you’ll sketch a junction detail twice on a new project, even though you know it.
Allow about 60 to 90 minutes for all five steps. You do not need to finish in one sitting. If you run out of time at Step 3, save the session and come back tomorrow, your NOW.md will tell Claude where to pick up.
Start with /spec-writer
Open a fresh Superset workspace. You’ll need the Ship It skills copied in. Tell Claude the path to your local ship-it folder (tip: drag the folder from Finder into the terminal to paste its path) and say: “please copy every skill from that folder’s skills/ directory into .claude/commands/ here”. Then start Claude with:
I want to build a small, beautiful iPhone widget for London tube arrivals and line status. You know the drill, please run the five-phase flow.
Claude will ask you questions, one at a time. Answer honestly. At the end you’ll have a SPECS.md that’s way better than the scribbled plan we made last time.
Then /init
Claude reads your new SPECS.md and drafts a CLAUDE.md. Look it over. Tighten anything that feels too vague or repeats the spec. Keep it under a hundred lines.
Now /feature-plan
The widget is a single feature. Please plan it as one feature pack, kept small.
This produces the feature’s own little spec pack, the detailed drawing for this one thing.
Build, then /commit
Now ask Claude to start building against the plan. Work in small chunks. Every time something works, type:
You’ll end up with a lovely history of small, readable checkpoints. If anything goes wrong you can rewind one step at a time.
Finish with /review
Check the widget for bugs, silent failures, and anything I might have missed. Make sure the TFL API key is only ever read from Doppler, never pasted in a file.
You’ll get a structured report. Fix anything urgent, commit those fixes, and ship. Congratulations, you’ve just built software the way professionals do.
Last time you got to working code. This time you got to confident code: something you can extend, hand off, or come back to in a month without being lost. That’s the graduation.
Let Claude
ask first.
Most AI mistakes come from Claude guessing instead of asking. The single biggest upgrade to your workflow is making “ask first, build second” the default. Five minutes of questions upfront beats an hour of debugging wrong assumptions later.
- What should the filter do? Hide arrivals later than 10 minutes, or toggle which lines show?
- Where does the control live? A row of chips above the list, or a dropdown in the top right?
- Should the choice stick? Remember it across page refreshes, or reset every load?
Three assumptions caught in thirty seconds. Answer, and Claude builds what you meant.
Two ways to turn it on.
Ad hoc · say it in the prompt
Good for any one-off task. Tack this onto your opening message:
Zero setup. Claude pauses and asks. When you’re happy, answer all five and it starts.
Always on · one line in CLAUDE.md
Good when you want this for every task, every session. Add this rule near the top of your project’s CLAUDE.md:
Now it’s the house rule. Every future session opens with Claude pausing to think, not typing.
Every wrong assumption becomes wrong code. Questions expose those assumptions before a single line is typed. One ten-second answer spares you rewriting a whole component. You already know this pattern from architecture: specify before you draw, measure twice, cut once. Same rule.
Open your tfl-widget project’s CLAUDE.md and add the line from Card 02. Save. Restart Claude. Ask for any small tweak, like “add the Bakerloo line to the defaults”. Count how many of your quiet assumptions Claude surfaces before it touches a file.
Hooks run the checks
you’d forget to.
You just built something. You noticed Claude sometimes does the obvious thing wrong: forgets to format, edits the wrong file, bypasses a check. A hook is how you stop that from happening twice.
A hook is a little script that fires at a fixed moment in every tool call, before Claude edits a file, after it runs a test, at session start. It’s always on, even when you forget to ask. Like the site safety officer: enforces process constraints without taking part in the design.
Three hooks worth having from day one.
Auto-format
Fires every time Claude writes a file. Runs Prettier (or your equivalent) so the code stays tidy without asking. You never have to say “please format that.”
Scope guard
Before Claude edits a file, checks whether it’s in the current phase’s scope. If not, asks first. Catches scope creep before it starts.
No-verify blocker
Blocks git commit --no-verify, which is how agents accidentally skip pre-commit checks. One line of defence.
Hooks live in .claude/settings.json at the top of your project. Ship It has a starter pack in templates/. You can also describe one in plain English with the /hookify skill and it writes the config for you.
Ask Claude: “add the auto-format hook from ship-it templates to this project.” Then save any file and watch the formatter fire.
Related habit: write the test from the acceptance criteria before writing the code. Research (METR, 2025) found experienced developers are 19% slower using AI without this loop. With it, Claude catches its own mistakes before you ever see them.
Before you close this,
write three things.
This is the most important page in the deck. Take two minutes. Type into each box. These words become the shape of what you know.
Three things I can do today that I couldn’t do yesterday.
Your words. Not anyone else’s. What is genuinely new for you?
One thing I’m still unsure about.
Naming the gap is how it gets filled. This is your next question for me, or for Claude.
(Your written answers are saved in this browser. Recap card states reset on reload.)
A monthly
ten-minute ritual.
A project, like a building, needs maintenance. Every month, sit down for ten minutes and do these five things. Future-you will be so grateful.
Prune CLAUDE.md
Ask Claude to read it and suggest what to cut. If anything’s out of date, edit it.
Review your skills
Any skill you didn’t use this month? Either delete it or rename it so its purpose is clearer.
Rotate your API keys
Go to each provider, rotate the key, update it in Doppler. Five minutes of paranoia well spent.
Check the spec still matches
Skim SPECS.md. If the app does something the spec doesn’t mention, update the spec.
Tidy the repo
Old branches you’ll never use again? Delete them. A clean repo is a clear head next month.
End of Part 2.
You know the alphabet. You know the basic grammar. You’ve built something twice, felt the difference.
Your one next action
Run /spec-writer on a project you already have but haven’t started. You’ll feel it click.
Coming when you’re ready
Part 3: The Full Workflow
Feature packs. Phase gates. Screen inventory. Asset generation. Parallelism. The real end-of-pack review. Open it when you want to see inside each stage.
Open Part 3 →Made with care for Janika, who builds actual buildings.
Stuck on something?
Type it here. It goes straight to Munim.