π« Toolkit to help you get started with SDD or any other process!
Docs setup
Den Delimarsky πΊ4b98c20f5d97
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.ymlnew file mode 100644index 000000000..92e81a5e6--- /dev/null+++ b/.github/workflows/docs.yml@@ -0,0 +1,67 @@+# Build and deploy DocFX documentation to GitHub Pages+name: Deploy Documentation to Pages++on:+ # Runs on pushes targeting the default branch+ push:+ branches: ["main"]+ paths:+ - 'docs/**'++ # Allows you to run this workflow manually from the Actions tab+ workflow_dispatch:++# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages+permissions:+ contents: read+ pages: write+ id-token: write++# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.+concurrency:+ group: "pages"+ cancel-in-progress: false++jobs:+ # Build job+ build:+ runs-on: ubuntu-latest+ steps:+ - name: Checkout+ uses: actions/checkout@v4+ with:+ fetch-depth: 0 # Fetch all history for git info++ - name: Setup .NET+ uses: actions/setup-dotnet@v4+ with:+ dotnet-version: '8.x'++ - name: Setup DocFX+ run: dotnet tool install -g docfx++ - name: Build with DocFX+ run: |+ cd docs+ docfx docfx.json++ - name: Setup Pages+ uses: actions/configure-pages@v5++ - name: Upload artifact+ uses: actions/upload-pages-artifact@v3+ with:+ path: 'docs/_site'++ # Deploy job+ deploy:+ environment:+ name: github-pages+ url: ${{ steps.deployment.outputs.page_url }}+ runs-on: ubuntu-latest+ needs: build+ steps:+ - name: Deploy to GitHub Pages+ id: deployment+ uses: actions/deploy-pages@v4diff --git a/docs/.gitignore b/docs/.gitignorenew file mode 100644index 000000000..614670d9f--- /dev/null+++ b/docs/.gitignore@@ -0,0 +1,8 @@+# DocFX build output+_site/+obj/+.docfx/++# Temporary files+*.tmp+*.logdiff --git a/docs/README.md b/docs/README.mdnew file mode 100644index 000000000..5501adf0c--- /dev/null+++ b/docs/README.md@@ -0,0 +1,33 @@+# Documentation++This folder contains the documentation source files for Spec Kit, built using [DocFX](https://dotnet.github.io/docfx/).++## Building Locally++To build the documentation locally:++1. Install DocFX:+ ```bash+ dotnet tool install -g docfx+ ```++2. Build the documentation:+ ```bash+ cd docs+ docfx docfx.json --serve+ ```++3. Open your browser to `http://localhost:8080` to view the documentation.++## Structure++- `docfx.json` - DocFX configuration file+- `index.md` - Main documentation homepage+- `toc.yml` - Table of contents configuration+- `installation.md` - Installation guide+- `quickstart.md` - Quick start guide+- `_site/` - Generated documentation output (ignored by git)++## Deployment++Documentation is automatically built and deployed to GitHub Pages when changes are pushed to the `main` branch. The workflow is defined in `.github/workflows/docs.yml`.diff --git a/docs/docfx.json b/docs/docfx.jsonnew file mode 100644index 000000000..959e166c1--- /dev/null+++ b/docs/docfx.json@@ -0,0 +1,69 @@+{+ "build": {+ "content": [+ {+ "files": [+ "*.md",+ "toc.yml"+ ]+ },+ {+ "files": [+ "../README.md",+ "../CONTRIBUTING.md",+ "../CODE_OF_CONDUCT.md",+ "../SECURITY.md",+ "../SUPPORT.md"+ ],+ "dest": "."+ }+ ],+ "resource": [+ {+ "files": [+ "images/**"+ ]+ },+ {+ "files": [+ "../media/**"+ ],+ "dest": "media"+ }+ ],+ "overwrite": [+ {+ "files": [+ "apidoc/**.md"+ ],+ "exclude": [+ "obj/**",+ "_site/**"+ ]+ }+ ],+ "dest": "_site",+ "globalMetadataFiles": [],+ "fileMetadataFiles": [],+ "template": [+ "default"+ ],+ "postProcessors": [],+ "markdownEngineName": "markdig",+ "noLangKeyword": false,+ "keepFileLink": false,+ "cleanupCacheHistory": false,+ "disableGitFeatures": false,+ "globalMetadata": {+ "_appTitle": "Spec Kit Documentation",+ "_appName": "Spec Kit",+ "_appFooter": "Spec Kit - A specification-driven development toolkit",+ "_enableSearch": true,+ "_disableContribution": false,+ "_gitContribute": {+ "repo": "https://github.com/github/spec-kit",+ "branch": "main"+ }+ }+ }+}diff --git a/docs/index.md b/docs/index.mdnew file mode 100644index 000000000..154a19d0d--- /dev/null+++ b/docs/index.md@@ -0,0 +1,61 @@+# π± Spec Kit++*Build high-quality software faster.*++**An effort to allow organizations to focus on product scenarios rather than writing undifferentiated code with the help of Spec-Driven Development.**++## π€ What is Spec-Driven Development?++Spec-Driven Development **flips the script** on traditional software development. For decades, code has been king β specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: **specifications become executable**, directly generating working implementations rather than just guiding them.++## Getting Started++- [Installation Guide](installation.md)+- [Quick Start Guide](quickstart.md)++## π Core Philosophy++Spec-Driven Development is a structured process that emphasizes:++- **Intent-driven development** where specifications define the "_what_" before the "_how_"+- **Rich specification creation** using guardrails and organizational principles+- **Multi-step refinement** rather than one-shot code generation from prompts+- **Heavy reliance** on advanced AI model capabilities for specification interpretation++## π Development Phases++| Phase | Focus | Key Activities |+|-------|-------|----------------|+| **0-to-1 Development** ("Greenfield") | Generate from scratch | <ul><li>Start with high-level requirements</li><li>Generate specifications</li><li>Plan implementation steps</li><li>Build production-ready applications</li></ul> |+| **Creative Exploration** | Parallel implementations | <ul><li>Explore diverse solutions</li><li>Support multiple technology stacks & architectures</li><li>Experiment with UX patterns</li></ul> |+| **Iterative Enhancement** ("Brownfield") | Brownfield modernization | <ul><li>Add features iteratively</li><li>Modernize legacy systems</li><li>Adapt processes</li></ul> |++## π― Experimental Goals++Our research and experimentation focus on:++### Technology Independence+- Create applications using diverse technology stacks+- Validate the hypothesis that Spec-Driven Development is a process not tied to specific technologies, programming languages, or frameworks++### Enterprise Constraints+- Demonstrate mission-critical application development+- Incorporate organizational constraints (cloud providers, tech stacks, engineering practices)+- Support enterprise design systems and compliance requirements++### User-Centric Development+- Build applications for different user cohorts and preferences+- Support various development approaches (from vibe-coding to AI-native development)++### Creative & Iterative Processes+- Validate the concept of parallel implementation exploration+- Provide robust iterative feature development workflows+- Extend processes to handle upgrades and modernization tasks++## Contributing++Please see our [Contributing Guide](CONTRIBUTING.md) for information on how to contribute to this project.++## Support++For support, please check our [Support Guide](SUPPORT.md) or open an issue on GitHub.diff --git a/docs/installation.md b/docs/installation.mdnew file mode 100644index 000000000..4467e9c03--- /dev/null+++ b/docs/installation.md@@ -0,0 +1,69 @@+# Installation Guide++## π§ Prerequisites++- **Linux/macOS** (or WSL2 on Windows)+- AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)+- [uv](https://docs.astral.sh/uv/) for package management+- [Python 3.11+](https://www.python.org/downloads/)+- [Git](https://git-scm.com/downloads)++## Installation++### Initialize a New Project++The easiest way to get started is to initialize a new project:++```bash+uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>+```++Or initialize in the current directory:++```bash+uvx --from git+https://github.com/github/spec-kit.git specify init --here+```++### Specify AI Agent++You can proactively specify your AI agent during initialization:++```bash+uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai claude+uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai gemini+uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai copilot+```++### Ignore Agent Tools Check++If you prefer to get the templates without checking for the right tools:++```bash+uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai claude --ignore-agent-tools+```++## Verification++After initialization, you should see the following commands available in your AI agent:+- `/specify` - Create specifications+- `/plan` - Generate implementation plans+- `/tasks` - Break down into actionable tasks++## π Troubleshooting++### Git Credential Manager on Linux++If you're having issues with Git authentication on Linux, you can install Git Credential Manager:++```bash+#!/usr/bin/env bash+set -e+echo "Downloading Git Credential Manager v2.6.1..."+wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb+echo "Installing Git Credential Manager..."+sudo dpkg -i gcm-linux_amd64.2.6.1.deb+echo "Configuring Git to use GCM..."+git config --global credential.helper manager+echo "Cleaning up..."+rm gcm-linux_amd64.2.6.1.deb+```diff --git a/docs/quickstart.md b/docs/quickstart.mdnew file mode 100644index 000000000..d70fe8228--- /dev/null+++ b/docs/quickstart.md@@ -0,0 +1,114 @@+# β‘ Quick Start Guide++This guide will help you get started with Spec-Driven Development using Spec Kit.++## The 4-Step Process++### 1. Install Specify++Initialize your project depending on the coding agent you're using:++```bash+uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>+```++### 2. Create the Spec++Use the `/specify` command to describe what you want to build. Focus on the **what** and **why**, not the tech stack.++```bash+/specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.+```++### 3. Create a Technical Implementation Plan++Use the `/plan` command to provide your tech stack and architecture choices.++```bash+/plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.+```++### 4. Break Down and Implement++Use `/tasks` to create an actionable task list, then ask your agent to implement the feature.++## Detailed Example: Building Taskify++Here's a complete example of building a team productivity platform:++### Step 1: Define Requirements with `/specify`++```text+Develop Taskify, a team productivity platform. It should allow users to create projects, add team members,+assign tasks, comment and move tasks between boards in Kanban style. In this initial phase for this feature,+let's call it "Create Taskify," let's have multiple users but the users will be declared ahead of time, predefined.+I want five users in two different categories, one product manager and four engineers. Let's create three+different sample projects. Let's have the standard Kanban columns for the status of each task, such as "To Do,"+"In Progress," "In Review," and "Done." There will be no login for this application as this is just the very+first testing thing to ensure that our basic features are set up. For each task in the UI for a task card,+you should be able to change the current status of the task between the different columns in the Kanban work board.+You should be able to leave an unlimited number of comments for a particular card. You should be able to, from that task+card, assign one of the valid users. When you first launch Taskify, it's going to give you a list of the five users to pick+from. There will be no password required. When you click on a user, you go into the main view, which displays the list of+projects. When you click on a project, you open the Kanban board for that project. You're going to see the columns.+You'll be able to drag and drop cards back and forth between different columns. You will see any cards that are+assigned to you, the currently logged in user, in a different color from all the other ones, so you can quickly+see yours. You can edit any comments that you make, but you can't edit comments that other people made. You can+delete any comments that you made, but you can't delete comments anybody else made.+```++### Step 2: Refine the Specification++After the initial specification is created, clarify any missing requirements:++```text+For each sample project or project that you create there should be a variable number of tasks between 5 and 15+tasks for each one randomly distributed into different states of completion. Make sure that there's at least+one task in each stage of completion.+```++Also validate the specification checklist:++```text+Read the review and acceptance checklist, and check off each item in the checklist if the feature spec meets the criteria. Leave it empty if it does not.+```++### Step 3: Generate Technical Plan with `/plan`++Be specific about your tech stack and technical requirements:++```text+We are going to generate this using .NET Aspire, using Postgres as the database. The frontend should use+Blazor server with drag-and-drop task boards, real-time updates. There should be a REST API created with a projects API,+tasks API, and a notifications API.+```++### Step 4: Validate and Implement++Have your AI agent audit the implementation plan:++```text+Now I want you to go and audit the implementation plan and the implementation detail files.+Read through it with an eye on determining whether or not there is a sequence of tasks that you need+to be doing that are obvious from reading this. Because I don't know if there's enough here.+```++Finally, implement the solution:++```text+implement specs/002-create-taskify/plan.md+```++## Key Principles++- **Be explicit** about what you're building and why+- **Don't focus on tech stack** during specification phase+- **Iterate and refine** your specifications before implementation+- **Validate** the plan before coding begins+- **Let the AI agent handle** the implementation details++## Next Steps++- Read the [complete methodology](../spec-driven.md) for in-depth guidance+- Check out more examples in the repository+- Explore the source code on GitHubdiff --git a/docs/toc.yml b/docs/toc.ymlnew file mode 100644index 000000000..c12e14928--- /dev/null+++ b/docs/toc.yml@@ -0,0 +1,10 @@+- name: Home+ href: index.md+- name: Installation+ href: installation.md+- name: Quick Start+ href: quickstart.md+- name: Contributing+ href: CONTRIBUTING.md+- name: Support+ href: SUPPORT.md