docs: simplify README around three processes

CONTRIBUTING.md

@@ -11,7 +11,7 @@ These are one time installations required to be able to test your changes locall
 1. Install [Python 3.11+](https://www.python.org/downloads/)
 1. Install [uv](https://docs.astral.sh/uv/) for package management
 1. Install [Git](https://git-scm.com/downloads)
-1. Have an [AI coding agent available](README.md#-supported-ai-coding-agent-integrations)
+1. Have an [AI coding agent available](https://github.github.io/spec-kit/reference/integrations.html)
 
 <details>
 <summary><b>💡 Hint if you are using <code>VSCode</code> or <code>GitHub Codespaces</code> as your IDE</b></summary>
@@ -151,6 +151,27 @@ Including the issue or PR number makes branches traceable — especially useful
 
 ## Development workflow
 
+### Does Spec Kit use Spec Kit?
+
+Yes — we dogfood Spec Kit while developing Spec Kit, especially for substantial
+features and changes to the development workflow. Contributors are asked to test
+relevant changes through the Spec-Driven Development commands. The
+[feature assessment workflow](https://github.com/github/spec-kit/blob/main/.github/workflows/feature-assess.md)
+is currently the automated dogfooding path: its setup uses the CLI from the
+current checkout to initialize Copilot and install the `assess` extension, after
+which Copilot follows the generated assessment skills against feature requests.
+The other agentic workflows currently operate independently of the Specify CLI.
+
+This does not mean every change goes through the full workflow. Small fixes can
+use the normal issue, pull request, review, and test process. Dogfooding
+scaffolding and artifacts under `.github/agents/`, `.github/prompts/`,
+`.github/copilot-instructions.md`, `.grok/`, `.specify/`, and `specs/` are
+intentionally gitignored. The automated assessment workflow is ephemeral and
+neither commits nor pushes its generated Copilot skills, so its output does not
+enter repository history.
+
+### Workflow expectations
+
 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

docs/README.md

@@ -27,7 +27,11 @@ To build the documentation locally:
 - `index.md` - Main documentation homepage
 - `toc.yml` - Table of contents configuration
 - `installation.md` - Installation guide
-- `quickstart.md` - Quick start guide
+- `quickstart.md` - Spec-Driven Development walkthrough
+- `guides/bugfix.md` - Bug-fixing walkthrough
+- `guides/assessment.md` - Idea assessment walkthrough
+- `guides/customization.md` - Choosing and combining customization building blocks
+- `reference/agentic-*.md` - Detailed process command references
 - `_site/` - Generated documentation output (ignored by git)
 
 ## Deployment

docs/community/overview.md

@@ -2,6 +2,10 @@
 
 The Spec Kit community builds extensions, presets, bundles, walkthroughs, and companion projects that expand what you can do with Spec-Driven Development. All community contributions are independently created and maintained by their respective authors.
 
+> [!NOTE]
+> Review community source code before installation and use it at your own
+> discretion. A catalog listing is not an audit or endorsement.
+
 ## Extensions
 
 Extensions add new capabilities to Spec Kit — domain-specific commands, external tool integrations, quality gates, and more. Over 130 community extensions are available from 70+ authors, covering everything from accessibility governance to multi-agent orchestration.
@@ -31,3 +35,11 @@ Step-by-step guides that show Spec-Driven Development in action across different
 Community projects that extend, visualize, or build on Spec Kit — including VS Code extensions, Claude Code plugins, and more.
 
 [Browse friend projects →](friends.md)
+
+## Contribute a component
+
+To publish your own work, follow the
+[Extension Publishing Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md),
+the [Presets Publishing Guide](https://github.com/github/spec-kit/blob/main/presets/PUBLISHING.md),
+or the [Community Bundles guide](bundles.md). For help choosing a component type,
+see [Customize Spec Kit](../guides/customization.md).

docs/guides/assessment.md

@@ -0,0 +1,115 @@
+# Idea Assessment Quickstart
+
+Use this process to decide whether an idea deserves investment before committing
+to a solution. It works for software ideas and non-software decisions alike.
+No existing source code is required.
+
+The bundled, opt-in **assess** extension provides five stages:
+**intake → research → define → shape → decide**. The result is an evidence-backed
+`go`, `needs-clarification`, or `kill` decision, not an implementation.
+
+## Set up
+
+[Install Spec Kit and initialize a project](../installation.md). An empty project
+is enough, or you can use an
+[existing repository](existing-projects.md) when the idea relates to its code.
+In a terminal at the initialized project root, install the extension:
+
+```bash
+specify extension add assess
+```
+
+Then launch your coding agent in that directory. The examples below use
+GitHub Copilot's default skills mode (`--integration copilot`). Other agents
+use their own
+[command invocation syntax](../reference/integrations.md#command-invocation).
+Invoke each `/speckit-assess-*` skill separately in your agent's chat, reviewing
+the artifact before moving on. These are agent skills, not terminal commands;
+the terminal command above only installs the extension.
+
+## 1. Capture the idea
+
+```text
+/speckit-assess-intake "Let users work offline and sync when they reconnect." slug=offline-mode
+```
+
+You can also supply a URL, ticket, or codebase pointer. The agent captures the
+input in `.specify/assessments/offline-mode/intake.md`.
+The slug is the shared handle for all five stages.
+
+## 2. Research the evidence
+
+```text
+/speckit-assess-research slug=offline-mode
+```
+
+The agent gathers supporting and opposing evidence in `research.md`. Review
+sources and confidence levels: uncited assumptions are not established facts.
+This stage should challenge the idea, not just build a case for it.
+
+## 3. Define the problem
+
+```text
+/speckit-assess-define slug=offline-mode
+```
+
+The agent writes `problem.md`, describing the affected users, problem, goals,
+non-goals, success metrics, and cost of doing nothing.
+
+## 4. Shape possible solutions
+
+```text
+/speckit-assess-shape slug=offline-mode
+```
+
+The agent compares concept-level options, constraints, appetite, and trade-offs
+in `concept.md`. Detailed architecture, implementation tasks, and source changes
+are deliberately outside this process.
+
+## 5. Make the decision
+
+```text
+/speckit-assess-decide slug=offline-mode
+```
+
+The agent records the scorecard, rationale, and verdict in `decision.md`.
+
+| Verdict | What it means | What to do |
+| --- | --- | --- |
+| `go` | The problem and evidence are adequate and a concept is recommended | Decide whether to act; optionally hand a software idea to SDD |
+| `needs-clarification` | Specific unknowns still block a defensible decision | Refine the affected artifacts with the missing information |
+| `kill` | The idea is not worth pursuing now | Keep the recorded rationale; stopping is a successful outcome |
+
+All five artifacts live under `.specify/assessments/offline-mode/`. None of the
+assessment commands modify source code.
+
+## Resolve unknowns by refining the artifacts
+
+The usual flow runs each command once. When an artifact contains
+`[NEEDS CLARIFICATION: ...]`, edit that Markdown file directly or ask the agent
+in free-form chat to incorporate the missing information:
+
+```text
+Update .specify/assessments/offline-mode/problem.md with these confirmed success metrics: <your metrics>. Update any dependent wording and revise decision.md if this resolves the blocker. Preserve source and confidence tags.
+```
+
+Do not automatically regenerate the entire stage. Ask the agent to review
+whether the new facts clear the blocker and revise the downstream scorecard,
+verdict, or handoff accordingly. Rerunning a command is an exception, such as
+replacing a discarded draft, and existing artifacts must not be overwritten
+without confirmation.
+
+## Optional handoff to SDD
+
+Assessment is standalone: it does not automatically invoke SDD or insert itself
+into the specification process. If you choose to build a software idea with a
+`go` verdict, establish your project constitution if needed, then pass the
+decision's handoff summary to the specification command:
+
+```text
+/speckit-specify Use the handoff summary in .specify/assessments/offline-mode/decision.md to specify the approved offline-mode concept.
+```
+
+Continue with the [SDD quickstart](../quickstart.md). For stage prerequisites,
+slug rules, and evidence requirements, see the
+[idea assessment command reference](../reference/agentic-assessment.md).

docs/guides/bugfix.md

@@ -0,0 +1,82 @@
+# Bug Fixing Quickstart
+
+Use this process when existing behavior is broken and you need an evidence-based
+diagnosis, a scoped repair, and verification against the original report. You do
+not need to run the SDD feature workflow first.
+
+The bundled, opt-in **bug** extension separates the work into
+**assess → fix → test**. Each bug gets a directory under
+`.specify/bugs/<slug>/` containing the diagnosis, change record, and test results.
+
+## Set up
+
+First [install Spec Kit](../installation.md) and initialize the repository that
+contains the bug. If it already contains code, follow
+[Adopting Spec Kit in an Existing Project](existing-projects.md).
+
+In a terminal at the initialized project root, install the extension:
+
+```bash
+specify extension add bug
+```
+
+Then launch your coding agent in that directory. The examples below use
+GitHub Copilot's default skills mode (`--integration copilot`). Other agents
+expose the same steps using their own
+[command invocation syntax](../reference/integrations.md#command-invocation).
+Invoke each `/speckit-bug-*` skill separately in your agent's chat and review its
+output before continuing. These are agent skills, not terminal commands; the
+terminal command above only installs the extension.
+
+## 1. Assess the bug
+
+Provide the symptom, reproduction steps, and expected behavior. A GitHub issue
+URL or stack trace also works. Choose a short, reusable name for the bug:
+
+```text
+/speckit-bug-assess "Submitting the login form with an empty password crashes the app instead of showing a validation error." slug=login-crash
+```
+
+The agent investigates the code and writes
+`.specify/bugs/login-crash/assessment.md`. It does not change source code.
+Review the diagnosis and proposed remediation before asking for a fix; do not
+proceed with an unsupported diagnosis or a report that is not a bug.
+
+## 2. Fix the assessed cause
+
+Use the same slug:
+
+```text
+/speckit-bug-fix slug=login-crash
+```
+
+The agent applies the assessed remediation and records the changes in
+`.specify/bugs/login-crash/fix.md`. This is the only stage that edits source
+code. If new evidence requires work outside the assessed scope, the agent must
+record that deviation rather than silently expanding the repair.
+
+## 3. Test the fix
+
+```text
+/speckit-bug-test slug=login-crash
+```
+
+The agent re-runs the reproduction and relevant tests, then writes
+`.specify/bugs/login-crash/test.md`. This stage records evidence; it does not
+edit source code to make a failing test pass.
+
+| Verdict | Meaning | What to do |
+| --- | --- | --- |
+| `verified` | The verification requirements were exercised successfully | Review the patch and evidence before merging |
+| `partial` | Some verification could not be completed | Supply the missing environment or reproduction evidence and test again |
+| `failed` | Verification found a remaining problem | Revisit the diagnosis or fix using that evidence, then test again |
+
+A passing test suite alone is not enough if the original reproduction was never
+exercised. Keep the assessment, fix record, and test report together so a reviewer
+can trace the repair from symptom to evidence.
+
+## Learn more
+
+- [Bug command reference](../reference/agentic-bugfix.md): arguments, slug handling, and output contracts.
+- [SDD quickstart](../quickstart.md): use this when the work is a new feature rather than a repair.
+- [Idea assessment quickstart](assessment.md): investigate whether a proposed change is worth pursuing.

docs/guides/customization.md

@@ -0,0 +1,105 @@
+# Customize Spec Kit
+
+The three first-party processes are starting points, not limits. Keep the
+built-in SDD process, add bug fixing or assessment, adapt a process to your
+organization, or bring a different process entirely.
+
+## Choose the right building block
+
+| Goal | Use |
+| --- | --- |
+| Add a new command, capability, or process | Extension |
+| Integrate an external tool or service | Extension |
+| Change the format or terminology of specs, plans, or tasks | Preset |
+| Enforce organizational or regulatory standards in existing templates | Preset |
+| Ship reusable domain-specific templates | Presets for overrides; extensions for templates accompanying new commands |
+| Make a one-off template adjustment in a single project | Project-local override |
+| Automate a multi-step process | Workflow |
+| Provision a complete role-based setup in one operation | Bundle |
+
+## Extensions: add capabilities
+
+Extensions expand **what Spec Kit can do** through commands, templates, scripts,
+and hooks. They can add domain-specific processes, external integrations, or
+development phases beyond the core.
+
+```bash
+specify extension search
+specify extension add <extension-name>
+```
+
+Examples include Jira integration, post-implementation code review, V-Model test
+traceability, and project health diagnostics. The bundled
+[bug](bugfix.md) and [assess](assessment.md) extensions are first-party examples.
+Browse [community extensions](../community/extensions.md), or use the
+[extension reference](../reference/extensions.md) for management and configuration.
+
+## Presets: change how a process works
+
+Presets override templates and commands supplied by the core **and by installed
+extensions**. They customize the artifacts and instructions produced without
+requiring new tooling.
+
+```bash
+specify preset search
+specify preset add <preset-name>
+```
+
+Use a preset to require regulatory traceability, enforce test-first task ordering,
+add security review gates to plans, or localize a workflow. Presets can also adapt
+the methodology to Agile, Kanban, Waterfall, jobs-to-be-done, or domain-driven
+design. The
+[pirate-speak demo](https://github.com/mnriem/spec-kit-pirate-speak-preset-demo)
+illustrates how extensively the terminology can change.
+
+Multiple presets can be stacked with priorities. See
+[community presets](../community/presets.md) for examples and the
+[preset reference](../reference/presets.md) for installation, composition
+strategies, and precedence.
+
+## Project-local overrides and resolution
+
+For a one-off project customization, place a template override in
+`.specify/templates/overrides/` rather than creating a reusable preset.
+The default replacement order is:
+
+1. Project-local overrides.
+2. Installed presets, in priority order.
+3. Installed extensions, in priority order.
+4. Spec Kit core templates in `.specify/templates/`.
+
+Templates are resolved when needed, using the first match by default.
+Commands are different: installing extensions or presets materializes command
+files into the active integration's directory. Agents do not re-resolve that
+stack every time they invoke a command. Removing an overriding component
+restores the surviving command layer through reconciliation.
+
+With no customizations, the core defaults apply. The
+[file resolution reference](../reference/presets.md#file-resolution) is the
+authoritative guide to paths, priorities, and prepend/append/wrap composition.
+
+## Bundles: role-based setups
+
+A bundle packages a curated set of extensions, presets, workflows, and workflow
+steps as one versioned setup for a role or team. Its `bundle.yml` manifest pins
+components and may target an integration; an integration-agnostic bundle inherits
+the project's active integration.
+
+```bash
+specify bundle search
+specify bundle info <bundle-id>
+specify bundle install <bundle-id>
+```
+
+Inspect `info` before installing to see the resolved component set. See the
+[bundle reference](../reference/bundles.md) for updates, removal, catalog policies,
+offline limitations, validation, and publishing, and the
+[example manifests](https://github.com/github/spec-kit/tree/main/examples/bundles)
+for product manager, business analyst, security researcher, and developer setups.
+
+## Share your customizations
+
+Community components are independently maintained. Review source code before
+installation and use it at your own discretion. Visit the
+[community guide](../community/overview.md) to discover components or publish your
+own, and the [workflow reference](../reference/workflows.md) to automate a process.

docs/guides/existing-projects.md

@@ -33,6 +33,12 @@ specifications for existing behavior.
 
 ## 2. Capture Project Guardrails
 
+The remaining steps illustrate adopting **SDD** for a bounded feature. If your
+first task is a repair, you can instead follow the
+[bug-fixing quickstart](bugfix.md) after initialization; to evaluate a proposal,
+use the [idea assessment quickstart](assessment.md). Neither process requires
+completing the SDD steps below first.
+
 Run `/speckit.constitution` with principles that are already true for the
 repository or that the team has explicitly agreed to adopt:
 
@@ -49,7 +55,7 @@ so unrealistic rules create noise instead of useful constraints.
 
 ## 3. Choose a Bounded First Change
 
-Start with a feature, bug fix, or modernization slice that can be reviewed
+Start with a feature or modernization slice that can be reviewed
 independently. Do not make "document the entire existing system" your first
 feature unless that inventory is itself the intended deliverable.