Spec-driven infrastructure automation and orchestration — delivered by AI agents on Itential.
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 six structured stages, with AI agents executing each stage and engineers approving the artifacts that gate the next one.
Requirements → Feasibility → Design → Build → Test → As-Built
│ │ │ │ │ │
/spec-agent /solution- /solution- /builder- /qa-agent /qa-agent
arch-agent arch-agent agent
│ │ │ │ │ │
customer- feasibility.md solution- assets test-plan.md as-built.md
spec.md (approved) design.md (delivered) (approved), (approved)
(approved) (approved) test-report.md
The result is infrastructure automation that is traceable, repeatable, and delivered faster.
| Requirement | Version | Notes |
|---|---|---|
| Itential Platform | 6.x | Target platform for every skill |
| IAG | 5.x | Only for the /iag skill |
| AI coding tool | — | Claude Code is the primary target (.claude/skills/<name>/SKILL.md, plugin install, /plugin update). Copilot reads the same .claude/skills path. Codex CLI and Cursor read .agents/skills instead — symlinked here to .claude/skills. See AGENTS.md. |
Install:
| Tool | Steps |
|---|---|
| Claude Code | /plugin marketplace add itential/builder-skills then /plugin install itential-builder@itential-builder. Update anytime with /plugin update itential-builder@itential-builder. |
| Codex CLI | codex plugin marketplace add itential/builder-skills registers this repo (reads .agents/plugins/marketplace.json), then install it from Codex's Plugins UI. |
| GitHub Copilot | No install step. Clone or open this repo — Copilot's coding agent reads .claude/skills directly. |
| Cursor | No install step. Clone or open this repo — Cursor auto-discovers skills from .agents/skills on start. |
First-time setup:
Create a folder for your use case and copy the environment template that matches your platform:
mkdir my-use-case
cp environments/cloud-lab.env my-use-case/.env # Cloud / OAuth
# or: cp environments/local-dev.env my-use-case/.env (Local / Password)
# or: cp environments/staging.env my-use-case/.env
cd my-use-caseOpen .env and fill in your values — PLATFORM_URL, plus either CLIENT_ID/CLIENT_SECRET (OAuth) or USERNAME/PASSWORD (local dev).
Then 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
"Am I ready to move from Gateway 4 (IAG4) to Gateway 5 (IAG5)?"
→ /itential-builder:gateway4-to-gateway5
"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 individually, then hands off to /qa-agent. |
/itential-builder:qa-agent |
Drafts a test plan from the approved acceptance criteria (engineer approves before anything runs live), generates and runs static + acceptance test cases against the delivered build, and produces test-report.md and as-built.md. The last technical stage before customer sign-off. |
/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 agent sessions. 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:gateway4-to-gateway5 |
Assesses readiness to migrate from Gateway4-IAG4 to Gateway5-IAG5. Scans workflows, JSON forms, scripts, playbooks, and inventory for Gateway4-IAG4 usage (AGManager / automation_gateway). Produces a deterministic markdown readiness report with a manual-action checklist. Read-only — never modifies the platform. For building Gateway5-IAG5 services after the assessment, use /iag. |
/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. |
/itential-builder:itential-json-forms |
Builds IAP JSON Forms — static-enum dropdowns, REST-bound dropdowns (live data from IAP endpoints), and cascading dropdowns (field dependency). Use when wiring structured input panels for manual triggers or manual tasks. |
Every skill above is foundational — owned and updated by Itential. Don't edit a skill's SKILL.md directly; those edits get silently overwritten (or produce merge conflicts) the next time this plugin is updated.
Instead, every skill has a custom/ folder with three layers, read automatically before the skill acts. More specific overrides less specific — dev overrides team overrides org overrides the foundational skill:
.claude/skills/<skill-name>/
├── SKILL.md ← foundational, Itential-owned — never edit this
└── custom/
├── org/ ← company-wide rules (e.g. naming conventions, security policy)
├── team/ ← your team's rules
└── dev/ ← your own local overrides and drafts
See .claude/CUSTOMIZATION.md for the full framework — precedence rules, the required format for stating an override, and a decision guide for which layer a given customization belongs in.
Two ways to consume this repo, both safe for custom/ content:
- Plugin install (
/plugin update itential-builder@itential-builder) — simplest. Claude Code's plugin installer keeps each marketplace as a real git clone updated via fetch/merge, so untrackedcustom/content survives an update the same way any untracked file survives agit pull(verified directly — see.claude/CUSTOMIZATION.md). - Clone or fork directly — skip the plugin installer,
git pull/git mergefrom upstream yourself. Same guarantee, plus the option to track and share yourcustom/files across your team. Full setup and update commands are in.claude/CUSTOMIZATION.md.
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 fixes.claude/CUSTOMIZATION.md— customize any skill without editing it directly (org/team/dev layers)helpers/— 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
This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.
Made with ❤️ by the Itential community