@cxi-lmai/ci-agent-platform 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Technical University of Liberec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# ci-agent-platform
+
+> Autonomous dev pipeline on top of plain GitLab CI / GitHub Actions, driven by Claude Code.
+
+The core is the **issue-to-code** loop: you file an issue and an open MR/PR comes
+out. The orchestrator triages it, the coder implements it, and the review loop
+checks the result. The input is a spec, the output is code. Details in
+[docs/issue-to-code.md](https://gitlab.com/cxi-lmai/ci-agent-platform/-/blob/main/docs/issue-to-code.md).
+
+- **15 generic agents**: triage, coding, review, tests, docs, release.
+- **7 skills**, configured per project.
+- **Project specifics live outside the agents**, in `.claude/pipeline-config.md` and `PIPE_*` variables.
+
+> [!NOTE]
+> The CI template wires two loops:
+> - the **review loop** (`review`, `review-fix`, `test-fix`, and the shared escalation `/postmortem-mr`),
+> - the **issue-to-code loop** (`orchestrate`, `code`, skills `triage-issue` and `implement-issue`).
+>
+> The other agents are installed too but have no CI job of their own. You invoke them by hand from the command line.
+
+> [!CAUTION]
+> The coder runs with `--dangerously-skip-permissions` and treats issue content
+> as untrusted input, so it does not blindly implement anything from anyone. Run
+> the loop only on maintainer-approved issues from trusted people, and on an
+> isolated ephemeral runner.
+
+## Platform support
+
+| Platform | Status | Tested |
+| --- | --- | --- |
+| GitLab | supported | end to end on a pilot project |
+| GitHub | experimental | CI templates ship, the issue loop is unverified |
+
+## Contents
+
+- [Platform support](#platform-support)
+- [The full cycle](#the-full-cycle)
+- [Repository layout](#repository-layout)
+- [Install](#install)
+  - [What it costs](#what-it-costs)
+  - [Upgrading and removing](#upgrading-and-removing)
+- [The issue-to-code loop (details)](https://gitlab.com/cxi-lmai/ci-agent-platform/-/blob/main/docs/issue-to-code.md)
+- [How it fits together](#how-it-fits-together)
+- [Possible extensions: changing agents and skills](#possible-extensions-changing-agents-and-skills)
+- [Reference: secrets and variables](https://gitlab.com/cxi-lmai/ci-agent-platform/-/blob/main/docs/reference-variables.md)
+
+## The full cycle
+
+<p align="center">
+  <img src="https://gitlab.com/cxi-lmai/ci-agent-platform/-/raw/main/docs/diagrams/full-cycle.svg" alt="The full cycle: from a labeled issue to a merge request ready to merge" width="760">
+</p>
+
+## Repository layout
+
+The package has two strictly separated halves. `bin/` is executable and never
+reads or rewrites `payload/`; `payload/` is inert content that is copied and
+never executed by Node. That separation is what lets an upgrade tell an
+untouched file from one the project has edited.
+
+```
+.
+├── LICENSE                               # MIT
+├── README.md                             # this file, and the npm front page
+├── package.json                          # bin: ci-agent-platform
+├── bin/init.mjs                          # phase 0: deterministic, no model
+├── payload/                              # everything that ships into your repo
+│   ├── INSTALL.md                        #   instructions for Claude, copied to your root
+│   ├── agents/                           #   15 agent definitions (.md)
+│   ├── skills/                           #   7 skills (folder with a SKILL.md)
+│   ├── templates/                        #   3 templates: config, spec issue, suppressions
+│   └── ci-templates/                     #   CI jobs and runner scripts (wired by the wizard)
+│       ├── claude-pipeline.gitlab-ci.yml #     GitLab CI template
+│       ├── github/                       #     GitHub Actions workflows
+│       └── scripts/                      #     shared runner scripts (both platforms)
+├── docs/                                 # supplementary documentation, not shipped
+│   ├── diagrams/
+│   ├── issue-to-code.md
+│   ├── reference-variables.md
+│   └── superpowers/                      #   this repository's own plans and specs
+├── examples/unitconv/                    # a filled-in example config, not shipped
+└── test/                                 # this repository's own tests, not shipped
+```
+
+## Install
+
+Requires Node 20 or newer, git, and Claude Code. Run both from the root of the
+repository you want to onboard:
+
+```bash
+npx @cxi-lmai/ci-agent-platform     # unpacks the platform
+claude                              # then ask it to install the pipeline
+```
+
+Two things are worth having before you start, though neither blocks the install.
+A `CLAUDE.md` at the repository root: most agents read it as the project's
+rulebook, and without one the reviewers work from `pipeline-config.md` alone. And
+CI credentials for whichever platform you use, which the wizard walks you
+through at the end. Any one of `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` or
+`CLAUDE_CODE_OAUTH_TOKEN` authenticates the agents, so a Claude subscription
+works without buying API credit.
+
+The first command is plain Node with no model in it. It refuses to run outside
+a git repository, detects your platform from the git remote (without ever
+printing the remote, which may embed a token), unpacks the payload into
+`.ci-agent-platform-src/`, adds that plus two working paths to `.gitignore`,
+writes `INSTALL.md` and a manifest of everything it wrote, and stops. It
+commits nothing, pushes nothing, and asks for no secret.
+
+The second hands over to Claude Code, which reads `INSTALL.md` and does the
+rest:
+
+1. distributes the files into `.claude/` and `.claude-pipeline/`,
+2. scans the repository and generates `.claude/pipeline-config.md`,
+3. asks whether the issue-to-code loop should run manually or on a schedule,
+   and how often,
+4. wires your CI file (`.gitlab-ci.yml`, or a GitHub Actions workflow),
+5. walks you through the tokens one step at a time and verifies each one.
+
+> [!NOTE]
+> On a GitHub remote the bootstrapper stops and asks you to confirm that you
+> accept experimental support before it writes anything. Pass
+> `--experimental-github` to answer that in advance, or `--force` to proceed
+> past a prior install it cannot account for.
+
+### What it costs
+
+Every pipeline job spends paid Claude usage, so the defaults are deliberately
+timid. The issue-to-code loop is **off** until you turn it on (`PIPE_ORCHESTRATE=1`
+on a schedule or a manual run), and `PIPE_CODER_CAP` bounds how many issues one
+orchestrate run hands to the coder, at 3. The review loop runs per merge
+request, and `PIPE_FIX_LOOP_CAP` stops it after 2 bot fix commits rather than
+letting it grind.
+
+Turn the schedule on only once both smoke tests pass, and start with a slow
+interval. A frequent schedule against a backlog of ready issues is the one
+configuration that spends real money without anyone watching.
+
+### Upgrading and removing
+
+Re-run `npx @cxi-lmai/ci-agent-platform` to take a newer release. It records what
+it installed in `.claude/pipeline-install.json`, including a checksum per file,
+so it can tell a file you edited from one it wrote.
+
+> [!NOTE]
+> Reconciling those checksums is not implemented yet. Until it is, re-running
+> refreshes the source folder and the manifest; treat updating the installed
+> copies under `.claude/` as a manual diff, and keep your own edits in
+> `pipeline-config.md` rather than in agent files, where nothing will reclaim
+> them.
+
+To remove the pipeline: delete `.claude/agents/`, `.claude/skills/`,
+`.claude/templates/`, `.claude/pipeline-config.md`,
+`.claude/pipeline-install.json`, `.claude-pipeline/`, the spec issue template,
+and `.ci-agent-platform-src/`; then drop the `include:` and the `PIPE_*`
+variables from your CI file, and the three `# ci-agent-platform` lines from
+`.gitignore`. Nothing else was touched.
+
+> [!IMPORTANT]
+> The installer **pushes only after you confirm** and **must not receive token
+> values in the chat**. It asks permission before every push. You enter secret
+> values yourself in the platform settings (CI/CD variables), so Claude never
+> sees them in the conversation.
+
+## How it fits together
+
+Each CI job runs `claude "/<skill>"`, and the work splits into two roles:
+
+1. **The skill** reads `$PIPE_CONFIG_PATH` and the context the runner prepared,
+   does the reasoning (build the diff, choose and run agents, verdict, classify),
+   and writes a marker file.
+2. **The runner** does only what needs a token or is mechanical: checkout,
+   prepare context from the API, compute the diff base, push commits, post
+   comments, set labels, emit metrics, gate.
+
+Where to find what:
+
+- **Skills** (what each takes as input, what it returns, which keys it writes to
+  the marker file): `payload/skills/` here, `.claude/skills/` once installed.
+- **The CI jobs and runner scripts** behind them: `payload/ci-templates/` here,
+  `.claude-pipeline/` once installed.
+
+## Possible extensions: changing agents and skills
+
+The platform is a kit. Adding a capability means adding one definition to your
+own repository. Custom definitions live alongside the installed ones in
+`.claude/`, and the installer never reclaims a file it did not write, so an
+upgrade leaves them alone.
+
+### Agent
+
+A single `.md` file in `.claude/agents/`. Its front matter
+carries `name`, `description`, `tools`, and `model`, followed by the system
+prompt. Platform convention: the prompt's first step reads `pipeline-config.md`
+(path in `PIPE_CONFIG_PATH`) so the agent takes project specifics from there
+rather than from hardcoded text. Agents are mostly read-only subagents that
+skills call.
+
+### Skill
+
+A folder with a `SKILL.md` file in `.claude/skills/`. A CI job
+runs it as `claude "/<skill-name>"`. The skill holds the reasoning: it reads the
+config and the prepared context, picks and runs agents, writes the result, and
+emits a marker file for the runner.
+
+### How to add one
+
+1. Create the definition (`.claude/agents/<name>.md` or
+   `.claude/skills/<name>/SKILL.md`), using the installed ones as a template.
+2. Wire it in. A new agent is called by name from a skill (as a subagent), a new
+   skill needs a CI job that runs it (see `.claude-pipeline/`).
+3. Commit it. The CI runner does a clean checkout, so an uncommitted definition
+   does not exist as far as the pipeline is concerned.
+
+> [!NOTE]
+> One project's rules (conventions, domain checks) do not belong in custom
+> agents, but in `pipeline-config.md`, the Domain Checks section, where every
+> agent reads them. A custom agent is for a new capability, not for one
+> repository's specifics. The `agent-architect` agent can propose improvements to
+> the existing agents.

package/bin/init.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+// Phase 0 of the install: the deterministic half, with no model involved.
+//
+// It unpacks the payload, records what it wrote, and hands over to Claude Code
+// for phases 1 to 6. It deliberately does the least it can: everything that
+// needs judgement about the target repository belongs to the init skill, and
+// everything that needs a secret belongs to the human.
+//
+// This file never reads or rewrites payload/. That separation is what lets the
+// upgrade path treat payload files as content-addressable.
+
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import readline from 'node:readline/promises'
+import { fileURLToPath } from 'node:url'
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const PAYLOAD = path.join(PKG_ROOT, 'payload')
+const SRC_DIR = '.ci-agent-platform-src'
+const GITIGNORE_ENTRIES = [`${SRC_DIR}/`, '.claude/onboarding-state.md', 'build/pipeline/']
+
+const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'))
+
+const argv = process.argv.slice(2)
+const has = (flag) => argv.includes(flag)
+const FORCE = has('--force')
+const YES_GITHUB = has('--experimental-github')
+
+function die(message, hint) {
+  process.stderr.write(`ci-agent-platform: ${message}\n`)
+  if (hint) process.stderr.write(`\n${hint}\n`)
+  process.exit(1)
+}
+
+function say(message = '') {
+  process.stdout.write(`${message}\n`)
+}
+
+if (has('--help') || has('-h')) {
+  say(`ci-agent-platform ${pkg.version}
+
+  npx @cxi-lmai/ci-agent-platform          unpack into the current repository
+  npx @cxi-lmai/ci-agent-platform --force  proceed despite an ambiguous prior install
+
+Options:
+  --experimental-github   accept that GitHub support is experimental, without
+                          being asked (for non-interactive use)
+  --version, --help
+
+Phase 0 only. When it finishes, open Claude Code in this repository and ask it
+to install the pipeline; it reads INSTALL.md and runs phases 1 to 6.`)
+  process.exit(0)
+}
+
+if (has('--version') || has('-v')) {
+  say(pkg.version)
+  process.exit(0)
+}
+
+// --- helpers ---------------------------------------------------------------
+
+function git(...args) {
+  const r = spawnSync('git', args, { encoding: 'utf8' })
+  return { ok: r.status === 0, out: (r.stdout || '').trim() }
+}
+
+function sha256(file) {
+  return `sha256:${createHash('sha256').update(fs.readFileSync(file)).digest('hex')}`
+}
+
+// Payload-relative paths, sorted, so the manifest is stable across platforms.
+function walk(dir, base = dir) {
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .flatMap((e) => {
+      const full = path.join(dir, e.name)
+      return e.isDirectory() ? walk(full, base) : [path.relative(base, full)]
+    })
+    .sort()
+}
+
+/**
+ * Classify the remote host without ever surfacing the URL. A remote can embed
+ * an access token in its userinfo, so the URL is read, matched, and dropped:
+ * it is never printed, never written to the state file, and never returned.
+ */
+function detectPlatform() {
+  const r = git('remote', 'get-url', 'origin')
+  if (!r.ok || !r.out) return 'unknown'
+  const host = r.out.replace(/\/\/[^/@]+@/, '//')
+  if (/gitlab/i.test(host)) return 'gitlab'
+  if (/github/i.test(host)) return 'github'
+  return 'unknown'
+}
+
+async function confirm(question) {
+  if (YES_GITHUB) return true
+  if (!process.stdin.isTTY) return false
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    const answer = await rl.question(`${question} [y/N] `)
+    return /^y(es)?$/i.test(answer.trim())
+  } finally {
+    rl.close()
+  }
+}
+
+function appendGitignore(repoRoot) {
+  const file = path.join(repoRoot, '.gitignore')
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : ''
+  const lines = existing.split('\n').map((l) => l.trim())
+  const missing = GITIGNORE_ENTRIES.filter((e) => !lines.includes(e))
+  if (missing.length === 0) return []
+  const prefix = existing === '' || existing.endsWith('\n') ? '' : '\n'
+  fs.appendFileSync(file, `${prefix}\n# ci-agent-platform\n${missing.join('\n')}\n`)
+  return missing
+}
+
+// --- preflight -------------------------------------------------------------
+
+const top = git('rev-parse', '--show-toplevel')
+if (!top.ok) {
+  die(
+    'this is not a git repository.',
+    'Run it from the root of the repository you want to onboard:\n' +
+      '  cd /path/to/your/repo && npx @cxi-lmai/ci-agent-platform',
+  )
+}
+const REPO = top.out
+process.chdir(REPO)
+
+const configPath = path.join(REPO, '.claude', 'pipeline-config.md')
+const manifestPath = path.join(REPO, '.claude', 'pipeline-install.json')
+if (fs.existsSync(configPath) && !fs.existsSync(manifestPath) && !FORCE) {
+  die(
+    'found .claude/pipeline-config.md but no .claude/pipeline-install.json.',
+    'That combination means an earlier install this tool cannot account for, so\n' +
+      'it will not overwrite anything. Re-run with --force once you are satisfied\n' +
+      'the existing config can be reconciled by hand.',
+  )
+}
+
+const platform = detectPlatform()
+let githubOptIn = null
+if (platform === 'github') {
+  say('GitHub support is experimental.')
+  say('The CI workflows ship and are manually verified, but the issue-to-code')
+  say('loop carries GitLab-shaped assumptions and is unverified on GitHub.')
+  say('GitLab is the supported and tested platform.')
+  say()
+  githubOptIn = await confirm('Continue anyway?')
+  if (!githubOptIn) {
+    die(
+      'stopped at the GitHub experimental-support check.',
+      'Re-run with --experimental-github to accept this without being asked.',
+    )
+  }
+}
+
+// --- write -----------------------------------------------------------------
+
+const srcPath = path.join(REPO, SRC_DIR)
+fs.rmSync(srcPath, { recursive: true, force: true })
+fs.cpSync(PAYLOAD, srcPath, { recursive: true })
+
+const addedIgnores = appendGitignore(REPO)
+
+// INSTALL.md is copied verbatim: it holds no per-project fact, so there is
+// nothing to template. It is NOT copied over a consumer's own INSTALL.md,
+// which is exactly the class of defect this project shipped once already.
+let installName = 'INSTALL.md'
+const payloadInstall = path.join(PAYLOAD, 'INSTALL.md')
+const rootInstall = path.join(REPO, installName)
+if (fs.existsSync(rootInstall)) {
+  const same = fs.readFileSync(rootInstall, 'utf8') === fs.readFileSync(payloadInstall, 'utf8')
+  if (!same) installName = 'INSTALL.ci-agent-platform.md'
+}
+fs.copyFileSync(payloadInstall, path.join(REPO, installName))
+
+fs.mkdirSync(path.join(REPO, '.claude'), { recursive: true })
+
+const payloadFiles = walk(PAYLOAD)
+const manifest = {
+  package: pkg.name,
+  version: pkg.version,
+  platform,
+  payload: Object.fromEntries(payloadFiles.map((rel) => [rel, sha256(path.join(PAYLOAD, rel))])),
+}
+fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+
+fs.writeFileSync(
+  path.join(REPO, '.claude', 'onboarding-state.md'),
+  `# Onboarding state
+
+Phase: 0-complete
+Platform: ${platform}
+GitHub experimental opt-in: ${githubOptIn === null ? 'not applicable' : githubOptIn}
+Source folder: ${SRC_DIR}/
+Install instructions: ${installName}
+
+Next action: phase 1 of .ci-agent-platform-src/skills/init-pipeline-config/SKILL.md
+(scan the repository, select agents, draft the config).
+
+This file is gitignored and is deleted at the end of the install. A session
+resuming an interrupted onboarding reads it first and continues from the phase
+recorded here, following the skill rather than improvising.
+`,
+)
+
+// --- handoff ---------------------------------------------------------------
+
+say()
+say(`ci-agent-platform ${pkg.version}: phase 0 complete.`)
+say()
+say(`  unpacked   ${SRC_DIR}/ (${payloadFiles.length} files)`)
+say(`  wrote      ${installName}`)
+say('             .claude/pipeline-install.json')
+say('             .claude/onboarding-state.md')
+say(`  gitignored ${addedIgnores.length > 0 ? addedIgnores.join(', ') : 'nothing new'}`)
+say(`  platform   ${platform}${platform === 'github' ? ' (experimental)' : ''}`)
+if (installName !== 'INSTALL.md') {
+  say()
+  say('  Note: this repository already had its own INSTALL.md, which was left')
+  say(`  untouched. The install instructions went to ${installName}.`)
+}
+if (platform === 'unknown') {
+  say()
+  say('  Note: no git remote found, so the platform is unknown. Phase 1 asks.')
+}
+say()
+say('Next: open Claude Code in this repository and ask it to install the')
+say('pipeline (any phrasing). It reads the instructions and takes it from here.')
+say()
+say('Nothing has been committed. Nothing has been pushed.')

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@cxi-lmai/ci-agent-platform",
+  "version": "3.0.0",
+  "description": "Autonomous dev pipeline on plain GitLab CI or GitHub Actions, driven by Claude Code. A labeled issue goes in, an open merge request comes out.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ci",
+    "gitlab-ci",
+    "github-actions",
+    "agents",
+    "code-review",
+    "automation"
+  ],
+  "homepage": "https://gitlab.com/cxi-lmai/ci-agent-platform#readme",
+  "bugs": {
+    "url": "https://gitlab.com/cxi-lmai/ci-agent-platform/-/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/cxi-lmai/ci-agent-platform.git"
+  },
+  "license": "MIT",
+  "author": "Technical University of Liberec",
+  "type": "module",
+  "bin": {
+    "ci-agent-platform": "bin/init.mjs"
+  },
+  "files": [
+    "bin/",
+    "payload/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "npm run test:lint && npm run test:gates && npm run test:unit",
+    "test:lint": "shellcheck -S warning test/*.sh payload/ci-templates/scripts/*.sh payload/ci-templates/scripts/lib/*.sh",
+    "test:gates": "bash test/coherence-gate.sh all && bash test/restructure-invariants.sh verify",
+    "test:unit": "node --test \"test/*.test.mjs\""
+  }
+}

package/payload/INSTALL.md

@@ -0,0 +1,113 @@
+# ci-agent-platform: onboarding
+
+Instructions for Claude Code. `npx @cxi-lmai/ci-agent-platform` unpacked the
+platform into this repository, and the user has asked to install it (any
+phrasing: "install ci-agent-platform", "install the pipeline", "set this up").
+Follow this file top to bottom. You are the installer and the guide; the user
+answers questions and approves steps.
+
+Ground rules:
+
+- Never push and never commit without showing what changed and asking first.
+- Never accept secret values (API keys, tokens) into the conversation. Name
+  them, say where to set them, verify presence, not values.
+- Do not overwrite existing files without showing a diff and asking.
+- `.ci-agent-platform-src/` is the source. It is gitignored, so everything the
+  CI needs must be copied into tracked paths (step 1): the runner does a clean
+  checkout and sees only what the repository tracks.
+
+## Step 0: check that the bootstrap ran
+
+`.ci-agent-platform-src/` and `.claude/pipeline-install.json` both exist once
+the bootstrapper has run. If either is missing, the user has not run it. Ask
+them to run `npx @cxi-lmai/ci-agent-platform` in this repository, and stop. Do
+not clone the platform yourself and do not improvise a source folder: the
+manifest that the upgrade path depends on is written only by the bootstrapper.
+
+Then read `.claude/onboarding-state.md`, which records the detected platform
+and the phase reached.
+
+## Step 1: distribute the files
+
+Let `<src>` be `.ci-agent-platform-src/`.
+
+The platform is `gitlab` or `github`, and `.claude/onboarding-state.md` already
+records which. Use that value. Do not re-read the git remote: the bootstrapper
+detected the platform precisely so that a URL which may embed an access token
+never has to enter this conversation.
+
+1. Copy `<src>/agents/` to `.claude/agents/` and `<src>/skills/` to
+   `.claude/skills/` (tracked: the CI runner does a clean checkout and needs
+   them in the repo).
+
+   **Never overwrite a file that is already there.** Repositories that qualify
+   to install this pipeline are exactly the ones likely to have their own
+   `.claude/agents/code-reviewer.md` or `coder.md` already, tuned by hand. For
+   every name that collides, show the diff and ask, one file at a time. Do not
+   offer "overwrite all". A definition the project wrote outranks the one that
+   ships here, and losing it silently is the worst outcome of the whole install.
+2. Copy `<src>/templates/` to `.claude/templates/`, under the same rule.
+3. Create `.claude/memory/review_suppressions.md` from
+   `<src>/templates/review_suppressions.template.md` **when it does not already
+   exist**, and never touch it when it does: it is a project-owned record.
+   The reviewer agents read it on every run, and without the file they read a
+   missing path on a repository that has just been told the pipeline is
+   installed.
+4. Copy the CI template and runner scripts. The runner scripts go to the same
+   place on both platforms, `.claude-pipeline/scripts/`, which is the default
+   `PIPE_SCRIPTS_DIR` the CI template already points at. Only the CI definition
+   differs:
+   - GitLab: `<src>/ci-templates/claude-pipeline.gitlab-ci.yml` to
+     `.claude-pipeline/`, and `<src>/ci-templates/scripts/` to
+     `.claude-pipeline/scripts/`.
+   - GitHub: `<src>/ci-templates/github/*.yml` to `.github/workflows/`, and
+     `<src>/ci-templates/scripts/` to `.claude-pipeline/scripts/`. Ask before
+     replacing a workflow file that already exists; `claude-pipeline.yml` is an
+     ordinary enough name to collide.
+5. Check `.gitignore`. The bootstrapper already added `.ci-agent-platform-src/`,
+   `.claude/onboarding-state.md` (the wizard's progress marker, see the skill's
+   ground rules) and `build/pipeline/` (the default `PIPE_CONTEXT_DIR`, the
+   runner's working files). Add any that are missing. The source folder is a
+   copy of the distributed package; the installed files above are what the
+   project tracks.
+
+Do not commit yet; one commit covers install and configuration together at
+the end of step 2.
+
+When you reach that commit, do not stage the copy of this file at the
+repository root (`INSTALL.md`, or `INSTALL.ci-agent-platform.md` where the
+project had its own). It is an instruction sheet for you, not documentation for
+the project, and it reads as the latter once committed. Delete it together with
+`.ci-agent-platform-src/` at the end of the install, as you already do with
+`.claude/onboarding-state.md`. Everything either file was needed for is by then
+recorded in `.claude/pipeline-install.json`, and re-running the bootstrapper
+restores both.
+
+## Step 2: run the configuration wizard
+
+Follow `.claude/skills/init-pipeline-config/SKILL.md` from phase 1 (it is now
+in the repo; in a fresh session it is also available as the
+`/init-pipeline-config` skill). It scans the repo, generates
+`.claude/pipeline-config.md`, asks the user only what it cannot detect, wires
+the project CI file, guides the secrets setup one step at a time (with a
+step counter), runs the smoke test itself, and closes with one recap table
+of every decision.
+
+Do not duplicate its content here. One rule binds both files: the user does
+only what a human must (tokens, CI variables), you do everything else. Keep
+the ceremony minimal: no per-step approvals, one commit at the end. Ask only
+when something is destructive, secret-related, or about to be pushed.
+
+Once running, a ready issue must carry its full spec in the issue description,
+not in a comment: the orchestrator reads only the description, and a spec left
+in a comment triages as missing sections.
+
+## Resuming an interrupted onboarding
+
+When a new session is asked to continue an installation ("continue", "resume",
+any phrasing, in any language), do not improvise from the repo state. Read
+`.claude/onboarding-state.md` (the wizard maintains it), then re-read
+`.claude/skills/init-pipeline-config/SKILL.md`, and continue at the recorded
+phase, following the skill to the letter. Completed phases are never redone.
+When the state file is missing, infer the phase from the repo (installed
+files, config, git log) and still follow the skill, not your own plan.