Task¶

A Task CR represents one discrete unit of agent work. The operator creates Tasks by admitting a QueuedEvent from the queue. Events are enqueued by SCM webhooks (issue and PR activity), by Grafana alert webhooks (incident tasks, enqueued as alert-class events), and by the project's cron scans (mrScan and issueScan sweeps produce review and lifecycle work; brainstorm, healthCheck, and refine are project-scoped runs). incident is not cron-driven - there is no incident schedule in scm.cron; the cdScan cron is a deploy-supervision backstop that sweeps existing Deploying Tasks rather than creating new ones.

One long-lived wrapper Pod (plus a Service) is created per Task session and reused across every turn. The operator submits each turn to the existing pod; it only re-creates the pod when it is absent (first turn) or has crashed, bounded by a fixed recreation budget (3 attempts) after which the Task is failed. A Task is not one pod per turn.

apiVersion: tatara.dev/v1alpha1
kind: Task

Kind families¶

Task kinds are divided into two families based on scope. The repositoryRef field is required for repo-scoped kinds and must be empty for project-scoped kinds. The operator rejects Tasks that violate this contract at reconcile time.

Spec¶

TaskSource¶

Records the SCM work-item that originated the task. Populated automatically from the webhook payload when the operator creates the Task from a QueuedEvent.

ProposedIssueSpec¶

Carried by brainstorm tasks that propose a new issue awaiting human approval. The operator creates a tracker issue from this spec when the task completes.

SystemicGroup¶

Carried by the lead task of a systemic-improvement group. The lead opens a single PR that closes all same-repo siblings and is aware of cross-repo siblings as reference context.

Status¶

Core progress fields¶

Agent outcome structs¶

One outcome struct is populated by the agent via MCP tool at the end of each task kind. All other outcome fields are absent.

ReviewVerdict¶

PROutcome¶

IssueOutcome¶

ImplementOutcome¶

Populated when an implement agent deliberately opens no PR.

BrainstormOutcome¶

Populated when a brainstorm agent exits without filing any proposals.

ChangeSummary¶

Submitted by the implement agent via the change_summary MCP tool at the end of a run.

issueLifecycle-only status fields¶

The issueLifecycle kind operates a multi-phase state machine rather than a single-shot run. The fields below are only populated for issueLifecycle tasks; all other task kinds leave them empty.

State machine¶

stateDiagram-v2
    [*] --> Triage
    Triage --> Conversation : discuss action
    Triage --> Implement : implement action
    Triage --> Done : close action
    Conversation --> Implement : human approves / agent decides
    Conversation --> Parked : inactivity deadline
    Conversation --> Done : resolved in conversation
    Implement --> MRCI : PR opened
    Implement --> Parked : implement-empty cap hit
    MRCI --> Merge : CI passes
    MRCI --> Implement : CI fails (re-implement)
    Merge --> MainCI
    MainCI --> Deploying : main CI passes (push-CD)
    MainCI --> Done : main CI passes (no significance / legacy)
    MainCI --> Implement : regression detected
    Deploying --> Done : tatara-helmfile apply confirmed
    Deploying --> Parked : deploy budget exceeded (reroll)
    Done --> [*]
    Stopped --> [*]
    Parked --> Conversation : human re-engages
    Parked --> Implement : human re-engages after implement-empty

State and timing¶

Branch and PR tracking¶

Conversation persistence¶

Token accounting¶

These fields are written for every task kind (not just issueLifecycle); they are the status surface behind the per-task token and cost metrics.

Re-entry context¶

Loop-breaker counters¶

Three counters bound retry loops. implementEmptyRetries and writebackSkip4xxAttempts reset to zero when a PR is successfully opened; implementGiveUps accumulates across the durable lifecycle Task to bound the auto-reroll backstop.

Async communication queues¶

Deploy-supervision status (PhaseDeploying)¶

When an issueLifecycle PR auto-merges and main CI (including the release tag-cut and version propagation) goes green, the Task does not terminate at merge. It enters the pod-less Deploying phase (phase: Deploying, lifecycleState: Deploying, both non-terminal): the agent pod is torn down and the operator - not an agent - drives the push-CD cascade to a tatara-helmfile apply, then resolves the Task Done and closes the originating issue. This is the only status surface for inspecting a stalled deploy cascade, so it is worth knowing when a kubectl get task shows Deploying.

WorkItems ledger¶

status.workItems is the single source of truth for every SCM artifact this task spans: the originating issue, any PRs it opens, proposals it files, and issues it closes. The operator seeds the ledger lazily from spec.source on the first reconcile and updates it as the agent drives actions via MCP tools.

The ledger is used for dedup, stall recovery, prompt generation, and cross-repo scope determination via TaskReposInScope.

WorkItemRef¶

Termination¶

A Task is considered terminal when either of the following is true:

• status.phase is Succeeded or Failed
• status.lifecycleState is Done, Stopped, or Parked

Example¶

apiVersion: tatara.dev/v1alpha1
kind: Task
metadata:
  name: implement-issue-42
  namespace: tatara
spec:
  projectRef: my-project
  repositoryRef: my-service
  kind: implement
  goal: |
    Implement the changes described in GitHub issue #42.
    Follow the existing patterns in internal/handler/.
  source:
    provider: github
    issueRef: my-org/my-service#42
    number: 42
    title: "Add retry logic to HTTP client"

Inspecting tasks¶

# List all tasks for a project
kubectl -n tatara get task -l tatara.dev/project=my-project

# Wide view (Phase, Lifecycle, Kind, Turns columns)
kubectl -n tatara get task -l tatara.dev/project=my-project -o wide

# Describe a specific task
kubectl -n tatara describe task implement-issue-42

# Stream agent logs
kubectl -n tatara logs \
  $(kubectl -n tatara get task implement-issue-42 \
      -o jsonpath='{.status.podName}') \
  -c tatara-claude-code-wrapper -f

# Check work-item ledger
kubectl -n tatara get task implement-issue-42 \
  -o jsonpath='{.status.workItems}' | jq .