---
name: spec
description: Use for nontrivial implementation, requirements, a PRD or vision document, or acceptance criteria. Defines done before code. Not for trivial edits, exploration, spikes or prototypes.
title: spec
canonical_url: https://skilld.dev/gh/masihmoafi/skills/spec
last_updated: 2026-11-03T09:01:25.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install masihmoafi/skills/spec`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/spec`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/masihmoafi/skills/spec) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/spec`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/spec --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/spec --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Spec-driven development

Define what done means before code, because an agent fills every gap in intent from its training data. A spec adds no approval gate; ask only about material gaps.

Size the loop to the task (Stanford CS146S, 29 Sep 2026):

- a copy change or small fix: just ask the agent;
- a small feature across several files: one plan;
- a medium feature: research, then plan, in separate sessions;
- a big refactor or migration: several rounds of research and plans, split into stacked issues, one agent each.

For discovery, spike first and specify once the behavior is known. Review the spec and plan yourself; that review is where the leverage is.

The loop: **Specify, Plan, Execute, Verify.** Go back to Specify when evidence changes the intent.

## 1. Specify

Numbered items, each with an acceptance check and a status, written before work begins. A check is observable ("feature works" is not one). When the change touches money, data, security or an external integration, add all four risk checks:

1. **Failure:** what happens when a dependency or write fails.
2. **Concurrency:** what happens when actors or async events collide.
3. **Observability:** how production behavior is measured.
4. **Rollback:** how the old behavior comes back, and how that is checked.

When intent has gaps, interview the user (goal, constraints, criteria, non-goals, edge cases) before writing. Keep the spec in version control beside the code it governs. Two tiers, after [OpenSpec](https://openspec.dev): `specs/` holds the current truth of each capability; a change is a short proposal with its delta against that truth, and once shipped its delta is merged into `specs/` and the proposal archived. No competing specs for one capability.

```markdown
# SPEC: [Feature]

Goal: [1-3 sentences: the problem and the outcome]
Invariants: [contracts and rules that must not break]
Constraints: [stack, banned dependencies, limits]

| # | Item | Acceptance check | Status |
| --- | --- | --- | --- |
| 1 | [observable happy path] | [command or action → result] | todo |
| 2 | [failure / concurrency / rollback, as relevant] | … | todo |

Non-goals: [what must not be touched]
Stop and ask: [3-5 task-specific conditions, e.g. a test still fails after 3 fixes; data would be deleted outside a test environment]
```

## 2. Plan

Read the spec and the codebase's conventions; write the approach, the trade-off chosen and why, the files affected and the order. Then split it into tasks: one atomic change each, ordered by dependency, each with a binary done-check (if it needs "and" twice, split it). Rate each task's **importance** (foundational, important, nice-to-have) and **difficulty** (easy, medium, hard) separately: importance is value, difficulty routes the work.

## 3. Execute

One task per fresh session when a combined diff would be too big to review; otherwise run the list in one session. Tick each item's status as its check passes. When reality contradicts the spec, stop, update the spec, then resume.

## 4. Verify

Every project gate passes first (lint, types, tests). A claim of "passes" or "fixed" needs the command run in this turn and its full output read; an earlier run or a subagent's report is a lead, not evidence. Evidence ranks: an agent's claim (untrusted) < automated tests or CI (necessary, not sufficient) < a real end-to-end run < the user's own acceptance, the only thing that closes "done". Name the level behind every completion claim, and give the user a one-line check per item.

For a vision document or PRD, follow `project-docs` (`VISION.md`): thesis, purpose, value, non-goals, kept apart from status.

Source: *AI-Native Software Engineering*, chapters 5 and 6.
