Customize pipeline behavior

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’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, followed by the repo-level config file.

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).

reference-repos

Clones the project’s configured reference repositories into the workspace before implementation. Skipped when no reference repositories are configured.

install-skills

Clones the project’s configured skills repository into the workspace for the agents selected across the run’s stages. Skipped automatically when the project has no skills repository set.Claude skills go to ~/.claude/skills; Codex skills go to ~/.agents/skills. This uses the trusted project skills repository, not a desktop client’s BuildDown plugin installation.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

Detects the package manager from the target repo’s lockfile — or from packageManager in .ai-implement/config.yml when set — and runs its frozen install:

npm ci
yarn install --frozen-lockfile
pnpm install --frozen-lockfile

A failing install does not stop the run. The step records the failure with the tail of the install output, the pipeline continues into setup and the agent run, and the agent is told that dependencies are missing.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.

install-retry

Runs the install a second time, reusing the package manager the first attempt detected. It runs only when the first install attempt failed, and it runs after the agent has finished — so a change the agent made to the lockfile can take effect on this attempt.It is skipped when the first install succeeded.A custom/steps/install.ts override runs for this second attempt too, since it reuses the same install module.

preflight

Runs the target repo’s own typecheck/lint/test package-manager scripts against the agent’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.It is also skipped when both dependency install attempts failed — its checks would fail for missing dependencies rather than for the change.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 the agent’s changes and pushes them to the target repository. On a new run, it opens a normal pull request when the feedback loop approved the change and dependencies installed. Otherwise, it opens a draft pull request for human review.On a gap-fill run, it commits and pushes an approved change to the existing pull request branch. It skips the push when the feedback loop did not approve.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
the feedback loop did not approve the change
both dependency install attempts failed

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.It is skipped when both dependency install attempts failed — an unverified run’s PR is left for a human rather than run through a review cycle.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 the implementation agent as fix instructions. 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.

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
reviewers:
  - id: security
    prompt: |
      Review the diff for injection, authentication, and secret-handling faults.
    model: claude-sonnet-5

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
none

When omitted, the install step auto-detects by lockfile presence: yarn.lock → yarn, pnpm-lock.yaml → pnpm, otherwise npm.none turns off the built-in install and its retry. Use a setup hook to install dependencies before the agent starts.A repo with no package.json skips installation entirely, so a non-Node project needs no setting here. A value outside the accepted values isn’t validated or rejected — it’s silently treated the same as omitting the setting, falling back to npm ci, so a typo goes unnoticed rather than failing the run.

string

Legacy model ID used for the implementation step. Overrides the model: value from WORKFLOW.md front matter for the implement step only.Configured projects use their implementation stage selection instead.

string

Legacy model ID used for the review step wrapped by feedback-loop. Configured projects use their review stage selection instead.

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 three 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.
Populated — the step waits, the same as omitting the field. Currently the only recognized value is github-claude-code-review (matches the Claude Code Review GitHub Action); unknown values are silently filtered out.

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.

array

Defines your own reviewers that run after AI-Implement opens the pull request, described in Reviewers.

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

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

​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

Repo-level configuration file

custom/providers/ — override a ticketing provider