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

Planning steps moved out of the custom-step pipeline. See the changelog for what changed and why.

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

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 push was skipped.

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 — up to maxIterations times (default 3) before reporting whatever the final state is.Inputs you can tune via your custom pipeline YAML:

reviewProviders?: string[] — review-provider IDs to consult (also settable per-repo via .ai-implement/config.yml)
reviewCheckNames?: string[] — GitHub Actions check-run names that identify external review (defaults to the Claude Code Review check)
reviewWaitPollMs?: number — poll interval while waiting for the external check (default 5000)
reviewWaitTimeoutMs?: number — total wait before failing closed (default 300000, i.e. 5 minutes)
maxIterations?: number — fix-and-push iteration cap (default 3)

Outputs: approved, iterations, finalFeedback, and forcePushedRevisions (count of revision pushes).

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: <StepType>
    moduleId: <registry-key>  # optional; defaults to type

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

packageManager

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.

models.implement

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.

models.review

string

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

reviewProviders

string[]

Opts the post-push-review step into waiting for and integrating findings from external GitHub Actions review checks on the same PR.Currently the only recognized value is github-claude-code-review (matches the Claude Code Review GitHub Action). Unknown values are silently filtered out.When omitted or empty, post-push-review runs its own analysis without coordinating with external reviewers.

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.

​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