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 workstream scheduler admits its work. Approval applies to that root, not an unrelated proposal.

Run the workstream conversation

Each workstream has one ordinary conversation and one standard agent runtime. Choose Redgold TUI, Codex, or Claude Code before the first Run. The conversation follows the normal repository and delivery instructions, including checks, review, publication and verification when its task requires them.

After approval, Run sends the root brief, settings and ready issue context to that conversation. It also works when the root brief is the only work available. Use --ticket to identify a ready member to work on first. Subsequent turns reuse the same conversation. A repeated Run while it is active or awaiting dispatch returns its current state without starting another runtime.

rac workstream settings <root-ticket-id-or-slug>
rac workstream settings <root-ticket-id-or-slug> --harness codex --cost normal --reasoning max --provider-policy codex-only --dry-run
rac workstream settings <root-ticket-id-or-slug> --harness codex --cost normal --reasoning max --provider-policy codex-only
rac workstream configure <root-ticket-id> --runtime tui
rac workstream status <root-ticket-id>
rac workstream run <root-ticket-id>
rac workstream run <root-ticket-id> --ticket <member-ticket-id>

rac workstream settings <root> --pace live enables a bounded API reviewer while a TUI lifecycle executor works. --pace serial restores the default; an absent pace label also means serial. This is independent of ticket delay and does not parallelize scheduled runs or remove the normal gate review. The setting is refreshed before the next worker starts, not applied to an already running worker.

Live review samples changed executor output every 30 seconds, with at most four API calls and two distinct nudge attempts per EXECUTE leg. Review uses a different model family (Luna, or Sol when the executor is Luna), low reasoning and a 512-token reply limit. Existing account spend and workstream cost/provider ceilings still apply. A cheap-only Luna executor or a Claude-only policy cannot use this cross-family API selection: the lifecycle records the reason and continues with its mandatory gate review. Unknown executor families and unavailable exact message endpoints also stop live observation rather than falling back to terminal keystrokes.

Samples, decisions, available token usage, estimated list-price cost and queue receipts appear in lifecycle notes. A queued receipt is not proof the executor acted on the correction. Codex nudges target its bound thread queue; Claude nudges target its private message socket and run after the active turn. Neither path takes over the visible pane. Observation is cancelled with the EXECUTE future, including lifecycle cancellation; no observer task survives it.

settings is an alias of configure; --harness and --reasoning are aliases of --runtime and --effort. With no edit flags it reads compact JSON settings and ordinary conversation evidence, without loading every member. --dry-run validates the same change and shows before/after settings without writing. Settings changes preserve approval, pause, schedule and conversation identity; revision-aware servers reject a stale edit rather than overwrite a concurrent Stop or policy change. A failed conversation observation appears separately from whether settings were saved. Null policy values inherit conversation defaults. When switching away from a TUI with stage presets or legacy model pins, add --clear-model-pins to explicitly remove those TUI-specific settings.

--runtime codex requests Codex through ordinary conversation admission. Native Codex requires an authorized personal gateway conversation; workspace and direct-credential conversations use the isolated TUI adapter. Runtime availability and authorization follow the same rules as a user-started conversation. An existing conversation retains its runtime binding. Codex also retains the original provider, model and authentication selection: changing its cost profile can hold later turns until the original selection is restored. A conflicting selection is reported instead of creating another conversation.

--runtime claude selects the native Claude Code harness for an authorized personal Anthropic gateway conversation. It runs Claude's own interactive CLI, tools and resumable session. Its transcript stays in the workstream conversation; the native parent turn must finish before the next scheduled turn can start. Workspace, imported and direct-credential conversations retain the isolated TUI adapter. The selected model and reasoning effort remain bound to the native session; use a fresh conversation to change them.

mixed-claude and claude-only are model presets for Redgold TUI. They choose models for its stages and do not select the native Claude harness. For native Claude, clear TUI model pins if present:

rac workstream configure <root> --runtime claude --provider-policy mixed --clear-model-pins --dry-run
rac workstream configure <root> --runtime claude --provider-policy mixed --clear-model-pins

To apply a changed harness, wait for the current turn to settle, then inspect rac workstream run <root> --fresh-conversation --ticket <owned-member> --dry-run. Remove --dry-run to submit the guarded transition. It retains the previous conversation in history and checks the exact settled message and control generation. Approval and pause gates still apply; rac workstream resume <root> opens a paused schedule without starting a turn. After an uncertain response, recover the retained transition receipt before retrying Play.

Status links to the workstream conversation and reports its acknowledged pod and session. Pending means dispatch is unconfirmed. Accepted means the message was accepted by Send. Running requires ordinary runtime evidence. Idle means the turn stopped; inspect its result to establish whether the work succeeded. Approval and scheduling holds remain visible separately from runtime state.

Existing executor claims remain available as historical evidence. A live legacy execution must finish or be stopped through its existing controls before a fresh ordinary conversation can start for that root.

Record complete delivery

Keep the root and issue IDs, conversation and message IDs, runtime evidence, and the useful result. For a code delivery, also record the pull request, tested head, merge and publication revision, and deployed verification. An accepted message or an open pull request is an intermediate result. The workstream conversation owns the same delivery lifecycle as an ordinary user-started task.

Write an issue an agent can finish

Use rac issue update <ticket> --add-dependency <id> or --remove-dependency <id> to change prerequisites without replacing the rest of the dependency list. Both accept repeated flags or comma-separated IDs and preserve ticket ownership and other fields. The update carries the current row revision when the server supports it; a concurrent edit requires a fresh read.

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 holds future scheduling and pauses the linked ordinary session. Resume continues that session without submitting another task. Stop holds scheduling and stops the linked session. Controls require acknowledgment before reporting success; an uncertain result leaves the scheduling hold in place. Completed issues retain their state, and the conversation association remains available.

rac workstream pause <root-ticket-id>
rac workstream resume <root-ticket-id>
rac workstream stop <root-ticket-id>

play aliases run; unpause aliases resume. Add --dispatch-only to Pause or Resume when only the root's scheduling gate should change. These controls preserve approval, issue history and unrelated agent assignments. Run can reopen an explicitly held root after the linked session's state has been confirmed.

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.

Queue automation

Manual waits for an explicit Run. Continuous wakes the same conversation when ready work is available and the previous turn has stopped. Scheduled uses a five-field UTC cron expression and sends one workstream brief turn when due, including when no issues are ready. Ready issues are included as context; paused or dependency-blocked issues remain ineligible. Continuous waits when the ready queue is empty. Missed occurrences are combined into one wake. The next occurrence reuses the same conversation after its previous turn has stopped. Saving a new schedule starts its clock at the save time.

All three modes use ordinary conversation Send. The conversation selects and completes work using its normal instructions. Scheduling does not create a per-ticket executor claim or manage another review and publication lifecycle. Each workstream remains one conversation even when its agent delegates internally.

The core engine hosts scheduling as native cron or retained-event pipeline activation. Each program has a durable clock/event cursor, an immutable pending invocation and a fenced retry lease. Workstream settings project into that same language, so the existing CLI and UI controls retain their behavior. The engine reuses ordinary conversation admission, runtime quotas, approval, dependencies and root holds. A paused or busy conversation cannot admit another automatic turn. The executor pool no longer owns workstream scheduling.

Recurring queue producers are declarations under pipelines/automations/workstreams/. They retain existing ticket IDs and bounds, with frozen submissions checked against the root's control generation. Finite native-release/question workers run as Jobs dispatched by the engine; their timing is also engine-owned. Configuring automation does not approve a proposal, resume an intentionally paused root, or change autoscaler settings.

rac workstream schedule <root-ticket-id> --mode continuous
rac workstream schedule <root-ticket-id> --mode cron --cron '0 9 * * 1-5'
rac workstream schedule <root-ticket-id> --mode manual