# Task Schema

> Tasks are JSON objects with this shape:

Source: https://bifrost5.com/foundry/docs/task-schema/

# Task Schema

Information

Describe an idea in plain words and get back a checked, ready-to-run task list from the Production-Grade planning companion.

[See editions](/foundry/docs/editions)

Tasks are JSON objects with this shape:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `task_id` | string | Yes | Unique identifier |
| `project_id` | string | Yes | Sandbox directory name under `sandbox/` |
| `intent` | string | Yes | Brief description |
| `tool` | string | No | `cursor` \| `gemini` \| `copilot` \| `codex` \| `claude` \| `ollama`. Acts as provider override; strategy decides if omitted. |
| `instructions` | string | Yes | Detailed instructions for the agent |
| `acceptance_criteria` | string[] | Yes | All must be met for completion |
| `retry_policy` | object | No | `max_retries`, `backoff_strategy` (linear \| exponential) |
| `status` | string | No | `pending` \| `in_progress` \| `completed` \| `blocked` |
| `working_directory` | string | No | Relative to sandbox root |
| `agent_mode` | string | No | e.g. `opus-4.5`, `auto` |
| `affects_files` | string[] | Yes (parallel) | Files this task modifies; used for file locking |
| `depends_on` | string[] | No | Task IDs that must complete first: auto-promoted when deps met |
| `test_command` | string | No | Command to run for validation |
| `tests_required` | boolean | No | Whether tests must pass |

## Example Task File

```
[
  {
    "task_id": "frontend-001",
    "intent": "Extend existing React component",
    "tool": "gemini",
    "instructions": "Extend the existing App.tsx component to add user authentication.",
    "acceptance_criteria": [
      "App.tsx includes authentication logic",
      "Uses existing React Router setup"
    ],
    "retry_policy": { "max_retries": 2 },
    "status": "pending"
  }
]
```

## Task Lifecycle

**Pending** → **In progress** → **Completed** (validation passed) or **Blocked** (failed after max retries).