{"id":46549464,"url":"https://github.com/ibm/iac-spec-kit","last_synced_at":"2026-03-07T03:03:30.967Z","repository":{"id":324267890,"uuid":"1096538958","full_name":"IBM/iac-spec-kit","owner":"IBM","description":"AI-assisted workflows for translating business requirements into infrastructure code","archived":false,"fork":false,"pushed_at":"2026-03-02T17:35:45.000Z","size":6566,"stargazers_count":42,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-02T20:57:49.347Z","etag":null,"topics":["ai","bob","claude","copilot","cursor","iac","llm","sdd","terraform","vscode"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IBM.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-14T15:16:54.000Z","updated_at":"2026-03-02T17:35:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/IBM/iac-spec-kit","commit_stats":null,"previous_names":["ibm/iac-spec-kit"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/IBM/iac-spec-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fiac-spec-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fiac-spec-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fiac-spec-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fiac-spec-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IBM","download_url":"https://codeload.github.com/IBM/iac-spec-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fiac-spec-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30206339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"online","status_checked_at":"2026-03-07T02:00:06.765Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","bob","claude","copilot","cursor","iac","llm","sdd","terraform","vscode"],"created_at":"2026-03-07T03:03:20.339Z","updated_at":"2026-03-07T03:03:30.956Z","avatar_url":"https://github.com/IBM.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IaC Spec Kit - a cloud-agnostic infrastructure as code specification toolkit\n\n\u003e AI-assisted workflows for translating business requirements into infrastructure code\n\n## Table of Contents\n\n- [What is Specification-Driven Development?](#what-is-specification-driven-development)\n- [About this project](#about-this-project)\n  - [Infrastructure-specific features](#infrastructure-specific-features)\n  - [Multi-Cloud Infrastructure Support](#multi-cloud-infrastructure-support)\n- [Get Started](#get-started)\n  - [1. Install IaC Specify CLI](#1-install-iac-specify-cli)\n  - [2. Establish project principles](#2-establish-project-principles)\n  - [3. Create the spec](#3-create-the-spec)\n  - [4. Create a technical implementation plan](#4-create-a-technical-implementation-plan)\n  - [5. Break down into tasks](#5-break-down-into-tasks)\n  - [6. Execute implementation](#6-execute-implementation)\n- [Cloud Provider Examples](#cloud-provider-examples)\n- [Tips for Best Results](#tips-for-best-results)\n  - [Use frontier AI models](#use-frontier-ai-models)\n  - [Configure MCP servers in advance](#configure-mcp-servers-in-advance)\n  - [Add search capabilities](#add-search-capabilities)\n  - [Start fresh between commands](#start-fresh-between-commands)\n  - [Configure custom modes](#configure-custom-modes)\n- [Supported AI Agents](#supported-ai-agents)\n- [IaC Specify CLI Reference](#iac-specify-cli-reference)\n  - [Commands](#commands)\n  - [`iac-specify init` Arguments \u0026 Options](#iac-specify-init-arguments--options)\n  - [Examples](#examples)\n  - [Available Slash Commands](#available-slash-commands)\n- [Infrastructure Architecture Section](#infrastructure-architecture-section)\n- [Environment Variables](#environment-variables)\n- [Core Philosophy](#core-philosophy)\n- [Development Phases](#development-phases)\n- [Experimental Goals](#experimental-goals)\n- [Prerequisites](#prerequisites)\n- [Learn More](#learn-more)\n- [Detailed Process](#detailed-process)\n- [Contributing](#contributing)\n- [Future Ideas](#future-ideas)\n- [Support](#support)\n- [Acknowledgements](#acknowledgements)\n- [License](#license)\n\n## What is Specification-Driven Development?\n\nSpecification-Driven Development (SDD) is an emerging methodology where detailed specifications are created before code. The specification becomes your single source of truth, guiding AI agents to generate implementation plans and production-ready code. This approach clarifies intent upfront, reduces misalignment, and enables iterative refinement through living documents that evolve with your project.\n\n**Learn more:** [Red Hat on SDD](https://developers.redhat.com/articles/2025/10/22/how-spec-driven-development-improves-ai-coding-quality) •  [Martin Fowler on SDD](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html) • [ThoughtWorks Radar](https://www.thoughtworks.com/radar/techniques/spec-driven-development)\n\n**Potential benefits for infrastructure:**\n\n- Supports starting with high-level requirements that AI agents can use to generate detailed specifications\n- Encourages separating requirements (what you need) from implementation details (specific cloud services)\n- Provides templates and commands to help AI agents translate specs into IaC configurations\n- Enables specification updates that can inform changes to plans and code\n- Facilitates team alignment through explicit, reviewable specifications\n\n\n\n## About this project\n\n[![GitHub Release](https://img.shields.io/github/v/release/IBM/iac-spec-kit?color=blue)](https://github.com/IBM/iac-spec-kit/releases)\n[![License](https://img.shields.io/github/license/IBM/iac-spec-kit)](https://github.com/IBM/iac-spec-kit/blob/main/LICENSE)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue)](https://www.python.org/downloads/)\n[![Last Commit](https://img.shields.io/github/last-commit/IBM/iac-spec-kit)](https://github.com/IBM/iac-spec-kit/commits/main)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/IBM/iac-spec-kit/pulls)\n\n**IaC Spec Kit** is a specialized implementation of the [GitHub Spec Kit](https://github.com/github/spec-kit) toolkit, adapted for Infrastructure as Code workflows with Terraform and cloud providers. As SDD is an emerging trend, this project explores how specification-driven approaches can improve infrastructure development—an experimental field where we're discovering what's possible with AI-assisted infrastructure provisioning.\n\n### Visual Walkthrough\n\nSee the complete workflow in action (2 minutes):\n\n\u003ca href=\"https://www.youtube.com/watch?v=al1Yx0BG7Wo\"\u003e\n  \u003cimg src=\"./media/iac-spec-kit-thumbnail.png\" alt=\"IaC Spec Kit Walkthrough\" width=\"600\"\u003e\n\u003c/a\u003e\n\nThis visual guide shows the end-to-end process of using IaC Spec Kit to generate infrastructure specifications, plans, and Terraform code for a WordPress deployment on IBM Cloud.\n\n### Infrastructure-specific features\n\n- **Infrastructure command namespace**: All commands use `.iac` prefix (`/iac.principles`, `/iac.specify`, `/iac.plan`, `/iac.tasks`, `/iac.implement`)\n- **IaC-centric templates**: Templates designed for cloud resources, networking, security, and compliance. The toolkit is slightly geared towards Terraform, but you can use any IaC tool.\n- **Multi-cloud support**: Works with any cloud provider - AWS, Azure, GCP, IBM Cloud, Oracle Cloud, and more\n- **Infrastructure principles**: Governance frameworks for cloud infrastructure, security standards, and cost management\n\n### Multi-Cloud Infrastructure Support\n\nIaC Spec Kit is designed to work with any cloud provider. The toolkit encourages AI agents to separate generic infrastructure requirements (what you need) from cloud-specific implementation (how to build it):\n\n- **Principles and Specifications** use generic infrastructure terms - IaC Spec Kit encourages describing requirements using terms like \"managed database\", \"object storage\", \"encryption key management\" rather than cloud-specific service names\n- **Plans and Implementation** are cloud-specific - IaC Spec Kit helps AI agents translate generic requirements into specific services like AWS RDS, Azure Database, Cloud SQL, or IBM Databases for MySQL\n\nThis separation is intended to:\n- Help you focus on *what* you need rather than *how* to build it, with templates that guide AI agents through cloud-specific implementation details\n- Make specifications more accessible to team members less familiar with a specific cloud provider\n- Support switching cloud providers by re-running `/iac.plan` with a different cloud\n- Enable deploying the same specification to multiple clouds\n- Facilitate comparing cloud provider options before committing\n\n## Contributing and future ideas\n\nIaC Spec Kit is an experimental project exploring how Specification-Driven Development can improve infrastructure as code workflows. Contributions help refine templates, expand compatibility, and discover what works best with AI-assisted infrastructure provisioning. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to participate, and [IDEAS.md](IDEAS.md) for potential areas to explore.\n\n---\n\n## Get Started\n\n### 1. Install IaC Specify CLI\n\n**Prerequisites:** This CLI tool requires [uv](https://docs.astral.sh/uv/) - a fast Python package installer. If you don't have it yet, install it with:\n\n```bash\n# macOS/Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Windows\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\nChoose your preferred installation method:\n\n#### Option 1: Persistent Installation (Recommended)\n\nInstall once and use everywhere:\n\n```bash\nuv tool install iac-specify-cli --from git+https://github.com/ibm/iac-spec-kit.git\n```\n\nThen use the tool directly:\n\n```bash\niac-specify init \u003cPROJECT_NAME\u003e\niac-specify check\n```\n\nTo upgrade iac-specify run:\n\n```bash\nuv tool install iac-specify-cli --force --from git+https://github.com/ibm/iac-spec-kit.git\n```\n\n#### Option 2: One-time Usage\n\nRun directly without installing:\n\n```bash\nuvx --from git+https://github.com/ibm/iac-spec-kit.git iac-specify init \u003cPROJECT_NAME\u003e\n```\n\n**Benefits of persistent installation:**\n\n- Tool stays installed and available in PATH\n- No need to create shell aliases\n- Better tool management with `uv tool list`, `uv tool upgrade`, `uv tool uninstall`\n- Cleaner shell configuration\n\n### 2. Create the spec\n\nLaunch your AI assistant in the project directory. The `/iac.*` commands are available in the assistant.\n\nUse the **`/iac.specify`** command to describe what you want to build. Focus on the **what** and **why**. IaC Spec Kit guides AI agents to avoid tech stack details at this stage.\n\n```\n/iac.specify I need to deploy WordPress for my small business website. Should handle a few thousand visitors per day, needs to be secure with automated backups. Budget is around $500/month. Use the official WordPress Docker image.\n```\n\n### 3. Create a technical implementation plan\n\nUse the **`/iac.plan`** command to create an architecture plan. This outputs a single `plan.md` file with inline research.\n\n```\n/iac.plan Deploy in us-south. Use Code Engine for containers, Databases for MySQL, Cloud Object Storage for media.\n```\n\n**Optional enrichment**: For quality-critical or complex projects, run **`/iac.enrichplan`** to generate deep research (Well-Architected Framework analysis, curated modules), detailed architecture, module specifications, and a provisioning quickstart guide.\n\n```\n/iac.enrichplan\n```\n\n### 4. Break down into tasks\n\nUse **`/iac.tasks`** to create an actionable task list from your implementation plan.\n\n```\n/iac.tasks\n```\n\n### 5. Execute implementation\n\nUse **`/iac.implement`** to execute all tasks and build your feature according to the plan.\n\n```\n/iac.implement\n```\n\n---\n\n**Optional: Add project principles** - For multi-capability projects or team collaboration, use **`/iac.principles`** before `/iac.specify` to establish a set of principles that apply across multiple capabilities. This creates a `principles.md` file that is referenced by all other commands.\n\n```\n/iac.principles This is a production environment. Security and compliance are critical. Use Terraform with curated modules.\n```\n\n```\n/iac.principles This is a development environment. Keep it simple, focus on basic security, and keep costs low. Use Terraform.\n```\n\nFor the original Spec-Driven Development methodology, see the [GitHub Spec Kit documentation](https://github.com/github/spec-kit).\n\n---\n\n## Generated Example\n\n**See what IaC Spec Kit generates:** [wordpress-ibm-cloud](https://github.com/vburckhardt/wordpress-ibm-cloud) - A complete WordPress deployment on IBM Cloud created using the workflow below, showing the generated specifications, plans, tasks, and Terraform code.\n\n## Cloud Provider Examples\n\n**Get started with your cloud provider:**\n\n| Cloud Provider | Example Workflows |\n|----------------|-------------------|\n| **IBM Cloud** | [Simple VPC](./examples/01-simple-vpc/cloud-workflows/ibm-cloud.md) • [Static Website](./examples/02-static-website/cloud-workflows/ibm-cloud.md) • [WordPress](./examples/03-wordpress/cloud-workflows/ibm-cloud.md) • [Landing Zone](./examples/04-landing-zone/cloud-workflows/ibm-cloud.md) • [Three-Tier Web App](./examples/05-three-tier-webapp/cloud-workflows/ibm-cloud.md) • [Data Pipeline](./examples/06-data-pipeline/cloud-workflows/ibm-cloud.md) • [Microservices](./examples/07-microservices/cloud-workflows/ibm-cloud.md) |\n| **AWS** | [Simple VPC](./examples/01-simple-vpc/cloud-workflows/aws.md) • [Static Website](./examples/02-static-website/cloud-workflows/aws.md) • [WordPress](./examples/03-wordpress/cloud-workflows/aws.md) • [Landing Zone](./examples/04-landing-zone/cloud-workflows/aws.md) • [Three-Tier Web App](./examples/05-three-tier-webapp/cloud-workflows/aws.md) • [Data Pipeline](./examples/06-data-pipeline/cloud-workflows/aws.md) • [Microservices](./examples/07-microservices/cloud-workflows/aws.md) |\n| **Azure** | [Simple VPC](./examples/01-simple-vpc/cloud-workflows/azure.md) • [Static Website](./examples/02-static-website/cloud-workflows/azure.md) • [WordPress](./examples/03-wordpress/cloud-workflows/azure.md) • [Landing Zone](./examples/04-landing-zone/cloud-workflows/azure.md) • [Three-Tier Web App](./examples/05-three-tier-webapp/cloud-workflows/azure.md) • [Data Pipeline](./examples/06-data-pipeline/cloud-workflows/azure.md) • [Microservices](./examples/07-microservices/cloud-workflows/azure.md) |\n| **GCP** | [Simple VPC](./examples/01-simple-vpc/cloud-workflows/gcp.md) • [Static Website](./examples/02-static-website/cloud-workflows/gcp.md) • [WordPress](./examples/03-wordpress/cloud-workflows/gcp.md) • [Landing Zone](./examples/04-landing-zone/cloud-workflows/gcp.md) • [Three-Tier Web App](./examples/05-three-tier-webapp/cloud-workflows/gcp.md) • [Data Pipeline](./examples/06-data-pipeline/cloud-workflows/gcp.md) • [Microservices](./examples/07-microservices/cloud-workflows/gcp.md) |\n\n**Explore examples:** See [examples/](./examples/) for complete workflows showing how the same requirements deploy to different cloud providers.\n\n**Learn more:** Read [Writing Tech-Agnostic Infrastructure Specifications](./docs/writing-tech-agnostic-specs.md) to understand how to write specifications using generic infrastructure terms instead of cloud-specific service names.\n\n---\n\n## Tips for Best Results\n\n### Use frontier AI models\n\nThe latest frontier models from leading AI providers typically offer improved reasoning capabilities and better understanding of infrastructure patterns. When configuring your AI assistant, consider selecting the most advanced model available for your use case.\n\n### Configure MCP servers in advance\n\nFor optimal results, configure your AI tool with appropriate Model Context Protocol (MCP) servers before starting your project. MCP servers provide your AI assistant with direct access to cloud provider APIs, Terraform registries, and other infrastructure tools, which can help improve accuracy and reduce hallucinations by providing real-time, verified information.\n\n**Recommended MCP servers by cloud provider:**\n\n| Cloud Provider | MCP Server | Description |\n|----------------|------------|-------------|\n| **IBM Cloud** | [TIM (Terraform IBM Modules)](https://github.com/terraform-ibm-modules/tim-mcp) | Focused on IBM Cloud module discovery and intelligent IaC generation |\n| **AWS** | [AWS Terraform MCP Server](https://awslabs.github.io/mcp/servers/terraform-mcp-server) | Prioritizes AWSCC provider with security scanning and best-practice automation |\n| **Azure** | [Azure Terraform MCP Server](https://learn.microsoft.com/en-us/azure/developer/azure-mcp-server/tools/azure-terraform-best-practices) | Best-practices guidance with built-in validation for Azure resources |\n| **Azure** | [HashiCorp Terraform MCP Server](https://developer.hashicorp.com/terraform/mcp-server) | Multi-cloud support with Terraform Registry integration |\n| **Google Cloud** | [GCP Tools MCP Server](https://lobehub.com/mcp/gcp-tools-mcp) | Automates Google Cloud Platform infrastructure setup via gcloud and Terraform |\n| **Google Cloud** | [HashiCorp Terraform MCP Server](https://developer.hashicorp.com/terraform/mcp-server) | Multi-cloud support with Terraform Registry integration |\n| **Multi-Cloud** | [HashiCorp Terraform MCP Server](https://developer.hashicorp.com/terraform/mcp-server) | Open-source, supports major providers via registry introspection and policy checks |\n\n### Add search capabilities\n\nFor AI tools that do not currently support web search (no built-in research agent), we strongly recommend adding a search MCP server such as [Brave Search MCP](https://github.com/brave/brave-search-mcp-server) or Perplexity MCP. This can be particularly helpful during the `/iac.plan` phase when the AI needs to research current cloud services, Terraform provider versions, and best practices.\n\nWithout search capabilities, AI tools tend to rely on inherent knowledge from their training data, which can lead to hallucinations or outdated information. Search-enabled agents can verify current service offerings, pricing, and technical specifications in real-time.\n\n### Start fresh between commands\n\nYou can start a new chat with an empty context between slash commands to save tokens and reduce costs. The IaC Spec Kit approach of storing outputs as markdown files (principles.md, spec.md, plan.md, tasks.md) acts as persistent memory that subsequent chats can pull from. The AI assistant reads these files as needed, so you don't need to maintain long conversation histories.\n\nThis is particularly useful for:\n- Long-running projects where context windows become expensive\n- Switching between different aspects of your infrastructure\n- Collaborating with team members who can start fresh with the same context files\n\n### Configure custom modes\n\nIf your AI agent supports custom modes or configurations, create one that enables all necessary tools for infrastructure work. At minimum, ensure your mode allows:\n- **File read/write operations** - Essential for creating and updating specification files\n- **MCP server calls** - Required for cloud provider and Terraform integrations\n- **Command execution** - Needed for running Terraform validation commands\n\nFor example, in agents like Claude Code or IBM Bob, you can create a custom \"Infrastructure\" mode that pre-enables these capabilities, streamlining your workflow and reducing the need to grant permissions repeatedly.\n\n## Supported AI Agents\n\n| Agent                                                     | Support | Notes                                             |\n|-----------------------------------------------------------|---------|---------------------------------------------------|\n| [Claude Code](https://www.anthropic.com/claude-code)      | ✅ |                                                   |\n| [GitHub Copilot](https://code.visualstudio.com/)          | ✅ |                                                   |\n| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✅ |                                                   |\n| [Cursor](https://cursor.sh/)                              | ✅ |                                                   |\n| [Qwen Code](https://github.com/QwenLM/qwen-code)          | ✅ |                                                   |\n| [opencode](https://opencode.ai/)                          | ✅ |                                                   |\n| [Windsurf](https://windsurf.com/)                         | ✅ |                                                   |\n| [Kilo Code](https://github.com/Kilo-Org/kilocode)         | ✅ |                                                   |\n| [Auggie CLI](https://docs.augmentcode.com/cli/overview)   | ✅ |                                                   |\n| [CodeBuddy CLI](https://www.codebuddy.ai/cli)             | ✅ |                                                   |\n| [Roo Code](https://roocode.com/)                          | ✅ |                                                   |\n| [Codex CLI](https://github.com/openai/codex)              | ✅ |                                                   |\n| [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. |\n| [Amp](https://ampcode.com/) | ✅ | |\n| [IBM Bob](https://www.ibm.com/products/bob) | ✅ | IDE-based agent with slash command support |\n| [SHAI](https://github.com/ovh/shai) | ✅ | OVHcloud CLI agent |\n| [Antigravity](https://antigravity.dev/) | ✅ | IDE-based agent |\n| [Qoder CLI](https://qoder.com/cli) | ✅ | |\n| Generic (bring your own agent) | ✅ | Use with `--ai-commands-dir` to specify custom commands directory |\n\n## IaC Specify CLI Reference\n\nThe `iac-specify` command supports the following options:\n\n### Commands\n\n| Command     | Description                                                    |\n|-------------|----------------------------------------------------------------|\n| `init`      | Initialize a new IaC Specify project from the latest template      |\n| `check`     | Check for installed tools (`git`, `claude`, `gemini`, `code`/`code-insiders`, `cursor-agent`, `windsurf`, `qwen`, `opencode`, `codex`, `auggie`, `codebuddy`, `qodercli`, `shai`, `amp`, `q`, `bob`) |\n| `version`   | Display the installed version of IaC Specify CLI                   |\n| `extension` | Manage extensions (subcommands: `list`, `add`, `remove`, `search`, `info`, `update`, `enable`, `disable`) |\n\n### `iac-specify init` Arguments \u0026 Options\n\n| Argument/Option        | Type     | Description                                                                  |\n|------------------------|----------|------------------------------------------------------------------------------|\n| `\u003cproject-name\u003e`       | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory) |\n| `--ai`                 | Option   | AI assistant to use: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, `codebuddy`, `amp`, `q`, `bob`, `shai`, `agy`, `qodercli`, or `generic` |\n| `--script`             | Option   | Script variant to use: `sh` (bash/zsh) or `ps` (PowerShell)                 |\n| `--ignore-agent-tools` | Flag     | Skip checks for AI agent tools like Claude Code                             |\n| `--no-git`             | Flag     | Skip git repository initialization                                          |\n| `--here`               | Flag     | Initialize project in the current directory instead of creating a new one   |\n| `--force`              | Flag     | Force merge/overwrite when initializing in current directory (skip confirmation) |\n| `--skip-tls`           | Flag     | Skip SSL/TLS verification (not recommended)                                 |\n| `--debug`              | Flag     | Enable detailed debug output for troubleshooting                            |\n| `--github-token`       | Option   | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable)  |\n| `--ai-commands-dir`    | Option   | Custom commands directory for generic or non-standard agent layouts         |\n| `--ai-skills`          | Flag     | Download and install AI skills/extensions during initialization             |\n\n### Examples\n\n```bash\n# Basic project initialization\niac-specify init my-infrastructure\n\n# Initialize with specific AI assistant (example: IBM Bob)\niac-specify init my-infrastructure --ai bob\n\n# Initialize with PowerShell scripts (Windows/cross-platform)\niac-specify init my-infrastructure --ai copilot --script ps\n\n# Initialize in current directory\niac-specify init . --ai bob\n# or use the --here flag\niac-specify init --here --ai bob\n\n# Force merge into current (non-empty) directory without confirmation\niac-specify init . --force --ai bob\n# or\niac-specify init --here --force --ai bob\n\n# Skip git initialization\niac-specify init my-infrastructure --ai bob --no-git\n\n# Enable debug output for troubleshooting\niac-specify init my-infrastructure --ai bob --debug\n\n# Use GitHub token for API requests (helpful for corporate environments)\niac-specify init my-infrastructure --ai bob --github-token ghp_your_token_here\n\n# Check system requirements\niac-specify check\n\n# Display installed version\niac-specify version\n\n# List installed extensions\niac-specify extension list\n\n# Initialize with a generic/custom agent\niac-specify init my-infrastructure --ai generic --ai-commands-dir .myagent/commands\n\n# Initialize with AI skills download\niac-specify init my-infrastructure --ai claude --ai-skills\n```\n\n### Available Slash Commands\n\nAfter running `iac-specify init`, your AI coding agent will have access to these slash commands for structured development:\n\n#### Core Workflow Commands\n\n| Command | Description |\n|---------|-------------|\n| `/iac.specify` | Define what you want to build (requirements) |\n| `/iac.plan` | Create architecture plan with technology decisions (outputs `plan.md` with inline research) |\n| `/iac.tasks` | Generate actionable task lists for implementation |\n| `/iac.implement` | Execute all tasks to build the feature according to the plan |\n\n#### Optional Enhancement Commands\n\n| Command | Description | When to Use |\n|---------|-------------|-------------|\n| `/iac.principles` | Create project governing principles | Before `/iac.specify` - for multi-capability projects or team collaboration |\n| `/iac.enrichplan` | Deep research, architecture details, module specs, quickstart guide | After `/iac.plan` - for quality-critical or complex projects |\n| `/iac.clarify` | Clarify underspecified areas | Before `/iac.plan` - reduces rework downstream |\n| `/iac.analyze` | Cross-artifact consistency analysis | After `/iac.tasks`, before `/iac.implement` |\n| `/iac.checklist` | Generate custom quality checklists | Anytime - validates requirements completeness |\n\n\n\n## Infrastructure Architecture Section\n\nWhen using `/iac.plan` for infrastructure projects, your `plan.md` will include an **Infrastructure Architecture** section with:\n\n- **Cloud Provider Selection**: Which provider and why (AWS, Azure, GCP, etc.)\n- **Compute Resources**: VMs, containers, serverless, load balancers\n- **Data Storage**: Databases, object storage, caching layers\n- **Networking**: VPCs, subnets, security groups, routing\n- **Security**: IAM roles, encryption, secrets management\n- **Environment Configuration**: Development, staging, production settings\n- **State Management**: Terraform backend configuration, workspace strategy\n\n**For quality-critical or complex projects**, use `/iac.enrichplan` after planning to generate:\n- **research.md**: Deep research including Well-Architected Framework analysis and curated module recommendations\n- **architecture.md**: Detailed component specifications\n- **modules.md**: Custom module specifications (if using modules)\n- **quickstart.md**: Step-by-step provisioning guide (documentation-first approach improves implementation quality)\n\n#### Quick Example\n\n```\n# 1. Create infrastructure specification (using generic infrastructure terms)\n/iac.specify I need to deploy WordPress for my small business website. Should handle a few thousand visitors per day, needs to be secure with automated backups. Budget is around $500/month.\n\n# 2. Create technical plan (specify cloud provider and services)\n/iac.plan Deploy in us-south. Use Code Engine for containers, Databases for MySQL, Cloud Object Storage for media.\n\n# 3. Optional: Enrich plan for production (generates research.md, architecture.md, modules.md, quickstart.md)\n/iac.enrichplan\n\n# 4. Generate tasks (includes terraform validation checkpoints)\n/iac.tasks\n\n# 5. Implement (AI generates Terraform .tf files)\n/iac.implement\n```\n\n**Note**: For multi-capability projects, add `/iac.principles` before step 1 to establish governance rules.\n\n**Important**: IaC Spec Kit is designed to generate infrastructure as code (terraform, pulumi, ansible, kube manifest). Actual provisioning (`terraform apply`, `kubectl apply`) is a manual step you control and that is outside the scope of IaC Spec Kit.\n\n### Environment Variables\n\n| Variable         | Description                                                                                    |\n|------------------|------------------------------------------------------------------------------------------------|\n| `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-vpc-infrastructure`) to work on a specific feature when not using Git branches.\u003cbr/\u003e**Must be set in the context of the agent you're working with prior to using `/iac.plan` or follow-up commands. |\n\n## Core Philosophy\n\nSpecification-Driven Development emphasizes intent-driven development, rich specification creation, and multi-step refinement. **For the complete philosophy, see the [GitHub Spec Kit documentation](https://github.com/github/spec-kit).**\n\nIaC Spec Kit applies these principles to infrastructure provisioning with additional focus on:\n\n- **Cloud resource specifications**: Infrastructure requirements using generic terms (avoid cloud-specific service names)\n- **Terraform module design**: Reusable, composable infrastructure components\n- **Security and compliance**: Built-in governance and policy validation\n- **Multi-cloud patterns**: Portable infrastructure specifications across cloud providers\n\n## Development Phases\n\n| Phase | Focus | Key Activities |\n|-------|-------|----------------|\n| **0-to-1 Development** (\"Greenfield\") | Generate from scratch | \u003cul\u003e\u003cli\u003eStart with high-level requirements\u003c/li\u003e\u003cli\u003eGenerate specifications\u003c/li\u003e\u003cli\u003ePlan implementation steps\u003c/li\u003e\u003cli\u003eBuild production-ready infrastructure\u003c/li\u003e\u003c/ul\u003e |\n| **Creative Exploration** | Parallel implementations | \u003cul\u003e\u003cli\u003eExplore diverse solutions\u003c/li\u003e\u003cli\u003eSupport multiple cloud providers \u0026 architectures\u003c/li\u003e\u003cli\u003eExperiment with infrastructure patterns\u003c/li\u003e\u003c/ul\u003e |\n| **Iterative Enhancement** (\"Brownfield\") | Brownfield modernization | \u003cul\u003e\u003cli\u003eAdd infrastructure iteratively\u003c/li\u003e\u003cli\u003eModernize legacy infrastructure\u003c/li\u003e\u003cli\u003eAdapt processes\u003c/li\u003e\u003c/ul\u003e |\n| **Infrastructure-as-Code** | Infrastructure provisioning | \u003cul\u003e\u003cli\u003eSpecify cloud resources using cloud-agnostic terms\u003c/li\u003e\u003cli\u003eDocument Infrastructure Architecture\u003c/li\u003e\u003cli\u003eGenerate Terraform configurations\u003c/li\u003e\u003cli\u003eValidate with terraform validate/fmt/tflint\u003c/li\u003e\u003c/ul\u003e |\n\n## Experimental Goals\n\nAs SDD is an emerging trend, this implementation explores several areas in the context of Infrastructure as Code:\n\n### Technology independence\n\n- Create infrastructure using diverse cloud providers\n- Validate the hypothesis that Spec-Driven Development is a process not tied to specific cloud platforms, IaC tools, or frameworks\n- Support multi-cloud and hybrid cloud scenarios\n\n### Enterprise constraints\n\n- Demonstrate mission-critical infrastructure development\n- Incorporate organizational constraints (cloud providers, compliance requirements, engineering practices)\n- Support enterprise security standards and compliance requirements\n\n### Infrastructure-centric development\n\n- Build infrastructure for different workload types and requirements\n- Support various development approaches (from manual provisioning to fully automated IaC)\n\n### Creative \u0026 iterative processes\n\n- Provide robust iterative infrastructure development workflows\n- Extend processes to handle upgrades and modernization tasks\n\n## Prerequisites\n\n- **Linux/macOS/Windows**\n- [Supported](#-supported-ai-agents) AI coding agent.\n- [uv](https://docs.astral.sh/uv/) for package management\n- [Python 3.11+](https://www.python.org/downloads/)\n- [Git](https://git-scm.com/downloads)\n\nIf you encounter issues with an agent, please open an issue so we can refine the integration.\n\n## Learn More\n\n- **[GitHub Spec Kit](https://github.com/github/spec-kit)** - Original Spec-Driven Development methodology and documentation\n- **[Detailed Walkthrough](#-detailed-process)** - Step-by-step implementation guide for infrastructure projects\n\n---\n\n## Detailed Process\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand the detailed step-by-step walkthrough\u003c/summary\u003e\n\nYou can use the Specify CLI to bootstrap your project, which will bring in the required artifacts in your environment. Run:\n\n```bash\niac-specify init \u003cproject_name\u003e\n```\n\nOr initialize in the current directory:\n\n```bash\niac-specify init .\n# or use the --here flag\niac-specify init --here\n# Skip confirmation when the directory already has files\niac-specify init . --force\n# or\niac-specify init --here --force\n```\n\nYou will be prompted to select the AI agent you are using. You can also proactively specify it directly in the terminal:\n\n```bash\niac-specify init \u003cproject_name\u003e --ai bob\niac-specify init \u003cproject_name\u003e --ai claude\niac-specify init \u003cproject_name\u003e --ai copilot\n\n# Or in current directory:\niac-specify init . --ai bob\niac-specify init . --ai codex\n\n# or use --here flag\niac-specify init --here --ai bob\niac-specify init --here --ai codex\n\n# Force merge into a non-empty current directory\niac-specify init . --force --ai bob\n\n# or\niac-specify init --here --force --ai bob\n```\n\nThe CLI will check if you have Bob, Claude Code, Gemini CLI, Cursor CLI, Qwen CLI, opencode, Codex CLI, or Amazon Q Developer CLI installed. If you do not, or you prefer to get the templates without checking for the right tools, use `--ignore-agent-tools` with your command:\n\n```bash\niac-specify init \u003cproject_name\u003e --ai claude --ignore-agent-tools\n```\n\n### **STEP 1:** Create project specifications\n\nGo to the project folder and run your AI agent. In our example, we're using `bob`.\n\nYou will know that things are configured correctly if you see the `/iac.specify`, `/iac.plan`, `/iac.tasks`, and `/iac.implement` commands available (plus optional commands like `/iac.principles`, `/iac.enrichplan`, `/iac.clarify`).\n\n**Optional: Establish principles first** - For enterprise or multi-capability projects, you may want to run `/iac.principles` before `/iac.specify` to establish governance rules. See the \"Optional: Add project principles\" section above for details.\n\nUse the `/iac.specify` command to describe the infrastructure you want to develop.\n\n\u003e[!IMPORTANT]\n\u003eBe as explicit as possible about *what* you are trying to build and *why*. For best results, **do not focus on describing the details of cloud services at this point**. IaC Spec Kit guides AI agents to use generic infrastructure terms instead.\n\nAn example prompt:\n\n```text\n/iac.specify I need an enterprise landing zone for our organization. Requirements: separate account groups for production, staging, development, and shared services. Centralized networking with hub-and-spoke topology. All logs aggregated to security account. Policy-based guardrails to enforce compliance. Cost tracking by environment. We need to comply with SOC 2 and Financial Services Cloud requirements.\n```\n\nAfter this prompt is entered, you should see your AI agent kick off the planning and spec drafting process. IaC Spec Kit's commands and templates guide the agent through this process, and the agent will also trigger some of the built-in scripts to set up the repository.\n\nOnce this step is completed, you should have a new branch created (e.g., `001-landing-zone`), as well as a new specification in the `specs/001-landing-zone` directory.\n\nThe produced specification should contain a set of infrastructure requirements and functional requirements, as defined in the template.\n\nAt this stage, your project folder contents should resemble the following:\n\n```text\n└── .specify\n    ├── memory\n    │  └── principles.md\n    ├── scripts\n    │  ├── check-prerequisites.sh\n    │  ├── common.sh\n    │  ├── create-new-feature.sh\n    │  ├── setup-plan.sh\n    │  └── update-agent-context.sh\n    ├── specs\n    │  └── 001-landing-zone\n    │      └── spec.md\n    └── templates\n        ├── plan-template.md\n        ├── spec-template.md\n        └── tasks-template.md\n```\n\n### **STEP 2:** Functional specification clarification (optional but recommended)\n\nWith the baseline specification created, you can go ahead and clarify any of the requirements that were not captured properly within the first shot attempt.\n\nYou should run the structured clarification workflow **before** creating a technical plan to reduce rework downstream.\n\nPreferred order:\n\n1. Use `/iac.clarify` (structured) – sequential, coverage-based questioning that records answers in a Clarifications section.\n2. Optionally follow up with ad-hoc free-form refinement if something still feels vague.\n\nIf you intentionally want to skip clarification (e.g., spike or exploratory prototype), explicitly state that so the agent doesn't block on missing clarifications.\n\nExample free-form refinement prompt (after `/iac.clarify` if still needed):\n\n```text\nFor the database services, we need PostgreSQL 14+ with point-in-time recovery enabled. Backup retention should be 30 days for production and 7 days for non-production environments. The database should be deployed in a private subnet with no direct internet access.\n```\n\nYou should also ask your AI agent to validate the **Review \u0026 Acceptance Checklist**, checking off the things that are validated/pass the requirements, and leave the ones that are not unchecked. The following prompt can be used:\n\n```text\nRead the review and acceptance checklist, and check off each item in the checklist if the infrastructure spec meets the criteria. Leave it empty if it does not.\n```\n\nIt's important to use the interaction with your AI agent as an opportunity to clarify and ask questions around the specification - **do not treat its first attempt as final**.\n\n### **STEP 3:** Generate a plan\n\nYou can now be specific about the tech stack and other technical requirements. You can use the `/iac.plan` command that is built into the project template with a prompt like this:\n\n```text\n/iac.plan We'll use IBM Cloud Enterprise account groups. Transit Gateway for networking. Security and Compliance Center for compliance. Activity Tracker and Log Analysis for centralized logging.\n```\n\nThe output of this step will be a `plan.md` file with inline research. Your directory tree will resemble this:\n\n```text\n.\n├── memory\n│  └── principles.md\n├── scripts\n│  ├── check-prerequisites.sh\n│  ├── common.sh\n│  ├── create-new-feature.sh\n│  ├── setup-plan.sh\n│  └── update-agent-context.sh\n├── specs\n│  └── 001-landing-zone\n│      ├── plan.md\n│      └── spec.md\n└── templates\n    ├── plan-template.md\n    ├── spec-template.md\n    └── tasks-template.md\n```\n\n**Optional: Enrich your plan** - For quality-critical or complex projects, run `/iac.enrichplan` to generate comprehensive documentation:\n\n```text\n/iac.enrichplan\n```\n\nThis generates additional files: `research.md`, `architecture.md`, `modules.md`, and `quickstart.md`. Your directory tree will then include:\n\n```text\n├── specs\n│  └── 001-landing-zone\n│      ├── architecture.md\n│      ├── modules.md\n│      ├── plan.md\n│      ├── quickstart.md\n│      ├── research.md\n│      └── spec.md\n```\n\nIf you ran `/iac.enrichplan`, check the `research.md` document to ensure that the right tech stack is used, based on your instructions. You can ask your AI agent to refine it if any of the components stand out, or even have it check the locally-installed version of Terraform or cloud provider CLI tools.\n\nAdditionally, you might want to ask your AI agent to research details about the chosen tech stack if it's something that is rapidly changing (e.g., Kubernetes versions, Terraform provider versions), with a prompt like this:\n\n```text\nI want you to go through the implementation plan and implementation details, looking for areas that could benefit from additional research as IBM Cloud services and Terraform providers are rapidly changing. For those areas that you identify that require further research, I want you to update the research document with additional details about the specific versions that we are going to be using in this infrastructure and spawn parallel research tasks to clarify any details using research from the web.\n```\n\nDuring this process, you might find that your AI agent gets stuck researching the wrong thing - you can help nudge it in the right direction with a prompt like this:\n\n```text\nI think we need to break this down into a series of steps. First, identify a list of tasks that you would need to do during implementation that you're not sure of or would benefit from further research. Write down a list of those tasks. And then for each one of these tasks, I want you to spin up a separate research task so that the net result is we are researching all of those very specific tasks in parallel. What I saw you doing was it looks like you were researching IBM Cloud services in general and I don't think that's gonna do much for us in this case. That's way too untargeted research. The research needs to help you solve a specific targeted question.\n```\n\n\u003e[!NOTE]\n\u003eYour AI agent might be over-eager and add components that you did not ask for. Ask it to clarify the rationale and the source of the change.\n\n### **STEP 4:** Validate the plan\n\nWith the plan in place, you should have your AI agent run through it to make sure that there are no missing pieces. You can use a prompt like this:\n\n```text\nNow I want you to go and audit the implementation plan and the implementation detail files. Read through it with an eye on determining whether or not there is a sequence of tasks that you need to be doing that are obvious from reading this. Because I don't know if there's enough here. For example, when I look at the core implementation, it would be useful to reference the appropriate places in the implementation details where it can find the information as it walks through each step in the core implementation or in the refinement.\n```\n\nThis helps refine the implementation plan and helps you avoid potential blind spots that your AI agent missed in its planning cycle. Once the initial refinement pass is complete, ask your AI agent to go through the checklist once more before you can get to the implementation.\n\nYou can also ask your AI agent (if you have the [GitHub CLI](https://docs.github.com/en/github-cli/github-cli) installed) to go ahead and create a pull request from your current branch to `main` with a detailed description, to make sure that the effort is properly tracked.\n\n\u003e[!NOTE]\n\u003eBefore you have the agent implement it, it's also worth prompting your AI agent to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask your AI agent to resolve them. Ensure that your AI agent follows the [principles](memory/principles.md) as the foundational piece that it must adhere to when establishing the plan.\n\n### **STEP 5:** Generate task breakdown with /iac.tasks\n\nWith the implementation plan validated, you can now break down the plan into specific, actionable tasks that can be executed in the correct order. Use the `/iac.tasks` command to have IaC Spec Kit guide AI agents in generating a detailed task breakdown from your implementation plan:\n\n```text\n/iac.tasks\n```\n\nThis step creates a `tasks.md` file in your feature specification directory that contains:\n\n- **Task breakdown organized by infrastructure component** - Each component becomes a separate implementation phase with its own set of tasks\n- **Dependency management** - Tasks are ordered to respect dependencies between components (e.g., networking before compute, compute before databases)\n- **Parallel execution markers** - Tasks that can run in parallel are marked with `[P]` to optimize development workflow\n- **File path specifications** - Each task includes the exact file paths where Terraform configuration should be created\n- **Validation checkpoints** - Each component phase includes checkpoints to validate (for example with `terraform validate`, `terraform fmt`, and `tflint`)\n- **Checkpoint validation** - Each infrastructure component phase includes checkpoints to validate independent functionality\n\nThe generated tasks.md provides a clear roadmap for the `/iac.implement` command. IaC Spec Kit helps AI agents ensure systematic implementation that maintains infrastructure quality and allows for incremental delivery of infrastructure components.\n\n### **STEP 6:** Implementation\n\nOnce ready, use the `/iac.implement` command to execute your implementation plan:\n\n```text\n/iac.implement\n```\n\nThe `/iac.implement` command helps AI agents:\n\n- Validate that all prerequisites are in place (principles, spec, plan, and tasks)\n- Parse the task breakdown from `tasks.md`\n- Execute tasks in the correct order, respecting dependencies and parallel execution markers\n- Generate IaC configuration, such as Terraform configuration files (.tf)\n- Provide progress updates and handle errors appropriately\n\n\u003e[!IMPORTANT]\n\u003eThe AI agent will execute local CLI commands (such as `terraform`, `ibmcloud`, `aws`, etc.) - make sure you have the required tools installed on your machine.\n\nOnce the implementation is complete, review the generated Terraform code and run validation commands:\n\n```bash\nterraform init\nterraform validate\nterraform fmt -check\ntflint\n```\n\nResolve any validation errors by providing feedback to your AI agent. Remember that `terraform apply` is a manual step you control - review the plan carefully before applying changes to your infrastructure.\n\n\u003c/details\u003e\n\n---\n\n## Contributing\n\nIaC Spec Kit is an experimental project exploring how Specification-Driven Development improves infrastructure as code workflows with AI assistance. Contributions are welcome in any area—template refinement, documentation, examples, validation improvements, cloud provider support, AI agent compatibility, or entirely new ideas.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on development setup, testing workflow, and PR submission.\n\n### Future ideas\n\nPotential areas for exploration include template refinement, validation improvements, AI agent compatibility, automation tooling, extensibility mechanisms, and patterns for other infrastructure domains. See [IDEAS.md](IDEAS.md) for the complete list. All ideas are open for anyone to pick up and explore.\n\n## Support\n\nFor support, please open a [GitHub issue](https://github.com/ibm/iac-spec-kit/issues/new). Bug reports, feature requests, and questions about using Spec-Driven Development for Infrastructure as Code are welcome.\n\n## Acknowledgements\n\nThis project is built upon the [GitHub Spec Kit](https://github.com/github/spec-kit) toolkit created by:\n- [John Lam](https://github.com/jflam)\n- [Den Delimarsky](https://github.com/localden)\n- The GitHub Spec Kit community\n\nWe are grateful for their foundational work in creating tools and patterns for Specification-Driven Development. This implementation adapts their toolkit specifically for Infrastructure as Code workflows.\n\n## License\n\nThis project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm%2Fiac-spec-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibm%2Fiac-spec-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm%2Fiac-spec-kit/lists"}