GitHub Spec Kit is easy to summarize badly.
The shallow description is: it turns an idea into spec.md, plan.md, tasks.md, and code.
The more interesting description is: Spec Kit turns one unreliable, open-ended agent request into a sequence of constrained transformations with explicit inputs, outputs, prompt-declared mutation contracts, checks, and recovery paths.
That second description is why the project matters to anyone building custom Agent Skills.
This article is a source-level review of the six stages readers ask about most:
specify -> clarify -> plan -> tasks -> analyze -> implement
I reviewed the prompt templates, artifact templates, Cursor integration, official documentation, and release history at Spec Kit v0.13.0, released on July 17, 2026. Where this article explains what the files do, the claims are source-backed. The company workflow later in the article is an illustrative design based on my engineering judgment.
One terminology correction matters before we begin: older explanations often call these only “slash commands.” When initialized with --integration cursor-agent, Spec Kit v0.13.0 installs them as .cursor/skills/speckit-<name>/SKILL.md Agent Skills by default. For the uncustomized core processes, shared templates/commands/*.md files are the generation source; presets and extensions can replace the effective installed content. They are therefore both a command surface and, in Cursor, real Agent Skills.
TL;DR
- Spec Kit is interesting because each skill behaves like a typed compiler pass, not a reusable bag of prompting tips.
- Every pass narrows the model’s freedom:
specifyseparates what and why from implementationclarifyconverts high-impact ambiguity into recorded decisionsplanconverts requirements into researched technical designtasksconverts design into dependency-ordered, independently testable workanalyzechecks cross-artifact consistency without editing the three artifacts it reviewsimplementexecutes approved work while updating durable progress
- The Markdown prompt is only one layer. Deterministic scripts resolve paths and state; templates constrain output shape; artifacts carry context between sessions; checks and hooks instruct or gate transitions, subject to agent and host enforcement.
- The design is strong, but not infallible. Some “validation” is still model judgment, task-to-requirement mapping is semantic rather than formally proven, tests are optional by default, and the implementation skill has a large mutation surface.
- An opinionated company spec workflow can apply the same control architecture through:
- machine-readable preflight
- explicit read/write contracts
- company-owned templates and artifact handoffs
- bounded clarification and revision loops
- policy and coverage gates
- verifiable
Done Whenconditions
- We should not copy the giant prompts verbatim. We should copy the control architecture.
What You Will Learn Here
- Why Spec Kit is more than a chain of Markdown prompts
- How the six requested skills work internally
- Which design decision in each skill reduces agent failure
- Where the skills remain heuristic, risky, or overly broad
- How the stages compose into an artifact pipeline
- How to turn the strongest patterns into a company-specific spec workflow
- A concrete planning skill, artifact layout, rollout sequence, and evaluation checklist
Audience: engineers and architects designing repeatable AI-assisted workflows.
The Core Idea: Treat Skills as Compiler Passes
A compiler does not ask one component to understand source text, optimize it, emit machine code, link dependencies, and verify the binary in one unstructured step. It uses intermediate representations and passes with narrower jobs.
Spec Kit applies that idea to agent work:
The “types” in this analogy are procedural contracts expressed in templates and instructions. They are not formally verified types or security boundaries.
natural-language intent
|
v
[specify] -> spec.md: behavior contract
|
v
[clarify] -> spec.md: ambiguity reduced
|
v
[plan] -> plan.md + research + model + contracts
|
v
[tasks] -> tasks.md: executable work graph
|
v
[analyze] -> artifact-level read-only report
|
v
[implement] -> code + planned tests + checked task state
Each artifact is an intermediate representation:
spec.mdrepresents intended behavior without committing to a stack.plan.mdrepresents implementation decisions without becoming the task queue.tasks.mdrepresents execution order without replacing requirements.- code represents one implementation of those approved artifacts.
This separation does three useful things.
First, it reduces the number of questions the model must answer at once. Second, it makes errors attributable to a stage. Third, it creates review surfaces a human or another agent can inspect before errors become expensive code.
The article’s central judgment is:
Spec Kit’s biggest innovation is not “write a spec first.” It is giving every transformation a contract and making the contracts persist outside model context.
The Four-Layer Architecture Behind the Skills
The installed SKILL.md files get the attention, but they are only one layer.
| Layer | Responsibility | Example |
|---|---|---|
| Deterministic state | Resolve the active project, feature, paths, and prerequisites | .specify/feature.json, check-prerequisites, setup scripts |
| Agent procedure | Tell the model what to read, decide, write, and report | speckit-specify/SKILL.md, speckit-analyze/SKILL.md |
| Artifact schema | Constrain the shape of generated context | spec-template.md, plan-template.md, tasks-template.md |
| Quality and extension | Instruct, inspect, or extend transitions | checklists, constitution gates, before/after hooks |
That split is important. A prompt is poor at reliably locating the right feature directory across operating systems. A script can do that. A script is poor at turning a vague product idea into coherent user scenarios. A model can do that. Spec Kit gives each side the work it is better suited to perform.
The project resolves from SPECIFY_INIT_DIR or the local Spec Kit project context; the active feature resolves from SPECIFY_FEATURE_DIRECTORY or .specify/feature.json, not from the checked-out Git branch. This corrects a common assumption in older Spec Kit tutorials.
The v0.13.0 Cursor integration makes this architecture portable by generating Agent Skills from the common templates. The generated skill frontmatter includes name, description, compatibility, author metadata, and source-template metadata, while command references and script paths are rewritten for Cursor’s invocation style.
This is a better portability model than maintaining six manually forked prompts for every agent.
Skill 1: speckit-specify
Its real job
specify is not merely a spec writer. It is a boundary enforcer between product intent and technical design.
It takes a natural-language feature description and must produce:
- prioritized, independently testable user stories
- acceptance scenarios
- edge cases
- numbered functional requirements
- key entities when data is involved
- measurable, technology-agnostic success criteria
- explicit assumptions
It also creates and persists the active feature directory, copies the resolved spec template, and creates a requirements-quality checklist.
The most interesting prompt patterns
1. A negative scope is as important as a positive goal
The skill says what belongs in the phase—actors, actions, data, constraints—but also what does not: implementation details, frameworks, APIs, and code structure.
This protects the stable “what” from premature commitment to the flexible “how.”
2. Clarification has a budget
The skill permits at most three [NEEDS CLARIFICATION] markers during initial specification. It prioritizes them by:
scope > security/privacy > user experience > technical detail
Everything else should use reasonable, documented assumptions.
That is a subtle but valuable design. An unconstrained agent either guesses too much or asks a questionnaire so long that the workflow stalls. A clarification budget forces prioritization.
3. Drafting includes a bounded self-review loop
After writing the spec, the skill generates checklists/requirements.md and evaluates the spec against it. For checklist failures other than unresolved clarification markers, it revises and retries up to three times; clarification markers use a separate bounded question flow.
The loop has:
- a named oracle: the checklist
- a retry cap: three
- an escalation outcome: document remaining issues and warn
That is much stronger than “review your work carefully.”
Where it is still weak
The skill instructs the model to make “reasonable defaults,” including domain defaults. That keeps momentum, but it can also launder an assumption into an apparently authoritative requirement. Data retention, authentication, legal compliance, and performance expectations are not always safe places to assume an industry norm.
The checklist is also evaluated by the same model that wrote the spec. It is a useful revision mechanism, not independent proof.
Lesson for custom skills: define assumption classes. Low-impact defaults can be inferred and recorded; security, legal, irreversible, and audience-changing decisions should trigger clarification.
Skill 2: speckit-clarify
Its real job
clarify is a decision-extraction protocol.
It scans the current spec across a detailed taxonomy:
- functional scope
- domain and data model
- interaction and UX
- non-functional qualities
- integrations
- failure handling
- constraints and tradeoffs
- terminology
- completion signals
- unresolved placeholders
It then ranks candidate questions using an Impact * Uncertainty heuristic.
The most interesting prompt patterns
1. Exactly one question at a time
Unlike specify, which can surface up to three critical questions together, clarify asks one question, validates the answer, writes it into the spec, and only then moves to the next queued question.
Sequential clarification lets each answer change which next question is worth asking.
2. Recommendations reduce interaction cost
For multiple-choice questions, the skill must recommend one option and explain why. The user can accept it with “yes” or “recommended.”
This avoids making the user perform all analysis from scratch while preserving the decision point.
3. Every answer is written through to its owning section
The skill does not only append a Q&A log. It updates the functional requirement, user story, entity, success criterion, edge case, or terminology that the answer changed. It removes contradictory old text and saves after each answer.
That creates two records:
decision history -> Clarifications session
current truth -> owning spec section
4. Downstream quality state is re-evaluated
If the requirements checklist exists, only checkbox states that actually changed are toggled. The completion report shows newly passing items, regressions, remaining gaps, and before/after counts.
This is change-aware validation, not just another full rewrite.
Where it is still weak
The taxonomy is broad enough that a model may classify plan-level concerns as product ambiguity or vice versa. The skill tells it to defer plan-level execution details, but that boundary remains judgment-based.
It also caps each session at five questions. That is good for interaction design, but “five questions asked” is not the same as “feature is sufficiently specified.” The completion report correctly preserves deferred and outstanding categories; teams must actually read them.
Lesson for custom skills: a clarification skill should mutate the source artifact immediately, keep a compact decision log, and report what remains unresolved. Chat answers alone are not durable state.
For the wider artifact-ownership pattern around review comments, see How to Handle Feedback in GitHub Spec Kit.
Skill 3: speckit-plan
Its real job
plan is a requirements-to-design compiler with governance gates.
It reads the feature spec, constitution, and plan template. It then creates:
plan.mdresearch.mddata-model.mdcontracts/when the project has external interfacesquickstart.mdas an end-to-end validation guide
The most interesting prompt patterns
1. Unknowns become research tasks
The Technical Context section explicitly permits NEEDS CLARIFICATION. Phase 0 converts each unknown, dependency, and integration question into research work. The final research.md records:
- decision
- rationale
- alternatives considered
Planning does not hide uncertainty; it changes uncertainty into an artifact-producing subtask.
2. Governance runs before and after design
The plan template includes a Constitution Check before research and requires it to be evaluated again after Phase 1 design.
This catches a common failure:
high-level plan passes principles
|
v
detailed design introduces a violation
Any justified exception belongs in an explicit Complexity Tracking table with the rejected simpler alternative.
3. Supporting artifacts have distinct purposes
The skill avoids putting everything into one giant design document:
research.mdholds decisions and alternatives.data-model.mdholds entities, relationships, validation, and state.contracts/holds externally observable interfaces.quickstart.mdholds runnable validation scenarios, not implementation code.
That is progressive disclosure at the artifact level.
Where it is still weak
The default plan can generate more artifacts than a small change needs. The prompt does say to skip contracts for purely internal work, but teams still need proportionality.
The plan’s research is only as reliable as its sources and repository access. “Research complete” can mean the model produced plausible rationale, not that a human validated primary evidence.
Lesson for custom skills: turn unknowns into named research tasks, but require source provenance for externally verifiable decisions. Separate “decision made” from “claim verified.”
Skill 4: speckit-tasks
Its real job
tasks is an execution-plan compiler.
It consumes required artifacts (spec.md, plan.md) and optional artifacts (data-model.md, contracts/, research.md, quickstart.md). It emits a strict task format:
- [ ] T012 [P] [US1] Create User model in src/models/user.py
Every symbol carries meaning:
- checkbox: durable progress state
T012: stable execution identity[P]: safe parallel opportunity[US1]: traceability to user value- file path: concrete mutation scope
The most interesting prompt patterns
1. User stories, not technical layers, organize delivery
The task list is ordered as:
Setup
-> Foundational blockers
-> User Story 1 (P1 / MVP)
-> User Story 2
-> User Story 3
-> Cross-cutting polish
Within a story, models, services, endpoints, and tests stay together. This encourages vertical slices that can be demonstrated and validated independently.
2. Parallelism is a claim with conditions
[P] is allowed only when tasks use different files and do not depend on unfinished work. The generated document must include dependency order and examples of parallel execution.
This is more useful than telling an orchestrator to “parallelize where possible.” It creates an inspectable scheduling hypothesis.
Execution isolation still belongs outside the marker; From Spec to Parallel Delivery covers branches, worktrees, and ownership.
3. MVP scope is encoded
User Story 1 is expected to deliver an independently testable minimum product. The completion report recommends an MVP scope, typically just that story.
That gives the implementation phase an intentional stopping point.
Where it is still weak
Tests are optional unless the spec or user explicitly requests them. For many production repositories, that default is too permissive. A constitution or preset can require tests, but the core task skill does not.
File paths are generated before implementation. In brownfield systems, exact paths may prove wrong after deeper exploration. The right response is to update the plan or tasks, not force code into the guessed location.
[P] also captures file independence, not all semantic dependencies. Two tasks can edit different files and still conflict through a shared interface or migration order.
Lesson for custom skills: make every work item carry identity, source traceability, mutation scope, dependency state, and an independent acceptance condition. Treat parallel markers as reviewable claims, not scheduler truth.
Skill 5: speckit-analyze
Its real job
analyze is an artifact-level read-only linker and static analyzer for planning artifacts.
It builds internal models of:
- requirements and success criteria
- user actions and acceptance criteria
- task coverage
- constitution rules
It then checks duplication, ambiguity, underspecification, constitution alignment, coverage, terminology, entities, and ordering.
The most interesting prompt patterns
1. Mutation is explicitly forbidden
The analysis procedure says “STRICTLY READ-ONLY,” produces a report, and requires explicit user approval before remediation. More precisely, it does not edit spec.md, plan.md, or tasks.md; its resolver may conditionally persist feature state, and configured hooks sit outside that guarantee.
This is a meaningful trust boundary. A checker that silently edits the artifact it judges can hide evidence and make the review impossible to reproduce.
2. Constitution authority is explicit
The constitution is non-negotiable within analysis. A conflict cannot be “resolved” by weakening or reinterpreting the constitution inside the same skill.
Other defects return to the stage that owns the affected artifact: requirement defects to specify or clarify, design defects to plan, and decomposition defects to tasks.
3. Analysis produces coverage, not only prose
The report includes:
- stable finding IDs
- severity
- locations
- recommendations
- requirement-to-task coverage
- unmapped tasks
- aggregate metrics
This gives the user a decision surface, not a generic “looks good.”
4. Analysis has an output budget
The skill caps findings at 50 and aggregates overflow. It asks for high-signal examples rather than dumping every stylistic concern.
Where it is still weak
The “semantic model” and coverage mapping are inferred by a language model using IDs, keywords, and key phrases. This is not formal traceability. A task can mention the right noun and still fail to satisfy the requirement.
The skill asks for deterministic IDs and counts across reruns, but model outputs are not inherently deterministic. Stable explicit requirement IDs help; they do not guarantee identical semantic mapping.
Lesson for custom skills: make audit skills artifact-level read-only by default, define governing constraints, and produce a coverage matrix. Then be honest about which checks are heuristic and which setup operations or hooks may still write state.
Skill 6: speckit-implement
Its real job
implement is a stateful executor.
It does more than write code:
- resolves the active feature
- checks every quality checklist if a checklist directory exists
- asks before continuing if any checklist is incomplete
- loads the task, plan, optional design artifacts, constitution, and validation guide
- verifies project ignore files
- parses task phases and dependencies
- executes work phase by phase
- marks completed tasks
[X] - halts on sequential-task failure
- validates the implementation against the artifacts
The most interesting prompt patterns
1. Readiness is visible before mutation
An incomplete checklist does not automatically block forever, but it forces an explicit proceed/stop decision. That is a good model for soft gates:
evidence incomplete
-> show exact status
-> require conscious override
-> continue only with recorded user intent
2. Progress is externalized
Every completed task is marked in tasks.md. A later run can resume from durable state rather than relying on conversation memory.
The official complex-feature guide recommends scoping implementation by task range or phase. This is a direct response to context-window degradation:
/speckit.implement only execute tasks T001-T010, then stop
3. Failure behavior differs by dependency type
- Sequential failure: halt.
- Parallel failure: preserve successful work and report failures.
- Unclear or blocked work: explain and suggest next steps.
The skill encodes operational semantics rather than merely saying “handle errors.”
Where it is still weak
This is the largest and riskiest stage.
The skill can alter application code, tests, task state, dependencies, and ignore configuration. Its generic ignore-file logic may be helpful for a new project but surprising in a narrow brownfield feature. A custom skill should rarely inherit such a broad mutation contract without explicitly declaring it.
The task checkbox is also only a progress claim. Marking [X] does not prove acceptance. Deterministic repository tests, CI, and human review remain authoritative.
Finally, one implementation run can still exceed context limits. Spec Kit’s own documentation recommends phase scoping, delegation, or splitting large features into smaller specs.
Lesson for custom skills: separate progress state from acceptance state, constrain each run’s mutation scope, and define a hard external verifier.
The Six Skills as One Control System
The individual prompts are useful, but their composition is the real design:
| Skill | Reads | Writes | Primary invariant | Failure response |
|---|---|---|---|---|
| Specify | user intent, template, constitution | spec, requirements checklist, feature state | what/why before how | ask only critical questions; bounded revision |
| Clarify | spec, constitution, checklist | clarified spec, decision log, checklist state | material ambiguity is explicit | defer low-impact or plan-owned unknowns |
| Plan | spec, constitution, plan template | plan, research, model, contracts, validation guide | technical design honors intent and governance | stop on unjustified gate failures |
| Tasks | spec, plan, optional design docs | dependency-ordered task list | each story can produce a testable increment | report missing or weak decomposition |
| Analyze | spec, plan, tasks, constitution | report; resolver may update feature state; hooks may mutate files | no unreported cross-artifact drift before execution | return defects to their owning stage |
| Implement | all approved artifacts, task state | code, planned tests, config, task progress | execute in dependency order and validate | halt, preserve progress, or ask to override |
Several reusable principles emerge.
1. Every skill has one dominant verb
Specify. Clarify. Plan. Decompose. Analyze. Implement.
A skill can perform supporting work, but its prompt-declared mutation contract and output remain organized around one verb.
2. Artifacts are APIs between skills
The next skill does not need the entire conversation. It needs a validated artifact with a known schema.
3. Artifact-level read-only review is a first-class phase
Analysis is not buried at the end of implementation. It is separate and does not rewrite the three artifacts it judges. Resolver state and configured hooks still need their own review.
4. The workflow records decisions, not just outputs
Assumptions, clarifications, alternatives, task IDs, checklist states, and completed work survive the model session.
5. Most loops have visible stopping conditions
Clarification, validation, finding, and workflow loops are bounded. Implementation runs all tasks by default; task-range or phase scoping is a documented recommendation that the user must request.
6. The prompt does not pretend to be enforcement
The workflow documentation explicitly warns that shell workflow steps run with local privileges and that the workflow engine is not a capability sandbox. Instructions influence behavior; operating-system permissions, tool policies, CI, and review constrain impact.
What a Company-Specific Spec Workflow Can Learn
Suppose a company wants an internal spec tool for customer-facing service changes. The company already has an opinionated engineering process:
- every spec must state goals, non-goals, owners, and measurable acceptance criteria
- public API changes require a compatibility plan
- persistent-data changes require migration, backfill, and rollback plans
- authentication or authorization changes require a threat model
- every rollout needs observability, feature-flag, and rollback sections
- implementation cannot begin until product and engineering approvals are recorded
The wrong implementation would be one enormous “follow our process” prompt. It would mix product discovery, architecture, governance, task planning, and code changes in a single context.
The stronger design is a company-specific pipeline:
feature request
|
v
[company-specify] -> spec.md from the product requirements template
|
v
[company-clarify] -> decisions.md + resolved requirements
|
v
[company-plan] -> plan.md + API/data/security/rollout sections
|
v
[company-tasks] -> tasks.md with owners, dependencies, and checks
|
v
[company-analyze] -> read-only policy and coverage report
|
v
[company-implement] -> scoped code changes + durable task state
This is not Spec Kit with the names changed. The company owns the artifact schemas and the transition rules.
| Stage | Company-specific rule | Result |
|---|---|---|
| Specify | Use the approved product template; reject missing owner or success metric | Requirements have a consistent review shape |
| Clarify | Ask only about decisions that can change scope, risk, or architecture | Low-impact details do not stall the workflow |
| Plan | Select required sections from the change profile | API, data, security, and rollout work cannot disappear |
| Tasks | Every task links to a requirement and a verifier | Work remains traceable to user and operational outcomes |
| Analyze | Evaluate artifacts without rewriting them | Review findings remain visible and reproducible |
| Implement | Execute one approved phase or task range | Mutation scope stays bounded |
The opinionated part should live in versioned inputs, not only in prose inside a skill:
.company-spec/
|-- constitution.md
|-- profiles/
| |-- service-change.yaml
| |-- data-migration.yaml
| `-- security-sensitive.yaml
|-- templates/
| |-- spec.md
| |-- plan.md
| `-- tasks.md
|-- policies/
| |-- api-compatibility.md
| |-- data-migrations.md
| `-- production-rollouts.md
|-- scripts/
| `-- company-spec-context
`-- skills/
|-- company-specify/
|-- company-clarify/
|-- company-plan/
|-- company-tasks/
|-- company-analyze/
`-- company-implement/
Templates define required output. Profiles decide which template sections and gates apply to a change class. Policies provide detailed rules. The context resolver returns facts such as the active change, service owner, repository type, selected profile, and artifact paths. Skills remain narrow procedures that connect those inputs.
A Concrete Custom Skill Pattern
Consider the planning stage. Its job is not to invent the company process. Its job is to apply the selected profile and produce a reviewable technical plan.
---
name: company-plan
description: Create the approved technical plan for a company service change. Use after company-specify and company-clarify have produced an approved spec.
metadata:
owner: platform-engineering
version: "1.0"
---
# Company Plan
## Mutation Contract
- May create or update plan.md in the active change directory.
- May add research notes under research/.
- Do not edit spec.md, tasks.md, or application code.
## Preflight
1. Run `.company-spec/scripts/company-spec-context plan --json` once.
2. Read the returned spec, constitution, profile, plan template, service metadata, and policy paths.
3. Stop if spec status is not `approved`.
4. Stop if a high-impact clarification remains unresolved.
## Artifact Contract
Populate the resolved plan template without deleting required headings.
Always include:
- architecture and affected boundaries
- requirement-to-design mapping
- test strategy
- observability and rollout
- rollback conditions
When selected by the profile:
- public API compatibility and deprecation
- schema migration and backfill
- threat model and permission changes
- privacy or regulatory review
## Decision Rules
- Prefer existing approved platform components.
- Record each material alternative and rejection reason.
- Do not invent service metadata; report missing catalog data.
- A policy exception must name its owner and approval record.
## Validation
1. Run `company-spec validate plan --change "$CHANGE_ID"`.
2. Revise schema or coverage failures; maximum two passes.
3. Stop on policy failures that require human approval.
## Done When
- Every requirement maps to a design decision.
- Every applicable profile gate passes or has an approved exception.
- Rollout, observability, and rollback are testable.
- Validation exits successfully.
The resolver could return:
{
"changeId": "billing-webhook-retries",
"profile": "service-change",
"specStatus": "approved",
"specPath": "changes/billing-webhook-retries/spec.md",
"planPath": "changes/billing-webhook-retries/plan.md",
"planTemplate": ".company-spec/templates/plan.md",
"service": {
"name": "billing-api",
"owner": "payments-platform",
"tier": 1
},
"requiredPolicies": [
".company-spec/policies/api-compatibility.md",
".company-spec/policies/production-rollouts.md"
]
}
The script resolves deterministic context; the skill makes technical decisions. If the service owner is missing, the resolver reports that fact. The model should not guess it.
The skill also does not embed every API, migration, and rollout rule. Those details stay in versioned policy files and are loaded only when the selected profile requires them. That follows the Agent Skills specification principle of progressive disclosure while keeping the actual company rules reviewable outside the prompt.
A Practical Build Plan for the Company Workflow
Build the workflow from policy outward:
- Choose one change class. Start with customer-facing service changes rather than trying to model every engineering workflow.
- Write the artifact contracts. Define the required fields and examples for
spec.md,plan.md, andtasks.md. - Create profiles. Encode when API, data, security, privacy, and rollout sections become mandatory.
- Build deterministic context resolution. Resolve the active change, repository, service owner, risk tier, profile, and artifact paths as JSON.
- Implement narrow skills. Give specify, clarify, plan, tasks, analyze, and implement separate read/write contracts and stopping conditions.
- Add machine checks. Validate template shape, required approvals, requirement coverage, task identifiers, and policy exceptions without relying entirely on model judgment.
- Pilot with real changes. Compare the generated artifacts with the company’s current review process before allowing implementation-stage mutation.
- Version and govern the workflow. Assign owners to templates, policies, profiles, scripts, and skills; record breaking process changes.
Test behavior, not prompt wording:
| Test | Expected behavior |
|---|---|
| Add an optional field to a public API | Requires compatibility, contract-test, rollout, and observability sections |
| Remove a public API field | Stops unless a versioning or deprecation path is approved |
| Add a database column with a backfill | Requires migration order, capacity impact, rollback, and verification |
| Change an authorization decision | Selects the security-sensitive profile and requires a threat model |
| Plan contains a requirement with no task | Analyze reports a coverage failure without editing artifacts |
| Implement is asked to run before approval | Stops before changing application code |
| Fix a typo in internal documentation | Bypasses the full spec workflow under an explicit low-risk rule |
Useful operating metrics include first-pass validation rate, clarification count, policy exceptions, review rework, escaped requirement defects, rollback-plan failures, and lead time from approved spec to accepted implementation. The goal is not to maximize generated documents. It is to make the company’s important decisions explicit before code is expensive to change.
What Not to Copy
Spec Kit is a rich source of patterns, but copying it mechanically would make the company workflow worse.
| Do not copy | Better rule |
|---|---|
| Prompt length as a proxy for control | Keep core skills short; move company rules to versioned policies and profiles |
| The authoring model as the only judge | Use independent review and external checks for high-impact work |
| Every artifact for every task | Keep transient control state transient unless it has lasting review value |
| Optional tests as a universal default | Follow repository policy and task risk |
| Broad authority hidden behind “implement” | Declare mutation scope; enforce tool and credential limits outside the prompt |
When the Full Pipeline Is Worth It
| Situation | Recommended shape |
|---|---|
| Typo, copy edit, or deterministic one-file fix | Direct edit + repository checks |
| Small feature with clear behavior and low risk | Specify → plan → tasks → implement |
| Ambiguous, cross-system, security-sensitive, or regulated feature | Full clarify/checklist/analyze gates |
| Large implementation likely to exhaust context | Scope by phase/task range or split into smaller specs |
| Team will not maintain generated artifacts | Use a lighter RFC/checklist workflow instead |
The architecture pays off when the cost of a misunderstood requirement exceeds the cost of maintaining the intermediate artifacts. For planning fundamentals beyond this teardown, see Correct Planning for Engineering Development; for the wider repository design, see Let’s Build Prompt-First Repositories.
The Deeper Design Lesson
The most useful way to think about Agent Skills is not:
prompt snippets the model can remember
It is:
small operating procedures
with typed inputs,
bounded authority,
durable state,
artifact schemas,
validation,
and explicit handoffs
Spec Kit is interesting because it makes those properties visible.
specify controls intent. clarify controls uncertainty. plan controls technical commitment. tasks controls decomposition. analyze controls drift. implement controls execution.
The chain is not guaranteed to produce correct software. It is designed to make incorrectness show up at a cheaper, more attributable boundary.
That is the lesson worth carrying into any custom workflow.
Sources
Primary and official sources, accessed July 17, 2026:
- GitHub Spec Kit v0.13.0 release — pinned version and release date
- Spec Kit README at v0.13.0 — project positioning, command/skill inventory, integrations, extensions, presets, and bundles
- Agentic SDD reference at v0.13.0 — official phase order and behavior
- Quick Start Guide at v0.13.0 — short and production paths, feature-state behavior
specifytemplate at v0.13.0 — specification workflow, clarification budget, and quality loopclarifytemplate at v0.13.0 — ambiguity taxonomy, sequential questions, and incremental writesplantemplate at v0.13.0 — research and design phases, constitution checkstaskstemplate at v0.13.0 — strict task format, user-story organization, and parallel markersanalyzetemplate at v0.13.0 — artifact-level read-only analysis, semantic coverage, severity, and output limitsimplementtemplate at v0.13.0 — checklist gate, execution rules, progress tracking, and completion checks- Cursor integration at v0.13.0 —
.cursor/skillslayout and default skills mode - Skills integration generator at v0.13.0 — transformation of common templates into Agent Skills
- Handling Complex Features — implementation scoping and context-window guidance
- Workflows reference at v0.13.0 — resumable state, gates, loops, fan-out, and shell security boundary
- GitHub Blog: Spec-driven development with AI — historical launch rationale, published September 2, 2025
- Agent Skills specification — portable skill structure and progressive-disclosure guidance
Related reading on this devlog: