How AI Agents Are Validated During Initialization in Spec-Kit: CLI vs IDE

Spec-Kit validates CLI-based AI agents by checking for executable presence via check_tool(), while IDE-based agents skip validation entirely based on the requires_cli flag in AGENT_CONFIG.

The specify init command in the github/spec-kit repository performs distinct validation paths depending on whether an AI agent requires a command-line tool or operates purely within an IDE. This differentiation ensures that CLI-dependent agents like Claude or Gemini are actually installed before initialization proceeds, whereas IDE-integrated agents like GitHub Copilot or Cursor are assumed to be managed by their host environments.

Agent Configuration Metadata Drives Validation

All supported agents are defined in the AGENT_CONFIG dictionary located in src/specify_cli/__init__.py (lines 26-62). Each entry specifies metadata including a critical boolean flag named requires_cli that determines the validation strategy.

"claude": {
    "name": "Claude Code",
    "folder": ".claude/",
    "commands_subdir": "commands",
    "install_url": "https://docs.anthropic.com/.../setup",
    "requires_cli": True,            # ← triggers executable check

},
"copilot": {
    "name": "GitHub Copilot",
    "folder": ".github/",
    "commands_subdir": "agents",
    "install_url": None,
    "requires_cli": False,           # ← skips CLI validation

},

The requires_cli field serves as the single source of truth for how spec-kit validates AI agents during initialization. When set to True, the system verifies the binary exists in PATH; when False, no tool presence check occurs.

Validation Logic in the Init Command

Inside the init command implementation (lines 99-107 of src/specify_cli/__init__.py), the code branches based on the requires_cli flag:

if not ignore_agent_tools:
    agent_config = AGENT_CONFIG.get(selected_ai)
    if agent_config and agent_config["requires_cli"]:
        install_url = agent_config["install_url"]
        if not check_tool(selected_ai):
            # Show an error panel with install_url and abort

CLI-based agents (requires_cli == True) trigger the check_tool() function. If the tool is missing, spec-kit displays an error panel (lines 103-109) containing the install_url and aborts the initialization.

IDE-based agents (requires_cli == False) bypass this block entirely. Since these agents function within the IDE itself rather than as standalone executables, spec-kit assumes availability through the editor's extension system.

How check_tool Validates CLI Executables

The check_tool function (defined at lines 544-566 in src/specify_cli/__init__.py) performs executable discovery using shutil.which() with special handling for specific agents:

def check_tool(tool: str, tracker: StepTracker = None) -> bool:
    if tool == "claude":
        # Special handling for the Claude CLI alias

        if CLAUDE_LOCAL_PATH.exists() and CLAUDE_LOCAL_PATH.is_file():
            return True
    if tool == "kiro-cli":
        found = shutil.which("kiro-cli") is not None or shutil.which("kiro") is not None
    else:
        found = shutil.which(tool) is not None
    # ... UI tracking updates ...

    return found

Key implementation details include:

• Standard lookup: Uses shutil.which(tool) for most binaries like gemini or qwen
• Claude exception: Checks for a local wrapper at CLAUDE_LOCAL_PATH before falling back to PATH
• Kiro flexibility: Accepts either kiro-cli or kiro as valid executable names
• Progress reporting: Optionally accepts a StepTracker to update the UI with "available" or "not found" status

Bypassing Validation with --ignore-agent-tools

Users can skip validation entirely using the --ignore-agent-tools flag. When provided, this sets the ignore_agent_tools boolean to True, short-circuiting the validation block before any check_tool() calls occur. This is particularly useful in CI/CD pipelines where the agent tool might be installed later or in separate containers.

Practical Initialization Examples

CLI-Based Agent (Claude)

When initializing with a CLI-dependent agent, spec-kit verifies the executable exists:

$ specify init myproj --ai claude

# If `claude` is not in PATH:

# → error panel:

#   claude not found

#   Install from: https://docs.anthropic.com/en/docs/claude-code/setup

IDE-Based Agent (Copilot)

IDE-based agents proceed immediately without tool checks:

$ specify init myproj --ai copilot

# No tool check happens; project is created immediately.

Skipping Validation in Automation

For environments where the tool is not yet installed:

$ specify init myproj --ai claude --ignore-agent-tools

Summary

• CLI-based agents (Claude, Gemini, Qwen, Opencode) set requires_cli: True in AGENT_CONFIG, triggering check_tool() to verify executable presence in PATH
• IDE-based agents (Copilot, Cursor, Windsurf) set requires_cli: False, skipping validation entirely as the IDE manages the agent
• Special cases in check_tool() handle Claude's local wrapper path and Kiro's dual executable names (kiro-cli or kiro)
• Override option --ignore-agent-tools bypasses all validation for automation scenarios
• Error handling for missing CLI tools displays the configured install_url before aborting initialization

Frequently Asked Questions

What happens if a CLI-based AI agent is not installed?

Spec-kit calls check_tool() during specify init and, if the executable is missing, displays an error panel containing the agent's install_url (as configured in AGENT_CONFIG) and aborts the initialization process unless --ignore-agent-tools is specified.

Why don't IDE-based agents require validation?

IDE-based agents like GitHub Copilot or Cursor operate as extensions within the IDE itself rather than standalone command-line tools. Since spec-kit cannot verify IDE extension installation from the CLI, these agents set requires_cli: False in their configuration, causing the validation block to be skipped entirely.

How does spec-kit handle different executable names for the same agent?

The check_tool function in src/specify_cli/__init__.py contains agent-specific logic. For example, the Kiro agent checks for both kiro-cli and kiro using shutil.which() on both names, while Claude checks for a local wrapper file at CLAUDE_LOCAL_PATH before searching PATH.

Can I initialize a project for an AI agent that I haven't installed yet?

Yes. By passing the --ignore-agent-tools flag to specify init, you bypass the check_tool() validation entirely. This allows project setup to complete even when CLI tools are missing, which is useful for setting up projects in containers or CI environments where tools are installed separately.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}