> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fortressproductivity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent work loop

> The session pattern agents should follow in Fortress.

An agent session should start by reading state, then act through explicit tools. Fortress is designed so an agent can recover context across sessions without relying on memory from a previous chat.

## Start every session

<Steps>
  <Step title="Read the workspace overview">
    Fetch `fortress://workspace/overview`. This gives the agent metrics, its assigned work, claimable work, open questions, active orders, and recent activity.
  </Step>

  <Step title="Read active orders">
    Fetch `fortress://orders`, then read `fortress://order/<id>` for any instruction document needed this run.
  </Step>

  <Step title="Inspect the queue">
    Call `get_work_queue` for a limited list of ready actions already assigned to the agent. To discover claimable work the agent does not yet own, read `fortress://workspace/overview` or `fortress://view/ready`. Read `fortress://action/<id>` for the full context bundle before doing real work.
  </Step>

  <Step title="Execute">
    Do the work outside Fortress as needed, heartbeat during long runs, and attach links or documents that preserve output context.
  </Step>

  <Step title="Finish cleanly">
    Call `complete_action` with a result summary, `drop_action` with a reason, or `ask_question` when the next move needs human judgment.
  </Step>
</Steps>

## Heartbeats

Heartbeats keep the human's **Working** view accurate. They record a timestamped progress note and bump `last_activity_at`.

Call `heartbeat` every few minutes during long-running work. A heartbeat is not a lock and does not reserve the task. Assignment already carries ownership.

## Completion

Use `complete_action` only when the promised result exists. Include a concise `result_summary` and any links to output, PRs, files, or deployed URLs.

Completed agent work normally goes to human review.

### Completing pool work

An agent can `complete_action` on a ready task it does not own as long as its capabilities match the task's requirements. The completion records the agent as the actor that finished the work, so review surfaces show who actually did it instead of leaving the task unowned.

Use this when the agent picked up claimable work directly from `fortress://workspace/overview` or `fortress://view/ready` and finished it in the same session. Tasks already assigned to a different actor cannot be completed from the pool path; the agent must reassign first or skip the task.

## Dropping work

Use `drop_action` when the work should not happen. Agents — both MCP and direct API callers — must include a `reason` that explains the decision to the human. Humans dropping work from the inbox or task views can omit a reason; the requirement only applies to agent callers.

Do not mark work complete when the real outcome is "this is no longer needed."

## Creating follow-up work

Project-manager agents can use `create_action` for follow-ups.

| `status` | Meaning                                                                                                                               |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `ready`  | Actionable work. Defaults to assigned to the calling agent unless `assigned_actor_id` is explicitly set to another actor or the pool. |
| `inbox`  | A finding or recommendation for the human to triage. Assigned to the workspace owner's user actor by default.                         |

Use `source_key` when the follow-up comes from a stable external object so duplicates collapse to the original task.

## Failure handling

Terminal writes are first-writer-wins. If another actor already completed or dropped a task, the agent receives a conflict such as `already_terminal`. The correct response is to refetch the action and move on, not retry blindly.