From 0e32149ec7b0eaea86bdfd5f8964b5ec57c2c12f Mon Sep 17 00:00:00 2001 From: Ashley Childress <6563688+anchildress1@users.noreply.github.com> Date: Thu, 16 Oct 2025 04:33:27 -0400 Subject: [PATCH 1/8] docs: Add guide for using Spec-Kit in existing projects - Add comprehensive guide for integrating Spec-Kit into existing codebases - Include step-by-step workflow from installation to implementation - Update documentation table of contents to include new guide - Provide troubleshooting section and cross-references to other docs Generated-by: ChatGPT Co-authored-by: GitHub Copilot Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com> --- docs/existing-project-guide.md | 175 +++++++++++++++++++++++++++++++++ docs/toc.yml | 3 +- 2 files changed, 177 insertions(+), 1 deletion(-) create mode 100644 docs/existing-project-guide.md diff --git a/docs/existing-project-guide.md b/docs/existing-project-guide.md new file mode 100644 index 000000000..48479bf1c --- /dev/null +++ b/docs/existing-project-guide.md @@ -0,0 +1,175 @@ +# 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 realistic scope; save the grand redesign 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 your repo 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 + +Your agent now recognizes: + +- `/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. + +> 💡 Use a model that can handle systems‑level reasoning. Don’t pick a tiny “mini” model for a brand‑new UI. Things will *not go well*. 😉 +> This is a 10‑minute starter, so pick something achievable—save the joyrides until your constraints file is done! + +```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; rerun 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/toc.yml b/docs/toc.yml index 082bb8c86..6e4f119e4 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -9,10 +9,11 @@ href: installation.md - name: Quick Start href: quickstart.md + - name: Existing Project Guide + href: existing-project-guide.md # Development workflows - name: Development items: - name: Local Development href: local-development.md - From c69f5d1ffefbe0776f17ac9b70025c23aa037330 Mon Sep 17 00:00:00 2001 From: Ashley Childress <6563688+anchildress1@users.noreply.github.com> Date: Fri, 17 Oct 2025 01:28:28 -0400 Subject: [PATCH 2/8] docs: Enhance quickstart guide with clarifications and examples - Add step-by-step explanations for each phase of the workflow - Include constitution step in detailed example for complete process - Add cross-references to related documentation guides - Improve navigation between new project and existing project workflows Generated-by: GitHub Copilot Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com> --- docs/quickstart.md | 42 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 34 insertions(+), 8 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 0ad5f6e3c..868ae23d9 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 @@ -22,6 +28,8 @@ uvx --from git+https://github.com/github/spec-kit.git specify init Date: Fri, 17 Oct 2025 21:38:06 -0400 Subject: [PATCH 3/8] docs(spec-driven): add detailed /speckit command reference - Add detailed usage, inputs, and examples for the /speckit command suite. - Improve example workflow and timing estimates to reflect added commands. - Clarify expected outputs and propagation behavior to templates and memory. - Minor editorial and formatting fixes in spec-driven.md. Generated-by: GitHub Copilot Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com> --- spec-driven.md | 293 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 277 insertions(+), 16 deletions(-) diff --git a/spec-driven.md b/spec-driven.md index 13edc9e3f..d3a3d1cbf 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -74,6 +74,36 @@ The key is treating specifications as the source of truth, with code as the gene The SDD methodology is significantly enhanced through three powerful commands that automate the specification → planning → tasking workflow: +### The `/speckit.constitution` Command + +This command creates or updates your project's architectural constitution, establishing the immutable principles that govern all implementations: + +**Core Value**: Provides architectural stability and consistency across time and team members, ensuring every feature reinforces rather than undermines your system's design principles. + +**Benefits**: +- Defines non-negotiable rules (like "library-first" or "test-first" imperatives) +- Automatically propagates constitutional changes to all dependent templates +- Maintains version history of architectural decisions +- Prevents over-engineering through explicit simplicity and anti-abstraction gates +- Ensures AI-generated code follows consistent architectural patterns + +**Expected Input:** + +- Define your project's core architectural principles +- Establish non-negotiable rules that govern all implementations +- Set simplicity thresholds and quality gates specific to your domain + +**Minimal usage** (provide your project's principles): + +```markdown +/speckit.constitution +Library-first: every feature begins as standalone library +Test-first: no code before tests +Simplicity gate: max 3 projects per feature +``` + +> 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:** -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 +- 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): + +```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: + +**Core Value**: Transforms your specification documents into working code through systematic, phase-by-phase execution that maintains quality at every step. -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 +**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 about 20 minutes, you have: +- 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 @@ -401,4 +663,3 @@ By embedding these principles into the specification and planning process, SDD e This isn't about replacing developers or automating creativity. It's about amplifying human capability by automating mechanical translation. It's about creating a tight feedback loop where specifications, research, and code evolve together, each iteration bringing deeper understanding and better alignment between intent and implementation. Software development needs better tools for maintaining alignment between intent and implementation. SDD provides the methodology for achieving this alignment through executable specifications that generate code rather than merely guiding it. - From 87b71cd86f6bfcd389a36a017959496bc71d8b1f Mon Sep 17 00:00:00 2001 From: Ashley Childress <6563688+anchildress1@users.noreply.github.com> Date: Fri, 17 Oct 2025 22:00:16 -0400 Subject: [PATCH 4/8] docs(existing-project-guide): normalize hyphen usage - Replace non-standard hyphens in title, workspace sentence, and troubleshooting table - Improve consistency with repository docs Assisted-by: GitHub Copilot Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com> --- docs/existing-project-guide.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/existing-project-guide.md b/docs/existing-project-guide.md index 48479bf1c..12b53a17e 100644 --- a/docs/existing-project-guide.md +++ b/docs/existing-project-guide.md @@ -1,6 +1,6 @@ -# Using Spec‑Kit in an Existing Project +# 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 realistic scope; save the grand redesign for later. +> 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 realistic scope; save the grand redesign for later. --- @@ -16,7 +16,7 @@ Install the CLI by following the [Installation Guide](installation.md), then jum ## 2. Init -> Spec‑Kit initializes a **workspace** in your repo and registers **slash commands** with your coding agent. This workspace holds your **specs, plans, and tasks**. +> Spec-Kit initializes a **workspace** in your repo 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. @@ -81,7 +81,7 @@ Out of scope: stacking, gift cards, loyalty. ### Checkpoint -* Spec‑Kit automatically creates and checks out a **feature branch**, e.g. `001-checkout-apply-coupon`. +* 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.** @@ -159,12 +159,12 @@ If your org enforces separation, use **two commits:** (1) specs + plan + tasks, ## 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; rerun plan / tasks | +| 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 | --- From 787340d56348b1f8cd4c5c64448d8b310a5cbe48 Mon Sep 17 00:00:00 2001 From: Ashley Childress <6563688+anchildress1@users.noreply.github.com> Date: Fri, 17 Oct 2025 22:22:34 -0400 Subject: [PATCH 5/8] docs(existing-project-guide): normalize hyphenation and punctuation - Replace non-breaking hyphens with standard hyphens in `docs/existing-project-guide.md`. - Fix spacing and punctuation for the "10-minute guide" phrasing. - Keep changes minimal and localized to documentation style. Assisted-by: GitHub Copilot Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com> --- docs/existing-project-guide.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/existing-project-guide.md b/docs/existing-project-guide.md index 12b53a17e..8972c7ee7 100644 --- a/docs/existing-project-guide.md +++ b/docs/existing-project-guide.md @@ -1,6 +1,6 @@ # 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 realistic scope; save the grand redesign for later. +> 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 realistic scope; save the grand redesign for later. --- @@ -27,7 +27,7 @@ Install the CLI by following the [Installation Guide](installation.md), then jum specify init --here --ai copilot ``` -### B) If you used uvx one‑shot +### B) If you used uvx one-shot ```bash uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai copilot @@ -49,13 +49,13 @@ Your agent now recognizes: ## 3. Constitution -Use the `/speckit.constitution` command to define the project's non‑negotiable rules and constraints that AI must follow. +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. +> 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%. +- 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. ``` @@ -64,10 +64,10 @@ Use the `/speckit.constitution` command to define the project's non‑negotiable ## 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. +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. -> 💡 Use a model that can handle systems‑level reasoning. Don’t pick a tiny “mini” model for a brand‑new UI. Things will *not go well*. 😉 -> This is a 10‑minute starter, so pick something achievable—save the joyrides until your constraints file is done! +> 💡 Use a model that can handle systems-level reasoning. Don’t pick a tiny “mini” model for a brand-new UI. Things will *not go well*. 😉 +> This is a 10-minute starter, so pick something achievable—save the joyrides until your constraints file is done! ```markdown /speckit.specify Create story “Apply coupon during checkout.” @@ -92,7 +92,7 @@ Out of scope: stacking, gift cards, loyalty. 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. +/speckit.clarify Tighten ACs: add duplicate-apply and expired-coupon edge cases. ``` Repeat until you’re satisfied — this shapes **the plan**. @@ -164,7 +164,7 @@ If your org enforces separation, use **two commits:** (1) specs + plan + tasks, | 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 | +| Implement touches unrelated files | Spec / plan too vague | Tighten scope; add explicit constraints / out-of-scope; re-run plan / tasks | --- From 0b1949202d4e7eda0215cb8fec1daf5bee1dc4ef Mon Sep 17 00:00:00 2001 From: Ashley Childress <6563688+anchildress1@users.noreply.github.com> Date: Sun, 19 Oct 2025 13:54:35 -0400 Subject: [PATCH 6/8] docs: normalize "Spec Kit" naming and fix minor formatting - Normalize product name to 'Spec Kit' in `CONTRIBUTING.md` and `docs/existing-project-guide.md`. - Fix minor formatting: blockquote spacing, list indentation, and trailing newline. Commit-generated-by: GitHub Copilot Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com> --- CONTRIBUTING.md | 5 ++--- docs/existing-project-guide.md | 10 +++++----- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 928949154..a20557cca 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 @@ -125,4 +125,3 @@ Please be respectful to maintainers and disclose AI assistance. - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) - [Using Pull Requests](https://help.github.com/articles/about-pull-requests/) - [GitHub Help](https://help.github.com) - diff --git a/docs/existing-project-guide.md b/docs/existing-project-guide.md index 8972c7ee7..54c73ff54 100644 --- a/docs/existing-project-guide.md +++ b/docs/existing-project-guide.md @@ -1,12 +1,12 @@ -# Using Spec-Kit in an Existing Project +# 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 realistic scope; save the grand redesign for later. +> 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 realistic scope; save the grand redesign for later. --- ## 1. Prerequisites -Before starting, you need the Spec-Kit CLI tool installed on your machine. +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. @@ -16,7 +16,7 @@ Install the CLI by following the [Installation Guide](installation.md), then jum ## 2. Init -> Spec-Kit initializes a **workspace** in your repo and registers **slash commands** with your coding agent. This workspace holds your **specs, plans, and tasks**. +> Spec Kit initializes a **workspace** in your repo 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. @@ -81,7 +81,7 @@ Out of scope: stacking, gift cards, loyalty. ### Checkpoint -* Spec-Kit automatically creates and checks out a **feature branch**, e.g. `001-checkout-apply-coupon`. +* 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.** From 5a322bcb97928ac89df2951c0ad9c8b9518c6589 Mon Sep 17 00:00:00 2001 From: Ashley Childress <6563688+anchildress1@users.noreply.github.com> Date: Sun, 19 Oct 2025 17:21:26 -0400 Subject: [PATCH 7/8] docs: add Copilot instructions shim and docs/AGENTS.md - Add a minimal Copilot Code Review instruction that references existing `AGENTS.md` files - Add `docs/AGENTS.md` for docs-specific agent guidance (tone, capitalization, argument formats) - The `copilot-instructions.md` file is designed to support auto-Copilot Code Reviews in GitHub - Existing `AGENTS.md` files remain unchanged and the authoritative source for project conventions Co-authored-by: GitHub Copilot Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com> --- .github/copilot-instructions.md | 6 ++++++ docs/AGENTS.md | 10 ++++++++++ 2 files changed, 16 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 docs/AGENTS.md 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/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. From 8202820f536a5ba0c620518bdb731937c1df31a5 Mon Sep 17 00:00:00 2001 From: Ashley Childress <6563688+anchildress1@users.noreply.github.com> Date: Sun, 19 Oct 2025 17:56:45 -0400 Subject: [PATCH 8/8] docs: clarify existing-project-guide and spec-driven timing - Correct timing for spec-driven development eliminating confusion - Minor wording improvements for clarity in existing-project-guide Co-authored-by: GitHub Copilot Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com> --- docs/existing-project-guide.md | 11 ++++++----- spec-driven.md | 2 +- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/existing-project-guide.md b/docs/existing-project-guide.md index 54c73ff54..906bcce50 100644 --- a/docs/existing-project-guide.md +++ b/docs/existing-project-guide.md @@ -1,6 +1,6 @@ # 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 realistic scope; save the grand redesign for later. +> 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. --- @@ -16,7 +16,7 @@ Install the CLI by following the [Installation Guide](installation.md), then jum ## 2. Init -> Spec Kit initializes a **workspace** in your repo and registers **slash commands** with your coding agent. This workspace holds your **specs, plans, and tasks**. +> 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. @@ -35,7 +35,7 @@ uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai c ### Checkpoint -Your agent now recognizes: +Spec Kit registers these slash commands in your coding agent: - `/speckit.constitution` - `/speckit.specify` @@ -66,8 +66,9 @@ Use the `/speckit.constitution` command to define the project's non-negotiable r 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. -> 💡 Use a model that can handle systems-level reasoning. Don’t pick a tiny “mini” model for a brand-new UI. Things will *not go well*. 😉 -> This is a 10-minute starter, so pick something achievable—save the joyrides until your constraints file is done! +> 💡 **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.” diff --git a/spec-driven.md b/spec-driven.md index d3a3d1cbf..6ee44b8bc 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -402,7 +402,7 @@ Simplicity gate: max 3 projects per feature # Executes: tasks in order, enforces test-first, validates checklist completion ``` -In about 20 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