| name | spec-agent |
| description | 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 22 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. |
Spec Agent
Stage: Requirements
Owns: Defining what needs to be built. Producing the approved HLD.
Hands off to: /solution-arch-agent
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 ${CLAUDE_PLUGIN_ROOT}/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 |
| 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.
Step 2: Fork the Spec
mkdir -p {use-case-name}
[ ! -f {use-case}/customer-spec.md ] && cp ${CLAUDE_PLUGIN_ROOT}/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, 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. Here's the rest of the delivery:
- Feasibility — The Solution Architecture Agent connects to your platform and assesses what's possible against your approved spec.
- Design — A solution design is produced with exactly what to build, reuse, and skip. You approve it before anything is built.
- Build — The Builder Agent implements the approved design and tests each component individually.
- Test — The QA Agent drafts a test plan from your acceptance criteria, which you approve before anything runs live, then verifies the delivered solution against it with real evidence.
- As-Built — What was actually delivered is recorded, backed by that test evidence, including any deviations and learnings.
You own approval 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 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 |
