A single agent pass is rarely enough for complex work. Planning before implementation, verification after — these are distinct responsibilities that benefit from separate prompts and separate context. Stages divide a Trak’s pipeline into sequential steps, each with a focused goal and its own output.
Artifacts
Every stage produces a named artifact: text output stored in .orkestra/.artifacts/. Artifact names are unique within a flow.
Artifacts from earlier stages are automatically injected into the prompt of every later agent stage. A review stage sees the plan and summary artifacts without any manual wiring. The pipeline accumulates context as it advances.
Iterations and rejection
When a human reviews a stage’s output and rejects it, the stage creates a new iteration — the agent session is resumed with the rejection feedback. The agent retains its full conversation history and does not start over.
Iterations are numbered starting from 1. A stage approved on the first try has one iteration. Two rejections before approval creates three iterations.
Multiple rounds of rejection are supported. Each round adds feedback to the agent’s context, narrowing down what needs to change.
Gate integration
Gates are configured per stage and run after the agent produces output. An automated gate (a shell script) that exits non-zero sends the error back to the agent and triggers a retry — all before the output reaches human review. An agentic gate (gate: true) has the agent produce an approve or reject verdict for a human to act on.
Auto mode
By default, every stage pauses after producing output and waits for a human to approve or reject. When a Trak is in auto mode, all stages advance without human approval.
Auto mode is a Trak-level setting, not a per-stage configuration. It applies to all stages in the Trak uniformly.
Capabilities
Agent stages can be extended with capabilities that change what the agent can produce. The Subtraks capability allows the agent to decompose the Trak into child Traks. Every stage can ask questions without any capability flag.
What’s next
See Gates to understand how automated quality checks work within a stage.