@maxiaochao/pi-toolkit 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2026-09-23 - v0.7.0
+
+- bundle the pi-worktree skill documenting the CLI for agents (the isolation loop, and which commands need an interactive terminal); fix pi-worktree: the .gitignore check tested a path form that never matched the directory-only .worktrees/ pattern, so the rule was re-appended on the first run in every repo and that self-inflicted edit then triggered the uncommitted-changes prompt
+
 ## 2026-09-22 - v0.6.1
 
 - bundle the pdlog skill for decompressing Pudu .pdlog logs (with bundled ppmd binary)

package/README.md

@@ -59,6 +59,8 @@ pi-worktree prune          # drop stale registrations for manually deleted dirs
 
 Typical loop: `pi-worktree start <name>` to start (Tab completes existing worktree names), commit inside Pi, `pi-worktree out` + `git merge <name>` to land the work, `pi-worktree remove <name>` to clean up. New branches are created from the branch you're currently on (or `HEAD` when detached), and the base commit is recorded in `branch.<name>.base` config so `info` can always tell you where the branch came from. Bash completion covers subcommands and existing worktree names (`pi-worktree feat<Tab>`).
 
+The bundled `pi-worktree` skill documents the CLI for agents: the `start`/`list`/`info`/`out`/`remove`/`prune` commands, the isolation loop from creating a worktree to landing the merge, and which of those commands need an interactive terminal (so an agent uses `start <name> -p "<task>"` for a headless nested run).
+
 The bundled `web-browser` skill provides reusable scripts for starting Chrome/Chromium with remote debugging, navigating tabs, evaluating JavaScript, emulating devices, taking screenshots, dismissing cookie dialogs, and inspecting browser logs. It auto-detects common Chrome/Chromium installations on macOS and Linux, including Windows Chrome when Pi runs under WSL; set `BROWSER_BIN` when the binary is elsewhere.
 
 The browser skill can be loaded explicitly with `/skill:web-browser`. Its scripts are available relative to the skill directory, for example:

package/bin/pi-worktree

@@ -63,7 +63,11 @@ resolve_base() {
 }
 
 ensure_gitignore() {
-  if ! git check-ignore -q .worktrees 2>/dev/null; then
+  # The trailing slash is load-bearing: `.worktrees/` is a directory-only
+  # pattern, and git check-ignore cannot match it against a path that does not
+  # exist yet — so `.worktrees` would look unignored on every first run and the
+  # rule would be appended again.
+  if ! git check-ignore -q .worktrees/ 2>/dev/null; then
     printf '.worktrees/\n' >> .gitignore
     ok "added .worktrees/ to .gitignore"
   fi
@@ -233,12 +237,12 @@ cd_wt() {
   fi
 
   local dir; dir="$(wt_dir "$name")"
-  ensure_gitignore
 
   if [[ -d "$dir" ]]; then
     # Reuse: must be a registered worktree for this repo.
     # Skip the dirty-workspace prompt — the worktree already exists, nothing new to create.
     git -C "$dir" rev-parse --git-dir >/dev/null 2>&1 || die "$dir exists but is not a git worktree"
+    ensure_gitignore
     ok "reusing existing worktree $dir"
   else
     # Dirty workspace: uncommitted changes do NOT follow into the new worktree.
@@ -249,6 +253,9 @@ cd_wt() {
       [[ "$ans" =~ ^[Yy]$ ]] || die "aborted"
     fi
 
+    # After the check above, so the tool's own .gitignore edit is not reported
+    # as (and does not prompt about) the user's uncommitted work.
+    ensure_gitignore
     mkdir -p .worktrees
     # Reuse branch if it exists, else create it
     if git show-ref --verify --quiet "refs/heads/$name"; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "keywords": [

package/skills/pi-worktree/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: pi-worktree
+description: Create, inspect, and clean up git worktrees with the pi-worktree CLI (start/list/info/remove/prune), which also launches Pi inside the worktree. Use when a task warrants isolation in its own worktree, or when the user asks to handle something the worktree way.
+---
+
+# pi-worktree
+
+`pi-worktree` wraps git worktree creation and Pi launch into one command. Worktrees live in `.worktrees/<name>` (added to `.gitignore`), each with a branch of the same name, branched from the branch you are on now (or `HEAD` when detached). The base commit is recorded in `branch.<name>.base` / `branch.<name>.baseRef` so `info` can always report where the branch came from.
+
+Installed by the package postinstall hook to `~/.local/bin/pi-worktree`, with bash completion for subcommands and existing worktree names.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `pi-worktree start <name> [pi args...]` | Create or reuse `.worktrees/<name>`, then launch Pi inside it. Already inside a linked worktree, it just launches Pi there. |
+| `pi-worktree start --base <ref> <name> [pi args...]` | Same, but branch from `<ref>` instead of the current branch. |
+| `pi-worktree list` | All worktrees; the main checkout is marked `(main checkout)`, stale registrations are flagged. |
+| `pi-worktree info <name>` | Clean/dirty status, branch and HEAD, base commit, ahead/behind `main`, unique commits. |
+| `pi-worktree out` | Open a shell in the main checkout (for merging). |
+| `pi-worktree remove <name>` | Remove the worktree and its branch; asks before discarding dirty files or unmerged commits. |
+| `pi-worktree prune` | Drop registrations whose directory was deleted by hand. |
+
+## Isolating a task
+
+1. **Survey** — `pi-worktree list`, plus `pi-worktree info <name>` when the name you want is already taken. Reuse is free; a removed worktree is gone for good, because `remove` deletes its branch.
+2. **Start** — `pi-worktree start <name>` (with `--base <ref>` when the work must not start from the current branch). Done when `list` shows the new worktree on its own branch.
+3. **Work** — inside the worktree: commit there, and check `pi-worktree info <name>` before claiming progress. `ahead: N commits since base` is the evidence.
+4. **Land** — `pi-worktree out`, then `git merge <name>` in the main checkout. Done when the worktree's unique commits are in the target branch.
+5. **Clean up** — `pi-worktree remove <name>`. A merged branch goes without prompting; anything unmerged asks once.
+
+## Driving it from an agent
+
+- `start` **execs `pi`** in the worktree, and `out` execs a shell. With no trailing Pi args both want an interactive terminal, so either run `start <name> -p "<task>"` for a headless nested run, or hand the bare `start <name>` to the user to run themselves.
+- `remove` asks before discarding dirty files or unmerged commits, and a non-interactive stdin (EOF) aborts safely. Answer explicitly when the removal is intended: `printf 'y\ny\n' | pi-worktree remove <name>`.
+- Your own working directory cannot change. "Isolate this in a worktree" therefore means launching a nested headless Pi in the worktree, or telling the user to run `pi-worktree start <name>`.