wtcraft

Git-native agent governance core.

wtcraft is a lightweight governance core for worktree-based agent workflows. It defines task contracts, tracks lifecycle state, and exposes deterministic scope and verification checks for CLIs, agents, and graphical clients.

Install

pipx install wtcraft       # pip / pipx (recommended — isolated venv)
npm install -g wtcraft     # npm (global)
brew tap zywkloo/wtcraft https://github.com/zywkloo/wtcraft && brew install wtcraft

Short alias available after install: wtc

Quick Start

wtcraft --version                        # print the installed CLI version
wtc agent init                          # create AGENTS.md + CLAUDE.md; no Git required
wtcraft init                            # scaffold harness; no Git required
wtcraft init --local                    # scaffold locally; ignore via .git/info/exclude
wtcraft patch                           # append routing stubs to CLAUDE.md / AGENTS.md
wtcraft lang install --lang zh-CN       # enforce output language in CLAUDE.md
wtcraft new feat/my-task                # create worktree + task contract
wtcraft new --base origin/main feat/x   # override the base branch/ref explicitly
wtcraft status                          # list active worktree contracts
wtcraft capabilities --json             # discover machine-protocol features
wtcraft status --json --repo /repo      # machine-readable status for a target repo
wtcraft check <worktree-name-or-path>   # verify Scope / Off-limits
wtcraft verify <worktree-name-or-path>  # run Verification commands

wtcraft new resolves its base in this order: --base, then WTCRAFT_BASE_BRANCH, then origin/HEAD, then local main, local master, local develop, and finally the current branch.

After running wtcraft init, you can use these slash commands in Claude Code:

• /planwt <task description>: Plan task + create worktree
• /finishwt <worktree-name>: Run verification and finish
• /statuswt: List active worktree task files

Suggested Workflow Roles

These roles and the models in role-models.yml are editable workflow guidance. The current CLI does not launch agents, route models, enforce role handoffs, or run token telemetry.

• Orchestrator (e.g., Gemini 3.6 Flash): An optional coordination profile for environment and Git logistics. wtcraft does not launch, route, or monitor this role.

• Planner (e.g., Claude Opus 5): A suggested planning profile that writes the local task contract (.worktree-task.md) with Scope, Off-limits, and Verification sections.

• Executor (e.g., GPT-5.5): A suggested implementation profile working in a dedicated Git worktree. wtcraft check detects out-of-scope changes when invoked; it does not sandbox the agent runtime.

• Verifier (e.g., Claude Opus 5): A human or agent review profile that can consume check --json and verify --json. wtcraft does not automatically run a review agent or a PR gate.

• Finisher (e.g., Gemini Flash 3.6): A suggested workflow profile that runs wtcraft check and wtcraft verify, then performs the repository's normal handoff and cleanup steps. Token telemetry is not implemented.

Commands

Why

AI agents (and human contributors) hallucinate, over-engineer, and accidentally break unrelated code. While parallel agents are useful, raw parallelism creates common problems: unclear handoffs, context pollution, and file collisions.

wtcraft provides a small, inspectable verification harness. It focuses on handoff, task boundaries, and deterministic checks rather than agent runtime control.

• Git-Native Task Isolation: Keep parallel task changes separated with git worktree.
• Task Contracts: Make agent handoffs explicit with a per-task whitelist in .worktree-task.md.
• Deterministic Checks: Detect out-of-scope files and run declared verification commands on demand.
• Machine-Readable Facts: Expose status, scope results, and verification results as stable JSON.

No hosted platform or custom agent runtime is required. You can use Aider, Cursor, Claude, or another coding agent because the checks operate on Git and the worktree changeset.

The current local task contract is mutable and is not, by itself, a security boundary. A reviewed policy envelope and protected required check are planned for the next milestone; see the Roadmap.

Docs

• Protocol Contracts
• Rust Core Extraction ADR
• Roadmap
• Gotchas & Coding Survival Guide
• Principles
• Migration Notes
• Changelog

Testing

bash tests/run_all.sh

License

Apache-2.0. See LICENSE.