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

# Build your Motion

> Draft a complete Motion with AI from your existing process docs, decks, Notion pages, and notes — everything lands as a draft you review and publish.

You almost certainly already have the program — in an onboarding runbook, a process doc, a Notion page, a deck, or your own head. **Build your Motion** turns that source material plus a short prompt into a complete draft Motion: stages with timelines, milestones tagged by how they can be verified, and working agents wired into each stage.

The output is always a **draft**. Nothing runs on any account until an admin reviews it, publishes it, and assigns accounts to it.

## Start a build

From **Motions**, click **Build your Motion**. (The **New motion** button next to it starts a blank Motion in the editor instead — use that when you'd rather compose by hand.)

<Steps>
  <Step title="Choose a mode">
    **Build from scratch** creates a new Motion. **Improve an existing Motion** starts from one of your published Motions and reworks it against your prompt and sources.
  </Step>

  <Step title="Add source material">
    Attach anything that describes the program: brand guidelines, sales decks, meeting notes, product specs, process docs, screenshots, Notion pages, and links. You can upload files (PDF, Word, Excel, slides, text, Markdown, CSV, and images), paste a URL, add a Notion page, or paste free-form notes. Remove any source before building.
  </Step>

  <Step title="Write the prompt">
    Tell the builder what the Motion should accomplish — who it's for, what it should know, and what outcome you want. Optionally set a name, a tone, a complexity level, and a target audience.
  </Step>

  <Step title="Build">
    **Build Motion** is enabled once you have a prompt or at least one source. The build runs server-side with a live progress view — it's safe to leave the page and come back. If a build fails, you can retry it or start over.
  </Step>
</Steps>

When the build completes, you land in the Motion editor on the new draft.

## What the builder generates

**Stages with real timelines.** The builder mirrors the structure of your source material — its phases become stages, in order, with an ideal day range per stage extracted from the source rather than a placeholder.

**Milestones tagged by verifiability.** Each stage's gates keep your source's wording, and each one is tagged by whether Thread can verify it automatically:

* **Auto** — verifiable from account context, your connected integrations, Slack, the portal, or logged milestones.
* **Manual** — needs data from a system Thread isn't connected to (for example, in-product usage metrics). The editor shows a manual badge on these so a reviewer can see at a glance which gates a human will confirm.

**One to three agents per stage.** For every stage where deliverable work makes sense, the builder creates purpose-built agents — a welcome-email drafter here, a kickoff coordinator there, a health watcher in adoption — each with a runbook-style goal, an expected outcome, testable success criteria, and the integrations it uses, grounded in your source material. Renewal and advocacy stages get covered too, not just onboarding.

**Honest integration stubs.** If a generated agent wants a tool from an integration your org hasn't connected, the agent keeps a visible "Connect X to enable" note rather than silently dropping the capability — so the draft doubles as a list of what to connect.

## Everything lands as a draft

The build's safety posture is uniform:

* The Motion is created as a **draft** — never auto-published.
* Generated agents are **motion-scoped**: they belong to this draft and don't appear in the [Agent Templates catalog](/motions/agents) unless you later publish or promote them.
* Generated agents default to proposing their actions for human approval.
* Nothing touches an account until an admin **publishes** the Motion and **assigns** accounts to it.

## Review before you publish

Treat the draft as a strong first pass, not a finished program:

<AccordionGroup>
  <Accordion title="Walk the stages">
    Check the stage order, names, and timelines against how you actually run the program. Add or merge stages freely — it's a normal draft in the normal editor.
  </Accordion>

  <Accordion title="Tighten the milestones">
    Confirm which milestones are flagged **Required to advance** — the builder proposes gates, but you own the definition of stage-done. Switch any mis-tagged milestone between Agent and Manual. See [Milestones and verification](/motions/milestones-and-verification).
  </Accordion>

  <Accordion title="Open each generated agent">
    Read the goal and instructions, check the tools it was granted, connect any stubbed integrations, and set the per-action approvals you're comfortable with. [Rehearse](/motions/email-plays#rehearse-before-you-rely-on-it) email-sending plays against a real account before going live.
  </Accordion>
</AccordionGroup>

When it reads right, publish. Accounts you assign are pinned to this version — and the next time your process changes, run **Improve an existing Motion** and publish the result as the next version without disturbing anything in flight.