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

[mnriem]

Please remove $ here

[mnriem]

I cannot see what changed here because it changes the entire table. Please revert it if it is merely a table formatting change that does not visually change anything

[mnriem]

Missing the skills column here?

[mnriem]

Similar as table above. If not a visible change please revert this

[mnriem]

Looks identical?

[mnriem]

Why is the Mermaid part being removed?

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

The “Core Commands” table maps /speckit.specify and /speckit.plan to the wrong agent-skill names. In skills mode the names are $speckit-specify, $speckit-plan, $speckit-tasks, etc. (see _display_cmd() in src/specify_cli/__init__.py where specify -> $speckit-specify and plan -> $speckit-plan). Please update the Agent Skill column so each slash command matches the corresponding skill name.

This issue also appears in the following locations of the same file:

• line 315
• line 325
• line 444

Suggested change

	| `/speckit.specify` | `$speckit-plan` | Define what you want to build (requirements and user stories) |
	| `/speckit.plan` | `$speckit-tasks` | Create technical implementation plans with your chosen tech stack |
	| `/speckit.specify` | `$speckit-specify` | Define what you want to build (requirements and user stories) |
	| `/speckit.plan` | `$speckit-plan` | Create technical implementation plans with your chosen tech stack |