> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orchestrahq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Issues from agents' work

> Agents turn what they work on into issues and keep the status current, with nothing in the prompt

When an agent works in a repository Orchestra is enabled for, its own hooks keep
your issues in step with the work. You do not have to ask the agent to file an
issue or move one, and nothing needs to be added to its prompt. This works for
Claude Code and Codex, on Orchestra Local and on hosted.

## What happens

* **New work becomes an issue.** When a session edits code past a small threshold
  (three edits, or two files), Orchestra first looks for an open issue the work is
  about: an issue key in the branch name or in what you asked (`W-12`, `PAY-41`),
  then an issue whose title matches what you asked. If one matches, the session is
  linked to it. If none does, Orchestra creates one in the session's team, titled
  from what you asked, and links the session as its source.
* **Status follows the work.** A session that starts on an issue moves it to
  In Progress. When the agent opens a pull request, the issue moves to In Review
  and the pull request is linked on it. When the pull request is merged (by the
  agent, or later on GitHub), the issue moves to Done, or your team's state for
  done in Jira or Linear.
* **A session that ends without a pull request** leaves one comment on its issue:
  what changed and what is left, citing the session.
* **Follow-ups and dead ends are proposals.** What a session left open, or tried
  and gave up on, is offered on the session's page and in your Inbox as a
  suggested issue, citing the messages it came from. One click creates the ones
  you keep. Nothing is filed without you.

Status only moves forward, and each step happens once. If you move an issue back
by hand, Orchestra does not move it again.

## Issues you ask for keep where they came from

When you ask an agent to make issues from a plan, for example "split this plan
into tickets and assign step 2 to me", each issue it creates carries its source:
the session or saved chat the plan was written in, a Knowledge doc, or a
Confluence page, with the part of it that issue covers. A plan split into several
issues links each one to the same source and its own step.

The issue's page shows the source first under Related, cited, and opens it in one
click. An agent that reads the issue with `get_issue` gets the same source and
passage before it starts.

The source is checked as each reader, every time. Someone who can see the issue
but cannot open its source (a private session, a restricted doc, or a Confluence
page their Atlassian account cannot view) sees the issue without it: no title, no
passage and no link.

In Claude or ChatGPT, the conversation becomes the source once it is saved, so
the assistant saves the chat first. Claude Code and Codex cite the session they
run in.

## Your trackers, your approval

Orchestra writes these changes the way you would, through the same path as any
issue change. With [write-back](https://docs.orchestrahq.ai/integrations-write-back.md) off, they stay in
Orchestra. With it on:

* **Status changes are approved by the team's setting.** When **Status from
  agents' work** is Automatic, moving an issue that is already in Jira or Linear to
  In Progress, In Review or Done is written there at once, with no click. The
  issue's history records it as approved by that setting.
* **Everything else still waits for your approval:** a new issue created in Jira
  or Linear, the end-of-session comment, any other field, and anything on a GitHub
  issue.

On Orchestra Local it is written with your own login, and none of the session's
content leaves your laptop.

Only issues you can see are matched, and only your own sessions are tracked from
your hooks.

## The team's status update

Each team's page shows a status update for the last day: issues done, in review,
started and created, and what the team's sessions concluded. Every line cites the
event it comes from, and it is computed for the person reading it, so a session or
issue you cannot see never appears in yours.

## Controls

On a team's page, a team admin or a workspace admin chooses, for **Issues from
agents' work** and **Status from agents' work**:

* **Automatic** (the default): as described above.
* **Propose**: new work is offered on the session's page for one click instead of
  created (issues only).
* **Off**: nothing happens for that team.
* **As the workspace**: follow the workspace's setting.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.