@tianhai/pi-workflow-kit 0.11.0 → 0.12.0

package/docs/plans/completed/2026-05-08-worktree-handoff-design.md

@@ -0,0 +1,118 @@
+# Worktree Handoff: Stop & Restart in New Directory
+
+## Problem
+
+When the user asks the agent to create a worktree during `executing-tasks`, the agent creates the worktree on disk but continues running in the original directory. All subsequent file operations, git commands, and task execution happen in the wrong place.
+
+Pi sessions are tied to their working directory — the agent cannot `cd` or spawn a sub-session in a different directory.
+
+## Root cause
+
+The `executing-tasks` skill creates the worktree (step 2) then continues executing tasks in the original directory instead of stopping and handing off to a new session.
+
+## Solution
+
+When the user chooses worktree isolation in `executing-tasks`, the agent:
+
+1. Creates the worktree
+2. Moves all plan docs into the worktree
+3. Commits the removal on the current branch
+4. Stops and tells the user to restart in the worktree
+
+The new session in the worktree finds the plan docs and continues seamlessly.
+
+## Changes
+
+### `skills/executing-tasks/SKILL.md`
+
+Replace step 2 ("Suggest workspace isolation") with a "Create & handoff" pattern for worktrees:
+
+```
+2. **Suggest workspace isolation** — if the user isn't already on a feature branch or worktree, present the options:
+
+   - **Branch** (smaller changes):
+     ```
+     git checkout -b <feature-name>
+     ```
+
+   - **Worktree** (larger features, keeps main clean):
+     ```
+     git worktree add ../<repo>-<feature-name> -b <feature-name>
+     ```
+
+   Derive `<feature-name>` from the plan doc (e.g. `docs/plans/2026-04-16-auth-design.md` → `auth`). Ask the user which they prefer, then wait for confirmation before proceeding.
+
+3. **If worktree was chosen — hand off to new session:**
+
+   a. Move plan docs into the worktree:
+      ```
+      mv docs/plans/*-design.md docs/plans/*-implementation.md docs/plans/*-progress.md <worktree>/docs/plans/ 2>/dev/null || true
+      mv docs/plans/adr/*.md <worktree>/docs/plans/adr/ 2>/dev/null || true
+      ```
+
+   b. Commit the removal on the current branch (if files were committed):
+      ```
+      git rm docs/plans/*-design.md docs/plans/*-implementation.md docs/plans/*-progress.md 2>/dev/null || true
+      git rm -r docs/plans/adr/ 2>/dev/null || true
+      git commit -m "chore: move plan docs to worktree for <feature-name>"
+      ```
+
+   c. Stop and show the user:
+      ```
+      ✅ Worktree created at ../<repo>-<feature-name>
+      📄 Plan docs moved to the worktree.
+
+      To continue, start a new session there:
+        cd ../<repo>-<feature-name> && pi
+
+      Then run: /skill:executing-tasks
+      ```
+
+   d. **Do not proceed with task execution.** The session ends here.
+```
+
+Remove the current step 3–4 numbering (progress file, commit plan docs) and renumber to account for the new handoff step. The "First run" flow becomes:
+
+1. Parse the implementation plan
+2. Suggest workspace isolation (branch or worktree)
+3. **If branch:** create progress file, commit plan docs, begin execution (existing flow)
+4. **If worktree:** move docs, commit removal, stop with handoff message (new flow)
+
+### No changes to other skills
+
+- `brainstorming` — read-only phase, no isolation needed
+- `writing-plans` — read-only phase, no isolation needed
+- `finalizing` — already handles worktree cleanup (`git worktree remove`)
+
+## User experience
+
+### Branch isolation (unchanged)
+
+```
+Agent: Would you like branch or worktree isolation?
+User: branch
+Agent: [creates branch, creates progress file, begins executing tasks]
+```
+
+### Worktree isolation (new)
+
+```
+Agent: Would you like branch or worktree isolation?
+User: worktree
+Agent: ✅ Worktree created at ../my-repo-auth
+       📄 Plan docs moved to the worktree.
+
+       To continue, start a new session there:
+         cd ../my-repo-auth && pi
+
+       Then run: /skill:executing-tasks
+```
+
+User opens a new terminal, runs the commands, and the new session picks up where the old one left off.
+
+## Edge cases
+
+- **No plan docs exist yet** — just create the worktree, don't try to move files
+- **Partial progress (some tasks done)** — progress file is moved, preserving state
+- **Uncommitted plan docs** — `mv` removes them, no `git rm` needed; commit only if they were previously committed
+- **Other uncommitted changes on current branch** — only touch plan docs, leave everything else untouched

package/docs/plans/completed/2026-05-08-worktree-handoff-implementation.md

@@ -0,0 +1,140 @@
+# Implementation Plan: Worktree Handoff
+
+## Overview
+
+Modify `skills/executing-tasks/SKILL.md` so that when the user chooses worktree isolation, the agent moves plan docs to the worktree, commits the removal, and stops with a handoff message instead of continuing execution in the wrong directory.
+
+**Design doc:** `docs/plans/2026-05-08-worktree-handoff-design.md`
+
+---
+
+## Task 1: Add worktree handoff flow to executing-tasks
+
+<!-- tdd: trivial -->
+<!-- checkpoint: none -->
+
+Modify the "First run" section of `skills/executing-tasks/SKILL.md`. After the workspace isolation prompt (step 2), add a branching path: if the user chose worktree, move docs and stop; if branch, continue with existing flow.
+
+### File: `skills/executing-tasks/SKILL.md`
+
+Replace the current steps 2–5 in the "First run" section:
+
+```markdown
+2. **Suggest workspace isolation** — if the user isn't already on a feature branch or worktree, present the options:
+
+   - **Branch** (smaller changes):
+     ```
+     git checkout -b <feature-name>
+     ```
+   - **Worktree** (larger features, keeps main clean):
+     ```
+     git worktree add ../<repo>-<feature-name> -b <feature-name>
+     ```
+
+   Derive `<feature-name>` from the plan doc (e.g. `docs/plans/2026-04-16-auth-design.md` → `auth`). Ask the user which they prefer, then wait for confirmation before proceeding.
+
+3. **Create the progress file** — save to `docs/plans/<plan-name>-progress.md` (replace `-implementation` with `-progress` in the plan filename):
+
+   ```markdown
+   # Progress: <topic>
+
+   Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
+   Branch: <actual branch name>
+   Started: <ISO timestamp>
+   Last updated: <ISO timestamp>
+
+   | # | Status | Task | Commit |
+   |---|--------|------|--------|
+   | 1 | ⬜ pending | Task description (preserve checkpoint labels) | — |
+   ```
+
+   Use the actual branch name — whether it's the original branch or a new one from the isolation step.
+
+4. **Commit the plan docs** — if `docs/plans/` has uncommitted files, commit them on the new branch:
+   ```
+   git add docs/plans/ && git commit -m "docs: add design and implementation plan"
+   ```
+
+5. **Begin task execution** — start with task 1 (see [Per-task execution](#per-task-execution)).
+```
+
+With:
+
+```markdown
+2. **Suggest workspace isolation** — if the user isn't already on a feature branch or worktree, present the options:
+
+   - **Branch** (smaller changes):
+     ```
+     git checkout -b <feature-name>
+     ```
+   - **Worktree** (larger features, keeps main clean):
+     ```
+     git worktree add ../<repo>-<feature-name> -b <feature-name>
+     ```
+
+   Derive `<feature-name>` from the plan doc (e.g. `docs/plans/2026-04-16-auth-design.md` → `auth`). Ask the user which they prefer, then wait for confirmation before proceeding.
+
+3. **If worktree was chosen — hand off to new session:**
+
+   a. Ensure the worktree's `docs/plans/` directory exists:
+      ```
+      mkdir -p <worktree>/docs/plans
+      mkdir -p <worktree>/docs/plans/adr
+      ```
+
+   b. Move plan docs into the worktree:
+      ```
+      mv docs/plans/*-design.md <worktree>/docs/plans/ 2>/dev/null || true
+      mv docs/plans/*-implementation.md <worktree>/docs/plans/ 2>/dev/null || true
+      mv docs/plans/*-progress.md <worktree>/docs/plans/ 2>/dev/null || true
+      mv docs/plans/adr/*.md <worktree>/docs/plans/adr/ 2>/dev/null || true
+      ```
+
+   c. Commit the removal on the current branch (if any plan docs were committed):
+      ```
+      git rm docs/plans/*-design.md docs/plans/*-implementation.md docs/plans/*-progress.md 2>/dev/null || true
+      git rm -r docs/plans/adr/ 2>/dev/null || true
+      git commit -m "chore: move plan docs to worktree for <feature-name>"
+      ```
+
+   d. Stop and show the user:
+      ```
+      ✅ Worktree created at ../<repo>-<feature-name>
+      📄 Plan docs moved to the worktree.
+
+      To continue, start a new session there:
+        cd ../<repo>-<feature-name> && pi
+
+      Then run: /skill:executing-tasks
+      ```
+
+   e. **Do not proceed with task execution.** The session ends here.
+
+4. **If branch was chosen — continue with execution:**
+
+   a. **Create the progress file** — save to `docs/plans/<plan-name>-progress.md` (replace `-implementation` with `-progress` in the plan filename):
+
+      ```markdown
+      # Progress: <topic>
+
+      Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
+      Branch: <actual branch name>
+      Started: <ISO timestamp>
+      Last updated: <ISO timestamp>
+
+      | # | Status | Task | Commit |
+      |---|--------|------|--------|
+      | 1 | ⬜ pending | Task description (preserve checkpoint labels) | — |
+      ```
+
+      Use the actual branch name — whether it's the original branch or a new one from the isolation step.
+
+   b. **Commit the plan docs** — if `docs/plans/` has uncommitted files, commit them on the new branch:
+      ```
+      git add docs/plans/ && git commit -m "docs: add design and implementation plan"
+      ```
+
+   c. **Begin task execution** — start with task 1 (see [Per-task execution](#per-task execution)).
+```
+
+**Commit:** `feat(executing-tasks): add worktree handoff with plan doc migration`

package/docs/plans/completed/2026-05-08-worktree-handoff-progress.md

@@ -0,0 +1,10 @@
+# Progress: Worktree Handoff
+
+Plan: docs/plans/2026-05-08-worktree-handoff-implementation.md
+Branch: main
+Started: 2026-05-08T00:00:00Z
+Last updated: 2026-05-08T00:00:00Z
+
+| # | Status | Task | Commit |
+|---|--------|------|--------|
+| 1 | ✅ done | Add worktree handoff flow to executing-tasks | 2ce48e7 |

package/extensions/workflow-guard.ts

@@ -45,7 +45,7 @@ const DESTRUCTIVE_PATTERNS = [
 	/\bshutdown\b/i,
 	/\bsystemctl\s+(start|stop|restart|enable|disable)/i,
 	/\bservice\s+\S+\s+(start|stop|restart)/i,
-	/\b(vim?|nano|emacs|code|subl)\b/i,
+	/^\s*(vim?|nano|emacs|code|subl)\b/i,
 ];
 
 const SAFE_PATTERNS = [
@@ -117,7 +117,8 @@ const SAFE_PATTERNS = [
 ];
 
 /** Split a compound command into individual sub-commands.
- * Handles &&, ||, ;, and | (pipe) operators, ignoring leading whitespace.
+ * Splits on &&, ||, and ; operators, ignoring leading whitespace.
+ * Does NOT split on | (pipe) to allow piping (e.g. `git log | head`).
  */
 function splitCompoundCommand(command: string): string[] {
 	// Match sub-commands separated by &&, ||, ; (with optional whitespace)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Enforce structured brainstorm→plan→execute→finalize workflow with TDD discipline in AI coding agents",
   "keywords": [
     "pi-package",

package/skills/executing-tasks/SKILL.md

@@ -29,29 +29,67 @@ Implement the plan from `docs/plans/*-implementation.md` task by task, with file
 
    Derive `<feature-name>` from the plan doc (e.g. `docs/plans/2026-04-16-auth-design.md` → `auth`). Ask the user which they prefer, then wait for confirmation before proceeding.
 
-3. **Create the progress file** — save to `docs/plans/<plan-name>-progress.md` (replace `-implementation` with `-progress` in the plan filename):
+3. **If worktree was chosen — hand off to new session:**
 
-   ```markdown
-   # Progress: <topic>
+   a. Ensure the worktree's `docs/plans/` directory exists:
+      ```
+      mkdir -p <worktree>/docs/plans
+      mkdir -p <worktree>/docs/plans/adr
+      ```
 
-   Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
-   Branch: <actual branch name>
-   Started: <ISO timestamp>
-   Last updated: <ISO timestamp>
+   b. Move plan docs into the worktree:
+      ```
+      mv docs/plans/*-design.md <worktree>/docs/plans/ 2>/dev/null || true
+      mv docs/plans/*-implementation.md <worktree>/docs/plans/ 2>/dev/null || true
+      mv docs/plans/*-progress.md <worktree>/docs/plans/ 2>/dev/null || true
+      mv docs/plans/adr/*.md <worktree>/docs/plans/adr/ 2>/dev/null || true
+      ```
 
-   | # | Status | Task | Commit |
-   |---|--------|------|--------|
-   | 1 | ⬜ pending | Task description (preserve checkpoint labels) | — |
-   ```
+   c. Commit the removal on the current branch (if any plan docs were committed):
+      ```
+      git rm docs/plans/*-design.md docs/plans/*-implementation.md docs/plans/*-progress.md 2>/dev/null || true
+      git rm -r docs/plans/adr/ 2>/dev/null || true
+      git commit -m "chore: move plan docs to worktree for <feature-name>"
+      ```
 
-   Use the actual branch name — whether it's the original branch or a new one from the isolation step.
+   d. Stop and show the user:
+      ```
+      ✅ Worktree created at ../<repo>-<feature-name>
+      📄 Plan docs moved to the worktree.
 
-4. **Commit the plan docs** — if `docs/plans/` has uncommitted files, commit them on the new branch:
-   ```
-   git add docs/plans/ && git commit -m "docs: add design and implementation plan"
-   ```
+      To continue, start a new session there:
+        cd ../<repo>-<feature-name> && pi
 
-5. **Begin task execution** — start with task 1 (see [Per-task execution](#per-task-execution)).
+      Then run: /skill:executing-tasks
+      ```
+
+   e. **Do not proceed with task execution.** The session ends here.
+
+4. **If branch was chosen — continue with execution:**
+
+   a. **Create the progress file** — save to `docs/plans/<plan-name>-progress.md` (replace `-implementation` with `-progress` in the plan filename):
+
+      ```markdown
+      # Progress: <topic>
+
+      Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
+      Branch: <actual branch name>
+      Started: <ISO timestamp>
+      Last updated: <ISO timestamp>
+
+      | # | Status | Task | Commit |
+      |---|--------|------|--------|
+      | 1 | ⬜ pending | Task description (preserve checkpoint labels) | — |
+      ```
+
+      Use the actual branch name — whether it's the original branch or a new one from the isolation step.
+
+   b. **Commit the plan docs** — if `docs/plans/` has uncommitted files, commit them on the new branch:
+      ```
+      git add docs/plans/ && git commit -m "docs: add design and implementation plan"
+      ```
+
+   c. **Begin task execution** — start with task 1 (see [Per-task execution](#per-task-execution)).
 
 ## Resume