agentleFS
JBSommelingJBSommeling/claude-config/.agents/skills/spec-driven-development/SKILL.md

spec-driven-development

Skill0 starsChanged 29 days agoMITView on GitHub

Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea.

  • Reads credentials

109 other projects use a version of this, 19 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use using-agent-skills, shipping-and-launch and 7 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • LLl0k0laDSkill

    using-agent-skills

    Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.

    Also in 44 projects that use this

  • LLl0k0laDSkill

    shipping-and-launch

    Use when preparing to deploy to production. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.

    Also in 53 projects that use this

  • MrCipherSmithSkill

    constraint-driven-development

    Use when a project needs a persistent, measurable quality bar — starting a project without documented standards, 'set up constraints', or when coverage/perf/a11y thresholds get re-debated per-PR. Produces CONSTRAINTS.md with enforceable numbers, ratchets, and a guard against silent weakening. NOT for throwaway prototypes or a one-off CI setup.

    Also in 16 projects that use this

  • HK-hubSkill

    observability-and-instrumentation

    Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting. Use when shipping any feature that runs in production and you need evidence it works. Use when production issues are reported but you can't tell what happened from the available data.

    Also in 36 projects that use this

  • seikaikyoSkill

    doubt-driven-development

    對非平凡決策啟動新鮮 context 對抗審查(找碴不背書),在修正還便宜的時候抓出錯誤方向。適用:高風險改動(production、資安敏感邏輯、不可逆操作)、不熟的程式碼、要宣稱「這樣是安全的 / 可行的」之前。機械性操作與一行修改不適用。

    Also in 44 projects that use this

  • +4 more from LLl0k0laD

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. 0 are common, 10 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 102 edited versions we read keep these.

  • 10

    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:

    Write a structured specification before writing any code.

    line 8
  2. Very specific:

    Skip this section entirely when repos= is absent: No discovery, no subagents, no extra spec sections — this is the most important rule.

    line 22
  3. Very specific:

    When repos=<path> appears in $ARGUMENTS:

    line 24
  4. Distinctive:

    If the resolved path does not exist or contains no git repositories, skip discovery and continue as a single-repo run without failing.

    line 27
  5. Very specific:

    Refuse: if the resolved path is /, $HOME, or a system root (/Users, /home, /root) — those resolve to an unbounded scan blast radius.

    line 29
  6. Distinctive:

    No file contents from a non-primary repo may appear in the spec or any downstream artifact.

    line 39
  7. Distinctive:

    If the candidate count exceeds 10, sort candidates lexicographically by directory name and scan the first 10.

    line 41
  8. Distinctive:

    Always do: [non-negotiable rules]

    line 64
  9. Distinctive:

    Ask first: [needs human approval]

    line 65
  10. Distinctive:

    Never do: [hard constraints]

    line 66
  11. Distinctive:

    When a Repo Allocation is present, tag acceptance criteria per repo so "done" is defined for each one.

    line 69
  12. Distinctive:

    Update when decisions or scope change

    line 101
  13. Distinctive:

    Commit the spec to version control

    line 102

“Common” is measured: kept by at least 6 in 10 of the 102 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-Driven Development

Write a structured specification before writing any code. The spec defines what we're building, why, and how we'll know it's done.

Gated Workflow

Four phases. Do not advance until current phase is validated by the user.

SPECIFY → PLAN → TASKS → IMPLEMENT
   ↓        ↓      ↓        ↓
 Review   Review  Review   Review

Cross-Repo Context (optional)

Skip this section entirely when repos= is absent. No discovery, no subagents, no extra spec sections — this is the most important rule.

When repos=<path> appears in $ARGUMENTS:

  • Relative paths resolve against $HOME (Development/tba → $HOME/Development/tba); absolute and ~/-prefixed paths are used as-is. The path is used exactly as given — on case-sensitive filesystems the case must match exactly.
  • If the resolved path does not exist or contains no git repositories, skip discovery and continue as a single-repo run without failing.
  • The primary repo root is resolved via git rev-parse --show-toplevel; it is not overridable.
  • Refuse if the resolved path is /, $HOME, or a system root (/Users, /home, /root) — those resolve to an unbounded scan blast radius. Echo the resolved absolute path and the full candidate list before scanning begins so scope is visible before any data is read.
  • Discover candidates: direct children of <path> that have a .git directory (not a file) at their own root. A .git file signals a submodule or linked worktree whose gitdir: pointer may redirect to a different repository — reject it. *.worktrees directories have no .git at their own root and are excluded without special-casing. The primary repo root (resolved via git rev-parse --show-toplevel) is always excluded from candidates — it always participates and is never dropped, even if a none scan verdict is returned.
  • Resolve each candidate with realpath; display the resolved path at the spec checkpoint — symlinks must be transparent so the checkpoint shows where data is actually read from, not the alias.
  • Skip any candidate whose resolved absolute path contains a character outside [A-Za-z0-9._/-]; list every skipped candidate at the spec checkpoint. Directory names are pasted verbatim into shell commands and cannot be safely quoted — rejection at discovery is the only safe gate.

Scan — up to 10 read-only subagents in parallel, on the cheap search tier:

  • Pass feature keywords extracted from the user's request; each scanner greps for them. Keyword-scoped grep keeps output bounded — scanners do not summarise the whole repo.
  • Scanners hard-exclude .env*, *.pem, *.key, *.p12, *.pfx, id_rsa*, credentials, *.tfstate, and honour each repo's .gitignore — credential files are never read or reported on.
  • Each scanner returns: repo name, one-line purpose, stack, public surface (API routes, exported packages, published or consumed events), and a relevance verdict of none / low / high. Evidence is file paths and symbol names only — never raw file content or matched lines.
  • No file contents from a non-primary repo may appear in the spec or any downstream artifact. Scanner evidence flows into the Repo Allocation and from there into the spec and PR body — the chain must carry no secrets.
  • Drop none repos immediately. They do not appear in the spec or any downstream phase.
  • If the candidate count exceeds 10, sort candidates lexicographically by directory name and scan the first 10; list the remainder as unscanned in the spec so the user sees them at the checkpoint — they are not silently dropped.
  • Scanners are read-only: they report, they do not edit.

Phase 1: Specify

Surface assumptions immediately:

ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies
3. Database is PostgreSQL (based on existing schema)
→ Correct me now or I'll proceed with these.

Write a spec. Areas 1–7 always apply; include area 8 when repos= was supplied:

  1. Objective — What, why, for whom, success criteria
  2. Design — Components and their responsibilities, data flow between them, and error handling (what can fail, how it is detected, what the user or caller sees)
  3. Commands — Full executable commands (build, test, lint, dev)
  4. Project Structure — Where source, tests, and docs live
  5. Code Style — One real code snippet showing style beats paragraphs describing it
  6. Testing Strategy — Framework, locations, coverage expectations
  7. Boundaries:
    • Always do: [non-negotiable rules]
    • Ask first: [needs human approval]
    • Never do: [hard constraints]
  8. Repo Allocation (when repos= was supplied) — per participating repo: what changes there, why it belongs there rather than elsewhere, and the contract it exposes or consumes.

When a Repo Allocation is present, tag acceptance criteria per repo so "done" is defined for each one. The spec checkpoint is where the user confirms the allocation — it is the architectural decision in the change.

Reframe vague requirements as testable success criteria:

"Make the dashboard faster"
→ LCP < 2.5s on 4G, initial load < 500ms, CLS < 0.1
→ Are these the right targets?

Phase 2: Plan

With validated spec, generate technical implementation plan:

  • Major components and dependencies
  • Implementation order
  • Risks and mitigations
  • What can parallelize vs. must be sequential

Phase 3: Tasks

Break plan into discrete tasks. Each task:

  • Completable in one focused session
  • Has acceptance criteria
  • Has verification step
  • Touches ~5 files or fewer
  • Ordered by dependency

Phase 4: Implement

Execute tasks one at a time following the incremental-implementation and tdd skills. Load the right spec sections and source files at each step rather than flooding the context with the entire spec.

Keeping the Spec Alive

  • Update when decisions or scope change
  • Commit the spec to version control
  • Reference spec sections in PRs

Red Flags

  • Starting code without written requirements
  • Implementing features not in any spec
  • Making architectural decisions without documenting them
  • Skipping the spec because "it's obvious"

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.