docs: run /speckit.checklist after /speckit.plan in quickstart

[jawwad-ali]

Description

Closes #2606.

The quickstart showed /speckit.checklist before /speckit.plan, while the CLI's own next-steps panel (src/specify_cli/commands/init.py) describes the checklist as running after the plan. #2606 flagged this docs-vs-CLI contradiction.

The maintainer already settled the direction on the (closed) PR #2816:

The docs were actually wrong here. The checklists are meant as "unit tests but then in English" which means they are meant for after plan. So what we need to update is the docs.

This PR aligns the docs to the CLI (which is correct) by moving /speckit.checklist to after /speckit.plan in docs/quickstart.md:

• the workflow diagram (… -> /speckit.clarify -> /speckit.plan -> /speckit.checklist -> /speckit.tasks -> …),
• the prose describing the quality gates (checklist now validates quality "once the plan exists"),
• the first walkthrough (the checklist step now follows the plan step), and
• the Taskify walkthrough (Step 4 is now Generate Plan, Step 5 is Validate the Spec).

/speckit.clarify stays before planning (matches the CLI). Docs-only — no CLI, behavior, or output change.

Testing

• Tested locally with uv run specify --help (exit 0)

• Ran existing tests with uv sync && uv run pytest (N/A — docs-only change, no Python touched)

• Tested with a sample project (N/A)

• npx markdownlint-cli2 docs/quickstart.md — 0 errors

• git diff --check — clean

• Verified the rendered ordering now matches the CLI next-steps text in commands/init.py (clarify before plan; checklist after plan; analyze after tasks).

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (describe below)

Prepared with Claude Code (Claude Opus 4.8) under my direction. AI cross-checked the docs against the CLI next-steps source and the maintainer's direction on #2816, made the edits, and ran markdownlint. I reviewed the diff and confirmed the new ordering matches the CLI before submitting. I'll disclose if any review responses are AI-assisted as well.

[Copilot]

Pull request overview

This PR resolves the docs-vs-CLI contradiction around when to run /speckit.checklist by updating the Quick Start workflow so the checklist step comes after /speckit.plan, matching the CLI’s intended next-steps guidance.

Changes:

• Reordered the Recommended Workflow diagram to place /speckit.checklist after /speckit.plan.
• Updated the “quality gates” prose to describe checklist usage after a plan exists.
• Reordered both walkthroughs so the plan step precedes the checklist validation step.

Show a summary per file

File	Description
docs/quickstart.md	Moves /speckit.checklist to after /speckit.plan across the workflow diagram, explanatory prose, and both walkthroughs to align docs with CLI guidance.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 1/1 changed files
• Comments generated: 2

[jawwad-ali]

Addressed both Copilot comments in 16acb01 — reworded so /speckit.checklist reads as generating quality checklists (which then validate the requirements) rather than performing validation directly, matching the CLI/README phrasing, while keeping the after-/speckit.plan ordering:

• Line 19: "…to generate quality checklists for the requirements once the plan exists…"
• First walkthrough: "Then generate a quality checklist with /speckit.checklist once the plan exists:"

npx markdownlint-cli2 docs/quickstart.md → 0 errors.

Disclosure: this update and comment were prepared with Claude Code (Claude Opus 4.8) under my direction; I reviewed the changes before pushing.

[Copilot]

Copilot's findings

• Files reviewed: 1/1 changed files
• Comments generated: 3

[jawwad-ali]

Thanks — addressed all three in a48da73, aligning the wording with the CLI next-steps text:

• Line 19 — now states the purpose and anchors the ordering: "/speckit.checklist (after /speckit.plan) to generate quality checklists that validate requirements completeness, clarity, and consistency".
• Line 86 — pluralized to "generate quality checklists".
• Taskify step — "Generate quality checklists to validate the specification using the /speckit.checklist command" (the spec is validated using the generated checklists).

npx markdownlint-cli2 docs/quickstart.md → 0 errors.

Disclosure: prepared with Claude Code (Claude Opus 4.8) under my direction; reviewed before pushing.

[Copilot]

Copilot's findings

• Files reviewed: 1/1 changed files
• Comments generated: 0 new

[mnriem]

Please address test & lint errors. You might have to pull in upstream/main

[jawwad-ali]

Rebased onto the latest main (head now b541db6). The failing check was tests/test_agent_config_consistency.py::test_issue_template_agent_lists_match_runtime_integrations reporting missing AGENT_CONFIG keys: ['firebender'] — unrelated to this docs change; the branch predated #3116 ("sync Firebender agent lists"), which adds firebender to the issue templates. After pulling main in, that test passes locally and npx markdownlint-cli2 docs/quickstart.md reports 0 errors. The quickstart edits (checklist after plan) are unchanged.