Add universal initialization for multiple AI Agents

[DanielHashmi]

Universal Initialization Feature for Spec Kit

Summary

This PR implements universal initialization functionality that allows specify init to set up multiple AI agents simultaneously. Users can now initialize projects with all 17 supported agents at once, or select specific subsets of agents, providing maximum flexibility for multi-agent development workflows.

Motivation

Previously, specify init only supported initializing one AI agent at a time. Users working with multiple agents had to:

• Run specify init multiple times in different directories
• Manually merge agent configurations
• Risk conflicts and inconsistencies

This feature enables:

• Universal initialization: Set up all 17 agents with a single command
• Flexible subset selection: Choose specific agents for your workflow
• Efficient multi-agent workflows: Test and compare different AI agents easily
• Backward compatibility: All existing single-agent functionality remains unchanged

Implementation Details

Architecture Decision

Approach: Download and merge individual agent templates

• Reuses existing template system (no build changes needed)
• Downloads multiple spec-kit-template-{agent}-{script}-*.zip files
• Merges agent-specific directories intelligently
• Handles conflicts (e.g., AGENTS.md shared by 5 agents)

Rejected Alternative: Pre-built "all-agents" templates (would require build system changes, less flexible)

Key Components

1. New CLI Options (lines 1202-1204)

--universal          # Initialize with ALL supported AI agents
--all-agents         # Alias for --universal
--agents "a,b,c"     # Comma-separated list of specific agents

2. Helper Functions Added

• parse_agent_list(): Validates and parses comma-separated agent names
• _merge_directory(): Recursively merges directories with special handling for .vscode/settings.json
• _handle_agents_md_conflict(): Merges AGENTS.md from multiple agents into single file
• download_and_extract_multi_agent_templates(): Main multi-agent download and merge logic

3. Core Logic Updates

• Mutual exclusivity validation: Ensures only one of --ai, --universal, --all-agents, or --agents is used
• Agent selection mode: Determines single vs multi-agent mode
• CLI tool checks: Non-blocking notices for multi-agent, strict checks for single-agent
• Branching logic: Routes to appropriate download function based on mode
• Progress tracking: Clear feedback during multi-agent downloads
• Success messages: Adapted for multi-agent setups

Usage Examples

# Initialize with all 17 agents
specify init my-project --universal
specify init my-project --all-agents

# Initialize with specific agents
specify init my-project --agents "claude,copilot,gemini"
specify init my-project --agents "claude,copilot,cursor-agent,windsurf"

# Initialize in current directory with all agents
specify init --here --universal
specify init . --universal

# Combine with other flags
specify init my-project --universal --script ps
specify init my-project --agents "claude,gemini" --no-git
specify init my-project --universal --ignore-agent-tools

# Single agent (existing behavior - unchanged)
specify init my-project --ai claude
specify init my-project  # Interactive selection

Key Features

✅ Backward Compatible - All existing single-agent functionality unchanged
✅ Flexible - Support for all agents, specific subsets, or single agent
✅ Intelligent Merging - Handles .specify/ directory and AGENTS.md conflicts
✅ Progress Tracking - Clear feedback during multi-agent downloads
✅ Smart CLI Checks - Non-blocking notices for multi-agent, strict for single-agent
✅ Error Handling - Validates agent names, shows helpful error messages

Files Changed

• src/specify_cli/__init__.py: Core implementation (added ~250 lines)
• README.md: Updated with universal initialization examples

Breaking Changes

None. This is a purely additive feature that maintains full backward compatibility.

AI Assistance

This implementation was developed with assistance from Claude Code, which was utilized for both the technical implementation and the creation of this pull request description.