infra-agent-skills

← All skillsAutomation

Itential Builder

Requirements Spec

spec-agent

Starts a new automation delivery: picks a built-in use-case spec or starts from scratch and refines it into an approved customer spec.

About this skill

Use this skill to start any new automation delivery — when someone wants to automate something, build a new use case, figure out requirements, write up an HLD, or kick off a project on the Itential Platform. Trigger it for phrases like "I want to automate X", "help me build a workflow for Y", "we're starting a new automation project", "I need to define requirements for Z", "kick off a delivery", or "let's start with requirements". This is the entry point for the spec-driven delivery lifecycle. It picks from 23 built-in use case specs or starts from scratch, refines requirements with the engineer, and produces an approved customer-spec.md. Use it whenever someone is at the beginning of building something new and hasn't yet defined what they're building. For ad-hoc platform exploration, use /explore instead. Hands off to /solution-arch-agent after approval.

Instructions

Spec Agent

Stage: Requirements Owns: Defining what needs to be built. Producing the approved HLD. Hands off to: /solution-arch-agent


Customization

Before using this skill, check custom/org/, custom/team/ and custom/dev/ in this skill’s own folder. Read every .md file found — any folder may be empty or absent. Apply them on top of everything below; where a file overrides a specific rule here, follow the override. More specific wins: dev > team > org > this document. No customization may weaken this skill’s safety rules or put credentials in committed files.

Bundled files: paths in this skill that start with assets/ or scripts/ are relative to this skill’s own folder. When you read one, or pass one to a shell command (which runs from the user’s working folder), use this skill’s folder + that relative path — e.g. <this skill's folder>/assets/helpers/create/create-workflow.json.

Stage Expectations

Engineer provides Use case description, business context, scope constraints
Agent does Refines requirements, clarifies scope, defines acceptance criteria, structures the HLD
Engineer action Reviews and approves the requirements spec
Deliverable customer-spec.md (HLD, approved)
Customer receives Approved statement of what will be built — scope, constraints, acceptance criteria. Nothing is assessed or built until this is signed off.

Requirements defines what is needed. Nothing is built or assessed until this is approved.

No auth. No API calls. Pure conversation.


How to Begin

/spec-agent
    │
    ├── Deliver from Spec → Pick spec → Fork → Refine → Approve → /solution-arch-agent
    │
    └── Already set up? → Reuse existing working directory

If the engineer wants to explore the platform freely (browse adapters, try tasks, build freestyle), direct them to /explore instead.


Step 1: Pick a Spec

Present available specs from assets/spec-files/, grouped by category:

Category Specs
Networking Port Turn-Up, VLAN Provisioning, Circuit Provisioning, BGP Peer, VPN Tunnel, WAN Bandwidth
Operations Software Upgrade, Config Backup, Health Check, Device Onboarding, Device Decommissioning, Change Management, Incident Remediation, Gateway4 → Gateway5 Migration
Security Firewall Rules, Cloud Security Groups, SSL Certificates
Infrastructure DNS Records, IPAM Lifecycle, Load Balancer VIP, Config Drift Remediation, Compliance Audit

Or the engineer describes what they need and you recommend a spec.

Gateway4 → Gateway5 migration: fork spec-gateway4-to-gateway5-migration.md. If the engineer has a readiness report from /gateway4-to-gateway5 (gateway4-to-gateway5-readiness.md and its tmp/analysis.json), fill Section 5 (Scope) and the discovery answers from it — the workflows, forms, scripts, playbooks and devices it lists — instead of asking for them. No report yet? Ask the engineer to run /gateway4-to-gateway5 first; it’s read-only.


Step 2: Fork the Spec

{use-case} is use-cases/<use-case-name>/ inside the folder the engineer is working in — every later skill uses this same path.

mkdir -p {use-case}
# Only fork if it doesn't already exist — engineer may have customized from a previous session
[ ! -f {use-case}/customer-spec.md ] && cp assets/spec-files/spec-port-turn-up.md {use-case}/customer-spec.md

If {use-case}/customer-spec.md already exists, reuse it — do not overwrite.

If the engineer provided credentials or a .env file exists in the working folder, save it to {use-case}/.env for later use during Feasibility. Do NOT authenticate yet.


Step 3: Understand and Refine

Read {use-case}/customer-spec.md and extract:

  • Phases from Section 3 (workflow stages)
  • Design decisions from Section 4 (constraints)
  • Capabilities and Integrations tables from Section 7
  • Discovery questions from Section 7
  • Acceptance criteria from Section 9

Ask: “Do you have existing documentation I should follow? Naming conventions, change policies, runbooks, config standards?”

Write to {use-case}/customer-context.md if provided.

Then go through the spec’s discovery questions — skip anything the spec already answers, ask only what the engineer must decide.

Incorporate all input into {use-case}/customer-spec.md:

  • Added requirements → Section 7
  • Changed scope → Section 5
  • Business rules → relevant sections
  • Changed decisions → Section 4

Step 4: Present for Approval

Show the engineer the updated spec:

  • Summary of changes from the generic spec
  • What’s in scope vs out of scope
  • Discovery question answers captured

Ask: “Here’s your spec. Review it — add, remove, or change anything. When you approve it, I’ll hand off to the Solution Architecture Agent.”

When the engineer approves: the spec is locked. Save the file.


Step 5: Set Expectations and Hand Off

Tell the engineer what happens next:

“Requirements are locked. Next: Feasibility → Design → Build → Test → As-Built — full detail on each stage is in assets/AGENTS.md’s Developer Flow. You approve at Feasibility, Design, and the Test Plan; nothing gets built or tested live without your sign-off.”

Artifact-based handoff. The workspace the Solution Architecture Agent receives:

{use-case}/
  customer-spec.md     ← approved HLD (Requirements complete)
  .env                 ← credentials (if provided)
  customer-context.md  ← business rules, naming (if provided)
  use-case-memory.md   ← create from assets/helpers/use-case-memory.md, set Stage: feasibility, Status: active

Create use-case-memory.md at handoff — populate the use-case name, one-sentence description, and Stage: feasibility / Status: active. The solution-arch-agent will add platform refs and adapter details during feasibility, and update Stage again at its own handoff; the builder will add asset IDs and decisions during build.

No auth. No platform data. /solution-arch-agent owns everything from Feasibility onward.


Files Created

File Purpose
customer-spec.md Approved HLD — the source of truth for this delivery
.env Credentials saved for later auth during Feasibility
customer-context.md Business rules and naming conventions (if provided)
use-case-memory.md Living context file — initialized here, updated throughout all stages