CHORE - Fix command syntax in documentation - #4601
Open
molson504x wants to merge 1 commit into
Open
molson504x wants to merge 1 commit into
molson504x wants to merge 1 commit into
Conversation
…ckit.*` to `/speckit-*` format across multiple files for consistency and clarity. Adjust references in guides and concepts to reflect the correct command usage, ensuring accurate instructions for users.
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Generic documentation now presents Copilot-specific syntax despite supported integrations using several invocation formats, and the SDD reference contradicts its own notation guidance.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
Standardizes documentation examples on hyphenated GitHub Copilot skill syntax.
Changes:
- Converts core, extension, and assessment command examples to
/speckit-*. - Updates community catalog documentation descriptions accordingly.
File summaries
| File | Description |
|---|---|
docs/upgrade.md |
Updates upgrade examples. |
docs/reference/core.md |
Updates core command references. |
docs/reference/agentic-sdd.md |
Converts SDD workflow examples. |
docs/reference/agentic-bugfix.md |
Converts bug workflow examples. |
docs/reference/agentic-assessment.md |
Converts assessment examples. |
docs/installation.md |
Updates installed-command list. |
docs/guides/monorepo.md |
Updates monorepo examples. |
docs/guides/existing-projects.md |
Updates adoption workflow examples. |
docs/guides/evolving-specs.md |
Updates specification lifecycle examples. |
docs/concepts/spec-of-specs.md |
Updates decomposition workflow references. |
docs/concepts/complex-features.md |
Updates scoped implementation examples. |
docs/community/presets.md |
Updates preset descriptions. |
docs/community/extensions.md |
Updates extension descriptions. |
Review details
- Files reviewed: 13/13 changed files
- Comments generated: 9
- Review effort level: Balanced
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+3
to
+5
| Large or complex features often run smoothly through `/speckit-specify`, | ||
| `/speckit-plan`, and `/speckit-tasks`, then degrade during implementation. In | ||
| the middle of a long `/speckit-implement` run, agents can start to lose track of |
|
|
||
| When a feature is too large to run through a single | ||
| `/speckit.specify` → `/speckit.plan` → `/speckit.tasks` → `/speckit.implement` | ||
| `/speckit-specify` → `/speckit-plan` → `/speckit-tasks` → `/speckit-implement` |
|
|
||
| When you add another feature or make a substantial follow-up change, create a | ||
| new feature spec through your installed `/speckit.specify` command and continue | ||
| new feature spec through your installed `/speckit-specify` command and continue |
| completing the SDD steps below first. | ||
|
|
||
| Run `/speckit.constitution` with principles that are already true for the | ||
| Run `/speckit-constitution` with principles that are already true for the |
| ```bash | ||
| cd apps/web | ||
| # then run /speckit.specify, /speckit.plan, … in your agent | ||
| # then run /speckit-specify, /speckit-plan, … in your agent |
| - `/speckit.constitution` - Create or update project principles | ||
| - `/speckit.converge` - Assess codebase against artifacts and append remaining tasks | ||
| - `/speckit.taskstoissues` - Convert tasks to issues | ||
| - `/speckit-specify` - Create specifications |
|
|
||
| ```text | ||
| /speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.plan -> /speckit.checklist -> /speckit.tasks -> /speckit.analyze -> /speckit.implement -> /speckit.converge | ||
| /speckit-constitution -> /speckit-specify -> /speckit-clarify -> /speckit-plan -> /speckit-checklist -> /speckit-tasks -> /speckit-analyze -> /speckit-implement -> /speckit-converge |
| | ----------------- | ------------------------------------------------------------------------ | | ||
| | `SPECKIT_INTEGRATION_DEFAULT` | Override the fallback integration used by `specify init` when `--integration` is omitted (interactive prompt default and non-interactive fallback). Set it to any registered integration key (e.g. `gemini`, `claude`). An unrecognized value is ignored with a warning and the built-in default (`copilot`) is used. An explicit `--integration <key>` always takes precedence. | | ||
| | `SPECIFY_INIT_DIR` | Target a member project from outside its directory (e.g. a monorepo root) without `cd`, for non-interactive / CI use. Set it to the **project root** — the directory *containing* `.specify/` (relative paths resolve against the current directory). The path must exist and contain `.specify/`, otherwise the command errors and does **not** fall back to the current directory. Resolved once in the core root helper (`get_repo_root` in Bash, `Get-RepoRoot` in PowerShell), so it is honored by the core feature scripts (`/speckit.plan`, `/speckit.tasks`, …) and the Git extension's feature-branch creation, which inherit it. The `specify` CLI applies the **same** validation rules to every project-scoped subcommand (`specify integration …`, `specify extension …`, `specify workflow …`, `specify preset …`, and the rest that operate on a `.specify/` project), so those can target a member project too. When unset, Bash/PowerShell helpers keep their existing upward search; the `specify` CLI keeps its project-scoped resolver cwd-only unless a command explicitly defines broader detection (for example, bundle commands). | | ||
| | `SPECIFY_INIT_DIR` | Target a member project from outside its directory (e.g. a monorepo root) without `cd`, for non-interactive / CI use. Set it to the **project root** — the directory *containing* `.specify/` (relative paths resolve against the current directory). The path must exist and contain `.specify/`, otherwise the command errors and does **not** fall back to the current directory. Resolved once in the core root helper (`get_repo_root` in Bash, `Get-RepoRoot` in PowerShell), so it is honored by the core feature scripts (`/speckit-plan`, `/speckit-tasks`, …) and the Git extension's feature-branch creation, which inherit it. The `specify` CLI applies the **same** validation rules to every project-scoped subcommand (`specify integration …`, `specify extension …`, `specify workflow …`, `specify preset …`, and the rest that operate on a `.specify/` project), so those can target a member project too. When unset, Bash/PowerShell helpers keep their existing upward search; the `specify` CLI keeps its project-scoped resolver cwd-only unless a command explicitly defines broader detection (for example, bundle commands). | |
| - **Diagnostics:** `specify check` to verify tool installation | ||
|
|
||
| Once you've run `specify init`, the slash commands (like `/speckit.specify`, `/speckit.plan`, etc.) are **permanently installed** in your project's agent folder (`.claude/`, `.github/prompts/`, `.pi/prompts/`, `.omp/commands/`, etc.). Your AI coding agent reads these command files directly—no need to run `specify` again. | ||
| Once you've run `specify init`, the slash commands (like `/speckit-specify`, `/speckit-plan`, etc.) are **permanently installed** in your project's agent folder (`.claude/`, `.github/prompts/`, `.pi/prompts/`, `.omp/commands/`, etc.). Your AI coding agent reads these command files directly—no need to run `specify` again. |
mnriem
added
the
triage-can-wait
Collaborator
|
Please address Copilot feedback where applicable. Note that I am fine with the Copilot skill syntax as the command shown. No need to repeat anywhere that the syntax might be different for different agents. Except for the installation page as there we have the one time someone could be picking another agent |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request standardizes command references throughout the documentation by converting all occurrences of slash-separated commands (e.g.,
/speckit.implement) to their hyphenated forms (e.g.,/speckit-implement). This improves consistency and aligns the docs with the current command naming conventions. The changes affect both the conceptual documentation and community extension/preset listings.The most important changes are:
Documentation consistency:
docs/concepts/complex-features.mdanddocs/concepts/spec-of-specs.mdfrom the old slash-dot format (e.g.,/speckit.implement) to the new slash-hyphen format (e.g.,/speckit-implement). [1] [2] [3] [4] [5] [6]Community extension and preset listings:
docs/community/extensions.mdanddocs/community/presets.mdto use hyphenated forms, ensuring extension descriptions and preset summaries are consistent with the new command syntax. [1] [2] [3] [4] [5] [6] [7] [8]These changes enhance clarity for users and reduce confusion by unifying command syntax across all documentation.