wtcraft 0.4.0

A lightweight, git-native scaffolding for bounded multi-agent coding

wtcraft

Zero-trust containment and governance for AI-generated code. Provide a definitive safety harness for agentic coding. Let your AI write code; wtcraft ensures it strictly obeys boundaries, scopes, and verification rules before it ever touches your main branch.

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

Quick Start

wtcraft init                            # scaffold harness into current repo
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 status                          # list active worktree contracts
wtcraft check <worktree-name-or-path>   # verify Scope / Off-limits
wtcraft verify <worktree-name-or-path>  # run Verification commands

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

The Layered Agent Team

graph TD
    Orchestrator["Orchestrator (gemini:Gemini 3.5 Flash)"] -->|Subtask| Planner["Planner (claude:Claude Opus 4.8)"]
    Planner -->|Task Contract| Executor["Executor (codex:GPT-5.4)"]
    Executor -->|PR| Verifier["Verifier (claude:Claude Opus Fable 5)"]
    Verifier -.->|Retry| Planner
    Verifier -.->|Retry| Executor
    Verifier -->|Merge| Finisher["Finisher (gemini:Gemini Flash 3.5)"]

Commands

Command	Arguments	What it does
wtcraft init	[--patch-agent-files]	Scaffold harness files. Does not overwrite.
wtcraft patch	—	Alias for init --patch-agent-files. Appends routing stubs to CLAUDE.md / AGENTS.md.
wtcraft unpatch	—	Remove the routing stub from CLAUDE.md / AGENTS.md.
wtcraft lang	install|remove	Add or remove language enforcement rules (e.g. install --lang zh-CN).
wtcraft new	<type/name>	Create a worktree and local .worktree-task.md contract.
wtcraft status	—	List active worktree tasks and their status.
wtcraft check	<worktree-path-or-name>	Verify the worktree's changes stay within Scope / Off-limits boundaries.
wtcraft verify	<worktree-path-or-name>	Run the Verification commands declared in the worktree's contract.
wtcraft help	[command]	Show usage.

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 definitive safety harness. It focuses on handoff, boundaries, and deterministic containment, not just concurrency.

• Git-Native Containment: Keep agent work physically isolated with git worktree.
• Task Contracts: Make agent handoffs explicit with a per-task whitelist in .worktree-task.md.
• Deterministic Gating: Enforce scope boundaries at the commit/PR level. If a task isn't in scope, the code doesn't merge.
• Budget-Aware: Avoid infinite LLM loops and track API usage per worktree.

No hosted platform is required. No custom runtime is required. You can use Aider, Cursor, Claude, or Devin — wtcraft simply wraps your working directory in a zero-trust governance layer.

Docs

• Roadmap
• Gotchas & Coding Survival Guide
• Principles
• Migration Notes
• Changelog

Testing

bash tests/run_all.sh

License

Apache-2.0. See LICENSE.