From 4b98c20f5d97d5a93646a37f2678a8a05734e170 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?= <53200638+localden@users.noreply.github.com> Date: Mon, 8 Sep 2025 23:14:53 -0700 Subject: [PATCH] Docs setup --- .github/workflows/docs.yml | 67 ++++++++++++++++++++++ docs/.gitignore | 8 +++ docs/README.md | 33 +++++++++++ docs/docfx.json | 69 ++++++++++++++++++++++ docs/index.md | 61 ++++++++++++++++++++ docs/installation.md | 69 ++++++++++++++++++++++ docs/quickstart.md | 114 +++++++++++++++++++++++++++++++++++++ docs/toc.yml | 10 ++++ 8 files changed, 431 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/.gitignore create mode 100644 docs/README.md create mode 100644 docs/docfx.json create mode 100644 docs/index.md create mode 100644 docs/installation.md create mode 100644 docs/quickstart.md create mode 100644 docs/toc.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..92e81a5 --- /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@v4 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..614670d --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,8 @@ +# DocFX build output +_site/ +obj/ +.docfx/ + +# Temporary files +*.tmp +*.log diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..5501adf --- /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.json new file mode 100644 index 0000000..959e166 --- /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.md new file mode 100644 index 0000000..154a19d --- /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 | | +| **Creative Exploration** | Parallel implementations | | +| **Iterative Enhancement** ("Brownfield") | Brownfield modernization | | + +## 🎯 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.md new file mode 100644 index 0000000..4467e9c --- /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 +``` + +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 --ai claude +uvx --from git+https://github.com/github/spec-kit.git specify init --ai gemini +uvx --from git+https://github.com/github/spec-kit.git specify init --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 --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.md new file mode 100644 index 0000000..d70fe82 --- /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 +``` + +### 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 GitHub diff --git a/docs/toc.yml b/docs/toc.yml new file mode 100644 index 0000000..c12e149 --- /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