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

# Capability spec

> The declarative definition of a capability — what must be true, within what boundaries, and how success will be proven.

The capability spec is the declarative definition of a capability. It describes what organizational ability should exist, what outcome it must deliver, and the boundaries within which it may operate.

It is analogous to source code, or to an infrastructure configuration file: it says what must be true without prescribing every runtime decision.

```text theme={null}
What should exist?
What should it accomplish?
Within what boundaries?
How will success be proven?
```

## What the spec contains

<AccordionGroup>
  <Accordion title="Purpose">
    * The Job to be fulfilled
    * The desired organizational outcome
    * Beneficiaries
    * Business value
  </Accordion>

  <Accordion title="Interface">
    * Triggers
    * Required inputs
    * Expected outputs
    * Preconditions
    * Completion conditions
  </Accordion>

  <Accordion title="Operating boundaries">
    * Policies
    * Constraints
    * Out-of-scope behavior
    * Allowed systems
    * Prohibited actions
    * Escalation conditions
  </Accordion>

  <Accordion title="Participants">
    * Capability owner
    * Human roles
    * AI roles
    * Reviewers
    * Approvers
    * Stakeholders
  </Accordion>

  <Accordion title="Resources">
    * Skills
    * Tools
    * Integrations
    * Credentials required
    * Knowledge sources
    * Memory access
  </Accordion>

  <Accordion title="Trust contract">
    * Success criteria
    * Acceptance criteria
    * Evidence requirements
    * Risk classification
    * Review requirements
  </Accordion>
</AccordionGroup>

The trust contract is the part that distinguishes a capability spec from a prompt. It states in advance what would count as proof that the capability worked.

## The spec is versioned

A capability may have many spec versions, but only approved versions may be instantiated and promoted. Each version is a distinct, reviewable artifact — which is what makes "what did we intend, and when did that change?" an answerable question.

## Spec and recipe are different

This distinction is load-bearing.

|                     | Answers                   | Analogy        |
| ------------------- | ------------------------- | -------------- |
| **Capability spec** | What must be true?        | The contract   |
| **Runtime recipe**  | How will we make it true? | The route plan |

The spec defines the desired organizational ability. The recipe defines the approved way of delivering it. Changing how the work gets done does not change what the capability is for.

## In the product today

You author a capability spec by talking to Joyvis in `jstm agent plan`, or in the web builder. The conversation produces a structured spec; committing it with `jstm agent plan done` is what turns the draft into a real agent definition.

`jstm agent spec <agent-id>` exports the committed definition, and `jstm agent view <agent-id> --definition` shows it inline.

## Next

<Columns cols={2}>
  <Card title="Agents and recipes" href="/concepts/agents-and-recipes" icon="bot">
    The governed intelligent realization of a spec.
  </Card>

  <Card title="Draft an agent" href="/guides/draft-an-agent" icon="message-circle">
    Author a spec in conversation.
  </Card>
</Columns>