1 · Plan A human or Planner agent inspects the repository and proposes task-specific boundaries and acceptance commands.
wtcraft
Task contracts and deterministic checks for agent worktrees
Create a worktree and local task contract, compare its changed files with declared Scope and Off-limits entries, and run the verification commands you wrote down. No hosted service or custom agent runtime.
Let the model write the exam, not grade it
2 · Grade externally wtcraft check inspects the Git changeset; wtcraft verify runs the exact declared commands and records their exit codes without an LLM judge.
3 · Test the tests A mechanical runner cannot prove that its test plan is strong. The separate wteval lab uses mutation and property-based testing to probe that acceptance layer.
4 · Review ambiguous findings A human reviews evidence that tools cannot resolve—such as a real test gap versus an equivalent mutant—and decides whether to harden the tests, clarify the specification, or accept the behavior.
Two different questions
wtcraft verify asks whether the declared checks passed. wteval asks whether those checks can detect defects.
What the CLI does today
wtcraft init Scaffolds the local harness and task templates without overwriting existing files.
wtcraft new Creates a Git worktree and seeds a local .worktree-task.md contract.
wtcraft check Compares committed, staged, unstaged, and untracked paths with Scope and Off-limits entries.
wtcraft verify Runs the contract's Verification commands and records a pass or fail result.
wtcraft status --json Lists active worktree contracts through a machine-readable status surface.
Current boundary
wtcraft does not launch agents, choose models, collect token telemetry, sandbox a process, or install a protected pull-request gate. Its checks are explicit commands over local Git facts.
Install
# Node / npm
npm install -g wtcraft
# Python / pipx (recommended)
pipx install wtcraft
# Homebrew (macOS)
brew tap zywkloo/wtcraft https://github.com/zywkloo/wtcraft && brew install wtcraft
Then run wtcraft init in your repository root.
FAQ
What is wtcraft?
wtcraft is a lightweight CLI for worktree-based agent workflows. It scaffolds local task contracts, creates worktrees, checks changed files against declared Scope and Off-limits entries, runs declared verification commands, and exposes status, check, and verify results as JSON.
How is wtcraft different from plain git worktrees or Claude Code's --worktree?
Git worktrees isolate branches. wtcraft adds a local .worktree-task.md contract with Scope, Off-limits, Verification, and lifecycle fields, plus commands that compare those declarations with the Git changeset. The checks run only when you invoke them.
Does wtcraft launch or monitor coding agents?
No. It does not launch agents, route models, enforce role handoffs, sandbox an agent runtime, or track token usage. You run your preferred coding tool separately; wtcraft operates on Git changes and local task files.
Is the task contract a security boundary?
No. The current .worktree-task.md is mutable local state. wtcraft check is a deterministic, on-demand signal, not protected authorization or an automatic pull-request gate.
Who writes and grades the verification checks?
A human or Planner agent proposes task-specific Verification commands after inspecting the repository. wtcraft does not ask the implementing model to judge its own work: it runs the declared commands and records their exit codes. The separate wteval lab examines whether those checks can detect defects, and a human reviews findings whose semantics remain ambiguous.
How do I install wtcraft?
Install globally via npm (npm install -g wtcraft), pipx (pipx install wtcraft), or Homebrew, then run `wtcraft init` in your repository root.