Spec

Stage 1 of the agentic development lifecycle (ADLC) · run with /spec.

What goes in, what you type, what comes out


Goes in	A sentence about the agent you want, plus anything in your project Helix can read for context (sample inputs, existing prompts, docs). No traces needed.
You type	`/spec a contract-review agent that extracts governing law, indemnification and termination clauses from vendor contracts`
Comes out	`.mutagent/specs/<agent-id>/agentspec.yaml`: the agent’s intent, constraints, non-goals, system prompt, procedure, target, and the evaluation criteria the later stages score against. The session ends by naming the next step, `/build`.

An excerpt of a real run’s output:

.mutagent/specs/contract-reviewer/agentspec.yaml

spec:
  intent:
    outcomes:
      - "Extract governing law jurisdiction, indemnification coverage/triggers, and
         termination terms into validated structured JSON."
    constraints:
      - "Never fabricate or hallucinate contract language."

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

Run it

Describe the agent you have in mind:

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 always starts from a well-formed definition. Headless (helix -p), the interview cannot ask questions. Put the answers in the /spec prompt (the output format, what to do when an input is missing, and the target), then continue the same session with helix -c -p "/build":

helix -p "/spec a contract-review agent that extracts governing law, indemnification and termination clauses from vendor contracts. Output: JSON, one field per clause with the verbatim text. A missing clause is null with a note. It runs as a Claude Code agent."
helix -c -p "/build"

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. To change a spec you already have, ask Helix to update the agent spec: the same interview runs, starting from your existing agentspec.yaml instead of a blank one.

Targets

A spec can target an agent framework (code), a coding agent that runs markdown agents, or the Mutagent platform:

Target	Options
Framework	Mastra · DeepAgents · Pydantic AI · LangGraph
Coding agent	Claude Code · Codex
Mutagent platform	An `agent.md` package you deploy with `mutagent agent deploy`

What you get

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

Next: Build

Turn the spec into a working agent.

Get started

Run it

Lifecycle

Features

Helix Cloud

Reference

What goes in, what you type, what comes out

Run it

Targets

What you get

Next: Build

​What goes in, what you type, what comes out

​Run it

​Targets

​What you get

Next: Build

What goes in, what you type, what comes out

Run it

Targets

What you get