Skip to main content
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/.
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).
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.
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.
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.
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.
Runs the target repo’s own typecheck/lint/test package-manager scripts against Claude’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.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.
Commits Claude’s changes, pushes the branch to the target repo, and opens the PR. Runs on every fresh implementation run — when the feedback-loop approved the diff it opens a normal PR, and when it didn’t it still opens a draft PR carrying the reviewer’s final feedback and per-pass stats. It’s skipped only on gap-fill re-runs, where Claude commits and pushes to the existing PR branch directly instead.Override to customize commit message format, branch naming, or PR body construction.
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.
Runs a merge-readiness code review of the PR — checking for bugs, missing requirements, and test gaps — and posts the findings as a PR comment.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 review 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 final comment is either “Approved”, or “Reached review cap” when the cap is hit without approval.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:
Here is the hello.ts example from custom/README.md:
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:
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:
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 — no other key is recognized. An inputs: key, for example, is parsed but silently ignored. A step whose id isn’t one of the built-ins above always receives an empty inputs object, so a genuinely new custom step must read whatever 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.
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. A value outside the three above 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
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/ — 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.