Linear templates

Use a built-in format for each brief type, or copy one into a named custom template. Templates format a brief and choose its Linear destination. They do not generate a brief, change recommendation readiness or update an existing Linear issue.

The dashboard, MCP, Developer API and CLI use the same saved revisions and defaults. Connect Linear once for the account before saving a template. Your agent needs a credential with access to the ShipFoundry project and linear:read; writes also need linear:write and an owner or admin account role. The agent never needs Linear's OAuth token.

Template CLI commands require version 0.2.0 or newer. Version 0.2.0 is prepared for publication; the currently published 0.1.0 package does not include these commands. The API and MCP controls ship with the corresponding application release.

Operations

API paths below are relative to /api/v1. Read operations have no confirmation requirement. All writes require confirmed: true through MCP/API, or --yes through the CLI. Use one idempotency key for the same write across retries and transports.

Prefix CLI commands with shipfoundry; add --json for structured output. Set the base URL and credential as described in the CLI guide. API requests use the bearer credential and X-Idempotency-Key header described in the API guide. MCP write tools accept idempotencyKey. CLI writes accept --idempotency-key.

Agent setup procedure

1. List templates and destination options with the ShipFoundry projectId.
2. Choose a built-in preset matching the brief type. Copy its titleTemplate and bodyTemplate into a draft, give the draft a name, and choose its destination IDs from the options response.
3. Preview the unsaved draft against a real recommendation using matchId. Check the rendered title, body and emptyVariables. Draft preview checks formatting and brief identity/type. It does not validate the destination against live Linear metadata or guarantee export readiness.
4. Save the draft. Saving validates the destination and appends a revision. Select its returned id as the default only when that is intended.
5. Preview the saved export payload. Export only after approval, then keep the returned Linear issue identity. An already-exported brief normally reuses its existing issue.

The list response contains:

To show one library entry per custom template, take its greatest version, omit isBuiltIn, and separate active from isArchived. Older rows are history, not separate templates. A default pins a specific revision's content. The named template's latest archive state controls whether that pinned revision is usable.

Save and preview input

This file creates a new custom template. Replace placeholder IDs with the IDs returned by the server. For MCP/API saving, add confirmed: true; the CLI adds it after --yes.

{
  "projectId": "SHIPFOUNDRY_PROJECT_UUID",
  "expectedVersion": 0,
  "name": "Team handoff",
  "titleTemplate": "{{title}}",
  "bodyTemplate": "{{brief}}\n\n## Report back\n{{outcomeInstructions}}",
  "outputKind": "engineering_handoff",
  "destination": {
    "teamId": "LINEAR_TEAM_UUID",
    "projectId": null,
    "stateId": null,
    "labelIds": []
  }
}

For draft preview, use the same file and add matchId, the ShipFoundry recommendation UUID. Do not add confirmed. Preview writes no template revision and creates no Linear issue.

Destination options include teams, projects with teamIds, states with teamId, and labels with teamId, isGroup and parent. A label name such as area:briefs is ordinary text unless parent identifies a real group. Independent labels can be combined.

Brief types and built-in defaults

Each preset also includes context, why the work matters, packet information, risks, non-goals, reporting instructions and references. The generic built-in fallback is {{title}} and {{brief}}. Read presets for the exact current text instead of reproducing it in an agent prompt.

Default precedence is: explicitly requested revision, matching brief-type default, compatible generic fallback, then built-in format. Selecting one type preserves other type defaults. Saving or loading history does not select a default.

Select, archive, restore and revert

Select a saved revision with:

{
  "projectId": "SHIPFOUNDRY_PROJECT_UUID",
  "revisionId": "SAVED_REVISION_UUID",
  "confirmed": true
}

Archive or restore a named template with the latest version from the list response:

{
  "action": "archive",
  "projectId": "SHIPFOUNDRY_PROJECT_UUID",
  "templateId": "NAMED_TEMPLATE_UUID",
  "expectedVersion": 3,
  "confirmed": true
}

For restore, change action to restore and reload the latest version first. Both actions append history. There is no permanent-delete endpoint. An archived default uses the built-in format with its pinned destination; restoring makes its pinned custom content available again. Explicit selection or export of an archived template is rejected.

To revert content, copy the earlier revision's name, title/body, type and destination into a save request. Keep its templateId but use the latest expectedVersion. The returned row is a new revision. Select its id if it should become active. Existing revisions and Linear issues remain unchanged.

To reset one type to built-in, use the existing pinned destination or a destination chosen from options:

{
  "action": "reset_default",
  "projectId": "SHIPFOUNDRY_PROJECT_UUID",
  "outputKind": "engineering_spike",
  "destination": {
    "teamId": "LINEAR_TEAM_UUID",
    "projectId": null,
    "stateId": null,
    "labelIds": []
  },
  "confirmed": true
}

Use outputKind: null for the generic fallback. Reset creates and selects an immutable built-in revision in one transaction. Built-in revisions cannot be edited; copy a preset to create a custom template instead.

Placeholder reference

Use {{brief}} for the full handoff, or individual sections for your own layout. Substitution does not remove repeated sections automatically. includedInBrief identifies direct sections already included by the complete handoff. Packet subfields can also duplicate parts of {{taskPacket}}.

The field guide shows 13 common fields initially. Advanced exposes all 39; search includes advanced fields. Optional missing values render as empty strings, and preview reports explicitly referenced empty values. {{taskPacket}} explicitly explains when no executable packet exists. Helpers, conditionals, nested expressions and unknown variables are rejected. Braces in brief or repository content remain literal.