docs: Add missing prompt commands + existing project walkthrough

.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.

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
@@ -122,7 +122,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
 

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.

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)

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 <PROJECT_NAME
 
 ### 2. Create the Spec
 
+Define your feature requirements in plain language—describe what users need and why, without worrying about implementation details or technical requirements. This should clearly state the goal in user-centric terms.
+
 Use the `/speckit.specify` command to describe what you want to build. Focus on the **what** and **why**, not the tech stack.
 
 ```bash
@@ -31,6 +39,8 @@ Use the `/speckit.specify` command to describe what you want to build. Focus on
 
 ### 3. Create a Technical Implementation Plan
 
+Translate your spec into concrete technical decisions—frameworks, databases, and architecture patterns.
+
 Use the `/speckit.plan` command to provide your tech stack and architecture choices.
 
 ```bash
@@ -39,12 +49,27 @@ Use the `/speckit.plan` command to provide your tech stack and architecture choi
 
 ### 4. Break Down and Implement
 
-Use `/speckit.tasks` to create an actionable task list, then ask your agent to implement the feature.
+Generate a step-by-step task list from your plan, then execute those tasks to build your feature.
+
+Use `/speckit.tasks` to create an actionable task list, then prompt your agent with `/speckit.implement` to execute the tasks.
+
+---
 
 ## Detailed Example: Building Taskify
 
 Here's a complete example of building a team productivity platform:
 
+### Step 0: Establish Project Principles (Recommended)
+
+Before creating features, use `/speckit.constitution` to define your project's governing principles:
+
+```text
+/speckit.constitution Establish core principles for this project:
+- Test-first development is mandatory - tests written and approved before implementation
+- API response times must stay under 200ms
+- Real integration tests over mocks - use actual database instances for testing
+```
+
 ### Step 1: Define Requirements with `/speckit.specify`
 
 ```text
@@ -102,10 +127,11 @@ Read through it with an eye on determining whether or not there is a sequence of
 to be doing that are obvious from reading this. Because I don't know if there's enough here.
 ```
 
-Finally, implement the solution:
+Finally, generate tasks and implement the solution:
 
 ```text
-implement specs/002-create-taskify/plan.md
+/speckit.tasks
+/speckit.implement 002-create-taskify
 ```
 
 ## Key Principles
@@ -118,6 +144,7 @@ implement specs/002-create-taskify/plan.md
 
 ## Next Steps
 
-- Read the complete methodology for in-depth guidance
-- Check out more examples in the repository
-- Explore the source code on GitHub
+- **Adding features to existing projects?** Use the [Existing Project Guide](existing-project-guide.md)
+- **Deep dive:** Read the [complete methodology](../spec-driven.md) for in-depth guidance
+- **Local development:** See [Local Development Guide](local-development.md) for CLI development workflows
+- **Troubleshooting:** Check the main [README troubleshooting section](../README.md#-troubleshooting)

docs/toc.yml

@@ -9,6 +9,8 @@
       href: installation.md
     - name: Quick Start
       href: quickstart.md
+    - name: Existing Project Guide
+      href: existing-project-guide.md
     - name: Upgrade
       href: upgrade.md