AGENTS.md

About Spec Kitty and Spec Kitty CLI

Spec Kitty is inspired by GitHub's Spec Kit. It continues to provide a comprehensive toolkit for implementing Spec-Driven Development (SDD) with clear, actionable specifications ahead of implementation.

Spec Kitty CLI is the command-line interface that bootstraps projects with the Spec Kitty framework. It sets up the necessary directory structures, templates, and AI agent integrations to support the Spec-Driven Development workflow.

Every command template leads with a discovery interview—the CLI will refuse to create specs or plans until the user answers its question set.

The toolkit supports multiple AI coding assistants, allowing teams to use their preferred tools while maintaining consistent project structure and development practices.

Task Lane Management (Work Packages)

Flat Structure: All work package (WP) files live in a flat tasks/ directory. Lane status is tracked only in frontmatter - files never move between subdirectories.

Current System (v0.9.0+)

kitty-specs/001-my-feature/tasks/
  ├── WP01-setup.md        (lane: "planned")
  ├── WP02-core.md         (lane: "doing")
  ├── WP03-tests.md        (lane: "for_review")
  └── WP04-docs.md         (lane: "done")

Key principles:

Lane is determined by lane: field in frontmatter (NOT directory location)
All WP files stay in flat tasks/ directory
Use Python CLI commands to update lanes (updates frontmatter + activity log)

Moving Work Packages Between Lanes

Use the workflow commands (lane transitions are automatic):

spec-kitty agent workflow implement WP01
spec-kitty agent workflow review WP01

The workflow commands:

Move planned → doing → for_review during implement
Move for_review → doing → planned/done during review
Update frontmatter and Activity Log
Keep files in the flat tasks/ directory

Workflow Commands (Recommended for Agents)

For implementation:

spec-kitty agent workflow implement [WP01]

Auto-detects first WP with lane: "planned" if no ID provided
Moves WP to lane: "doing" automatically
Displays full prompt with "WHEN YOU'RE DONE" instructions

For review:

spec-kitty agent workflow review [WP01]

Auto-detects first WP with lane: "for_review" if no ID provided
Moves WP to lane: "doing" automatically
Displays full prompt with review instructions

Other Task Commands

# List all work packages for current feature
spec-kitty agent tasks list-tasks

# List tasks in specific lane
spec-kitty agent tasks list-tasks --lane doing

# Add a history entry without changing lanes
spec-kitty agent tasks add-history WP01 --note "Progress update"

General practices

Any changes to __init__.py for the Spec Kitty CLI require a version rev in pyproject.toml and addition of entries to CHANGELOG.md.

Adding New Agent Support

This section explains how to add support for new AI agents/assistants to the Spec Kitty CLI. Use this guide as a reference when integrating new AI tools into the Spec-Driven Development workflow.

Overview

Spec Kitty CLI supports multiple AI agents by generating agent-specific command files and directory structures when initializing projects. Each agent has its own conventions for:

Command file formats (Markdown, TOML, etc.)
Directory structures (.claude/commands/, .windsurf/workflows/, etc.)
Command invocation patterns (slash commands, CLI tools, etc.)
Argument passing conventions ($ARGUMENTS, {{args}}, etc.)

Current Supported Agents

Agent	Directory	Format	CLI Tool	Description
Claude Code	`.claude/commands/`	Markdown	`claude`	Anthropic's Claude Code CLI
Gemini CLI	`.gemini/commands/`	TOML	`gemini`	Google's Gemini CLI
GitHub Copilot	`.github/prompts/`	Markdown	N/A (IDE-based)	GitHub Copilot in VS Code
Cursor	`.cursor/commands/`	Markdown	`cursor-agent`	Cursor CLI
Qwen Code	`.qwen/commands/`	TOML	`qwen`	Alibaba's Qwen Code CLI
opencode	`.opencode/command/`	Markdown	`opencode`	opencode CLI
Windsurf	`.windsurf/workflows/`	Markdown	N/A (IDE-based)	Windsurf IDE workflows
Amazon Q Developer CLI	`.amazonq/prompts/`	Markdown	`q`	Amazon Q Developer CLI

Step-by-Step Integration Guide

Follow these steps to add a new agent (using Windsurf as an example):

1. Update AI_CHOICES Constant

Add the new agent to the AI_CHOICES dictionary in src/specify_cli/__init__.py:

AI_CHOICES = {
    "copilot": "GitHub Copilot",
    "claude": "Claude Code", 
    "gemini": "Gemini CLI",
    "cursor": "Cursor",
    "qwen": "Qwen Code",
    "opencode": "opencode",
    "windsurf": "Windsurf",
    "q": "Amazon Q Developer CLI"  # Add new agent here
}

Also update the agent_folder_map in the same file to include the new agent's folder for the security notice:

agent_folder_map = {
    "claude": ".claude/",
    "gemini": ".gemini/",
    "cursor": ".cursor/",
    "qwen": ".qwen/",
    "opencode": ".opencode/",
    "codex": ".codex/",
    "windsurf": ".windsurf/",  
    "kilocode": ".kilocode/",
    "auggie": ".auggie/",
    "copilot": ".github/",
    "q": ".amazonq/" # Add new agent folder here
}

2. Update CLI Help Text

Update all help text and examples to include the new agent:

Command option help: --ai parameter description
Function docstrings and examples
Error messages with agent lists

3. Update README Documentation

Update the Supported AI Agents section in README.md to include the new agent:

Add the new agent to the table with appropriate support level (Full/Partial)
Include the agent's official website link
Add any relevant notes about the agent's implementation
Ensure the table formatting remains aligned and consistent

4. Update Release Package Script

Modify .github/workflows/scripts/create-release-packages.sh:

Add to ALL_AGENTS array:

ALL_AGENTS=(claude gemini copilot cursor qwen opencode windsurf q)

Add case statement for directory structure:

case $agent in
  # ... existing cases ...
  windsurf)
    mkdir -p "$base_dir/.windsurf/workflows"
    generate_commands windsurf md "\$ARGUMENTS" "$base_dir/.windsurf/workflows" "$script" ;;
esac

4. Update GitHub Release Script

Modify .github/workflows/scripts/create-github-release.sh to include the new agent's packages:

gh release create "$VERSION" \
  # ... existing packages ...
  .genreleases/spec-kitty-template-windsurf-sh-"$VERSION".zip \
  .genreleases/spec-kitty-template-windsurf-ps-"$VERSION".zip \
  # Add new agent packages here

5. Agent Context Management (v0.10.0+)

Note: As of v0.10.0, bash/PowerShell scripts were removed in favor of Python CLI commands.

Agent context is now managed via the Python CLI:

# Update agent context programmatically
spec-kitty agent context update

# Or handle during feature workflow via slash commands
# which automatically manage agent context

For adding new agent support, the key integration points are:

Add agent to AGENT_DIRS in src/specify_cli/upgrade/migrations/m_0_9_1_complete_lane_migration.py
Update init command to generate commands for the new agent
Create command templates if agent needs custom format (optional)

Most agents use the same command template format from .kittify/templates/command-templates/.

6. Update CLI Tool Checks (Optional)

For agents that require CLI tools, add checks in the check() command and agent validation:

# In check() command
tracker.add("windsurf", "Windsurf IDE (optional)")
windsurf_ok = check_tool_for_tracker("windsurf", "https://windsurf.com/", tracker)

# In init validation (only if CLI tool required)
elif selected_ai == "windsurf":
    if not check_tool("windsurf", "Install from: https://windsurf.com/"):
        console.print("[red]Error:[/red] Windsurf CLI is required for Windsurf projects")
        agent_tool_missing = True

Note: Skip CLI checks for IDE-based agents (Copilot, Windsurf).

Agent Categories

CLI-Based Agents

Require a command-line tool to be installed:

Claude Code: claude CLI
Gemini CLI: gemini CLI
Cursor: cursor-agent CLI
Qwen Code: qwen CLI
opencode: opencode CLI

IDE-Based Agents

Work within integrated development environments:

GitHub Copilot: Built into VS Code/compatible editors
Windsurf: Built into Windsurf IDE

Command File Formats

Markdown Format

Used by: Claude, Cursor, opencode, Windsurf, Amazon Q Developer

---
description: "Command description"
---

Command content with {SCRIPT} and $ARGUMENTS placeholders.

TOML Format

Used by: Gemini, Qwen

description = "Command description"

prompt = """
Command content with {SCRIPT} and {{args}} placeholders.
"""

Directory Conventions

CLI agents: Usually .<agent-name>/commands/
IDE agents: Follow IDE-specific patterns:
- Copilot: .github/prompts/
- Cursor: .cursor/commands/
- Windsurf: .windsurf/workflows/

Argument Patterns

Different agents use different argument placeholders:

Markdown/prompt-based: $ARGUMENTS
TOML-based: {{args}}
Script placeholders: {SCRIPT} (replaced with actual script path)
Agent placeholders: __AGENT__ (replaced with agent name)

Testing New Agent Integration

Build test: Run package creation script locally
CLI test: Test spec-kitty init --ai <agent> command
File generation: Verify correct directory structure and files
Command validation: Ensure generated commands work with the agent
Context update: Test agent context update scripts

Common Pitfalls

Forgetting update scripts: Both bash and PowerShell scripts must be updated
Missing CLI checks: Only add for agents that actually have CLI tools
Wrong argument format: Use correct placeholder format for each agent type
Directory naming: Follow agent-specific conventions exactly
Help text inconsistency: Update all user-facing text consistently

Future Considerations

When adding new agents:

Consider the agent's native command/workflow patterns
Ensure compatibility with the Spec-Driven Development process
Document any special requirements or limitations
Update this guide with lessons learned

This documentation should be updated whenever new agents are added to maintain accuracy and completeness.

7. Branching and Pinning Policy

This repository intentionally has two long-lived lines: main for stable 1.x maintenance and 2.x for next-generation development.
Every pull request must target exactly one long-lived line. Do not combine 1.x and 2.x scope in a single pull request.
If a change must exist on both lines, propagate it explicitly with merge or cherry-pick and record source commit IDs.
Pin cross-repo dependencies and references to immutable commit SHAs or release tags.
Do not pin release or production workflows to moving branch names.
Keep any local branch or ref overrides uncommitted.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

AGENTS.md

About Spec Kitty and Spec Kitty CLI

Task Lane Management (Work Packages)

Current System (v0.9.0+)

Moving Work Packages Between Lanes

Workflow Commands (Recommended for Agents)

Other Task Commands

General practices

Adding New Agent Support

Overview

Current Supported Agents

Step-by-Step Integration Guide

1. Update AI_CHOICES Constant

2. Update CLI Help Text

3. Update README Documentation

4. Update Release Package Script

Add to ALL_AGENTS array:

Add case statement for directory structure:

4. Update GitHub Release Script

5. Agent Context Management (v0.10.0+)

6. Update CLI Tool Checks (Optional)

Agent Categories

CLI-Based Agents

IDE-Based Agents

Command File Formats

Markdown Format

TOML Format

Directory Conventions

Argument Patterns

Testing New Agent Integration

Common Pitfalls

Future Considerations

7. Branching and Pinning Policy

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

AGENTS.md

About Spec Kitty and Spec Kitty CLI

Task Lane Management (Work Packages)

Current System (v0.9.0+)

Moving Work Packages Between Lanes

Workflow Commands (Recommended for Agents)

Other Task Commands

General practices

Adding New Agent Support

Overview

Current Supported Agents

Step-by-Step Integration Guide

1. Update AI_CHOICES Constant

2. Update CLI Help Text

3. Update README Documentation

4. Update Release Package Script

Add to ALL_AGENTS array:

Add case statement for directory structure:

4. Update GitHub Release Script

5. Agent Context Management (v0.10.0+)

6. Update CLI Tool Checks (Optional)

Agent Categories

CLI-Based Agents

IDE-Based Agents

Command File Formats

Markdown Format

TOML Format

Directory Conventions

Argument Patterns

Testing New Agent Integration

Common Pitfalls

Future Considerations

7. Branching and Pinning Policy