From f438a10c7c74aeaffb6e9329c8cf439823eecc20 Mon Sep 17 00:00:00 2001 From: Vincent Burckhardt Date: Thu, 6 Nov 2025 15:31:11 +0000 Subject: [PATCH 1/5] feat: add support for IBM Bob IDE --- .github/workflows/scripts/create-github-release.sh | 2 ++ .../workflows/scripts/create-release-packages.sh | 5 ++++- AGENTS.md | 4 +++- README.md | 6 +++++- scripts/bash/update-agent-context.sh | 13 +++++++++++-- scripts/powershell/update-agent-context.ps1 | 9 ++++++--- src/specify_cli/__init__.py | 8 +++++++- 7 files changed, 38 insertions(+), 9 deletions(-) diff --git a/.github/workflows/scripts/create-github-release.sh b/.github/workflows/scripts/create-github-release.sh index 25d354ef..7490dfdf 100644 --- a/.github/workflows/scripts/create-github-release.sh +++ b/.github/workflows/scripts/create-github-release.sh @@ -44,5 +44,7 @@ gh release create "$VERSION" \ .genreleases/spec-kit-template-amp-ps-"$VERSION".zip \ .genreleases/spec-kit-template-q-sh-"$VERSION".zip \ .genreleases/spec-kit-template-q-ps-"$VERSION".zip \ + .genreleases/spec-kit-template-bob-sh-"$VERSION".zip \ + .genreleases/spec-kit-template-bob-ps-"$VERSION".zip \ --title "Spec Kit Templates - $VERSION_NO_V" \ --notes-file release_notes.md diff --git a/.github/workflows/scripts/create-release-packages.sh b/.github/workflows/scripts/create-release-packages.sh index f9d3b1ae..bd341ea5 100644 --- a/.github/workflows/scripts/create-release-packages.sh +++ b/.github/workflows/scripts/create-release-packages.sh @@ -186,13 +186,16 @@ build_variant() { q) mkdir -p "$base_dir/.amazonq/prompts" generate_commands q md "\$ARGUMENTS" "$base_dir/.amazonq/prompts" "$script" ;; + bob) + mkdir -p "$base_dir/.bob/commands" + generate_commands bob md "\$ARGUMENTS" "$base_dir/.bob/commands" "$script" ;; esac ( cd "$base_dir" && zip -r "../spec-kit-template-${agent}-${script}-${NEW_VERSION}.zip" . ) echo "Created $GENRELEASES_DIR/spec-kit-template-${agent}-${script}-${NEW_VERSION}.zip" } # Determine agent list -ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf codex kilocode auggie roo codebuddy amp q) +ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf codex kilocode auggie roo codebuddy amp q bob) ALL_SCRIPTS=(sh ps) norm_list() { diff --git a/AGENTS.md b/AGENTS.md index d34efb67..1c827497 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,6 +45,7 @@ Specify supports multiple AI agents by generating agent-specific command files a | **CodeBuddy CLI** | `.codebuddy/commands/` | Markdown | `codebuddy` | CodeBuddy CLI | | **Amazon Q Developer CLI** | `.amazonq/prompts/` | Markdown | `q` | Amazon Q Developer CLI | | **Amp** | `.agents/commands/` | Markdown | `amp` | Amp CLI | +| **IBM Bob** | `.bob/commands/` | Markdown | N/A (IDE-based) | IBM Bob IDE | ### Step-by-Step Integration Guide @@ -318,12 +319,13 @@ Work within integrated development environments: - **GitHub Copilot**: Built into VS Code/compatible editors - **Windsurf**: Built into Windsurf IDE +- **IBM Bob**: Built into IBM Bob IDE ## Command File Formats ### Markdown Format -Used by: Claude, Cursor, opencode, Windsurf, Amazon Q Developer, Amp +Used by: Claude, Cursor, opencode, Windsurf, Amazon Q Developer, Amp, IBM Bob ```markdown --- diff --git a/README.md b/README.md index 1c7dda21..87f31d16 100644 --- a/README.md +++ b/README.md @@ -150,6 +150,7 @@ Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.c | [Codex CLI](https://github.com/openai/codex) | ✅ | | | [Amazon Q Developer CLI](https://aws.amazon.com/developer/learning/q-developer-cli/) | ⚠️ | Amazon Q Developer CLI [does not support](https://github.com/aws/amazon-q-developer-cli/issues/3064) custom arguments for slash commands. | | [Amp](https://ampcode.com/) | ✅ | | +| [IBM Bob](https://www.ibm.com/products/bob) | ✅ | IDE-based agent with slash command support | ## 🔧 Specify CLI Reference @@ -167,7 +168,7 @@ The `specify` command supports the following options: | 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: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, `codebuddy`, `amp`, or `q` | +| `--ai` | Option | AI assistant to use: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, `codebuddy`, `amp`, `q`, or `bob` | | `--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 | @@ -195,6 +196,9 @@ specify init my-project --ai windsurf # Initialize with Amp support specify init my-project --ai amp +# Initialize with IBM Bob support +specify init my-project --ai bob + # Initialize with PowerShell scripts (Windows/cross-platform) specify init my-project --ai copilot --script ps diff --git a/scripts/bash/update-agent-context.sh b/scripts/bash/update-agent-context.sh index 2a44c68a..8c685b8c 100644 --- a/scripts/bash/update-agent-context.sh +++ b/scripts/bash/update-agent-context.sh @@ -72,6 +72,7 @@ ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md" CODEBUDDY_FILE="$REPO_ROOT/CODEBUDDY.md" AMP_FILE="$REPO_ROOT/AGENTS.md" Q_FILE="$REPO_ROOT/AGENTS.md" +BOB_FILE="$REPO_ROOT/AGENTS.md" # Template file TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md" @@ -621,9 +622,12 @@ update_specific_agent() { q) update_agent_file "$Q_FILE" "Amazon Q Developer CLI" ;; + bob) + update_agent_file "$BOB_FILE" "IBM Bob" + ;; *) log_error "Unknown agent type '$agent_type'" - log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|amp|q" + log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|amp|q|bob" exit 1 ;; esac @@ -693,6 +697,11 @@ update_all_existing_agents() { found_agent=true fi + if [[ -f "$BOB_FILE" ]]; then + update_agent_file "$BOB_FILE" "IBM Bob" + found_agent=true + fi + # If no agent files exist, create a default Claude file if [[ "$found_agent" == false ]]; then log_info "No existing agent files found, creating default Claude file..." @@ -717,7 +726,7 @@ print_summary() { echo - log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|codebuddy|q]" + log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|codebuddy|q|bob]" } #============================================================================== diff --git a/scripts/powershell/update-agent-context.ps1 b/scripts/powershell/update-agent-context.ps1 index 695e28b8..7307285e 100644 --- a/scripts/powershell/update-agent-context.ps1 +++ b/scripts/powershell/update-agent-context.ps1 @@ -25,7 +25,7 @@ Relies on common helper functions in common.ps1 #> param( [Parameter(Position=0)] - [ValidateSet('claude','gemini','copilot','cursor-agent','qwen','opencode','codex','windsurf','kilocode','auggie','roo','codebuddy','amp','q')] + [ValidateSet('claude','gemini','copilot','cursor-agent','qwen','opencode','codex','windsurf','kilocode','auggie','roo','codebuddy','amp','q','bob')] [string]$AgentType ) @@ -57,6 +57,7 @@ $ROO_FILE = Join-Path $REPO_ROOT '.roo/rules/specify-rules.md' $CODEBUDDY_FILE = Join-Path $REPO_ROOT 'CODEBUDDY.md' $AMP_FILE = Join-Path $REPO_ROOT 'AGENTS.md' $Q_FILE = Join-Path $REPO_ROOT 'AGENTS.md' +$BOB_FILE = Join-Path $REPO_ROOT 'AGENTS.md' $TEMPLATE_FILE = Join-Path $REPO_ROOT '.specify/templates/agent-file-template.md' @@ -382,7 +383,8 @@ function Update-SpecificAgent { 'codebuddy' { Update-AgentFile -TargetFile $CODEBUDDY_FILE -AgentName 'CodeBuddy CLI' } 'amp' { Update-AgentFile -TargetFile $AMP_FILE -AgentName 'Amp' } 'q' { Update-AgentFile -TargetFile $Q_FILE -AgentName 'Amazon Q Developer CLI' } - default { Write-Err "Unknown agent type '$Type'"; Write-Err 'Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|q'; return $false } + 'bob' { Update-AgentFile -TargetFile $BOB_FILE -AgentName 'IBM Bob' } + default { Write-Err "Unknown agent type '$Type'"; Write-Err 'Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|q|bob'; return $false } } } @@ -401,6 +403,7 @@ function Update-AllExistingAgents { if (Test-Path $ROO_FILE) { if (-not (Update-AgentFile -TargetFile $ROO_FILE -AgentName 'Roo Code')) { $ok = $false }; $found = $true } if (Test-Path $CODEBUDDY_FILE) { if (-not (Update-AgentFile -TargetFile $CODEBUDDY_FILE -AgentName 'CodeBuddy CLI')) { $ok = $false }; $found = $true } if (Test-Path $Q_FILE) { if (-not (Update-AgentFile -TargetFile $Q_FILE -AgentName 'Amazon Q Developer CLI')) { $ok = $false }; $found = $true } + if (Test-Path $BOB_FILE) { if (-not (Update-AgentFile -TargetFile $BOB_FILE -AgentName 'IBM Bob')) { $ok = $false }; $found = $true } if (-not $found) { Write-Info 'No existing agent files found, creating default Claude file...' if (-not (Update-AgentFile -TargetFile $CLAUDE_FILE -AgentName 'Claude Code')) { $ok = $false } @@ -415,7 +418,7 @@ function Print-Summary { if ($NEW_FRAMEWORK) { Write-Host " - Added framework: $NEW_FRAMEWORK" } if ($NEW_DB -and $NEW_DB -ne 'N/A') { Write-Host " - Added database: $NEW_DB" } Write-Host '' - Write-Info 'Usage: ./update-agent-context.ps1 [-AgentType claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|q]' + Write-Info 'Usage: ./update-agent-context.ps1 [-AgentType claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|q|bob]' } function Main { diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py index a33a1c61..0637b1ee 100644 --- a/src/specify_cli/__init__.py +++ b/src/specify_cli/__init__.py @@ -150,6 +150,12 @@ AGENT_CONFIG = { "install_url": "https://ampcode.com/manual#install", "requires_cli": True, }, + "bob": { + "name": "IBM Bob", + "folder": ".bob/", + "install_url": None, # IDE-based + "requires_cli": False, + }, } SCRIPT_TYPE_CHOICES = {"sh": "POSIX Shell (bash/zsh)", "ps": "PowerShell"} @@ -865,7 +871,7 @@ def ensure_executable_scripts(project_path: Path, tracker: StepTracker | None = @app.command() def init( project_name: str = typer.Argument(None, help="Name for your new project directory (optional if using --here, or use '.' for current directory)"), - ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, codebuddy, amp, or q"), + ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, codebuddy, amp, q, or bob"), 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"), no_git: bool = typer.Option(False, "--no-git", help="Skip git repository initialization"), From 537f349f1b46cc09c0171f874b5717924c1b8dd2 Mon Sep 17 00:00:00 2001 From: Vincent Burckhardt Date: Sat, 15 Nov 2025 20:49:08 +0000 Subject: [PATCH 2/5] feat: add bob to new update-agent-context.ps1 + consistency in comments --- .github/workflows/scripts/create-release-packages.ps1 | 8 ++++++-- .github/workflows/scripts/create-release-packages.sh | 2 +- scripts/bash/update-agent-context.sh | 2 +- scripts/powershell/update-agent-context.ps1 | 2 +- 4 files changed, 9 insertions(+), 5 deletions(-) diff --git a/.github/workflows/scripts/create-release-packages.ps1 b/.github/workflows/scripts/create-release-packages.ps1 index f935dbe8..d5f006b1 100644 --- a/.github/workflows/scripts/create-release-packages.ps1 +++ b/.github/workflows/scripts/create-release-packages.ps1 @@ -14,7 +14,7 @@ .PARAMETER Agents Comma or space separated subset of agents to build (default: all) - Valid agents: claude, gemini, copilot, cursor-agent, qwen, opencode, windsurf, codex, kilocode, auggie, roo, codebuddy, amp, q + Valid agents: claude, gemini, copilot, cursor-agent, qwen, opencode, windsurf, codex, kilocode, auggie, roo, codebuddy, amp, q, bob .PARAMETER Scripts Comma or space separated subset of script types to build (default: both) @@ -339,6 +339,10 @@ function Build-Variant { $cmdDir = Join-Path $baseDir ".amazonq/prompts" Generate-Commands -Agent 'q' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script } + 'bob' { + $cmdDir = Join-Path $baseDir ".bob/commands" + Generate-Commands -Agent 'bob' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script + } } # Create zip archive @@ -348,7 +352,7 @@ function Build-Variant { } # Define all agents and scripts -$AllAgents = @('claude', 'gemini', 'copilot', 'cursor-agent', 'qwen', 'opencode', 'windsurf', 'codex', 'kilocode', 'auggie', 'roo', 'codebuddy', 'amp', 'q') +$AllAgents = @('claude', 'gemini', 'copilot', 'cursor-agent', 'qwen', 'opencode', 'windsurf', 'codex', 'kilocode', 'auggie', 'roo', 'codebuddy', 'amp', 'q', 'bob') $AllScripts = @('sh', 'ps') function Normalize-List { diff --git a/.github/workflows/scripts/create-release-packages.sh b/.github/workflows/scripts/create-release-packages.sh index 901f793f..e8cb3a0a 100755 --- a/.github/workflows/scripts/create-release-packages.sh +++ b/.github/workflows/scripts/create-release-packages.sh @@ -6,7 +6,7 @@ set -euo pipefail # Usage: .github/workflows/scripts/create-release-packages.sh # Version argument should include leading 'v'. # Optionally set AGENTS and/or SCRIPTS env vars to limit what gets built. -# AGENTS : space or comma separated subset of: claude gemini copilot cursor-agent qwen opencode windsurf codex amp shai (default: all) +# AGENTS : space or comma separated subset of: claude gemini copilot cursor-agent qwen opencode windsurf codex amp shai bob (default: all) # SCRIPTS : space or comma separated subset of: sh ps (default: both) # Examples: # AGENTS=claude SCRIPTS=sh $0 v0.2.0 diff --git a/scripts/bash/update-agent-context.sh b/scripts/bash/update-agent-context.sh index 1e552b18..ff40c192 100644 --- a/scripts/bash/update-agent-context.sh +++ b/scripts/bash/update-agent-context.sh @@ -35,7 +35,7 @@ # - Creates default Claude file if no agent files exist # # Usage: ./update-agent-context.sh [agent_type] -# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|shai|q +# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|shai|q|bob # Leave empty to update all existing agent files set -e diff --git a/scripts/powershell/update-agent-context.ps1 b/scripts/powershell/update-agent-context.ps1 index c4525c02..e887b2b5 100644 --- a/scripts/powershell/update-agent-context.ps1 +++ b/scripts/powershell/update-agent-context.ps1 @@ -9,7 +9,7 @@ Mirrors the behavior of scripts/bash/update-agent-context.sh: 2. Plan Data Extraction 3. Agent File Management (create from template or update existing) 4. Content Generation (technology stack, recent changes, timestamp) - 5. Multi-Agent Support (claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, roo, codebuddy, amp, shai, q) + 5. Multi-Agent Support (claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, roo, codebuddy, amp, shai, q, bob) .PARAMETER AgentType Optional agent key to update a single agent. If omitted, updates all existing agent files (creating a default Claude file if none exist). From 71a20eb787545761374b919970dbf0d911b667c4 Mon Sep 17 00:00:00 2001 From: Andy Warner Date: Wed, 19 Nov 2025 14:20:21 -0700 Subject: [PATCH 3/5] Update supported AI agents in README.md Add Jules and change the table to alphabetical order by agent because the table is likely to grow. --- README.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index c3dcdf26..380a90b6 100644 --- a/README.md +++ b/README.md @@ -136,21 +136,23 @@ Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.c | Agent | Support | Notes | |-----------------------------------------------------------|---------|---------------------------------------------------| -| [Claude Code](https://www.anthropic.com/claude-code) | ✅ | | -| [GitHub Copilot](https://code.visualstudio.com/) | ✅ | | -| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✅ | | -| [Cursor](https://cursor.sh/) | ✅ | | -| [Qwen Code](https://github.com/QwenLM/qwen-code) | ✅ | | -| [opencode](https://opencode.ai/) | ✅ | | -| [Windsurf](https://windsurf.com/) | ✅ | | -| [Kilo Code](https://github.com/Kilo-Org/kilocode) | ✅ | | -| [Auggie CLI](https://docs.augmentcode.com/cli/overview) | ✅ | | -| [CodeBuddy CLI](https://www.codebuddy.ai/cli) | ✅ | | -| [Roo Code](https://roocode.com/) | ✅ | | -| [Codex CLI](https://github.com/openai/codex) | ✅ | | | [Amazon Q Developer CLI](https://aws.amazon.com/developer/learning/q-developer-cli/) | ⚠️ | Amazon Q Developer CLI [does not support](https://github.com/aws/amazon-q-developer-cli/issues/3064) custom arguments for slash commands. | | [Amp](https://ampcode.com/) | ✅ | | +| [Auggie CLI](https://docs.augmentcode.com/cli/overview) | ✅ | | +| [Claude Code](https://www.anthropic.com/claude-code) | ✅ | | +| [CodeBuddy CLI](https://www.codebuddy.ai/cli) | ✅ | | +| [Codex CLI](https://github.com/openai/codex) | ✅ | | +| [Cursor](https://cursor.sh/) | ✅ | | +| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✅ | | +| [GitHub Copilot](https://code.visualstudio.com/) | ✅ | | +| [Jules](https://jules.google.com/) | ✅ | | +| [Kilo Code](https://github.com/Kilo-Org/kilocode) | ✅ | | +| [opencode](https://opencode.ai/) | ✅ | | +| [Qwen Code](https://github.com/QwenLM/qwen-code) | ✅ | | +| [Roo Code](https://roocode.com/) | ✅ | | | [SHAI (OVHcloud)](https://github.com/ovh/shai) | ✅ | | +| [Windsurf](https://windsurf.com/) | ✅ | | + ## 🔧 Specify CLI Reference From 41a9fc885965191f43cf4f48ed73e6b084acf939 Mon Sep 17 00:00:00 2001 From: Ashley Childress <6563688+anchildress1@users.noreply.github.com> Date: Sun, 23 Nov 2025 04:22:21 -0500 Subject: [PATCH 4/5] docs: add constitution step to quickstart guide (fixes #906) --- docs/quickstart.md | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index a97c9fe1..5f45fc0c 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -4,7 +4,7 @@ This guide will help you get started with Spec-Driven Development using Spec Kit > NEW: All automation scripts now provide both Bash (`.sh`) and PowerShell (`.ps1`) variants. The `specify` CLI auto-selects based on OS unless you pass `--script sh|ps`. -## The 4-Step Process +## The 5-Step Process ### 1. Install Specify @@ -21,7 +21,15 @@ uvx --from git+https://github.com/github/spec-kit.git specify init --script sh # Force POSIX shell ``` -### 2. Create the Spec +### 2. Define Your Constitution + +Use the `/speckit.constitution` command to establish the core rules and principles for your project. This ensures all future code and specifications adhere to your project's standards. + +```bash +/speckit.constitution +``` + +### 3. Create the Spec Use the `/speckit.specify` command to describe what you want to build. Focus on the **what** and **why**, not the tech stack. @@ -29,7 +37,7 @@ Use the `/speckit.specify` command to describe what you want to build. Focus on /speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface. ``` -### 3. Create a Technical Implementation Plan +### 4. Create a Technical Implementation Plan Use the `/speckit.plan` command to provide your tech stack and architecture choices. @@ -37,7 +45,7 @@ Use the `/speckit.plan` command to provide your tech stack and architecture choi /speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database. ``` -### 4. Break Down and Implement +### 5. Break Down and Implement Use `/speckit.tasks` to create an actionable task list, then ask your agent to implement the feature. @@ -45,7 +53,15 @@ Use `/speckit.tasks` to create an actionable task list, then ask your agent to i Here's a complete example of building a team productivity platform: -### Step 1: Define Requirements with `/speckit.specify` +### Step 1: Define Constitution + +Initialize the project's constitution to set ground rules: + +```bash +/speckit.constitution +``` + +### Step 2: Define Requirements with `/speckit.specify` ```text Develop Taskify, a team productivity platform. It should allow users to create projects, add team members, @@ -66,7 +82,7 @@ see yours. You can edit any comments that you make, but you can't edit comments delete any comments that you made, but you can't delete comments anybody else made. ``` -### Step 2: Refine the Specification +### Step 3: Refine the Specification After the initial specification is created, clarify any missing requirements: @@ -82,7 +98,7 @@ Also validate the specification checklist: Read the review and acceptance checklist, and check off each item in the checklist if the feature spec meets the criteria. Leave it empty if it does not. ``` -### Step 3: Generate Technical Plan with `/speckit.plan` +### Step 4: Generate Technical Plan with `/speckit.plan` Be specific about your tech stack and technical requirements: @@ -92,7 +108,7 @@ Blazor server with drag-and-drop task boards, real-time updates. There should be tasks API, and a notifications API. ``` -### Step 4: Validate and Implement +### Step 5: Validate and Implement Have your AI agent audit the implementation plan: From bb21eedabcc5e8e6be865df1d7fd0e2ac020076e Mon Sep 17 00:00:00 2001 From: Ashley Childress <6563688+anchildress1@users.noreply.github.com> Date: Sun, 23 Nov 2025 14:48:35 -0500 Subject: [PATCH 5/5] docs: Enhance quickstart guide with admonitions and examples - Convert blockquotes to GFM admonitions for better visibility - Add current directory initialization example - Expand process to 6 steps with clarify, analyze, checklist, implement - Update example with separate clarify commands - Add proper links in Next Steps Fixes #906, #472 Generated-by: GitHub Copilot Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com> --- docs/quickstart.md | 127 +++++++++++++++++++++++++++------------------ 1 file changed, 76 insertions(+), 51 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 5f45fc0c..4d3b863b 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -2,16 +2,24 @@ This guide will help you get started with Spec-Driven Development using Spec Kit. -> NEW: All automation scripts now provide both Bash (`.sh`) and PowerShell (`.ps1`) variants. The `specify` CLI auto-selects based on OS unless you pass `--script sh|ps`. +> [!NOTE] +> All automation scripts now provide both Bash (`.sh`) and PowerShell (`.ps1`) variants. The `specify` CLI auto-selects based on OS unless you pass `--script sh|ps`. -## The 5-Step Process +## The 6-Step Process -### 1. Install Specify +> [!TIP] +> **Context Awareness**: Spec Kit commands automatically detect the active feature based on your current Git branch (e.g., `001-feature-name`). To switch between different specifications, simply switch Git branches. -Initialize your project depending on the coding agent you're using: +### Step 1: Install Specify + +**In your terminal**, run the `specify` CLI command to initialize your project: ```bash +# Create a new project directory uvx --from git+https://github.com/github/spec-kit.git specify init + +# OR initialize in the current directory +uvx --from git+https://github.com/github/spec-kit.git specify init . ``` Pick script type explicitly (optional): @@ -21,33 +29,57 @@ uvx --from git+https://github.com/github/spec-kit.git specify init --script sh # Force POSIX shell ``` -### 2. Define Your Constitution +### Step 2: Define Your Constitution -Use the `/speckit.constitution` command to establish the core rules and principles for your project. This ensures all future code and specifications adhere to your project's standards. +**In your AI Agent's chat interface**, use the `/speckit.constitution` slash command to establish the core rules and principles for your project. You should provide your project's specific principles as arguments. -```bash -/speckit.constitution +```markdown +/speckit.constitution This project follows a "Library-First" approach. All features must be implemented as standalone libraries first. We use TDD strictly. We prefer functional programming patterns. ``` -### 3. Create the Spec +### Step 3: Create the Spec -Use the `/speckit.specify` command to describe what you want to build. Focus on the **what** and **why**, not the tech stack. +**In the chat**, use the `/speckit.specify` slash command to describe what you want to build. Focus on the **what** and **why**, not the tech stack. -```bash +```markdown /speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface. ``` -### 4. Create a Technical Implementation Plan +### Step 4: Refine the Spec -Use the `/speckit.plan` command to provide your tech stack and architecture choices. +**In the chat**, use the `/speckit.clarify` slash command to identify and resolve ambiguities in your specification. You can provide specific focus areas as arguments. ```bash +/speckit.clarify Focus on security and performance requirements. +``` + +### Step 5: Create a Technical Implementation Plan + +**In the chat**, use the `/speckit.plan` slash command to provide your tech stack and architecture choices. + +```markdown /speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database. ``` -### 5. Break Down and Implement +### Step 6: Break Down and Implement -Use `/speckit.tasks` to create an actionable task list, then ask your agent to implement the feature. +**In the chat**, use the `/speckit.tasks` slash command to create an actionable task list. + +```markdown +/speckit.tasks +``` + +Optionally, validate the plan with `/speckit.analyze`: + +```markdown +/speckit.analyze +``` + +Then, use the `/speckit.implement` slash command to execute the plan. + +```markdown +/speckit.implement +``` ## Detailed Example: Building Taskify @@ -57,8 +89,8 @@ Here's a complete example of building a team productivity platform: Initialize the project's constitution to set ground rules: -```bash -/speckit.constitution +```markdown +/speckit.constitution Taskify is a "Security-First" application. All user inputs must be validated. We use a microservices architecture. Code must be fully documented. ``` ### Step 2: Define Requirements with `/speckit.specify` @@ -70,58 +102,51 @@ let's call it "Create Taskify," let's have multiple users but the users will be I want five users in two different categories, one product manager and four engineers. Let's create three different sample projects. Let's have the standard Kanban columns for the status of each task, such as "To Do," "In Progress," "In Review," and "Done." There will be no login for this application as this is just the very -first testing thing to ensure that our basic features are set up. For each task in the UI for a task card, -you should be able to change the current status of the task between the different columns in the Kanban work board. -You should be able to leave an unlimited number of comments for a particular card. You should be able to, from that task -card, assign one of the valid users. When you first launch Taskify, it's going to give you a list of the five users to pick -from. There will be no password required. When you click on a user, you go into the main view, which displays the list of -projects. When you click on a project, you open the Kanban board for that project. You're going to see the columns. -You'll be able to drag and drop cards back and forth between different columns. You will see any cards that are -assigned to you, the currently logged in user, in a different color from all the other ones, so you can quickly -see yours. You can edit any comments that you make, but you can't edit comments that other people made. You can -delete any comments that you made, but you can't delete comments anybody else made. +first testing thing to ensure that our basic features are set up. ``` ### Step 3: Refine the Specification -After the initial specification is created, clarify any missing requirements: +Use the `/speckit.clarify` command to interactively resolve any ambiguities in your specification. You can also provide specific details you want to ensure are included. -```text -For each sample project or project that you create there should be a variable number of tasks between 5 and 15 -tasks for each one randomly distributed into different states of completion. Make sure that there's at least -one task in each stage of completion. +```bash +/speckit.clarify I want to clarify the task card details. For each task in the UI for a task card, you should be able to change the current status of the task between the different columns in the Kanban work board. You should be able to leave an unlimited number of comments for a particular card. You should be able to, from that task card, assign one of the valid users. ``` -Also validate the specification checklist: +You can continue to refine the spec with more details using `/speckit.clarify`: -```text -Read the review and acceptance checklist, and check off each item in the checklist if the feature spec meets the criteria. Leave it empty if it does not. +```bash +/speckit.clarify When you first launch Taskify, it's going to give you a list of the five users to pick from. There will be no password required. When you click on a user, you go into the main view, which displays the list of projects. When you click on a project, you open the Kanban board for that project. You're going to see the columns. You'll be able to drag and drop cards back and forth between different columns. You will see any cards that are assigned to you, the currently logged in user, in a different color from all the other ones, so you can quickly see yours. You can edit any comments that you make, but you can't edit comments that other people made. You can delete any comments that you made, but you can't delete comments anybody else made. ``` -### Step 4: Generate Technical Plan with `/speckit.plan` +### Step 4: Validate the Spec + +Validate the specification checklist using the `/speckit.checklist` command: + +```bash +/speckit.checklist +``` + +### Step 5: Generate Technical Plan with `/speckit.plan` Be specific about your tech stack and technical requirements: -```text -We are going to generate this using .NET Aspire, using Postgres as the database. The frontend should use -Blazor server with drag-and-drop task boards, real-time updates. There should be a REST API created with a projects API, -tasks API, and a notifications API. +```bash +/speckit.plan We are going to generate this using .NET Aspire, using Postgres as the database. The frontend should use Blazor server with drag-and-drop task boards, real-time updates. There should be a REST API created with a projects API, tasks API, and a notifications API. ``` -### Step 5: Validate and Implement +### Step 6: Validate and Implement -Have your AI agent audit the implementation plan: +Have your AI agent audit the implementation plan using `/speckit.analyze`: -```text -Now I want you to go and audit the implementation plan and the implementation detail files. -Read through it with an eye on determining whether or not there is a sequence of tasks that you need -to be doing that are obvious from reading this. Because I don't know if there's enough here. +```bash +/speckit.analyze ``` Finally, implement the solution: -```text -implement specs/002-create-taskify/plan.md +```bash +/speckit.implement ``` ## Key Principles @@ -134,6 +159,6 @@ implement specs/002-create-taskify/plan.md ## Next Steps -- Read the complete methodology for in-depth guidance -- Check out more examples in the repository -- Explore the source code on GitHub +- Read the [complete methodology](../spec-driven.md) for in-depth guidance +- Check out [more examples](../templates) in the repository +- Explore the [source code on GitHub](https://github.com/github/spec-kit)