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

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.

install

Runs your repo-specific install/setup script(s) before Claude starts. Also reads .ai-implement/config.yml (when present) for repo-level packageManager, models, and reviewProviders settings.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

Pre-implementation checks — validates the workspace and expected tools before Claude starts on a fresh run. Automatically skipped when the feedback-loop did not approve the diff.

push

Commits Claude’s changes, pushes the branch to the target repo, and opens the PR. Automatically skipped when the feedback-loop did not approve the diff.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

Runs the gap analysis Claude pass after the PR is opened, comparing the diff to the ticket spec and posting the structured gap-analysis comment to the PR.Before the analysis 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 analysis 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.The one setting you can change without code is which external reviewers to wait for, via reviewProviders 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 eight values below>
    moduleId: <registry-key>  # defaults to type — a custom step needs its own module ID

The type: field accepts exactly eight 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
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 for the built-in step IDs (clone, install-skills, install, setup, feedback-loop, preflight, push, verify, post-push-review) are applied automatically by the pipeline loader.Your YAML only needs to declare id, type, and optional moduleId.

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.

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

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 repo with no package.json skips installation entirely, so a non-Node project needs no setting here. Any value outside the three above fails the run.

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 three cases each do something different:

Omitted — the step waits for an external review check and merges its findings in, auto-detecting checks named claude-review or claude code review.
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.

The file is read fresh at the start of every run, so changes take effect on the next dispatch without needing to restart the orchestrator.

custom/providers/ — reserved

The custom/providers/ directory is reserved for future provider overrides. It is not yet wired up to a stable interface.

Do not use custom/providers/ for production customizations — the interface is not yet stable and may change without notice.

Get Started

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/ — reserved

​custom/steps/ — override or add a step

​Built-in step IDs

​custom/pipelines/ — override the pipeline definition

​Repo-level configuration file

​custom/providers/ — reserved

custom/steps/ — override or add a step

Built-in step IDs

custom/pipelines/ — override the pipeline definition

Repo-level configuration file

custom/providers/ — reserved