Introducing a new way to review your PRs.

Read the announcement

stablyai / orca

Orca lets you run a fleet of bots with your own subscription (e.g. Claude Code, Grok, Agy, Codex). Available on desktop, mobile and remote runtime.

View on GitHub

34 documents · Updated Nov 20, 2026

docs / jira-work-management

Jira work management

Jira work management connects Jira sites to Orca so engineers can find work, read issue context, change issue data, and start coding work from an issue. A Jira issue keeps its site identity as it moves through the desktop task view, mobile client, workspace, and agent session. See Agent workspaces, Mobile client, and Command-line and headless runtime for the systems that receive this work.

Product role

Jira work item

The Jira work item is Orca’s provider view of one Jira issue. It keeps the issue key, site, title, project, status, people, labels, priority, dates, and browse URL in one shape so task lists, detail views, linked workspaces, and agent prompts refer to the same external item.

Agile data such as the active sprint and story points is optional. Orca discovers the fields for each site because Jira field names can differ between sites. A missing optional field does not make the issue unavailable.

References: src/…/jira-types.ts• L39-45 src/…/jira-types.ts• L107-129 src/…/jira-issue-mapping.ts• L192-267

Jira connection

Account and site selection

The connection flow verifies a Jira site before Orca saves it as a usable account. It supports Atlassian Cloud and self-hosted Jira. Self-hosted sites can use a personal access token or username and password. Cloud connections can use a scoped token without an email when the selected runtime supports that mode.

Orca can keep more than one site or account. The engineer can select one site or all sites for discovery. A site remains part of the work identity because the same issue key can exist on different Jira sites.

Credentials belong to the runtime that owns the Jira connection. Site information and credentials have separate storage responsibilities. A credential read error stays visible instead of becoming an empty task list. A multi-site read can continue with healthy sites when one saved credential cannot be read.

References: src/…/client.ts• L38-81 src/…/client.ts• L84-167 src/…/jira-connect-dialog.tsx• L67-100 src/…/jira-connect-dialog.tsx• L126-163

Request boundary

All authenticated Jira traffic crosses one host-owned request boundary. The boundary chooses the Cloud or Server/Data Center API form, applies the saved site authorization, uses the runtime network settings, and keeps Cloud tenant routing tied to the selected site.

The boundary also limits response bodies and preserves useful Jira error status. This lets callers distinguish an invalid credential from a permission problem or a transport failure without exposing credentials to the renderer.

References: src/…/authenticated-request.ts• L17-43 src/…/authenticated-request.ts• L95-149 src/…/authenticated-request.ts• L151-212

Runtime ownership

Jira data belongs to the runtime that stores the Jira account. A desktop task view can use its local host or a selected remote host. Mobile asks the paired desktop for Jira access. Remote callers therefore work through the same site and account boundary instead of keeping another copy of Jira credentials.

The task view keeps the runtime owner, site, and task-source context with its reads and writes. This prevents a late reply from one host or account from changing another task view.

References: src/…/runtime-jira-client.ts• L50-103 src/…/runtime-jira-client.ts• L106-175 mobile/…/mobile-jira-operations.ts• L10-72

Work discovery

Projects and filters

Project discovery gives the task view the scope needed to find and create Jira work. A repository can provide a default Jira project when its execution host matches the Jira source host. Engineers can override that project for the current task context without changing the repository setting.

Task discovery supports preset views for assigned, reported, all, and done issues. Status filters, current-sprint filters, saved JQL filters, and Jira favourite filters narrow the same site-scoped work set. Favourite filters require one explicit site because Jira does not define one shared filter space across accounts.

References: src/…/use-task-page-jira-project-scope.ts• L20-75 src/…/jira-project-override-session.ts• L3-21 src/…/Filters.tsx• L57-136 src/…/jira.ts• L218-247

Issue search and lists

The search flow turns a preset, issue key, text query, or JQL query into normalized Jira issues. A malformed JQL query can fall back to text search with a notice, while authentication, rate-limit, and service failures remain visible as failures. Results can appear as a sortable list or a status board.

The task view bounds result size and can cancel an old search when the engineer changes the query. Across several sites, healthy results remain useful when one site fails. The task view reports a failure only when the complete selected set fails.

References: src/…/jira-issue-input-search.ts• L24-75 src/…/jira-issue-search.ts• L24-34 src/…/jira-issue-search.ts• L73-123 src/…/jira-issue-search.ts• L126-201 src/…/Filters.tsx• L204-245 src/…/Content.tsx• L141-249

Status board

The Jira board groups the discovered issues by status and uses Jira transitions to move an issue to another column. When a transition needs extra fields or a comment, the board asks for those values before it sends the change. An unambiguous transition can run directly; an ambiguous choice stays in the move dialog.

Board metadata is scoped to the runtime owner, task source, site, project, issue, and current status. A failed transition lookup remains retryable and does not silently move the issue in the local view.

References: src/…/task-page-jira-board-view.tsx• L78-153 src/…/task-page-jira-board-view.tsx• L155-223 src/…/Content.tsx• L203-221

Issue detail

Issue detail starts with the selected list item and then loads the full issue, comments, priorities, and available transitions from the owning Jira runtime. Optional comments can fail without hiding a readable issue. The view keeps submitted edits visible while a refresh is pending or incomplete.

Jira Cloud uses Atlassian Document Format, while Server/Data Center can use plain or wiki-style text. Orca presents both forms as readable Markdown-like text and publishes user-entered Markdown back in the form required by the site. Inline media uses a host-owned reference so the renderer does not receive Jira credentials or trust a caller-supplied image URL.

References: src/…/JiraIssueWorkspace.tsx• L81-110 src/…/JiraIssueWorkspace.tsx• L188-260 src/…/jira-issue-mapping.ts• L179-189 src/…/adf-markdown.ts• L66-108 src/…/markdown-adf.ts• L288-304

Issue mutation

Issue creation

Issue creation is driven by the selected project and issue type. Orca first reads the fields that Jira allows for that type. The creation form then collects the title, optional description, assignee, and required custom values before it creates the issue.

Jira user fields use stable account identities rather than display names alone. After a successful create, Orca refreshes the new issue, adds it to the task view, and opens its detail so the result is immediately linked to the source context.

References: src/…/IssueDialog.tsx• L40-80 src/…/IssueDialog.tsx• L243-365 src/…/use-task-page-jira-issue-creation.ts• L45-115 src/…/jira-issue-mutations.ts• L15-67

Issue edits and comments

Daily issue edits cover the title, labels, assignee, priority, and workflow transition. A transition can include required fields and a comment. The same site-aware issue identity is used for comments, reads, and edits.

The desktop view applies an optimistic change, sends it through the Jira runtime, refreshes the issue, and reconciles the task cache with the provider result. Changes for one issue are serialized. A failed write rolls back only the affected fields while preserving later pending changes.

References: src/…/jira-issue-mutations.ts• L81-187 src/…/jira-issue-mutation-queue.ts• L27-41 src/…/jira-issue-mutation-queue.ts• L66-167 src/…/JiraIssueWorkspace.tsx• L111-179

Workspace handoff

Linked work item

Selecting a Jira issue for development creates a provider-neutral linked work item. The durable link keeps the Jira provider, issue key, title, and URL with the workspace. This lets workspace lists show the source and lets the new-workspace flow recognize a Jira URL.

Pasted Jira URLs are matched against connected sites. If more than one site can own the issue, the engineer selects the account before Orca reads the summary. The resolved source keeps the selected site, project, account label, repository, and execution host together.

References: src/…/workspace-source.ts• L36-39 src/…/workspace-source.ts• L70-99 src/…/workspace-source.ts• L147-157 src/…/use-jira-url-source.ts• L75-93 src/…/use-jira-url-source.ts• L129-215

Agent handoff

Starting work turns the Jira issue into a workspace creation request for a chosen repository and execution host. Orca derives a workspace name from the issue, stores the linked work item, and carries the issue URL into the initial agent draft when an agent is selected. The URL is context for the agent; it is not treated as an already-submitted prompt.

The handoff follows this path:

flowchart LR
    A[Jira issue] --> B[Choose repository and agent]
    B --> C[Create workspace]
    C --> D[Store linked Jira item]
    C --> E[Prepare issue URL context]
    E --> F[Agent session]

After a workspace exists, the CLI can start an agent in that workspace as chat or terminal. A remote call names the workspace because a local directory does not identify a remote worktree. A lost launch reply is treated as unknown, not as permission to start a duplicate launch. Supported hosts replay the same operation ID; older hosts require inspection before another deliberate launch.

References: src/…/JiraLinkedWorkspaceAction.tsx• L14-63 src/…/workspace-source.ts• L189-227 src/…/agent-launch-request.ts• L39-50 src/…/agent-launch-request.ts• L123-175 src/…/agent-launch-recovery.ts• L8-93

Linked workspace return path

Jira task rows show workspaces already linked to an issue. The engineer can open an existing workspace or start another workspace from the same issue. Jira therefore serves as both a work queue and an entry point to an active coding session.

References: src/…/JiraLinkedWorkspaceAction.tsx• L24-61 src/…/use-task-page-jira-list-projection.ts• L44-81

Client and runtime contracts

Desktop contract

The desktop task view uses one Jira client contract for connection state, project and filter discovery, issue lists, issue detail, comments, transitions, mutations, and issue creation. The client sends each operation to either local host IPC or a selected remote runtime, so the product flow stays the same across execution hosts.

The local and remote boundaries validate inputs, preserve site identity, bound issue data, and expose host-owned media access. Runtime methods separate account administration from workspace work through different permissions.

References: src/…/runtime-jira-client.ts• L50-176 src/…/runtime-jira-client.ts• L178-272 src/…/jira.ts• L54-131 src/…/jira.ts• L132-230

Mobile contract

Mobile presents Jira as a task discovery and workspace-source experience. It asks the paired desktop for connection status, issue lists, searches, issue detail, and comments. It then uses the normal workspace creation and agent launch contracts to start work.

Jira credentials and Jira issue mutations stay on the paired desktop. Mobile can continue to show other task providers when the paired host does not support the Jira contract or returns an incompatible reply.

References: mobile/…/mobile-jira-operations.ts• L10-72 mobile/…/mobile-jira-task-source.ts• L19-80 mobile/…/jira-mobile-connection.ts• L23-69 mobile/…/jira-mobile-url-lookup.ts• L10-30

CLI and headless contract

CLI and headless callers use the runtime command and RPC surface instead of a second Jira client. The runtime exposes connection, discovery, reads, creation, edits, comments, and workflow metadata to authenticated callers. The caller selects the execution host, and the host checks whether the requested Jira or agent action is supported.

Agent launch requests can carry a prompt, model choice, and chat-or-terminal surface when the host supports them. Durable launch operations carry an operation ID so a transport failure does not become an unsafe blind retry.

References: src/…/jira.ts• L54-81 src/…/jira.ts• L113-224 src/…/agent-launch-request.ts• L71-105 src/…/agent-launch-request.ts• L115-175

Payload compatibility

Remote issue details and comments can be larger than one transport frame because they may contain rich text and media. The runtime can stream bounded Jira payloads in chunks. A client can use a text-only or one-shot path when the remote host does not support the newer rich-data method.

Image access uses a short-lived opaque reference. Disconnecting or replacing a site revokes old references so a later image request cannot use an old Jira session.

References: src/…/jira.ts• L27-38 src/…/jira.ts• L150-216 src/…/jira-attachment-image.ts• L13-50

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the shared Jira types, runtime parameter schemas, desktop adapters, mobile readers, and CLI callers aligned. They form one contract across all Jira surfaces.
  • Preserve siteId through issue reads, search results, filters, mutations, attachment references, and linked workspace data. A Jira key is not globally unique across sites.
  • Keep Cloud and Server/Data Center API forms, authentication rules, and text body formats aligned with the saved site type.
  • Keep project scope tied to the execution host, repository identity, selected site, and session override. A repository default must not cross to another host or site.
  • Keep issue and board cache scopes tied to the runtime owner, task source, site, issue, project, and status. Do not let a late reply replace another view’s data.
  • Keep rich issue payloads paired with a bounded streaming path and a compatible fallback for older runtimes.
  • Keep attachment grants and cache invalidation paired with connect, disconnect, credential replacement, and cancellation paths.
  • When changing workspace creation or agent launch, keep the linked Jira item, generated workspace name, issue URL context, selected agent, launch surface, and recovery operation ID together.

Important failure modes

TriggerConsequenceGuard
The same issue key matches more than one connected siteOrca may read or mutate the wrong external issueKeep siteId in the work identity and require account selection for ambiguous URL lookups.
A saved credential cannot be read or no longer has accessJira work appears unavailable even though the account remains configuredSurface the credential error and require reconnect or re-authentication.
A Cloud request uses the wrong tenant or an unsafe attachment URLData or authorization can cross the selected site boundaryRoute through the saved site gateway and reject destinations outside that site.
Jira rejects a JQL query because it is malformedSearch may show no work even though text matches existRetry as text search only for a Jira bad-request response and show the JQL notice.
A required create or transition field is missingJira rejects the create or workflow changeDiscover fields for the selected project and type before submission.
A write succeeds but the refresh failsThe task view can show stale provider dataKeep the successful optimistic change and reconcile it on the next provider read.
A runtime lacks a newer filter or streaming capabilityA board filter or rich detail read cannot run on that hostCheck capabilities and use the supported fallback or show an update message.
Mobile attempts to own Jira credentials or mutationsJira ownership crosses the phone-to-desktop boundaryRoute Jira account and issue changes to the paired desktop.
A CLI launch reply is lost after the host may have started the agentA fresh retry can create a duplicate session or submit the prompt twiceReplay the same operation ID when supported; otherwise inspect the host before relaunching.
A late reply arrives after the site, runtime, or issue changesOld data can overwrite the current task viewScope request state and cache entries by the current runtime, site, source, and issue.

Key files

FileWhy to read it
src/…/jira-types.tsDefines the shared Jira site, issue, filter, creation, and mutation language.
src/…/client.tsShows site verification, account selection, connection status, and credential ownership.
src/…/authenticated-request.tsShows the host-owned request boundary for Cloud and Server/Data Center Jira.
src/…/jira-issue-search.tsShows preset and JQL discovery across one or more sites.
src/…/jira-issue-read.tsShows issue detail reads, summary lookup, and optional media loading.
src/…/jira-issue-mutations.tsShows issue creation, edits, workflow changes, and comments.
src/…/jira-issue-mapping.tsShows the common issue shape and site-specific body handling.
src/…/adf-markdown.ts and src/…/markdown-adf.tsShow the read and write boundary between Jira rich text and Orca text.
src/…/jira.tsDefines the authenticated runtime Jira operations and permissions.
src/…/runtime-jira-client.tsPresents one Jira client across local and remote desktop targets.
src/…/Content.tsx and Filters.tsxShow the desktop task list, board, filters, and workspace entry points.
src/…/JiraIssueWorkspace.tsxShows the issue detail, edit, transition, comment, and start-work surface.
src/…/task-page-jira-board-view.tsxShows status movement and transition handling from the board.
src/…/IssueDialog.tsxShows project, issue type, and dynamic-field selection for issue creation.
src/…/workspace-source.tsDefines how a Jira issue becomes a durable linked workspace source.
src/…/use-jira-url-source.tsShows pasted-URL lookup, account choice, and source-context binding.
mobile/…/mobile-jira-task-source.tsShows mobile issue discovery and detail reads through the paired host.
mobile/…/jira-mobile-connection.tsShows mobile connection state and older-host compatibility.
src/…/agent-launch-request.ts and agent-launch-recovery.tsShow CLI agent launch capabilities, replay IDs, and safe unknown-outcome recovery.