A personal spec-driven workflow toolkit for working with Claude Code.
Claude Code is powerful but freestyle use produces mid-quality output. Long sessions drift, prompts get buried, and there's no structured way to catch mistakes before they land. The output feels fast but isn't reviewable.
This kit codifies a different approach: specs before code, an A→F cycle with human-approved phase gates at every transition, and a three-party review loop that catches errors any single party would miss. The discipline is portable across any codebase, any language, any task size.
The method is the product. The scaffolding here is just what makes it repeatable.
The kit codifies discipline that pays off when work is multi-step, multi-file, or quality-critical. It's overhead when work is none of those. Don't use the kit for:
- One-shot reads (what does this function do?)
- Code explanations or learning queries
- Quick refactors of <20 lines in a single file
- Scratchpad experiments you'll throw away
- Tasks where you genuinely don't care about quality
For real work — features, fixes, releases, anything that matters — the method's overhead pays itself back many times over. For exploratory or trivial work, it's friction.
The honest test: if you wouldn't review the output before committing it, you don't need the method.
Every piece of work involves three parties:
- You — decision-maker. Approves phase transitions. Catches mistakes everyone else misses.
- Architect — drafts specs, reviews phase outputs, pushes back on drift. Either chat Claude (for greenfield projects) or Claude Code in a separate session (for brownfield work where codebase context matters).
- Executor — Claude Code in the project repo. Runs A→F per spec. Writes code. Commits.
Flow:
┌─────────────────────────────────────────────────────┐
│ │
│ YOU ──── planning ────▶ ARCHITECT │
│ │ │ │
│ │◀──── spec drafts ──────────│ │
│ │ │
│ ├── paste session prompt ──▶ EXECUTOR │
│ │ │ │
│ │◀──── phase output ───────────────│ │
│ │ │
│ ├── "does this look right?" ─▶ ARCHITECT │
│ │◀──── review + pushback ──────────│ │
│ │ │
│ └── "proceed to C" ──────────▶ EXECUTOR │
│ │
└─────────────────────────────────────────────────────┘
| Mode | Tier | Trigger | Scaffolding | Specs | Architect |
|---|---|---|---|---|---|
| New project | 3 | Empty repo, week+ of work | New repo from this template | 10-20 atomic, all drafted upfront | High |
| Feature | 2 | Existing codebase, hours-to-days | .claude-local/<name>/ (gitignored) |
1-5, all drafted upfront | Medium |
| Bug fix | 1 | <1 hour, single session | None | None | Low (on-demand) |
Specs-first is universal for Tier 2 and Tier 3. Tier 1 is the only mode without pre-drafted specs.
Starting new work. Which mode?
┌─────────────────────────────────────────────────────┐
│ │
│ Will this take more than a day? │
│ │
│ NO ──▶ Is it in an existing codebase? │
│ │ │
│ YES ──▶ Do you expect multiple sessions? │
│ │ │ │
│ │ NO ──▶ MODE 3 (BUG FIX) │
│ │ YES ──▶ MODE 2 (FEATURE) │
│ │ │
│ NO ──▶ MODE 1 (NEW PROJECT) │
│ │
│ YES ──▶ Is it in an existing codebase? │
│ │ │
│ YES ──▶ MODE 2 (FEATURE) │
│ NO ──▶ MODE 1 (NEW PROJECT) │
│ │
│ When in doubt, start at Tier 1. │
│ Promote to Tier 2 if you discover real scope. │
│ Don't start at Tier 3 and demote. │
│ │
└─────────────────────────────────────────────────────┘
This section explains what user-level CLAUDE.md enforces in every Claude Code session, and why each rule exists.
Top-tier Opus required by default. Drift to lower tiers causes quality regressions that are hard to diagnose mid- session. Each project pins its model explicitly so model upgrades don't silently change behavior.
Six phases for every state-changing task:
- Analyze — read context, report findings, propose nothing yet
- Blueprint — propose the implementation in detail, no code yet
- Code — implement the approved blueprint
- Diff — show every change made
- Evaluate — run tests, lint, typecheck
- Finalize — commit per spec format
Each phase has a different mode of thinking. Mixing them (e.g., proposing solutions during Analyze) is the most common reason sessions go wrong. The cycle forces separation.
Between every phase, the executor stops and waits for explicit user approval. Vague approvals like "looks good" do not count — only "proceed to [next phase]" or equivalent.
The phase gate is the single most important rule. Skipping it produces fast, low-quality output. Honoring it produces slow, reviewable, correct output.
After Phase F, before declaring a session complete, the executor runs a 7-item verification:
- All declared files exist
- All "do not touch" files are untouched
- Commit message matches required format
- No uncommitted changes
- DEBT entries recorded if applicable
- Acceptance criteria satisfied
- Deviations from blueprint stopped execution per §5
If any check fails, the session is NOT complete. The user must direct what happens next.
Known issues, deferred work, and intentional shortcuts go into the project's DEBT.md with incrementing numbers. Resolved entries are marked RESOLVED in place — never deleted, never renumbered. The audit trail matters more than tidiness.
Silent deferrals ("we'll fix that later") are forbidden. If you're choosing not to fix something now, document why.
When a spec needs to change after it's been locked or
executed, never patch it in place. Open a fresh session,
draft a new spec file (specs/NN-amendment-to-spec-MM.md),
and execute it as its own A→F cycle.
The original spec is the historical record of what was decided when. The amendment is the agreed change. Both exist. Neither overwrites the other.
For Tier 2 (feature) and Tier 3 (project) work, all specs must be drafted and approved before any execution begins. No "we'll figure out the next spec as we go." Specs are the contract between architect and executor sessions; without a contract, executor work drifts.
- Click "Use this template" on github.com/ashawareb/kit
- Clone your new repo, edit template/CLAUDE.md
- Open architect session, draft all specs together
- Open Claude Code in the project, paste prompts/RUN-tier3.md
- Execute specs sequentially with phase gates
- In your existing repo, ensure .claude-local/ is gitignored
- Create .claude-local//
- Open architect session, draft 1-5 specs
- Open Claude Code in the project, paste prompts/RUN-tier2.md
- Execute with phase gates
- Open Claude Code in the repo where the bug lives
- Paste prompts/RUN-tier1.md with the bug description filled in
- Run A→F inside one session
- If scope grows mid-session: stop, promote to Tier 2
One-time per machine:
cp user-CLAUDE.md ~/.claude/CLAUDE.md
This installs the personal method into every Claude Code session on this machine, in every project.
For full setup including verification and multi-machine notes, see INSTALL.md.
kit/
├── README.md ← this file
├── INSTALL.md ← one-time setup guide
├── LICENSE ← MIT
├── user-CLAUDE.md ← personal method, copies to ~/.claude/
└── template/
├── CLAUDE.md ← per-project scaffolding
├── docs/
│ └── DEBT.md ← empty known-issues registry
├── prompts/
│ ├── architect-chat-opener.md ← primes chat Claude as architect
│ ├── architect-cc-role.md ← primes Claude Code as architect (default)
│ ├── RUN-tier1.md ← bug fix session prompt
│ ├── RUN-tier2.md ← feature execution prompt
│ ├── RUN-tier3.md ← new project execution prompt
│ └── amendment.md ← amendment session prompt
└── specs/
├── EXAMPLE-spec-01.md ← one filled-in toy example
└── spec-template.md ← blank spec skeleton
RUN-tier1.md— single-session bug fixRUN-tier2.md— feature in existing repoRUN-tier3.md— new project from scratch
Each is the entry point for an executor Claude Code session at that tier. Names are deliberately parallel so you can find the right one in seconds.
architect-chat-opener.md— for chat Claude (web/app)architect-cc-role.md— for Claude Code in a separate session (the default for brownfield work)
amendment.md— universal, paste at the top of any fresh session that's amending an existing spec
Format: specs/NN-short-name.md where NN is a zero-padded
sequence number (01, 02, ..., 15).
Amendments use: specs/NN-amendment-to-spec-MM.md where MM
is the original spec number.
The architect catches mistakes the executor misses, and vice versa. Solo Claude Code review (you reviewing CC's output alone) means errors at your blind-spot intersect with CC's blind-spot pass through. Three-party catches more.
The 30 minutes spent specifying often save 4 hours of rework. Specs are how you make decisions explicit before they get encoded in code. Code that doesn't match a spec is harder to review, harder to change, and harder to explain. Slow drafting is fast shipping.
Tier 1 (bug fix) does not require an architect — the discipline lives in user-CLAUDE.md and one session can hold the entire scope. Tier 2 and Tier 3 require an architect by design. If you find yourself wanting to skip the architect for "small" Tier 2 work, that's usually a signal it should be Tier 1 instead.
Fork the kit. Edit user-CLAUDE.md. Use your version. The kit isn't dogma — it's one person's working discipline made portable. Your discipline may differ.
The user-level CLAUDE.md is Claude Code specific (memory file). The conceptual method (specs-first, phase gates, EOS check, DEBT) is tool-agnostic. You could adapt it to other tools, but you'd need to re-implement the loading mechanism.
See the mode detection flowchart above. When in doubt, start at Tier 1 and promote if scope grows. Don't start at Tier 3 and demote — over-speccing is fixable mid-session, under-speccing usually isn't.
Verify it loaded: open Claude Code and ask "what method file are you operating under?" — should reference user-CLAUDE.md. If not, see INSTALL.md troubleshooting.
MIT. See LICENSE.