DOCSEARCHbyAlgolia
Submit Docs

GitHub Spec Kit

repository·main·Indexed 13 days ago

https://github.com/github/spec-kit

An open-source toolkit for Spec-Driven Development (SDD) that enables AI coding agents to build software by defining executable specifications, technical plans, and task lists. It includes the specify-cli (v0.16.3.dev0) for bootstrapping projects and provides role-specific bundles for Business Analysts, Developers, Product Managers, and Security Researchers, as well as extensions for agent context management and idea assessment pipelines.

Tokens
136.7K
Snippets
329
Records
571
Agent score
95%

What's inside Spec Kit

  1. Understand the Spec Kit community ecosystem

    main

    The Spec Kit community provides several types of contributions that expand the capabilities of Spec-Driven Development. These are independently created and maintained by third-party authors and include:

    • Extensions: Add new capabilities like domain-specific commands, external tool integrations, or quality gates.
    • Presets: Customize Spec Kit behavior by overriding templates, commands, and terminology without modifying the core tooling.
    • Bundles: Pre-composed stacks of extensions, presets, workflows, and steps designed for specific roles or teams.
    • Walkthroughs: Practical, step-by-step guides demonstrating Spec-Driven Development in various scenarios, languages, and frameworks.
    • Friends: Companion projects such as VS Code extensions or Claude Code plugins that visualize or build upon Spec Kit.

  2. Files in the Spec Kit extension template

    main

    The extension template includes the following files which serve different purposes in the extension lifecycle:

    • extension.yml: The extension manifest. This must be customized with your extension's metadata and command definitions.
    • config-template.yml: A template for defining your extension's configuration options. This must be customized.
    • commands/example.md: An example command implementation. This should be replaced with your actual command logic.
    • README.md: The documentation for your extension. This should be replaced with your own usage instructions.
    • LICENSE: The MIT License. Review this to ensure it meets your requirements.
    • CHANGELOG.md: Used to track version history. Update this as you release.
    • .gitignore: Pre-configured Git ignore rules.

  3. Explore Spec Kit Community Extensions

    main

    Spec Kit supports a wide ecosystem of community-developed extensions that augment the Spec-Driven Development (SDD) lifecycle. These extensions are categorized by their primary function:

    • Process: Tools that manage the SDD lifecycle (e.g., spec-kit-refine for updating specs, spec-kit-schedule for task scheduling, spec-kit-tdd for test-driven development).
    • Docs: Tools focused on documentation, review, and visibility (e.g., spec-kit-critique for spec review, spec-kit-preview for generating Markdown/HTML previews).
    • Code: Tools that interact directly with the codebase (e.g., spec-kit-trace for requirement traceability, spec-kit-spectest for test scaffolding).
    • Visibility: Tools for monitoring progress and state (e.g., spec-kit-diagram- for Mermaid diagrams, spec-kit-tldr for review-oriented dashboards).
    • Integration: Tools that connect Spec Kit to external platforms (e.g., spec-kit-figma for design context, spec-kit-tasks-to-project for GitHub Projects).
    • Integration/Read+Write: Extensions that can both read and modify project artifacts.
    • Read-only: Extensions that provide analysis or visibility without modifying files.

  4. Understand the Spec-Driven Development lifecycle with Specify CLI

    main

    The Specify CLI (specify) is a management tool for the full lifecycle of Spec-Driven Development (SDD). It handles everything from project initialization to workflow automation.

    Spec Kit is composed of several layers:

    • Core Commands: Foundational commands for project management and initialization.
    • Integrations: Connects Spec Kit to specific AI coding agents (only one active per project).
    • Extensions: Adds new capabilities like domain-specific commands or quality gates.
    • Presets: Customizes command files, templates, and scripts to enforce organizational standards without changing the underlying tooling.
    • Workflows: Automates multi-step processes by chaining commands, prompts, and shell steps with support for conditional logic and human checkpoints.
    • Bundles: Curated, versioned units that compose extensions, presets, and workflows into a single installable stack.

  5. Use the Business Analyst role bundle

    main

    The Business Analyst bundle is a role-specific bundle designed for Spec-Driven Development workflows involving requirements elicitation, traceability, and acceptance criteria.

    It provides the following components:

    • Extension: agent-context (synchronizes the agent context file).
    • Preset: requirements-elicitation (priority 10, append) for elicitation and analysis commands.
    • Steps: capture-requirements and trace-acceptance-criteria.
    • Workflow: requirements-to-spec (converts captured requirements into a specification).

    This bundle is integration-agnostic, meaning it automatically inherits the active integration configured in your project.

  6. What is Spec-Driven Development?

    main

    Spec-Driven Development (SDD) is a structured development process where specifications are treated as executable assets rather than discarded scaffolding. Instead of code being the primary driver, specifications define the "what" (intent) before the "how" (implementation), and are used to directly generate working implementations.

    Core Philosophy

    • Intent-driven development: Specifications define requirements before implementation details.
    • Rich specification creation: Uses guardrails and organizational principles to build robust specs.
    • Multi-step refinement: Moves away from one-shot code generation in favor of iterative refinement.
    • AI-reliance: Leverages advanced AI model capabilities to interpret and act upon specifications.

  7. Overview of the Spec Kit Extension System

    main
    The Spec Kit Extension System allows for modular integration with external tools (such as Jira, Linear, or Azure DevOps) without bloating the core framework. Extensions are self-contained packages installed into the .specify/extensions/ directory of a project. They use declarative manifests for configuration, are versioned independently from the core, and are discoverable via a central catalog. This modularity ensures that core spec-kit remains lean while allowing users to opt-in to specific integrations.

  8. What is Spec-Driven Development (SDD)?

    main

    Spec-Driven Development (SDD) is a core process in Spec Kit where you describe what to build and refine it through structured phases before writing code. This approach provides AI coding agents with structured context via Markdown artifacts rather than ad-hoc prompts.

    The standard SDD workflow follows these phases:

    1. Spec: Define the requirements.
    2. Plan: Create a technical strategy.
    3. Tasks: Break the plan into actionable items.
    4. Implement: Execute the code changes.

    Each phase produces a Markdown artifact that feeds into the next phase, ensuring the agent maintains intent throughout the Software Development Life Cycle (SDLC).

  9. The three-layer pattern for AI agent instructions

    main

    A common pattern for organizing instructions for AI agents involves splitting them into three distinct layers to improve clarity and maintainability:

    1. AGENTS.md: High-level instructions and persona definitions for the agent.
    2. SKILL.md: Specific capabilities, tools, or procedures the agent can execute.
    3. DESIGN.md: The technical design and architectural specifications the agent must follow.

    This separation helps manage context and prevents instruction bloat.

  10. Understand Spec Persistence Models

    main

    Spec Kit provides a repeatable workflow for managing spec.md, plan.md, and tasks.md, but it does not enforce a specific maintenance strategy. Teams must choose a model for how these artifacts are updated when requirements change.

    To choose a model, evaluate two dimensions:

    1. Temporal Lifecycle: How long should the specification matter? (Spec-first, Spec-anchored, or Spec-as-source).
    2. Mutation Strategy: What happens to the artifact set when requirements change?

    Common models include Flow-Back, Flow-Forward, and Living Spec.

  11. How tasks are appended to tasks.md during convergence

    main

    When the converge command identifies actionable findings, it follows an append contract to update tasks.md. It does not modify existing tasks; it only adds new work to the end of the file.

    Append Logic

    1. Identify Phase: It finds the highest existing phase number M and determines the next phase N = M + 1.
    2. Create Section: A new header ## Phase N: Convergence is created.
    3. Generate Task IDs: New tasks are assigned zero-padded IDs starting from the next available number (e.g., if the last task was T041, the new tasks start at T042).
    4. Task Format: Each task is written as a checklist item:
      - [ ] T042 <imperative description> per <source-ref> (<gap-type>)
      • <source-ref>: Traces the task to its origin (e.g., FR-003, plan: storage decision).
      • <gap-type>: Must be one of missing, partial, contradicts, or unrequested.
      • Priority: Constitution-violation tasks are emitted first and labeled as CRITICAL.

    Note: If no findings are found, tasks.md is not modified, and no empty phase header is added.

    - [ ] T042 Add append-only enforcement per FR-008 (missing)

  12. How the Spec-Driven Development (SDD) workflow works

    main

    Spec-Driven Development (SDD) uses executable specifications to drive software construction. Instead of writing code first, you follow a structured workflow using slash commands in your AI coding assistant:

    1. Establish Principles: Use /speckit.constitution to define governance and development guidelines.
    2. Define Requirements: Use /speckit.specify to describe what to build and why, focusing on functionality rather than technical implementation.
    3. Technical Planning: Use /speckit.plan to define your tech stack and architecture.
    4. Task Generation: Use /speckit.tasks to break the plan into an executable task list.
    5. Implementation: Use /speckit.implement to execute the tasks and build the features.

    This process ensures that the AI assistant builds exactly what was specified in the high-level requirements and technical plans.

    1. /speckit.constitution (Principles)
2. /speckit.specify (Requirements)
3. /speckit.plan (Architecture)
4. /speckit.tasks (Task List)
5. /speckit.implement (Execution)