Add custom pipeline steps to AI-Implement

AI-Implement’s pipeline is extensible — you can override any built-in step or add new ones by placing TypeScript files in the custom/ directory. 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. There are two extension points: custom/steps/ for step modules and custom/pipelines/ for pipeline definitions.

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 runs two pipelines — an implementation pipeline and a planning pipeline. Only the implementation pipeline checks custom/steps/ for overrides at runtime. The six overridable IDs are: clone, install, feedback-loop, preflight, push, post-push-review.

Placing a file in custom/steps/ for any other step ID listed below has no effect. The planning pipeline steps (architecture-analysis, explore-codebase, test-plan, work-unit-decomposition, cross-story-context, post-to-ticketing) do not currently check for custom overrides — a matching file in custom/steps/ is silently ignored for those IDs.implement and review run as inner passes of the feedback-loop step and cannot be individually overridden. To change their behavior, override the feedback-loop step itself.

All step IDs are listed below for reference.

architecture-analysis

Runs Claude during the planning phase to produce the Architecture Analysis comment posted to the issue. Override to change the prompt, model, or how the analysis is shaped.

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

cross-story-context

Planning step that produces the Cross-Story Context comment when the issue has dependencies or sibling stories with meaningful coordination needs. Skipped automatically when no related issues exist.

explore-codebase

Read-only codebase exploration during the planning phase. Builds the context that feeds into the architecture analysis and test plan.

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.

implement

The main implementation Claude session. Reads the planning context and, when Work Units are present, appends instructions for Claude to use parallel subagents. The subagents run inside the single Claude session via the Task tool — not as separate processes — so AI-Implement can’t observe their individual progress.

install

Runs your repo-specific install/setup script(s) before Claude starts. Override to add cache management, dependency precompilation, or other setup not expressible as a setup: script in WORKFLOW.md.

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.

post-to-ticketing

Posts the four structured planning comments (Architecture Analysis, Test Plan, Work Units, Cross-Story Context) back to the ticketing system. Used by the planning workflow.

preflight

Pre-implementation checks — validates the workspace and expected tools before Claude starts on a fresh run.

push

Commits Claude’s changes, pushes the branch to the target repo, and opens the PR. Override to customize commit message format, branch naming, or PR body construction.

review

A code-review sub-step executed inside feedback-loop. Evaluates Claude’s diff against the issue requirements and returns an approval verdict plus an issues list that drives the loop’s next iteration. Distinct from the post-PR gap analysis (which is the post-push-review step) — review runs during the implementation loop to drive iteration; post-push-review runs after the PR is opened to report on completeness.

test-plan

Runs Claude during the planning phase to produce the Test Plan comment posted to the issue.

work-unit-decomposition

Runs Claude during the planning phase to produce the Work Units comment, splitting the issue into parallelizable subagent tasks. See AI planning phase for the downstream parallel-implementation behavior.

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
steps:
  - id: my-step
    type: custom
    moduleId: hello        # loads custom/steps/hello.js (or .ts in dev)
  - id: install
    type: install
  - id: feedback-loop
    type: feedback-loop
  - id: preflight
    type: preflight
  - id: push
    type: push

Step input wiring and skip predicates for the known built-in step IDs (install, feedback-loop, preflight, push) are applied automatically by the pipeline loader — your YAML only needs to declare id, type, and optional moduleId.

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

Add custom pipeline steps to AI-Implement

custom/steps/ — override or add a step

Built-in step IDs

custom/pipelines/ — override the pipeline definition

custom/providers/ — reserved

​custom/steps/ — override or add a step

​Built-in step IDs

​custom/pipelines/ — override the pipeline definition

​custom/providers/ — reserved

custom/steps/ — override or add a step

Built-in step IDs

custom/pipelines/ — override the pipeline definition

custom/providers/ — reserved