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

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:

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

Step 2: Fork the Spec

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