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.
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 within a 24-hour window of its previous dispatch.
Either condition 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.Claude reads the codebase in read-only mode, guided by your repo’s PLANNING.md template. It then posts up to four structured comments to the issue:
  • Architecture Analysis — how the codebase is structured and what changes are needed
  • Test Plan — what tests should be written or updated
  • Work Units — a breakdown of the issue into smaller pieces, separated into ones that can be implemented in parallel and ones that must come after.
  • Cross-Story Context — relevant context from related issues (if available)
When the Work Units section is present, the implementation phase spins up multiple Claude subagents in parallel — each scoped to a specific set of files — so independent chunks land at the same time instead of one after another. Skipped when the issue is too small or too tightly coupled to decompose, in which case implementation runs as a single pass.
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

Automated review is posted to the PR

After the PR is opened, a second Claude pass runs automatically, reviewing the diff for merge readiness — bugs, missing requirements, unsafe behavior, and test gaps. If it finds blocking issues, it has Claude fix them and reviews again, up to 3 passes by default (2 for Bedrock); if it approves, it posts an ”✅ Approved” comment and a native GitHub PR review.See Post-push review for the full comment sequence and what happens if the iteration cap is reached without approval.
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 and the automated review comments in GitHub, and see the status change in your ticketing system — no context-switching required.
8

Gap-fill runs with /ai-implement

After reviewing the PR, you can send Claude back in for another pass without starting a new run. Comment on the PR with something starting with /ai-implement. On a repo synced to the current workflow templates, the orchestrator’s own webhook picks up the comment directly — this needs the GitHub App’s webhook configured and subscribed to PR-comment events (see GITHUB_WEBHOOK_SECRET); there’s no other path that watches for this comment on such a repo.Claude checks out the existing branch, reads the same WORKFLOW.md template, and focuses on the feedback from the previous pass. It pushes new commits to the same branch, and the automated review runs again against the updated diff.
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

This requires a GitHub webhook pointed at your orchestrator. Unlike the rest of the lifecycle, there’s no polling fallback here — without a webhook configured, blocking review feedback is never picked up and no follow-up run happens.See GITHUB_WEBHOOK_SECRET for the setup.
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 — and the automated review runs again to reflect what was newly addressed.
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.