Skip to main content
AI-Implement connects three systems — Linear or Jira, GitHub Actions, and Claude Code — through a small Node.js orchestrator. 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.
A concurrency limit applies: by default, no more than 3 issues can be in progress at once. You set the limit per mapping in the admin UI, and 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 adds the AI-Working label, which signals to your team that a run is active on this issue. It also moves the issue to In Progress, unless you have already started it yourself.
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.
  • Already dispatched — 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, and labels the issue AI-Planning while it runs.Claude reads the codebase in read-only mode, guided by your repo’s PLANNING.md template, then posts structured comments to the issue:
  • Implementation Map — the approach, the files it expects to create, modify, test or delete, and the constraints an implementer must not break.
  • Acceptance Bar — numbered claims that can be checked against the diff, or by running a command.
  • Risks & Open Questions — edge cases and unknowns found while exploring the codebase.
Each lands on the issue for you to read. The orchestrator also reads the Acceptance Bar, which the review pass checks the diff against, and the Implementation Map’s file list, which is what holds back a sibling issue whose work would overlap.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 Claude has full 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 a payload with everything Claude needs 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
  • Run caps — Claude turn cap, implement/review iteration cap, GitHub Actions job timeout — each forwarded only when set on the project mapping
  • Provider routing — 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.
Two execution modes are supported, configured per project mapping in the admin UI:
  • GitHub Actions (default) — runs Claude Code inside a standard ubuntu-latest runner.
  • Fly Machines — boots a dedicated Fly.io machine for the run, useful for repos that need more resources or a custom runtime environment.
5

Claude checks out the repo and implements the issue

Inside the GitHub Actions runner, Claude Code:
  1. Checks out the repo using the GitHub App token.
  2. Reads WORKFLOW.md (your per-repo implementation prompt template) for instructions.
  3. Reads any planning context fetched from the issue comments.
  4. Implements the issue — creating a branch, writing code, and committing changes.
  5. Opens a pull request with the title IDENTIFIER: Title (e.g. ENG-123: Add user export for Linear, PROJ-456: Add user export for Jira) and a body that links back to the originating issue.
Claude uses the model specified in your WORKFLOW.md front matter. The default for new repos is claude-sonnet-4-6. You can override this per repo by editing the model: field in WORKFLOW.md.
You can add setup:, verify:, and teardown: script hooks in your WORKFLOW.md front matter to run custom scripts before and after the Claude pass — useful for installing project dependencies or running tests.
6

The pull request is reviewed

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 follow-up run without it.See GITHUB_WEBHOOK_SECRET for the setup.
After reviewing the PR, you can send Claude back in for another pass without starting a new run. Comment /ai-implement on the PR (in any PR comment), and the orchestrator picks it up.Anything you write after the trigger becomes the brief for that run, as in /ai-implement also cover the error path with tests. Leave it bare and Claude works from the original issue alone.Claude checks out the existing branch, reads the same WORKFLOW.md template, and pushes new commits to the same branch.
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

After the PR is open, reviewers — your teammates or other bots like Claude Code Review — may leave blocking feedback that needs another pass from Claude. AI-Implement watches for this and re-runs Claude automatically; no manual /ai-implement comment needed.The orchestrator listens to three kinds of GitHub events on the PR:
  • Pull request reviews with a Request changes verdict or blocking feedback in the body
  • Inline review comments on specific lines of the diff
  • Issue comments on the PR containing actionable feedback
Each new piece of feedback is deduplicated against what Claude already addressed in earlier passes, then queued for the next follow-up run. The run pushes to the same PR branch — no new PRs or branches.
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.

​
Authentication options

The workflow supports three authentication paths for Claude, 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.