Skip to content

README.md

Latest commit

 

History

History
372 lines (265 loc) · 9.15 KB

README.md

File metadata and controls

372 lines (265 loc) · 9.15 KB

🚀 SpecOps

Spec-Driven Infrastructure as Code

Build production-ready infrastructure with systematic deployment automation using Terraform, Ansible, and ArgoCD.

License Python

🤔 What is SpecOps?

SpecOps brings the Spec-Driven Development methodology to Infrastructure as Code. Instead of "vibe coding" your infrastructure, you:

  1. Define infrastructure requirements clearly
  2. Plan technical implementation systematically
  3. Execute with AI-assisted automation
  4. Deploy confidently with GitOps

SpecOps is inspired by GitHub's Spec Kit and adapted specifically for infrastructure engineering.

⚡ Quick Start

Prerequisites

Installation

# Install SpecOps CLI
uv tool install specops-cli --from git+https://github.com/dotlabshq/spec-ops.git

# Verify installation
specops check

Create Your First Infrastructure Project

# Initialize new project
specops init my-infrastructure --ai claude

# Navigate to project
cd my-infrastructure

# Launch your AI agent (e.g., Claude Code)
claude

# Follow the workflow:
# 1. /specops.constitution - Establish principles
# 2. /specops.specify - Define infrastructure requirements
# 3. /specops.plan - Create technical implementation plan
# 4. /specops.tasks - Generate task breakdown
# 5. /specops.implement - Execute deployment

🏗️ Technology Stack

SpecOps is built around a proven infrastructure stack:

Component Tool Purpose
VM Provisioning Terraform Infrastructure as Code for cloud resources
K8s Setup Ansible Configuration management and cluster installation
App Deployment ArgoCD GitOps continuous delivery
Network Cilium eBPF-based CNI with network policies
Multi-tenancy Kubernetes Namespace isolation with RBAC

📚 Core Concepts

Spec-Driven Infrastructure

Traditional approach:

💭 Idea → 🔨 Code → 📝 Documentation (maybe)

SpecOps approach:

💭 Idea → 📋 Specification → 📐 Plan → ✅ Tasks → 🚀 Implementation

The Five Commands

1. /specops.constitution

Establish your infrastructure principles and standards.

/specops.constitution Create principles for multi-tenant Kubernetes using Terraform, 
Ansible, ArgoCD, and Cilium. Focus on security, scalability, and operational excellence.

Output: .specops/memory/constitution.md

2. /specops.specify

Define what you want to build and why.

/specops.specify Deploy a single sign-on (SSO) solution for our organization. 
Need to support multiple authentication providers and integrate with existing LDAP.
Must be isolated per organization using namespace boundaries.

Output: .specops/specs/001-sso-deployment/spec.md

3. /specops.plan

Specify how to implement it technically.

/specops.plan Use Zitadel for SSO deployed via Helm. PostgreSQL backend in same namespace.
Configure Cilium network policies for isolation. Expose via ingress with TLS.

Output: .specops/specs/001-sso-deployment/plan.md

4. /specops.tasks

Generate actionable task breakdown.

/specops.tasks

Output: .specops/specs/001-sso-deployment/tasks.md

5. /specops.implement

Execute the implementation with AI assistance.

/specops.implement

Result: Working infrastructure deployed and version controlled!

🎯 Use Cases

Multi-Organization Kubernetes Platform

Deploy a shared Kubernetes cluster with:

  • Namespace-based isolation per organization
  • Cilium network policies for security
  • Resource quotas and limits
  • GitOps deployment with ArgoCD

Complete Application Stack

Provision end-to-end:

  • VMs/cloud resources (Terraform)
  • Kubernetes cluster (Ansible)
  • Applications (ArgoCD)
  • Monitoring (Prometheus + Grafana)
  • Logging (ELK/Loki)

Compliance-Ready Infrastructure

Build infrastructure that meets:

  • Security best practices
  • Audit requirements
  • Disaster recovery standards
  • Documentation requirements

📖 Documentation

Getting Started

Concepts

Examples

🤖 Supported AI Agents

SpecOps works with popular AI coding assistants:

Agent Status Notes
Claude Code ✅ Full Support Recommended
GitHub Copilot ✅ Full Support Via VS Code
Cursor ✅ Full Support
Gemini CLI ✅ Full Support
Windsurf ✅ Full Support

🏛️ Project Structure

my-infrastructure/
├── terraform/              # Infrastructure provisioning
│   ├── modules/           # Reusable Terraform modules
│   └── environments/      # Environment configs (dev, prod)
├── ansible/               # Kubernetes cluster setup
│   ├── roles/            # Ansible roles
│   ├── playbooks/        # Playbooks for cluster management
│   └── inventory/        # Dynamic inventory
├── kubernetes/            # Application deployments
│   ├── argocd/           # ArgoCD setup and apps
│   ├── apps/             # Application manifests
│   ├── namespaces/       # Namespace definitions
│   └── network-policies/ # Cilium network policies
└── .specops/             # SpecOps artifacts
    ├── memory/
    │   └── constitution.md
    ├── specs/
    │   └── 001-feature/
    │       ├── spec.md
    │       ├── plan.md
    │       └── tasks.md
    └── templates/

🔧 CLI Reference

Commands

# Initialize new project
specops init <project-name> [OPTIONS]

# Check installed tools
specops check

# Version information
specops --version

Options

--ai <agent>              # AI agent: claude, copilot, cursor, gemini, windsurf
--script <type>           # Script type: sh (bash) or ps (PowerShell)
--here                    # Initialize in current directory
--force                   # Force overwrite in non-empty directory
--no-git                  # Skip git initialization
--ignore-agent-tools      # Skip AI agent checks
--debug                   # Enable debug output

Examples

# Basic initialization
specops init my-infra --ai claude

# Initialize in current directory
specops init . --ai copilot
specops init --here --ai cursor

# Force overwrite
specops init . --force --ai claude

# Skip git initialization
specops init my-infra --ai gemini --no-git

# Debug mode
specops init my-infra --ai claude --debug

🛠️ Development

Setup Development Environment

# Clone repository
git clone https://github.com/dotlabshq/specops.git
cd specops

# Install dependencies
uv sync

# Install in editable mode
uv pip install -e .

# Run CLI
specops --help

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=specops_cli

# Run specific test
pytest tests/test_cli.py

Code Quality

# Format code
black src/

# Lint code
ruff check src/

# Type checking
mypy src/

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Areas We Need Help

  • Additional AI agent integrations
  • Cloud provider templates (AWS, Azure, GCP)
  • Example infrastructure patterns
  • Documentation improvements
  • Bug fixes and testing

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgements

  • Inspired by GitHub Spec Kit
  • Built on top of industry-standard tools: Terraform, Ansible, Kubernetes, ArgoCD, Cilium

📞 Support

Built with ❤️ for infrastructure engineers who believe in systematic, spec-driven automation.