ai-pipeline-kit

A model-agnostic, multi-station AI delivery pipeline, scaffolded into your frontend project — framework-agnostic across React, Vue, Svelte, Angular, Astro, or plain HTML/CSS/JS.

It walks a ticket/issue through: intake → architect → sdet → developer → qa → classifier → specialists (security / performance / accessibility / visual) → reviewer → release, gated by schema validation, test-integrity hashing, and a push-gate — with a human confirmation required before anything is ever pushed.

This repo is a scaffolder, not a library. Running it copies editable files into your project (similar to shadcn/ui's add command) rather than installing a hidden dependency — the pipeline becomes part of your codebase, under version control, and you're expected to read and adapt it.

Usage

npx ai-pipeline-kit init

This copies the template/ files into ./pipeline in your current project:

pipeline/
├── pipeline.config.json     # which agentic CLI runs each station
├── orchestrator.mjs         # sequences stations, enforces gates/retries
├── runner.mjs                # invokes the configured CLI per station
├── paths.mjs                 # repo-root/pipeline-dir resolution (git-based)
├── classify-diff.mjs         # deterministic diff classifier (no model call)
├── validate-handoff.mjs      # schema gate between stations
├── verify-test-integrity.mjs # hash-locks SDET's test files
├── push-gate.mjs              # last check before push
├── git-host.mjs                # GitHub/GitLab PR/MR opening, auto-detected
└── prompts/                    # one prompt per station

Configuring at install time

Pass config as flags and pipeline.config.json is written for you — no hand-editing to get started:

npx ai-pipeline-kit init \
  --cli claude --model claude-opus-5 \
  --max-parallel 2 \
  --disable architect,specialist-visual \
  --no-require-test-suite

| Flag | Sets | |---|---| | --dir <path> | where to scaffold (default pipeline) | | --force | overwrite scripts/prompts — never your config | | --cli <name> | defaultCli + every station (claude, gemini, glm) | | --model <id> | the model flag for that CLI (claude, gemini) | | --station <name>=<cli> | one station's CLI; repeatable | | --max-parallel <n> | maxParallelAgents | | --max-attempts <n> | maxAttempts | | --timeout <ms> | timeoutMs | | --disable <a,b,c> | disabledStations | | --no-require-test-suite | requireTestSuite: false |

Run npx ai-pipeline-kit --help for the authoritative list — it prints the valid station and CLI names from the template itself.

Two things that make this safe to re-run:

• Flags merge. They apply on top of the config that's already there, so npx ai-pipeline-kit init --max-parallel 1 changes that one setting and leaves your custom clis entries, per-station assignments, and timeouts alone.
• --force never touches your config. It refreshes the .mjs files and prompts (so local edits to those are lost — diff first if you've customised prompts) and reports kept existing: pipeline.config.json. That's how you take a kit upgrade without re-tuning.

Everything is validated before any file is written, so a typo fails fast rather than producing a config that breaks mid-run:

$ npx ai-pipeline-kit init --disable intake
ai-pipeline-kit: "intake" is a core station and cannot be disabled.
Disableable: architect, sdet, qa, specialist-security, ..., reviewer, classifier

Why frontend-specific

The specialist panel and prompts assume a component-based frontend codebase:

• specialist-security — auth, XSS (innerHTML/v-html/dangerouslySetInnerHTML), unsafe storage.
• specialist-performance — unnecessary re-renders, useEffect/useMemo misuse, unbounded loops, missing cleanup of timers/listeners.
• specialist-accessibility — missing aria-*, keyboard support, alt text, label association, contrast, semantic HTML.
• specialist-visual — design-token/theme drift, missing responsive handling, layout shift, dark-mode regressions.

SDET is nudged toward React Testing Library / Vue Test Utils / Cypress-Playwright-style tests that assert on accessible, rendered behavior rather than implementation details. QA adds a pass for responsive breakpoints, keyboard navigation, and console warnings/errors.

After scaffolding

1. Edit pipeline/pipeline.config.json — set which agentic CLI (claude, gemini, glm, ...) runs each station.
2. Dry-run it: node pipeline/orchestrator.mjs <issue-number> --dry-run
3. Once comfortable, run for real and pass --confirm-push only when you want the release station to actually push and open the PR/MR.

The pipeline folder can live anywhere (--dir tools/pipeline and friends) — the repo root is resolved from git, not from the folder's name or depth.

How many agents run at once

Stations run sequentially — the orchestrator awaits each one. The only parallel step is the specialist panel, so a full ticket looks like:

intake → architect → sdet → developer → qa          1 agent at a time
   ↓
security / performance / accessibility / visual      up to maxParallelAgents
   ↓
reviewer → release                                   1 agent at a time

A clean run is 7 station invocations plus however many specialists the classifier triggered (0–4), so 7–11 total. Cap the parallel step in pipeline.config.json:

{ "maxParallelAgents": 2 }

Defaults to 4 (the whole panel at once). Anything queued still runs — a cap slows the panel down, it doesn't drop specialists. Values below 1, non-integers, and non-numbers warn and fall back to 1.

Worth sizing deliberately: each agent is a full agentic CLI session running its own tool-use loop, not one model call, and timeoutMs (default 15 min) applies per station — so at 4 you can have four 15-minute CLI sessions in flight. Set it to 1 on a rate-limited plan.

Note this caps agents within one ticket. Two orchestrator processes on two issues don't coordinate — they'd also be editing the same working tree, which the pipeline doesn't lock.

Turning stations off

Every station except the three core ones is optional. List what you don't want in pipeline.config.json:

{
  "disabledStations": ["architect", "specialist-visual"]
}

Valid entries: architect, sdet, qa, classifier, reviewer, and any of specialist-security, specialist-performance, specialist-accessibility, specialist-visual.

intake, developer, and release are core and cannot be disabled — without them there's no ticket, no change, and nothing gating the remote. Naming one (or a typo) prints a warning and is ignored rather than silently accepted.

Routing follows the chain, so a disabled station is skipped wherever it's named — including when QA or the reviewer tries to route a failure back to it. Disabling classifier also skips the whole specialist panel. Disabling individual specialists still records their signals in 04b-classify.json, so the reviewer can see that a change touched accessibility even on a project that opted out of that review.

Note the stations map is a different thing: it assigns which CLI runs each station, not whether it runs.

Projects with no test suite

A repo with no tests works — the SDET station's job is to add the runner and the test script on its first pass, and the pipeline proceeds normally from there.

What can't happen is a station claiming testsGreen: true with no suite to check it against. The orchestrator's core guarantee is that it re-runs your real tests rather than believing that claim, so if there's still no runnable test script after the SDET has run, the ticket is routed back to the SDET (not dumped on you), and the push gate blocks. If the SDET is disabled, it halts.

A plain HTML/CSS/JS site that genuinely has no test runner is a legitimate case — opt out explicitly:

{ "requireTestSuite": false }

in pipeline.config.json. Stations then run on self-reported results, and both the orchestrator and the push gate say so on every run. Test/lint/build scripts are invoked through whichever package manager your lockfile indicates (npm, pnpm, yarn, or bun).

Gates that are enforced, not just documented

• Schema — every handoff is validated against a per-station schema; malformed output blocks.
• Test integrity — the SDET's test hashes are re-checked right after the developer and QA stations, so tampering routes back to the SDET before the specialist panel and reviewer spend model calls. Hashes for shipped (released) tickets stop gating, so a later refactor of an old test doesn't block every future push.
• Real test runs — the developer's testsGreen and QA's passed are re-verified by running the suite.
• Push gate — re-run by the orchestrator itself immediately before any push.
• Branch safety — the branch name from intake is model-authored, so it is checked: the pipeline refuses to push a protected/default branch, or any branch that isn't the checked-out one.
• Resume — an interrupted ticket resumes at the phase it stopped in; an unrecognized station in state.json halts instead of quietly skipping ahead to release.

Requirements

• Node.js >= 18
• gh (GitHub) or glab (GitLab) CLI, whichever your origin remote points at
• Whichever agentic CLI(s) you configure in pipeline.config.json, installed and authenticated
• GitNexus MCP tools available to your agentic CLI (architect, developer, and reviewer stations require it)

Updating an existing scaffold

npx ai-pipeline-kit init --dir pipeline --force

This refreshes the .mjs scripts and prompts and keeps pipeline.config.json. Local edits to the scripts or prompts are overwritten, so diff those first if you've customised them.