Design a CI/CD Pipeline

Design a CI/CD pipeline at author time, before failures happen. This skill is the complement to kramme:pr:fix-ci: that one fixes a broken pipeline; this one designs a pipeline worth having.

Use this when:

Adding a CI pipeline to a new repository or service.
Modifying gate configuration (adding, removing, or re-ordering gates).
Planning a rollout for a new service and deciding what CI discipline it needs.
Auditing an existing pipeline against the exit checklist.

Do NOT use this when:

CI is already failing on a specific PR — use kramme:pr:fix-ci.
You need a full rollout execution runbook with monitoring, comms, and operator steps. This skill only covers the pipeline and safety gates that should exist before rollout.

Step 0: Declare the stack

Before recommending any gate, declare what you detected about the repository. Emit a STACK DETECTED marker with:

CI platform (GitHub Actions / CircleCI / Buildkite / Jenkins / other).
Primary language(s).
Package manager and lockfile.
Existing pipeline file(s), if any, and their current gate set. If no CI exists yet, state that explicitly (e.g., "no pipeline file present; this is a greenfield design").

Example:

STACK DETECTED: GitHub Actions; TypeScript + Python; pnpm-lock.yaml and uv.lock;
existing .github/workflows/ci.yml runs lint + unit only, no types/integration/audit/build.

If any of these are ambiguous (multiple package managers, no clear CI file, mixed lockfiles), emit CONFUSION and ask before proceeding. Gate recommendations that ignore the stack are noise.

Named principles

"A bug caught in linting costs minutes; the same bug caught in production costs hours."

"No gate can be skipped. If lint fails, fix lint — don't disable the rule."

"Smaller batches and more frequent releases reduce risk, not increase it."

These three together dictate the design:

Shift Left — cheap gates catch cheap bugs. Move checks as far left (toward the developer's keystroke) as practical: editor → pre-commit → PR CI → merge queue → production.
Quality Gate Principle — every gate the pipeline has, it must enforce. A gate that can be skipped is worse than no gate at all, because it signals false confidence.
Faster is Safer — a 4-minute pipeline that runs on every PR beats a 40-minute pipeline that runs nightly. Speed unlocks frequency; frequency unlocks small, reversible changes.

Step 1: Order the gates

Default order, fastest first:

Lint — syntax, style, obvious bugs. Seconds. Fails fast.
Types — type checker (tsc, mypy --strict, etc.). Tens of seconds. Catches whole categories of runtime errors at author time.
Unit tests — pure-function, module-level tests. Low minutes. No network, no DB, no filesystem state.
Integration tests — tests that exercise real services (DB, queue, auth). Minutes. Run in parallel shards where possible.
Build — produce the deployable artifact. Minutes. Catches packaging issues, missing deps, bundle-size regressions.
Audit — dependency vulnerability scan, license check, secret scan. Sub-minute with caching.

The ordering matters because fast-fail saves contributor time. A broken lint should cancel the rest of the pipeline in under a minute, not block at integration-test time after eight minutes of compute.

For gates already present in the repo, annotate which already exist and which are new. Do not silently replace existing gates — explicitly name every delta and confirm with the user.

Step 2: Set the pipeline budget

Target: under 10 minutes wall-clock, fresh PR, cold cache.

If the pipeline is over 10 minutes or trending there, pick from:

Parallel jobs — split gates into independent jobs that run concurrently.
Test sharding — partition the integration test suite across N runners.
Dependency caching — cache the package manager's install output keyed on lockfile hash.
Fast-fail / cancel-in-progress — on lint failure, cancel remaining jobs; on new push, cancel the prior run.
Selective re-runs — run affected-only tests for touched files on PR; run the full suite in the merge queue or on main after merge.

A gate that still can't fit the budget is a signal to split, not remove: keep a blocking PR slice that covers the same risk on every PR, then run the extended suite in the merge queue, on push to main, or nightly as a backstop. Nightly-only is never enough for a gate that protects merge readiness.

Step 3: Design the feature-flag lifecycle

Every feature behind a flag has a lifecycle. The common failure is skipping the last step.

Create — introduce the flag, default off. Code paths exist but are gated.
Enable for testing — flag on for employees / staging / test tenants only.
Canary — flag on for a small production subset (N% of traffic, one region, one tenant class).
Full rollout — flag on for 100% of traffic.
Remove flag AND dead code — delete the flag definition, delete the gated-off branch, delete the now-unreachable code.

Step 5 is the one teams skip. A dead flag that still exists in code is a rollback trap: someone reads the flag as live, reasons about both branches, or reintroduces the gated-off path because it "looks intentional." Every flag's design must name its removal criteria up-front (e.g., "remove after 30 days at 100% with zero rollback events").

If the user proposes a flag without a removal plan, emit MISSING REQUIREMENT and require one.

Step 4: Staged rollout (summary)

For the canary → full-rollout sequence, short summary. If the design requires more than the four bullets below, that work is out of scope for this skill; stop and call it out as separate rollout-runbook work.

Canary — deploy to a small bounded subset (one region, one tenant class, N% of traffic). Watch metrics for a defined bake period.
Percentage rollout — incrementally raise the subset (e.g., 5% → 25% → 50% → 100%) with a bake period between steps.
Full — 100% and remove the canary scaffolding.
Rollback criteria — named metrics and thresholds that, if breached at any stage, trigger immediate rollback.

Step 5: Secrets and branch protection

Secrets must live in a secrets manager (GitHub Actions secrets, AWS Secrets Manager, Vault). Not in committed files. Not in plaintext .env files (gitignore is a convention, not a boundary). Not in CI-level env vars without masking. Never echoed in logs.
Branch protection must require the full PR gate set on the default branch. Required checks should include every blocking gate that runs before merge. If a gate also has an extended post-merge or nightly companion, name that separately instead of presenting it as a required PR check.
Merge queue (optional) — if the team ships multiple PRs per day, a merge queue prevents "green at PR time, red at merge time" drift by re-running the pipeline on the merged commit before landing.

Exit checklist

A pipeline is ready to land when every box is checked:

[ ] All six default gate categories have an explicit enforcement point (blocking PR gate, merge-queue gate, or post-merge backstop). Omissions are named and justified.
[ ] Pipeline runs on every PR and every push to main.
[ ] Branch protection requires the full PR gate set; merge is blocked on failure.
[ ] Secrets live in a secrets manager. No secrets in committed files, plaintext env, or unmasked CI variables.
[ ] A rollback mechanism exists and has been exercised at least once (not a theoretical runbook).
[ ] Total pipeline runtime under 10 minutes on a fresh PR with a cold cache.
[ ] Every feature flag has a named removal criterion.
[ ] For each gate, it is clear whether it already existed in the repo or is new (no silent replacements).

Output markers

Use these markers verbatim (uppercase, no decoration), one marker per line. They are a plugin-wide convention for Addy-ported skills.

STACK DETECTED — the required preamble (see Step 0). Always first.
UNVERIFIED — a design recommendation based on inference, not direct repo evidence. UNVERIFIED: I couldn't confirm the integration tests actually exercise the DB — they may be mocking it.
NOTICED BUT NOT TOUCHING — a pre-existing pipeline issue outside this design session. NOTICED BUT NOT TOUCHING: the release workflow mixes secrets into build output; worth a separate pass.
CONFUSION — stack detection is ambiguous. CONFUSION: the repo has both package-lock.json and pnpm-lock.yaml; which is authoritative?
MISSING REQUIREMENT — a product / policy decision is required before the design can proceed. MISSING REQUIREMENT: no stated rollback target; what's the maximum acceptable downtime?

Common rationalizations

Watch for these excuses — they signal the design is about to regress:

| Excuse | Reality | | --- | --- | | "We can skip the audit gate for speed." | Audit cost is one-time to set up and seconds to run with caching. The cost of a shipped vulnerability is unbounded. | | "Secrets in .env are fine, it's gitignored." | Gitignore is a convention, not a boundary. One git add -A and secrets are in history. Use a secrets manager. | | "We'll remove the flag later." | "Later" is where dead flags live forever. Every flag ships with a named removal criterion or it doesn't ship. | | "Integration tests are slow, skip them on PR." | Skipping is how regressions ship. Parallelize, shard, or gate-per-change — don't remove the gate. | | "We don't need branch protection, the team is small." | Small teams make small mistakes at high velocity. Branch protection costs nothing and catches the one 2am push that otherwise lands unreviewed. | | "The pipeline is 18 minutes but nobody complains." | People route around slow pipelines — smaller PRs get batched, tests get skipped locally, --no-verify creeps in. The complaint surfaces as erosion, not a bug report. |

Red Flags — STOP

If any of these are true, pause and re-design before recommending the pipeline:

No rollback mechanism, or one that exists only on paper.
Secrets stored in committed files, unmasked CI variables, or plaintext env files.
Branch protection disabled, or gates not marked required.
Pipeline over 10 minutes with no plan to shrink it.
A feature flag with no removal criterion named.
A gate recommendation made without emitting STACK DETECTED first.
"Temporary" skip of a gate with no named removal date.
A merge-queue configuration that bypasses PR-level gate enforcement.

Verification

Before handing the design off, confirm:

[ ] STACK DETECTED was emitted and names platform, language, package manager, and existing pipeline state.
[ ] Every gate in the proposal is marked as either pre-existing or new; no silent replacements.
[ ] Every exit-checklist item has a clear owner or status (done / deferred with reason / not applicable with reason).
[ ] Every UNVERIFIED, CONFUSION, or MISSING REQUIREMENT marker is resolved or explicitly deferred by the user.
[ ] Feature flags (if any) have named removal criteria.
[ ] The full pipeline runtime has been estimated, not guessed — numbers come from current CI data or comparable repos, not optimism.
[ ] The user has explicitly approved any gate removal, threshold lowering, or skip-on-PR decision.

Design a CI/CD Pipeline

Design a CI/CD pipeline at author time, before failures happen. This skill is the complement to kramme:pr:fix-ci: that one fixes a broken pipeline; this one designs a pipeline worth having.

Use this when:

Adding a CI pipeline to a new repository or service.
Modifying gate configuration (adding, removing, or re-ordering gates).
Planning a rollout for a new service and deciding what CI discipline it needs.
Auditing an existing pipeline against the exit checklist.

Do NOT use this when:

CI is already failing on a specific PR — use kramme:pr:fix-ci.
You need a full rollout execution runbook with monitoring, comms, and operator steps. This skill only covers the pipeline and safety gates that should exist before rollout.

Step 0: Declare the stack

Before recommending any gate, declare what you detected about the repository. Emit a STACK DETECTED marker with:

CI platform (GitHub Actions / CircleCI / Buildkite / Jenkins / other).
Primary language(s).
Package manager and lockfile.
Existing pipeline file(s), if any, and their current gate set. If no CI exists yet, state that explicitly (e.g., "no pipeline file present; this is a greenfield design").

Example:

STACK DETECTED: GitHub Actions; TypeScript + Python; pnpm-lock.yaml and uv.lock;
existing .github/workflows/ci.yml runs lint + unit only, no types/integration/audit/build.

If any of these are ambiguous (multiple package managers, no clear CI file, mixed lockfiles), emit CONFUSION and ask before proceeding. Gate recommendations that ignore the stack are noise.

Named principles

"A bug caught in linting costs minutes; the same bug caught in production costs hours."

"No gate can be skipped. If lint fails, fix lint — don't disable the rule."

"Smaller batches and more frequent releases reduce risk, not increase it."

These three together dictate the design:

Shift Left — cheap gates catch cheap bugs. Move checks as far left (toward the developer's keystroke) as practical: editor → pre-commit → PR CI → merge queue → production.
Quality Gate Principle — every gate the pipeline has, it must enforce. A gate that can be skipped is worse than no gate at all, because it signals false confidence.
Faster is Safer — a 4-minute pipeline that runs on every PR beats a 40-minute pipeline that runs nightly. Speed unlocks frequency; frequency unlocks small, reversible changes.

Step 1: Order the gates

Default order, fastest first:

Lint — syntax, style, obvious bugs. Seconds. Fails fast.
Types — type checker (tsc, mypy --strict, etc.). Tens of seconds. Catches whole categories of runtime errors at author time.
Unit tests — pure-function, module-level tests. Low minutes. No network, no DB, no filesystem state.
Integration tests — tests that exercise real services (DB, queue, auth). Minutes. Run in parallel shards where possible.
Build — produce the deployable artifact. Minutes. Catches packaging issues, missing deps, bundle-size regressions.
Audit — dependency vulnerability scan, license check, secret scan. Sub-minute with caching.

For gates already present in the repo, annotate which already exist and which are new. Do not silently replace existing gates — explicitly name every delta and confirm with the user.

Step 2: Set the pipeline budget

Target: under 10 minutes wall-clock, fresh PR, cold cache.

If the pipeline is over 10 minutes or trending there, pick from:

Parallel jobs — split gates into independent jobs that run concurrently.
Test sharding — partition the integration test suite across N runners.
Dependency caching — cache the package manager's install output keyed on lockfile hash.
Fast-fail / cancel-in-progress — on lint failure, cancel remaining jobs; on new push, cancel the prior run.
Selective re-runs — run affected-only tests for touched files on PR; run the full suite in the merge queue or on main after merge.

Step 3: Design the feature-flag lifecycle

Every feature behind a flag has a lifecycle. The common failure is skipping the last step.

Create — introduce the flag, default off. Code paths exist but are gated.
Enable for testing — flag on for employees / staging / test tenants only.
Canary — flag on for a small production subset (N% of traffic, one region, one tenant class).
Full rollout — flag on for 100% of traffic.
Remove flag AND dead code — delete the flag definition, delete the gated-off branch, delete the now-unreachable code.

If the user proposes a flag without a removal plan, emit MISSING REQUIREMENT and require one.

Step 4: Staged rollout (summary)

Canary — deploy to a small bounded subset (one region, one tenant class, N% of traffic). Watch metrics for a defined bake period.
Percentage rollout — incrementally raise the subset (e.g., 5% → 25% → 50% → 100%) with a bake period between steps.
Full — 100% and remove the canary scaffolding.
Rollback criteria — named metrics and thresholds that, if breached at any stage, trigger immediate rollback.

Step 5: Secrets and branch protection

Secrets must live in a secrets manager (GitHub Actions secrets, AWS Secrets Manager, Vault). Not in committed files. Not in plaintext .env files (gitignore is a convention, not a boundary). Not in CI-level env vars without masking. Never echoed in logs.
Branch protection must require the full PR gate set on the default branch. Required checks should include every blocking gate that runs before merge. If a gate also has an extended post-merge or nightly companion, name that separately instead of presenting it as a required PR check.
Merge queue (optional) — if the team ships multiple PRs per day, a merge queue prevents "green at PR time, red at merge time" drift by re-running the pipeline on the merged commit before landing.

Exit checklist

A pipeline is ready to land when every box is checked:

[ ] All six default gate categories have an explicit enforcement point (blocking PR gate, merge-queue gate, or post-merge backstop). Omissions are named and justified.
[ ] Pipeline runs on every PR and every push to main.
[ ] Branch protection requires the full PR gate set; merge is blocked on failure.
[ ] Secrets live in a secrets manager. No secrets in committed files, plaintext env, or unmasked CI variables.
[ ] A rollback mechanism exists and has been exercised at least once (not a theoretical runbook).
[ ] Total pipeline runtime under 10 minutes on a fresh PR with a cold cache.
[ ] Every feature flag has a named removal criterion.
[ ] For each gate, it is clear whether it already existed in the repo or is new (no silent replacements).

Output markers

Use these markers verbatim (uppercase, no decoration), one marker per line. They are a plugin-wide convention for Addy-ported skills.

STACK DETECTED — the required preamble (see Step 0). Always first.
UNVERIFIED — a design recommendation based on inference, not direct repo evidence. UNVERIFIED: I couldn't confirm the integration tests actually exercise the DB — they may be mocking it.
NOTICED BUT NOT TOUCHING — a pre-existing pipeline issue outside this design session. NOTICED BUT NOT TOUCHING: the release workflow mixes secrets into build output; worth a separate pass.
CONFUSION — stack detection is ambiguous. CONFUSION: the repo has both package-lock.json and pnpm-lock.yaml; which is authoritative?
MISSING REQUIREMENT — a product / policy decision is required before the design can proceed. MISSING REQUIREMENT: no stated rollback target; what's the maximum acceptable downtime?

Common rationalizations

Watch for these excuses — they signal the design is about to regress:

Red Flags — STOP

If any of these are true, pause and re-design before recommending the pipeline:

No rollback mechanism, or one that exists only on paper.
Secrets stored in committed files, unmasked CI variables, or plaintext env files.
Branch protection disabled, or gates not marked required.
Pipeline over 10 minutes with no plan to shrink it.
A feature flag with no removal criterion named.
A gate recommendation made without emitting STACK DETECTED first.
"Temporary" skip of a gate with no named removal date.
A merge-queue configuration that bypasses PR-level gate enforcement.

Verification

Before handing the design off, confirm:

[ ] STACK DETECTED was emitted and names platform, language, package manager, and existing pipeline state.
[ ] Every gate in the proposal is marked as either pre-existing or new; no silent replacements.
[ ] Every exit-checklist item has a clear owner or status (done / deferred with reason / not applicable with reason).
[ ] Every UNVERIFIED, CONFUSION, or MISSING REQUIREMENT marker is resolved or explicitly deferred by the user.
[ ] Feature flags (if any) have named removal criteria.
[ ] The full pipeline runtime has been estimated, not guessed — numbers come from current CI data or comparable repos, not optimism.
[ ] The user has explicitly approved any gate removal, threshold lowering, or skip-on-PR decision.

Adoption

abildtoft/kramme:pr:design-pipeline

$ install --global

Security Scan Results

SKILL.md

Design a CI/CD Pipeline

Step 0: Declare the stack

Named principles

Step 1: Order the gates

Step 2: Set the pipeline budget

Step 3: Design the feature-flag lifecycle

Step 4: Staged rollout (summary)

Step 5: Secrets and branch protection

Exit checklist

Output markers

Common rationalizations

Red Flags — STOP

Verification

Related Skills

abildtoft/kramme:linear:issue-to-pr

abildtoft/kramme:pr:convention-review

abildtoft/kramme:siw:wayfinder

abildtoft/kramme:research

abildtoft/kramme:pr:design-pipeline

$ install --global

Security Scan Results

SKILL.md

Design a CI/CD Pipeline

Step 0: Declare the stack

Named principles

Step 1: Order the gates

Step 2: Set the pipeline budget

Step 3: Design the feature-flag lifecycle

Step 4: Staged rollout (summary)

Step 5: Secrets and branch protection

Exit checklist

Output markers

Common rationalizations

Red Flags — STOP

Verification

Related Skills

abildtoft/kramme:linear:issue-to-pr

abildtoft/kramme:pr:convention-review

abildtoft/kramme:siw:wayfinder

abildtoft/kramme:research