0–5 min: setup inventory
List README commands, CI commands, tool versions, env files, task runners, and release scripts.
Success checkThe current setup surface is visible.
Developer environment governance · Updated 2026-06-27
Project Setup Contract Checklist: mise, uv, Tool Versions, Environment Rules, Tasks, README, and CI Parity
A practical checklist for teams turning project setup into a reviewable contract instead of scattered README steps, shell history, CI drift, and tribal knowledge.
A project setup contract is the written agreement that tells a clean machine, a new teammate, and CI how to enter a repository. It names the tools, versions, environment rules, tasks, secrets boundaries, and review owners that make development reproducible.
mise is the natural center of this checklist because it can pin tools, load project environment rules, and define tasks. uv owns Python dependency and project behavior. gstack-style workstation baselines and coding agents such as Claude Code or Codex CLI add more pressure for a clear contract: if agents and humans do not enter the same environment, every automation result becomes harder to trust.
RepoDaily verdict
Treat project setup as code. Put tool versions, safe environment rules, and common tasks in a reviewable source of truth such as `mise.toml`; keep secrets out of the repo; make README and CI use the same commands; and review setup changes with the same seriousness as build or deployment changes.
Quick matrix
| Contract area | What to define | Good default | Review trigger |
|---|---|---|---|
| Tools | Node, Python, uv, pnpm, Terraform, cloud CLIs, linters, formatters | Pin exact or policy-approved versions in `mise.toml` | Tool version change affects build, deploy, tests, or generated output |
| Python workflow | uv commands, lockfile policy, Python version, private indexes | Use uv for Python sync/run; use mise to pin uv and Python | Lockfile, index, Python version, or publish behavior changes |
| Environment | Non-secret defaults, local-only files, secret-manager boundaries | Document examples; never commit real secrets | New variable touches credentials, production, billing, user data, or cloud accounts |
| Tasks | dev, test, lint, build, format, typecheck, docs, release | Expose common commands through `mise run` or equivalent | Task can deploy, delete, migrate, change infra, or call external services |
| README | Single clean-machine path and fallback notes | README calls the same setup commands as CI | Docs diverge from `mise.toml`, uv lock, or CI commands |
| CI parity | Install, cache, test, lint, build and release command alignment | CI mirrors documented local commands where possible | CI uses hidden scripts or different tool versions |
| Ownership | Who reviews setup changes and tool upgrades | CODEOWNERS or explicit maintainers for setup files | Any setup contract file changes |
| Agent readiness | Whether coding agents may run tasks in this repo | Agents use the same setup contract and denied-command policy | Agent tools need extra env, MCP, hooks, or secrets |
Setup contract maturity scorecard
Score the repository before calling its onboarding reproducible.
| Dimension | 0 points | 1 point | 2 points | Reviewer question |
|---|---|---|---|---|
| Single source of truth | README, CI, and local steps disagree | Some shared commands | `mise.toml`/README/CI aligned | Where does a new developer start? |
| Tool pinning | Versions implicit | Some versions pinned | Critical tools pinned and owned | Which tool change would break output? |
| Env/secrets boundary | Secrets unclear | Examples exist | Secret boundary and local overrides documented | What can safely be committed? |
| Task authority | Tasks are scattered | Common tasks exist | Tasks have risk levels and owners | Which task can mutate infrastructure? |
| CI parity | CI uses hidden workflow | Partially mirrors local | CI and README share commands and versions | Can CI reproduce local setup? |
| Change review | Setup changes unowned | Ad hoc review | Setup files have owners and checklist | Who approves `mise.toml` changes? |
30-minute project setup contract test plan
Use this plan before standardizing a repo on mise or rewriting onboarding docs.
5–12 min: contract draft
Draft or inspect `mise.toml` with tools, safe env defaults, and dev/test/lint/build tasks.
Success checkA new developer can see the intended setup path.
12–18 min: clean-machine thought test
Ask what happens on a machine with no Node, no Python, no uv, and no secrets.
Success checkInstall, secret, and fallback gaps are explicit.
18–24 min: CI parity check
Compare README commands with CI commands and note every intentional difference.
Success checkCI and local setup are aligned or differences are documented.
24–30 min: ownership decision
Assign owners for setup files, task authority, and future tool upgrades.
Success checkThe contract has reviewers and a next review date.
Contract decision flow
- Inventory current setup: README commands, CI commands, package managers, Python versions, Node versions, env files, task runners, and release scripts.
- Choose the contract surface: `mise.toml` for tools/env/tasks, uv for Python dependencies, package-manager files for language-specific dependencies, and README for the human entry path.
- Move only stable, non-secret defaults into the contract. Keep secrets in a secret manager or ignored local files with documented examples.
- Define task risk levels: safe local tasks, network tasks, mutation tasks, deploy/release tasks, and prohibited commands.
- Make CI call the same core commands as README or document every intentional difference.
- Assign ownership and review rules so setup changes cannot drift silently.
Scenario table
| Scenario | Contract pattern | Do not do |
|---|---|---|
| Python application | mise pins Python and uv; uv owns lock/sync/run; README and CI use `uv sync` and `uv run` | Let developers choose random Python versions while CI uses another |
| Polyglot web app | mise pins Node, pnpm, Python, uv, and Terraform; tasks expose dev/test/build | Hide half the setup inside personal shell aliases |
| Infra-heavy repo | Tasks are risk-labeled; deploy/migrate require owners and approvals | Put destructive deploy commands behind a casual `run deploy` task |
| Agent-enabled repo | Coding agents use the same setup contract plus denied paths and command policy | Let each agent invent setup commands from README guesses |
| Open-source project | Keep setup minimal, portable, and documented with fallback commands | Require a private workstation stack without explanation |
| Notebook or learning repo | Pin Python and uv, document data source and small reproducible commands | Commit large outputs or private datasets as setup shortcuts |
| Legacy repo | Introduce contract in stages: pin tools, then tasks, then CI parity | Rewrite all setup rules without fallback or owner review |
Setup contract risk checklist
Secret leakage
Environment convenience can turn into credential leakage. Never commit real tokens, production URLs, or private datasets as defaults.
Task authority creep
A harmless task runner can become a deployment surface. Label tasks by risk and require review for mutation tasks.
Duplicate sources of truth
If README, CI, mise, package scripts, and Makefiles disagree, onboarding becomes guesswork again.
Unowned tool upgrades
Tool versions change generated output, lockfiles, and deploy behavior. Setup files need owners.
Agent mismatch
Coding agents are only reliable if they run in the same environment and obey the same command policy as humans.
Overfitted local setup
A contract should be reproducible, not a dump of one person’s laptop preferences.
Implementation patterns
`mise.toml` as contract
Use `[tools]` for versions, `[env]` only for safe defaults, and `[tasks]` for reviewed commands.
README mirrors contract
Make the first setup path short: install mise, run install, run test, run dev. Put exceptions after the happy path.
CI parity check
CI should use the same pinned tools and core commands unless an intentional difference is documented.
Risk-labeled tasks
Mark tasks as safe, network, mutation, deploy, or release so humans and agents know which need approval.
Secret boundary file
Keep `.env.example` or docs for variable names, but source real secrets from a manager or ignored local file.
Setup change checklist
Every setup change should answer: what changed, who is affected, how CI proves it, how to roll back.
FAQ
Short answers for teams turning setup into a contract.
Is `mise.toml` supposed to replace README?
No. `mise.toml` can be the executable contract, while README explains the happy path, prerequisites, and exceptions.
Should secrets go in mise env settings?
Only safe defaults or non-secret examples. Real secrets should come from a secret manager or ignored local files.
How does uv fit into a setup contract?
uv should own Python dependency sync, lockfiles, and Python project commands. mise can pin uv and Python alongside other tools.
Should CI use mise?
Often yes, if mise is the project source of truth. If CI differs, document why and keep versions aligned.
Related radar
Related RepoDaily briefs
mise Explained: One Project Setup for Dev Tools, Runtime Versions, Environments, and Tasksjdx/mise · Developer tool / CLIuv Explained: Rust-Fast Python Package, Project, Tool, and Python Version Managementastral-sh/uv · Developer tool / CLIgstack: Garry Tan's Open-Source AI Engineering Toolkit for Claude Code and Beyondgarrytan/gstack · Dataset / Public directoryOpenAI Codex CLI Explained: Local Terminal Coding Agent, Sandboxes, Approvals, and Repository Workflowsopenai/codex · Developer tool / CLIClaude Code Explained: Agentic Coding in the Terminal, IDE, GitHub, Hooks, Plugins, and MCPanthropics/claude-code · Developer tool / CLI
Sources
Feedback
Did this page help you make a decision?
Anonymous feedback helps RepoDaily improve what is actually useful.