/build-deploy-and-tooling

name: build-deploy-and-tooling
description: Use when writing, reviewing, or changing build scripts, CI workflows, deploy pipelines, repo setup, or evaluating a new tool/dependency

Build, Deploy and Tooling

Overview

Build scripts, CI pipelines, deploy jobs, and tooling choices are part of the codebase. **Own the build as code. Build one artifact and promote it. Deploy from day one. Choose tools that fit the project, not the resume. Automate everything you do twice.** This skill enforces the decisions to make whenever you touch infrastructure or evaluate a tool.

This is a **rigid** skill. Run the checklist in order. If you can't satisfy a step, stop and tell the user what's blocking you.

These checks matter most when shaping a release artifact — production deploy, shared CI pipeline, tool adoption that other contributors will inherit. In MVPs, prototypes, internal dev tools, and one-off scripts where the architecture is not yet settled, prefer the simplest thing that works.

When to invoke

Invoke when you're about to:

• Write or modify a build script, `Makefile`, `package.json` script, `Dockerfile`, or build configuration
• Change a CI workflow (`.github/workflows/*`, `.gitlab-ci.yml`, Jenkinsfile, etc.)
• Author or change a deploy pipeline, release script, or environment promotion job
• Add a new dependency, framework, linter, formatter, or developer tool to the project
• Set up a new repository, devcontainer, or onboarding script
• Add a new repeated manual step to anyone's workflow (a candidate for automation)
• Configure a bug tracker, issue template, or defect-triage workflow
• Write or change an installer, a "getting started" page, or a `README` quick-start
• Review CI config, deploy pipelines, build scripts, or tooling choices

Non-triggers — do NOT invoke for

• Running the existing test suite or build (`npm test`, `make`, `docker build` on an unchanged config)
• Tailing a log file or reading CI output to diagnose a failure
• Asking "what does this Makefile target do?" — read it; no design decision is being made
• Using a linter, formatter, or tool the repo already mandates with its current configuration
• Bumping a single dependency patch version because of a security advisory
• Editing a deployed service's runtime configuration through the platform's normal config interface
• An early-stage MVP or prototype where the architecture is still in flux
• An internal dev tool or one-off script whose build needs are "run this command"
• Throwaway code expected to be replaced before reaching users

If you're not sure whether a change counts as "authoring infrastructure," **invoke anyway** — the checklist is short and skipping it produces build scripts nobody understands.

Build/deploy/tooling checklist

Run every step in order. The sub-area headings group related principles; the numbered items run end-to-end.

Version control

1. **Put everything the project needs into version control before anything else.** Source, build scripts, CI configuration, `Dockerfile`, infrastructure-as-code, fixtures, sample data, generated-docs config, design notes, the README itself. A new contributor's setup should be a single clone plus running the documented bootstrap script — no "copy this file from Slack." Each commit should isolate one logical change, carry a message that explains the *why*, and not break the build. *(Spinellis, 97/68.)*

Builds

2. **The dev team owns the build as code, and refactors it.** Build scripts are not someone else's problem or a configuration file beneath your attention — they decide what the executable artifact actually is, define the component boundaries, and gate every change on the way to production. Treat them with the same discipline you apply to source: name the targets clearly, factor out duplication, delete dead branches, document non-obvious steps. A build that takes a new contributor a day to get green is a bug. *(Berczuk, 97/63.)* 3. **Build one immutable artifact and promote *that* through every environment.** The deployable artifact (container image, JAR, binary, bundle) is built once from a tagged commit. The same bytes flow through dev, staging, and prod. Environment-specific values — endpoints, credentials, feature flags — live in the environment (container env vars, config service, mounted file), never baked into the image. If the build rewrites code per environment, you cannot prove that what shipped to prod is what staging tested. *(Freeman, 97/61.)*

Deploy

4. **Deploy to a realistic clean environment from week one, and refactor the deploy process like code.** Hand-crafted demo environments hide the assumptions your code makes about a developer's laptop. The first deployment should happen before there is anything interesting to deploy, so the pipeline matures alongside the application. Each environment promotion uses the same artifact from step 3 with a different config bundle. When the deploy is painful, treat the pain as a defect — change the deploy script, change the code that complicates it, do not normalize the workaround. *(Berczuk, 97/20; promotion model from Freeman, 97/61.)*

Tooling choice

5. **Respect the project's existing tool conventions before recommending a new one.** If the repo already uses a linter, a test runner, a build system, a deployment target — that is the convention until the team agrees otherwise. Adding a parallel tool because you prefer it doubles maintenance and fragments contributor knowledge. When you do propose a new tool, evaluate the real costs: architectural fit with the existing stack, upgrade lifecycle and how it interacts with the other tools' upgrade cycles, configuration burden, license compatibility, lock-in risk, and whether "free" hides a paid support tier you will eventually need. Start with the smallest set that works; isolate each external tool behind an internal interface so it can be swapped later with bounded pain. *(Asproni, 97/10.)* 6. **Treat the installe