Skip to content

CONCEPT Cited by 1 source

Work item as agent prompt

Definition

Work-item-as-agent-prompt is the architectural framing in which a ticket / work item in an issue tracker (Jira, Linear, GitHub Issues) is treated as a structured prompt for an AI agent — not just a unit of human work. The work item's fields, description, comments, and attachments are the agent's context; the workflow state machine is the orchestration layer; the status transition is the trigger.

Atlassian's 2026-06-01 Jira-team post is the canonical wiki articulation:

"Jira is the heart of our strategy. Each work item is a record of the tasks we need to complete and acts as a prompt for agents. All the context an agent needs is shared using the work item, Atlassian's Teamwork Graph, and the explicit instructions we include in our workflow automations." (Source: sources/2026-06-01-atlassian-how-we-cut-up-to-80-of-engineering-chores-using-ai-agents-in)

The three context substrates

The agent's prompt at run time is composed from three layers:

  1. The work item itself — title, description, custom fields, labels, comments, attachments, links. For Atlassian's stale feature flag cleanup work items: "Flag name and type … Repository and code references: the exact repo, file paths, and line numbers where the flag appears … Desired final state: what the code should look like once the flag is removed." This is the per-task brief.
  2. The cross-product knowledge graph — Atlassian's Teamwork Graph in the Atlassian instance; analogues elsewhere include LinkedIn Project ChickenSpot's metadata layer, Linear's project links, or any API-catalog-style discovery substrate. This is the cross-task context the agent can pull in (related work, ownership, prior decisions).
  3. The workflow automation's custom system prompt — encoded into the Jira workflow transition itself; this is where the "how to do this kind of work" instructions live (sibling to a per-codebase orchestration skill). Atlassian: "a workflow that passes a custom system prompt to the agent with cleanup instructions."

The split matters: the work item is per-task data, the knowledge graph is shared cross-task knowledge, and the transition prompt is per-procedure instructions. Three layers, three lifetimes, three editors.

Structured fields > free-text descriptions

The substrate framing privileges schema-shaped fields over free-text descriptions because the agent does not need to parse prose to extract the brief. Atlassian's stale-flag work items use explicit fields:

Field Why structured Agent action
Flag name Disambiguates target Find call sites, flag-config entry
Flag type (rollout / experiment / kill switch) Selects fix pattern "For a rollout gate, this is typically the 'on' or 'off' branch to preserve. For experiments, it may be the winning cohort, a specific variant's behavior, or a custom path defined by the experiment owner."
Repo + file paths + line numbers Localises the change git checkout and cd to right files
Desired final state Defines done Dictates the diff

A free-text "please clean up flag X" would force the agent to re-discover all of this; the cron's value is resolving cross-system state once and writing it into the work item so each agent run starts with a fully resolved brief.

Workflow state machine as agent orchestration

The Jira workflow is the outer orchestration loop for the agent:

  • Open — work item exists, not yet triaged by human.
  • In Progress — engineer transitioned it to delegate-to-agent. Transition triggers the agent run.
  • Awaiting Review — agent has opened a draft PR and added a comment. Human reviews.
  • Done — PR merged, work item closes.

The workflow's named states bound the agent's authority: it can move the work item from "In Progress" to "Awaiting Review" (by opening a PR / commenting), but it cannot merge or close — the merge gate (concepts/agent-as-first-pass-investigator) is preserved by the workflow definition.

Why this is a distinct concept from generic ticket→work

Tickets have always been "the unit of work" in human-driven engineering. The shift is:

  • Pre-agent: ticket = human assignment + free-text context; human reads, interprets, executes; status updates happen on the way.
  • Agent-as-prompt-target: ticket = structured agent prompt + per-procedure system prompt + workflow-state-machine orchestration; agent reads, interprets, executes; status updates trigger the agent.

The structural-prompt discipline and the workflow-state-as-trigger mechanic are the new architectural moves; the underlying ticketing substrate (Jira, Linear, GitHub Issues) is unchanged.

Substrate requirements

For "work item as agent prompt" to function:

  • Custom fields — to encode structured task parameters.
  • Workflow automations / transitions with side-effect actions — to trigger the agent run with a per-transition system prompt.
  • Comments + PR-link surface — for the agent to report back into the work item.
  • (Optional) cross-product knowledge graph — to enrich the agent context beyond the work item itself.

Jira Cloud's Add an agent to workflow transitions feature is the first-party Atlassian implementation surface; Linear / GitHub-Actions-on-issues are adjacent equivalents on other substrates.

The work-item-as-prompt model composes with upstream auto-ticket-creation pipelines. Two canonical inputs:

In both cases the upstream signal becomes a Jira work item with the agent already in mind as the consumer — the cron / alert workflow's job is to write the prompt fields the agent will later read.

Seen in

Last updated · 542 distilled / 1,571 read