latest version. Each entry has its own anchor link — pages elsewhere in this version may link you directly to a relevant entry below. Use the version dropdown at the top of the page to switch back to the stable docs.
claude-plan.yml no longer contains Linear-specific code paths. Planning context (parent issue, sibling issues, dependencies) arrives as workflow_dispatch inputs, fetched by the orchestrator from whichever ticketing system the project mapping uses.No operator action needed — same workflow file serves Linear and Jira mappings, with the orchestrator handling the provider-specific fetching upstream.Third-party GitHub Actions used by
claude-implement.yml, claude-plan.yml, and comment-trigger.yml are now pinned to specific commit SHAs rather than version tags. Supply-chain hardening — pinned actions don’t auto-update when their maintainers publish a new release.Trade-off: pinned actions need manual SHA bumps to receive upstream bug fixes or security patches. The AI-Implement team handles those on the upstream workflow templates; running sync-workflow.yml in your target repo propagates the updates.The synced
claude-implement.yml now calls ::add-mask:: on run_token and run_progress_token before the runner uses them. If either token accidentally surfaces in workflow output (a script logging an env var, an error trace, etc.), GitHub displays it as *** instead of the literal value.No operator action needed.Project mappings now carry three optional run-cap fields configurable per-mapping in the admin UI’s Projects panel:
maxTurns— cap on Claude turns per implement pass (default50)maxIterations— cap on implement/review cycles (default3Anthropic,2Bedrock)maxJobMinutes— cap on GitHub Actions job timeout in minutes (default90)
workflow_dispatch input on orchestrator-initiated runs. The same caps are configurable as target-repo variables (AI_IMPLEMENT_MAX_*) for /ai-implement comment-triggered gap-fill runs — same defaults apply to both paths.See Project mappings for the schema reference.The built-in default runner image in synced
claude-implement.yml is now ghcr.io/builddownai/ai-implement-runner:latest (previously :next).This is the fallback used only when no override mechanism is in play. The following all take precedence:.ai-implement/image.ymlSESSION_IMAGEon the orchestratorAI_IMPLEMENT_RUNNER_IMAGEon the target repo
:next-channel code, set SESSION_IMAGE=ghcr.io/builddownai/ai-implement-runner:next on the orchestrator. Otherwise repos without other overrides will silently dispatch on :latest images (production-stable runner code) while the orchestrator runs testing-branch logic — a mismatch you generally want to avoid.A new
AI_IMPLEMENT_RUNNER_IMAGE target-repo (or org-level) variable lets you override the runner image for GitHub Actions execution mode without committing .ai-implement/image.yml to each repo. Useful for setting an organization-wide default across many repos at once.Resolution order on a GHA dispatch (highest precedence to lowest):- Orchestrator-forwarded image (from
.ai-implement/image.ymlorSESSION_IMAGE) AI_IMPLEMENT_RUNNER_IMAGE- The workflow’s built-in default
A new
POST /runner/progress endpoint accepts step-by-step progress updates from active runner sessions. Unlike the existing POST /runner/result (single-use, fires at the end of a dispatch), the progress token is multi-use so a single runner can post many updates throughout its run.This is what powers live step-status updates in the admin UI — previously the UI only learned about a run when the runner completed and posted its final result.Both runner-callback endpoints respond 501 when the orchestrator has no RUNNER_TOKEN_SECRET configured. Reference: Runner callback endpoints.A new internal
step_log table records each pipeline step’s status, start/end times, and any structured output. This is what POST /runner/progress writes into and what the admin UI’s per-job step view reads from.Operational caveat: the table has no automatic TTL or cleanup mechanism yet — it grows unbounded as dispatches accumulate. For high-volume orchestrators this may eventually need manual pruning or a future retention policy. No operator action needed today.The
dispatch_log table now carries a dispatch_id column with an index. This lets the orchestrator correlate audit-log entries with the runner results they produced and unifies the path back from a runner/result callback to the dispatch that triggered it.Internal tracking — not surfaced in the admin UI today. From an operator’s perspective, no visible change.A new
stuck_attempts table records how many times the orchestrator has retried dispatching each issue, supporting the AII-116 stuck-issue detection work. The orchestrator increments per attempt and clears the row when an issue dispatches successfully.Not surfaced in the admin UI today; the data is used internally for stuck-issue surfacing logic.When reviewers leave blocking feedback on an open PR — as a PR review verdict, inline review comments, or issue comments containing actionable feedback — AI-Implement now detects it via GitHub webhooks and queues a follow-up Claude run automatically. No manual
/ai-implement comment needed.The orchestrator listens to three GitHub event types 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
The
workflow_dispatch payload the orchestrator sends to claude-implement.yml now carries substantially more context than before. New field categories:- Related-issue context — parent issue, sibling issues, and dependencies detected from ticketing-system relationships
- 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 (
anthropicorbedrock) 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
claude-implement.yml that doesn’t accept the new workflow_dispatch inputs, you’ll get “unexpected inputs” rejection on dispatch. Re-sync from the orchestrator to pick them up.Where this fits in the lifecycle: How AI-Implement works.The orchestrator now skips dispatching an issue if a job for that issue is already actively running, in addition to the existing 24-hour recent-dispatch dedup.Operationally invisible most of the time — but useful when you’re debugging “why won’t my issue dispatch?” and the answer is “because the previous attempt is still running.”
GitHub Actions workflows in target repos no longer call Linear’s API directly. All label and status transitions now happen from the orchestrator via a provider abstraction (which also unlocked Jira parity).From an operator’s perspective the labels still update the same way; the change is internal. AI-Implement developers cross-referencing: the new flow goes through
runner-callback.ts → provider.markPlanComplete() and similar methods.The runner-to-orchestrator authentication token now comes in two flavors: a one-time-use
result token for posting the final dispatch outcome, and a multi-use progress token for streaming step-by-step progress updates back to the admin UI.Internal plumbing — no operator action needed. Supports live admin-UI streaming while keeping result callbacks single-use.GitHub
pull_request.synchronize webhook events (fired whenever commits push to a PR) are now acknowledged with a 200 OK and no further processing. Synchronize alone doesn’t trigger a new Claude pass — use a blocking review comment or /ai-implement for that..ai-implement/config.yml now accepts a reviewProviders field that opts the post-push-review step into waiting for and integrating findings from external GitHub Actions review checks. Currently github-claude-code-review is the only recognized value; unknown providers are silently filtered out.The orchestrator’s parser for this file was also upgraded internally — quoted YAML values and other standard YAML syntax now work correctly (previously some quoted values were silently misinterpreted). See Repo-level configuration file for the full field reference.ORCHESTRATOR_URL is no longer something you configure on the orchestrator. Its role is now covered by RUNNER_CALLBACK_BASE_URL, which the orchestrator uses both as the runner-callback target and as the URL stamped into dispatch metadata.If you have ORCHESTRATOR_URL set in your orchestrator’s .env or Fly secrets: you can remove it — the orchestrator no longer reads it at startup. Leaving it set causes no harm.Three new repository variables cap
/ai-implement comment-triggered gap-fill runs, mirroring the per-project caps that already gate orchestrator-initiated runs in the admin UI:AI_IMPLEMENT_MAX_TURNS— cap on Claude turns per implement pass (default50)AI_IMPLEMENT_MAX_ITERATIONS— cap on implement/review cycles (default3Anthropic,2Bedrock)AI_IMPLEMENT_MAX_JOB_MINUTES— cap on GitHub Actions job timeout in minutes (default90)
Planning steps have moved out of the customizable autonomous pipeline. Planning now runs as a separate workflow (
claude-plan.yml) with its own executor — synced to your target repo alongside claude-implement.yml.Step IDs no longer overridable as pipeline steps:architecture-analysistest-planwork-unit-decompositioncross-story-contextpost-to-ticketingexplore-codebase
StepType enum, so custom pipeline YAMLs that referenced any of them as type: values will fail to load on this version.What’s still overridable: the implementation-loop steps — clone, install, setup, feedback-loop, preflight, push, verify, post-push-review. See Custom pipeline steps for the full list and their descriptions.If you previously overrode a planning step (for example, a custom architecture-analysis.ts), the override is dead code on this version. Customizing planning behavior means modifying the planning workflow itself in your target repo, not dropping a file in custom/steps/.The
post-push-review step (the gap-analysis Claude pass that runs after the PR is opened) now coordinates with external review providers — such as a Claude Code Review GitHub Action running on the same PR — instead of racing them.New behavior:- Before running its gap analysis, the step waits for any configured external review check to finish (default timeout: 5 minutes, then fails closed).
- External reviewer findings are deduplicated against Claude’s own analysis and folded into the iteration prompt.
- If blocking issues remain after a pass, the step force-pushes the revision and runs another review pass — up to
maxIterationstimes (default3).
.ai-implement/config.yml):reviewProviders— review-provider IDs to consultreviewCheckNames— GitHub Actions check-run names that identify external reviewreviewWaitPollMs— poll interval while waiting (default5000)reviewWaitTimeoutMs— total wait before failing closed (default300000)
post-push-review on the Custom pipeline steps page for the full input table.