Repo tooling architect

Repo Tooling Architecture

Productivity files that live at the repo root, are language-agnostic, and shape how every contributor and CI step interacts with the code. Pairs with every language and framework architect skill. See STACK.md for pinned tool versions.

Decision model

Add a tool when all three are true:

1. It pays back on day one. Not "useful eventually" — useful from the first PR.
2. The cost of installing it is smaller than the cost of going without it. A 30-second install is fine; a 30-minute setup that breaks once per OS is not.
3. There's no language-native option that already covers it. go test doesn't need a Makefile wrapper. uv run doesn't need task for one-language projects.

When in doubt, skip. Tools you add later are easy; tools you remove are political.

1. .editorconfig

Always include. Universal editor support, zero ceremony, ends the indent-style wars before they start.

# .editorconfig
root = true

[*]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.{go,Makefile}]
indent_style = tab

[*.{yml,yaml,json}]
indent_size = 2

[*.md]
trim_trailing_whitespace = false  # Markdown uses trailing spaces for hard breaks

2. .gitignore

Always include. Curate per language; never copy a 500-line GitHub default that contains entries for languages you don't use.

• Use github.com/github/gitignore as the source for the base section per language.
• Trim aggressively. A clean .gitignore is documentation; a noisy one is noise.
• Local-only exclusions (.idea/, .vscode/settings.json) go in .git/info/exclude per-developer or ~/.gitignore_global, not the repo's .gitignore.

3. Tool version pinning — mise (default), proto (alternative)

The problem: "works on my machine" because each dev has different Go / Python / Node versions. CI uses yet another version. Fix: pin every tool the repo needs in a file, install with one command.

Default: mise with mise.toml

# mise.toml
[tools]
go = "1.26"
python = "3.14"
node = "22"
task = "3.51"
golangci-lint = "2.12"
buf = "1.69"
trivy = "0.70"

mise install                     # installs everything pinned

• Why mise as default: broadest tool coverage via asdf-legacy plugins, available through winget/brew/scoop.
• Shell activation required: eval "$(mise activate bash)" (or zsh/fish/pwsh equivalent).

Alternative: proto with .prototools

Same key-value shape, file named .prototools, install with proto install. Pick proto when you want strict separation (proto manages only binary versions; task handles env + tasks) and no shell-activation step (PATH-shim based). Trade-off: smaller plugin ecosystem; obscure tools may need a custom WASM plugin.

Either way: the pinned-versions file is committed; CI installs the same versions; nobody runs "whatever's on their machine."

4. Task runner — Task (default) or just (alternative)

The problem: every project has 5–15 commands a contributor needs to know (go build, go test --race, docker compose up -d db, task generate-protos, etc.). Without a runner, they live in stale README sections.

Default: skip a task runner for single-language projects. go build, uv run, npm are enough. Don't wrap them in task build: aliases — that's ceremony.

Add a task runner when: multi-language repo, multi-service compose stack, or a meaningful number of multi-step commands.

Default: Task with Taskfile.yml

# Taskfile.yml
version: '3'

dotenv: ['.env', '.env.local']

tasks:
  default:
    desc: List all tasks
    cmds:
      - task --list

  proto:generate:
    desc: Regenerate Go code from .proto files
    sources:
      - 'proto/**/*.proto'
    generates:
      - 'internal/**/*.pb.go'
    cmds:
      - buf generate

  test:unit:
    desc: Run unit tests
    cmds:
      - go test ./...

  test:race:
    desc: Run all tests with race detector
    cmds:
      - go test -race ./...

  docker:up:
    desc: Start dev stack (DB + app)
    cmds:
      - docker compose up -d

  docker:down:
    desc: Stop dev stack
    cmds:
      - docker compose down

• Why Task as default: built-in sources: / generates: for incremental builds, --watch mode, first-class Windows support (ships its own POSIX-sh interpreter), built-in dotenv: loading.
• Discoverability: task --list shows every task with its desc.

Naming: module:verb. Name tasks after the thing they act on, then the action — proto:generate, test:unit, test:race, docker:up, docker:down — not the reverse (generate-proto, run-tests). task --list groups alphabetically, so this puts every task for a module next to its siblings and reads as a discoverable namespace even without splitting files. Reserve unprefixed names (default, build, lint) for repo-wide entry points that don't belong to a single module.

For a large enough module to warrant its own file, promote the prefix to a real namespace with includes: — Task auto-prefixes every task in the included file, so docker:up becomes task docker:up whether it's a flat key or defined in Taskfile.docker.yml:

# Taskfile.yml
includes:
  docker: ./Taskfile.docker.yml
  proto: ./Taskfile.proto.yml

# Taskfile.docker.yml
version: '3'
tasks:
  up:
    desc: Start dev stack (DB + app)
    cmds:
      - docker compose up -d
  down:
    desc: Stop dev stack
    cmds:
      - docker compose down

Stay flat until a module earns its own file (5+ tasks, or config distinct enough to warrant separation) — splitting a two-task module into its own Taskfile.*.yml is ceremony the flat module:verb key already avoids.

Alternative: just with justfile

Makefile-style brevity over YAML; recipes look like shell. Add set windows-shell := [...] and set dotenv-load at the top. Pick just when you prefer terseness, don't need incremental builds, and all collaborators are on macOS/Linux. Trade-off: no native incremental builds, no --watch mode.

Settle on one per repo. Don't mix Taskfile.yml and justfile.

5. Pre-commit hooks — minimal, opt-in

The problem: minor issues (trailing whitespace, committed secrets, large files) reach CI when they could have been blocked locally. Fix: a tiny pre-commit hook set that catches only what can't be caught later or that's genuinely fast.

Strong opinions exist. Some teams love pre-commit; some find it slows commits / blocks WIP commits. The minimal-hook stance is the compromise: catch real risks, never run language-specific linters or formatters in commit hooks (those run in editor-on-save and again in CI).

.pre-commit-config.yaml — minimal set

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
        exclude: '\.md$'             # markdown uses trailing space for hard breaks
      - id: end-of-file-fixer
      - id: check-added-large-files
        args: ['--maxkb=500']
      - id: check-merge-conflict
      - id: check-yaml
      - id: check-json

  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.21.0
    hooks:
      - id: gitleaks                 # secret detection

• Install: pre-commit install once per clone.
• Run on demand: pre-commit run --all-files (or wire into a Task: task lint:precommit).
• No language-specific linters. ruff, golangci-lint, etc. run in editor (on save) and again in CI. Running them in a pre-commit hook duplicates work and slows commits.
• Skip on a single commit: git commit --no-verify is fine; over-policing pre-commit erodes trust.

6. Environment variables

The problem: secrets and config diverge across machines, leak into git, or get exported globally and bleed across projects.

Pattern

• Non-secret config: .env + .env.local, loaded by Task's dotenv: directive.
  • .env is committed (defaults safe for any contributor — LOG_LEVEL=info, DB_HOST=localhost).
  • .env.local is git-ignored (per-developer overrides — LOG_LEVEL=debug).
• Real secrets: external secret manager. Never in .env, never committed:
  • 1Password CLI (op run --env-file=.env.template -- task up) — solo / small team
  • doppler (doppler run -- task up) — team
  • Cloud secret manager (AWS Secrets Manager, GCP Secret Manager) — production injection at runtime
• No direnv unless you need automatic activation when you cd into a directory. Task's dotenv: covers the common case without a second tool.

.env shape

# .env — committed, safe defaults
LOG_LEVEL=info
APP_PORT=8080
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp_dev

# .env.local — git-ignored, per-developer overrides + dev secrets
LOG_LEVEL=debug
DB_PASSWORD=dev-only-not-a-real-secret

.gitignore must include .env.local. Audit any .env* pattern: only ignore variants that hold secrets; commit the safe ones.

7. Dependency updates — Renovate (default), Dependabot (acceptable)

The problem: dependency updates accumulate until they hit a security advisory or a breaking version, then a week of catch-up is needed. Automate it.

Default: Renovate

renovate.json at the repo root:

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "schedule": ["before 6am on Monday"],
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "groupName": "minor + patch updates"
    },
    {
      "matchPackageNames": ["go", "python", "node"],
      "matchUpdateTypes": ["major"],
      "automerge": false,
      "labels": ["language-bump"]
    }
  ],
  "vulnerabilityAlerts": {
    "enabled": true,
    "labels": ["security"]
  }
}

• Why Renovate: grouping rules, scheduled batches, broader ecosystem coverage (Go modules, Python, npm, Docker tags, GitHub Actions, Terraform).
• Group minor + patch updates into one weekly PR — review-bandwidth-friendly.
• Security updates land immediately — never queued.
• Major bumps stay separate, labeled, never auto-merged — they deserve a human read.

Acceptable: Dependabot

For tiny single-language repos where Renovate's flexibility is overkill, GitHub's built-in Dependabot is fine. Same pattern (security immediate, minor grouped, major labeled).

8. When to skip the whole thing

This skill is opinionated about adding tools, but the strongest opinion is don't add what you don't need.

• Single-language single-service project: skip the task runner (use native tooling), keep mise/proto for version pinning if more than one dev exists.
• Solo throwaway project: .editorconfig and .gitignore. That's it.
• Documentation-only repo: .editorconfig, .gitignore, optional pre-commit for trailing whitespace.
• Library / SDK with one entry point: language-native tooling + Renovate. No Task, no mise needed.
• Multi-language monorepo / multi-service compose stack: the full stack — .editorconfig, .gitignore, mise.toml (or .prototools), Taskfile.yml, pre-commit-config.yaml, renovate.json, docker-compose.yaml.

Default to less. Add when the friction is real.