CI Pipeline Harness

# CI Pipeline Harness

A Claude Code project configuration for scaffolding and enforcing a staged CI pipeline.

## What it does

When this harness is active, Claude Code operates as a CI pipeline engineer. It follows a
strict gate order — lint → typecheck → test → build — and refuses to advance a gate until
the previous one is green. The workflow is instruction-driven: Claude reads this README and
treats it as the working contract for the session.

- **Fail-fast:** The first failing gate halts the pipeline and surfaces the output before
  continuing, so failures don't cascade.
- **Caching:** Claude proposes caching strategies for dependencies and build artefacts at
  setup time, scoped to the runner and toolchain.
- **Settings gate:** The `settings.json` permits only pipeline-relevant bash commands,
  preventing off-task tool use during a CI session.

## Files in this harness

| File | Purpose |
|------|---------|
| `README.md` | This guide — Claude reads it as its working instructions |
| `settings.json` | Claude Code project settings — copy to `.claude/settings.json` |

## Setup

1. Copy `settings.json` to `.claude/settings.json` in your project root.
2. Open your project in Claude Code. The permission gates take effect immediately.
3. Tell Claude which package manager and CI platform you are targeting, e.g.:
   "We use pnpm on GitHub Actions."

Claude will scaffold a pipeline file (e.g. `.github/workflows/ci.yml`) and a local
`Makefile` or `package.json` scripts block that mirrors the same gate order.

## Workflow reference

### Scaffolding a new pipeline
Tell Claude: "Set up a CI pipeline for this project."

Claude will:
1. Inspect `package.json` (or equivalent) for existing lint/test/build scripts.
2. Propose the four gates with concrete commands for each.
3. Draft the CI config file with fail-fast enabled and dependency caching.
4. Run the gates locally in order so you can confirm each one passes before committing.

### Adding a gate
Tell Claude: "Add a `security-audit` gate after `test`."

Claude will insert the gate in the correct position in both the CI config and the local
script block, and verify it runs without breaking the existing pipeline.

### Debugging a gate failure
Tell Claude: "Gate 2 (typecheck) is failing in CI but passes locally."

Claude will diff the CI environment against local (Node version, env vars, installed
packages) and propose the most likely fix before touching any code.

## Commands

- `/ci-setup` — Scaffold a full lint→typecheck→test→build pipeline for the current
  project, including a CI config file and local script equivalents.
- `/ci-gate <gate-name>` — Run a single gate (e.g. `/ci-gate lint`) and report
  pass/fail with the raw output.
- `/ci-debug <gate-name>` — Diagnose a failing gate: diff CI vs local environment,
  pinpoint the root cause, and propose a fix.

## Allowed bash commands

The harness permits pipeline-related commands only:

- `Bash(npm run lint*)`, `Bash(npx eslint*)` — lint gate
- `Bash(npx tsc*)` — typecheck gate
- `Bash(npm test*)`, `Bash(npx vitest*)`, `Bash(npx jest*)` — test gate
- `Bash(npm run build*)`, `Bash(npx next build*)` — build gate
- `Bash(git diff*)`, `Bash(git status*)`, `Bash(git log*)` — inspect state

Destructive commands (`rm -rf`, `git push`, `git reset --hard`) are blocked.

## Known limitations

- The harness does not auto-detect your CI platform; tell Claude which one you use at
  the start of the session.
- Caching config is proposed, not generated automatically — Claude needs to know your
  runner OS and lockfile location to produce valid cache keys.

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Write(**)",
      "Edit(**)",
      "Bash(npm run lint*)",
      "Bash(npx eslint*)",
      "Bash(npx tsc*)",
      "Bash(npm test*)",
      "Bash(npx vitest*)",
      "Bash(npx jest*)",
      "Bash(npm run build*)",
      "Bash(npx next build*)",
      "Bash(pnpm run*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(git log*)"
    ],
    "deny": [
      "Bash(git push*)",
      "Bash(git reset --hard*)",
      "Bash(git restore*)",
      "Bash(git clean*)",
      "Bash(rm -rf*)"
    ]
  }
}