Readme clarity

[pchemguy]

Description

Improves clarity of README.md

AI Disclosure

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

[mnriem]

Please address changes

[Copilot]

Pull request overview

Improves README.md clarity by restructuring and expanding documentation around supported agents, available slash commands, and the Specify CLI reference.

Changes:

• Reformats the “Supported AI Agents” section into a cleaner markdown table.
• Moves/expands “Available Slash Commands” into its own section with core/optional command listings.
• Refactors the CLI reference and replaces the extensions/presets mermaid diagram with a priority table + bullets.

Comments suppressed due to low confidence (3)

README.md:321

• The CLI invocation signature shown as specify <COMMAND> <SUBCOMMAND> <OPTIONS> is misleading because several top-level commands (e.g., init, check, version) do not take a subcommand. Consider documenting this as specify <COMMAND> [<SUBCOMMAND>] [OPTIONS] or showing separate usage lines for commands with/without subcommands.

The `specify` tool is invoked as

specify

and supports the following commands:

README.md:330

• The “Commands” table omits the version top-level command even though it exists in the CLI (@app.command() def version() in src/specify_cli/__init__.py). Since this section says “supports the following commands”, the list should include version (and any other top-level commands) to avoid documenting an incomplete CLI surface.

| Command     | Description                                                                                                                                                                                                                                                                                                                                  |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `init`      | Initialize a new Specify project from the latest template.                                                                                                                                                                                                                                                                                   |
| `check`     | Check for installed tools: `git` plus all CLI-based agents configured in `AGENT_CONFIG` (for example: `claude`, `gemini`, `code`/`code-insiders`, `cursor-agent`, `windsurf`, `junie`, `qwen`, `opencode`, `codex`, `kiro-cli`, `shai`, `qodercli`, `vibe`, `kimi`, `iflow`, `pi`, etc.). This command does not have any additional options. |
| `extension` | Manage extensions                                                                                                                                                                                                                                                                                                                            |
| `preset`    | Manage presets                                                                                                                                                                                                                                                                                                                               |

README.md:449

• The template stack table has incorrect locations for presets and extensions: .specify/presets//templates/ and .specify/extensions//templates/ contain a double slash and are missing the <preset-id> / <ext-id> directory segment (compare to the surrounding text that previously used .specify/presets/<preset-id>/templates/ etc.). This should be corrected so the paths match the actual on-disk layout.

| Priority | Component Type                                    | Location                          |
| -------: | ------------------------------------------------- | --------------------------------- |
|      ⬆ 1 | Project-Local Overrides                           | `.specify/templates/overrides/`   |
|        2 | Presets — Customize core & extensions             | `.specify/presets//templates/`    |
|        3 | Extensions — Add new capabilities                 | `.specify/extensions//templates/` |
|      ⬇ 4 | Spec Kit Core — Built-in SDD commands & templates | `.specify/templates/`             |

---

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

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 5 comments.

---

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

[mnriem]

Please address Copilot feedback. If not applicable, please explain why. Thank you for doing this!

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

---

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

[mnriem]

Please address more Copilot feedback. You are almost there!

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

---

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

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

---

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

[pchemguy]

@mnriem, There was another comment from Copilot re /speckit-XXX vs. /speckit.XXX format. This actually varies. For Copilot agent, command uses dot, while Codex agent shows dashed commands as suggestions.

The rest should be addressed.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

---

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