---
name: clockwork
description: >-
  Use when coordinating multi-step work in Clockwork — creating or launching
  workflows, adding tasks and dependencies, assigning executors (human / AI /
  vendor), completing or delaying tasks, and querying a workflow's schedule,
  critical path, or conflicts. Drives the `clockwork` MCP server tools.
---

# Clockwork — coordination backend

Clockwork owns **workflow state**: the dependency graph, CPM scheduling, deadlines,
approval gates, and handoffs between executors. You bring the intelligence (deciding
*what* to do); Clockwork tracks *when* things can happen and *who* owns them, and
re-computes the critical path and conflicts after every change.

Reach for this skill whenever the user wants to plan, run, or adjust real work as a
tracked, dependency-aware workflow rather than a flat to-do list.

## Model & conventions

- **Workflow** = a running instance of a task graph (a "template instance"). Every task
  belongs to one workflow.
- **Executor** = whoever a task is assigned to — a human, an AI agent, or a vendor —
  identified by a `platformUserId`. Reassigning is a first-class operation.
- **Durations** are in **minutes**. **Timestamps** are **ISO 8601** (e.g.
  `2026-06-23T15:00:00Z`).
- **Dependencies** order tasks. Default type is `finish_to_start` (successor can start
  once the predecessor finishes); `start_to_start`, `finish_to_finish`, and
  `start_to_finish` are also available, with optional `lagMinutes`.
- IDs flow from creation responses — capture the `id` a create call returns and feed it
  into the next call (e.g. a new task's id into `create_dependency`).

## Prerequisite

This skill calls Clockwork **through the `clockwork` MCP server**, not raw HTTP. There
are two equivalent ways to connect — pick whichever your client supports.

**Hosted (recommended)** — query the server over HTTP; nothing to install. Point your
client at the hosted endpoint and send your API key as a Bearer token:

```json
{
  "mcpServers": {
    "clockwork": {
      "url": "https://mcp.clockwork-co.com/mcp",
      "headers": { "Authorization": "Bearer ck_live_…" }
    }
  }
}
```

**Local (stdio)** — run the server as a subprocess via `npx`:

```json
{
  "mcpServers": {
    "clockwork": {
      "command": "npx",
      "args": ["-y", "@clockwork/mcp"],
      "env": {
        "CLOCKWORK_API_KEY": "ck_live_…",
        "CLOCKWORK_API_URL": "https://platform.clockwork-co.com"
      }
    }
  }
}
```

Both expose the exact same tools. Mint the API key in the Clockwork app under
**Settings → API Keys** (it is shown once). Keep it only in this config — never paste it
into chat or commit it.

If the `clockwork` tools are not present in the current session, say so plainly and point
the user at the config above rather than guessing or falling back to unverified calls.

## Tool catalog

All tools are exposed by the `clockwork` MCP server.

| Tool | Purpose | Key inputs |
|---|---|---|
| `create_workflow` | Start a new execution graph. Pass `templateId` to seed it from a template. | `name`; optional `anchorDate`, `templateId` |
| `instantiate_template` | Launch a fully-scheduled workflow from a published template. | `templateId`; optional `name`, `anchorDate` |
| `create_task` | Add a task to a workflow and assign an executor. | `name`, `durationMinutes`, `earliestStart`, `assigneePlatformUserId`; optional `templateInstanceId`, `deadline` |
| `create_dependency` | Order two tasks. | `fromTaskId`, `toTaskId`; optional `type`, `lagMinutes` |
| `assign_task` | Move a task to a different executor. | `taskId`, `assigneePlatformUserId` |
| `complete_task` | Mark a task done; dependents reschedule automatically. | `taskId` |
| `delay_task` | Slip a task; the delay propagates to all dependents. | `taskId`; optional `delayMinutes` or `newEarliestStart`, `reason` |
| `query_schedule` | Read a workflow's tasks, CPM slack / critical path, and conflicts. | `workflowId` |
| `delete_workflow` | Delete a workflow and all its tasks/dependencies/conflicts. Irreversible. | `workflowId` |
| `update_workflow` | Rename a workflow or change its status / tags. | `workflowId`; optional `name`, `status`, `tags` |
| `list_workflows` | List the caller's workflows. | — |
| `get_task` | Read a single task, including its computed schedule fields. | `taskId` |
| `update_task` | Edit a task's fields (name, duration, status, dates, buffer, priority). | `taskId`; any editable fields |
| `delete_task` | Delete a task; dependents reschedule. Irreversible. | `taskId` |
| `list_tasks` | List tasks, optionally filtered. | optional `workflowId`, `status` (`pending`/`active`/`done`/`blocked`) |
| `list_templates` | List templates available to the caller (owned + public). | — |
| `list_conflicts` | List scheduling conflicts the engine has detected. | — |
| `resolve_conflict` | Mark a conflict resolved. | `conflictId` |
| `snooze_conflict` | Snooze a conflict until a given time. | `conflictId`, `until` (ISO 8601) |
| `list_opportunities` | List scheduling opportunities the engine surfaced. | — |
| `dismiss_opportunity` | Dismiss an opportunity. | `opportunityId` |

## Recipes

**Stand up a workflow from scratch**
1. `create_workflow` → keep the returned workflow id.
2. `create_task` once per step (set `templateInstanceId` to the workflow id, give each a
   `durationMinutes`, `earliestStart`, and `assigneePlatformUserId`) → keep each task id.
3. `create_dependency` to wire predecessors → successors.
4. `query_schedule` to show the computed start/finish times, critical path, and any conflicts.

**Launch from a template**
1. `list_templates` to find the right `templateId`.
2. `instantiate_template` with that id (and an `anchorDate` if the schedule should hang off
   a specific date).
3. `query_schedule` on the new workflow to confirm the plan.

**Handle a slip**
1. `delay_task` with `delayMinutes` (or a concrete `newEarliestStart`) and a `reason`.
2. `query_schedule` to read how the slip propagated — which downstream tasks moved, whether
   any deadline is now violated or a resource is double-booked.

**Re-route work**
- `assign_task` to hand a task to a different executor (e.g. human → AI agent). Follow with
  `query_schedule` if the reassignment could change travel-time or availability conflicts.

## Operating tips

- After **any** mutation, call `query_schedule` — Clockwork re-runs the CPM engine on every
  change, so that's how you see the real, recomputed plan (slack, critical path, conflicts)
  rather than assuming the local effect.
- Prefer `list_*` tools to discover real ids before mutating; don't invent UUIDs.
- Conflicts surfaced by `query_schedule` (deadline violations, resource contention,
  travel-time issues) are the signal to act — flag them to the user and propose a fix
  (delay, reassign, or re-order) instead of silently proceeding.
- Webhooks (`task_ready`, `task_completed`, `task_delayed`, `conflict_detected`,
  `workflow_completed`) are available for push updates if the user wants event-driven flows.