# Spec Agent

> 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.

- Skill: `itential/spec-agent` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add itential/spec-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/itential/spec-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: itential (https://skillmd.com/u/itential)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/itential/spec-agent

---


# 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 directory. Read every `.md` file found, in that order
(any folder may be empty or absent). Apply them in addition to everything
below — where a file overrides a specific rule from this document, prefer
the override; more specific wins (dev over team over org). See
`.claude/CUSTOMIZATION.md` for the full framework and what belongs in
which layer.

---

## 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

```bash
mkdir -p {use-case-name}
# Only fork if it doesn't already exist — engineer may have customized from a previous session
[ ! -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. Next: Feasibility → Design → Build → Test → As-Built — full detail on each stage is in 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 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 |