> ## Documentation Index
> Fetch the complete documentation index at: https://docs.builddown.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add custom pipeline steps to AI-Implement

> How to override built-in pipeline steps or add entirely new ones by placing TypeScript modules in the custom/steps/ directory of your AI-Implement installation.

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

<Info>
  Overrides are discovered at startup by **filename match** — there is no plugin manifest or registration call.
</Info>

### 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`.

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

All step IDs are listed below for reference.

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="explore-codebase">
    Read-only codebase exploration during the planning phase. Builds the context that feeds into the architecture analysis and test plan.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="preflight">
    Pre-implementation checks — validates the workspace and expected tools before Claude starts on a fresh run.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="test-plan">
    Runs Claude during the planning phase to produce the **Test Plan** comment posted to the issue.
  </Accordion>

  <Accordion title="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](/configuration/planning) for the downstream parallel-implementation behavior.
  </Accordion>
</AccordionGroup>

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

```typescript theme={null}
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`:

```typescript theme={null}
// 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;
```

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

## 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:

```yaml theme={null}
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:

```yaml theme={null}
# 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
```

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

## custom/providers/ — reserved

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

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