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

---

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

[pchemguy]

I have completed conflict resolution process and Copilot review.

[Copilot]

Pull request overview

This PR improves the project’s README documentation by reorganizing and clarifying how to use Spec Kit’s agent commands, CLI invocation, and customization layering (extensions/presets/overrides).

Changes:

• Adds an “Available Slash Commands” section with a core/optional command breakdown.
• Clarifies specify CLI invocation and expands the documented top-level command list.
• Replaces the extensions/presets mermaid diagram with a priority table and bullet explanations.

Show a summary per file

File	Description
README.md	Reorganizes and clarifies agent command usage, CLI reference formatting, and extensions/presets layering docs

Copilot's findings

Tip

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

Comments suppressed due to low confidence (1)

README.md:341

• #### Optional Commands also skips a heading level under ## Available Slash Commands, which will trigger markdownlint MD001. Use a ### Optional Commands heading (or adjust surrounding headings so nesting increments by one).

#### Optional Commands

Additional commands for enhanced quality and validation:

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

[Copilot]

Pull request overview

Updates README.md to improve onboarding clarity around agent commands and the specify CLI reference.

Changes:

• Adds a dedicated “Available Slash Commands” section with core vs optional commands and corresponding skill names.
• Clarifies CLI invocation and expands the documented top-level command list.
• Replaces the extensions/presets priority Mermaid diagram with a concise priority table and bullets.

Show a summary per file

File	Description
README.md	Reorganizes and expands documentation for slash commands, CLI usage, and customization (templates/extensions/presets) resolution.

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: 4

[mnriem]

Please address Copilot feedback. If not applicable, please explain why

[Copilot]

Pull request overview

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

---

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

[pchemguy]

Please address Copilot feedback. If not applicable, please explain why

Done. I have not fixed presets/extensions paths copied from the Mermaid diagram, as I cannot assess correctness of suggested fix.

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