diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..fcce9dc6c --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,6 @@ +# Copilot instructions for automated code reviews 🌱 + +This file provides minimal guidance for Copilot Code Review suggestions on pull requests. Code changes should be judged against the guidelines defined below. + +- Reference [repository-level standards](../AGENTS.md) as the authoritative source for project conventions when reviewing any files changed in this repo. +- For files under `docs/`, additionally consult the [docs-specific guidance](../docs/AGENTS.md) for additional requirements designed to promote consistency in independent documentation contributions. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3e6e24aa8..5cfb3a86b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,7 +55,7 @@ Here are a few things you can do that will increase the likelihood of your pull ## Development workflow -When working on spec-kit: +When working on Spec Kit: 1. Test changes with the `specify` CLI commands (`/speckit.specify`, `/speckit.plan`, `/speckit.tasks`) in your coding agent of choice 2. Verify templates are working correctly in `templates/` directory @@ -99,7 +99,7 @@ When submitting AI-assisted contributions, please ensure they include: - **Clear disclosure of AI use** - You are transparent about AI use and degree to which you're using it for the contribution - **Human understanding and testing** - You've personally tested the changes and understand what they do -- **Clear rationale** - You can explain why the change is needed and how it fits within Spec Kit's goals +- **Clear rationale** - You can explain why the change is needed and how it fits within Spec Kit's goals - **Concrete evidence** - Include test cases, scenarios, or examples that demonstrate the improvement - **Your own analysis** - Share your thoughts on the end-to-end developer experience diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 000000000..58abaa240 --- /dev/null +++ b/docs/AGENTS.md @@ -0,0 +1,10 @@ +# AGENTS.md for Spec Kit documentation + +## Guidelines for consistent user documentation + +- The correct syntax for this project is "Spec Kit" (two words, capital S and K). Never use any other variation outside of code snippets. +- Use active voice and present tense where possible. +- Write for an audience familiar with AI and programming concepts, but new to Spec Kit. +- Ensure an informal narrative, teaching voice: give a one-line "why" plus a one-line "how" and a minimal, copy‑pastable example/command when helpful. +- User documentation files are expected to use kebab-case for the `.md` extension, except for special files like `README.md`. +- Examples should be copy-pastable in fenced code blocks and accurate; if unsure, prefer not to change examples. diff --git a/docs/existing-project-guide.md b/docs/existing-project-guide.md new file mode 100644 index 000000000..906bcce50 --- /dev/null +++ b/docs/existing-project-guide.md @@ -0,0 +1,176 @@ +# Using Spec Kit in an Existing Project + +> You already have a codebase. You want to try Spec Kit without rearranging the furniture. This is a surgical guide: minimum steps, clear checkpoints, easy rollback. This is a **10-minute guide** — pick a realistic scope and save any grand redesigns for later. + +--- + +## 1. Prerequisites + +Before starting, you need the Spec Kit CLI tool installed on your machine. + +Install the CLI by following the [Installation Guide](installation.md), then jump back here for step 2. + +> **Starting a new project?** See the [Quick Start Guide](quickstart.md) instead. + +--- + +## 2. Init + +> Spec Kit initializes a **workspace** in the current directory and registers **slash commands** with your coding agent. This workspace holds your **specs, plans, and tasks**. + +* Substitute any [supported assistant](../README.md#-supported-ai-agents) (`claude`, `gemini`, `copilot`, `cursor-agent`, etc.) for the `--ai` argument in place of `copilot`. +* When prompted for script type, **pick your flavor** and continue. + +### A) If you installed the CLI globally + +```bash +specify init --here --ai copilot +``` + +### B) If you used uvx one-shot + +```bash +uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai copilot +``` + +### Checkpoint + +Spec Kit registers these slash commands in your coding agent: + +- `/speckit.constitution` +- `/speckit.specify` +- `/speckit.clarify` +- `/speckit.plan` +- `/speckit.tasks` +- `/speckit.analyze` +- `/speckit.implement` + +--- + +## 3. Constitution + +Use the `/speckit.constitution` command to define the project's non-negotiable rules and constraints that AI must follow. + +> You'll want to spend serious time here later, but for now write the **high-priority or high-impact** rules you want AI to always follow in your repo. + +```markdown +/speckit.constitution Create principles for: +- Quality: tests for all new endpoints; critical-path coverage > 80%. +- Performance/UX: totals update within 200 ms of coupon apply. +- Security/Compliance: log coupon usage with order ID; no PII in logs. +``` + +--- + +## 4. Specify + +Use `/speckit.specify` inside your coding agent to create a single, focused story. Keep it high-level—what and why. Don’t worry about technical details yet; those come later. + +> 💡 **Model selection matters:** Pick a model capable of handling systems-level reasoning, such as `Claude 4.5`, `GPT-5`, or `Gemini 2.5 Pro`. Avoid smaller, lower-capacity models (like `GPT-5-mini` or similar) for systems-level tasks; they can miss context or produce incomplete plans. Use smaller models for narrow, well-defined edits or straightforward refactors. +> +> **This is a 10-minute starter**, so pick something achievable — save the joyrides until your constraints file is complete! + +```markdown +/speckit.specify Create story “Apply coupon during checkout.” +Goal: User can enter a valid coupon and see totals update before payment. +Acceptance Criteria: +- Valid coupon → discount applied; totals update before payment. +- Invalid/expired coupon → show reason; totals unchanged. +Constraints: one coupon per order; preserve tax/shipping rules; log coupon usage. +Out of scope: stacking, gift cards, loyalty. +``` + +### Checkpoint + +* Spec Kit automatically creates and checks out a **feature branch**, e.g. `001-checkout-apply-coupon`. +* It also creates a `./specs/001-checkout-apply-coupon/` folder and a set of `.md` files. +* `spec.md` is the specification derived from your prompt — **review it now for accuracy.** + +--- + +## 5. Clarify + +If you find any mistakes in your `spec.md` or need to tighten constraints, use the `/speckit.clarify` prompt. + +```markdown +/speckit.clarify Tighten ACs: add duplicate-apply and expired-coupon edge cases. +``` + +Repeat until you’re satisfied — this shapes **the plan**. + +--- + +## 6. Plan + +The plan converts your spec into concrete technical decisions—choosing frameworks, databases, and architecture patterns. + +You can leave this step blank, or include a **single tech requirement** if one matters; otherwise, AI will make a reasonable attempt. + +```markdown +/speckit.plan Tech requirement: preserve existing checkout API contract and return HTTP 422 for invalid coupons. +``` + +--- + +## 7. Tasks + +This breaks down your plan into a step-by-step checklist of individual coding tasks. + +**Taskify** once your plan feels right. + +```markdown +/speckit.tasks +``` + +--- + +## 8. Analyze (Optional) + +Analyze cross-checks your spec, plan, and tasks for consistency issues before implementation begins. + +Run analyze as a safety check before touching code: + +```markdown +/speckit.analyze +``` + +--- + +## 9. Implement + +This executes all the tasks from step 7, writing the actual code to implement your feature. + +The last step is implementation with the name of your spec. You can include `--dry-run` to see what would be changed without writing any files, or run without it to have AI implement the changes. + +```markdown +/speckit.implement 001-checkout-apply-coupon --dry-run # optional: shows planned changes without executing +/speckit.implement 001-checkout-apply-coupon # execute the implementation +``` + +--- + +## Commit strategy + +Decide how to organize your git commits—either all-in-one or separating planning from code. + +Use **one commit** for the full spike — specs → plan → tasks → code. +If your org enforces separation, use **two commits:** (1) specs + plan + tasks, (2) code changes. + +--- + +## Troubleshooting (quick) + +| Symptom | Likely Cause | Fix | +| - | - | - | +| Slash commands not recognized | Init not executed or failed | Re-run init with `--ai copilot` in repo root; restart agent | +| “No such option: --ai” | Missing assistant name | Use `--ai copilot` (or another supported value) | +| Nothing generated after `/speckit.specify` | Missing model creds / provider blocked / init incomplete | Fix credentials; verify init output; retry with a smaller story | +| Implement touches unrelated files | Spec / plan too vague | Tighten scope; add explicit constraints / out-of-scope; re-run plan / tasks | + +--- + +## Next Steps + +- **Learn more:** Read the [complete Spec-Driven Development methodology](../spec-driven.md) +- **New projects:** See the [Quick Start Guide](quickstart.md) for greenfield workflows +- **Troubleshooting:** Check the main [README troubleshooting section](../README.md#-troubleshooting) diff --git a/docs/quickstart.md b/docs/quickstart.md index a97c9fe19..0ab393e9b 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,13 +1,19 @@ # Quick Start Guide -This guide will help you get started with Spec-Driven Development using Spec Kit. +This guide will help you get started with Spec-Driven Development using Spec Kit for **new projects**. +> **Already have a project?** See the [Existing Project Guide](existing-project-guide.md) for a streamlined workflow. +> > NEW: All automation scripts now provide both Bash (`.sh`) and PowerShell (`.ps1`) variants. The `specify` CLI auto-selects based on OS unless you pass `--script sh|ps`. ## The 4-Step Process ### 1. Install Specify +Create a new project directory and set up Spec-Kit with your preferred AI coding agent. + +> For detailed installation options, see the [Installation Guide](installation.md). + Initialize your project depending on the coding agent you're using: ```bash @@ -23,6 +29,8 @@ uvx --from git+https://github.com/github/spec-kit.git specify init Encodes principles into `/memory/constitution.md`, propagates to all templates, and validates future implementations automatically. + ### The `/speckit.specify` Command This command transforms a simple feature description (the user-prompt) into a complete, structured specification with automatic repository management: @@ -83,24 +113,223 @@ This command transforms a simple feature description (the user-prompt) into a co 3. **Template-Based Generation**: Copies and customizes the feature specification template with your requirements 4. **Directory Structure**: Creates the proper `specs/[branch-name]/` structure for all related documents +**Expected Input:** + +- Provide natural language feature description +- System automatically generates branch, spec file, user stories, and acceptance criteria + +**Minimal usage** (requires feature description): + +```markdown +/speckit.specify +Real-time chat system with instant messaging, conversation history, and user presence (online/offline/away). Users create rooms, add members, manage settings. +``` + +> Generates a document like `spec.md` with structured requirements, auto-numbered feature, branch created, quality checklist validated. + +### The `/speckit.clarify` Command + +This command identifies underspecified areas in your feature spec and guides you through targeted clarification questions to resolve ambiguities: + +**Core Value**: Eliminates specification uncertainty early, preventing downstream rework and ensuring your requirements are precise enough for consistent implementation. + +**Benefits**: +- Asks only high-impact questions that affect architecture or testing +- Provides recommended answers based on best practices and project context +- Updates your spec.md automatically with accepted clarifications +- Covers functional scope, data models, UX flows, and quality attributes +- Limits to 5 questions maximum to avoid analysis paralysis + +**Expected Input:** + +- Direct clarification focus to specific areas (data model, performance, security) +- System automatically identifies ambiguities and asks targeted questions (max 5) + +**Minimal usage** (runs without arguments, scans entire spec): + +```markdown +/speckit.clarify +``` + +**With focus** (optionally narrow scope): + +```markdown +/speckit.clarify +Focus on data model (retention policy, capacity limits) and security (encryption). +``` + +> Asks high-impact questions, provides recommended answers, and updates `spec.md` with "Clarifications" section automatically. + +### The `/speckit.checklist` Command + +This command **automatically generates** custom checklists that serve as "unit tests for your requirements," validating the quality and completeness of your specifications: + +**Core Value**: Transforms vague requirements into measurable quality gates, ensuring your specifications are precise enough to generate reliable code. + +**Benefits**: +- **Automatically creates** targeted checklists for different concerns (UX, API, security, performance) +- Tests requirement clarity, consistency, and measurability rather than implementation behavior +- Identifies missing edge cases and acceptance criteria gaps +- Provides traceability between requirements and validation points +- Enables systematic requirement refinement before planning begins + +**Expected Input:** + +- Specify quality concern area (security, API, UX, performance) +- System automatically generates validation checklist testing requirement quality + +**Minimal usage** (requires quality focus area): + +```markdown +/speckit.checklist security +``` + +**With detail** (optionally add specifics): + +```markdown +/speckit.checklist +Security: password policies, encryption, data retention, privacy controls +``` + +> Generates `checklists/security.md` validating requirement clarity/measurability. Identifies gaps (e.g., "encryption standard not specified"). + ### The `/speckit.plan` Command -Once a feature specification exists, this command creates a comprehensive implementation plan: +Once a feature specification exists, this command automatically creates a comprehensive implementation plan from your spec: + +**Core Value**: Translates business requirements into actionable technical architecture, eliminating the gap between "what we need" and "how to build it." + +**Benefits**: + +- Analyzes all requirements and automatically creates phased implementation strategy +- Ensures all technical decisions trace back to specific requirements +- Generates supporting artifacts (data models, API contracts, schemas) automatically +- Validates alignment with project constitution and architectural principles +- Produces implementation-ready technical documentation in minutes + +**Expected Input:** + +- Highlight blocking architectural decisions that need priority +- System automatically analyzes spec, generates architecture, models, contracts, phases + +**Minimal usage** (runs without arguments, analyzes full spec): + +```markdown +/speckit.plan +``` + +**With priorities** (optionally specify focus): -1. **Specification Analysis**: Reads and understands the feature requirements, user stories, and acceptance criteria -2. **Constitutional Compliance**: Ensures alignment with project constitution and architectural principles -3. **Technical Translation**: Converts business requirements into technical architecture and implementation details -4. **Detailed Documentation**: Generates supporting documents for data models, API contracts, and test scenarios -5. **Quickstart Validation**: Produces a quickstart guide capturing key validation scenarios +```markdown +/speckit.plan +Prioritize real-time transport decision (WebSocket vs polling) and auth integration. +``` + +> Generates `plan.md` with architecture, data models, API contracts, implementation phases—all traced to spec requirements. ### The `/speckit.tasks` Command -After a plan is created, this command analyzes the plan and related design documents to generate an executable task list: +This command analyzes your implementation plan and design documents to automatically generate an executable task list: + +**Core Value**: Breaks down complex architecture into specific, ordered, actionable tasks that can be executed systematically with clear dependencies and parallelization opportunities. + +**Benefits**: + +- Automatically maps technical decisions to concrete implementation tasks +- Identifies task dependencies and safe parallel execution paths +- Converts abstract plans into specific file creation and code generation steps +- Marks non-blocking tasks with `[P]` for parallel execution +- Generates phase-based execution roadmap ready for implementation + +**Expected Input:** + +- Constrain scope (MVP only, specific user stories) +- System automatically generates tasks, dependencies, parallelization markers + +**Minimal usage** (runs without arguments, processes full plan): + +```markdown +/speckit.tasks +``` + +**With scope constraint** (optionally limit to MVP): + +```markdown +/speckit.tasks +MVP scope only: P1 stories + shared infrastructure +``` + +> Generates `tasks.md` with phases, task IDs, dependencies, `[P]` parallel markers, file paths—immediately executable. + +### The `/speckit.analyze` Command + +This command performs automated cross-artifact consistency analysis, validating that your specification, plan, and tasks align before expensive implementation begins: + +**Core Value**: Catches specification gaps, conflicts, and incomplete coverage *before* they become code bugs—preventing costly rework after implementation starts. + +**Benefits**: + +- Automatically scans all three artifacts for requirement → task coverage +- Identifies unassigned requirements that would be missed during implementation +- Flags vague/unmeasurable terms that lack acceptance criteria +- Detects conflicting requirements or technical decisions +- Reports constitutional violations before code generation +- Surfaces critical issues blocking implementation readiness + +**Expected Input:** + +- Set severity filter (critical issues only vs. all issues) +- System automatically scans spec/plan/tasks for gaps, conflicts, violations + +**Minimal usage** (runs without arguments, reports all issues): + +```markdown +/speckit.analyze +``` + +**With severity filter** (optionally limit to critical): + +```markdown +/speckit.analyze +CRITICAL issues only: coverage gaps, constitutional violations, P1 story risks +``` + +> Scans artifacts, reports gaps (e.g., "Authentication: 0 assigned tasks—security gap detected"). Fix before implementation. + +### The `/speckit.implement` Command + +This command executes your complete implementation plan by processing all tasks in your tasks.md file, following strict test-first development: -1. **Inputs**: Reads `plan.md` (required) and, if present, `data-model.md`, `contracts/`, and `research.md` -2. **Task Derivation**: Converts contracts, entities, and scenarios into specific tasks -3. **Parallelization**: Marks independent tasks `[P]` and outlines safe parallel groups -4. **Output**: Writes `tasks.md` in the feature directory, ready for execution by a Task agent +**Core Value**: Transforms your specification documents into working code through systematic, phase-by-phase execution that maintains quality at every step. + +**Benefits**: + +- Enforces test-driven development (tests written before implementation) +- Respects task dependencies and parallelization markers +- Validates checklist completion before allowing implementation to proceed +- Automatically sets up proper ignore files for your technology stack +- Provides progress tracking and error handling throughout execution + +**Expected Input:** + +- Specify scope (which user stories to implement) +- Set failure behavior (halt on error vs. continue) +- System automatically executes tasks, enforces test-first, validates dependencies + +**Minimal usage** (runs without arguments, executes all tasks): + +```markdown +/speckit.implement +``` + +**With scope control** (optionally limit execution): + +```markdown +/speckit.implement +User Story 1 (authentication) only. Halt on any non-parallel task failure. +``` + +> Executes tasks in phase order, writes tests before code, validates dependencies, stops on critical failures. ### Example: Building a Chat Feature @@ -120,9 +349,14 @@ Total: ~12 hours of documentation work **SDD with Commands Approach:** ```bash +# Step 0: Establish project constitution (first time only, 10 minutes) +/speckit.constitution +Library-first: every feature begins as standalone library +Test-first: no code before tests +Simplicity gate: max 3 projects per feature + # Step 1: Create the feature specification (5 minutes) /speckit.specify Real-time chat system with message history and user presence - # This automatically: # - Creates branch "003-chat-system" # - Generates specs/003-chat-system/spec.md @@ -130,10 +364,26 @@ Total: ~12 hours of documentation work # Step 2: Generate implementation plan (5 minutes) /speckit.plan WebSocket for real-time messaging, PostgreSQL for history, Redis for presence +# Creates: specs/003-chat-system/spec.md with structured requirements -# Step 3: Generate executable tasks (5 minutes) -/speckit.tasks +# Step 2: Clarify ambiguities (5 minutes) +/speckit.clarify +# Asks: "What latency defines 'real-time'?", "How long should message history persist?" +# Updates: spec.md with clarification section + +# Step 3: Validate requirement quality (5 minutes) +/speckit.checklist security +/speckit.checklist api +# Generates: checklists/security.md, checklists/api.md +# Tests: requirement clarity, completeness, measurability + +# Step 4: Generate implementation plan (5 minutes) +/speckit.plan +# Creates: plan.md with WebSocket architecture, PostgreSQL schema, Redis caching strategy +# Step 5: Generate executable tasks (5 minutes) +/speckit.tasks +# Creates: tasks.md with phase-by-phase breakdown, task dependencies, [P] parallel markers # This automatically creates: # - specs/003-chat-system/plan.md # - specs/003-chat-system/research.md (WebSocket library comparisons) @@ -141,12 +391,24 @@ Total: ~12 hours of documentation work # - specs/003-chat-system/contracts/ (WebSocket events, REST endpoints) # - specs/003-chat-system/quickstart.md (Key validation scenarios) # - specs/003-chat-system/tasks.md (Task list derived from the plan) + +# Step 6: Analyze for consistency (5 minutes) +/speckit.analyze +# Validates: all requirements mapped to tasks, no ambiguous terms remain +# Reports: coverage %, critical issues before implementation + +# Step 7: Execute implementation (ongoing) +/speckit.implement +# Executes: tasks in order, enforces test-first, validates checklist completion ``` -In 15 minutes, you have: +In under an hour, you get: +- Constitutional principles established and enforced across all templates - A complete feature specification with user stories and acceptance criteria - A detailed implementation plan with technology choices and rationale +- Executable tasks with dependencies and parallelization markers +- Requirement quality validated through checklists (security, API, UX) - API contracts and data models ready for code generation - Comprehensive test scenarios for both automated and manual testing - All documents properly versioned in a feature branch