acaprariacaprari/specdriven-skills/skills/spec-bootstrap/SKILL.md

spec-bootstrap

Skill1 starsChanged 5 months agoMITView on GitHub

Use when starting a new project or new capability area before any code is written, to create the initial specs/ structure.

1 other project uses a version of this.

Adopted by

Most recently taken up by

apourmd941/selran-devlooptheir own version, first seen Jun 13, 2026

Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
apourmd941/selran-devloop★ 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 repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- spec-captureSkill
- spec-coreSkill
- spec-inferSkill
- spec-maintainSkill
- spec-validateSkill

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 7 are distinctive, and 0 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
If any condition is unmet, ask before writing.
line 21
Distinctive:
Ask targeted questions — one per gap, in priority order — before writing anything:
line 25
Distinctive:
Stop after the first unanswered question.
line 33
Distinctive:
If the description is too vague to identify core purpose and platform after one clarification round, state this explicitly:
line 39
Distinctive:
Do not attempt to infer. Do not write placeholder specs.
line 43
Distinctive:
Create these files, in this order:
line 47
Distinctive:
Create with equivalent content to the CLAUDE.md enforcement block above.
line 113

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “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: Bootstrap

Overview

Bootstrap creates the spec foundation for a project or new capability area. It does not write anything until the input clears the quality bar. A vague brief produces bad specs; bad specs undermine the rebuild guarantee.

Before Writing Anything

Evaluate the input against the quality bar. Four conditions must all be met before a single spec file is created:

Core purpose is unambiguous — the problem being solved and who it's for are clear enough that two developers would build the same thing
Tech stack is known or decidable — language, runtime, key libraries, storage; if none specified, enough context exists to make a defensible choice with rationale
Non-scope is defined — what this project explicitly does not do (prevents scope creep in specs)
At least one capability area can be identified with its decisions and invariants

If any condition is unmet, ask before writing. "Well-understood domain" does not substitute for unambiguous input — a task manager could be a CLI tool, a web app, a mobile app, or a Slack bot. Assume nothing.

Clarification Protocol

Ask targeted questions — one per gap, in priority order — before writing anything:

Core purpose gap → "What problem does this solve, and who uses it?"
Platform/interface gap → "How do users interact with it — CLI, web, mobile, API, other?"
Tech stack gap → "Any constraints on language, framework, or infrastructure?"
Non-scope gap → "What should this explicitly never do?"
Capability gap → "What are the main functional areas?"

Stop after the first unanswered question. Wait for the response before asking the next. Do not front-load all questions at once.

Do not write partial specs while waiting. Partial specs are worse than no specs.

The Wall

If the description is too vague to identify core purpose and platform after one clarification round, state this explicitly:

"I don't have enough to write specs that would clear the quality bar. I need at minimum: what this does, who uses it, and how they interact with it. Can you give me a one-paragraph description?"

Do not attempt to infer. Do not write placeholder specs. Do not proceed.

Output (when quality bar is met)

Create these files, in this order:

1. `specs/project.md`

# Project

## Purpose
What this project does and why it exists.

## Non-scope
What this project explicitly does not do.

## Tech stack
Key technology choices with rationale. Rejected alternatives where relevant.

## Architecture
The structural approach and why. Not a diagram — a decision.

## Dev commands
How to run, test, build.

2. `specs/<capability>.md` — one per identified functional area

Each file follows the capability spec format from spec:core. Every Decisions entry must have rationale. Invariants must be testable.

Seed ADRs (specs/adr/ADR-001-slug.md) only when a significant cross-cutting decision with a meaningful rejected alternative emerges. Do not create ADRs for straightforward choices.

3. `specs/README.md`

Brief descriptive text per capability — not a flat file index. A human reading it should understand what the project does and where to look for each area.

4. `CLAUDE.md` enforcement block

Append to an existing CLAUDE.md, or create it. Insert verbatim:

## Spec-driven development

This project follows spec-driven development.
Specs are the source of truth. Code is a derivative.

Before implementing any feature, bugfix, or refactor:
1. Read `specs/project.md`
2. Read any relevant capability spec in `specs/`
3. If no spec exists for the area you're touching, create one before writing code
4. If specs exist but are outdated, update them before writing code

Use the following skills:
- `spec:core` — core principles, always available as reference
- `spec:bootstrap` — starting a new project or capability
- `spec:maintain` — updating specs alongside a change
- `spec:capture` — capturing decisions from the current session
- `spec:infer` — recovering specs from an existing codebase
- `spec:validate` — auditing spec completeness and invariant coverage

Run `spec:validate` before considering any feature branch complete.

## Specs

Then append a generated list of the capability specs just created, one line each: - <capability>.md — <one sentence description>.

5. `AGENTS.md`

Create with equivalent content to the CLAUDE.md enforcement block above. This ensures non-Claude agents in the same project follow the same spec-driven workflow.

Common Mistakes

Mistake	Correct behaviour
Writing specs from a vague brief	Evaluate quality bar first. Ask if any condition is unmet.
Asking all questions at once	One question per gap, in priority order. Wait for each answer.
Inferring tech stack from domain type	"Task manager" ≠ CLI. Ask.
Writing placeholder specs to unblock	Partial specs are worse than no specs. Block until clear.
Skipping CLAUDE.md / AGENTS.md	Always append the enforcement block. It's what makes spec-driven development self-reinforcing.
Creating ADRs for every decision	ADRs are for cross-cutting decisions with meaningful rejected alternatives. Not for every choice.

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.

Check your setup, free