Customize pipeline behavior

AI-Implement’s pipeline is configurable in two complementary ways:

Code-level overrides — drop TypeScript files in the custom/ directory of your AI-Implement installation to replace a built-in step’s behavior or define your own pipeline. Files in custom/ take precedence over the corresponding built-ins, and upstream updates never overwrite them (the only exception is custom/README.md, which may be updated with documentation changes). Your customizations are safe across upgrades.
Repo-level configuration — drop a YAML file at .ai-implement/config.yml in your target repo to tune step parameters (package manager, model IDs, external reviewer integration) without writing any code.

The custom/ mechanism has two extension points:

custom/steps/ for step modules
custom/pipelines/ for pipeline definitions.

Both are covered below.

custom/steps/ — override or add a step

You can either replace a built-in step or introduce an entirely new one by dropping a TypeScript file in custom/steps/.

To override a built-in step, create a file named after its step ID — for example, custom/steps/install.ts replaces the built-in install step.
To add a new step, give the file a name that doesn’t match any built-in ID and reference it from a custom pipeline (see below).

Overrides are discovered at startup by filename match — there is no plugin manifest or registration call.

Built-in step IDs

The orchestrator pipelines reference these step IDs. Any of them can be overridden by placing a matching file in custom/steps/.

clone

Clones the target repo into the workspace at the start of an implementation run.Override if you need custom checkout logic (e.g. shallow clones, submodule init).

install-skills

Clones the project’s configured skills repository into the workspace so Claude can use its skills during the run. Skipped automatically when the project has no skills repository set.Override to change how skills are fetched — for example to pull from a private mirror, or to filter which skills are made available.

dependency-auth

Mints a short-lived, read-only access token during the run and registers it as a git credential helper, so ordinary dependency fetches against private sibling repositories succeed without any per-repository setup.The step does nothing unless the project’s dependency-token scope is turned on — the first thing to rule out when a private dependency fetch fails.It also no-ops silently, without failing the run, when the run has no callback URL to request the token from, or no progress token to authenticate the request.

install

Runs your repo-specific install/setup script(s) before Claude starts. Also reads .ai-implement/config.yml (when present) for the repo-level settings documented below.Override to add cache management, dependency precompilation, or other setup not expressible as a setup: script in WORKFLOW.md.

setup

Runs the setup: shell script declared in your repo’s WORKFLOW.md front matter, if any. The script runs before the implement loop with set -euo pipefail; a non-zero exit aborts the run early. Automatically skipped when setup: is not declared.Override to do pre-flight work in TypeScript instead of shell.

feedback-loop

Wraps the implementation loop — runs implement → review and iterates until the review approves the diff or the iteration cap is hit. Common override target for adjusting iteration limits, custom acceptance criteria, or swapping the review model.The implement and review sub-steps run inside this loop and are not separately overridable as top-level pipeline steps; overriding feedback-loop is the way to change either of them.

preflight

Runs the target repo’s own typecheck/lint/test package-manager scripts against Claude’s finished diff, immediately before push. Automatically skipped when the feedback-loop did not approve the diff — so it validates a reviewer-approved change, not the pre-implementation workspace.A failing preflight check does not block push; the diff is pushed either way. Override to make preflight failures blocking, or to run additional checks.

push

Commits Claude’s changes, pushes the branch to the target repo, and opens the PR. Runs on every fresh implementation run — when the feedback-loop approved the diff it opens a normal PR, and when it didn’t it still opens a draft PR carrying the reviewer’s final feedback and per-pass stats. It’s skipped only on gap-fill re-runs, where Claude commits and pushes to the existing PR branch directly instead.Override to customize commit message format, branch naming, or PR body construction.

verify

Runs the verify: shell script declared in your repo’s WORKFLOW.md front matter, if any. Runs after a successful push, with set -euo pipefail. Automatically skipped when verify: is not declared, or when the feedback loop did not approve the change.

The matching teardown: script (also declared in WORKFLOW.md) is handled by the runner inside a finally block — it always executes, even on failure, and is not a pipeline step you can override here.

post-push-review

Reviews the pull request after it is opened — reading the diff, posting what it finds, and running fix passes that force-push corrections to the branch.Before the review runs, the step waits for any configured external review provider (such as a claude-review.yml GitHub Action posting its own findings) to finish. Both the external reviewer’s blocking issues and the step’s own findings are then deduped and fed back to Claude as iteration prompts. If blocking issues remain after a pass, the step force-pushes the revision and runs another review pass.It runs up to three review passes by default, which force-push at most two revised versions: on the third pass the step reports that it reached the review cap rather than force-pushing again. Post-push review covers the comments it leaves and how each outcome reads.Without code, you can change which external reviewers to wait for and which check-run names the step matches, both in .ai-implement/config.yml. The iteration cap and the external-review wait timings are built in; change them by overriding this step.

Every step file must export a StepModule as its default export:

export interface StepModule<
  I extends Record<string, unknown> = Record<string, unknown>,
  O extends Record<string, unknown> = Record<string, unknown>,
> {
  run(context: PipelineContext, inputs: I, reporter: StepReporter): Promise<O>;
}

Here is the hello.ts example from custom/README.md:

// custom/steps/hello.ts
import type { StepModule } from "../../src/pipeline/types.js";

export default {
  async run(_context, _inputs, _reporter) {
    return { message: "hello from custom step" };
  },
} satisfies StepModule;

A file in custom/steps/ that exists but has no default export produces a warning at runtime and falls back to the built-in rather than silently misbehaving.

custom/pipelines/ — override the pipeline definition

You can override the built-in autonomous loop pipeline by creating custom/pipelines/autonomous.yml. This replaces the built-in pipeline YAML entirely. Pipeline YAML follows this schema:

id: <pipeline-id>
steps:
  - id: <step-id>
    type: <one of the values below>
    moduleId: <registry-key>  # defaults to type — a custom step needs its own module ID

The type: field accepts only these values — anything else fails to load:

clone
install
implement
review
preflight
push
await_ci
custom

Several built-in steps are not types of their own:

setup
feedback-loop
install-skills
dependency-auth
verify
post-push-review

Each runs as type: custom with a moduleId naming the module.Writing any of them as a type — type: verify — fails to load, because these names are module IDs, not step types.

The moduleId field is what connects a pipeline step to your custom step module. When moduleId is set, the runner looks for custom/steps/<moduleId>.js (or .ts in development). When omitted, it defaults to the value of type. Here is an example that adds a custom step to the pipeline:

# custom/pipelines/autonomous.yml
id: autonomous-loop
steps:
  - id: my-step
    type: custom
    moduleId: hello        # loads custom/steps/hello.js (or .ts in dev)
  - id: clone
    type: clone
  - id: install
    type: install
  - id: feedback-loop
    type: custom
    moduleId: feedback-loop
  - id: preflight
    type: preflight
  - id: push
    type: push
  - id: post-push-review
    type: custom
    moduleId: post-push-review

Step input wiring and skip predicates are applied automatically by the pipeline loader for every built-in step ID.

Your YAML only needs to declare id, type, and optional moduleId. No other key is recognized, and an inputs: key is parsed but silently ignored. A step whose id isn’t one of the built-ins always receives an empty inputs object, so a genuinely new custom step must read what it needs from the pipeline’s shared context data rather than from step-level YAML config.

Profiles

Profiles come from a Jira custom field. A run dispatched from a Linear issue never carries any.

A run can carry a list of profile names. No built-in step reads them — they exist so your own steps can branch on the issue that started the run. Where they come from depends on how the run started:

From the ticket — the AI-Implement Profiles multi-select field, whose selected options become the names, spelled exactly as they appear there. Jira: manual custom-field setup covers creating the field.
From a task file — the profiles key, which works whichever ticketing provider you use, since nothing reads a ticket.

A step reads them from the pipeline’s shared context data:

// custom/steps/provision-database.ts
import type { StepModule } from "../../src/pipeline/types.js";

export default {
  async run(context, _inputs, _reporter) {
    if (!context.data.profiles?.includes("backend")) {
      return { provisioned: false };
    }
    // …stand up a throwaway database for this run
    return { provisioned: true };
  },
} satisfies StepModule;

A step guarded on a profile does nothing until that profile is set on an issue, so it is safe to write and deploy before anyone uses it.

Repo-level configuration file

Drop a YAML file at .ai-implement/config.yml in your target repo’s root to override certain runtime behaviors without modifying WORKFLOW.md or any synced workflow files. The orchestrator’s install step reads this file at the start of every run.

Changes take effect on the next dispatch, with no orchestrator restart needed.

packageManager: pnpm
models:
  implement: claude-opus-4-8
  review: claude-sonnet-4-6
reviewProviders:
  - github-claude-code-review
reviewCheckNames:
  - claude-review
  - my-org-review-bot

All fields are optional. The file may also be absent entirely — when it is, the install step falls back to its built-in defaults.

string

default:"auto-detected"

Forces a specific package manager for the install step.Accepted values:

npm
yarn
pnpm

When omitted, the install step auto-detects by lockfile presence: yarn.lock → yarn, pnpm-lock.yaml → pnpm, otherwise npm. A value outside the three above is neither validated nor rejected — it runs npm ci whichever lockfile is present, so a typo quietly costs you the auto-detection rather than failing the run.A repo with no package.json skips installation entirely, so a non-Node project needs no setting here.

none is the one value that fails the run. It reads as a way to skip installation, but on a repo that has a package.json it aborts the install step instead.

string

Model ID used for the implementation step. Overrides the model: value from WORKFLOW.md front matter for the implement step only.Useful when you want a heavier model for implementation and a lighter one for review.

string

Model ID used for the review step wrapped by feedback-loop. Same override semantics as models.implement.

string[]

Controls whether the post-push-review step waits for an external GitHub Actions review check on the same PR and folds its findings into its own review.This is opt-out: external coordination is on by default, and supplying an empty list is how you turn it off. The cases each do something different:

Omitted — the step waits for an external review check and merges its findings in, auto-detecting the check by name (see reviewCheckNames for the names recognized by default and how to override them).
Empty list — the step skips the external wait entirely and runs only its own review.
Includes github-claude-code-review — the step waits, the same as omitting the field. This is the only recognized value, and it matches the Claude Code Review GitHub Action. Unknown entries beside it are silently ignored.
Only unknown entries — the step skips the external wait, the same as an empty list. A misspelled github-claude-code-review turns the wait off without any warning.

string[]

Sets which external review check runs the post-push-review step waits for, by check-run name.Set it when your external review bot posts under a name the step doesn’t recognize by default — findings from an unrecognized check are never folded in.When omitted or left empty, the step uses its built-in defaults, recognizing these check-run names:

review
code-review-plugin
claude-review
claude code review
claude-code-review

It also matches any other check whose name contains both claude and review, catching most naming variants without configuration.

A list here replaces the defaults rather than extending them, and matching becomes exact — the claude-and-review heuristic stops applying.Any check you leave off silently stops being matched, so list every one you rely on.

custom/providers/ — override a ticketing provider

Drop a TypeScript file at custom/providers/<id>.ts to replace the built-in Linear or Jira provider for that ID — same override mechanism and precedence as custom/steps/. The file’s default export is used in place of the built-in provider whenever one is found.

The exported factory’s interface shape may still change in a future release without notice, so treat a custom provider as something you’ll need to revisit on upgrades.

Get Started

Setup

Optional setup

Configuration

Providers

Customize

Reference

Customize pipeline behavior

custom/steps/ — override or add a step

Built-in step IDs

custom/pipelines/ — override the pipeline definition

Profiles

Repo-level configuration file

custom/providers/ — override a ticketing provider

​custom/steps/ — override or add a step

​Built-in step IDs

​custom/pipelines/ — override the pipeline definition

​Profiles

​Repo-level configuration file

​custom/providers/ — override a ticketing provider

custom/steps/ — override or add a step

Built-in step IDs

custom/pipelines/ — override the pipeline definition

Profiles

Repo-level configuration file

custom/providers/ — override a ticketing provider