Spec-driven infrastructure automation and orchestration — delivered by AI agents on Itential.
- Prerequisites
- Getting Started
- How to Use It
- Skills
- Spec Library
- Demo Specs
- Docs
- Contributing
- Support
Most infrastructure automation is built without a delivery model. No consistent stages, no traceability, no repeatable process — just ad hoc builds that are hard to maintain, document, or hand off.
This repository introduces Spec-Driven Development for infrastructure automation. Every delivery follows five structured stages, with AI agents executing each stage and engineers approving the artifacts that gate the next one.
Requirements → Feasibility → Design → Build → As-Built
│ │ │ │ │
/spec-agent /solution- /solution- /builder- /builder-
arch-agent arch-agent agent agent
│ │ │ │ │
customer- feasibility.md solution- assets as-built.md
spec.md (approved) design.md (delivered) (approved)
(approved) (approved)
The result is infrastructure automation that is traceable, repeatable, and delivered faster.
| Requirement | Version | Notes |
|---|---|---|
| Itential Platform | 6.x | |
| IAG | 5.x | Required only for the /iag skill |
| Claude Code | Latest | Install guide |
Install the plugin:
/plugin marketplace add itential/builder-skills
/plugin install itential-builder@itential-builderAlready installed? Update to the latest version:
/plugin update itential-builder@itential-builderFirst-time setup:
Create a folder for your use case and add a .env file with your platform credentials:
mkdir my-use-case && cd my-use-caseCloud / OAuth:
# my-use-case/.env
PLATFORM_URL=https://your-instance.itential.io
AUTH_METHOD=oauth
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secretLocal / Password:
# my-use-case/.env
PLATFORM_URL=http://localhost:4000
AUTH_METHOD=password
USERNAME=admin
PASSWORD=adminThen start your first delivery from inside that folder:
/itential-builder:spec-agent
See docs/quickstart.md for the full setup and first delivery walkthrough.
"I need to automate VLAN provisioning on my platform"
→ /itential-builder:spec-agent
"I have a FlowAgent that's been running in production — productionize it"
→ /itential-builder:flowagent-to-spec
"I have an existing project with no documentation"
→ /itential-builder:project-to-spec
"Document all my global workflows and group them by use case"
→ /itential-builder:documentation
"I want to explore what's available on my platform"
→ /itential-builder:explore
"Help me build a golden config for my devices and run compliance"
→ /itential-builder:itential-golden-config
Delivery
| Skill | What It Does |
|---|---|
/itential-builder:spec-agent |
Refines a use case into an approved requirements spec (HLD). Picks from 22 built-in specs or starts from scratch. Produces customer-spec.md — the input to every downstream stage. |
/itential-builder:solution-arch-agent |
Connects to your platform, assesses what it can support, and produces a feasibility decision and a concrete implementation plan. Outputs feasibility.md and solution-design.md. |
/itential-builder:builder-agent |
Implements the approved solution design end-to-end — workflows, templates, configs, projects. Tests each component, verifies acceptance criteria, and produces as-built.md. |
/itential-builder:flowagent-to-spec |
Reads a FlowAgent's config and mission history, reconstructs what it actually did, and produces a customer-spec.md for the deterministic equivalent. Turns agentic exploration into a governed delivery path. |
/itential-builder:project-to-spec |
Reads an existing Itential project — workflows, templates, MOP — and reverse-engineers a customer-spec.md and solution-design.md. Use to document undocumented automation or create a baseline for a rebuild. |
/itential-builder:documentation |
Surveys global assets on a platform — collects workflows, templates, LCM models, golden config, and OM automations, discovers their relationships, groups them into use cases, and produces customer-spec.md + solution-design.md per use case plus a master README. Optionally creates a project per use case and moves assets in with a reference impact report. For a named project, use /project-to-spec instead. |
/itential-builder:explore |
Authenticates to a platform, pulls live data, and lets you browse capabilities freely. Use for ad-hoc investigation before starting a delivery or when you need to work outside the lifecycle. |
Platform
| Skill | What It Does |
|---|---|
/itential-builder:flowagent |
Creates and runs AI agents on the Itential Platform. Configures LLM providers, registers tools (adapters, workflows, IAG services), and runs missions. Use when building or operating Flow AI agents. |
/itential-builder:iag |
Builds and runs IAG 5 services — Python scripts, Ansible playbooks, OpenTofu plans. Manages YAML service definitions, imports via iagctl, and calls services from Itential workflows via GatewayManager. |
/itential-builder:itential-mop |
Builds Method of Procedure command templates with variable substitution and validation rules. Runs CLI pre-checks and post-checks against devices, and uses analytic templates for before/after config comparison. |
/itential-builder:itential-devices |
Manages network devices in Itential Configuration Manager — onboard devices, take config backups, diff configurations, organize device groups, and apply device templates. |
/itential-builder:itential-golden-config |
Builds golden config trees and node-level config specs that define the expected configuration standard for your devices. Runs compliance plans, grades results, and generates remediation configs for violations. |
/itential-builder:itential-inventory |
Builds and manages device inventories in Itential Inventory Manager. Populates nodes in bulk, assigns tags, runs actions against inventory devices, and manages inventory-level access and grouping. |
/itential-builder:itential-lcm |
Defines reusable service resource models in Itential Lifecycle Manager, creates and manages resource instances, runs lifecycle actions, and tracks execution history. Use for service models that have create, update, and delete lifecycle phases. |
22 technology-agnostic HLD specs in spec-files/. Each spec is ready to use with /itential-builder:spec-agent as the starting point for a delivery.
| Category | Specs |
|---|---|
| Networking | Port Turn-Up · VLAN Provisioning · Circuit Provisioning · BGP Peer Provisioning · VPN Tunnel Provisioning · WAN Bandwidth Modification |
| Operations | Software Upgrade · Config Backup & Compliance · Network Health Check · Device Onboarding · Device Decommissioning · Change Management · Incident Auto-Remediation |
| Security | Firewall Rule Lifecycle · Cloud Security Groups · SSL Certificate Lifecycle |
| Infrastructure | DNS Record Management · IPAM Lifecycle · Load Balancer VIP · Config Drift Remediation · Network Compliance Audit · AWS Webserver Deploy |
Ready-to-run specs in spec-files/demo/ for walkthroughs and demonstrations.
| Spec | Description |
|---|---|
| Device Health Troubleshooting Agent | FlowAI agent spec for device health triage — runs diagnostics and surfaces findings |
| Linux Diagnostics Agent | FlowAI agent spec for Linux system diagnostics |
| DNS A Record Provisioning — Simple | Simplified DNS A record provisioning via Infoblox |
| DNS A Record Provisioning | Full DNS A record provisioning lifecycle |
docs/quickstart.md— install, setup, and first delivery walkthroughdocs/developer-flow.md— full lifecycle diagram and design principlesdocs/builder-flow.md— build sequence, asset structure, and import patterndocs/troubleshooting.md— common issues and fixeshelpers/— JSON scaffolds for workflows, templates, projects, and reference patterns
Contributions are welcome! Please read our Contributing Guide to get started. Before contributing, you'll need to sign our Contributor License Agreement.
- Bug Reports: Open an issue
- Questions: Start a discussion
- Lead Maintainer: @keepithuman
- Maintainer: @wcollins
This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.
Made with ❤️ by the Itential community