diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c44063b16f..5188d70a71 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -94,7 +94,7 @@ uv pip install -e . # Ensure the `specify` binary in this environment points at your working tree so the agent runs the branch you're testing. # Initialize a test project using your local changes -uv run specify init /speckit-test --ai --offline +uv run specify init /speckit-test --integration cd /speckit-test # Open in your agent @@ -102,7 +102,7 @@ cd /speckit-test #### Manual testing process -Any change that affects a slash command's behavior requires manually testing that command through an AI agent and submitting results with the PR. +Any change that affects a slash command's behavior requires manually testing that command through a coding agent and submitting results with the PR. 1. **Identify affected commands** — use the [prompt below](#determining-which-tests-to-run) to have your agent analyze your changed files and determine which commands need testing. 2. **Set up a test project** — scaffold from your local branch (see [Testing setup](#testing-setup)). diff --git a/README.md b/README.md index 3aa320fc73..419e7f919a 100644 --- a/README.md +++ b/README.md @@ -81,9 +81,9 @@ And use the tool directly: specify init # Or initialize in existing project -specify init . --ai copilot +specify init . --integration copilot # or -specify init --here --ai copilot +specify init --here --integration copilot # Check installed tools specify check @@ -105,9 +105,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 copilot +uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init . --integration copilot # or -uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --ai copilot +uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --integration copilot ``` **Benefits of persistent installation:** @@ -123,7 +123,7 @@ If your environment blocks access to PyPI or GitHub, see the [Enterprise / Air-G ### 2. Establish project principles -Launch your AI assistant in the project directory. Most agents expose spec-kit as `/speckit.*` slash commands; Codex CLI in skills mode uses `$speckit-*` instead. +Launch your coding agent in the project directory. Most agents expose spec-kit as `/speckit.*` slash commands; Codex CLI in skills mode uses `$speckit-*` instead. Use the **`/speckit.constitution`** command to create your project's governing principles and development guidelines that will guide all subsequent development. @@ -302,7 +302,7 @@ Run `specify integration list` to see all available integrations in your install ## Available Slash Commands -After running `specify init`, your AI coding agent will have access to these slash commands for structured development. If you pass `--ai --ai-skills`, Spec Kit installs agent skills instead of slash-command prompt files; `--ai-skills` requires `--ai`. +After running `specify init`, your AI coding agent will have access to these slash commands for structured development. For integrations that support skills mode, passing `--integration --integration-options="--skills"` installs agent skills instead of slash-command prompt files. #### Core Commands @@ -475,37 +475,37 @@ specify init --here --force ![Specify CLI bootstrapping a new project in the terminal](./media/specify_cli.gif) -You will be prompted to select the AI agent you are using. You can also proactively specify it directly in the terminal: +You will be prompted to select the coding agent integration you are using. You can also proactively specify it directly in the terminal: ```bash -specify init --ai copilot -specify init --ai gemini -specify init --ai copilot +specify init --integration copilot +specify init --integration gemini +specify init --integration codex # Or in current directory: -specify init . --ai copilot -specify init . --ai codex --ai-skills +specify init . --integration copilot +specify init . --integration codex --integration-options="--skills" # or use --here flag -specify init --here --ai copilot -specify init --here --ai codex --ai-skills +specify init --here --integration copilot +specify init --here --integration codex --integration-options="--skills" # Force merge into a non-empty current directory -specify init . --force --ai copilot +specify init . --force --integration copilot # or -specify init --here --force --ai copilot +specify init --here --force --integration 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 copilot --ignore-agent-tools +specify init --integration copilot --ignore-agent-tools ``` ### **STEP 1:** Establish project principles -Go to the project folder and run your AI agent. In our example, we're using `claude`. +Go to the project folder and run your coding agent. In our example, we're using `claude`. ![Bootstrapping Claude Code environment](./media/bootstrap-claude-code.gif) @@ -517,7 +517,7 @@ The first step should be establishing your project's governing principles using /speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. Include governance for how these principles should guide technical decisions and implementation choices. ``` -This step creates or updates the `.specify/memory/constitution.md` file with your project's foundational guidelines that the AI agent will reference during specification, planning, and implementation phases. +This step creates or updates the `.specify/memory/constitution.md` file with your project's foundational guidelines that the coding agent will reference during specification, planning, and implementation phases. ### **STEP 2:** Create project specifications @@ -725,9 +725,9 @@ The `/speckit.implement` command will: - Provide progress updates and handle errors appropriately > [!IMPORTANT] -> The AI agent will execute local CLI commands (such as `dotnet`, `npm`, etc.) - make sure you have the required tools installed on your machine. +> The coding agent will execute local CLI commands (such as `dotnet`, `npm`, etc.) - make sure you have the required tools installed on your machine. -Once the implementation is complete, test the application and resolve any runtime errors that may not be visible in CLI logs (e.g., browser console errors). You can copy and paste such errors back to your AI agent for resolution. +Once the implementation is complete, test the application and resolve any runtime errors that may not be visible in CLI logs (e.g., browser console errors). You can copy and paste such errors back to your coding agent for resolution. diff --git a/docs/installation.md b/docs/installation.md index c99810f706..7f6aa089b7 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -39,16 +39,16 @@ uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init . uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here ``` -### Specify AI Agent +### Specify Integration -You can proactively specify your AI agent during initialization: +You can proactively specify your coding agent integration during initialization: ```bash -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 gemini -uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --ai copilot -uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --ai codebuddy -uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --ai pi +uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --integration claude +uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --integration gemini +uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --integration copilot +uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --integration codebuddy +uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --integration pi ``` ### Specify Script Type (Shell vs PowerShell) @@ -73,7 +73,7 @@ uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --ai claude --ignore-agent-tools +uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --integration claude --ignore-agent-tools ``` ## Verification @@ -86,7 +86,7 @@ specify version This helps verify you are running the official Spec Kit build from GitHub, not an unrelated package with the same name. -After initialization, you should see the following commands available in your AI agent: +After initialization, you should see the following commands available in your coding agent: - `/speckit.specify` - Create specifications - `/speckit.plan` - Generate implementation plans @@ -131,12 +131,10 @@ pip install --no-index --find-links=./dist specify-cli ```bash # Initialize a project — no GitHub access needed -specify init my-project --ai claude --offline +specify init my-project --integration claude ``` -The `--offline` flag tells the CLI to use the templates, commands, and scripts bundled inside the wheel instead of downloading from GitHub. - -> **Deprecation notice:** Starting with v0.6.0, `specify init` will use bundled assets by default and the `--offline` flag will be removed. The GitHub download path will be retired because bundled assets eliminate the need for network access, avoid proxy/firewall issues, and guarantee that templates always match the installed CLI version. No action will be needed — `specify init` will simply work without network access out of the box. +Bundled assets are used by default — no network access is required. > **Note:** Python 3.11+ is required. diff --git a/docs/local-development.md b/docs/local-development.md index a23ea1d88f..4776204d7d 100644 --- a/docs/local-development.md +++ b/docs/local-development.md @@ -20,7 +20,7 @@ You can execute the CLI via the module entrypoint without installing anything: ```bash # From repo root python -m src.specify_cli --help -python -m src.specify_cli init demo-project --ai claude --ignore-agent-tools --script sh +python -m src.specify_cli init demo-project --integration claude --ignore-agent-tools --script sh ``` If you prefer invoking the script file style (uses shebang): @@ -52,7 +52,7 @@ Re-running after code edits requires no reinstall because of editable mode. `uvx` can run from a local path (or a Git ref) to simulate user flows: ```bash -uvx --from . specify init demo-uvx --ai copilot --ignore-agent-tools --script sh +uvx --from . specify init demo-uvx --integration copilot --ignore-agent-tools --script sh ``` You can also point uvx at a specific branch without merging: @@ -69,14 +69,14 @@ If you're in another directory, use an absolute path instead of `.`: ```bash uvx --from /mnt/c/GitHub/spec-kit specify --help -uvx --from /mnt/c/GitHub/spec-kit specify init demo-anywhere --ai copilot --ignore-agent-tools --script sh +uvx --from /mnt/c/GitHub/spec-kit specify init demo-anywhere --integration copilot --ignore-agent-tools --script sh ``` Set an environment variable for convenience: ```bash export SPEC_KIT_SRC=/mnt/c/GitHub/spec-kit -uvx --from "$SPEC_KIT_SRC" specify init demo-env --ai copilot --ignore-agent-tools --script ps +uvx --from "$SPEC_KIT_SRC" specify init demo-env --integration copilot --ignore-agent-tools --script ps ``` (Optional) Define a shell function: @@ -123,7 +123,7 @@ When testing `init --here` in a dirty directory, create a temp workspace: ```bash mkdir /tmp/spec-test && cd /tmp/spec-test -python -m src.specify_cli init --here --ai claude --ignore-agent-tools --script sh # if repo copied here +python -m src.specify_cli init --here --integration claude --ignore-agent-tools --script sh # if repo copied here ``` Or copy only the modified CLI portion if you want a lighter sandbox. diff --git a/docs/quickstart.md b/docs/quickstart.md index 5c0f009306..0e6c0ab9d4 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -42,7 +42,7 @@ uvx --from git+https://github.com/github/spec-kit.git specify init ` | Update slash commands, templates, and scripts in your project | +| **Project Files** | `specify init --here --force --integration ` | Update slash commands, templates, and scripts in your project | | **Both** | Run CLI upgrade, then project update | Recommended for major version updates | --- @@ -32,7 +32,7 @@ uv tool install specify-cli --force --from git+https://github.com/github/spec-ki Specify the desired release tag: ```bash -uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --ai copilot +uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --integration copilot ``` ### If you installed with `pipx` @@ -82,7 +82,7 @@ The `specs/` directory is completely excluded from template packages and will ne Run this inside your project directory: ```bash -specify init --here --force --ai +specify init --here --force --integration ``` Replace `` with your AI coding agent. Refer to this list of [Supported AI Coding Agent Integrations](reference/integrations.md) @@ -90,7 +90,7 @@ Replace `` with your AI coding agent. Refer to this list of [Support **Example:** ```bash -specify init --here --force --ai copilot +specify init --here --force --integration copilot ``` ### Understanding the `--force` flag @@ -124,7 +124,7 @@ Without `--force`, shared infrastructure files that already exist are skipped cp .specify/memory/constitution.md .specify/memory/constitution-backup.md # 2. Run the upgrade -specify init --here --force --ai copilot +specify init --here --force --integration copilot # 3. Restore your customized constitution mv .specify/memory/constitution-backup.md .specify/memory/constitution.md @@ -182,7 +182,7 @@ Restart your IDE to refresh the command list. uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git # Update project files to get new commands -specify init --here --force --ai copilot +specify init --here --force --integration copilot # Restore your constitution if customized git restore .specify/memory/constitution.md @@ -199,7 +199,7 @@ cp -r .specify/templates /tmp/templates-backup uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git # 3. Update project -specify init --here --force --ai copilot +specify init --here --force --integration copilot # 4. Restore customizations mv /tmp/constitution-backup.md .specify/memory/constitution.md @@ -232,7 +232,7 @@ If you initialized your project with `--no-git`, you can still upgrade: cp .specify/memory/constitution.md /tmp/constitution-backup.md # Run upgrade -specify init --here --force --ai copilot --no-git +specify init --here --force --integration copilot --no-git # Restore customizations mv /tmp/constitution-backup.md .specify/memory/constitution.md @@ -253,13 +253,13 @@ The `--no-git` flag tells Spec Kit to **skip git repository initialization**. Th **During initial setup:** ```bash -specify init my-project --ai copilot --no-git +specify init my-project --integration copilot --no-git ``` **During upgrade:** ```bash -specify init --here --force --ai copilot --no-git +specify init --here --force --integration copilot --no-git ``` ### What `--no-git` does NOT do @@ -367,7 +367,7 @@ Only Spec Kit infrastructure files: - **Use `--force` flag** - Skip this confirmation entirely: ```bash - specify init --here --force --ai copilot + specify init --here --force --integration copilot ``` **When you see this warning:** diff --git a/extensions/EXTENSION-USER-GUIDE.md b/extensions/EXTENSION-USER-GUIDE.md index 595985d955..31bb81cb1a 100644 --- a/extensions/EXTENSION-USER-GUIDE.md +++ b/extensions/EXTENSION-USER-GUIDE.md @@ -153,7 +153,7 @@ This will: 2. Validate the manifest 3. Check compatibility with your spec-kit version 4. Install to `.specify/extensions/jira/` -5. Register commands with your AI agent +5. Register commands with your coding agent 6. Create config template ### Install from URL @@ -189,7 +189,7 @@ Provided commands: ### Automatic Agent Skill Registration -If your project was initialized with `--ai-skills`, extension commands are **automatically registered as agent skills** during installation. This ensures that extensions are discoverable by agents that use the [agentskills.io](https://agentskills.io) skill specification. +If your project uses a skills-based integration (e.g., `--integration claude`, `--integration codex`) or was initialized with `--integration-options="--skills"`, extension commands are **automatically registered as agent skills** during installation. This ensures that extensions are discoverable by agents that use the [agentskills.io](https://agentskills.io) skill specification. ```text ✓ Extension installed successfully! @@ -208,7 +208,7 @@ When an extension is removed, its corresponding skills are also cleaned up autom ### Using Extension Commands -Extensions add commands that appear in your AI agent (Claude Code): +Extensions add commands that appear in your coding agent (Claude Code): ```text # In Claude Code @@ -780,12 +780,12 @@ specify extension add --dev /path/to/extension ### Command Not Available -**Issue**: Extension command not appearing in AI agent +**Issue**: Extension command not appearing in coding agent **Solutions**: 1. Check extension is enabled: `specify extension list` -2. Restart AI agent (Claude Code) +2. Restart coding agent (Claude Code) 3. Check command file exists: ```bash @@ -819,8 +819,8 @@ specify extension add --dev /path/to/extension **Solutions**: 1. Check MCP server is installed -2. Check AI agent MCP configuration -3. Restart AI agent +2. Check coding agent MCP configuration +3. Restart coding agent 4. Check extension requirements: `specify extension info jira` ### Permission Denied diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py index 618492f306..d5f5aba2d5 100644 --- a/src/specify_cli/__init__.py +++ b/src/specify_cli/__init__.py @@ -967,7 +967,7 @@ def init( ai_assistant: str = typer.Option(None, "--ai", help=AI_ASSISTANT_HELP), ai_commands_dir: str = typer.Option(None, "--ai-commands-dir", help="Directory for agent command files (required with --ai generic, e.g. .myagent/commands/)"), script_type: str = typer.Option(None, "--script", help="Script type to use: sh or ps"), - ignore_agent_tools: bool = typer.Option(False, "--ignore-agent-tools", help="Skip checks for AI agent tools like Claude Code"), + ignore_agent_tools: bool = typer.Option(False, "--ignore-agent-tools", help="Skip checks for coding agent tools like Claude Code"), no_git: bool = typer.Option(False, "--no-git", help="Skip git repository initialization"), here: bool = typer.Option(False, "--here", help="Initialize project in the current directory instead of creating a new one"), force: bool = typer.Option(False, "--force", help="Force merge/overwrite when using --here (skip confirmation)"), @@ -997,29 +997,28 @@ def init( This command will: 1. Check that required tools are installed (git is optional) - 2. Let you choose your AI assistant + 2. Let you choose your coding agent integration 3. Download template from GitHub (or use bundled assets with --offline) 4. Initialize a fresh git repository (if not --no-git and no existing repo) - 5. Optionally set up AI assistant commands + 5. Optionally set up coding agent integration commands Examples: specify init my-project - specify init my-project --ai claude - specify init my-project --ai copilot --no-git + specify init my-project --integration claude + specify init my-project --integration copilot --no-git specify init --ignore-agent-tools my-project - specify init . --ai claude # Initialize in current directory - specify init . # Initialize in current directory (interactive AI selection) - specify init --here --ai claude # Alternative syntax for current directory - specify init --here --ai codex --ai-skills - specify init --here --ai codebuddy - specify init --here --ai vibe # Initialize with Mistral Vibe support + specify init . --integration claude # Initialize in current directory + specify init . # Initialize in current directory (interactive integration selection) + specify init --here --integration claude # Alternative syntax for current directory + specify init --here --integration codex --integration-options="--skills" + specify init --here --integration codebuddy + specify init --here --integration vibe # Initialize with Mistral Vibe support specify init --here specify init --here --force # Skip confirmation when current directory not empty - specify init my-project --ai claude # Claude installs skills by default - specify init --here --ai gemini --ai-skills - specify init my-project --ai generic --ai-commands-dir .myagent/commands/ # Unsupported agent - specify init my-project --offline # Use bundled assets (no network access) - specify init my-project --ai claude --preset healthcare-compliance # With preset + specify init my-project --integration claude # Claude installs skills by default + specify init --here --integration gemini + specify init my-project --integration generic --integration-options="--commands-dir .myagent/commands/" # Bring your own agent; requires --commands-dir + specify init my-project --integration claude --preset healthcare-compliance # With preset """ show_banner() @@ -1029,14 +1028,14 @@ def init( if ai_assistant and ai_assistant.startswith("--"): console.print(f"[red]Error:[/red] Invalid value for --ai: '{ai_assistant}'") console.print("[yellow]Hint:[/yellow] Did you forget to provide a value for --ai?") - console.print("[yellow]Example:[/yellow] specify init --ai claude --here") + console.print("[yellow]Example:[/yellow] specify init --integration claude --here") console.print(f"[yellow]Available agents:[/yellow] {', '.join(AGENT_CONFIG.keys())}") raise typer.Exit(1) if ai_commands_dir and ai_commands_dir.startswith("--"): console.print(f"[red]Error:[/red] Invalid value for --ai-commands-dir: '{ai_commands_dir}'") console.print("[yellow]Hint:[/yellow] Did you forget to provide a value for --ai-commands-dir?") - console.print("[yellow]Example:[/yellow] specify init --ai generic --ai-commands-dir .myagent/commands/") + console.print("[yellow]Example:[/yellow] specify init --integration generic --integration-options=\"--commands-dir .myagent/commands/\"") raise typer.Exit(1) if ai_assistant: @@ -1170,7 +1169,7 @@ def init( ai_choices = {key: config["name"] for key, config in AGENT_CONFIG.items()} selected_ai = select_with_arrows( ai_choices, - "Choose your AI assistant:", + "Choose your coding agent integration:", "copilot" ) @@ -1241,7 +1240,7 @@ def init( else: selected_script = default_script - console.print(f"[cyan]Selected AI assistant:[/cyan] {selected_ai}") + console.print(f"[cyan]Selected coding agent integration:[/cyan] {selected_ai}") console.print(f"[cyan]Selected script type:[/cyan] {selected_script}") tracker = StepTracker("Initialize Specify Project") @@ -1250,7 +1249,7 @@ def init( tracker.add("precheck", "Check required tools") tracker.complete("precheck", "ok") - tracker.add("ai-select", "Select AI assistant") + tracker.add("ai-select", "Select coding agent integration") tracker.complete("ai-select", f"{selected_ai}") tracker.add("script-select", "Select script type") tracker.complete("script-select", selected_script) @@ -1565,7 +1564,7 @@ def _display_cmd(name: str) -> str: return f"/speckit-{name}" return f"/speckit.{name}" - steps_lines.append(f"{step_num}. Start using {usage_label} with your AI agent:") + steps_lines.append(f"{step_num}. Start using {usage_label} with your coding agent:") steps_lines.append(f" {step_num}.1 [cyan]{_display_cmd('constitution')}[/] - Establish project principles") steps_lines.append(f" {step_num}.2 [cyan]{_display_cmd('specify')}[/] - Create baseline specification") @@ -1636,7 +1635,7 @@ def check(): console.print("[dim]Tip: Install git for repository management[/dim]") if not any(agent_results.values()): - console.print("[dim]Tip: Install an AI assistant for the best experience[/dim]") + console.print("[dim]Tip: Install a coding agent for the best experience[/dim]") @app.command() def version(): @@ -1882,7 +1881,7 @@ def get_speckit_version() -> str: integration_app = typer.Typer( name="integration", - help="Manage AI agent integrations", + help="Manage coding agent integrations", add_completion=False, ) app.add_typer(integration_app, name="integration") @@ -2020,7 +2019,7 @@ def integration_list( console.print(table) return - table = Table(title="AI Agent Integrations") + table = Table(title="Coding Agent Integrations") table.add_column("Key", style="cyan") table.add_column("Name") table.add_column("Status")