Authoring partials

Write contractor/partials/testing.md and contractor/partials/prepare.md so contractor knows how to run your repo.

Partials are short, repo-specific prose files that contractor inlines into agent prompts at run time. The two ids contractor wires today are:

testing — read on every implement-phase agent run. Names your default test command, subset variants, pre-test setup, flaky areas, and the scope of "verified".
prepare — read on every synthetic worktree-prepare run. Names your install command, a cheap readiness probe, and any post-install setup.

This guide is the long form of /contractor:setup. If you have Claude Code installed, run that slash command and it will probe your repo and walk you through the same recommendations interactively. If you'd rather author from scratch — or you want to understand what /contractor:setup is teaching — read on.

The mechanism (slot ids, block markers, the user → shipped → empty fallback) is documented in Partials. This page is about content: what to write, how short to keep it, and a concrete starting point for each file.

Why these two files matter

Without contractor/partials/testing.md, the implement agent guesses your test command from package.json scripts or framework conventions. That guess is usually right for greenfield repos and often wrong for monorepos, repos with multiple test runners, or repos where the obvious command is too slow to use as a default. Wrong guesses surface as wasted iterations: the agent runs the whole-monorepo suite when it could have run a single package, or commits without verifying because it picked a lint script over a test script.

Without contractor/partials/prepare.md, the prepare agent detects your stack from lockfiles and guesses an install command. The guess is right more often here — pnpm install --frozen-lockfile is hard to get wrong when pnpm-lock.yaml is sitting at the repo root — but the readiness probe is purely a guess, which means prepare runs in full on every HEAD change instead of fast-pathing when dependencies are already there.

Both partials are inlined into every relevant agent run, so brevity matters. Every line you add is paid for in tokens on every run. Aim for ~20–60 lines for testing.md and ~10–30 lines for prepare.md. If a partial grows past a page, something belongs elsewhere — the design doc, a code comment, or nowhere.

`contractor/partials/testing.md`

Recommended structure (in order):

Default test command. The single command an agent should run before committing a task group when it has no reason to pick something narrower. Make it unambiguous. This is the "when in doubt, run this" command — the test the agent reaches for if the diff doesn't suggest a smaller scope.
Subset variants. For monorepos: per-package, per-file, watch-mode. The agent picks based on the actual diff; your job is to name the options. Skip this section for single-package repos.
Pre-test setup. Migrations, fixtures, environment variables, services, build steps that must run first. Anything implicit that a fresh clone would miss. Install-level setup belongs in prepare.md, not here.
Known-flaky areas. Tests that flake under agentic runs. Name them. Suggest retry-once, skip, or exclude. Be specific — "the e2e suite is slow" is useless; "packages/cli/src/smoke.e2e.test.ts spawns real subprocesses; retry once on timeout before treating as a regression" is useful.
Scope of "verified". What the verify loop is meant to catch (unit + integration) versus what it is NOT meant to catch (perf benchmarks, e2e suites, manual QA). Keep the loop tight; the agent shouldn't try to run hours-long suites between commits.
Test layout and naming conventions. Where tests live, how they're named (*.test.ts, test_*.py, colocated vs. __tests__/), mocking conventions.

Frame this list as recommended, not mandatory. A repo with no flaky tests skips section 4. A single-package repo skips section 2. Adapt.

A critical rule for monorepos: the agent picks the subset based on the actual change, not on a declared blueprint scope. The guide names the options; it does NOT try to encode a {{scope}}-style substitution. Write prose like "for a change touching only packages/foo/**, use pnpm --filter foo test; for a cross-package change, run the full suite."

Example

For a TypeScript pnpm monorepo (keep yours this short or shorter):

# Verifying this repo
 
## Default
 
`pnpm test` — runs the full vitest suite across every workspace. Use this when in doubt, or for any change that spans more than one package.
 
## Subset variants
 
- One package: `pnpm --filter @scope/pkg test` — use when your change touches only that package.
- One file: `pnpm --filter @scope/pkg test path/to/foo.test.ts` — use when iterating on a single failing test.
 
## Pre-test setup
 
- `pnpm install` must have run.
- No database or external services required for the unit suite.
 
## Known-flaky areas
 
- `packages/cli/src/smoke.e2e.test.ts` spawns real subprocesses; retry once on timeout before treating as a regression.
- Integration tests under `e2e/` require a live Postgres — excluded from `pnpm test`.
 
## Scope of "verified"
 
- Covered: unit tests and integration tests that run in-process.
- NOT covered: `e2e/` (requires stack), `perf/` (benchmarks), manual browser QA.
 
## Test layout
 
- Colocated `*.test.ts` next to source files.
- No mocking framework — direct imports and filesystem fixtures under `__fixtures__/`.

For a single-package Python pytest repo with no flaky tests, the file might be ten lines: a default pytest invocation, a one-line note that fixtures live under tests/fixtures/, and a one-line scope statement. Match the size to the size of the truth.

`contractor/partials/prepare.md`

Recommended structure (in order):

Install command. The exact one-line install or bootstrap command this repo uses. Match CI where possible (e.g. pnpm install --frozen-lockfile, npm ci, uv sync --frozen, poetry install --no-interaction, bundle install). Lockfile-respecting flags matter — reproducibility is the whole point.
Readiness probe. A cheap command the agent can run FIRST to decide whether the environment is already prepared. If the probe passes, the agent skips the install step. Examples: typecheck, dry-run build, pnpm install --frozen-lockfile --dry-run, python -c 'import <pkg>', make check-deps. Must be fast.
Post-install setup. Required code generation, env-file scaffolding, or migration steps. Only list steps that are BOTH required AND cheap to run every time.
Guardrails. Repo-specific "do not do X" notes. The shipped prepare prompt already forbids editing source files, committing, or running tests; add anything specific to your repo (e.g. "do not run pnpm build here — it is slow and the implement step runs it").

Frame this list as recommended, not mandatory. A repo with no post-install setup skips section 3. A repo with no extra guardrails skips section 4.

Example

For a TypeScript pnpm monorepo:

# Preparing a worktree for this repo
 
## Install
 
`pnpm install --frozen-lockfile` — matches CI. Do NOT pass `--no-frozen-lockfile`.
 
## Readiness probe
 
`pnpm -r exec node -e 'process.exit(0)'` — succeeds only if every workspace has its deps installed. If it fails, run the install command above, then re-run the probe.
 
## Post-install
 
- No code generation required.
- No env-file setup required for the unit suite.
 
## Do not
 
- Do not run `pnpm build` here — expensive, and the implement step handles builds on demand.
- Do not run tests — verification happens inside the implement session, not here.

For a Python uv project this might be three lines: install command, uv run python -c 'import <pkg>' as the readiness probe, nothing else.

Verifying

Once both files are in place, run contractor doctor from the repo root. The "Partials wiring" section reports each known partial id (testing, prepare) and whether your repo authors it, falls back to the shipped default, or returns empty:

Partials wiring
  testing: present (contractor/partials/testing.md)
  prepare: present (contractor/partials/prepare.md)

You can also confirm the inlined content directly:

# Re-render the slash commands and inspect what the agent sees.
contractor ai install --provider claude
cat .claude/commands/blueprint/implement.md | grep -A50 'verify-block:start'

If you have Claude Code installed, /contractor:setup runs through this same checklist interactively, with repo-aware probes (which lockfile is present, which framework is wired up) and an offer to adapt the examples to your stack.

Editing later

Both files are read fresh on every relevant agent run, so edits take effect immediately — no contractor ai install rebuild required. The shipped slash commands embed the partials at install time, so if you want the on-disk slash command files in .claude/commands/blueprint/ to reflect a partial edit, you do need to re-run contractor ai install. The agent runtime itself reads the partials at render time, not the slash command files, so an edit to contractor/partials/testing.md is live on the next run regardless.

Legacy paths

Older repos may still carry:

contractor/VERIFY.md — the legacy path for the testing partial. Move it to contractor/partials/testing.md. Contractor no longer reads the old path.
A verify: field in contractor/config.yaml — removed. Delete the line; contractor emits a warning when it sees one.
A worktree.bootstrap field in contractor/config.yaml — removed. Author contractor/partials/prepare.md instead.

Doctor flags the first two when it sees them, so you don't have to remember.