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 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.
If autoApprovePlans is enabled (the default), implementation starts automatically after planning. If disabled, a human must approve before implementation proceeds.
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

Gap analysis is posted to the PR

After the PR is opened, a second Claude pass runs automatically. This is the gap analysis: Claude reads the PR diff and the original ticket, then posts a structured comment to the PR with three sections:
  • Implemented — requirements from the ticket that are fully addressed in the diff
  • Gaps / Partial Implementation — requirements that are missing or only partially done
  • Manual Steps Required — human actions needed, such as setting environment variables, running migrations, or configuring external services
The gap analysis uses a lighter model by default (claude-haiku-4-5-20251001 on the Anthropic provider) to keep costs low. You can override this with the gap_analysis_model: field in WORKFLOW.md.
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 gap analysis 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 and reading the gap analysis, 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 comment-trigger.yml workflow picks it up.Claude checks out the existing branch, reads the same WORKFLOW.md template, and focuses on the gaps identified in the previous run. It pushes new commits to the same branch, and the gap analysis comment is updated automatically.
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 — and updates the gap analysis with what was newly addressed.
To make AI-Implement wait for an external review bot’s findings before running its own gap analysis (so both reviewers’ feedback get folded into one pass), configure the reviewProviders field in .ai-implement/config.yml.See Repo-level configuration file.

​
Status markers

Linear (label)Jira (status field value)When it’s used in the lifecycle
AI-ImplementReadyYou apply this marker to trigger a run. The orchestrator polls for these issues on each cycle.
AI-WorkingImplementingRun is active
Plan-CompletePlan ApprovedPlanning succeeded
Ready for ReviewPR ReadyPR is ready for review
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.