The ONLY guide you'll need for GitHub Spec Kit

Tech/Product Summary (GitHub Spec Kit + Spec-Driven Development)

Speaker/source + Momentum/Feedback

• Dan Delamarski introduces SpecKit, a new GitHub open-source, free toolkit.
• He points to early traction (e.g., stars) and encourages community input via:
  • GitHub issues
  • pull requests
• He advises against certain PR patterns—such as making large rewrites into an MCP server—without first discussing the approach in an issue.

What SpecKit Is For

• SpecKit is a toolkit to bootstrap spec-driven development.
• Its purpose is to prevent “vibe coding”:
  • generated code/implementation/design drifting from the original intent
• The goal is to convert fuzzy ideas into structured, repeatable specifications that scale beyond experimentation.

---

Core Artifacts and Workflow (Demonstrated)

SpecKit Repo + Spec CLI

• SpecKit includes a CLI scaffold tool called “specify CLI” that generates the initial project structure.
• Installation/setup approaches shown:
  • Use uvx to run directly from the GitHub repo (not yet distributed on the Python package index).
  • Or download templates directly from GitHub Releases (agent-specific zips/templates) to avoid installation.
• Supports multiple “agents” (tools/editors), including:
  • Copilot and others
  • Cursor, added “just today” (as mentioned in the video)

OS/Agent-Specific Templates

• Templates are delivered as scripts, such as:
  • PowerShell for Windows
  • bash for Linux
• A highlighted capability: native PowerShell support on Windows without WSL2.

Project Bootstrapping + Folder Structure

• After scaffolding, the project includes a specify/ folder with:
  • helper scripts
  • templates
  • metadata
• It also includes GitHub folder prompts used as “slash commands” in VS Code (LLM/agent custom prompts).

“Constitution” Concept (Non-Negotiable Principles)

• A constitution file encodes fixed project principles, such as:
  • static-first delivery
  • required conventions (e.g., tests/framework/version constraints)
• The constitution can be:
  • auto-filled by an LLM from a template
  • manually edited by the user
• These constitution items are treated as non-negotiable constraints used later during generation.

Spec Creation (What/Why, Detached From Implementation)

• A /specify command generates a spec from a prompt file.
• The spec focuses on:
  • product intent
  • requirements
• It intentionally avoids locking in technical implementation details.
• Claimed benefit: because the spec is implementation-independent, the same spec can later generate variants across different stacks/tools.

LLM Output Verification + Acceptance Checklist

• After spec generation, it surfaces:
  • functional requirements and user stories
  • acceptance scenarios and edge cases
  • an important review/acceptance checklist
• The video stresses that you must manually verify the output:
  • the spec is Markdown, not unquestionable code
• If something is unclear (e.g., ordering rules), the LLM may “best guess,” framed as prototype behavior.

Plan Generation (Technical Requirements)

• A /plan command translates spec + constitution into a technical plan.
• The plan includes:
  • execution flow
  • context (language/version/environment)
  • dependencies (example mentioned: Next.js and static-site/static export concepts)
  • hosting targets (example targets include CDN/static hosting, such as GitHub Pages and Azure Static Web Apps)
  • constitutional checks and requirement gates
• Output is structured as JSON/metadata so the agent can follow it reliably.

Task Breakdown and Phased Implementation

• A /tasks command produces tasks.md, a chunked set of development phases.
• The demo style includes:
  • test-first guidance (e.g., “tests must fail before…” / TDD flow)
  • setup
  • data model implementation
  • pages (e.g., about/FAQ/episodes)
  • integration and polish
• Optional checks (example: Lighthouse) may fail for expected reasons (e.g., Chrome not installed), demonstrated as acceptable.
• Tasks are Markdown and can be edited or guided in chat.

---

Model Choice and Experimentation

• The demo discusses that model/agent choice affects outputs, for example:
  • one model may be slower but better for doc scaffolding
  • another may be preferred for code generation/iteration
• Examples mentioned:
  • GPT-5
  • Sonnet 4 / Cloud Sonnet
• Recommendation: experiment and iterate using the tool.

---

End-to-End Demo Result

• Example product built: a modern podcast website (“podsite”).
• After running tasks, it generates:
  • landing page with a featured episode
  • about page
  • FAQ page
  • episodes pages with episode links
• It suggests aligning UI output with an organization’s design system via MCP integration (example mentioned: Figma MCP), rather than assuming random designs.
• Compared to vibe coding:
  • spec + artifacts enable easier customization
  • structured iteration
  • rebuilding/re-implementing using the same constraints/context

---

Stated Positioning

• Presented clearly as an experiment, not yet production-grade.
• Intended feedback loop:
  • users try it
  • report failures/garbage outputs
  • improvements follow based on that input

---

Main Speakers or Sources

• Dan Delamarski — SpecKit maintainer at GitHub; presenter in the video
• SpecKit / GitHub Spec Kit — primary source/tool being demonstrated
• VS Code “slash commands” (custom prompts) — interface for LLM/agent instructions
• Agents/models referenced in the demo:
  • GitHub Copilot (and mentions of other agents like Cursor)
  • model examples: GPT-5, Cloud Sonnet 4
• Installation workflow mention: uvx (Astral tooling) for running directly from GitHub