Merge pull request #100 from github/update-docs

Docs setup
Update docs/quickstart.md
2025-09-08 23:17:04 -07:00 · 2025-09-08 23:16:51 -07:00 · 2025-09-08 23:14:53 -07:00 · 2025-09-08 18:37:10 -07:00 · 2025-09-09 05:39:54 +05:30 · 2025-09-08 13:18:10 -07:00
20 changed files with 473 additions and 47 deletions
--- a/.github/workflows/docs.yml
+++ 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@v4
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -11,12 +11,14 @@ jobs:
    
    permissions:
      contents: write
+      pull-requests: write
      
    steps:
    - name: Checkout repository
      uses: actions/checkout@v4
      with:
        fetch-depth: 0
+        token: ${{ secrets.GITHUB_TOKEN }}
        
    - name: Get latest tag
      id: get_tag
@@ -204,7 +206,7 @@ jobs:
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        
-    - name: Update version in pyproject.toml
+    - name: Update version in pyproject.toml (for release artifacts only)
      if: steps.check_release.outputs.exists == 'false'
      run: |
        # Update version in pyproject.toml (remove 'v' prefix for Python versioning)
@@ -213,19 +215,8 @@ jobs:
        
        if [ -f "pyproject.toml" ]; then
          sed -i "s/version = \".*\"/version = \"$PYTHON_VERSION\"/" pyproject.toml
-          echo "Updated pyproject.toml version to $PYTHON_VERSION"
+          echo "Updated pyproject.toml version to $PYTHON_VERSION (for release artifacts only)"
        fi
        
-    - name: Commit version update
-      if: steps.check_release.outputs.exists == 'false'
-      run: |
-        git config --local user.email "action@github.com"
-        git config --local user.name "GitHub Action"
-        
-        if git diff --quiet; then
-          echo "No changes to commit"
-        else
-          git add pyproject.toml
-          git commit -m "chore: bump version to ${{ steps.get_tag.outputs.new_version }}"
-          git push
-        fi
+    # Note: No longer committing version changes back to main branch
+    # The version is only updated in the release artifacts
--- a/README.md
+++ b/README.md
@@ -2,14 +2,14 @@
    <img src="./media/logo_small.webp"/>
    <h1>🌱 Spec Kit</h1>
    <h3><em>Build high-quality software faster.</em></h3>
-    
-    [![Release](https://github.com/github/spec-kit/actions/workflows/release.yml/badge.svg)](https://github.com/github/spec-kit/actions/workflows/release.yml)
 </div>

 <p align="center">
    <strong>An effort to allow organizations to focus on product scenarios rather than writing undifferentiated code with the help of Spec-Driven Development.</strong>
 </p>

+[![Release](https://github.com/github/spec-kit/actions/workflows/release.yml/badge.svg)](https://github.com/github/spec-kit/actions/workflows/release.yml)
+
 ---

 ## Table of Contents
@@ -21,8 +21,12 @@
 - [🎯 Experimental goals](#-experimental-goals)
 - [🔧 Prerequisites](#-prerequisites)
 - [📖 Learn more](#-learn-more)
- [Detailed process](#detailed-process)
- [Troubleshooting](#troubleshooting)
+- [📋 Detailed process](#-detailed-process)
+- [🔍 Troubleshooting](#-troubleshooting)
+- [👥 Maintainers](#-maintainers)
+- [💬 Support](#-support)
+- [🙏 Acknowledgements](#-acknowledgements)
+- [📄 License](#-license)

 ## 🤔 What is Spec-Driven Development?

@@ -43,7 +47,7 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
 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 never other nested albums. Within each album, photos are previewed in a tile-like interface.
+/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
@@ -118,7 +122,7 @@ Our research and experimentation focus on:

 ---

-## Detailed process
+## 📋 Detailed process

 <details>
 <summary>Click to expand the detailed step-by-step walkthrough</summary>
@@ -207,7 +211,7 @@ At this stage, your project folder contents should resemble the following:
 │	 ├── setup-plan.sh
 │	 └── update-claude-md.sh
 ├── specs
-│	 └── 002-create-taskify
+│	 └── 001-create-taskify
 │	     └── spec.md
 └── templates
    ├── CLAUDE-template.md
@@ -260,7 +264,7 @@ The output of this step will include a number of implementation detail documents
 │	 ├── setup-plan.sh
 │	 └── update-claude-md.sh
 ├── specs
-│	 └── 002-create-taskify
+│	 └── 001-create-taskify
 │	     ├── contracts
 │	     │	 ├── api-spec.json
 │	     │	 └── signalr-spec.md
@@ -341,14 +345,14 @@ Once the implementation step is done, ask Claude Code to try to run the applicat

 ---

-## Troubleshooting
+## 🔍 Troubleshooting

 ### Git Credential Manager on Linux

 If you're having issues with Git authentication on Linux, you can install Git Credential Manager:

 ```bash
-#!/bin/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
@@ -360,19 +364,19 @@ echo "Cleaning up..."
 rm gcm-linux_amd64.2.6.1.deb
 ```

-## Maintainers
+## 👥 Maintainers

 - Den Delimarsky ([@localden](https://github.com/localden))
 - John Lam ([@jflam](https://github.com/jflam))

-## Support
+## 💬 Support

 For support, please open a [GitHub issue](https://github.com/github/spec-kit/issues/new). We welcome bug reports, feature requests, and questions about using Spec-Driven Development.

-## Acknowledgements
+## 🙏 Acknowledgements

 This project is heavily influenced by and based on the work and research of [John Lam](https://github.com/jflam).

-## License
+## 📄 License

 This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms.
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -0,0 +1,8 @@
+# DocFX build output
+_site/
+obj/
+.docfx/
+
+# Temporary files
+*.tmp
+*.log
--- a/docs/README.md
+++ 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`.
--- a/docs/docfx.json
+++ 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"
+      }
+    }
+  }
+}
--- a/docs/index.md
+++ 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.
--- a/docs/installation.md
+++ 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
+```
--- a/docs/quickstart.md
+++ 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 for in-depth guidance
+- Check out more examples in the repository
+- Explore the source code on GitHub
--- a/docs/toc.yml
+++ 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
--- a/scripts/check-task-prerequisites.sh
+++ b/scripts/check-task-prerequisites.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Check that implementation plan exists and find optional design documents
 # Usage: ./check-task-prerequisites.sh [--json]

--- a/scripts/common.sh
+++ b/scripts/common.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Common functions and variables for all scripts

 # Get repository root
--- a/scripts/create-new-feature.sh
+++ b/scripts/create-new-feature.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Create a new feature with branch, directory structure, and template
 # Usage: ./create-new-feature.sh "feature description"
 #        ./create-new-feature.sh --json "feature description"
--- a/scripts/get-feature-paths.sh
+++ b/scripts/get-feature-paths.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Get paths for current feature branch without creating anything
 # Used by commands that need to find existing feature files

--- a/scripts/setup-plan.sh
+++ b/scripts/setup-plan.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Setup implementation plan structure for current branch
 # Returns paths needed for implementation plan generation
 # Usage: ./setup-plan.sh [--json]
--- a/scripts/update-agent-context.sh
+++ b/scripts/update-agent-context.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Incrementally update agent context files based on new feature plan
 # Supports: CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md
 # O(1) operation - only reads current context file and new plan.md
--- a/spec-driven.md
+++ b/spec-driven.md
@@ -2,7 +2,7 @@

 ## The Power Inversion

-For decades, code has been king. Specifications served code—they were the scaffolding we built and then discarded once the "real work" of coding began. We wrote PRDs to guide development, created design docs to inform implementation, drew diagrams to visualize architecture. But these were always subordinate to the code itself. Code was truth. Everything else was, at best, good intentions. Code was the source of truth, as it mvoed forward, and spec's rarely kept pace. As the asset (code) and the implementation are one, it's not easy to have a parallel implementation without trying to build from the code.
+For decades, code has been king. Specifications served code—they were the scaffolding we built and then discarded once the "real work" of coding began. We wrote PRDs to guide development, created design docs to inform implementation, drew diagrams to visualize architecture. But these were always subordinate to the code itself. Code was truth. Everything else was, at best, good intentions. Code was the source of truth, as it moved forward, and spec's rarely kept pace. As the asset (code) and the implementation are one, it's not easy to have a parallel implementation without trying to build from the code.

 Spec-Driven Development (SDD) inverts this power structure. Specifications don't serve code—code serves specifications. The (Product Requirements Document-Specification) PRD isn't a guide for implementation; it's the source that generates implementation. Technical plans aren't documents that inform coding; they're precise definitions that produce code. This isn't an incremental improvement to how we build software. It's a fundamental rethinking of what drives development.

@@ -34,13 +34,13 @@ The feedback loop extends beyond initial development. Production metrics and inc

 Three trends make SDD not just possible but necessary:

-First, AI capabilities have reached a threshold where natural language specifications can reliably generate working code. This isn't about replacing developers—it's about amplifying their effectiveness by automating the mechanical translation from specification to implementation. It can amplify exploration and creativity, it can support "start-over" easily, it supports addition substraction and critical thinking.
+First, AI capabilities have reached a threshold where natural language specifications can reliably generate working code. This isn't about replacing developers—it's about amplifying their effectiveness by automating the mechanical translation from specification to implementation. It can amplify exploration and creativity, it can support "start-over" easily, it supports addition subtraction and critical thinking.

-Second, software complexity continues to grow exponentially. Modern systems integrate dozens of services, frameworks, and dependencies. Keeping all these pieces aligned with original intent through manual processes becomes increasingly difficult. SDD provides systematic alignment through specification-driven generation. Frameworks may eviolve to provide AI-first support, not human-first support, or architect around reusable components. 
+Second, software complexity continues to grow exponentially. Modern systems integrate dozens of services, frameworks, and dependencies. Keeping all these pieces aligned with original intent through manual processes becomes increasingly difficult. SDD provides systematic alignment through specification-driven generation. Frameworks may evolve to provide AI-first support, not human-first support, or architect around reusable components.

 Third, the pace of change accelerates. Requirements change far more rapidly today than ever before. Pivoting is no longer exceptional—it's expected. Modern product development demands rapid iteration based on user feedback, market conditions, and competitive pressures. Traditional development treats these changes as disruptions. Each pivot requires manually propagating changes through documentation, design, and code. The result is either slow, careful updates that limit velocity, or fast, reckless changes that accumulate technical debt.

-SDD can support what-if/simulation experiments, "If we need to re-implement of change the application to promote a business need to sell more T-shirts, how would we implement and experiment for that?". 
+SDD can support what-if/simulation experiments, "If we need to re-implement or change the application to promote a business need to sell more T-shirts, how would we implement and experiment for that?".

 SDD transforms requirement changes from obstacles into normal workflow. When specifications drive implementation, pivots become systematic regenerations rather than manual rewrites. Change a core requirement in the PRD, and affected implementation plans update automatically. Modify a user story, and corresponding API endpoints regenerate. This isn't just about initial development—it's about maintaining engineering velocity through inevitable changes.

@@ -256,7 +256,7 @@ The constitution defines nine articles that shape every aspect of the developmen
 #### Article I: Library-First Principle
 Every feature must begin as a standalone library—no exceptions. This forces modular design from the start:
 ```
-Every feature in Specify2 MUST begin its existence as a standalone library. 
+Every feature in Specify MUST begin its existence as a standalone library. 
 No feature shall be implemented directly within application code without 
 first being abstracted into a reusable library component.
 ```
--- a/src/specify_cli/init.py
+++ b/src/specify_cli/init.py
@@ -15,7 +15,7 @@ Specify CLI - Setup tool for Specify projects
 Usage:
    uvx specify-cli.py init <project-name>
    uvx specify-cli.py init --here
-    
+
 Or install globally:
    uv tool install --from specify-cli.py specify-cli
    specify init <project-name>
@@ -813,12 +813,12 @@ def init(
    if selected_ai == "claude":
        steps_lines.append(f"{step_num}. Open in Visual Studio Code and start using / commands with Claude Code")
        steps_lines.append("   - Type / in any file to see available commands")
-        steps_lines.append("   - Use /spec to create specifications")
+        steps_lines.append("   - Use /specify to create specifications")
        steps_lines.append("   - Use /plan to create implementation plans")
        steps_lines.append("   - Use /tasks to generate tasks")
    elif selected_ai == "gemini":
        steps_lines.append(f"{step_num}. Use / commands with Gemini CLI")
-        steps_lines.append("   - Run gemini /spec to create specifications")
+        steps_lines.append("   - Run gemini /specify to create specifications")
        steps_lines.append("   - Run gemini /plan to create implementation plans")
        steps_lines.append("   - See GEMINI.md for all available commands")
    elif selected_ai == "copilot":
@@ -868,4 +868,4 @@ def main():


 if __name__ == "__main__":
-    main()
+    main()
--- a/templates/commands/plan.md
+++ b/templates/commands/plan.md
@@ -19,7 +19,7 @@ Given the implementation details provided as an argument, do this:
 3. Read the constitution at `/memory/constitution.md` to understand constitutional requirements.

 4. Execute the implementation plan template:
-   - Load `/templates/implementation-plan-template.md` (already copied to IMPL_PLAN path)
+   - Load `/templates/plan-template.md` (already copied to IMPL_PLAN path)
   - Set Input path to FEATURE_SPEC
   - Run the Execution Flow (main) function steps 1-10
   - The template is self-contained and executable
--- a/templates/commands/tasks.md
+++ b/templates/commands/tasks.md
@@ -13,10 +13,10 @@ Given the context provided as an argument, do this:
 2. Load and analyze available design documents:
   - Always read plan.md for tech stack and libraries
   - IF EXISTS: Read data-model.md for entities
-   - IF EXISTS: Read contracts/ for API endpoints  
+   - IF EXISTS: Read contracts/ for API endpoints
   - IF EXISTS: Read research.md for technical decisions
   - IF EXISTS: Read quickstart.md for test scenarios
-   
+
   Note: Not all projects have all documents. For example:
   - CLI tools might not have contracts/
   - Simple libraries might not need data-model.md
Author	SHA1	Message	Date
Den Delimarsky	4591cf7df6	Merge pull request #100 from github/update-docs Docs setup	2025-09-08 23:17:04 -07:00
Den Delimarsky	03ee3401e7	Update docs/quickstart.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>	2025-09-08 23:16:51 -07:00
Den Delimarsky 🌺	4b98c20f5d	Docs setup	2025-09-08 23:14:53 -07:00
Den Delimarsky	e566e90708	Merge pull request #94 from paullen/patch-1 Update README.md	2025-09-08 18:37:10 -07:00
Bitan Paul	a3b6e4455a	Update README.md Correct grammar in /specify example for better clarity	2025-09-09 05:39:54 +05:30
Den Delimarsky	3259b845ed	Merge pull request #85 from github/update-readme README consistency	2025-09-08 13:18:10 -07:00
Den Delimarsky 🌺	9d01e9d7b6	Update README.md	2025-09-08 13:16:38 -07:00
Den Delimarsky	e786a9df64	Merge pull request #70 from azuma317/cleanup/tasks-template-whitespace Remove trailing whitespace from tasks.md template	2025-09-08 09:18:59 -07:00
azuma	51b8459122	Remove trailing whitespace from tasks.md template	2025-09-08 11:57:53 +09:00
Den Delimarsky 🌺	fa56dbd8b0	Merge branch 'main' of https://github.com/github/spec-kit	2025-09-07 00:55:55 -07:00
Den Delimarsky	793e5176ef	Merge pull request #54 from y-yagi/fixes_shebang Use `/usr/bin/env bash` instead of `/bin/bash` for shebang	2025-09-07 00:46:20 -07:00
Yuji Yaginuma	29eb082e2a	Use `/usr/bin/env bash` instead of `/bin/bash` for shebang Some systems like NixOS don't have `/bin/bash`. Ref: https://discourse.nixos.org/t/add-bin-bash-to-avoid-unnecessary-pain/5673 This changes allow to run scripts in those systems. Fixes #43.	2025-09-07 15:24:27 +09:00
Den Delimarsky	7176d2dea3	Merge pull request #27 from riya-amemiya/riya-amemiya/fix-typos fix: correct typos in spec-driven.md	2025-09-04 23:33:45 -07:00
Riya Amemiya	6cade67360	fix: correct typos in spec-driven.md - Fixed spelling: substraction → subtraction - Fixed spelling: eviolve → evolve - Fixed grammar: re-implement of change → re-implement or change	2025-09-05 12:04:22 +09:00
Den Delimarsky	c106281eff	Merge pull request #24 from np-yoe/patch-1 Fix formatting in usage instructions	2025-09-04 12:34:18 -07:00
np-yoe	74ccf93512	Fix formatting in usage instructions	2025-09-05 02:17:29 +09:00
Den Delimarsky	decccc4e95	Merge pull request #13 from yamkazu/fix-plan-temaplate-name Fix template path in plan command	2025-09-04 09:46:51 -07:00
Den Delimarsky	23c6bf1b71	Merge pull request #19 from adam-paterson/fix/really-important-documentation-fix fix: incorrect tree structure in examples	2025-09-04 09:46:32 -07:00
Den Delimarsky	36fbb85c65	Merge pull request #21 from thegovind/main fix minor typo in constitution's Article I	2025-09-04 09:46:05 -07:00
Govind Kamtamneni	f077e90a24	fix minor typo in Article I	2025-09-04 13:46:36 +00:00
adam.paterson	f88f6c8c05	fix: incorrect tree structure in examples	2025-09-04 13:42:39 +01:00
Kazuki YAMAMOTO	fd517699a4	Fix template path in plan command documentation	2025-09-04 10:59:07 +09:00
Den Delimarsky	b4833cb7ea	Merge pull request #8 from Insik-Han/patch-1 chore: Fix typo	2025-09-03 09:22:34 -07:00
Insik Han	2fc7ebeebe	Update CLI commands from '/spec' to '/specify'	2025-09-03 19:24:27 +09:00
Den Delimarsky	b4b31f167c	Merge pull request #7 from chanezon/add-execute-perm-to-shell-scripts adding executable permission to the scripts so they execute when the …	2025-09-02 21:48:45 -07:00
PATRICK CHANEZON	f3fb55d183	adding executable permission to the scripts so they execute when the coding agent launches them	2025-09-02 21:20:42 -07:00
Den Delimarsky	54c7f9c19b	Merge pull request #4 from lucasmodrich/fix-typo doco(spec-driven): Fix small typo in spec-driven.md	2025-09-02 21:03:51 -07:00
Lucas Modrich	81fea96e42	doco(spec-driven): Fix small typo in document	2025-09-03 10:58:10 +10:00
Den Delimarsky	b5b02b3961	Merge pull request #3 from github/update-readme-contributors Update README.md	2025-08-25 14:10:32 -07:00
Den Delimarsky 🌺	c3ff114c5f	Update README.md	2025-08-25 14:09:38 -07:00
Den Delimarsky	5ee736b677	Merge pull request #2 from github/update-readme-contributors Fix release workflow to work with repository rules	2025-08-25 14:09:19 -07:00
Den Delimarsky	704e272a00	Update .github/workflows/release.yml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>	2025-08-25 14:09:09 -07:00
Den Delimarsky 🌺	f755bcfb43	Fix release workflow to work with repository rules - Remove problematic direct push to main branch - Keep version updates only for release artifacts - Add pull-requests permission for future flexibility - Releases/tags created via API don't require branch pushes	2025-08-25 14:07:30 -07:00
Den Delimarsky 🌺	c96f6e1a1b	Fix release workflow to work with repository rules - Remove problematic direct push to main branch - Keep version updates only for release artifacts - Add pull-requests permission for future flexibility - Releases/tags created via API don't require branch pushes	2025-08-25 14:07:00 -07:00