# Automations & Goals

DotCraft splits "schedule the agent to do something at a certain time" and "keep one Thread moving toward a declared objective" into two complementary capabilities:

- **Automations** — Workspace-level task scheduling that runs the agent on a timer or on-demand
- **Goals** — Thread-level long-running objectives that DotCraft can continue when the Thread is idle

> Automations decide *when* to run; Goals decide *what the Thread keeps working toward*.

![DotCraft Goals](https://github.com/DotHarness/resources/raw/master/dotcraft/whats-new/goal.gif)

## Automations

DotCraft native Automations covers local tasks only. It reads task files from `.craft/tasks/` in the current workspace, runs Agents manually or on a schedule, and supports thread binding, templates, retries, activity display, and the `CompleteLocalTask` completion path.

### Create a Local Task

A local task lives under `.craft/tasks/<task-id>/`:

```text
.craft/
  tasks/
    weekly-report/
      task.md
      workflow.md
```

`task.md` describes the title, body, schedule, and thread binding. `workflow.md` describes the Agent workflow prompt.

### Common Capabilities

| Capability | Description |
|---|---|
| Manual run | Desktop Automations panel or AppServer `automation/task/run` |
| Scheduled run | Configure `schedule` in the task file |
| Thread binding | Bind a task to an existing thread so future runs submit there |
| Templates | Save reusable task templates under `.craft/automations/templates/` |
| Completion tool | Agent calls `CompleteLocalTask` with a summary |
| Delete task | Delete the task folder, optionally with the linked thread |

### Workflow Template Variables

| Variable | Description |
|---|---|
| `task.id` | Task id |
| `task.title` | Task title |
| `task.description` | `task.md` body |
| `task.thread_id` | Bound thread id |

### AppServer Methods

| Method | Description |
|---|---|
| `automation/task/list` | List local tasks |
| `automation/task/read` | Read one local task |
| `automation/task/create` | Create a local task |
| `automation/task/run` | Run a local task immediately |
| `automation/task/updateBinding` | Update or clear thread binding |
| `automation/task/delete` | Delete a local task |
| `automation/template/list` | List templates |
| `automation/template/save` | Save a user template |
| `automation/template/delete` | Delete a user template |

### Configuration Fields

| Field | Description | Default |
|---|---|---|
| `Automations.Enabled` | Enables the Automations orchestrator | `true` |
| `Automations.LocalTasksRoot` | Local task root. Empty uses `.craft/tasks/` | Empty |
| `Automations.PollingInterval` | Polling interval | `00:00:30` |
| `Automations.MaxConcurrentTasks` | Maximum concurrent local tasks | `3` |
| `Automations.TurnTimeout` | Single-turn timeout | `00:30:00` |
| `Automations.StallTimeout` | Stall timeout without response | `00:10:00` |
| `Automations.MaxRetries` | Maximum retry count | `3` |
| `Automations.RetryInitialDelay` | Initial retry delay | `00:00:30` |
| `Automations.RetryMaxDelay` | Maximum retry delay | `00:10:00` |

### `CompleteLocalTask` Tool

| Parameter | Description |
|---|---|
| `summary` | Short completion summary |

The agent calls it after finishing the work so the task can record its summary and complete.

### Directory Layout

```text
<workspace>/
  .craft/
    tasks/
      <task-id>/
        task.md
        workflow.md
    automations/
      templates/
        <template-id>/
          template.md
```

---

## Goals

Goals are long-running objectives attached to a single Thread. After a user explicitly sets a goal, DotCraft stores it in Session Core so future Turns can see it. When the Thread is idle and auto-continue is enabled, the system can keep advancing the goal until it is completed, paused, cleared, or budget-limited.

### Good Fits

- Refactors, documentation passes, migrations, or investigations that need multiple turns.
- Long-running work that users may pause, resume, replace, or clear at any time.
- Work where token usage, elapsed time, and completion state should persist with the Thread.

### Lifecycle

| Status | Meaning |
|---|---|
| `active` | The goal is in effect; idle Threads may auto-continue |
| `paused` | The goal is retained but does not auto-continue |
| `budgetLimited` | Token budget was reached; user action is required |
| `complete` | The agent audited the work and marked the goal complete |

### Common Entry Points

| Action | Entry point |
|---|---|
| Set / replace a goal | Desktop Goal control, clients with `threadGoals`, AppServer `thread/goal/set` |
| Pause / resume a goal | Desktop Goal control or AppServer `thread/goal/set` status update |
| Clear a goal | Desktop Goal control or AppServer `thread/goal/clear` |
| Read goal state | Thread lists, Thread detail, AppServer `thread/goal/get` |

### Configuration Fields

| Field | Default | Description |
|---|---|---|
| `Goals.Enabled` | `true` | Enables goal storage, AppServer methods, goal context injection, usage accounting, and model goal tools |
| `Goals.AutoContinueEnabled` | `true` | Allows active goals to continue when a Thread is idle; users can pause a goal to stop continuation |

### Goals × Automations

Automations are best for "run this task on a schedule or on demand." Goals are best for "keep this Thread moving toward one long-running objective." They can be combined: an Automation wakes up or submits a check, while the Goal preserves the Thread's long-term direction and completion state.

## Common Scenarios

| Scenario | Recommendation |
|---|---|
| Weekly / daily reports, scheduled checks | Automations on a schedule |
| Run a test suite and write the summary to a thread | Automations + `CompleteLocalTask` |
| Keep advancing a refactor or documentation pass | Goals |
| Make scheduled work follow the same long-running objective | Automations + Goals |
| Auto-lint / format after file writes | [Hooks](./security.md#hooks) `AfterToolCall` |
| Block dangerous shell commands | [Hooks](./security.md#hooks) `BeforeToolCall` |

## Troubleshooting

### Goal does not continue

Confirm `Goals.Enabled = true`, `Goals.AutoContinueEnabled = true`, the goal status is `active`, and the current Thread has no running Turn or pending user approval.

### Goal entered budgetLimited

The goal reached its token budget and auto-continuation stopped. Increase the budget, replace the goal, pause it, or ask the agent to summarize progress before setting a smaller follow-up goal.

### Client does not show Goal controls

Confirm AppServer `initialize` returns `capabilities.threadGoals = true`. If `Goals.Enabled = false`, the server does not expose `thread/goal/*` methods.

### Automation tasks not visible in Desktop

The Automations panel requires Gateway to load the Automations module. The local Dashboard works for single-workspace debugging but does not orchestrate full automation runs.

## Related

- [Project Workspace](./workspace.md) — where `.craft/tasks/` and `.craft/automations/` sit
- [Unified Session Core](./session-core.md) — how Thread / Turn / Item relate to goal state
- [Observability](./observability.md) — Trace and approvals in Dashboard
- [Security & Sandbox](./security.md#hooks) — Hooks, security guards, and sandbox isolation
- [Configuration Reference](../developing/configuration.md) for `Automations.*`, `Goals.*`, and `Hooks.*`
