AGENTS.md

About IaC Spec Kit and Specify

IaC Spec Kit is a domain-specific implementation of the spec-driven development pattern optimized for Infrastructure as Code workflows. While the original GitHub Spec Kit focuses on software development, IaC Spec Kit provides infrastructure-specific templates, foundational principles, cloud resource specifications, and Terraform patterns.

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

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

General practices

Any changes to __init__.py for the Specify 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 Specify CLI. Use this guide as a reference when integrating new AI tools into the Spec-Driven Development workflow for infrastructure projects.

Overview

Specify 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
Amazon Q Developer CLI	`.amazonq/prompts/`	Markdown	`q`	Amazon Q Developer CLI
Amp	`.agents/commands/`	Markdown	`amp`	Amp CLI
Antigravity	`.agent/workflows/`	Markdown	N/A (IDE-based)	Antigravity IDE
Auggie CLI	`.augment/commands/`	Markdown	`auggie`	Auggie CLI
Claude Code	`.claude/commands/`	Markdown	`claude`	Anthropic's Claude Code CLI
Cline	`.clinerules/workflows/`	Markdown	N/A (IDE-based)	Cline IDE
CodeBuddy CLI	`.codebuddy/commands/`	Markdown	`codebuddy`	CodeBuddy CLI
Codex CLI	`.codex/prompts/`	Markdown	`codex`	Codex CLI
Cursor	`.cursor/commands/`	Markdown	`cursor-agent`	Cursor CLI
Devin for Terminal	`.devin/skills/`	Markdown	`devin`	Cognition AI Devin
Firebender	`.firebender/commands/`	Markdown	N/A (IDE-based)	Android Studio / IntelliJ
Forge	`.forge/commands/`	Markdown	`forge`	Forge CLI
Gemini CLI	`.gemini/commands/`	TOML	`gemini`	Google's Gemini CLI
Generic	(user-defined)	Markdown	N/A	Bring-your-own agent (use `--ai-commands-dir`)
GitHub Copilot	`.github/agents/`	Markdown	N/A (IDE-based)	GitHub Copilot in VS Code
Goose	`.goose/recipes/`	YAML	`goose`	Block/Square Goose agent
Hermes	`.hermes/commands/`	Markdown	`hermes`	Hermes CLI
IBM Bob	`.bob/commands/`	Markdown	N/A (IDE-based)	IBM Bob IDE
iFlow	`.iflow/commands/`	Markdown	N/A (IDE-based)	iFlow IDE
Junie	`.junie/commands/`	Markdown	`junie`	JetBrains Junie
Kilo Code	`.kilocode/workflows/`	Markdown	N/A (IDE-based)	Kilo Code IDE
Kimi Code	`.kimi-code/skills/`	Markdown	`kimi`	Moonshot AI Kimi Code
Kiro CLI	`.kiro/prompts/`	Markdown	`kiro-cli`	AWS Kiro CLI
Lingma	`.lingma/commands/`	Markdown	N/A (IDE-based)	Alibaba Lingma
Mistral Vibe	`.vibe/skills/`	Markdown	`vibe`	Mistral Vibe
OMP	`.omp/commands/`	Markdown	`omp`	OMP CLI
opencode	`.opencode/command/`	Markdown	`opencode`	opencode CLI
Pi Coding Agent	`.pi/commands/`	Markdown	`pi`	Pi Coding Agent
Qoder CLI	`.qoder/commands/`	Markdown	`qodercli`	Qoder CLI
Qwen Code	`.qwen/commands/`	TOML	`qwen`	Alibaba's Qwen Code CLI
Roo Code	`.roo/commands/`	Markdown	N/A (IDE-based)	Roo Code IDE
RovoDev ACLI	`.rovodev/skills/`	Markdown	`acli`	Atlassian Rovo Dev
SHAI	`.shai/commands/`	Markdown	`shai`	OVHcloud SHAI CLI
Tabnine CLI	`.tabnine/agent/commands/`	TOML	`tabnine`	Tabnine CLI
Trae	`.trae/skills/`	Markdown	N/A (IDE-based)	Trae IDE
Windsurf	`.windsurf/workflows/`	Markdown	N/A (IDE-based)	Windsurf IDE workflows
ZCode	`.zcode/skills/`	Markdown	`zcode`	Z.AI ZCode
Zed	`.agents/skills/`	Markdown	N/A (IDE-based)	Zed editor

Step-by-Step Integration Guide

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

1. Add to AGENT_CONFIG

IMPORTANT: Use the actual CLI tool name as the key, not a shortened version.

Add the new agent to the AGENT_CONFIG dictionary in src/iac_specify_cli/__init__.py. This is the single source of truth for all agent metadata:

AGENT_CONFIG = {
    # ... existing agents ...
    "new-agent-cli": {  # Use the ACTUAL CLI tool name (what users type in terminal)
        "name": "New Agent Display Name",
        "folder": ".newagent/",  # Directory for agent files
        "install_url": "https://example.com/install",  # URL for installation docs (or None if IDE-based)
        "requires_cli": True,  # True if CLI tool required, False for IDE-based agents
    },
}

Key Design Principle: The dictionary key should match the actual executable name that users install. For example:

✅ Use "cursor-agent" because the CLI tool is literally called cursor-agent
❌ Don't use "cursor" as a shortcut if the tool is cursor-agent

This eliminates the need for special-case mappings throughout the codebase.

Field Explanations:

name: Human-readable display name shown to users
folder: Directory where agent-specific files are stored (relative to project root)
install_url: Installation documentation URL (set to None for IDE-based agents)
requires_cli: Whether the agent requires a CLI tool check during initialization

2. Update CLI Help Text

Update the --ai parameter help text in the init() command to include the new agent:

ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, codebuddy, qodercli, shai, agy, generic, or q"),

Also update any function docstrings, examples, and error messages that list available agents.

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-agent 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-kit-template-windsurf-sh-"$VERSION".zip \
  .genreleases/spec-kit-template-windsurf-ps-"$VERSION".zip \
  # Add new agent packages here

5. Update Agent Context Scripts

Bash script (`scripts/bash/update-agent-context.sh`)

Add file variable:

WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"

Add to case statement:

case "$AGENT_TYPE" in
  # ... existing cases ...
  windsurf) update_agent_file "$WINDSURF_FILE" "Windsurf" ;;
  "") 
    # ... existing checks ...
    [ -f "$WINDSURF_FILE" ] && update_agent_file "$WINDSURF_FILE" "Windsurf";
    # Update default creation condition
    ;;
esac

PowerShell script (`scripts/powershell/update-agent-context.ps1`)

Add file variable:

$windsurfFile = Join-Path $repoRoot '.windsurf/rules/specify-rules.md'

Add to switch statement:

switch ($AgentType) {
    # ... existing cases ...
    'windsurf' { Update-AgentFile $windsurfFile 'Windsurf' }
    '' {
        foreach ($pair in @(
            # ... existing pairs ...
            @{file=$windsurfFile; name='Windsurf'}
        )) {
            if (Test-Path $pair.file) { Update-AgentFile $pair.file $pair.name }
        }
        # Update default creation condition
    }
}

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: 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.

Important Design Decisions

Using Actual CLI Tool Names as Keys

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.

Why this matters:

The check_tool() function uses shutil.which(tool) to find executables in the system PATH
If the key doesn't match the actual CLI tool name, you'll need special-case mappings throughout the codebase
This creates unnecessary complexity and maintenance burden

Example - The Cursor Lesson:

❌ Wrong approach (requires special-case mapping):

AGENT_CONFIG = {
    "cursor": {  # Shorthand that doesn't match the actual tool
        "name": "Cursor",
        # ...
    }
}

# Then you need special cases everywhere:
cli_tool = agent_key
if agent_key == "cursor":
    cli_tool = "cursor-agent"  # Map to the real tool name

✅ Correct approach (no mapping needed):

AGENT_CONFIG = {
    "cursor-agent": {  # Matches the actual executable name
        "name": "Cursor",
        # ...
    }
}

# No special cases needed - just use agent_key directly!

Benefits of this approach:

Eliminates special-case logic scattered throughout the codebase
Makes the code more maintainable and easier to understand
Reduces the chance of bugs when adding new agents
Tool checking "just works" without additional mappings

7. Update Devcontainer files (Optional)

For agents that have VS Code extensions or require CLI installation, update the devcontainer configuration files:

VS Code Extension-based Agents

For agents available as VS Code extensions, add them to .devcontainer/devcontainer.json:

{
  "customizations": {
    "vscode": {
      "extensions": [
        // ... existing extensions ...
        // [New Agent Name]
        "[New Agent Extension ID]"
      ]
    }
  }
}

CLI-based Agents

For agents that require CLI tools, add installation commands to .devcontainer/post-create.sh:

#!/bin/bash

# Existing installations...

echo -e "\n🤖 Installing [New Agent Name] CLI..."
# run_command "npm install -g [agent-cli-package]@latest" # Example for node-based CLI
# or other installation instructions (must be non-interactive and compatible with Linux Debian "Trixie" or later)...
echo "✅ Done"

Quick Tips:

Extension-based agents: Add to the appropriate configuration files
CLI-based agents: Ensure installation instructions are documented
Hybrid agents: May require both extension and CLI installation
Test thoroughly: Ensure installations work in the development environment

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
Amazon Q Developer CLI: q CLI
CodeBuddy CLI: codebuddy CLI
Amp: amp CLI
SHAI: shai CLI
Qoder CLI: qodercli CLI

IDE-Based Agents

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
Antigravity: Built into Antigravity IDE
Kilo Code: Built into Kilo Code IDE
Roo Code: Built into Roo Code IDE

Command File Formats

Markdown Format

Used by: Claude, Cursor, opencode, Windsurf, Amazon Q Developer, Amp, IBM Bob

---
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/agents/
- Cursor: .cursor/commands/
- Windsurf: .windsurf/workflows/
- Antigravity: .agent/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 iac-specify 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
Infrastructure validation: Test with infrastructure-specific commands (/iac.*)

Common Pitfalls

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.
Forgetting update scripts: Both bash and PowerShell scripts must be updated when adding new agents.
Incorrect requires_cli value: Set to True only for agents that actually have CLI tools to check; set to False for IDE-based agents.
Wrong argument format: Use correct placeholder format for each agent type ($ARGUMENTS for Markdown, {{args}} for TOML).
Directory naming: Follow agent-specific conventions exactly (check existing agents for patterns).
Help text inconsistency: Update all user-facing text consistently (help strings, docstrings, README, error messages).
Infrastructure context: Ensure agent commands work with infrastructure-specific workflows (Terraform validation, cloud provider CLIs).

Future Considerations

When adding new agents:

Consider the agent's native command/workflow patterns
Ensure compatibility with the Spec-Driven Development process for infrastructure
Test with Terraform and cloud provider CLI tools
Document any special requirements or limitations for infrastructure projects
Update this guide with lessons learned
Verify the actual CLI tool name before adding to AGENT_CONFIG

Infrastructure-Specific Considerations

When working with IaC Spec Kit:

Command namespace: All infrastructure commands use the .iac namespace (/iac.specify, /iac.plan, etc.)
Terraform integration: Agents should support Terraform validation commands (terraform validate, terraform fmt, tflint)
Cloud provider CLIs: Consider integration with cloud provider CLIs (AWS CLI, Azure CLI, gcloud, IBM Cloud CLI)
State management: Agents should understand Terraform state management concepts
Infrastructure patterns: Templates focus on cloud resources, networking, security, and compliance

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

Navigation Menu

Uh oh!

AGENTS.md

About IaC Spec Kit and Specify

General practices

Adding New Agent Support

Overview

Current Supported Agents

Step-by-Step Integration Guide

1. Add to AGENT_CONFIG

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. Update Agent Context Scripts

Bash script (`scripts/bash/update-agent-context.sh`)

PowerShell script (`scripts/powershell/update-agent-context.ps1`)

6. Update CLI Tool Checks (Optional)

Important Design Decisions

Using Actual CLI Tool Names as Keys

7. Update Devcontainer files (Optional)

VS Code Extension-based Agents

CLI-based Agents

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

Infrastructure-Specific Considerations

Uh oh!

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

AGENTS.md

About IaC Spec Kit and Specify

General practices

Adding New Agent Support

Overview

Current Supported Agents

Step-by-Step Integration Guide

1. Add to AGENT_CONFIG

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. Update Agent Context Scripts

Bash script (scripts/bash/update-agent-context.sh)

PowerShell script (scripts/powershell/update-agent-context.ps1)

6. Update CLI Tool Checks (Optional)

Important Design Decisions

Using Actual CLI Tool Names as Keys

7. Update Devcontainer files (Optional)

VS Code Extension-based Agents

CLI-based Agents

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

Infrastructure-Specific Considerations

Bash script (`scripts/bash/update-agent-context.sh`)

PowerShell script (`scripts/powershell/update-agent-context.ps1`)