Write motions

A motion is a folder under motions/ in the tenant repository. This section is for whoever writes them: a GTM engineer, a consultant working with Claude Code, or a developer. You need to be comfortable reading TypeScript and YAML; you don’t need to know anything about how Motions runs underneath.

The parts

• Directorymotions/

  • Directoryweekly/

    • motion.yaml the steps, in order, and who decides what
    • rules.yaml values steps read, such as thresholds and ICP lists
    • Directorysteps/

      • identity.ts one file per step that runs code
      • people.ts
    • Directorylib/ code the steps share

      • …
    • Directorytests/ tests for the steps, with fixtures

      • …

• motion.yaml lists the steps and, for each, the code it runs, the sources it may call, and what it may read and propose in the CRM. It names the approvers and the question queues.
• Steps are TypeScript functions. A step gets one company and returns facts about it, or decides it’s out of the batch, or asks a person.
• rules.yaml holds the values you’ll want to tune without touching code: the minimum headcount, the list of target segments, a score threshold. Steps read them as ctx.rules.

The loop

1. Edit the motion in your editor.
2. Check it: npx motions check compiles every step and validates motion.yaml, in a second, without the network.
3. Test it: npx motions test runs your tests, with source calls answered from fixtures.
4. Push a draft: npx motions push publishes a new version without making it live.
5. Try it on a few real companies from the draft’s page, with Try on a batch.
6. Make it live, from the app or with npx motions push --live, or by merging to main if you publish from GitHub.

Where to start

Write a stepThe function, what it gets, and the four things it can return.

Ask questionsHand the unclear cases to a person, with options, evidence and a deadline.

Read and propose CRM changesRead companies, contacts and deals; propose writes for a changeset.

Use sourcesCall built-in providers, handle their errors, and keep spend under a cap.

Test a motionFixtures, runStep, and testing the cases that ask.

Work with Claude CodeHow to give an AI assistant what it needs to write motions well.