> ## Documentation Index
> Fetch the complete documentation index at: https://docs.builddown.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Triggers and status indicators
> How AI-Implement triggers and tracks runs across Linear (labels) and Jira (status fields), what each marker means, and when each is applied automatically.
AI-Implement tracks runs using **Linear labels** or **Jira custom status fields**, depending on which ticketing system the team mapping uses. Some markers you apply yourself to kick things off; others are applied and removed automatically as a run progresses. Pick your ticketing system below; concurrency and the `/ai-implement` comment trigger work identically for both.
## Label overview
| Label | Applied by | When | Removed when |
| ------------------ | ------------------- | ---------------------------------------- | ------------------------------------------- |
| `AI-Implement` | You | When you want a run to start | Not removed automatically |
| `AI-Working` | Orchestrator (auto) | When a run is dispatched and in progress | When the run completes (success or failure) |
| `AI-Planning` | Orchestrator (auto) | While the planning phase is running | When planning completes |
| `Plan-Complete` | Workflow (auto) | When planning succeeds | Not removed automatically |
| `Ready for Review` | Workflow (auto) | When a PR is opened after implementation | Not removed automatically |
## Label details
### AI-Implement
You apply this label manually to any Linear issue you want AI-Implement to implement. The orchestrator polls for issues with this label every 60 seconds and dispatches a run for each one that is eligible.
An issue must be **unblocked** to be picked up. An issue is considered blocked if it has any open blocking issues linked to it in Linear. Blocked issues are skipped on each poll cycle until their blockers are resolved.
### AI-Working
The orchestrator applies `AI-Working` as soon as it dispatches a run for an issue. It acts as a live indicator that a run is in progress. The label is removed at the end of the run — whether the run succeeds, fails, or times out.
If `AI-Working` remains on an issue after a run should have finished, the run may have stalled. Check the dispatch log in the admin UI at `/api/log` and the active sessions panel. You can destroy a stuck session from the sessions panel, which also removes `AI-Working` and clears the issue from the dedup window.
### AI-Planning
When the planning phase is enabled for a team/repo mapping (the default), `AI-Planning` is applied while the planning workflow is running. It is removed when planning completes and execution moves to the implementation phase.
### Plan-Complete
`Plan-Complete` is applied when the planning phase finishes successfully. It is not removed automatically. You can use it to filter issues that have been planned but not yet implemented.
### Ready for Review
`Ready for Review` is applied by the implementation workflow after it opens a PR. At the same time, the workflow posts a comment on the Linear issue with a link to the PR. The label signals that the AI's work is ready for a human reviewer.
## Status field overview
Jira mappings track runs through a single custom **select field** named `AI-Implement Status`. The orchestrator sets one of the following values as a run progresses.
| Status value | Applied by | When | Changed when |
| ----------------------- | ------------------- | ----------------------------------------- | ------------------------------------------ |
| `Ready` | You | When you want a run to start | When the orchestrator dispatches the issue |
| `Planning` | Orchestrator (auto) | While the planning phase is running | When planning completes or fails |
| `Plan Approved` | Workflow (auto) | When planning succeeds | When implementation is dispatched |
| `Implementing` | Orchestrator (auto) | When the implementation run is dispatched | When the run completes or fails |
| `PR Ready` | Workflow (auto) | When a PR is opened after implementation | Not changed automatically |
| `Planning Failed` | Workflow (auto) | When the planning run errors | Not changed automatically |
| `Implementation Failed` | Workflow (auto) | When the implementation run errors | Not changed automatically |
A second custom field `AI-Implement Repo` is also required — its value scopes each issue to a target repo in the team mapping. Both fields must exist before the orchestrator can pick up issues; see [Jira manual setup](/setup/target-repo#jira-manual-custom-field-setup).
## Status details
### Ready
You set `AI-Implement Status` to `Ready` on any Jira issue you want AI-Implement to handle. The orchestrator polls every 60 seconds using the team mapping's JQL query (which filters to this status value) and dispatches a run for each eligible issue.
Unlike Linear, Jira has no built-in blocking semantics here — if you need to prevent a run from starting, gate it through your JQL or move the issue out of `Ready` manually.
### Planning / Plan Approved
The orchestrator sets `Planning` while the planning workflow is running, then transitions to `Plan Approved` on success. It is changed when planning completes and execution moves to the implementation phase.
### Implementing
Set automatically when the orchestrator dispatches the implementation run. It acts as a live indicator that a run is in progress.
If `Implementing` lingers on an issue after a run should have finished, the run may have stalled. Check the dispatch log in the admin UI and the active sessions panel; you can destroy a stuck session from there, which also clears the issue from the dedup window.
### PR Ready
Set by the implementation workflow after it opens a PR. At the same time, the workflow posts a comment on the Jira issue with a link to the PR. The status signals that the AI's work is ready for a human reviewer.
### Planning Failed / Implementation Failed
Set when the corresponding run errors out. The orchestrator posts a comment on the issue describing the failure. Neither status is cleared automatically — review the failure and either re-run by moving the status back to `Ready` (for planning) or `Plan Approved` (for implementation), or close out the issue.
## Concurrency
The `maxInProgressAiIssues` setting on each team/repo mapping controls how many issues a team mapping can have in flight (`AI-Working` in Linear, or `Implementing` in Jira) simultaneously. The default is `3`. The orchestrator counts in-progress issues before dispatching and skips teams that are at their limit.
You can change the concurrency cap for a team from the admin UI or by sending a `PATCH /api/mappings/:teamKey` request.
## /ai-implement comment trigger
Commenting `/ai-implement` on a PR that was opened by AI-Implement triggers a gap-fill run — no label or status field is needed. The comment must be exactly `/ai-implement` (no extra text) and must be posted by a collaborator with write access to the repo.
The gap-fill run checks out the existing PR branch, reviews the gap analysis comment, and pushes additional commits to address any gaps identified. The issue link and PR metadata are preserved from the original run.
The `/ai-implement` trigger requires `comment-trigger.yml` to be installed in the target repo. This file is synced automatically when you run the sync workflow.