Spec-Driven Development – Network & Infrastructure Automation

Spec-Driven Development for Agentic Operations with Itential

The operating model applied to the use cases your team actually runs, at the scale and complexity your environment actually demands.

Guides 1 and 2 established what SDD is and what it looks like applied to real network and infrastructure automation. This guide covers how Itential operationalizes it – the four agents that execute the six stages, the governed skills that connect the model to your infrastructure, the artifact chain that functions as the audit record, and the progression from AI-assisted delivery to autonomous operations.

Overview

What’s In This Guide

Four Agents, Six Stages

The Spec Agent, Solution Architecture Agent, Builder Agent, and QA Agent – what each is authorized to do, what artifact it produces, what it cannot do, and how artifact-based handoffs govern the transition between stages.

17 Skills, Any Coding Agent

Itential Builder Skills ships four delivery agents and 17 skills that run in Claude Code, Codex, GitHub Copilot, and Cursor. Delivery skills run the SDD lifecycle and bring existing automation under governance. Platform skills give every agent governed access to FlowAgents, Itential Gateway, configuration, and lifecycle services for agentic infrastructure operations.

The Trust Progression

Three stages from AI-assisted to governed autonomy – what each looks like operationally, what earns the right to advance, and where most production teams should operate today.

Audience

Who This Guide Is For

Network & Infrastructure Engineers

Understand how the agents execute SDD, what each is authorized to do, how the governed skills connect to your actual infrastructure, and where to start based on where your team is today.

Automation Managers & Leads

Understand how Itential enforces phase boundaries, what governs agent execution, and how the artifact chain makes every delivery auditable – for human teams and agentic operations alike.

VPs, Directors & CTOs

Understand the governed autonomy progression, what the trust advancement requires, and what organizational prerequisites produce the foundation to move from AI-assisted to autonomous operations.

Why It Matters

The Problem with Unconstrained Agent Execution

An AI agent that operates on network and infrastructure without a governing operating model is not autonomous operations. It is unaccountable automation. The agent makes decisions at machine speed against requirements that were never formally agreed, in an environment it may not have fully validated, producing outputs with no authoritative record of what it changed or why.

This is not a hypothetical risk. It is the predictable outcome of deploying AI agents without the structural foundations that make human-executed automation trustworthy – approved requirements, reviewed designs, enforced phase boundaries, and a reconciled record after delivery. AI acceleration without those foundations does not eliminate the structural failures of informal practice. It reproduces them at machine speed and at larger scale.

The organizations advancing toward agentic operations safely are not doing so by constraining what their agents can do. They are doing so by ensuring agent execution occurs inside a governing operating model – one that defines the boundaries of agent authority, enforces phase transitions, and produces an auditable record of every action. SDD is that operating model. Itential is the platform that makes it executable.

The critical distinction: SDD practiced without platform enforcement degrades under AI acceleration. Agents produce well-formatted artifacts faster, but nothing enforces the gates. Nothing connects the spec to execution. Nothing makes the as-built record authoritative. The operating model exists on paper and is absent in practice. Platform enforcement is what converts SDD from a methodology into a governed system – and what makes agentic operations trustworthy at production scale.

The Execution Model

Four Agents, Six Stages: How Itential Executes SDD

Itential operationalizes the six SDD stages through four named agents. Each agent owns specific stages, is authorized to access specific platform capabilities, produces required artifacts, and cannot advance past a gate without explicit approval. The agent is the execution mechanism. The SDD operating model is the boundary that defines what it is authorized to do.

Stage 01

Requirements

Spec Agent

customer-spec.md

The Spec Agent runs requirements as a structured conversation – no platform access, no environment queries, no design work. It surfaces discovery questions about the use case, integration dependencies, operational constraints, blast radius, and acceptance criteria. It produces a written spec that captures what the automation must do, what success looks like, and what is explicitly out of scope.

Authorized to do

✓

Conduct structured discovery conversation

✓

Clarify scope, constraints, and success criteria

✓

Produce and refine the customer spec document

✓

Surface integration dependencies for feasibility

Not authorized to do

✗

Access the platform or any environment

✗

Make feasibility assumptions before Gate 1

✗

Begin any design or implementation work

✗

Advance to feasibility without Gate 1 approval

Gate 1

Requirements locked – spec approved in writing. No platform access, no environment authentication, no discovery until this gate is recorded.

Stage 02

Feasibility

Solution Architecture Agent

feasibility.md

Feasibility is the first point of platform access. The Solution Architecture Agent authenticates to the target environment via a scoped service account, inventories available API skills and integrations, validates platform capabilities against the approved spec, and identifies existing automation assets available for reuse. Findings that conflict with approved requirements surface as tradeoffs requiring a formal decision – not silent scope changes absorbed into design.

Authorized to do

✓

Authenticate via scoped service account

✓

Inventory available API skills & integrations

✓

Identify reuse candidates in existing automation estate

✓

Surface platform constraints against the approved spec

Not authorized to do

✗

Redefine approved requirements based on findings

✗

Absorb requirement conflicts silently into design

✗

Begin any design or implementation work

✗

Advance to design without an approved feasibility report

Stage 03

Design

Solution Architecture Agent

solution-design.md

The Solution Architecture Agent takes the approved feasibility findings and produces the solution design – the execution contract the build phase answers to. The design maps approved requirements to discovered capabilities: which components will be built, which assets will be reused, the dependency order for build, acceptance criteria per component, and the testing approach. Once approved at Gate 2, this document is the locked authority. Build does not interpret it – it executes it.

Authorized to do

✓

Map requirements to feasibility findings

✓

Specify component inventory & dependency order

✓

Define reuse decisions and acceptance criteria

✓

Produce the solution design document for review

Not authorized to do

✗

Begin building any platform asset

✗

Make design decisions not grounded in approved feasibility

✗

Advance to build without Gate 2 approval

Gate 2

Execution contract locked – solution design approved. Build cannot begin until this gate is recorded. The approved design is the authority build answers to, not the agent’s interpretation of it.

Stage 04

Build

Builder Agent

platform assets

The Builder Agent executes the approved design in dependency order – command templates, configuration primitives, and parsing logic before composite orchestration; child workflows before parent workflows. Each component is tested on its own as it is built, and the full set of assets is imported atomically. Where build encounters conditions not addressed in the approved design, those are surfaced as documented deviations – not resolved through ad-hoc judgment. When the build is complete, it hands off to the QA Agent. The agent that builds the automation does not certify it.

Authorized to do

✓

Build assets in approved dependency order

✓

Test each component individually as it is built

✓

Import assets atomically to the platform

✓

Surface deviations for documentation

Not authorized to do

✗

Reinterpret the approved solution design

✗

Make scope decisions not authorized by the design

✗

Certify its own build against acceptance criteria

✗

Absorb deviations without recording them

Stage 05

Test

QA Agent

test-plan.md
test-report.md

The QA Agent verifies the delivered build against the approved acceptance criteria – a separate agent from the one that built it. It drafts a test plan that maps every acceptance criterion to a test, asks the engineer for real test data and safe targets, and waits for approval before anything runs live. Static checks run first, validating workflow structure, task IDs, adapter references, and error handling. Acceptance tests then run real jobs against the delivered assets, with results checked in each task’s own output rather than job status alone. Failures go back to the Builder Agent with evidence. The QA Agent never edits a workflow itself.

Authorized to do

✓

Draft the test plan from approved acceptance criteria

✓

Request confirmed test data and safe targets

✓

Run static checks, then acceptance tests after Gate 3

✓

Report evidence for every acceptance criterion

Not authorized to do

✗

Run live tests before Gate 3 approval

✗

Invent test data, devices, or targets

✗

Edit workflows or fix failures itself

✗

Declare a pass without evidence

Gate 3

Test plan approved. Acceptance tests run real jobs with real side effects – pushing config, opening tickets, allocating addresses – so nothing executes live until the engineer confirms the plan, the test data, and the targets.

Stage 06

As-Built

QA Agent

as-built.md

Once tests pass, the QA Agent compares the delivered automation against the approved solution design and produces the as-built record, backed by the test report. Deviations are documented – what changed, why it changed, what conditions required adaptation. Original artifacts are preserved. The reconciled record becomes the authoritative baseline for all future work on this use case – what the next engineer, the next agent, and the next audit start from.

Authorized to do

✓

Compare delivered state against approved design

✓

Document deviations and their causes

✓

Back the record with test evidence

✓

Produce the reconciled as-built record

Not authorized to do

✗

Overwrite or replace original approved artifacts

✗

Write the as-built record before tests pass or residuals are accepted

✗

Treat as-built as optional when delivery is clean

Sign-off

Delivery signed off – the engineer approves the as-built record, and the use case is marked delivered. That record is the baseline every future change starts from.

Governed Skills

Four Agents, 17 Skills, Any Coding Agent

The agents above execute the SDD lifecycle. What they execute against is the platform’s governed skill library – every system your automation touches, exposed as a skill the platform orchestrates against the approved spec. Not open API access engineers manage themselves. Skills with defined inputs, defined outputs, and defined access boundaries that execute within the governance envelope the operating model establishes.

Itential Builder Skills ships four delivery agents and 17 skills in one open-source package. Delivery skills run and extend the SDD lifecycle. Platform skills are what every agent invokes against your actual infrastructure.

Runs in the Coding Agent Your Team Already Uses

The same skills, stages, gates, and artifacts work in five coding harnesses, using whichever model each one is configured with. Only the install step and the invoke syntax change.

Claude Code

/itential-builder:spec-agent

Codex CLI

$spec-agent

GitHub Copilot CLI

/spec-agent

GitHub Copilot in VS Code

/spec-agent

Cursor

/spec-agent

Install steps for every coding agent →

SDD Delivery Agents: 4 Agents, 6 Stages

Four agents execute the six SDD stages. Each owns specific stages, produces a required artifact, and cannot advance past a gate without explicit approval. These are the agents that operationalize the operating model.

spec-agent

Spec Agent

Structured discovery conversation. Produces the approved customer spec. No platform access until Gate 1.

Stage 01 – Requirements

solution-arch-agent

Solution Architecture Agent

Platform discovery, integration validation, feasibility report and solution design production.

Stages 02 & 03 – Feasibility & Design

builder-agent

Builder Agent

Executes the approved design in dependency order. Tests each component and imports assets atomically.

Stage 04 – Build

qa-agent

QA Agent

Plans and runs acceptance tests against the approved criteria. Produces the test report and the as-built record.

Stages 05 & 06 – Test & As-Built

Delivery Skills: Conversion, Retrofit & Discovery

Four delivery skills sit outside the six-stage path. They bring exploratory agent work and existing automation into the SDD lifecycle, or let you survey a platform before a formal engagement begins.

flowagent-to-spec

FlowAgent to Spec

Reads a FlowAgent’s configuration and mission history, reconstructs what it actually did, and produces a spec for the deterministic equivalent – converting exploratory agent work into a governed SDD delivery path.

Bridge from agentic exploration to governed delivery

project-to-spec

Project to Spec

Reads an existing Itential project – workflows, templates, and command templates – and reverse-engineers a spec and solution design from it, bringing existing automation under SDD governance without starting from scratch.

Retrofit path for project automation

documentation

Documentation

Surveys global platform assets that live outside any project, discovers how they relate, groups them into use cases, and produces a spec and solution design for each – with the option to organize them into projects.

Retrofit path for global automation

explore

Explore

Authenticates to your Itential Platform environment and lets you browse what’s available – adapters, integrations, existing automation assets – before committing to a formal SDD engagement.

Discovery before a formal engagement begins

FlowAI & Itential Gateway Skills: Agents & Distributed Execution

flowagent

FlowAgent

Creates and runs FlowAgents on the Itential Platform – configures LLM providers, registers tools such as adapters, workflows, and Itential Gateway services, and runs agent sessions within defined missions.

Agentic workflows & AI-driven operations on platform

iag

Itential Gateway Services

Builds and runs Itential Gateway 5 services – Python scripts, Ansible playbooks, and OpenTofu plans – and calls them from Itential workflows. Governed, ephemeral runtimes that execute where your infrastructure lives.

Cloud APIs, server configuration, IaC delivery

gateway4-to-gateway5

Gateway 4 to Gateway 5 Readiness

Scans workflows, forms, scripts, playbooks, and inventory for Itential Gateway 4 usage and produces a readiness report with a manual-action checklist. Read-only – it never modifies the platform.

Migration planning

Network & Device Skills: Governed Access to Network Infrastructure

itential-devices

Device Management

Governed access to network devices in Configuration Manager – onboarding, configuration backups, diffs, device groups, and device templates.

Network provisioning, change management, compliance

itential-golden-config

Golden Config

Golden config trees and compliance plans against the approved standard – drift detection, compliance grading, and generated remediation configs. It never applies changes to a device; corrections ship through a governed config-push delivery.

Configuration compliance, drift reporting

itential-mop

Method of Procedure

Command templates with variable substitution and validation rules – CLI pre-checks and post-checks, plus analytic templates for before-and-after configuration comparison.

Change management, software upgrades

itential-lcm

Lifecycle Manager

Resource models, instances, and lifecycle action execution – governed management of network service lifecycles from activation through decommission.

Service lifecycle, device onboarding & retirement

itential-inventory

Inventory

Device inventories in Inventory Manager – bulk node population, tags, grouping, and actions run against inventory devices.

Targeting, grouping, inventory actions

itential-json-forms

JSON Forms

Structured input for manual triggers and manual tasks – static, REST-bound, and cascading dropdowns that give operators validated choices instead of free text.

Self-service input, manual approvals

The Guardrails That Travel With the Skills

The governance model doesn’t depend on which coding agent an engineer uses. It lives in the skills and in the files the skills read, so the same boundaries apply in every harness.

Same Model in Every Coding Agent

The skills follow the open Agent Skills convention, so Claude Code, Codex, GitHub Copilot, and Cursor all read the same skill files. The stages, gates, and artifacts are identical in each. Teams standardize the delivery model, not the editor.

Setup for every coding agent →

Hard Gates Before Every Action

A skill router makes loading the matching skill a precondition before an agent touches any platform asset. A pre-flight checklist confirms task names and schemas before every create call, and a circuit breaker stops the agent after a repeated error instead of letting it guess.

No improvisation against a live platform

Org, Team & Dev Policy Layers

Every skill reads organization, team, and developer override layers before it acts. A company-wide rule such as “no workflow may ever call runAutoRemediation” lives at the org layer and binds every engagement, whoever runs the agent. Overrides survive skill updates.

Policy-level governance, in practice

State That Lives in Files

Each use case keeps a memory file recording its stage, IDs, decisions, and open items. Every skill verifies that stage against the artifacts that actually exist before it resumes. If they disagree, the files win.

Resumable, inspectable deliveries

Every skill executes within the governance envelope. Itential Gateway distributes execution to wherever your infrastructure actually lives – network devices, on-prem servers, cloud APIs across AWS, Azure, and GCP – without losing the governance properties the SDD operating model requires. The skill is the governed interface. The gateway is what gets it there.

The Audit Record

The Artifact Chain as the Audit Record

Every SDD engagement executed through Itential produces a complete, linked sequence of artifacts – from the initial approved spec through the test evidence to the reconciled as-built record. This is the audit record. Every decision from intent to production state is traceable to the artifact that authorized it.

Approved Spec

customer-spec.md

→

Feasibility Report

feasibility.md

→

Solution Design

solution-design.md

→

Delivered Assets

automation + configs

→

Test Evidence

test-plan.md
test-report.md

→

As-Built Record

as-built.md

This chain answers the questions that informal practice cannot. What was the original requirement? What did feasibility find? What did the design approve? What was actually built? How was it tested, and against what data? Where did it deviate and why? Every question an auditor, a compliance team, a future engineer, or a subsequent agent might ask is answered by the artifact chain – not by inspecting workflow code or relying on whoever built it to remember.

For agentic operations, the artifact chain is what makes machine-speed execution auditable. An agent that deploys automation in twenty minutes leaves the same artifact trail as a human engineer working over two weeks. The speed changes. The accountability does not.

What the Chain Enables on Day 2

Every Day 2 engagement – extension, debug session, modification, handoff – starts from the reconciled as-built record rather than from archaeology. The next engineer knows exactly what was built, how it was tested, what deviated from the design, and why. The next agent can be scoped against the same artifact chain. The compliance team has the evidence package they need without a post-delivery documentation sprint. The automation estate compounds rather than accumulates debt.

For compliance teams: The artifact chain from approved spec through as-built record is the evidence package for every automated change. Auditors can trace any delivered automation to its approved requirements and see exactly where implementation diverged from the design and why. This is not post-hoc documentation – it is a required output of the delivery process, produced by the platform as the engagement closes.

The Trust Progression

The Governed Autonomy Progression

Itential is the agentic operations platform for network and infrastructure automation. Agentic operations in Itential follow a trust progression – not a capability ladder, but a governance model. Each stage increases the scope of agent authority based on demonstrated reliability of agent execution. Human oversight shifts from execution-level to gate-level to policy-level. The SDD operating model remains constant throughout. What changes is who performs each stage and at what level humans maintain decision authority.

AI-Assisted SDD

Human-in-loop throughout

Agents draft artifacts – the spec, feasibility report, solution design, test plan, and as-built record. Human engineers review, refine, and approve each one. Build may still be human-executed. Agents accelerate artifact production; humans retain decision authority at every stage and gate. This is the appropriate starting point for teams introducing AI into an established SDD practice.

AI-Driven SDD

Human-at-gates

Agents execute all six stages. Human engineers govern the approval gates – Gate 1 locking requirements, Gate 2 locking the execution contract, and Gate 3 approving the test plan before anything runs live. Execution is agent-driven; governance is human-maintained. The human role shifts from builder and reviewer to approver. This is where most production deployments will operate as agent reliability is established through the AI-Assisted stage.

Governed Autonomy

Human-at-policy level

For well-understood, low-blast-radius operations within a mature spec library, agents operate within pre-approved policy boundaries. A class of operations is approved, not individual requests. Agents execute and produce as-built records. Human oversight applies at the policy level – not per engagement. This stage requires a mature as-built record library to define the boundaries agents operate within, and org-level policy layers in the skills that define what no agent may do, whoever runs it.

The progression from Stage 1 to Stage 3 is earned, not assumed. Stage 3 autonomy for VLAN provisioning on a mature, reconciled automation estate is reasonable. Stage 3 autonomy for a new integration class with no prior as-built record is not. The artifact chain is what makes the advancement decision defensible – each engagement’s as-built record is evidence of agent execution quality that can be assessed before trust is extended further.

Most production infrastructure teams will operate at Stage 2. That is the correct posture for most production automation – and it produces significant value. Stage 3 is not a target for all use cases. It is appropriate for specific, well-bounded operations where the as-built record library is sufficient to define the policy boundaries agents operate within. The goal is not maximum autonomy. The goal is the right level of autonomy for each use case, with the governance to back it up.

The Spec Library

22 Ready-to-Use Starting Points

The Itential Builder Skills ship with 22 technology-agnostic High-Level Design specs – one for each of the most common network and infrastructure automation use cases. Each spec is a starting point, not a template to follow verbatim. Hand it to the Spec Agent, tell it what’s different about your environment, and it refines it for your specific infrastructure before kicking off a delivery.

Networking

Port Turn-Up

Networking

VLAN Provisioning

Networking

Circuit Provisioning

Networking

BGP Peer Provisioning

Networking

VPN Tunnel Provisioning

Networking

WAN Bandwidth Modification

Operations

Software Upgrade

Operations

Config Backup & Compliance

Operations

Network Health Check

Operations

Device Onboarding

Operations

Device Decommissioning

Operations

Change Management

Operations

Incident Auto-Remediation

Security

Firewall Rule Lifecycle

Security

Cloud Security Groups

Security

SSL Certificate Lifecycle

Infrastructure

DNS Record Management

Infrastructure

IPAM Lifecycle

Infrastructure

Load Balancer VIP

Infrastructure

Config Drift Remediation

Infrastructure

Network Compliance Audit

Infrastructure

AWS Webserver Deploy

The specs are available in the Itential Builder Skills GitHub repo. Clone the repo, pick the spec closest to your use case, and use the Spec Agent to refine it for your environment before kicking off a delivery. The repo also includes example environments, JSON scaffolds for workflows, templates, and projects, and importable vendor and platform asset exports that accelerate the Build stage.

Getting Started

Entry Points by Automation Maturity

The right starting point depends on where your team is today. Three practical paths based on your current automation state. The commands below use Claude Code syntax; in Codex, invoke skills with $spec-agent, and in GitHub Copilot or Cursor, with /spec-agent. Setup for every coding agent is on the Itential Builder Skills page.

If you have existing automation but no SDD

Start with project-to-spec

Before building anything new, establish a baseline. The project-to-spec skill reads existing platform projects and reverse-engineers a spec and solution design from what’s already deployed. This produces the as-built record your existing automation never had – and makes it the starting point for all future Day 2 work on those use cases. Build the governance layer on top of what you already have, then extend it forward with SDD. For global automation that doesn’t belong to any project, the documentation skill does the same across the whole platform, grouping assets into use cases first.

/itential-builder:project-to-spec

If you have SDD practice but no agents

Start at Stage 1 – AI-Assisted

Use the Spec Agent to draft requirements, the Solution Architecture Agent to produce feasibility reports and solution designs, the Builder Agent to construct assets, and the QA Agent to plan and run acceptance tests – but review and approve every artifact before advancing. Run three to five engagements at Stage 1 before evaluating whether agent artifact quality supports moving to Stage 2. The as-built records from those engagements are the evidence base for that decision.

/itential-builder:spec-agent

If you are starting from scratch

Start with the full model from day one

Teams starting without an existing automation estate have the advantage of building the spec library from engagement one. Every engagement produces a reconciled as-built record that compounds. The spec library becomes the agent’s operating boundary library. The as-built collection becomes the training ground for advancing through the trust stages. Starting with the full SDD model is not harder – it is faster to a trusted, scalable automation estate than retrofitting governance later.

/itential-builder:spec-agent → solution-arch-agent → builder-agent → qa-agent

Continue the Series

GUIDE 01

What Is Spec-Driven Development?

Read Guide 1 →

GUIDE 02

SDD for Network Automation

Read Guide 2 →

GUIDE 03

Agentic SDD & Autonomous Network Operations with Itential

You Are Here

Keep Learning