docs: address review feedback on accuracy and scope

- quickstart: correct the git/feature note — resolution reads
  .specify/feature.json / SPECIFY_FEATURE, not the checked-out branch,
  so switching branches alone does not switch the active feature.
- quickstart + agentic-sdd: add an invocation-style note ($speckit-* for
  Codex/ZCode, /skill:speckit-* for Kimi) so the agent-neutral commands
  are executable everywhere.
- agentic-sdd: fix the tasks phase structure to match the generator
  (Setup, Foundational, one phase per user story, final Polish; tests
  optional within user-story phases).
- index: soften the catalog claim (catalogs curate discovery, not an
  install allow-list) and relabel the "CLI reference" link to "Reference"
  to match the retitled, broader page.

Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9d9232f8-ece4-4aa6-a9bd-ff8d74ca1c89

Author: mnriem

docs/index.md

@@ -64,12 +64,12 @@ Including entirely different SDD processes:
 
 ### Integrate into your organization
 
-Works offline, behind firewalls, and on **Windows, macOS, and Linux**. Host your own catalogs so your organization controls what integrations, extensions, presets, workflows, and bundles get installed.
+Works offline, behind firewalls, and on **Windows, macOS, and Linux**. Host your own catalogs to curate what integrations, extensions, presets, workflows, and bundles your organization discovers and recommends.
 
 Community extensions like CI Guard and Architecture Guard add compliance gates and governance that fit the way your team already works.
 
 <a href="install/air-gapped.md" class="pillar-link">Enterprise / Air-Gapped →</a>&nbsp;&nbsp;
-<a href="reference/overview.md" class="pillar-link">CLI reference →</a>
+<a href="reference/overview.md" class="pillar-link">Reference →</a>
 
 </div>
 

docs/quickstart.md

@@ -5,10 +5,13 @@ This guide will help you get started with Spec-Driven Development using Spec Kit
 > [!NOTE]
 > Automation scripts are provided as both Bash (`.sh`) and PowerShell (`.ps1`) variants. The `specify` CLI auto-selects based on your OS unless you pass `--script sh|ps`.
 
+> [!NOTE]
+> Commands are shown here in `/speckit.*` form, but the exact invocation depends on your agent. Some skills-based agents use `$speckit-*` (e.g. Codex, ZCode) or `/skill:speckit-*` (e.g. Kimi). Use whichever form your agent exposes — the steps are otherwise identical.
+
 ## Recommended Process
 
 > [!TIP]
-> **Context Awareness**: Spec Kit tracks the active feature through the feature directory it creates (recorded in `.specify/feature.json`), so commands know which specification you're working on — no Git required. Prefer a branch-per-feature process? Install the opt-in **git** extension to get feature branches (e.g. `001-feature-name`) and switch specifications by switching branches.
+> **Context Awareness**: Spec Kit tracks the active feature through the feature directory it creates (recorded in `.specify/feature.json`), so commands know which specification you're working on — no Git required. Want numbered feature branches? Install the opt-in **git** extension: creating a branch (e.g. `001-feature-name`) also sets that branch's feature as active. Note that resolution reads `.specify/feature.json` / the `SPECIFY_FEATURE` variable, not the checked-out branch — so to switch back to another feature, set `SPECIFY_FEATURE` (or its state file) explicitly rather than relying on `git checkout` alone.
 
 After installing Spec Kit, each command below is a step in the process. Two paths are common:
 

docs/reference/agentic-sdd.md

@@ -4,6 +4,9 @@ The `/speckit.*` slash commands drive the core Spec-Driven Development (SDD) pro
 
 The commands are designed to run in order, but only `/speckit.specify` is strictly required before `/speckit.plan`. The clarify, checklist, and analyze commands are quality gates you add for anything with meaningful ambiguity.
 
+> [!NOTE]
+> Commands are written in `/speckit.*` form throughout this page. The exact invocation depends on your agent — some skills-based agents use `$speckit-*` (e.g. Codex, ZCode) or `/skill:speckit-*` (e.g. Kimi). Substitute the form your agent exposes.
+
 ```text
 /speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.plan -> /speckit.checklist -> /speckit.tasks -> /speckit.analyze -> /speckit.implement -> /speckit.converge
 ```
@@ -60,7 +63,7 @@ Review the generated checklist. If it surfaces gaps, loop back to `/speckit.clar
 
 ## `/speckit.tasks`
 
-Generates an actionable, dependency-ordered `tasks.md` from the design artifacts. Tasks are grouped into phases (setup, tests, core, integration, polish) and marked for parallel execution where possible.
+Generates an actionable, dependency-ordered `tasks.md` from the design artifacts. Tasks are organized into phases: **Setup**, **Foundational** (blocking prerequisites), then **one phase per user story** in priority order, and a final **Polish** phase for cross-cutting concerns. Tests are generated within a user story's phase when requested rather than as a separate phase, and tasks are marked for parallel execution where possible.
 
 ```text
 /speckit.tasks