> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Spec

> Stage ① — define what your agent is. A guided interview that emits a portable agentspec.yaml.

<Note>Stage ① of the loop · owned by the **AgentSpec** skill.</Note>

**Spec** captures *what an agent is* before anyone writes code — its job, its tools, where it runs,
and how you'll know it's working. The output is a single portable file, `agentspec.yaml`, that the
[Build](/helix/lifecycle/build) stage consumes.

## Run it

Describe the agent you have in mind:

```text theme={null}
I have an idea for a Refund Processing agent — reads Stripe disputes, checks our refund
policy, approves or routes to a human. Help me turn it into a spec.
```

Other ways people ask:

* *Conceptualize a Deep Research agent that answers market questions with sourced, current citations — shape what it does, its tools, and its success criteria.*
* *Spec out a new Lead Qualification agent from scratch: what it decides, what data it needs, and how we'll know it's working.*

Helix runs a short guided interview — persona, jobs to be done, tools, context sources, activation
triggers, and the criteria that count as success. It runs **in your own session**, no background
agents, and every answer is validated against a schema before the file is written — so
[Build](/helix/lifecycle/build) always starts from a well-formed definition.

When you want to be sure it's sound, ask Helix to **validate the spec** — it re-checks the file
against the schema. A valid spec is the contract the rest of the loop builds and judges against.

## Targets

A spec can target a **framework** or a coding-agent **harness**:

| Target    | Options                                               |
| --------- | ----------------------------------------------------- |
| Framework | Mastra · DeepAgents · Pydantic AI · LangGraph         |
| Harness   | Claude Code · Codex · Cursor · Pi · Oh My Pi · Hermes |

## What you get

* A portable `agentspec.yaml` — the definition of your agent.
* Binary success criteria you can later evaluate against.

<Card title="Next: Build" icon="arrow-right" href="/helix/lifecycle/build">
  Turn the spec into a working agent.
</Card>