Workstreams and issues

A workstream gives a managed application a continuing objective. Issues divide that objective into changes an agent can finish and someone can verify. The workstream preserves the larger purpose when individual sessions end.

Start with an outcome

For a support application, use an objective such as “Urgent requests reach the right queue without duplicate entries.” Record the affected application and environment, expected behavior, scope limits and a way to demonstrate success. “Improve the backend” leaves too much unstated to schedule or review.

A workstream is represented by an epic root ticket. Related issues point back to that root. Agents can propose a workstream and attach issues immediately; human approval is a separate step before the managed automatic scheduler admits its work. Approval applies to that root, not an unrelated proposal.

Run one eligible issue

After a human approves the workstream root, Run starts or resumes one eligible member of that workstream. Run is a manual, one-shot dispatch: its metadata records the selected ticket, executor claim, slot and session, conversation and branch so an operator can follow that single attempt. It does not approve the root, continuously schedule the workstream or dispatch an unrelated issue.

All ordinary approval gates remain in effect. Run also preserves the legacy PR orchestrator's operator-paused state; it does not silently resume that orchestrator. An execution can finish blocked before it produces a change, so using Run does not promise a pull request. Record the terminal outcome and a PR URL only when a PR was actually opened.

This page's documentation-only Run smoke test recorded:

Write an issue an agent can finish

A useful issue includes:

• the observed problem and desired behavior;
• the relevant app, repository and environment;
• acceptance examples, including a failure or duplicate case;
• dependencies and scope boundaries;
• required evidence, including deployed behavior when delivery is in scope.

For example: “Submitting the same support-request id twice must leave one queue entry. Preserve its original priority. Demonstrate the behavior with a focused test and an authorized read after managed deployment.” This defines a result without forcing the agent to follow an unverified implementation guess.

Separate grouping from ordering

Parent/root links organize issues. Dependency links define ordering. Two issues belonging to the same workstream are not automatically sequential.

flowchart LR
  Contract[Agree duplicate-request behavior] --> Transform[Implement schema and transform change]
  Contract --> Fixture[Prepare acceptance fixture]
  Transform --> Verify[Integrate, deploy and verify]
  Fixture --> Verify

Keep independent investigations parallel where capacity permits. Changes to the same schema or files need a clear owner and an integration step. A dependency becoming terminal is a scheduling signal; a cancelled prerequisite still needs review to establish whether its dependent work makes sense.

Track progress with evidence

A code-only issue may finish with a reviewed change if that is its stated scope. A delivery issue needs the deployed result. Keep a separate delivery issue when several implementation issues contribute to one rollout.

Pause, reprioritize and follow up

Pause suspends the running TUI and its worker sessions and gates new dispatches. Run resumes them, or requests one eligible member when the lane is idle. Stop terminates the sessions, cancels queued dispatch and waits for executor claim cleanup. Completed issues retain their terminal state.

The CLI exposes the same mechanics:

rac workstream status <root-ticket-id>
rac workstream run <root-ticket-id> --ticket <member-ticket-id>
rac workstream pause <root-ticket-id>
rac workstream unpause <root-ticket-id>
rac workstream stop <root-ticket-id>

play aliases run; unpause aliases resume. Resume reopens the gate and continues suspended sessions without requesting another issue. Add --dispatch-only to pause or resume when only the queue gate should change. Status reports the complete claim inventory and execution conversation links; a queued request is pending until an executor claim appears. Running requires the root's separate human approval. A failed control keeps the gate closed.

For executors with repair loops, the workstream max-iterations setting limits repair rounds in each phase: before verification and, if verification introduces a regression, again afterward. An execution can therefore use up to twice the configured number of repair rounds. Ticket TUI workflows retain their separate single-pass review/fix limits. This setting does not drain or bound the issue queue; each Run still selects one eligible issue.

For example, after Stop, wait until status shows that the executor claim has been cleaned up before treating the stop as complete. After a queued Run, treat it as pending until status shows both a live executor claim and its execution conversation.

When priorities change, identify both queued and active assignments so obsolete work does not continue unnoticed.

Put newly discovered work into linked follow-up issues with its own acceptance criteria. This keeps the current change reviewable while preserving discoveries. Use issue comments for significant failures and their resolution, with links to the corresponding revision and verification result.

The tickets application explains the managed issue store and its onboarding API. Continue with agent lifecycle to follow an eligible issue into execution.