Skip to content

Commit 8fb4dd5

Browse files
authored
Merge upstream pull request github#17 from panaversity/merge-upstream-v0.0.19
2 parents da1594e + 28f6eec commit 8fb4dd5

16 files changed

Lines changed: 573 additions & 421 deletions

File tree

‎.github/workflows/scripts/create-github-release.sh‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ gh release create "$VERSION" \
3838
.genreleases/spec-kit-template-auggie-ps-"$VERSION".zip \
3939
.genreleases/spec-kit-template-roo-sh-"$VERSION".zip \
4040
.genreleases/spec-kit-template-roo-ps-"$VERSION".zip \
41+
.genreleases/spec-kit-template-codebuddy-sh-"$VERSION".zip \
42+
.genreleases/spec-kit-template-codebuddy-ps-"$VERSION".zip \
4143
.genreleases/spec-kit-template-q-sh-"$VERSION".zip \
4244
.genreleases/spec-kit-template-q-ps-"$VERSION".zip \
4345
--title "Spec Kit Plus Templates - $VERSION_NO_V" \

‎.github/workflows/scripts/create-release-packages.sh‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,7 @@ generate_commands() {
106106

107107
case $ext in
108108
toml)
109+
body=$(printf '%s\n' "$body" | sed 's/\\/\\\\/g')
109110
{ echo "description = \"$description\""; echo; echo "prompt = \"\"\""; echo "$body"; echo "\"\"\""; } > "$output_dir/sp.$name.$ext" ;;
110111
md)
111112
echo "$body" > "$output_dir/sp.$name.$ext" ;;
@@ -310,6 +311,10 @@ This file is generated during init for the selected agent.
310311
mkdir -p "$base_dir/.roo/commands"
311312
generate_commands roo md "\$ARGUMENTS" "$base_dir/.roo/commands" "$script"
312313
generate_agent_rules roo "$base_dir" ;;
314+
codebuddy)
315+
mkdir -p "$base_dir/.codebuddy/commands"
316+
generate_commands codebuddy md "\$ARGUMENTS" "$base_dir/.codebuddy/commands" "$script" ;;
317+
313318
q)
314319
mkdir -p "$base_dir/.amazonq/prompts"
315320
generate_commands q md "\$ARGUMENTS" "$base_dir/.amazonq/prompts" "$script"
@@ -320,10 +325,9 @@ This file is generated during init for the selected agent.
320325
}
321326

322327
# Determine agent list
323-
ALL_AGENTS=(claude gemini copilot cursor qwen opencode windsurf codex kilocode auggie roo q)
328+
ALL_AGENTS=(claude gemini copilot cursor qwen opencode windsurf codex kilocode auggie roo codebuddy q)
324329
ALL_SCRIPTS=(sh ps)
325330

326-
327331
norm_list() {
328332
# convert comma+space separated -> space separated unique while preserving order of first occurrence
329333
tr ',\n' ' ' | awk '{for(i=1;i<=NF;i++){if(!seen[$i]++){printf((out?" ":"") $i)}}}END{printf("\n")}'

‎AGENTS.md‎

Lines changed: 92 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -111,56 +111,57 @@ Specify supports multiple AI agents by generating agent-specific command files a
111111
| **Cursor** | `.cursor/commands/` | Markdown | `cursor-agent` | Cursor CLI |
112112
| **Qwen Code** | `.qwen/commands/` | TOML | `qwen` | Alibaba's Qwen Code CLI |
113113
| **opencode** | `.opencode/command/` | Markdown | `opencode` | opencode CLI |
114+
| **Codex CLI** | `.codex/commands/` | Markdown | `codex` | Codex CLI |
114115
| **Windsurf** | `.windsurf/workflows/` | Markdown | N/A (IDE-based) | Windsurf IDE workflows |
116+
| **Kilo Code** | `.kilocode/rules/` | Markdown | N/A (IDE-based) | Kilo Code IDE |
117+
| **Auggie CLI** | `.augment/rules/` | Markdown | `auggie` | Auggie CLI |
118+
| **Roo Code** | `.roo/rules/` | Markdown | N/A (IDE-based) | Roo Code IDE |
119+
| **CodeBuddy** | `.codebuddy/commands/` | Markdown | `codebuddy` | CodeBuddy |
115120
| **Amazon Q Developer CLI** | `.amazonq/prompts/` | Markdown | `q` | Amazon Q Developer CLI |
116121

117-
118122
### Step-by-Step Integration Guide
119123

120-
Follow these steps to add a new agent (using Windsurf as an example):
124+
Follow these steps to add a new agent (using a hypothetical new agent as an example):
125+
126+
#### 1. Add to AGENT_CONFIG
121127

122-
#### 1. Update AI_CHOICES Constant
128+
**IMPORTANT**: Use the actual CLI tool name as the key, not a shortened version.
123129

124-
Add the new agent to the `AI_CHOICES` dictionary in `src/specify_cli/__init__.py`:
130+
Add the new agent to the `AGENT_CONFIG` dictionary in `src/specify_cli/__init__.py`. This is the **single source of truth** for all agent metadata:
125131

126132
```python
127-
AI_CHOICES = {
128-
"copilot": "GitHub Copilot",
129-
"claude": "Claude Code",
130-
"gemini": "Gemini CLI",
131-
"cursor": "Cursor",
132-
"qwen": "Qwen Code",
133-
"opencode": "opencode",
134-
"windsurf": "Windsurf",
135-
"q": "Amazon Q Developer CLI" # Add new agent here
133+
AGENT_CONFIG = {
134+
# ... existing agents ...
135+
"new-agent-cli": { # Use the ACTUAL CLI tool name (what users type in terminal)
136+
"name": "New Agent Display Name",
137+
"folder": ".newagent/", # Directory for agent files
138+
"install_url": "https://example.com/install", # URL for installation docs (or None if IDE-based)
139+
"requires_cli": True, # True if CLI tool required, False for IDE-based agents
140+
},
136141
}
137142
```
138143

139-
Also update the `agent_folder_map` in the same file to include the new agent's folder for the security notice:
144+
**Key Design Principle**: The dictionary key should match the actual executable name that users install. For example:
145+
- ✅ Use `"cursor-agent"` because the CLI tool is literally called `cursor-agent`
146+
- ❌ Don't use `"cursor"` as a shortcut if the tool is `cursor-agent`
140147

141-
```python
142-
agent_folder_map = {
143-
"claude": ".claude/",
144-
"gemini": ".gemini/",
145-
"cursor": ".cursor/",
146-
"qwen": ".qwen/",
147-
"opencode": ".opencode/",
148-
"codex": ".codex/",
149-
"windsurf": ".windsurf/",
150-
"kilocode": ".kilocode/",
151-
"auggie": ".auggie/",
152-
"copilot": ".github/",
153-
"q": ".amazonq/" # Add new agent folder here
154-
}
155-
```
148+
This eliminates the need for special-case mappings throughout the codebase.
149+
150+
**Field Explanations**:
151+
- `name`: Human-readable display name shown to users
152+
- `folder`: Directory where agent-specific files are stored (relative to project root)
153+
- `install_url`: Installation documentation URL (set to `None` for IDE-based agents)
154+
- `requires_cli`: Whether the agent requires a CLI tool check during initialization
156155

157156
#### 2. Update CLI Help Text
158157

159-
Update all help text and examples to include the new agent:
158+
Update the `--ai` parameter help text in the `init()` command to include the new agent:
160159

161-
- Command option help: `--ai` parameter description
162-
- Function docstrings and examples
163-
- Error messages with agent lists
160+
```python
161+
ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, codebuddy, new-agent-cli, or q"),
162+
```
163+
164+
Also update any function docstrings, examples, and error messages that list available agents.
164165

165166
#### 3. Update README Documentation
166167

@@ -264,17 +265,65 @@ elif selected_ai == "windsurf":
264265
agent_tool_missing = True
265266
```
266267

267-
**Note**: Skip CLI checks for IDE-based agents (Copilot, Windsurf).
268+
**Note**: CLI tool checks are now handled automatically based on the `requires_cli` field in AGENT_CONFIG. No additional code changes needed in the `check()` or `init()` commands - they automatically loop through AGENT_CONFIG and check tools as needed.
269+
270+
## Important Design Decisions
271+
272+
### Using Actual CLI Tool Names as Keys
273+
274+
**CRITICAL**: When adding a new agent to AGENT_CONFIG, always use the **actual executable name** as the dictionary key, not a shortened or convenient version.
275+
276+
**Why this matters:**
277+
- The `check_tool()` function uses `shutil.which(tool)` to find executables in the system PATH
278+
- If the key doesn't match the actual CLI tool name, you'll need special-case mappings throughout the codebase
279+
- This creates unnecessary complexity and maintenance burden
280+
281+
**Example - The Cursor Lesson:**
282+
283+
❌ **Wrong approach** (requires special-case mapping):
284+
```python
285+
AGENT_CONFIG = {
286+
"cursor": { # Shorthand that doesn't match the actual tool
287+
"name": "Cursor",
288+
# ...
289+
}
290+
}
291+
292+
# Then you need special cases everywhere:
293+
cli_tool = agent_key
294+
if agent_key == "cursor":
295+
cli_tool = "cursor-agent" # Map to the real tool name
296+
```
297+
298+
✅ **Correct approach** (no mapping needed):
299+
```python
300+
AGENT_CONFIG = {
301+
"cursor-agent": { # Matches the actual executable name
302+
"name": "Cursor",
303+
# ...
304+
}
305+
}
306+
307+
# No special cases needed - just use agent_key directly!
308+
```
309+
310+
**Benefits of this approach:**
311+
- Eliminates special-case logic scattered throughout the codebase
312+
- Makes the code more maintainable and easier to understand
313+
- Reduces the chance of bugs when adding new agents
314+
- Tool checking "just works" without additional mappings
268315

269316
## Agent Categories
270317

271318
### CLI-Based Agents
319+
272320
Require a command-line tool to be installed:
273321
- **Claude Code**: `claude` CLI
274322
- **Gemini CLI**: `gemini` CLI
275323
- **Cursor**: `cursor-agent` CLI
276324
- **Qwen Code**: `qwen` CLI
277325
- **opencode**: `opencode` CLI
326+
- **CodeBuddy**: `codebuddy` CLI
278327

279328
### IDE-Based Agents
280329
Work within integrated development environments:
@@ -331,20 +380,23 @@ Different agents use different argument placeholders:
331380

332381
## Common Pitfalls
333382

334-
1. **Forgetting update scripts**: Both bash and PowerShell scripts must be updated
335-
2. **Missing CLI checks**: Only add for agents that actually have CLI tools
336-
3. **Wrong argument format**: Use correct placeholder format for each agent type
337-
4. **Directory naming**: Follow agent-specific conventions exactly
338-
5. **Help text inconsistency**: Update all user-facing text consistently
383+
1. **Using shorthand keys instead of actual CLI tool names**: Always use the actual executable name as the AGENT_CONFIG key (e.g., `"cursor-agent"` not `"cursor"`). This prevents the need for special-case mappings throughout the codebase.
384+
2. **Forgetting update scripts**: Both bash and PowerShell scripts must be updated when adding new agents.
385+
3. **Incorrect `requires_cli` value**: Set to `True` only for agents that actually have CLI tools to check; set to `False` for IDE-based agents.
386+
4. **Wrong argument format**: Use correct placeholder format for each agent type (`$ARGUMENTS` for Markdown, `{{args}}` for TOML).
387+
5. **Directory naming**: Follow agent-specific conventions exactly (check existing agents for patterns).
388+
6. **Help text inconsistency**: Update all user-facing text consistently (help strings, docstrings, README, error messages).
339389

340390
## Future Considerations
341391

342392
When adding new agents:
393+
343394
- Consider the agent's native command/workflow patterns
344395
- Ensure compatibility with the Spec-Driven Development process
345396
- Document any special requirements or limitations
346397
- Update this guide with lessons learned
398+
- Verify the actual CLI tool name before adding to AGENT_CONFIG
347399

348400
---
349401

350-
*This documentation should be updated whenever new agents are added to maintain accuracy and completeness.*
402+
*This documentation should be updated whenever new agents are added to maintain accuracy and completeness.*

‎README.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,12 @@ Use `specifyplus` or `sp` commands instead of `specify`.
5050
<strong>An effort to allow organizations to focus on product scenarios rather than writing undifferentiated code with the help of Spec-Driven Development.</strong>
5151
</p>
5252

53-
[![Release](https://github.com/github/spec-kit/actions/workflows/release.yml/badge.svg)](https://github.com/github/spec-kit/actions/workflows/release.yml)
53+
<p align="center">
54+
<a href="https://github.com/github/spec-kit/actions/workflows/release.yml"><img src="https://github.com/github/spec-kit/actions/workflows/release.yml/badge.svg" alt="Release"/></a>
55+
<a href="https://github.com/github/spec-kit/stargazers"><img src="https://img.shields.io/github/stars/github/spec-kit?style=social" alt="GitHub stars"/></a>
56+
<a href="https://github.com/github/spec-kit/blob/main/LICENSE"><img src="https://img.shields.io/github/license/github/spec-kit" alt="License"/></a>
57+
<a href="https://github.github.io/spec-kit/"><img src="https://img.shields.io/badge/docs-GitHub_Pages-blue" alt="Documentation"/></a>
58+
</p>
5459

5560
---
5661

@@ -199,6 +204,7 @@ Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.c
199204
| [Windsurf](https://windsurf.com/) | ✅ | |
200205
| [Kilo Code](https://github.com/Kilo-Org/kilocode) | ✅ | |
201206
| [Auggie CLI](https://docs.augmentcode.com/cli/overview) | ✅ | |
207+
| [CodeBuddy](https://www.codebuddy.ai/) | ✅ | |
202208
| [Roo Code](https://roocode.com/) | ✅ | |
203209
| [Codex CLI](https://github.com/openai/codex) | ✅ | |
204210
| [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. |
@@ -226,7 +232,7 @@ The `specify` command supports the following options:
226232
| Argument/Option | Type | Description |
227233
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
228234
| `<project-name>` | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory) |
229-
| `--ai` | Option | AI assistant to use: `claude`, `gemini`, `copilot`, `cursor`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, or `q` |
235+
| `--ai` | Option | AI assistant to use: `claude`, `gemini`, `copilot`, `cursor`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, `codebuddy`, or `q` |
230236
| `--script` | Option | Script variant to use: `sh` (bash/zsh) or `ps` (PowerShell) |
231237
| `--ignore-agent-tools` | Flag | Skip checks for AI agent tools like Claude Code |
232238
| `--no-git` | Flag | Skip git repository initialization |

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "specify-cli"
3-
version = "0.0.18"
3+
version = "0.0.19"
44
description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
55
requires-python = ">=3.11"
66
dependencies = [

‎scripts/bash/update-agent-context.sh‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
6969
KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
7070
AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
7171
ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
72+
CODEBUDDY_FILE="$REPO_ROOT/.codebuddy/rules/specify-rules.md"
7273
Q_FILE="$REPO_ROOT/AGENTS.md"
7374

7475
# Template file
@@ -581,6 +582,9 @@ update_specific_agent() {
581582
roo)
582583
update_agent_file "$ROO_FILE" "Roo Code"
583584
;;
585+
codebuddy)
586+
update_agent_file "$CODEBUDDY_FILE" "CodeBuddy"
587+
;;
584588
q)
585589
update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
586590
;;
@@ -646,6 +650,11 @@ update_all_existing_agents() {
646650
found_agent=true
647651
fi
648652

653+
if [[ -f "$CODEBUDDY_FILE" ]]; then
654+
update_agent_file "$CODEBUDDY_FILE" "CodeBuddy"
655+
found_agent=true
656+
fi
657+
649658
if [[ -f "$Q_FILE" ]]; then
650659
update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
651660
found_agent=true
@@ -674,7 +683,8 @@ print_summary() {
674683
fi
675684

676685
echo
677-
log_info "Usage: $0 [claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|q]"
686+
687+
log_info "Usage: $0 [claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|codebuddy|q]"
678688
}
679689

680690
#==============================================================================

‎scripts/powershell/update-agent-context.ps1‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Relies on common helper functions in common.ps1
2525
#>
2626
param(
2727
[Parameter(Position=0)]
28-
[ValidateSet('claude','gemini','copilot','cursor','qwen','opencode','codex','windsurf','kilocode','auggie','roo','q')]
28+
[ValidateSet('claude','gemini','copilot','cursor','qwen','opencode','codex','windsurf','kilocode','auggie','roo','codebuddy','q')]
2929
[string]$AgentType
3030
)
3131

@@ -54,6 +54,7 @@ $WINDSURF_FILE = Join-Path $REPO_ROOT '.windsurf/rules/specify-rules.md'
5454
$KILOCODE_FILE = Join-Path $REPO_ROOT '.kilocode/rules/specify-rules.md'
5555
$AUGGIE_FILE = Join-Path $REPO_ROOT '.augment/rules/specify-rules.md'
5656
$ROO_FILE = Join-Path $REPO_ROOT '.roo/rules/specify-rules.md'
57+
$CODEBUDDY_FILE = Join-Path $REPO_ROOT '.codebuddy/rules/specify-rules.md'
5758
$Q_FILE = Join-Path $REPO_ROOT 'AGENTS.md'
5859

5960
$TEMPLATE_FILE = Join-Path $REPO_ROOT '.specify/templates/agent-file-template.md'
@@ -377,8 +378,9 @@ function Update-SpecificAgent {
377378
'kilocode' { Update-AgentFile -TargetFile $KILOCODE_FILE -AgentName 'Kilo Code' }
378379
'auggie' { Update-AgentFile -TargetFile $AUGGIE_FILE -AgentName 'Auggie CLI' }
379380
'roo' { Update-AgentFile -TargetFile $ROO_FILE -AgentName 'Roo Code' }
381+
'codebuddy' { Update-AgentFile -TargetFile $CODEBUDDY_FILE -AgentName 'CodeBuddy' }
380382
'q' { Update-AgentFile -TargetFile $Q_FILE -AgentName 'Amazon Q Developer CLI' }
381-
default { Write-Err "Unknown agent type '$Type'"; Write-Err 'Expected: claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|roo|q'; return $false }
383+
default { Write-Err "Unknown agent type '$Type'"; Write-Err 'Expected: claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|q'; return $false }
382384
}
383385
}
384386

@@ -395,6 +397,7 @@ function Update-AllExistingAgents {
395397
if (Test-Path $KILOCODE_FILE) { if (-not (Update-AgentFile -TargetFile $KILOCODE_FILE -AgentName 'Kilo Code')) { $ok = $false }; $found = $true }
396398
if (Test-Path $AUGGIE_FILE) { if (-not (Update-AgentFile -TargetFile $AUGGIE_FILE -AgentName 'Auggie CLI')) { $ok = $false }; $found = $true }
397399
if (Test-Path $ROO_FILE) { if (-not (Update-AgentFile -TargetFile $ROO_FILE -AgentName 'Roo Code')) { $ok = $false }; $found = $true }
400+
if (Test-Path $CODEBUDDY_FILE) { if (-not (Update-AgentFile -TargetFile $CODEBUDDY_FILE -AgentName 'CodeBuddy')) { $ok = $false }; $found = $true }
398401
if (Test-Path $Q_FILE) { if (-not (Update-AgentFile -TargetFile $Q_FILE -AgentName 'Amazon Q Developer CLI')) { $ok = $false }; $found = $true }
399402
if (-not $found) {
400403
Write-Info 'No existing agent files found, creating default Claude file...'
@@ -410,7 +413,7 @@ function Print-Summary {
410413
if ($NEW_FRAMEWORK) { Write-Host " - Added framework: $NEW_FRAMEWORK" }
411414
if ($NEW_DB -and $NEW_DB -ne 'N/A') { Write-Host " - Added database: $NEW_DB" }
412415
Write-Host ''
413-
Write-Info 'Usage: ./update-agent-context.ps1 [-AgentType claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|roo|q]'
416+
Write-Info 'Usage: ./update-agent-context.ps1 [-AgentType claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|q]'
414417
}
415418

416419
function Main {

0 commit comments

Comments
 (0)