Developer workflow

The Developer workflow implements and validates engineering changes; use it to take a brief or ticket through pull-request review.

You can

• Start from a brief or a connected task.
• Review plans and designs when approval is configured.
• Inspect validation, reviews, costs, and delivery evidence.
• Recover eligible failed work from a saved branch.
• Choose approval and merge actions based on current checks.

How does a Developer run work?

DEVELOPER DELIVERY PATH

A scoped brief becomes a reviewed pull request

1. 01

   Define

   Resolve the brief, repository, agent, and access.

2. 02

   Build

   Plan, implement, and self-review in isolation.

3. 03

   Verify

   Run validation, reviews, and eligible repair loops.

4. 04

   Deliver

   Push the branch, open the PR, and follow CI.

The run prepares an isolated execution environment, lets a coding agent implement the change, and records delivery evidence. Run history records repository access, execution, issue updates, and pull-request delivery.

Prepare the launch inputs

Input	Purpose
Organization and venture	Access boundary
Repository and base branch	Source and integration target
Task or brief	Goal and acceptance criteria
Developer agent	Coding identity and tool permissions
Validation requirements	Repository commands and evidence expectations
Project-management reference	Optional source ticket and status updates
Approved resources	Available credentials and resources
Per-launch AI settings	Optional overrides to venture defaults

Empty repositories are supported. Organ creates an empty starting commit on the requested base branch; scaffold files remain on the feature branch until merged.

Check access before starting

• Connect a repository.
• Supply a supported source-control credential with the required permissions.
• Connect a work item for task-driven runs.
• Enable a developer agent and model.
• Ensure execution capacity is available.

GitHub, GitLab, and platform-hosted repositories (Beta) are supported. Linear is the only supported task tracker; use providers offered in the selector.

What happens at each stage?

The exact path depends on configuration.

Stage	Work performed
Initialize	Resolve task, title, run record, authorized context, and execution environment
Define	Scope, gather missing answers, link/create the task, and await configured approval
Plan	Produce candidates and await selection when human review is enabled
Execute	Implement, self-review, validate, and fix reported issues
Review	Engineering, design, acceptance, and cleanup reviews when applicable
Deliver	Await approval, push, open the PR, inspect CI, repair eligible failures, rebase, notify, update issue
Finalize	Record the outcome and release execution resources

Scoping, planning, coding, reviews, and eligible repairs use models. Waiting, notifications, record creation, and most infrastructure operations do not need model calls.

Review a design before implementation

UI work can include a design pass with mocks, captured states, and the product lead's critique. Revisions remain available for review.

1. Review the design result and captured states in the run.
2. Choose Approve, or choose Request changes and provide notes when a decision is needed.
3. For a standalone signed-off design, choose Implement this design to start coding.

Sign-off does not ship code. Cancelling a Developer run also cancels the design run it is waiting on.

Once the parent ends, its design child no longer needs an operator decision. Failed or unsigned designs can fall back to planning without using unsigned mocks.

The run records that fallback when it can save the note. Inspect the design result before assuming implementation used it.

Confirm what was delivered

A successful run can provide:

• Pushed branch, commit identifier, and pull-request link.
• Validation and CI results.
• Phase outputs and review findings.
• Connected issue status updates and comments.
• Model usage and cost attribution.
• Application event history.

Code in the execution environment alone is not delivery. Confirm the push, pull request, final notification, and issue update.

When supported, an existing agent pull request returns to draft while the Developer run works on it. This also covers later revisions; the run attempts to restore readiness when work finishes.

Draft conversion is best-effort and provider support varies. Inspect the actual pull-request state and CI result before treating the work as ready.

Understand model and compute usage

Each model-using phase resolves settings from the saved run configuration. Several calls or models can contribute to one phase.

Detail	Meaning
Live token counters	Provisional input, output, and cache activity
Completed phase metadata	Final per-model token and estimated-cost attribution
Runner compute	Separate estimate using recorded tier, capacity, and duration
Hourly compute refresh	Attributes runtime after workflow completion

Developer phases can resume or fork sessions. Keeping provider/model settings consistent preserves cache reuse; explicit overrides may cause cache misses or unsupported cross-provider resume.

See Compute, tokens, and model selection for settings precedence and billing boundaries.

Review and recover work

Open the run detail for stages, logs, costs, PR links, errors, and saved work. Failure explanations use plain language; raw technical diagnostics are staff-only.

1. Open the retry dialog for eligible failed Developer work.
2. Inspect the saved work and whether implementation or validation comes next.
3. Keep Recover the previous work selected to reuse the saved branch when available.
4. Clear Recover the previous work for a fresh start from main.

Without saved work, retries start from main. Validation always runs again.

Expand Quality check in the phase timeline to see validation, reviews, fixes, and related pushes. Applicable rule checks appear beside their steps; finding counts group reported issues by severity.

Choose an approval or merge action

Available actions depend on the current PR, checks, and branch protection.

Action	Result
Approve with note…	Adds context before approval
Approve only	Leaves the PR open
Merge when green on a draft	Marks ready, waits for checks, then merges if gates pass
Rebase or conflict-resolution choices	Attempt the offered repair before merging
Merge despite failures when offered	Requires a note and still respects branch protection
Approval without merging	Available when branch protection blocks the merge request

Troubleshoot a failed or waiting stage

If you see…	Why	What to do
Task/context fetch failed	Reference, credential scope, or ownership issue	Correct the reference/access and retry
Execution cannot start	Capacity or recovery state	Wait for recovery; retry only when allowed
Waiting for input	Question or approval is pending	Submit the requested decision
Implementation/review failed	Model, context, or tool problem	Inspect the last output; retry if eligible
Validation failed	Repository checks reported a problem	Inspect command and exit code; fix or refine requirements
Push/PR failed	Access, branch protection, or remote conflict	Restore access or rebase; follow repository force-push policy
Waiting for CI	Provider build or synchronization state	Inspect CI and synchronization; avoid duplicate PRs

Check the available recovery controls

Use the launch form's supported providers. Export or recovery controls absent from the UI require administrator help.

Older runs can have less phase and cost detail. Do not start duplicate runs while the existing run awaits a decision or recovery.