https://github.com/zywkloo/wtcraft
Git-native agent governance core — task contracts and deterministic scope/verification checks that keep coding agents in their lanes.
https://github.com/zywkloo/wtcraft
agent antigravity antigravity-cli claude-code claude-skills codex gemini gemini-cli govenance harness-engineering skills vibe-coding
Last synced: 8 days ago
JSON representation
Git-native agent governance core — task contracts and deterministic scope/verification checks that keep coding agents in their lanes.
- Host: GitHub
- URL: https://github.com/zywkloo/wtcraft
- Owner: zywkloo
- License: apache-2.0
- Created: 2026-05-27T04:02:34.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-24T18:23:33.000Z (17 days ago)
- Last Synced: 2026-06-24T20:12:05.046Z (17 days ago)
- Topics: agent, antigravity, antigravity-cli, claude-code, claude-skills, codex, gemini, gemini-cli, govenance, harness-engineering, skills, vibe-coding
- Language: Shell
- Homepage: https://www.npmjs.com/package/wtcraft
- Size: 3.42 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Roadmap: docs/roadmap.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 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.
[](https://www.npmjs.com/package/wtcraft)
[](https://pypi.org/project/wtcraft/)
[](https://github.com/zywkloo/wtcraft/actions/workflows/ci.yml)
[](https://github.com/zywkloo/wtcraft/releases)
[](./LICENSE)
## Install
```bash
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
```bash
wtcraft --version # print the installed CLI version
wtcraft init # scaffold harness into current repo
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 # verify Scope / Off-limits
wtcraft verify # 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 `: Plan task + create worktree
- `/finishwt `: Run verification and finish
- `/statuswt`: List active worktree task files
## The Layered Agent Team
* **Orchestrator (e.g., Gemini 3.5 Flash)**: Sits at the top of the workflow. Highly tool-agentic, low-latency, and coordinates the overall project state. It focuses on environment orchestration, git logistics, verification suites, and telemetry. Core features like cross-repository worktree monitoring, automated session summarization, and active agent handoff routing are **coming soon (upcoming role integration)**.
* **Planner (e.g., Claude Opus 4.8)**: The slow, high-reasoning "architect". It reads the requirement, analyzes the code context, and designs the bounded execution contract (`.worktree-task.md`) specifying Scope, Off-limits, and Verification steps.
* **Executor (e.g., GPT-5.4)**: The precision coder. It is budget-friendly, highly focused, and operates strictly inside the isolated worktree sandbox, adhering strictly to the contract boundaries.
* **Verifier (e.g., Claude Opus Fable 5)**: The quality gatekeeper. It automatically conducts code reviews, checks for style/security constraints, and runs PR-level checks. If verification fails, it can trigger a feedback loop back to the Planner or Executor.
* **Finisher (e.g., Gemini Flash 3.5)**: Performs deterministic boundary validation (`wtcraft check`), test suite verification (`wtcraft verify`), and cleans up local worktree assets after a successful merge to keep the development disk clean. Additionally, in an upcoming release (integrating with PR #12), the Finisher will aggregate and report **token telemetry** to track cost, budget, and API usage per agent model (**Coming Soon**).
## Commands
| Command | Arguments | What it does |
|---|---|---|
| `wtcraft init` | `[--patch-agent-files] [--local] [--repo ]` | Scaffold harness files. Does not overwrite. `--local` keeps scaffold clone-local via Git-resolved `.git/info/exclude`. |
| `wtcraft patch` | `[--repo ]` | Alias for `init --patch-agent-files`. Appends routing stubs to `CLAUDE.md` / `AGENTS.md`. |
| `wtcraft unpatch` | `[--repo ]` | Remove the routing stub from `CLAUDE.md` / `AGENTS.md`. |
| `wtcraft lang` | `install\|remove [--repo ]` | Add or remove language enforcement rules (e.g. `install --lang zh-CN`). |
| `wtcraft new` | `[--repo ] [--base ] ` | Create a worktree and local `.worktree-task.md` contract. |
| `wtcraft status` | `[--json] [--repo ]` | List active worktree tasks and their status. `--json` is the machine-readable status surface. |
| `wtcraft check` | `[--json] [--repo ] ` | Verify the worktree's changes stay within Scope / Off-limits boundaries. |
| `wtcraft verify` | `[--json] [--repo ] ` | Run the Verification commands declared in the worktree's contract. |
| `wtcraft capabilities` | `--json` | Report supported machine-protocol features for external launchers. |
| `wtcraft --version` | — | Print the installed CLI version. |
| `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
- [Protocol Contracts](./docs/protocol/README.md)
- [Rust Core Extraction ADR](./docs/adr/006-rust-core-extraction.md)
- [Roadmap](./docs/roadmap.md)
- [Gotchas & Coding Survival Guide](./docs/gotchas/README.md)
- [Principles](./docs/principles.md)
- [Migration Notes](./docs/migration.md)
- [Changelog](./CHANGELOG.md)
## Testing
```bash
bash tests/run_all.sh
```
## License
Apache-2.0. See [LICENSE](./LICENSE).