Skip to main content
Experimental version.This is the latest in-development version of AI-Implement. Features may change without notice and behavior is not guaranteed. Switch to the latest stable version here.
AI-Implement connects Linear or Jira, your execution backend, and the selected coding agents through a small Node.js orchestrator. Configured projects can select Codex or Claude Code independently for planning, implementation, and review. Understanding how these pieces fit together helps you write better tickets, configure the service correctly, and know what to expect at each stage of a run.

​
The full lifecycle

Here is what happens from the moment you mark an issue (with the AI-Implement label in Linear, or AI-Implement Status = Ready in Jira) to when the PR is ready for your review.
1

Orchestrator polls for marked issues

The orchestrator polls your Linear workspace every 60 seconds (configurable via POLL_INTERVAL_MS). It looks for issues that have the AI-Implement label and are not blocked by any unresolved dependencies.
Per-project-mapping concurrency limits apply: by default, no more than 3 issues per mapping can be in progress at once. You can change this limit per mapping in the admin UI. If a mapping is at capacity, eligible issues wait until a slot opens.
Capacity is bucketed differently per provider:Linear groups by team key (all issues for a team share one cap, even across multiple project mappings that point at the same team).Jira groups by individual project mapping (each mapping has its own cap).
2

Issue is picked up and marked In Progress

When the orchestrator selects an issue, it marks it In Progress in Linear and adds the AI-Working label. The AI-Working label signals to your team that a run is active on this issue.
Two deduplication checks prevent duplicate dispatches:
  • In-flight — if a job is already actively running for this issue, no new dispatch happens regardless of how recent the last one was.
  • Recent — even after a job finishes, the same issue won’t be re-dispatched while a dedup entry from its previous dispatch is still on record.
A separate condition also stops a dispatch: an issue the dispatch breaker has parked after repeated failed dispatches is skipped until an operator unparks it.Any of these is enough to skip dispatch.
3

Planning phase (if enabled)

If planning is enabled for the project mapping (the default), the orchestrator dispatches a separate planning workflow (claude-plan.yml) before implementation begins.The selected planning agent reads the codebase in read-only mode, guided by your repo’s PLANNING.md template. The supplied template posts Implementation Map, Acceptance Bar, and Risks & Open Questions comments. Your repository owns the template, so its output can differ.See Planning for the output format and how the next stage consumes it.When the planning workflow finishes successfully, these comments appear on the issue and its marker is updated:
The AI-Planning label is removed and Plan-Complete is added.
Implementation starts automatically once planning succeeds. The project mapping’s autoApprovePlans field is reserved for a future manual-approval gate and does not currently change this.
Planning runs against your PLANNING.md template, which you can customize per repo. The planning output is injected into the implementation prompt so the implementation agent has that context when it starts writing code.
4

Implementation workflow is dispatched

The orchestrator dispatches the claude-implement.yml GitHub Actions workflow in your target repo using a workflow_dispatch event.The workflow receives the context needed to start:
  • Issue context — issue ID, identifier (e.g. ENG-123 for Linear, PROJ-456 for Jira), title, and description
  • Related-issue context — parent issue, sibling issues, and dependencies detected from ticketing-system relationships, when present
  • Stage selection — for configured projects, the resolved agent, provider, model, account profile, and elapsed timeout are frozen at dispatch
  • Run caps — the feedback-loop iteration cap and job timeout, plus Claude turn caps where relevant
  • Legacy provider routing — for projects that have not opted in, the Claude provider (anthropic or bedrock) and AWS region (Bedrock only)
  • Runner image override — a custom container image when the project has one configured
  • Callback credentials — a signed token the runner uses to report final results, plus a separate signed token for streaming step-progress updates back to the admin UI
Each field is included only when relevant — the AWS region is omitted on Anthropic mappings, run caps are omitted when not set on the mapping, and so on.
Execution backends include:
  • GitHub Actions (default) — runs the selected agent inside an ubuntu-latest job using the configured runner image.
  • Fly Machines — boots a dedicated Fly.io machine for the run, useful for repos that need more resources or a custom runtime environment.
Ordinary local Docker runs are also available for development. Managed configured review-fix support is narrower than this backend list; see Managed review-fix with Codex.
5

The selected agent implements the issue

The pipeline checks out the repository using the GitHub App token. The implementation agent reads WORKFLOW.md, receives any planning context, and changes the code. The pipeline runs its checks and review loop, commits and pushes the change, and opens a pull request titled IDENTIFIER: Title with a link to the originating issue.For an opted-in project, stage settings select the model and timeout. They take precedence over repository model settings. A legacy Claude project continues to use its repository front matter or per-repo model configuration.
You can add setup:, verify:, and teardown: script hooks in your WORKFLOW.md front matter to run custom scripts before and after the implementation pass — useful for installing project dependencies or running tests.
6

The pull request is reviewed again

Once the pull request is open, AI-Implement reviews it from the outside — reading the diff as pushed, commenting what it finds, and pushing fixes where it can.Every comment it leaves ends with a merge-readiness line:
  • Ready to merge. means a review pass found nothing left to fix.
  • Anything else means the pull request still needs someone to look at it, and Post-push review covers each of those cases.
7

Issue is updated to Ready for Review

Once the PR is open, the workflow posts a comment on the issue with a link to the PR, then updates the marker:
The Ready for Review label is added and the AI-Working label is removed.
Your team can now review the PR in GitHub, along with the review comments on it, and see the status change in your ticketing system — no context-switching required.
8

Gap-fill runs with /ai-implement

This step and the next both need a GitHub webhook pointed at your orchestrator, which serves them and polls for neither. On a repo synced to the current workflow templates, nothing else watches for an /ai-implement comment, and review feedback never starts a review-fix run without it.See GITHUB_WEBHOOK_SECRET for the setup.
After reviewing the PR, comment /ai-implement to start another pass on the same branch.Anything after the trigger becomes the run’s instruction and takes priority over its default brief. For example: /ai-implement also cover the error path with tests.With no added instruction, the run follows its configured gap-fill prompt. The supplied template asks the agent to address feedback and read relevant PR discussion as needed. A custom WORKFLOW.md can change that brief.The implementation agent works on the existing branch using the same WORKFLOW.md template. The pipeline pushes any new commits to that branch.You can also comment /ai-implement on a grouping roll-up PR — one whose branch is ai-implement/feature/<key> or ai-implement/multi-issue/<key>. See Feature-branch grouping.On any other PR with no AI-Implement run record, AI-Implement replies: “AI-Implement has no record of this PR. Please trigger a new implementation run from the issue tracker first.”
Gap-fill runs do not create new PRs or new branches. All work goes onto the existing PR branch, keeping your review history clean.
9

Late review feedback handling

Like the previous step, this runs on the orchestrator’s GitHub webhook and has no polling fallback.
After the PR is open, reviewers — your teammates or other bots like Claude Code Review — may leave feedback that needs another pass from the implementation agent. AI-Implement turns that feedback into a review-fix run on the same PR. It does not need a manual /ai-implement comment.AI-Implement writes to one PR with one run at a time. An issue that already has an open PR always goes to a review-fix run on that PR, so AI-Implement never implements the issue a second time.A project on the Claude Code Review, repository auto-fix review process is the exception for Claude’s findings: the repository’s own auto-fix fixes them, and AI-Implement does not start a review-fix run. See Repository auto-fix.The orchestrator listens to three kinds of GitHub events on the PR:
  • Pull request reviews with a Request changes verdict
  • Inline review comments on specific lines of the diff
  • Issue comments on the PR containing actionable feedback
AI-Implement deduplicates each new piece of feedback against what earlier passes already addressed. It then queues a review-fix run that pushes to the same PR branch — no new PRs or branches.Bot feedback must come from an author trusted by the project’s review process. See Trusted Review Authors.This table lists what AI-Implement does for each situation:A review-fix run does not start a new post-push review. See Post-push review.If a person pushes to the PR branch while a run is active, the run stops without pushing and posts: “A human pushed to this branch while AI-Implement was running, so the run stopped without pushing. Comment /ai-implement to resume.”If a bot pushes while a run is active, AI-Implement queues a new review-fix run by itself.A fixing agent can defer a finding that asks for work outside the issue’s requirements. AI-Implement lists that work on the issue for you to triage. See Finding dispositions.
To make AI-Implement wait for an external review bot’s findings before running its own review (so both reviewers’ feedback get folded into one pass), configure the reviewProviders field in .ai-implement/config.yml.See Repo-level configuration file.
10

PR merges and the issue is marked done

When someone merges the pull request, the orchestrator closes the loop itself — no ticketing-system automation needed on your side.
The issue moves to your team’s Done state and the Ready for Review label is removed.
A merge is picked up on the next poll. This bookkeeping runs even for a paused project, so pausing stops new work without stranding issues whose pull requests you merge afterwards.
This is the lifecycle for a single issue. When a parent issue and its children are marked together, the children’s pull requests target a shared branch instead of your default branch, and the whole tree lands as one pull request at the end — see Feature-branch grouping.

​
Status markers

See Triggers and status indicators for the full lifecycle reference, including planning/implementation failure markers.

​
Verify the agent and result

After a run, open Reports in the admin UI and find the issue under Agent attribution. Read Stage, Agent / provider / model, Profile / auth, and Outcome together. This is observed invocation evidence; the saved Agents values only show configuration. The card shows the latest invocation per job. Its usage and cost are not totals for every planning, implementation, and review invocation. unavailable means the cost was not reported, and partial cost is incomplete. Neither should be read as a zero-dollar total. No attribution (legacy) means no managed attribution was recorded. On the PR, check the Generated with AI-Implement footer for the implementation harness, model, and provider. Then read the test plan, the Full reviewer report, and the current merge-readiness status. A successful invocation or a PR link alone does not establish that checks passed or the review approved. See Post-push review for the result states. For a local Codex run, inspect the artifacts described in Local harness.

​
Authentication options

Configured projects use a managed account profile for each stage. For Codex, add an OpenAI API key or connect your own ChatGPT plan, then set stage defaults and opt the project in. An all-Codex configured project does not need an Anthropic repository secret.

​
Legacy Claude authentication

Projects that have not opted in retain these authentication paths, selected in order of precedence:
  1. AWS Bedrock — when the orchestrator dispatches with provider=bedrock, the workflow uses OIDC to assume an IAM role and calls Claude via Bedrock. Requires AWS_BEDROCK_ROLE_ARN as a repo secret and a model: set in WORKFLOW.md (there is no safe Bedrock default).
  2. Claude Code OAuth token — when CLAUDE_CODE_OAUTH_TOKEN is set as a repo or org secret, it takes precedence over an API key.
  3. Anthropic API key — the fallback when neither Bedrock nor OAuth is configured. Set ANTHROPIC_API_KEY as a repo or org secret.
See Providers and AWS Bedrock for setup details.