Most side projects stall because "improve the portfolio" is not a task — it is a mood. This build avoids that by turning the whole thing into a numbered list.
The spec is the contract
Before any code, there is a SPEC.md: the stack (locked, no substitutions), the
design tokens, five non-negotiable design rules, the route list, and a table of
eleven phases. Each phase has a single deliverable and a one-line definition of
done.
A session picks up exactly one phase. It does not scaffold ahead. When Phase 3 is the projects grid, Phase 4's GitHub sync does not get a placeholder folder — it does not exist yet.
Every commit clears the same bar
There is no "I'll fix the types later." The gates are fixed:
pnpm build # zero type errors
pnpm lint # zero eslint warnings
pnpm test # unit tests for anything with logicIf a commit does not pass all three, it is not a commit. That sounds strict, but
it means the main branch is always in a shippable state, and the next session
starts from something that works instead of something half-finished.
What carries between sessions
A CLAUDE.md at the repo root holds the tokens, the five rules verbatim, and a
short note for each decision that could otherwise be re-litigated — why a
particular hover glow was dropped, why the résumé PDF uses no letter-spacing.
New context, same constraints.
Why it works
The constraint that does the most work is "one phase per session." It forces each piece to be finished — responsive, tested, committed — before the next one starts. The portfolio is never 80% done in eight places at once.