Shortcut Integration

Connect ElasticClaw to Shortcut to auto-spawn agents when stories enter a workflow state.

Shortcut workflows work identically to Linear workflows — stories replace issues, workflow states replace statuses. The [DONE] signal moves the story and terminates the agent when the PR merges.

How it works

When a Shortcut story moves into a configured workflow state, the workflow engine creates an agent pre-loaded with the story title, description, and URL in CONTEXT.md. The agent reads it, implements the task, opens a PR, and sends [DONE] https://github.com/org/repo/pull/N. ElasticClaw Server moves the story and keeps the agent alive to watch for CI failures and review comments. When the PR merges, the agent terminates automatically.

1. Get a Shortcut API token

  1. Go to Shortcut → Settings → API Tokens
  2. Click Generate Token, name it elasticclaw
  3. Copy the token

2. Register the webhook

Shortcut supports programmatic webhook registration. Register the ElasticClaw webhook using your API token:

bash
curl -X POST https://api.app.shortcut.com/api/v3/webhooks \
  -H "Shortcut-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://server.example.com/api/workspaces/shortcut-workspace/webhooks/shortcut",
    "description": "ElasticClaw workflow",
    "story_update": true
  }'

You can also find the webhook URL in the workspace issue tracker settings in the server web UI.

3. Add the issue tracker

text
Settings -> Workspaces -> shortcut-workspace -> Issue Trackers
Add Shortcut:
  workspace: my-company
  token: ${SHORTCUT_TOKEN}

4. Configure workflow.yaml

yaml
# .elasticclaw/workflows/shortcut-workflow.yaml
schema_version: v1
name: shortcut-workflow

trigger:
  shortcut:
    event: status_changed
    workspace: my-company
    states:
      - "In Development"
    labels:
      - agent-ready
    exclude_labels:
      - blocked

working_status: "In Progress"

stages:
  - id: working
    label: Working
    entry: true
    on_enter:
      inject: |
        Read CONTEXT.md and start working.

  - id: pr_opened
    label: PR Opened
    triggers:
      - message_contains: "[DONE]"
    on_enter:
      move_issue: "In Review"

  - id: merged
    label: Merged
    triggers:
      - pr_merged: {}
    on_enter:
      move_issue: Done
    terminal: true
Publish the workspace with elasticclaw workspace push shortcut-workspace, then publish this file with elasticclaw workflow push --workspace shortcut-workspace .elasticclaw/workflows/shortcut-workflow.yaml.

5. Add to your workspace

Tell your agent to signal done when finished:

markdown
When your task is complete, open a PR and send:
[DONE] https://github.com/org/repo/pull/N

This moves the Shortcut story and keeps you alive to watch for CI and review comments.
You'll be terminated automatically when the PR merges.

Label filters

Shortcut workflow triggers use trigger.shortcut.labels and trigger.shortcut.exclude_labels. All configured required labels must be present, and no configured excluded labels may be present. In the workflow above, agent-ready is required and blocked prevents automatic agent creation.

Template variables

Shortcut story context is written to CONTEXT.md when the agent starts. Automatic Shortcut workflow stages do not currently expose a Go template object such as {{.Issue.Title}} instages[].on_enter.inject.

Use CONTEXT.md for the story ID, title, URL, and description. Manual workflow triggers can still render {{.Inputs.name}} values from configured inputs.

Differences from Linear

  • No HMAC signing — Shortcut doesn't provide webhook signatures
  • Story IDs are stored as sc-<id> internally
  • Workflow state names are resolved via the Shortcut API on each event
  • No team filter (Shortcut uses project-level scoping instead)