Partials

A partial is a small piece of repo-specific prose that gets inlined into an agent's system prompt at run time. Partials let you teach contractor about your repo's conventions — how to run tests, how to bootstrap a worktree — without forking a schema. They live under contractor/partials/<id>.md and are read fresh on every render, so editing one takes effect on the next agent run.

Wired partial slots

The set of partial ids contractor recognizes is closed: a partial is only useful when some template inlines it, and templates wire partials by id. The current set of wired ids is KNOWN_PARTIAL_IDS, derived from the typed PARTIAL_SLOTS record in packages/cli/src/lib/slash-commands/partials.ts.

Adding a new id is deliberate: a CLI contributor must add an entry to PARTIAL_SLOTS, wire the consumer template, and register a <id>-block marker. The loader's API is permissive (it returns the empty string for unknown ids), but only ids in the slot record are consumed by any template.

The block marker mechanism

Each consuming template wraps the partial-dependent prose in an HTML-comment marker pair:

<!-- verify-block:start -->
… instructions that only apply when the testing partial is present …
{{verifyGuide}}
<!-- verify-block:end -->

At render time, the strategy resolves the partial via readPartial(repoRoot, "testing"), substitutes its trimmed contents into {{verifyGuide}}, and then calls processPartialBlock(rendered, "verify", verifyGuide !== ""):

• Partial is non-empty — processPartialBlock strips the marker lines and keeps the inner content.
• Partial is empty — processPartialBlock strips the entire block (markers and content), so the agent never sees instructions for guidance that does not exist.

The marker name (verify-block, prepare-block) and the slot variable ({{verifyGuide}}, {{prepareGuide}}) are not always the partial id — they're configured per slot in PARTIAL_SLOTS:

{
  testing: { id: "testing", variable: "verifyGuide", blockMarker: "verify", … },
  prepare: { id: "prepare", variable: "prepareGuide", blockMarker: "prepare", … },
}

The slot record is the single source of truth: doctor's wiring check, the strategy renderers, the prepare instruction renderer, and the drift-detection test all derive from it.

Resolution order

readPartial(repoRoot, id) walks three sources in order and returns the first hit:

1. User partial — contractor/partials/<id>.md under repoRoot. Read and trimmed; if non-empty, returned.
2. Shipped partial — packages/cli/schemas/partials/<id>.md. Read and trimmed; if present, returned. Today only prepare.md ships a default.
3. Empty string — when neither file exists or both are whitespace-only.

A whitespace-only user file falls through to the shipped partial, so saving an empty user file does not mask the default. The loader re-reads on every call, which means edits to contractor/partials/testing.md take effect on the next agent run without restarting the CLI or dashboard.

The fallback chain has a useful consequence: a repo that does not author contractor/partials/testing.md simply omits the verify block from the implement prompt — the agent gets the stack-agnostic prose with no embedded test command. A repo that does not author contractor/partials/prepare.md falls back to the shipped stack-agnostic prepare prose, which tells the agent to detect the stack itself.

Authoring

/contractor:setup walks you through authoring the two wired partials with a recommended structure for each. See the authoring partials guide for a hands-on walk-through; this page covers the mechanism, not the content.