AgentPlan Reference - Nominos Documentation

Overview

An AgentPlan (apiVersion: nominos.io/v1) coordinates several AgentJobs against one repository. You either write the steps yourself (decompositionMode: manual) or give a high-level task and let a model break it down (decompositionMode: ai). The controller creates one AgentJob per step, respecting execution order, dependencies, and the failure strategy.

kubectl

kubectl get agentplans
NAME                     PHASE     MODE     PROGRESS   TOTAL   AGE
security-patch-rollout   Running   manual   1          3       4m

Spec Fields

Field	Type	Default	Description
`repository`	RepositorySpec	—	Repository for all jobs in this plan. Same shape as AgentJob’s spec.repository. Required.
`decompositionMode`	enum: manual \| ai	—	How tasks are defined: you write the steps (manual) or an AI breaks down a high-level task (ai). Required.
`task`	string	—	For AI decomposition: the high-level task to break down. Required when decompositionMode is ai.
`steps`	PlanStep[]	—	For manual decomposition: the list of sub-tasks. Required when decompositionMode is manual.
`executionMode`	enum: sequential \| parallel \| mixed	sequential	One step at a time, all steps concurrently, or dependency-aware (mixed respects dependsOn and per-step parallel flags).
`defaultContextMode`	enum: shared \| isolated	shared	shared: each step starts on the same branch and sees previous commits. isolated: each step starts fresh from the base branch.
`createDraftPR`	boolean	false	Create PRs as drafts.
`agent`	AgentSpec	—	Default agent configuration for all steps (image, model, harness, maxTurns, …).
`maxCostDollars`	string	—	Maximum total spend in dollars for the entire plan.
`mergeQueue`	MergeQueueRef	—	MergeQueue to enqueue PRs into. Sub-fields: name, namespace (defaults to the plan’s namespace), disabled (opt out entirely).
`defaultPRLabels`	string[]	—	Default labels for PRs created by steps in this plan.
`failureStrategy`	enum: FailFast \| ContinueOnFailure	ContinueOnFailure	Stop the plan on the first failed step, or keep running independent steps.
`mergeStrategy`	enum: squash \| merge \| rebase	squash	How PRs created by this plan’s jobs are merged.

Steps (PlanStep)

Field	Type	Default	Description
`name`	string	—	Step identifier, unique within the plan. Required.
`task`	string	—	Task description for this step. Required.
`focusFiles`	string[]	—	Files the agent should focus on.
`context`	string	—	Additional context for this step.
`contextMode`	enum: shared \| isolated	plan default	Override the plan’s defaultContextMode for this step.
`dependsOn`	string[]	—	Steps that must complete before this one runs.
`parallel`	boolean	false	Whether this step may run alongside other ready steps (mixed mode only).
`model`	string	agent.model	Model override for this step.
`maxTurns`	integer	agent.maxTurns	Turn-limit override for this step.
`agent`	AgentSpec	plan agent	Full agent-config override for this step.
`timeoutSeconds`	integer	3600	Timeout for this specific step, in seconds.

Per-step model choice

Each step can override model, maxTurns, or the whole agent config — use a frontier model for the hard refactor step and a cheaper model for the mechanical cleanup steps in the same plan.

Status

Plan Phases

Phase	Meaning
`Pending`	Plan is waiting to start.
`Decomposing`	AI is breaking the task down into steps (ai mode only).
`Running`	Steps are being executed.
`Completed`	All steps completed successfully.
`Failed`	One or more steps failed.

Status Fields

Field	Description
`phase / message`	Plan phase (see above) and a human-readable status message.
`startTime / completionTime`	When the plan started and finished.
`generatedSteps`	For AI decomposition: the steps the model produced.
`stepStatuses`	Per-step status: phase (Pending, Running, Completed, Failed, Skipped), job reference, branch, commits, PR URL, files changed, errors.
`completedSteps / totalSteps`	Overall progress counters.
`jobRefs`	AgentJobs created for the plan.
`pending / running / failed`	Aggregate step counts by state.
`estimatedCostDollars`	Total estimated cost across all steps.
`workBranch`	Current working branch (shared context mode).
`events`	Significant events during execution (bounded to the last 50): phase transitions, job creation, step start/finish, decomposition progress.
`phaseHistory`	Enter/exit timestamps for each phase the plan has been in.
`decompositionJobRef / decompositionPrompt / decompositionLogs / decompositionParser`	AI-mode introspection: the decomposition job, the prompt sent, the first 10K chars of output, and which parser extracted the steps.
`conditions`	Standard Kubernetes conditions.

Examples

Manual plan with dependencies

agentplan-manual.yaml

apiVersion: nominos.io/v1
kind: AgentPlan
metadata:
  name: security-patch-rollout
spec:
  decompositionMode: manual
  executionMode: mixed
  failureStrategy: ContinueOnFailure
  repository:
    url: https://github.com/myorg/myapp
    baseBranch: main
    createPR: true
  steps:
    - name: patch-auth-service
      task: "Apply security fix to the auth module"
      focusFiles: ["services/auth/"]
    - name: patch-api-gateway
      task: "Update API gateway dependencies"
      dependsOn: [patch-auth-service]
    - name: update-docs
      task: "Document the new auth behavior"
      parallel: true
      model: claude-haiku-4-5   # cheaper model for the easy step

AI decomposition with a merge queue

agentplan-ai.yaml

apiVersion: nominos.io/v1
kind: AgentPlan
metadata:
  name: add-rate-limiting
spec:
  decompositionMode: ai
  task: "Add per-tenant rate limiting to all public API endpoints, with tests"
  executionMode: sequential
  defaultContextMode: shared
  repository:
    url: https://github.com/myorg/api
    baseBranch: main
  mergeQueue:
    name: main-queue
  maxCostDollars: "10.00"

In AI mode the plan first enters Decomposing, records the generated steps in status.generatedSteps, then runs them like a manual plan. PRs land in the referenced MergeQueue.