Project¶

The Project custom resource is the top-level grouping unit in tatara. One Project maps to a single SCM owner (a GitHub organization, a GitLab group, or a personal account), owns the per-project memory stack, and drives all scheduled activity: issue scans, MR reviews, brainstorm cycles, and incident handling.

Every Repository CR must reference a Project. Every Task, QueuedEvent, Issue, and MergeRequest is born inside a Project.

API group / version: tatara.dev/v1alpha1 Kind: Project Scope: Namespaced

Spec¶

Top-level fields¶

The per-stage deadlines that used to live here as deployBudgetSeconds / deploySingleHopBudgetSeconds are gone: every stage's exit deadline is a fixed budget measured from status.stageEnteredAt (or podStartedAt, or stageWorkStartedAt for a live pod stage), not a Project-configurable field. See the one clock, one table model on the Task stage machine.

AgentSpec¶

Controls every agent pod spawned by this project.

LifecycleHooks¶

Each field is a shell command string passed to sh -c. An empty field is skipped. Hook failures are logged and counted as metrics but never abort the agent session.

MCPServerSpec¶

One entry per additional MCP server to make available to this project's agent pods, alongside the platform-owned servers (tatara, grafana when enabled, serena) and any overlay-dir fragments baked into the image.

MemorySpec¶

Governs the per-project memory stack: a CNPG-managed Postgres cluster (LightRAG backing store) and a Neo4j single-node instance (graph traversal).

WorkspaceSpec¶

Persistent volumes for the agent pod, replacing the container's writable layer - which is volatile (destroyed with the pod) and unbounded (no guarantee a node has room for every repo a project clones and builds). Not a speed feature by itself: a resumed repo costs more than a fresh shallow clone (~5s vs ~2s). The win is the separate build-cache volume - a cold go build vs. a warm one is a 5-6x difference.

Two PVCs, two lifecycles: the per-Task workspace PVC is owned by the Task and deleted only on a terminal outcome, never on a park (a parked Task can resume, and destroying its workspace would defeat the point). The per-project cache PVC is owned by the Project and provisioned once, independent of any single Task.

A fresh CephFS subvolume is root:root 0755 and the agent runs as a non-root uid - AgentFsGroup plus AgentFsGroupChangePolicy: OnRootMismatch on the operator's own deployment config (not a per-Project field) fix ownership without a full recursive chown on every mount, which would make the cache a net loss on a large tree.

The agent pod is not created until every PVC it mounts is Bound - an unprovisionable volume costs zero pods (bounded at a 10-minute timeout, then the Task parks at operator-error) rather than respawning indefinitely.

A review-stage pod for an implement Task inherits the same workspace (sequential stages of one Task, one pod name - never concurrent writers, so this is not a sharing hazard by itself). It is a review hazard instead: any edit a review agent makes there is committed and pushed at turn end into the very MR it is judging, attributed as if the implementer wrote it. The review agent is told this explicitly when the project has the workspace enabled.

GrafanaSpec¶

Enables an operator-provisioned grafana-mcp sidecar and an alert-webhook receiver for incident-response tasks. The feature is entirely inert when enabled: false.

DocumentationSpec¶

The real on/off switch for the nightly documentation agent, and its docs-target repo. scm.cron.documentation.schedule (below) is a separate, required gate - both must be set for the cron to actually fire.

UpgradePolicySpec¶

The policy the upgrade agent is handed at turn 0. The operator does not act on it - it renders it verbatim into the assignment. Every decision it describes (which candidate is eligible, how far a hop may jump) is the agent's, made against release notes the operator itself never reads. Nil disables nothing by itself - the real on/off switch is scm.cron.upgrade.schedule, below - but engine defaults to none, so an unset block behaves as if there were no dependency manifests to scan.

Adoption is inert until both adoptBranchPrefix is set and the engine actually authors matching merge requests as botLogin or an upgradeEngineLogins entry - a branch-prefix match from a human author is never adopted.

ReleaseAgeSpec¶

See Upgrade for the full agent behavior this policy drives.

QueueSpec¶

Fine-grained control over the in-operator admission queue. Omit this section entirely if the defaults derived from maxConcurrentAgents are sufficient.

TokenBudgetSpec¶

Configures the per-Project token-budget admission gate: pauses proactive work (brainstorm, implement, review, ...) at proactivePercent and incident work (the alert pool) at emergencyPercent of the measured usage window. Off by default at every level: the operator-wide default Config is the zero value (enabled: false), and a Project inherits that default verbatim unless it sets its own tokenBudget block - the presence of the block, not any single field, is what turns the gate on for that Project.

ScmSpec¶

Binds the project to an SCM provider and configures the full set of operational knobs: bot identity, the approval grammar, labels, and cron schedules.

Identity¶

Approval gates¶

Merge and review policy¶

Merging itself has no policy field to set: it is always an operator action, triggered only by an accepted submit_outcome(verdict=approve) from a review pod, and no tatara-opened PR ever carries an auto-merge setting. See Merge and deploy for the full sequence.

Operational tuning¶

Per-stage stall detection is no longer a Project-configurable minute count. Every stage runs a fixed budget from status.stageEnteredAt / status.podStartedAt / status.stageWorkStartedAt - see the Task stage machine for the full table.

Board integration¶

Configure board to enable project-board synchronization.

Cron schedules¶

All cron fields use standard 5-field cron syntax (minute hour dom month dow). An empty schedule disables that activity.

scm.cron.issueScan¶

scm.cron.brainstorm¶

Opt-in self-driven issue-proposal cycle. Disabled unless enabled: true.

!!! note "scm.cron.healthCheck retired" The retired origin kind's own cron block (scm.cron.healthCheck) is dropped along with it; there is no independent health-check schedule any more. maxOpenProposals and the BrainstormActivity/HealthCheckActivity shapes it is declared on both remain live in the API - only the cron trigger and the origin kind are gone.

scm.cron.documentation¶

Schedule-driven. One nightly batch Task per project, covering everything delivered in the last 24 hours - not a per-delivery spawn, and not a "did anything meaningful change?" judgment call. This CronActivity has no enabled field of its own; the real on-switch is the top-level spec.documentation block (enabled + repo). Both spec.documentation.enabled and a non-empty schedule here are required for the cron to fire.

scm.cron.refine¶

Pre-step that fires automatically before each scan and brainstorm cycle. No independent schedule; it is a mandatory barrier, not a standalone cron.

scm.cron.upgrade¶

The dependency-upgrade cron. Default off (empty schedule) for every project: enabling it lets an agent open merge requests that change deployed versions, so it is opt-in per project in the enrollment values, alongside upgradePolicy.

Each due tick mints at most one upgrade Task, and only while open upgrade lanes sit below maxOpenUpgrades. Throughput is therefore the cron frequency, not a fan-out: 58 */4 * * * yields up to six Tasks a day, each taking exactly one dependency-upgrade unit. Minting several Tasks per fire was rejected - each would self-scan and race for the same top candidate, and there is no agent-side task-minting tool left to partition the work with.

Label set¶

The operator projects a set of SCM labels onto issues to communicate the platform's decision state. Every label here is a write-only projection: the operator writes it when the underlying Issue.status.status (or the parked/reaped state) changes, and no label is ever read to derive that status - the sole exception is the internal tatara-parked marker, which is read to decide re-mint cost, never authority (see Ownership, GC, and admission).

!!! note "Removed: approvalLabel, ideaLabel, rejectedLabel" These three fields are removed from the CRD outright - they configured the old label-applies-approval trigger, and approval is comment-text-only now (see Approval gates).

Status¶

The operator writes observed state back to .status. All fields are read-only.

Top-level status fields¶

Last-run timestamps¶

All timestamps are RFC 3339 and reflect the last time the corresponding activity completed successfully.

TokenBudgetStatus¶

The claudeSubscription gate's live snapshot state is not per-Project any more - the subscription is one account shared by every Project, so a per-Project field would go stale for any Project that falls quiet while its neighbours burn the same shared windows. The wrapper's newest snapshot lands on Task.status.accountUsage instead (see Task reference), and a leader-only reconciler folds the newest one across every Task into a fleet-wide in-process store the gate actually reads. There is no CRD-visible field for that fleet-wide value; read tatara_account_usage_gate_ready and tatara_account_usage_snapshot_age_seconds instead.

Annotated example¶

apiVersion: tatara.dev/v1alpha1
kind: Project
metadata:
  name: my-platform
  namespace: tatara
spec:
  # (1)!
  scmSecretRef: my-platform-scm-token
  triggerLabel: tatara
  maxConcurrentAgents: 5
  # (10)!
  agentPodTTLSeconds: 3600
  maxNewTasksPerSweep: 5
  maxOpenTasks: 6
  maxBundleBytes: 400000

  agent:
    # (2)!
    model: claude-opus-4-8
    permissionMode: bypassPermissions
    turnTimeoutSeconds: 1800
    effort: high
    # (11)!
    maxTurnsPerPod: 40
    maxTurnsPerTask: 300
    maxReviewRounds: 3
    maxPodRecreations: 3
    modelByKind:
      documentation: claude-sonnet-5
      refine: claude-sonnet-5
    effortByKind:
      documentation: low
      refine: medium
    skillsRef: v1.5.2
    hooks:
      # (3)!
      postClone: "mise install --quiet"
      conversationFinished: |
        echo "Task ${TATARA_TASK} finished in project ${TATARA_PROJECT}"
    extraEnvs:
      - name: CUSTOM_REGISTRY
        value: harbor.example.com
    # (15)!
    mcpServers:
      - name: internal-search
        url: http://internal-search.svc.cluster.local:8080/mcp
        type: http

  memory:
    # (4)!
    pgInstances: 3
    pgStorage: 20Gi
    neo4jStorage: 20Gi

  grafana:
    # (5)!
    enabled: true
    url: https://grafana.example.com
    secretRef: grafana-tatara-credentials

  # (14)!
  documentation:
    enabled: true
    repo: https://github.com/my-org/my-docs

  queue:
    # (6)!
    capacity: 5
    alertCapacity: 2

  # (12)!
  tokenBudget:
    enabled: true
    mode: customWindow
    proactivePercent: 50
    emergencyPercent: 80
    resetSchedule: "0 0 * * *"
    windowDuration: "24h"
    tokenLimit: 50000000

  scm:
    provider: github
    owner: my-org
    # (7)!
    botLogin: my-org-bot
    botEmail: my-org-bot@users.noreply.github.com
    # (8)!
    maintainerLogins:
      - alice
      - bob
    reporterLogins:
      - alice
      - bob
      - charlie
    prReactionScope: labeledOrMentioned
    guidance: |
      This project runs the platform team's infrastructure repos.
      Prefer Kubernetes-native approaches. Avoid new external dependencies.

    board:
      githubProjectNumber: 42
      statusField: Status

    cron:
      issueScan:
        # (9)!
        schedule: "0 * * * *"
        maxPerRepo: 1
      brainstorm:
        enabled: true
        schedule: "0 9 * * 1"
        targetOpenProposals: 3
        historyWindow: 20
        # (13)!
        staleProposalDays: 14
        sources:
          - memory
          - docs
      documentation:
        schedule: "0 2 * * *"
        maxPerRepo: 1
      refine:
        closedLookbackDays: 14

1. scmSecretRef is the only required field. The Secret must exist in the same namespace and contain a token key with the bot PAT.
2. Agent defaults are production-ready out of the box. Override model and image to pin specific versions.
3. Hooks run via sh -c. A non-zero exit is logged and counted but never aborts the session.
4. Set pgInstances: 3 for HA. A single instance is acceptable for non-critical projects but is vulnerable to crash-recovery wedges on CephFS-backed storage.
5. Grafana integration provisions a grafana-mcp sidecar for incident-response tasks. The secretRef Secret must contain serviceAccountToken and webhookSecret keys.
6. capacity overrides the maxConcurrentAgents default for queue admission. alertCapacity reserves dedicated slots so incident tasks are never starved by a backlog of normal-priority work.
7. botLogin must match the SCM account whose token is in scmSecretRef. Mismatches cause the operator to misidentify its own comments as human input.
8. maintainerLogins + reporterLogins form the security perimeter. maintainerLogins is not optional hardening here - it is required for anything to ever be approved: empty means no login can ever be cited as a maintainer approval, so no issue advances out of refined.
9. Issue scan hourly, brainstorm weekly on Monday morning, documentation nightly. There is no mrScan cron to set; scheduled PR re-review is part of the sweep.
10. agentPodTTLSeconds bounds one pod's life, not the Task. maxNewTasksPerSweep and maxOpenTasks are separate Task-minting budgets from the pod-concurrency budget (maxConcurrentAgents) above. maxBundleBytes is the hard byte cap on every rendered context bundle.
11. maxTurnsPerPod, maxTurnsPerTask, maxReviewRounds, and maxPodRecreations are deprecated with zero effect - kept only because helmfile still sets them. Nothing survives that group as a live field: the review-re-entry bound is the MaxHumanReviewRounds constant (see the warning under AgentSpec), not something to write here. modelByKind/effortByKind tier specific agent kinds down (here documentation/refine drop to Sonnet at lower effort) while the project-wide model/effort fallback stays high-end for everything else. skillsRef pins the agent-skills clone to a released tag to avoid main drift; it is hand-bumped in every project including tatara/infrastructure - no pipeline rewrites it - and tatara-helmfile's check_agent_pins() guard fails CI if it (or the wrapper image tag) is ever left unpinned.
12. tokenBudget is off unless this block is present with enabled: true. customWindow mode meters absolute tokens against tokenLimit inside the cron-anchored resetSchedule/windowDuration window; claudeSubscription mode gates on wrapper-reported Claude usage percentages instead (see TokenBudgetSpec).
13. staleProposalDays: 14 is accepted by the CRD but read by nothing today - no reaper auto-closes stale proposals. See the warning under scm.cron.brainstorm. minSessionIntervalMinutes is the knob that does bite on this cycle.
14. documentation.enabled + documentation.repo is the real on-switch and docs-target repo for the nightly documentation agent; scm.cron.documentation.schedule (above) is a separate, also-required gate - the cron CronActivity has no enabled field of its own.
15. mcpServers bring-your-own-MCPs into this project's agent pods, on top of the platform-owned servers. The operator only checks shape (name pattern, type enum); the wrapper does the actual merge and drops any entry that collides with a reserved platform name.