wtcraft 0.3.0__py3-none-any.whl

wtcraft/__init__.py

@@ -0,0 +1,2 @@
+# wtcraft — git-native harness helper
+__version__ = "0.3.0"

wtcraft/_cli.py

@@ -0,0 +1,41 @@
+"""
+Entry point for pip / pipx installations.
+
+Locates the bundled shell script and templates, injects WTCRAFT_TEMPLATE_DIR
+into the environment, then exec-replaces itself with bash.
+"""
+
+import os
+import sys
+
+
+def main() -> None:
+    pkg_dir = os.path.dirname(os.path.abspath(__file__))
+
+    shell_path = os.path.join(pkg_dir, "_shell.sh")
+    tmpl_dir = os.path.join(pkg_dir, "templates")
+
+    # Editable / source installs: fall back to the repo layout
+    if not os.path.isfile(shell_path):
+        shell_path = os.path.join(pkg_dir, "..", "..", "scripts", "wtcraft")
+    if not os.path.isdir(tmpl_dir):
+        tmpl_dir = os.path.join(pkg_dir, "..", "..", "templates")
+
+    shell_path = os.path.realpath(shell_path)
+    tmpl_dir = os.path.realpath(tmpl_dir)
+
+    if not os.path.isfile(shell_path):
+        print(f"wtcraft: cannot locate shell script at {shell_path}", file=sys.stderr)
+        sys.exit(1)
+    if not os.path.isdir(tmpl_dir):
+        print(f"wtcraft: cannot locate templates at {tmpl_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    env = os.environ.copy()
+    env["WTCRAFT_TEMPLATE_DIR"] = tmpl_dir
+
+    os.execve("/bin/bash", ["/bin/bash", shell_path] + sys.argv[1:], env)
+
+
+if __name__ == "__main__":
+    main()

wtcraft/_shell.sh

@@ -0,0 +1,537 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "${SELF_DIR}/.." && pwd)"
+# WTCRAFT_TEMPLATE_DIR overrides the default; pip/Homebrew installs set this.
+TEMPLATE_DIR="${WTCRAFT_TEMPLATE_DIR:-${ROOT_DIR}/templates}"
+
+usage() {
+  cat <<'EOF'
+wtcraft - git-native harness helper
+
+Usage:
+  wtcraft init [--patch-agent-files]
+  wtcraft status
+  wtcraft new <type/name>
+  wtcraft check <worktree-path-or-name>
+  wtcraft verify <worktree-path-or-name>
+  wtcraft help [command]
+EOF
+}
+
+usage_init() {
+  cat <<'EOF'
+wtcraft init [--patch-agent-files]
+
+  Scaffold harness files into the current git repository.
+  Existing files are never overwritten.
+
+  Options:
+    --patch-agent-files   Append a wtcraft routing stub to CLAUDE.md and
+                          AGENTS.md (opt-in only; never overwrites content)
+
+  Creates:
+    .agent-harness/planner.md
+    .agent-harness/executor.md
+    .agent-harness/finisher.md
+    .claude/commands/planwt.md
+    .claude/commands/finishwt.md
+    .worktree-task.template.md
+EOF
+}
+
+usage_status() {
+  cat <<'EOF'
+wtcraft status
+
+  List active worktree task files and their frontmatter metadata.
+  Shows: task file path, status, agent, and priority.
+EOF
+}
+
+usage_new() {
+  cat <<'EOF'
+wtcraft new <type/name>
+
+  Create a new git worktree from the base branch and seed it with a
+  .worktree-task.md contract file.
+
+  Arguments:
+    <type/name>   Branch and worktree path (e.g. feat/auth-refactor)
+
+  Environment:
+    WTCRAFT_BASE_BRANCH   Base branch to branch from (default: develop)
+EOF
+}
+
+usage_check() {
+  cat <<'EOF'
+wtcraft check <worktree-path-or-name>
+
+  Compare files changed in the worktree against the Scope and Off-limits
+  sections of the .worktree-task.md contract.
+
+  Scope pattern syntax:
+    - Exact file path:      src/index.ts
+    - Directory prefix:     src/components  (matches anything under it)
+    - Glob (* any chars):   *.md, src/*.ts  (* matches path separators too)
+    - Recursive glob:       src/**/*.ts
+
+  Exit codes:
+    0   No violations detected
+    2   One or more Scope or Off-limits violations found
+EOF
+}
+
+usage_verify() {
+  cat <<'EOF'
+wtcraft verify <worktree-path-or-name>
+
+  Run verification commands listed in the Verification section of the
+  .worktree-task.md contract. Each command runs inside the worktree directory.
+
+  Output includes per-command timing, exit codes, and a summary table.
+
+  Exit codes:
+    0   All commands passed
+    3   One or more commands failed
+EOF
+}
+
+cmd_help() {
+  if [ $# -eq 0 ]; then
+    usage
+    return 0
+  fi
+  case "$1" in
+    init)   usage_init ;;
+    status) usage_status ;;
+    new)    usage_new ;;
+    check)  usage_check ;;
+    verify) usage_verify ;;
+    help)   usage ;;
+    *) die "no help topic for: $1" ;;
+  esac
+}
+
+die() {
+  echo "Error: $*" >&2
+  exit 1
+}
+
+ensure_repo_root() {
+  git rev-parse --show-toplevel >/dev/null 2>&1 || die "not inside a git repository"
+}
+
+copy_if_missing() {
+  local src="$1"
+  local dst="$2"
+  if [ -e "$dst" ]; then
+    return 0
+  fi
+  mkdir -p "$(dirname "$dst")"
+  cp "$src" "$dst"
+}
+
+append_managed_block_if_missing() {
+  local file="$1"
+  local block="$2"
+  local start_marker="$3"
+
+  if [ ! -f "$file" ]; then
+    echo "Skipped (not found): ${file}"
+    return 0
+  fi
+
+  if grep -qF "$start_marker" "$file"; then
+    echo "Already patched: ${file}"
+    return 0
+  fi
+
+  printf "\n%s\n" "$block" >>"$file"
+  echo "Patched: ${file}"
+}
+
+patch_agent_files() {
+  local repo_root="$1"
+  local claude_file="${repo_root}/CLAUDE.md"
+  local agents_file="${repo_root}/AGENTS.md"
+
+  local claude_start="<!-- wtcraft:claude:start -->"
+  local agents_start="<!-- wtcraft:agents:start -->"
+
+  local claude_block
+  claude_block="$(cat <<'EOF'
+<!-- wtcraft:claude:start -->
+## wtcraft routing
+For complex or parallel tasks, read `.agent-harness/planner.md`.
+For worktree finishing, read `.agent-harness/finisher.md`.
+<!-- wtcraft:claude:end -->
+EOF
+)"
+
+  local agents_block
+  agents_block="$(cat <<'EOF'
+<!-- wtcraft:agents:start -->
+## wtcraft routing
+If `.worktree-task.md` exists in the current worktree root, read `.agent-harness/executor.md` first and follow task Scope, Off-limits, and Verification.
+<!-- wtcraft:agents:end -->
+EOF
+)"
+
+  append_managed_block_if_missing "$claude_file" "$claude_block" "$claude_start"
+  append_managed_block_if_missing "$agents_file" "$agents_block" "$agents_start"
+}
+
+cmd_init() {
+  ensure_repo_root
+  local patch_agent=false
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --patch-agent-files) patch_agent=true ;;
+      *) die "unknown init option: $1" ;;
+    esac
+    shift
+  done
+
+  local repo_root
+  repo_root="$(git rev-parse --show-toplevel)"
+
+  copy_if_missing "${TEMPLATE_DIR}/.agent-harness/planner.md" "${repo_root}/.agent-harness/planner.md"
+  copy_if_missing "${TEMPLATE_DIR}/.agent-harness/executor.md" "${repo_root}/.agent-harness/executor.md"
+  copy_if_missing "${TEMPLATE_DIR}/.agent-harness/finisher.md" "${repo_root}/.agent-harness/finisher.md"
+  copy_if_missing "${TEMPLATE_DIR}/.claude/commands/planwt.md" "${repo_root}/.claude/commands/planwt.md"
+  copy_if_missing "${TEMPLATE_DIR}/.claude/commands/finishwt.md" "${repo_root}/.claude/commands/finishwt.md"
+  copy_if_missing "${TEMPLATE_DIR}/worktrees/.worktree-task.md" "${repo_root}/.worktree-task.template.md"
+
+  cat <<'EOF'
+Initialized wtcraft harness files (existing files were left untouched):
+  .agent-harness/planner.md
+  .agent-harness/executor.md
+  .agent-harness/finisher.md
+  .claude/commands/planwt.md
+  .claude/commands/finishwt.md
+  .worktree-task.template.md
+EOF
+
+  if [ "$patch_agent" = true ]; then
+    echo
+    echo "Applying optional routing stubs to agent files..."
+    patch_agent_files "$repo_root"
+  else
+    echo
+    echo "Agent files were not modified (default behavior)."
+    echo "Use: wtcraft init --patch-agent-files"
+  fi
+}
+
+extract_frontmatter() {
+  local file="$1"
+  local key="$2"
+  awk -v key="$key" '
+    BEGIN { in_fm=0 }
+    /^---$/ {
+      if (in_fm==0) { in_fm=1; next }
+      else { in_fm=0; exit }
+    }
+    in_fm==1 {
+      if ($0 ~ "^" key ":") {
+        sub("^" key ":[[:space:]]*", "", $0)
+        print $0
+        exit
+      }
+    }
+  ' "$file"
+}
+
+cmd_status() {
+  ensure_repo_root
+  local repo_root
+  repo_root="$(git rev-parse --show-toplevel)"
+
+  printf "%-45s %-12s %-10s %-8s\n" "Task File" "Status" "Agent" "Priority"
+  printf "%-45s %-12s %-10s %-8s\n" "---------" "------" "-----" "--------"
+
+  local found=0
+  while IFS= read -r wt; do
+    [ -z "$wt" ] && continue
+    # Skip the primary worktree (repo root), keep only linked worktrees.
+    [ "$wt" = "$repo_root" ] && continue
+    local task rel status agent priority
+    task="${wt}/.worktree-task.md"
+    [ -f "$task" ] || continue
+    found=1
+    rel="${task#"${repo_root}"/}"
+    status="$(extract_frontmatter "$task" "status")"
+    agent="$(extract_frontmatter "$task" "agent")"
+    priority="$(extract_frontmatter "$task" "priority")"
+    status="${status:-unknown}"
+    agent="${agent:-unknown}"
+    priority="${priority:-unknown}"
+    printf "%-45s %-12s %-10s %-8s\n" "$rel" "$status" "$agent" "$priority"
+  done < <(git -C "$repo_root" worktree list --porcelain | awk '/^worktree /{sub(/^worktree /,"",$0); print}')
+
+  if [ "$found" -eq 0 ]; then
+    echo "No worktree task files found under worktrees/."
+  fi
+}
+
+cmd_new() {
+  ensure_repo_root
+  [ $# -eq 1 ] || die "new expects exactly one argument: <type/name>"
+  local branch="$1"
+  local repo_root base_branch wt_path
+  repo_root="$(git rev-parse --show-toplevel)"
+  base_branch="${WTCRAFT_BASE_BRANCH:-develop}"
+  wt_path="${repo_root}/worktrees/${branch}"
+
+  [ ! -e "$wt_path" ] || die "worktree path already exists: ${wt_path}"
+  git -C "$repo_root" show-ref --verify --quiet "refs/heads/${branch}" && die "branch already exists: ${branch}"
+
+  mkdir -p "${repo_root}/worktrees"
+  git -C "$repo_root" worktree add "$wt_path" -b "$branch" "$base_branch"
+
+  local task_file="${wt_path}/.worktree-task.md"
+  cp "${TEMPLATE_DIR}/worktrees/.worktree-task.md" "$task_file"
+
+  local today
+  today="$(date +%F)"
+  sed -i.bak "s|^branch: .*|branch: ${branch}|" "$task_file"
+  sed -i.bak "s|^created: .*|created: ${today}|" "$task_file"
+  sed -i.bak "s|^base: .*|base: ${base_branch}|" "$task_file"
+  rm -f "${task_file}.bak"
+
+  cat <<EOF
+Created worktree:
+  ${wt_path}
+Created task contract:
+  ${task_file}
+EOF
+}
+
+collect_section_items() {
+  local file="$1"
+  local section="$2"
+  awk -v section="$section" '
+    BEGIN { in_section=0 }
+    $0 ~ "^##[[:space:]]+" section "$" { in_section=1; next }
+    in_section==1 && $0 ~ "^##[[:space:]]+" { in_section=0 }
+    in_section==1 {
+      line=$0
+      gsub(/^[[:space:]]*-[[:space:]]*/, "", line)
+      gsub(/`/, "", line)
+      gsub(/[[:space:]]+$/, "", line)
+      if (line != "" && line !~ /^#/) print line
+    }
+  ' "$file"
+}
+
+collect_verification_commands() {
+  local file="$1"
+  awk '
+    BEGIN { in_section=0 }
+    /^##[[:space:]]+Verification$/ { in_section=1; next }
+    in_section==1 && /^##[[:space:]]+/ { in_section=0 }
+    in_section==1 {
+      line=$0
+      if (line ~ /^[[:space:]]*-[[:space:]]*\[[ xX]\][[:space:]]+/) {
+        sub(/^[[:space:]]*-[[:space:]]*\[[ xX]\][[:space:]]+/, "", line)
+        gsub(/`/, "", line)
+        gsub(/[[:space:]]+$/, "", line)
+        if (line != "") print line
+      }
+    }
+  ' "$file"
+}
+
+resolve_worktree_path() {
+  local arg="$1"
+  if [ -d "$arg" ]; then
+    (cd "$arg" && pwd)
+    return 0
+  fi
+  local repo_root
+  repo_root="$(git rev-parse --show-toplevel)"
+  if [ -d "${repo_root}/worktrees/${arg}" ]; then
+    echo "${repo_root}/worktrees/${arg}"
+    return 0
+  fi
+  return 1
+}
+
+# file_matches_scope_item <file> <pattern>
+#
+# Returns 0 (match) when the file path satisfies the pattern, 1 otherwise.
+#
+# Pattern types:
+#   No wildcard  — exact match OR directory-prefix match (pattern/ prefix)
+#   With *       — bash glob matching; * matches any chars including '/'
+#                  so src/*.ts also matches src/sub/dir/file.ts
+#                  and *.md matches docs/readme.md at any depth
+file_matches_scope_item() {
+  local file="$1"
+  local pattern="$2"
+  [ -z "$pattern" ] && return 1
+
+  # No wildcards: exact or directory-prefix match (original behaviour)
+  if [[ "$pattern" != *"*"* ]]; then
+    [ "$file" = "$pattern" ] && return 0
+    [[ "$file" == "$pattern/"* ]] && return 0
+    return 1
+  fi
+
+  # Glob pattern: in bash [[ ]], * matches any characters including '/'
+  # This makes src/*.ts, src/**/*.ts, and *.md all work as expected.
+  # shellcheck disable=SC2254
+  [[ "$file" == $pattern ]] && return 0
+  return 1
+}
+
+cmd_check() {
+  ensure_repo_root
+  [ $# -eq 1 ] || die "check expects exactly one argument"
+  local wt_path
+  wt_path="$(resolve_worktree_path "$1")" || die "worktree not found: $1"
+
+  local task_file="${wt_path}/.worktree-task.md"
+  [ -f "$task_file" ] || die "missing task file: ${task_file}"
+
+  local base_branch
+  base_branch="$(extract_frontmatter "$task_file" "base")"
+  base_branch="${base_branch:-develop}"
+
+  local changed_files=()
+  local scope_items=()
+  local offlimits_items=()
+  local line
+
+  while IFS= read -r line; do
+    changed_files+=("$line")
+  done < <(git -C "$wt_path" diff --name-only "${base_branch}...HEAD")
+
+  while IFS= read -r line; do
+    scope_items+=("$line")
+  done < <(collect_section_items "$task_file" "Scope")
+
+  while IFS= read -r line; do
+    offlimits_items+=("$line")
+  done < <(collect_section_items "$task_file" "Off-limits")
+
+  local has_violations=0
+
+  for f in "${changed_files[@]:-}"; do
+    [ -z "$f" ] && continue
+
+    local in_scope=0
+    for s in "${scope_items[@]:-}"; do
+      [ -z "$s" ] && continue
+      if file_matches_scope_item "$f" "$s"; then
+        in_scope=1
+        break
+      fi
+    done
+    if [ "${#scope_items[@]}" -gt 0 ] && [ "$in_scope" -eq 0 ]; then
+      echo "Scope violation: ${f}"
+      has_violations=1
+    fi
+
+    for o in "${offlimits_items[@]:-}"; do
+      [ -z "$o" ] && continue
+      if file_matches_scope_item "$f" "$o"; then
+        echo "Off-limits violation: ${f} (matched ${o})"
+        has_violations=1
+      fi
+    done
+  done
+
+  if [ "$has_violations" -eq 0 ]; then
+    echo "Check passed: no Scope/Off-limits violations detected against ${base_branch}...HEAD."
+  else
+    exit 2
+  fi
+}
+
+cmd_verify() {
+  ensure_repo_root
+  [ $# -eq 1 ] || die "verify expects exactly one argument"
+  local wt_path
+  wt_path="$(resolve_worktree_path "$1")" || die "worktree not found: $1"
+
+  local task_file="${wt_path}/.worktree-task.md"
+  [ -f "$task_file" ] || die "missing task file: ${task_file}"
+
+  local commands=()
+  local line
+  while IFS= read -r line; do
+    commands+=("$line")
+  done < <(collect_verification_commands "$task_file")
+
+  if [ "${#commands[@]}" -eq 0 ]; then
+    die "no verification commands found in ${task_file}"
+  fi
+
+  local failures=0
+  local total="${#commands[@]}"
+  local result_lines=()
+  local i=0
+
+  for cmd in "${commands[@]}"; do
+    i=$((i + 1))
+    local start=$SECONDS
+    echo ""
+    echo "[${i}/${total}] Running: ${cmd}"
+    echo "----------------------------------------------------------------"
+    set +e
+    (cd "$wt_path" && bash -lc "$cmd")
+    local exit_code=$?
+    set -e
+    local elapsed=$((SECONDS - start))
+    echo "----------------------------------------------------------------"
+    if [ "$exit_code" -ne 0 ]; then
+      failures=$((failures + 1))
+      echo "FAILED (exit ${exit_code}, ${elapsed}s)"
+      result_lines+=("  FAIL  [exit ${exit_code}] (${elapsed}s)  ${cmd}")
+    else
+      echo "PASSED (${elapsed}s)"
+      result_lines+=("  PASS  [exit 0]       (${elapsed}s)  ${cmd}")
+    fi
+  done
+
+  echo ""
+  echo "================================================================"
+  echo "Verification summary: $((total - failures)) passed, ${failures} failed of ${total}"
+  echo "================================================================"
+  for r in "${result_lines[@]}"; do
+    echo "$r"
+  done
+  echo "================================================================"
+
+  if [ "$failures" -ne 0 ]; then
+    echo ""
+    echo "Verification FAILED: ${failures} of ${total} command(s) failed."
+    exit 3
+  fi
+
+  echo ""
+  echo "Verification PASSED: all ${total} command(s) succeeded."
+}
+
+main() {
+  [ $# -ge 1 ] || { usage; exit 1; }
+  local cmd="$1"
+  shift
+
+  case "$cmd" in
+    init)        cmd_init "$@" ;;
+    status)      cmd_status "$@" ;;
+    new)         cmd_new "$@" ;;
+    check)       cmd_check "$@" ;;
+    verify)      cmd_verify "$@" ;;
+    help)        cmd_help "$@" ;;
+    -h|--help)   usage ;;
+    *) usage; die "unknown command: ${cmd}" ;;
+  esac
+}
+
+main "$@"

wtcraft/templates/.agent-harness/executor.md

@@ -0,0 +1,33 @@
+# Executor Role
+
+You are the execution agent for a bounded worktree task.
+
+## Responsibilities
+
+1. Read `.worktree-task.md` before making any edits.
+2. Edit only files listed in `Scope`.
+3. Do not modify anything listed in `Off-limits`.
+4. Execute `Verification` commands before reporting done.
+
+## If Ambiguity Exists
+
+- Stop and report the gap.
+- Ask for planner clarification instead of widening scope implicitly.
+
+## Model Selection
+
+Use the most capable model available in your current environment:
+
+| Environment | Preferred model |
+|---|---|
+| Claude Code (Anthropic CLI) | claude-sonnet-4-6 or claude-opus-4-6 |
+| Codex CLI (OpenAI) | codex (default), or gpt-4.1-mini as fallback |
+| Other / unknown | Default to the host CLI's configured model |
+
+**Codex fallback:** if the Codex CLI is invoked without an explicit `--model`
+flag and the default model is unavailable, pass `--model gpt-4.1-mini` as a
+fallback. Do not attempt to call the Anthropic API from inside Codex; use
+whichever OpenAI model the CLI supports.
+
+The executor role is model-agnostic — these are recommendations, not hard
+requirements. Follow the Scope and Verification contract regardless of model.

wtcraft/templates/.agent-harness/finisher.md

@@ -0,0 +1,16 @@
+# Finisher Role
+
+You are the finisher for a worktree task.
+
+## Responsibilities
+
+1. Read `.worktree-task.md`.
+2. Run all verification commands.
+3. Check diff scope against `Scope` and `Off-limits`.
+4. Push and open PR only if checks pass.
+5. Update task status to `done` locally after successful verification.
+
+## Safety
+
+- If verification fails, stop and report.
+- If unexpected files changed, stop and report.

wtcraft/templates/.agent-harness/planner.md

@@ -0,0 +1,19 @@
+# Planner Role
+
+You are the planner for a bounded worktree task.
+
+## Responsibilities
+
+1. Read the user request and inspect the codebase before proposing edits.
+2. Create or update `.worktree-task.md` with explicit Scope, Steps, Off-limits, Context, and Verification.
+3. Keep task boundaries strict enough for safe execution by a separate agent.
+4. Split tasks as a DAG:
+- shared foundation first
+- file-disjoint tasks in parallel
+- shared-file tasks serialized
+
+## Constraints
+
+- Prefer minimal file scope.
+- Do not include unrelated refactors.
+- Keep verification commands concrete and runnable.

wtcraft/templates/.claude/commands/finishwt.md

@@ -0,0 +1,7 @@
+You are finishing a worktree task.
+
+Read:
+- `.agent-harness/finisher.md`
+- `worktrees/$ARGUMENTS/.worktree-task.md`
+
+Run verification, check boundaries, and report results.

wtcraft/templates/.claude/commands/planwt.md

@@ -0,0 +1,8 @@
+You are planning a worktree task.
+
+Read:
+- `.agent-harness/planner.md`
+
+For the user request below, produce or update a bounded `.worktree-task.md`:
+
+$ARGUMENTS

wtcraft/templates/worktrees/.worktree-task.md

@@ -0,0 +1,33 @@
+---
+branch: feat/example-task
+agent: codex
+status: ready
+created: YYYY-MM-DD
+priority: medium
+base: develop
+---
+
+## Scope
+
+- src/example.ts
+
+## Steps
+
+- [ ] [D] Read files listed in Scope and Context.
+- [ ] [A] Implement only the requested change.
+- [ ] [D] Run verification checks and capture outcomes.
+
+## Off-limits
+
+- pnpm-lock.yaml
+- contracts/
+- CLAUDE.md
+- AGENTS.md
+
+## Context
+
+Add only task-specific context that is not obvious from code.
+
+## Verification
+
+- [ ] pnpm tsc --noEmit

wtcraft-0.3.0.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: wtcraft
+Version: 0.3.0
+Summary: Craft bounded multi-agent workflows with git-native worktrees
+License: MIT
+Project-URL: Repository, https://github.com/zywkloo/wtcraft
+Project-URL: Issues, https://github.com/zywkloo/wtcraft/issues
+Keywords: git,worktree,agents,orchestration,multi-agent,claude,codex
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# wtcraft - Worktree Craft
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/zywkloo/wtcraft/main/wtcraft-icon.PNG" alt="wtcraft icon" width="120" />
+</p>
+
+```bash
+npm install -g wtcraft
+```
+
+`wtcraft` is a lightweight, git-native harness for solo developers orchestrating multiple coding agents on a limited budget.
+
+**Keywords:** `Solo Dev` · `Budget-Aware` · `Agent Handoff` · `Boundaries` · `Lightweight`
+
+The goal is simple:
+- keep agent work isolated with `git worktree`
+- make agent handoffs explicit with a task contract
+- keep file and task boundaries easy to verify
+- stay usable from CLI + any IDE
+
+No hosted platform is required. No custom runtime is required.
+
+## Why
+
+Parallel agents are useful, but raw parallelism creates four common problems:
+- unclear handoff between planner and executor agents
+- context pollution across tasks
+- file ownership collisions
+- review overload from too many noisy PRs
+
+`wtcraft` focuses on handoff, boundaries, and budget-aware sequencing, not maximum concurrency.
+
+For the design story behind this project, read:
+[Beyond Worktrees: A Budget-Aware Multi-Agent Coding Harness for Solo Developers](https://zywkloo.github.io/blog/beyond-worktrees-budget-aware-multi-agent-coding-harness/).
+
+## Core Model
+
+1. Planner defines a bounded task contract.
+2. Executor works only inside that contract.
+3. Verifier checks scope, off-limits, and completion gates.
+4. Finisher handles push/PR/cleanup.
+
+This supports a DAG workflow:
+- merge shared foundation tasks first
+- run file-disjoint tasks in parallel
+- serialize tasks that touch shared files
+
+## Project Status
+
+Early public bootstrap.
+
+Current scope:
+- open documentation for workflow and roadmap
+- starter contract and command specs
+- CLI MVP available (`init`, `status`, `check`)
+
+## Requirements
+
+| Dependency | Required | Notes |
+|---|---|---|
+| bash | yes | macOS / Linux |
+| git | yes | worktree support (git ≥ 2.5) |
+| Claude Code CLI | no | optional planner / finisher agent |
+| Codex CLI | no | optional executor agent |
+| Node.js / npm | no | only needed for `npm install` distribution |
+
+Claude Code and Codex are agent tools that *use* wtcraft — they are not
+prerequisites for the CLI itself.
+
+## Install
+
+**npm (global):**
+
+```bash
+npm install -g wtcraft
+```
+
+**pip / pipx:**
+
+```bash
+pipx install wtcraft        # recommended — isolated venv, no conflicts
+# or
+pip install --user wtcraft
+```
+
+**Homebrew (tap):**
+
+```bash
+brew tap zywkloo/wtcraft https://github.com/zywkloo/wtcraft
+brew install wtcraft
+```
+
+**From source (no package manager needed):**
+
+```bash
+git clone https://github.com/zywkloo/wtcraft.git
+chmod +x wtcraft/scripts/wtcraft
+# add wtcraft/scripts to PATH, or run directly:
+wtcraft/scripts/wtcraft init
+```
+
+## Quick Start
+
+```bash
+wtcraft init                            # scaffold harness into current repo
+wtcraft init --patch-agent-files        # also append routing stubs to CLAUDE.md / AGENTS.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
+wtcraft help [command]                  # per-command usage
+```
+
+What `init` scaffolds:
+- `.agent-harness/planner.md`
+- `.agent-harness/executor.md`
+- `.agent-harness/finisher.md`
+- `.claude/commands/planwt.md`
+- `.claude/commands/finishwt.md`
+- `.worktree-task.template.md`
+
+`init` is non-destructive: existing files are not overwritten.
+By default `init` does not modify `CLAUDE.md` or `AGENTS.md`.
+Use `--patch-agent-files` to append managed routing stubs to existing files.
+
+`new` defaults to base branch `develop`. Set `WTCRAFT_BASE_BRANCH=main` (or another branch) when needed.
+
+## Docs
+
+- [Roadmap](./docs/roadmap.md)
+- [Principles](./docs/principles.md)
+- [Migration Notes](./docs/migration.md)
+- [Changelog](./CHANGELOG.md)
+
+## Testing
+
+```bash
+chmod +x tests/smoke.sh
+tests/smoke.sh
+```
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).

wtcraft-0.3.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+wtcraft/__init__.py,sha256=yS8DBdN2QliN0HEfybR8UtLyVmVo8YLHwRvp2TBcvQc,62
+wtcraft/_cli.py,sha256=oJi1K1R54btjnvizSmtkf2Q_AuHBsqMgTOE9cEZjErQ,1234
+wtcraft/_shell.sh,sha256=N1t35zu0lpwjh9q1ZEle_KzpYMJjABjDlI9NpyrzDqw,14639
+wtcraft/templates/.agent-harness/executor.md,sha256=Rv9XWSGC_uo88RPQx-n6Vn2A7zuc2FQx6DnLKlOrbso,1180
+wtcraft/templates/.agent-harness/finisher.md,sha256=4Byg3gnGCc2ng6avwXfV4rzeACNrkaa0ktIYs0WS0r4,412
+wtcraft/templates/.agent-harness/planner.md,sha256=cfmq8K-v657u-2cQoViIuqGlwVEwWKk7j4xnJHv5Mhk,598
+wtcraft/templates/.claude/commands/finishwt.md,sha256=eD1RJ5PEi_1fw15Qf4OfhfB7MmSAj_7HUmiaSofx8jg,173
+wtcraft/templates/.claude/commands/planwt.md,sha256=XCgy6NTWNJ9Yw934DwGQHDYpuJGj_ixL-c6PulV3m2E,161
+wtcraft/templates/worktrees/.worktree-task.md,sha256=gpj7czQeGffnQ2stbTcB58MbQptQ-r-cASYVldImRuI,491
+wtcraft-0.3.0.dist-info/licenses/LICENSE,sha256=bPY9h1hsfCXDq45i7vXHW7qpgrCm-cAMWeJyAlWqyew,9156
+wtcraft-0.3.0.dist-info/METADATA,sha256=4WmrRcZA9l72vHTLMSKmqmvv-GJ1UEHbU49wfg2hTNc,4522
+wtcraft-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+wtcraft-0.3.0.dist-info/entry_points.txt,sha256=1AmGZWIINFDnGZOgPx7RverW_RZHeTSTBYqCQaJfnZs,46
+wtcraft-0.3.0.dist-info/top_level.txt,sha256=9Ysbf1Qd8sYmgCc8yCeBBvakZN2nnpi2wBOP496nNOE,8
+wtcraft-0.3.0.dist-info/RECORD,,

wtcraft-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

wtcraft-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+wtcraft = wtcraft._cli:main

wtcraft-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,176 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

wtcraft-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+wtcraft