From 08c514e8d90687d92cbb1273749abd3b475065cb Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Thu, 16 Apr 2026 13:47:51 -0500 Subject: [PATCH 1/3] docs: add core commands reference and simplify README CLI section - New docs/reference/core.md: reference for init (active options only, copilot as main example), check, and version commands - docs/toc.yml: add Core Commands under Reference - README.md: replace verbose CLI Reference section (init options table, 30+ per-agent examples, deprecated flags, env vars) with links to reference docs; use copilot as main example throughout --- README.md | 155 +++++------------------------------------ docs/reference/core.md | 79 +++++++++++++++++++++ docs/toc.yml | 2 + 3 files changed, 97 insertions(+), 139 deletions(-) create mode 100644 docs/reference/core.md diff --git a/README.md b/README.md index a12c6cbb75..70588c1bcd 100644 --- a/README.md +++ b/README.md @@ -77,9 +77,9 @@ And use the tool directly: specify init # Or initialize in existing project -specify init . --ai claude +specify init . --ai copilot # or -specify init --here --ai claude +specify init --here --ai copilot # Check installed tools specify check @@ -100,9 +100,9 @@ Run directly without installing: uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init # Or initialize in existing project -uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init . --ai claude +uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init . --ai copilot # or -uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --ai claude +uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --ai copilot ``` **Benefits of persistent installation:** @@ -349,136 +349,13 @@ Additional commands for enhanced quality and validation: ## 🔧 Specify CLI Reference -The `specify` tool is invoked as - -```text -specify [SUBCOMMAND] [OPTIONS] -``` - -and supports the following commands: - -### Commands - -| 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`, `forge`, etc.) | -| `version` | Show the currently installed Spec Kit version. | -| `extension` | Manage extensions | -| `preset` | Manage presets | -| `integration` | Manage integrations | -| `workflow` | Run, manage, and search workflows. See the [Workflows reference](https://github.github.io/spec-kit/reference/workflows.html) | - -### `specify init` Arguments & Options - -```bash -specify init [PROJECT_NAME] -``` - -| Argument/Option | Type | Description | -| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `` | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory) | -| `--ai` | Option | AI assistant to use (see `AGENT_CONFIG` for the full, up-to-date list). Common options include: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `junie`, `kilocode`, `auggie`, `roo`, `codebuddy`, `amp`, `shai`, `kiro-cli` (`kiro` alias), `agy`, `bob`, `qodercli`, `vibe`, `kimi`, `iflow`, `pi`, `forge`, or `generic` (requires `--ai-commands-dir`) | -| `--ai-commands-dir` | Option | Directory for agent command files (required with `--ai generic`, e.g. `.myagent/commands/`) | -| `--script` | Option | Script variant to use: `sh` (bash/zsh) or `ps` (PowerShell) | -| `--ignore-agent-tools` | Flag | Skip checks for AI agent tools like Claude Code | -| `--no-git` | Flag | Skip git repository initialization | -| `--here` | Flag | Initialize project in the current directory instead of creating a new one | -| `--force` | Flag | Force merge/overwrite when initializing in current directory (skip confirmation) | -| `--skip-tls` | Flag | Skip SSL/TLS verification (not recommended) | -| `--debug` | Flag | Enable detailed debug output for troubleshooting | -| `--github-token` | Option | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable) | -| `--ai-skills` | Flag | Install Prompt.MD templates as agent skills in agent-specific `skills/` directory (requires `--ai`). Extension commands are also auto-registered as skills when extensions are added later. | -| `--branch-numbering` | Option | Branch numbering strategy: `sequential` (default — `001`, `002`, `003`, …, `1000`, … — expands beyond 3 digits automatically) or `timestamp` (`YYYYMMDD-HHMMSS`). Timestamp mode is useful for distributed teams to avoid numbering conflicts | - -### Examples - -```bash -# Basic project initialization -specify init my-project - -# Initialize with specific AI assistant -specify init my-project --ai claude - -# Initialize with Cursor support -specify init my-project --ai cursor-agent - -# Initialize with Qoder support -specify init my-project --ai qodercli - -# Initialize with Windsurf support -specify init my-project --ai windsurf - -# Initialize with Kiro CLI support -specify init my-project --ai kiro-cli - -# Initialize with Amp support -specify init my-project --ai amp - -# Initialize with SHAI support -specify init my-project --ai shai - -# Initialize with Mistral Vibe support -specify init my-project --ai vibe - -# Initialize with IBM Bob support -specify init my-project --ai bob - -# Initialize with Pi Coding Agent support -specify init my-project --ai pi - -# Initialize with Codex CLI support -specify init my-project --ai codex --ai-skills - -# Initialize with Antigravity support -specify init my-project --ai agy --ai-skills +For full command details, options, and examples, see the [reference documentation](https://github.github.io/spec-kit/): -# Initialize with Forge support -specify init my-project --ai forge - -# Initialize with an unsupported agent (generic / bring your own agent) -specify init my-project --ai generic --ai-commands-dir .myagent/commands/ - -# Initialize with PowerShell scripts (Windows/cross-platform) -specify init my-project --ai copilot --script ps - -# Initialize in current directory -specify init . --ai copilot -# or use the --here flag -specify init --here --ai copilot - -# Force merge into current (non-empty) directory without confirmation -specify init . --force --ai copilot -# or -specify init --here --force --ai copilot - -# Skip git initialization -specify init my-project --ai gemini --no-git - -# Enable debug output for troubleshooting -specify init my-project --ai claude --debug - -# Use GitHub token for API requests (helpful for corporate environments) -specify init my-project --ai claude --github-token ghp_your_token_here - -# Claude Code installs skills with the project by default -specify init my-project --ai claude - -# Initialize in current directory with agent skills -specify init --here --ai gemini --ai-skills - -# Use timestamp-based branch numbering (useful for distributed teams) -specify init my-project --ai claude --branch-numbering timestamp - -# Check system requirements -specify check -``` - -### Environment Variables - -| Variable | Description | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-photo-albums`) to work on a specific feature when not using Git branches.
\*\*Must be set in the context of the agent you're working with prior to using `/speckit.plan` or follow-up commands. | +- [Core Commands](https://github.github.io/spec-kit/reference/core.html) — `init`, `check`, `version` +- [Integrations](https://github.github.io/spec-kit/reference/integrations.html) — `integration list`, `install`, `uninstall`, `switch`, `upgrade` +- [Extensions](https://github.github.io/spec-kit/reference/extensions.html) — `extension add`, `remove`, `search`, `update`, catalogs +- [Presets](https://github.github.io/spec-kit/reference/presets.html) — `preset add`, `remove`, `resolve`, priority stacking +- [Workflows](https://github.github.io/spec-kit/reference/workflows.html) — `workflow run`, `resume`, step types, expressions ## 🧩 Making Spec Kit Your Own: Extensions & Presets @@ -627,29 +504,29 @@ specify init --here --force You will be prompted to select the AI agent you are using. You can also proactively specify it directly in the terminal: ```bash -specify init --ai claude +specify init --ai copilot specify init --ai gemini specify init --ai copilot # Or in current directory: -specify init . --ai claude +specify init . --ai copilot specify init . --ai codex --ai-skills # or use --here flag -specify init --here --ai claude +specify init --here --ai copilot specify init --here --ai codex --ai-skills # Force merge into a non-empty current directory -specify init . --force --ai claude +specify init . --force --ai copilot # or -specify init --here --force --ai claude +specify init --here --force --ai copilot ``` The CLI will check if you have Claude Code, Gemini CLI, Cursor CLI, Qwen CLI, opencode, Codex CLI, Qoder CLI, Tabnine CLI, Kiro CLI, Pi, Forge, Goose, or Mistral Vibe installed. If you do not, or you prefer to get the templates without checking for the right tools, use `--ignore-agent-tools` with your command: ```bash -specify init --ai claude --ignore-agent-tools +specify init --ai copilot --ignore-agent-tools ``` ### **STEP 1:** Establish project principles diff --git a/docs/reference/core.md b/docs/reference/core.md new file mode 100644 index 0000000000..fdab05a02b --- /dev/null +++ b/docs/reference/core.md @@ -0,0 +1,79 @@ +# Core Commands + +The core `specify` commands handle project initialization, system checks, and version information. + +## Initialize a Project + +```bash +specify init [] +``` + +| Option | Description | +| ------------------------ | ------------------------------------------------------------------------ | +| `--integration ` | AI coding agent integration to use (e.g. `copilot`, `claude`, `gemini`). See the [Integrations reference](integrations.md) for all available keys | +| `--integration-options` | Options for the integration (e.g. `--integration-options="--commands-dir .myagent/cmds"`) | +| `--script sh\|ps` | Script type: `sh` (bash/zsh) or `ps` (PowerShell) | +| `--here` | Initialize in the current directory instead of creating a new one | +| `--force` | Force merge/overwrite when initializing in an existing directory | +| `--no-git` | Skip git repository initialization | +| `--ignore-agent-tools` | Skip checks for AI coding agent CLI tools | +| `--preset ` | Install a preset during initialization | +| `--branch-numbering` | Branch numbering strategy: `sequential` (default) or `timestamp` | + +Creates a new Spec Kit project with the necessary directory structure, templates, scripts, and AI coding agent integration files. + +Use `` to create a new directory, or `--here` (or `.`) to initialize in the current directory. If the directory already has files, use `--force` to merge without confirmation. + +### Examples + +```bash +# Create a new project with an integration +specify init my-project --integration copilot + +# Initialize in the current directory +specify init --here --integration copilot + +# Force merge into a non-empty directory +specify init --here --force --integration copilot + +# Use PowerShell scripts (Windows/cross-platform) +specify init my-project --integration copilot --script ps + +# Skip git initialization +specify init my-project --integration copilot --no-git + +# Install a preset during initialization +specify init my-project --integration copilot --preset compliance + +# Use timestamp-based branch numbering (useful for distributed teams) +specify init my-project --integration copilot --branch-numbering timestamp +``` + +### Environment Variables + +| Variable | Description | +| ----------------- | ------------------------------------------------------------------------ | +| `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-photo-albums`) to work on a specific feature when not using Git branches. Must be set in the context of the agent prior to using `/speckit.plan` or follow-up commands. | + +## Check Installed Tools + +```bash +specify check +``` + +Checks that required tools are available on your system: `git` and any CLI-based AI coding agents. IDE-based agents are skipped since they don't require a CLI tool. + +## Version Information + +```bash +specify version +``` + +Displays the Spec Kit CLI version, Python version, platform, and architecture. + +A quick version check is also available via: + +```bash +specify --version +specify -V +``` diff --git a/docs/toc.yml b/docs/toc.yml index 5666cbb230..aa9ca29a44 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -15,6 +15,8 @@ # Reference - name: Reference items: + - name: Core Commands + href: reference/core.md - name: Integrations href: reference/integrations.md - name: Extensions From e31043947f83c12da26284d99bb234f560bb9b41 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Thu, 16 Apr 2026 13:49:27 -0500 Subject: [PATCH 2/3] docs: add CLI reference overview page - New docs/reference/overview.md: explains each CLI surface area (core, integrations, extensions, presets, workflows) with key commands and links to detailed reference pages - docs/toc.yml: add Overview as first item under Reference - README.md: simplify CLI Reference to single link to overview page --- README.md | 8 +----- docs/reference/overview.md | 51 ++++++++++++++++++++++++++++++++++++++ docs/toc.yml | 2 ++ 3 files changed, 54 insertions(+), 7 deletions(-) create mode 100644 docs/reference/overview.md diff --git a/README.md b/README.md index 70588c1bcd..119f0c8a0f 100644 --- a/README.md +++ b/README.md @@ -349,13 +349,7 @@ Additional commands for enhanced quality and validation: ## 🔧 Specify CLI Reference -For full command details, options, and examples, see the [reference documentation](https://github.github.io/spec-kit/): - -- [Core Commands](https://github.github.io/spec-kit/reference/core.html) — `init`, `check`, `version` -- [Integrations](https://github.github.io/spec-kit/reference/integrations.html) — `integration list`, `install`, `uninstall`, `switch`, `upgrade` -- [Extensions](https://github.github.io/spec-kit/reference/extensions.html) — `extension add`, `remove`, `search`, `update`, catalogs -- [Presets](https://github.github.io/spec-kit/reference/presets.html) — `preset add`, `remove`, `resolve`, priority stacking -- [Workflows](https://github.github.io/spec-kit/reference/workflows.html) — `workflow run`, `resume`, step types, expressions +For full command details, options, and examples, see the [CLI Reference](https://github.github.io/spec-kit/reference/overview.html). ## 🧩 Making Spec Kit Your Own: Extensions & Presets diff --git a/docs/reference/overview.md b/docs/reference/overview.md new file mode 100644 index 0000000000..e022abfb05 --- /dev/null +++ b/docs/reference/overview.md @@ -0,0 +1,51 @@ +# CLI Reference + +The Specify CLI (`specify`) manages the full lifecycle of Spec-Driven Development — from project initialization to workflow automation. + +## Core Commands + +The foundational commands for creating and managing Spec Kit projects. + +- **`specify init`** — scaffold a new project with templates, scripts, and an AI coding agent integration +- **`specify check`** — verify that required tools (Git, AI coding agents) are installed +- **`specify version`** — display version and system information + +[Core Commands reference →](core.md) + +## Integrations + +Integrations connect Spec Kit to your AI coding agent. Each integration sets up the appropriate command files, context rules, and directory structures for a specific agent. Only one integration is active per project. + +- **`specify integration list`** — see available integrations +- **`specify integration install`** / **`uninstall`** / **`switch`** / **`upgrade`** — manage the active integration + +[Integrations reference →](integrations.md) + +## Extensions + +Extensions add new capabilities — domain-specific commands, external tool integrations, quality gates, and more. Multiple extensions can be installed side by side. + +- **`specify extension search`** / **`add`** / **`remove`** — discover and manage extensions +- **`specify extension catalog`** — manage catalog sources for discovery and installation + +[Extensions reference →](extensions.md) + +## Presets + +Presets customize how Spec Kit works — overriding templates, commands, and terminology without changing any tooling. Multiple presets can be stacked with priority ordering. + +- **`specify preset search`** / **`add`** / **`remove`** — discover and manage presets +- **`specify preset resolve`** — trace which file wins in the resolution stack +- **`specify preset catalog`** — manage catalog sources + +[Presets reference →](presets.md) + +## Workflows + +Workflows automate multi-step processes — chaining commands, prompts, shell steps, and human checkpoints into repeatable sequences with conditional logic, loops, and resume support. + +- **`specify workflow run`** / **`resume`** / **`status`** — execute and monitor workflows +- **`specify workflow search`** / **`add`** / **`remove`** — discover and manage workflows +- **`specify workflow catalog`** — manage catalog sources + +[Workflows reference →](workflows.md) diff --git a/docs/toc.yml b/docs/toc.yml index aa9ca29a44..70ae77de39 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -15,6 +15,8 @@ # Reference - name: Reference items: + - name: Overview + href: reference/overview.md - name: Core Commands href: reference/core.md - name: Integrations From d39045e1ad41540e47b3b35511f1b406c095eb75 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Thu, 16 Apr 2026 13:50:11 -0500 Subject: [PATCH 3/3] docs: remove command references from overview, keep paragraphs only --- docs/reference/overview.md | 28 +++++----------------------- 1 file changed, 5 insertions(+), 23 deletions(-) diff --git a/docs/reference/overview.md b/docs/reference/overview.md index e022abfb05..10fcdc3bca 100644 --- a/docs/reference/overview.md +++ b/docs/reference/overview.md @@ -4,48 +4,30 @@ The Specify CLI (`specify`) manages the full lifecycle of Spec-Driven Developmen ## Core Commands -The foundational commands for creating and managing Spec Kit projects. - -- **`specify init`** — scaffold a new project with templates, scripts, and an AI coding agent integration -- **`specify check`** — verify that required tools (Git, AI coding agents) are installed -- **`specify version`** — display version and system information +The foundational commands for creating and managing Spec Kit projects. Initialize a new project with the necessary directory structure, templates, and scripts. Verify that your system has the required tools installed. Check version and system information. [Core Commands reference →](core.md) ## Integrations -Integrations connect Spec Kit to your AI coding agent. Each integration sets up the appropriate command files, context rules, and directory structures for a specific agent. Only one integration is active per project. - -- **`specify integration list`** — see available integrations -- **`specify integration install`** / **`uninstall`** / **`switch`** / **`upgrade`** — manage the active integration +Integrations connect Spec Kit to your AI coding agent. Each integration sets up the appropriate command files, context rules, and directory structures for a specific agent. Only one integration is active per project at a time, and you can switch between them at any point. [Integrations reference →](integrations.md) ## Extensions -Extensions add new capabilities — domain-specific commands, external tool integrations, quality gates, and more. Multiple extensions can be installed side by side. - -- **`specify extension search`** / **`add`** / **`remove`** — discover and manage extensions -- **`specify extension catalog`** — manage catalog sources for discovery and installation +Extensions add new capabilities to Spec Kit — domain-specific commands, external tool integrations, quality gates, and more. They are discovered through catalogs and can be installed, updated, enabled, disabled, or removed independently. Multiple extensions can coexist in a single project. [Extensions reference →](extensions.md) ## Presets -Presets customize how Spec Kit works — overriding templates, commands, and terminology without changing any tooling. Multiple presets can be stacked with priority ordering. - -- **`specify preset search`** / **`add`** / **`remove`** — discover and manage presets -- **`specify preset resolve`** — trace which file wins in the resolution stack -- **`specify preset catalog`** — manage catalog sources +Presets customize how Spec Kit works — overriding command files, template files, and script files without changing any tooling. They let you enforce organizational standards, adapt the workflow to your methodology, or localize the entire experience. Multiple presets can be stacked with priority ordering to layer customizations. [Presets reference →](presets.md) ## Workflows -Workflows automate multi-step processes — chaining commands, prompts, shell steps, and human checkpoints into repeatable sequences with conditional logic, loops, and resume support. - -- **`specify workflow run`** / **`resume`** / **`status`** — execute and monitor workflows -- **`specify workflow search`** / **`add`** / **`remove`** — discover and manage workflows -- **`specify workflow catalog`** — manage catalog sources +Workflows automate multi-step Spec-Driven Development processes into repeatable sequences. They chain commands, prompts, shell steps, and human checkpoints together, with support for conditional logic, loops, fan-out/fan-in, and the ability to pause and resume from the exact point of interruption. [Workflows reference →](workflows.md)