skills

A personal Claude Code skills library built around one deliberate, gated workflow:

/spec  →  /plan  →  /build  →  /test  →  /review  →  /ship

When uncertainty is high, use a prototype pass first:

/prototype  →  /spec  →  /plan  →  /build  →  /test  →  /review  →  /ship

Use this path when the question is still ambiguous after interview (for example, uncertain state model behavior, unclear interaction design, or multiple plausible approaches with low confidence).

Each step is a skill in skills/<name>/SKILL.md. Unlike command-driven setups, invocation is controlled entirely through skill frontmatter:

• The pipeline skills (spec, plan, build, test, review, ship, plus the where status check) set disable-model-invocation: true, so they only run when explicitly invoked (typing /spec, /plan, etc.) — never auto-triggered by Claude matching their description against the conversation.
• Standalone skills like tdd omit that flag, so they trigger automatically from context (e.g. Claude reaches for /tdd's discipline when you ask it to add a new function, no explicit invocation needed).

There's no .claude/commands/ layer, no agent personas, no hooks — the skill is the command.

The pipeline

Each step reads the previous step's output, writes its own, and stops for your approval before the next step runs. Nothing auto-chains. Artifacts live in the project you're working in (not this repo), under a per-feature folder in the project's shared git dir:

# git rev-parse --path-format=absolute --git-common-dir
<git-common-dir>/specs/<slug>/
├── spec.md      # /spec   — problem, goals, requirements, acceptance criteria
├── plan.md      # /plan   — technical approach, files touched, key decisions
├── tasks.md     # /plan writes it, /build's task subagents check tasks off + append task notes,
│                #   /test appends verification
└── review.md    # /review — final spec-conformance verdict

Individual tasks in tasks.md may carry an optional trailing `[model: X]` tag — /plan adds it where a task warrants a specific model, and /build's orchestrator dispatches that task's subagent with it; a task with no tag gets the orchestrator's default (sonnet).

Important

Start a new session for each step. The artifact is the hand-off — it contains everything the next step needs. Opening a fresh session keeps context slim and focused; don't carry a long session forward into the next step. /build is the one step that spans more than a single session: a build orchestrator session dispatches one disposable task subagent per task in tasks.md, sequentially, so no single session's context grows with the whole feature's implementation work — see skills/build/SKILL.md.

Putting artifacts under the shared git dir (.git/specs/, not a working-tree specs/) is deliberate. The pipeline is stateful across sessions, and Claude Code may transparently switch a step into a background-isolated worktree. A worktree gets its own working directory but shares the one .git, and crucially ignored/untracked files do not cross into a worktree — so a specs/ folder that's .gitignored becomes invisible to the next step, breaking the hand-off. Resolving to <git-common-dir>/specs sidesteps this: the path is identical from the main tree and every worktree, the artifacts are never committed (they live inside .git), and there's no .gitignore entry to maintain. git rev-parse --git-common-dir also makes the location deterministic, so /where and /tally can always find it.

If a step's required input file is missing, it tells you which command to run first instead of improvising.

/where is a read-only status check across a feature's specs/<slug>/ artifacts — it reports which gate you're at (spec ✓ plan ✓ build 3/7 test — review —) and the single command to run next. Useful when returning to a feature after a break, since the pipeline is stateful but otherwise has no way to query the current state.

/clean is the destructive counterpart to /where: it removes the specs/<slug>/ artifacts of features that are complete (a passing review.md with every AC<n> met), leaving in-flight work untouched. It always lists the candidates and waits for confirmation before deleting anything, and it excludes features whose review looks green but has drifted — so a spec that quietly changed after review isn't swept away as finished. Because the artifacts live inside .git, deleting a folder is the whole operation — nothing to commit, no .gitignore to update.

/review is a spec-conformance check (did we build what /spec said), not a code-quality or security review — pair it with your existing code-review/security-review tooling for that.

/ship is the operational close: once /review passes, it turns the work into git state — a feature branch, atomic commits mapped to the tasks, and a draft PR built from spec.md + review.md — then hands off to /code-review and /security-review for the code-quality/security gates this pipeline deliberately delegates. It confirms before any outward-facing step (push, PR) and never merges. Unlike the other steps it writes no specs/<slug>/ artifact; its output is the branch, commits, and PR.

Looping back

The pipeline flows forward but isn't one-way. Real work loops back — /test fails and you re-/build, or you realise mid-build that the spec was wrong. The catch is that the artifacts form a dependency chain (spec → plan → tasks → verification → review), so changing anything upstream silently invalidates everything downstream of it. Left unmanaged, that drift is invisible until it bites.

The fix is a reconciliation discipline rather than a rule against looping back:

• Each step skill, when it changes an artifact that already has downstream artifacts, reconciles them in the same pass — re-run the affected step, edit-and-revalidate, or explicitly confirm still-valid. The protocol (which change invalidates what) lives in skills/where/RECONCILE.md.
• /where is the backstop: it detects drift (an AC<n> with no verification entry, an upstream file changed after a downstream one) and surfaces it as a ⚠ line, so drift that slipped past a hand-edit gets caught the next time you check state.
• Stable AC<n> IDs make spec↔test drift content-detectable. The known blind spot is a reworded AC (same ID and count) — so the discipline is to re-run /test after any change to an AC's meaning.

Ubiquitous language & ADRs

domain-modeling maintains two project-level (not per-feature) files, ported from mattpocock's skills:

/
├── CONTEXT.md         # or CONTEXT-MAP.md for multi-context repos — the project's glossary
└── docs/
    └── adr/
        ├── 0001-slug.md
        └── 0002-slug.md

CONTEXT.md is a glossary only — canonical terms, what to avoid, nothing implementation-specific. docs/adr/ records decisions that are hard to reverse, surprising without context, and the result of a real trade-off; see domain-modeling/ADR-FORMAT.md for the full test. Both are created lazily, the moment there's a real term or decision to capture — not scaffolded up front.

This isn't a separate step — it's threaded through the pipeline: /spec and /plan sharpen fuzzy terms and read existing ones before writing anything, /plan offers ADRs for architectural forks, /build respects both while implementing, and /review flags glossary drift or missing ADRs as part of its verdict.

Two supporting skills make this work, both ported near-verbatim from mattpocock/skills:

• grilling — a relentless, one-question-at-a-time interview technique. /spec and /plan use it for their interview steps; it's also available standalone whenever you want to stress-test a plan outside the pipeline (auto-triggers on "grill" phrasing).
• grill-with-docs (/grill-with-docs, explicit only) — runs a grilling session while using domain-modeling to capture glossary terms and ADRs as they come up. Useful for a standalone design discussion that isn't going through /spec//plan but still deserves permanent documentation.

Skills

Skill	Invocation	Purpose
spec	/spec (explicit only)	Interview + write the spec and acceptance criteria
plan	/plan (explicit only)	Technical approach + atomic task breakdown
build	/build (explicit only)	Orchestrator dispatches one task subagent per task, one at a time
test	/test (explicit only)	Verify acceptance criteria with real evidence
review	/review (explicit only)	Final spec-conformance verdict
where	/where (explicit only)	Read-only status: which pipeline gate a feature is at + next command
clean	/clean (explicit only)	Delete completed features' spec artifacts from the shared git dir, after confirmation
tally	/tally (explicit only)	Read-only per-step + total token/USD tally for a feature
ship	/ship (explicit only)	Branch, commit per task, draft PR; delegates to code-review/security-review
tdd	automatic	Red-green-refactor nudge when writing new behavior
domain-modeling	automatic	Maintain CONTEXT.md glossary + docs/adr/ decisions
grilling	automatic	Relentless one-question-at-a-time interview
grill-with-docs	/grill-with-docs (explicit only)	grilling + domain-modeling combined, for standalone design sessions
handoff	/handoff (explicit only)	Compact the current conversation into a handoff doc for another agent
skill-gap-scan	automatic	Detect repeated friction and recommend which workflow should become a new skill
prototype	automatic	Throwaway prototype (logic or UI) to answer a design question fast

Credits

This repo borrows ideas and, in several cases, ported content from two existing skills repos:

• addyosmani/agent-skills — the shape of the gated spec → plan → build → test → review pipeline with persisted hand-off artifacts and human-approval checkpoints between steps.
• mattpocock/skills — the terse SKILL.md style, the user-invoked/model-invoked split via frontmatter, and the domain-modeling, grilling, grill-with-docs, tdd, handoff, and prototype skills, ported here directly or near-verbatim.