@atez/orchestrator-pipeline-cli

Interactive CLI to scaffold an AI development pipeline harness for your repository.

What It Generates

The wizard creates a complete harness skeleton, including:

• Orchestration agent definitions and tool-specific entry files (from your selected AI tools)
• Domain and ADR folder bootstrap (docs/domain/README.md, docs/adr/README.md)
• docs/orchestration/harness-profile.md — short summary of scope, stacks, and app roots
• Pipeline contracts and decision policies under docs/orchestration/
• Canonical pipeline bundle — most of pipeline/ (scripts, metrics, eval scaffolding, etc.) is copied from the packaged canonical/ tree; a few templates stay generated from your answers (e.g. pipeline-state, agent report, execution log) and quality gates are chosen for your languages/frameworks
• pipeline/README.md and pipeline/.harness-layout.json — which paths came from canonical vs generated
• Optional Dockerfiles under each configured application root (not only the harness root), when you opt in and files are missing
• Stored configuration .atez-harness-config.json (project name, surfaces, languages, frameworks, app roots, Docker/CI preferences, AI tools, ticket system) for fast patch reruns

All generated markdown files include a HARNESS SETUP block at the top with:

• A purpose description
• TODO placeholders for project-specific values
• A stack-agnostic LLM prompt to bootstrap the file's content

Requirements

• Node.js ≥ 20.0.0
• Runtime for generated pipeline scripts:
  • macOS/Linux: Bash environment
  • Windows: Git-Bash or WSL (recommended; cmd.exe/powershell are not primary runtime targets)
  • Required commands: bash, git, awk, sed, grep, find, xargs, and YAML parser (ruby or python3)
  • Optional but recommended: jq

You can validate runtime dependencies after generation with:

bash pipeline/scripts/check-runtime-deps.sh

Windows examples:

Git-Bash:

cd /c/Users/<you>/path/to/repo
bash pipeline/scripts/check-runtime-deps.sh

WSL:

cd /mnt/c/Users/<you>/path/to/repo
bash pipeline/scripts/check-runtime-deps.sh

PowerShell launching Git-Bash:

"C:\Program Files\Git\bin\bash.exe" -lc "cd /c/Users/<you>/path/to/repo && bash pipeline/scripts/check-runtime-deps.sh"

Usage

Run without installing globally:

npx @atez/orchestrator-pipeline-cli

Or install globally:

npm install -g @atez/orchestrator-pipeline-cli
atez-pipeline-init

Run modes

The first prompt asks how to run the generator:

| Mode | When to use | |------|-------------| | Patch existing harness | A harness already exists and .atez-harness-config.json is present — reuses saved answers, asks only for the harness directory, optional Docker/CI if those files are missing, then confirmation. | | Create/update with full wizard | New project or you want to change scope, stacks, app paths, tools, etc. |

If patch mode finds no saved config, run the full wizard once from the same directory you use as the harness output root.

Wizard flow (full wizard)

Questions follow this order (section labels in the CLI use “Step * of 8” for the middle block; project name is collected first, then steps 1–6, then output path and conditional prompts):

| Order | Topic | |-------|--------| | — | Project name | | 1 | Surfaces in this checkout — which of backend, web frontend, and mobile exist in the folder you are generating into (not “how many git remotes”). Options include backend-only, frontend-only, mobile-only, backend + web, web + mobile, backend + mobile, backend + web + mobile, and legacy monorepo (same surfaces as backend + web only). | | 2 | Languages (choices depend on the selected surfaces; mobile scopes can mix web + mobile language options). | | 3 | Frameworks — checkboxes per applicable surface (frontend / backend / mobile). | | 4 | Application directories — repo-relative roots such as apps/api, apps/web, src, or . for each active surface. If backend + web live in the same app folder (single fullstack app), the wizard can capture one shared root and reuse it for both surfaces. These paths drive sandbox roots, harness copy, and where optional Dockerfiles are created. | | 5 | AI coding tools (Claude Code, Copilot, Cursor, OpenCode, …). | | 6 | Ticket / issue tracking (Jira, Linear, GitHub/GitLab issues, none). | | — | Harness output directory — where files are written (defaults to .; cannot be the filesystem root). | | — | Docker (conditional) — if any expected Dockerfile is missing under the configured app root(s), you are asked whether to generate one stack-aware Dockerfile per app directory (or a single merged template if two surfaces share the same path). | | — | CI/CD (conditional) — if neither GitHub Actions nor GitLab CI pipeline files exist in the output tree, you are asked whether to generate them and which provider to use. | | — | Confirmation — summary then generate. |

The interactive full wizard always uses patch semantics for writes: existing files are updated in place, with backup snapshots under .atez-patches/<timestamp>/ (before/, after/, changed-files.txt, apply-updates.sh).

Fast patch update

After the first full run, the generator stores .atez-harness-config.json in the harness root.

Choose Patch existing harness: you only supply the harness directory (and, when needed, answers for missing Dockerfiles / missing CI). Saved application paths from config are reused so Docker detection matches the same roots as the full wizard.

Drift-fix prompt (paste into your agent when drift is reported)

Once the harness is generated, drift will eventually appear: two documents will disagree, a rule will be documented but not invoked, or an agent will silently bypass a script. The harness itself already codifies the procedure in docs/orchestration/repo-memory.md § Harness Change Discipline, but in practice agents still default to adding a new rule when asked to "prevent recurrence". The prompt below is a reinforcement layer: paste it into the agent (Cursor / Claude / Codex / Copilot / …) before describing the drift symptom. It forces the agent to classify, prefer deletion, and ship the smallest sufficient diff.

Before you propose ANY change,
you MUST follow the contract in `docs/orchestration/repo-memory.md`
§ Harness Change Discipline. The rules below are a restatement of that
section for emphasis — on conflict, the file is authoritative.

Hard requirements for this turn:

1. Your FIRST line of output MUST be exactly:
   DRIFT_CLASS: <spec-conflict | invocation-gap | enforcement-gap | genuine-new-rule>

   Definitions (do not invent new classes):
   - spec-conflict:  two documents disagree. Fix = reconcile wording in the
                     authoritative file (see repo-memory.md § Authority map)
                     and DELETE the restatement elsewhere.
   - invocation-gap: the rule is clear, a script exists, but the call site
                     skipped it. Fix = adjust the EXISTING invocation site.
                     Do NOT add a new rule.
   - enforcement-gap: the rule is clear, a script exists, but nothing verifies
                     that it was invoked. Fix = minimum check in the nearest
                     EXISTING verification script
                     (typically `pipeline/scripts/validate-orchestration-contract.sh`).
   - genuine-new-rule: the harness has never covered this case. This is the
                     ONLY class that justifies a new rule, and you MUST
                     explicitly argue why the other three classes do not apply.

2. Prefer DELETION and MERGE over addition. If the fix can be expressed as:
      - removing a contradiction, or
      - merging two restatements into the authoritative file, or
      - tightening an existing script,
   that is the required path. A fix that grows the rule count is a net
   regression unless `genuine-new-rule` holds.

3. Ship the SMALLEST sufficient diff. One drift = one minimum fix. Do not
   bundle adjacent "while we are here" improvements; each deserves its own
   classification and fix. If you notice a second drift, STOP, report it as
   a separate item, and wait for a separate instruction.

4. Before proposing the diff, locate the authoritative file for the topic
   using `docs/orchestration/repo-memory.md` § Authority map. If you cannot
   identify a single authoritative file, the drift is likely `spec-conflict`
   and the first fix is choosing the authority — not writing new text.

5. Forbidden moves for this turn:
   - Adding a new rule, script, state field, or document before emitting
     DRIFT_CLASS and justifying it.
   - Restating an existing rule in a second document ("for visibility",
     "for safety", "as a reminder"). Link to the authoritative file instead.
   - Bundling unrelated cleanups into the same diff.
   - Silently skipping a large file with a size-limit error. Use view_range;
     silent skip is a harness contract violation.

Output format for this turn:

   Line 1: DRIFT_CLASS: <class>
   Line 2: AUTHORITY: <path to the single authoritative file for this topic>
   Then:   One-paragraph justification (≤ 5 sentences) for the class choice,
           explicitly ruling out the other three classes when relevant.
   Then:   The minimum diff (deletions preferred), scoped to the authority
           file and at most one invocation/verification site.
   Then:   A one-line "NET_RULES_DELTA: <-N | 0 | +1>" stating how the rule
           count changes. +1 is only permitted when DRIFT_CLASS =
           genuine-new-rule.

Drift report follows below this line.
---
<PASTE YOUR DRIFT SYMPTOM HERE: which files disagree, which invocation was
 skipped, which check is missing, or which behavior the harness has never
 covered. Include file paths and, if available, the output of
 `bash pipeline/scripts/validate-orchestration-contract.sh`.>

When to use it

| Situation | Use this prompt? | |---|---| | CI/validator failed and you are about to ask the agent to "just add a rule" | Yes — this is exactly the case it protects against. | | Two docs visibly disagree and you are unsure which one is authoritative | Yes — forces agent to resolve via repo-memory.md § Authority map first. | | A rule is documented but agents keep ignoring it in real runs | Yes — the prompt will classify it as invocation-gap or enforcement-gap instead of growing the ruleset. | | Genuinely new capability / brand-new stage / new artifact type | Optional — but genuine-new-rule still requires the justification, so pasting the prompt keeps the bar honest. | | Pure casual-mode Q&A, no file writes expected | No — casual-mode chats do not need the drift-fix protocol. |

Why this exists

Every new rule, script, state field, and document is maintenance surface and a future drift source. The CLI generates a harness with ~40+ orchestration files already; uncontrolled rule growth erodes the harness faster than it fixes it. This prompt makes that cost visible on every drift-fix turn.

Changelog

See CHANGELOG.md for version history.

Notes

• Output path cannot be the filesystem root.
• Fill all TODO placeholders in generated markdown (especially project-context.md and ARCHITECTURE_MAP.md) before relying on agents.
• docs/domain/ and docs/adr/ are always initialized as knowledge folders; add real documents as the project grows.
• For single fullstack web apps (e.g. one Vite/Nitro or Next/Nuxt app folder), choose fullstack and answer the shared app-root prompt with that directory.
• fullstack_mobile in the wizard means backend + mobile (no web app tier). fullstack_all is backend + web + mobile.