{"id":51389628,"url":"https://github.com/zywkloo/wtcraft","last_synced_at":"2026-07-03T22:08:22.248Z","repository":{"id":360601467,"uuid":"1250891573","full_name":"zywkloo/wtcraft","owner":"zywkloo","description":"Git-native agent governance core — task contracts and deterministic scope/verification checks that keep coding agents in their lanes.","archived":false,"fork":false,"pushed_at":"2026-06-24T18:23:33.000Z","size":3588,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T20:12:05.046Z","etag":null,"topics":["agent","antigravity","antigravity-cli","claude-code","claude-skills","codex","gemini","gemini-cli","govenance","harness-engineering","skills","vibe-coding"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/wtcraft","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zywkloo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-27T04:02:34.000Z","updated_at":"2026-06-24T18:23:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zywkloo/wtcraft","commit_stats":null,"previous_names":["zywkloo/wtcraft"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/zywkloo/wtcraft","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zywkloo%2Fwtcraft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zywkloo%2Fwtcraft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zywkloo%2Fwtcraft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zywkloo%2Fwtcraft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zywkloo","download_url":"https://codeload.github.com/zywkloo/wtcraft/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zywkloo%2Fwtcraft/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35102815,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","antigravity","antigravity-cli","claude-code","claude-skills","codex","gemini","gemini-cli","govenance","harness-engineering","skills","vibe-coding"],"created_at":"2026-07-03T22:08:21.491Z","updated_at":"2026-07-03T22:08:22.241Z","avatar_url":"https://github.com/zywkloo.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wtcraft\n\n\u003e **Git-native agent governance core.**\n\u003e\n\u003e `wtcraft` is a lightweight governance core for worktree-based agent\n\u003e workflows. It defines task contracts, tracks lifecycle state, and exposes\n\u003e deterministic scope and verification checks for CLIs, agents, and graphical\n\u003e clients.\n\n[![npm version](https://img.shields.io/npm/v/wtcraft.svg?logo=npm\u0026maxAge=300)](https://www.npmjs.com/package/wtcraft)\n[![PyPI version](https://img.shields.io/pypi/v/wtcraft.svg?logo=pypi\u0026maxAge=300)](https://pypi.org/project/wtcraft/)\n[![CI](https://github.com/zywkloo/wtcraft/actions/workflows/ci.yml/badge.svg)](https://github.com/zywkloo/wtcraft/actions/workflows/ci.yml)\n[![GitHub release](https://img.shields.io/github/v/release/zywkloo/wtcraft?logo=github\u0026maxAge=300)](https://github.com/zywkloo/wtcraft/releases)\n[![License](https://img.shields.io/github/license/zywkloo/wtcraft)](./LICENSE)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/zywkloo/wtcraft/main/wtcraft-icon.PNG\" alt=\"wtcraft icon\" width=\"120\" /\u003e\n\u003c/p\u003e\n\n## Install\n\n```bash\npipx install wtcraft       # pip / pipx (recommended — isolated venv)\nnpm install -g wtcraft     # npm (global)\nbrew tap zywkloo/wtcraft https://github.com/zywkloo/wtcraft \u0026\u0026 brew install wtcraft\n```\n\nShort alias available after install: `wtc`\n\n## Quick Start\n\n```bash\nwtcraft --version                        # print the installed CLI version\nwtcraft init                            # scaffold harness into current repo\nwtcraft init --local                    # scaffold locally; ignore via .git/info/exclude\nwtcraft patch                           # append routing stubs to CLAUDE.md / AGENTS.md\nwtcraft lang install --lang zh-CN       # enforce output language in CLAUDE.md\nwtcraft new feat/my-task                # create worktree + task contract\nwtcraft new --base origin/main feat/x   # override the base branch/ref explicitly\nwtcraft status                          # list active worktree contracts\nwtcraft capabilities --json             # discover machine-protocol features\nwtcraft status --json --repo /repo      # machine-readable status for a target repo\nwtcraft check \u003cworktree-name-or-path\u003e   # verify Scope / Off-limits\nwtcraft verify \u003cworktree-name-or-path\u003e  # run Verification commands\n```\n\n`wtcraft new` resolves its base in this order: `--base`, then\n`WTCRAFT_BASE_BRANCH`, then `origin/HEAD`, then local `main`, local `master`,\nlocal `develop`, and finally the current branch.\n\nAfter running `wtcraft init`, you can use these slash commands in Claude Code:\n- `/planwt \u003ctask description\u003e`: Plan task + create worktree\n- `/finishwt \u003cworktree-name\u003e`: Run verification and finish\n- `/statuswt`: List active worktree task files\n\n## The Layered Agent Team\n\n\n\u003c!-- wtcraft:models:start --\u003e\n* **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)**.\n\n* **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.\n\n* **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.\n\n* **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.\n\n* **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**).\n\u003c!-- wtcraft:models:end --\u003e\n\n## Commands\n\n| Command | Arguments | What it does |\n|---|---|---|\n| `wtcraft init` | `[--patch-agent-files] [--local] [--repo \u003cpath\u003e]` | Scaffold harness files. Does not overwrite. `--local` keeps scaffold clone-local via Git-resolved `.git/info/exclude`. |\n| `wtcraft patch` | `[--repo \u003cpath\u003e]` | Alias for `init --patch-agent-files`. Appends routing stubs to `CLAUDE.md` / `AGENTS.md`. |\n| `wtcraft unpatch` | `[--repo \u003cpath\u003e]` | Remove the routing stub from `CLAUDE.md` / `AGENTS.md`. |\n| `wtcraft lang` | `install\\|remove [--repo \u003cpath\u003e]` | Add or remove language enforcement rules (e.g. `install --lang zh-CN`). |\n| `wtcraft new` | `[--repo \u003cpath\u003e] [--base \u003cbranch\u003e] \u003ctype/name\u003e` | Create a worktree and local `.worktree-task.md` contract. |\n| `wtcraft status` | `[--json] [--repo \u003cpath\u003e]` | List active worktree tasks and their status. `--json` is the machine-readable status surface. |\n| `wtcraft check` | `[--json] [--repo \u003cpath\u003e] \u003cworktree-path-or-name\u003e` | Verify the worktree's changes stay within Scope / Off-limits boundaries. |\n| `wtcraft verify` | `[--json] [--repo \u003cpath\u003e] \u003cworktree-path-or-name\u003e` | Run the Verification commands declared in the worktree's contract. |\n| `wtcraft capabilities` | `--json` | Report supported machine-protocol features for external launchers. |\n| `wtcraft --version` | — | Print the installed CLI version. |\n| `wtcraft help` | `[command]` | Show usage. |\n\n## Why\n\nAI 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.\n\n`wtcraft` provides a definitive safety harness. It focuses on handoff, boundaries, and deterministic containment, not just concurrency. \n\n- **Git-Native Containment:** Keep agent work physically isolated with `git worktree`.\n- **Task Contracts:** Make agent handoffs explicit with a per-task whitelist in `.worktree-task.md`.\n- **Deterministic Gating:** Enforce scope boundaries at the commit/PR level. If a task isn't in scope, the code doesn't merge.\n- **Budget-Aware:** Avoid infinite LLM loops and track API usage per worktree.\n\nNo 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.\n\n## Docs\n\n- [Protocol Contracts](./docs/protocol/README.md)\n- [Rust Core Extraction ADR](./docs/adr/006-rust-core-extraction.md)\n- [Roadmap](./docs/roadmap.md)\n- [Gotchas \u0026 Coding Survival Guide](./docs/gotchas/README.md)\n- [Principles](./docs/principles.md)\n- [Migration Notes](./docs/migration.md)\n- [Changelog](./CHANGELOG.md)\n\n## Testing\n\n```bash\nbash tests/run_all.sh\n```\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzywkloo%2Fwtcraft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzywkloo%2Fwtcraft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzywkloo%2Fwtcraft/lists"}