agentleFS
GideonKai33GideonKai33/claude-skills/skills/spec-build/SKILL.md

spec-build

Skill0 starsChanged 6 months agoMITView on GitHub

Use this skill when the user wants to turn a software, automation, or tool project into an agent-runnable build plan. Walks through a Discovery Brief dialogue (problem, user, out of scope, stack, done), then decomposes the work into atomic phases of roughly 5-15 minutes each with observable acceptance criteria and explicit per-phase non-goals. Produces two artifacts: `discovery-brief.md` and `phases.md` in the project folder. Triggers include "/spec-build", "phase out this project", "turn this into a build plan", "make this agent-runnable". Do NOT use for writing projects (book chapters, essays), relational or business projects, or vague ideas that haven't been promoted to a real project yet — those need different treatment.

3 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions3 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 3

    1. rioffe/speccheck★ 5same name
    2. pjlangley/ff★ 4same name
    3. cldanielhernandez/claude-skills★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository2 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 6 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If the request is outside this scope, decline gracefully and explain why.

    line 22
  2. Distinctive:

    Read whatever project context already exists: a project README, a CLAUDE.md, any existing planning notes.

    line 32
  3. Very specific:

    Check for existing spec artifacts: If discovery-brief.md or phases.md already exist in the target folder, ask whether to redo from scratch, …

    line 34
  4. Distinctive:

    If the answer is no or unclear, bail gracefully and suggest the user think the scope through first, or pick a different planning approach.

    line 42
  5. Very specific:

    Ask these five questions, one at a time.

    line 46
  6. Distinctive:

    If a phase feels bigger than 15 minutes of agent work, split it.

    line 91
  7. Distinctive:

    If the user already has a phased plan from earlier work, use it as the starting point and decompose any phase that's too big into atomic …

    line 93
  8. Distinctive:

    Living-contract rule applies: If work later reveals the Discovery Brief or Phases doc got something wrong, update the doc *first*, then …

    line 130
  9. Very specific:

    No API keys, no accounts, no configuration required.

    line 135

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/spec-build — Spec-Driven Build

Turn a software or tool project into an agent-runnable build plan. Two artifacts come out of this: discovery-brief.md (the one-page upstream doc) and phases.md (the atomic phase breakdown). The goal is a plan that's small enough at each step to actually finish, with verifiable acceptance criteria so you know when each phase is done.

When to use

  • The project is a software build, automation, tool, or technical pipeline
  • The plan is to hand significant chunks of the work to Claude Code (or another agent)
  • A project folder or at least a clear scope exists

When NOT to use

  • Writing projects (book chapters, essays, scripts). Those need flow, not phase gates.
  • Relational or business projects (launching a service org, recruiting clients). Wrong fit for a bounded-scope build framework.
  • A vague idea that hasn't been scoped at all yet. The user needs to think the project through first; this skill produces a plan, not the idea.

If the request is outside this scope, decline gracefully and explain why.

Inputs

The project name or folder path. If not specified, ask the user where the project lives or whether they want the artifacts created in the current working directory.

Workflow

Step 1: Read what exists

Read whatever project context already exists: a project README, a CLAUDE.md, any existing planning notes. Get full context before asking questions. If there's nothing yet, that's fine — proceed to Step 2 and gather context through the dialogue.

Check for existing spec artifacts. If discovery-brief.md or phases.md already exist in the target folder, ask whether to redo from scratch, refine in place, or skip a step. Never silently overwrite.

Step 2: Fit check

Ask one question:

"Spec-Driven Build is tuned for software, automation, and tool projects with bounded scope and an agent-built implementation. Does that match what you're doing here?"

If the answer is no or unclear, bail gracefully and suggest the user think the scope through first, or pick a different planning approach.

Step 3: Discovery Brief dialogue

Ask these five questions, one at a time. Don't push if the user doesn't have an answer. Capture what they do have and flag the gap with a <!-- TODO --> comment in the brief so it doesn't get lost.

  1. What's the problem? One paragraph. What is broken or missing.
  2. Who's the user? The person who will use the thing once it's built.
  3. What's explicitly out of scope? Multiple items. These are the v1 non-goals. The clearer this is, the less the agent invents.
  4. Stack constraints? Languages, frameworks, hosting, decisions already made.
  5. What does done look like? Concrete and observable. Something verifiable in 30 seconds when walking back into the project after time away.

Step 4: Write discovery-brief.md

Save to the target folder using this template:

# [Project Name] — Discovery Brief

The one-page upstream doc for the Spec-Driven Build of this project.

## Problem
[From Q1]

## User
[From Q2]

## Out of scope (v1)
- [From Q3]

## Stack constraints
- [From Q4]

## Done looks like
[From Q5]

Step 5: Phase decomposition dialogue

Walk the user through phasing in two passes:

Pass 1 — Stages. What are the high-level stages of work? Group related concerns together. Examples: "Pipeline core," "Frontend + viewer," "Polish + first real run."

Pass 2 — Atomic phases per stage. For each stage, decompose into phases of roughly 5 to 15 minutes of agent work. For each phase, capture:

  • Goal: one sentence
  • Acceptance: observable criterion the user can verify
  • Out of scope for this phase: specific things not to touch in this phase

If a phase feels bigger than 15 minutes of agent work, split it. The atomic phase is the unit that prevents the agent from drifting; the more discipline here, the better the build runs.

If the user already has a phased plan from earlier work, use it as the starting point and decompose any phase that's too big into atomic chunks.

Step 6: Write phases.md

Save to the target folder using this template:

# [Project Name] — Phases

Agent-runnable phase breakdown. Each phase is roughly 5 to 15 minutes of agent work, has a testable acceptance, and explicit non-goals.

**Workflow rule:** stop at the end of each phase, verify acceptance personally, commit, then unlock the next. If a phase reveals a wrong assumption, update the Discovery Brief or this Phases doc *before* continuing.

## Stage 1 — [Name]

### 1.1 — [Phase name]
**Goal:** [one sentence]
**Acceptance:** [observable criterion]
**Out of scope for this phase:** [specific things not to touch]

### 1.2 — [Phase name]
[etc.]

## Stage 2 — [Name]
[etc.]

Step 7: Confirm

Tell the user:

  • The two new artifacts that exist now (discovery-brief.md and phases.md) and where they live
  • That Phase 1.1 is ready to run in a fresh Claude Code session pointed at the spec docs
  • The suggested workflow: open Claude Code in the project folder, tell it "Read the Discovery Brief and Phases doc. Run Phase 1.1 only. Stop after acceptance is met."

Notes

  • Living-contract rule applies. If work later reveals the Discovery Brief or Phases doc got something wrong, update the doc first, then continue. Don't flag for later. The drift compounds silently and the doc becomes fiction.
  • The atomic-phase discipline matters more than the document format. If the user prefers different filenames or structure, the underlying framework still applies.

Setup notes (first run)

No API keys, no accounts, no configuration required. Drop this skill into ~/.claude/skills/spec-build/SKILL.md and use it.

For best results, run this from inside an existing project folder (or a folder where you want the spec artifacts saved). If you're starting from a fresh idea, scope it loosely on paper first — even a one-paragraph summary helps the Discovery Brief dialogue land.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.