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
siteIdthrough 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
| Trigger | Consequence | Guard |
|---|---|---|
| The same issue key matches more than one connected site | Orca may read or mutate the wrong external issue | Keep siteId in the work identity and require account selection for ambiguous URL lookups. |
| A saved credential cannot be read or no longer has access | Jira work appears unavailable even though the account remains configured | Surface the credential error and require reconnect or re-authentication. |
| A Cloud request uses the wrong tenant or an unsafe attachment URL | Data or authorization can cross the selected site boundary | Route through the saved site gateway and reject destinations outside that site. |
| Jira rejects a JQL query because it is malformed | Search may show no work even though text matches exist | Retry as text search only for a Jira bad-request response and show the JQL notice. |
| A required create or transition field is missing | Jira rejects the create or workflow change | Discover fields for the selected project and type before submission. |
| A write succeeds but the refresh fails | The task view can show stale provider data | Keep the successful optimistic change and reconcile it on the next provider read. |
| A runtime lacks a newer filter or streaming capability | A board filter or rich detail read cannot run on that host | Check capabilities and use the supported fallback or show an update message. |
| Mobile attempts to own Jira credentials or mutations | Jira ownership crosses the phone-to-desktop boundary | Route Jira account and issue changes to the paired desktop. |
| A CLI launch reply is lost after the host may have started the agent | A fresh retry can create a duplicate session or submit the prompt twice | Replay the same operation ID when supported; otherwise inspect the host before relaunching. |
| A late reply arrives after the site, runtime, or issue changes | Old data can overwrite the current task view | Scope request state and cache entries by the current runtime, site, source, and issue. |
Key files
| File | Why to read it |
|---|---|
| src/…/jira-types.ts | Defines the shared Jira site, issue, filter, creation, and mutation language. |
| src/…/client.ts | Shows site verification, account selection, connection status, and credential ownership. |
| src/…/authenticated-request.ts | Shows the host-owned request boundary for Cloud and Server/Data Center Jira. |
| src/…/jira-issue-search.ts | Shows preset and JQL discovery across one or more sites. |
| src/…/jira-issue-read.ts | Shows issue detail reads, summary lookup, and optional media loading. |
| src/…/jira-issue-mutations.ts | Shows issue creation, edits, workflow changes, and comments. |
| src/…/jira-issue-mapping.ts | Shows the common issue shape and site-specific body handling. |
| src/…/adf-markdown.ts and src/…/markdown-adf.ts | Show the read and write boundary between Jira rich text and Orca text. |
| src/…/jira.ts | Defines the authenticated runtime Jira operations and permissions. |
| src/…/runtime-jira-client.ts | Presents one Jira client across local and remote desktop targets. |
| src/…/Content.tsx and Filters.tsx | Show the desktop task list, board, filters, and workspace entry points. |
| src/…/JiraIssueWorkspace.tsx | Shows the issue detail, edit, transition, comment, and start-work surface. |
| src/…/task-page-jira-board-view.tsx | Shows status movement and transition handling from the board. |
| src/…/IssueDialog.tsx | Shows project, issue type, and dynamic-field selection for issue creation. |
| src/…/workspace-source.ts | Defines how a Jira issue becomes a durable linked workspace source. |
| src/…/use-jira-url-source.ts | Shows pasted-URL lookup, account choice, and source-context binding. |
| mobile/…/mobile-jira-task-source.ts | Shows mobile issue discovery and detail reads through the paired host. |
| mobile/…/jira-mobile-connection.ts | Shows mobile connection state and older-host compatibility. |
| src/…/agent-launch-request.ts and agent-launch-recovery.ts | Show CLI agent launch capabilities, replay IDs, and safe unknown-outcome recovery. |