@tianhai/pi-workflow-kit 0.11.1 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/plans/completed/2026-05-08-worktree-handoff-design.md +118 -0
- package/docs/plans/completed/2026-05-08-worktree-handoff-implementation.md +140 -0
- package/docs/plans/completed/2026-05-08-worktree-handoff-progress.md +10 -0
- package/package.json +1 -1
- package/skills/executing-tasks/SKILL.md +55 -17
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# Worktree Handoff: Stop & Restart in New Directory
|
|
2
|
+
|
|
3
|
+
## Problem
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
Pi sessions are tied to their working directory — the agent cannot `cd` or spawn a sub-session in a different directory.
|
|
8
|
+
|
|
9
|
+
## Root cause
|
|
10
|
+
|
|
11
|
+
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.
|
|
12
|
+
|
|
13
|
+
## Solution
|
|
14
|
+
|
|
15
|
+
When the user chooses worktree isolation in `executing-tasks`, the agent:
|
|
16
|
+
|
|
17
|
+
1. Creates the worktree
|
|
18
|
+
2. Moves all plan docs into the worktree
|
|
19
|
+
3. Commits the removal on the current branch
|
|
20
|
+
4. Stops and tells the user to restart in the worktree
|
|
21
|
+
|
|
22
|
+
The new session in the worktree finds the plan docs and continues seamlessly.
|
|
23
|
+
|
|
24
|
+
## Changes
|
|
25
|
+
|
|
26
|
+
### `skills/executing-tasks/SKILL.md`
|
|
27
|
+
|
|
28
|
+
Replace step 2 ("Suggest workspace isolation") with a "Create & handoff" pattern for worktrees:
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
2. **Suggest workspace isolation** — if the user isn't already on a feature branch or worktree, present the options:
|
|
32
|
+
|
|
33
|
+
- **Branch** (smaller changes):
|
|
34
|
+
```
|
|
35
|
+
git checkout -b <feature-name>
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
- **Worktree** (larger features, keeps main clean):
|
|
39
|
+
```
|
|
40
|
+
git worktree add ../<repo>-<feature-name> -b <feature-name>
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
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.
|
|
44
|
+
|
|
45
|
+
3. **If worktree was chosen — hand off to new session:**
|
|
46
|
+
|
|
47
|
+
a. Move plan docs into the worktree:
|
|
48
|
+
```
|
|
49
|
+
mv docs/plans/*-design.md docs/plans/*-implementation.md docs/plans/*-progress.md <worktree>/docs/plans/ 2>/dev/null || true
|
|
50
|
+
mv docs/plans/adr/*.md <worktree>/docs/plans/adr/ 2>/dev/null || true
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
b. Commit the removal on the current branch (if files were committed):
|
|
54
|
+
```
|
|
55
|
+
git rm docs/plans/*-design.md docs/plans/*-implementation.md docs/plans/*-progress.md 2>/dev/null || true
|
|
56
|
+
git rm -r docs/plans/adr/ 2>/dev/null || true
|
|
57
|
+
git commit -m "chore: move plan docs to worktree for <feature-name>"
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
c. Stop and show the user:
|
|
61
|
+
```
|
|
62
|
+
✅ Worktree created at ../<repo>-<feature-name>
|
|
63
|
+
📄 Plan docs moved to the worktree.
|
|
64
|
+
|
|
65
|
+
To continue, start a new session there:
|
|
66
|
+
cd ../<repo>-<feature-name> && pi
|
|
67
|
+
|
|
68
|
+
Then run: /skill:executing-tasks
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
d. **Do not proceed with task execution.** The session ends here.
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
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:
|
|
75
|
+
|
|
76
|
+
1. Parse the implementation plan
|
|
77
|
+
2. Suggest workspace isolation (branch or worktree)
|
|
78
|
+
3. **If branch:** create progress file, commit plan docs, begin execution (existing flow)
|
|
79
|
+
4. **If worktree:** move docs, commit removal, stop with handoff message (new flow)
|
|
80
|
+
|
|
81
|
+
### No changes to other skills
|
|
82
|
+
|
|
83
|
+
- `brainstorming` — read-only phase, no isolation needed
|
|
84
|
+
- `writing-plans` — read-only phase, no isolation needed
|
|
85
|
+
- `finalizing` — already handles worktree cleanup (`git worktree remove`)
|
|
86
|
+
|
|
87
|
+
## User experience
|
|
88
|
+
|
|
89
|
+
### Branch isolation (unchanged)
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
Agent: Would you like branch or worktree isolation?
|
|
93
|
+
User: branch
|
|
94
|
+
Agent: [creates branch, creates progress file, begins executing tasks]
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Worktree isolation (new)
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
Agent: Would you like branch or worktree isolation?
|
|
101
|
+
User: worktree
|
|
102
|
+
Agent: ✅ Worktree created at ../my-repo-auth
|
|
103
|
+
📄 Plan docs moved to the worktree.
|
|
104
|
+
|
|
105
|
+
To continue, start a new session there:
|
|
106
|
+
cd ../my-repo-auth && pi
|
|
107
|
+
|
|
108
|
+
Then run: /skill:executing-tasks
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
User opens a new terminal, runs the commands, and the new session picks up where the old one left off.
|
|
112
|
+
|
|
113
|
+
## Edge cases
|
|
114
|
+
|
|
115
|
+
- **No plan docs exist yet** — just create the worktree, don't try to move files
|
|
116
|
+
- **Partial progress (some tasks done)** — progress file is moved, preserving state
|
|
117
|
+
- **Uncommitted plan docs** — `mv` removes them, no `git rm` needed; commit only if they were previously committed
|
|
118
|
+
- **Other uncommitted changes on current branch** — only touch plan docs, leave everything else untouched
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
# Implementation Plan: Worktree Handoff
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
**Design doc:** `docs/plans/2026-05-08-worktree-handoff-design.md`
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Task 1: Add worktree handoff flow to executing-tasks
|
|
12
|
+
|
|
13
|
+
<!-- tdd: trivial -->
|
|
14
|
+
<!-- checkpoint: none -->
|
|
15
|
+
|
|
16
|
+
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.
|
|
17
|
+
|
|
18
|
+
### File: `skills/executing-tasks/SKILL.md`
|
|
19
|
+
|
|
20
|
+
Replace the current steps 2–5 in the "First run" section:
|
|
21
|
+
|
|
22
|
+
```markdown
|
|
23
|
+
2. **Suggest workspace isolation** — if the user isn't already on a feature branch or worktree, present the options:
|
|
24
|
+
|
|
25
|
+
- **Branch** (smaller changes):
|
|
26
|
+
```
|
|
27
|
+
git checkout -b <feature-name>
|
|
28
|
+
```
|
|
29
|
+
- **Worktree** (larger features, keeps main clean):
|
|
30
|
+
```
|
|
31
|
+
git worktree add ../<repo>-<feature-name> -b <feature-name>
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
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.
|
|
35
|
+
|
|
36
|
+
3. **Create the progress file** — save to `docs/plans/<plan-name>-progress.md` (replace `-implementation` with `-progress` in the plan filename):
|
|
37
|
+
|
|
38
|
+
```markdown
|
|
39
|
+
# Progress: <topic>
|
|
40
|
+
|
|
41
|
+
Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
|
|
42
|
+
Branch: <actual branch name>
|
|
43
|
+
Started: <ISO timestamp>
|
|
44
|
+
Last updated: <ISO timestamp>
|
|
45
|
+
|
|
46
|
+
| # | Status | Task | Commit |
|
|
47
|
+
|---|--------|------|--------|
|
|
48
|
+
| 1 | ⬜ pending | Task description (preserve checkpoint labels) | — |
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Use the actual branch name — whether it's the original branch or a new one from the isolation step.
|
|
52
|
+
|
|
53
|
+
4. **Commit the plan docs** — if `docs/plans/` has uncommitted files, commit them on the new branch:
|
|
54
|
+
```
|
|
55
|
+
git add docs/plans/ && git commit -m "docs: add design and implementation plan"
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
5. **Begin task execution** — start with task 1 (see [Per-task execution](#per-task-execution)).
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
With:
|
|
62
|
+
|
|
63
|
+
```markdown
|
|
64
|
+
2. **Suggest workspace isolation** — if the user isn't already on a feature branch or worktree, present the options:
|
|
65
|
+
|
|
66
|
+
- **Branch** (smaller changes):
|
|
67
|
+
```
|
|
68
|
+
git checkout -b <feature-name>
|
|
69
|
+
```
|
|
70
|
+
- **Worktree** (larger features, keeps main clean):
|
|
71
|
+
```
|
|
72
|
+
git worktree add ../<repo>-<feature-name> -b <feature-name>
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
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.
|
|
76
|
+
|
|
77
|
+
3. **If worktree was chosen — hand off to new session:**
|
|
78
|
+
|
|
79
|
+
a. Ensure the worktree's `docs/plans/` directory exists:
|
|
80
|
+
```
|
|
81
|
+
mkdir -p <worktree>/docs/plans
|
|
82
|
+
mkdir -p <worktree>/docs/plans/adr
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
b. Move plan docs into the worktree:
|
|
86
|
+
```
|
|
87
|
+
mv docs/plans/*-design.md <worktree>/docs/plans/ 2>/dev/null || true
|
|
88
|
+
mv docs/plans/*-implementation.md <worktree>/docs/plans/ 2>/dev/null || true
|
|
89
|
+
mv docs/plans/*-progress.md <worktree>/docs/plans/ 2>/dev/null || true
|
|
90
|
+
mv docs/plans/adr/*.md <worktree>/docs/plans/adr/ 2>/dev/null || true
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
c. Commit the removal on the current branch (if any plan docs were committed):
|
|
94
|
+
```
|
|
95
|
+
git rm docs/plans/*-design.md docs/plans/*-implementation.md docs/plans/*-progress.md 2>/dev/null || true
|
|
96
|
+
git rm -r docs/plans/adr/ 2>/dev/null || true
|
|
97
|
+
git commit -m "chore: move plan docs to worktree for <feature-name>"
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
d. Stop and show the user:
|
|
101
|
+
```
|
|
102
|
+
✅ Worktree created at ../<repo>-<feature-name>
|
|
103
|
+
📄 Plan docs moved to the worktree.
|
|
104
|
+
|
|
105
|
+
To continue, start a new session there:
|
|
106
|
+
cd ../<repo>-<feature-name> && pi
|
|
107
|
+
|
|
108
|
+
Then run: /skill:executing-tasks
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
e. **Do not proceed with task execution.** The session ends here.
|
|
112
|
+
|
|
113
|
+
4. **If branch was chosen — continue with execution:**
|
|
114
|
+
|
|
115
|
+
a. **Create the progress file** — save to `docs/plans/<plan-name>-progress.md` (replace `-implementation` with `-progress` in the plan filename):
|
|
116
|
+
|
|
117
|
+
```markdown
|
|
118
|
+
# Progress: <topic>
|
|
119
|
+
|
|
120
|
+
Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
|
|
121
|
+
Branch: <actual branch name>
|
|
122
|
+
Started: <ISO timestamp>
|
|
123
|
+
Last updated: <ISO timestamp>
|
|
124
|
+
|
|
125
|
+
| # | Status | Task | Commit |
|
|
126
|
+
|---|--------|------|--------|
|
|
127
|
+
| 1 | ⬜ pending | Task description (preserve checkpoint labels) | — |
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Use the actual branch name — whether it's the original branch or a new one from the isolation step.
|
|
131
|
+
|
|
132
|
+
b. **Commit the plan docs** — if `docs/plans/` has uncommitted files, commit them on the new branch:
|
|
133
|
+
```
|
|
134
|
+
git add docs/plans/ && git commit -m "docs: add design and implementation plan"
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
c. **Begin task execution** — start with task 1 (see [Per-task execution](#per-task execution)).
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
**Commit:** `feat(executing-tasks): add worktree handoff with plan doc migration`
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Progress: Worktree Handoff
|
|
2
|
+
|
|
3
|
+
Plan: docs/plans/2026-05-08-worktree-handoff-implementation.md
|
|
4
|
+
Branch: main
|
|
5
|
+
Started: 2026-05-08T00:00:00Z
|
|
6
|
+
Last updated: 2026-05-08T00:00:00Z
|
|
7
|
+
|
|
8
|
+
| # | Status | Task | Commit |
|
|
9
|
+
|---|--------|------|--------|
|
|
10
|
+
| 1 | ✅ done | Add worktree handoff flow to executing-tasks | 2ce48e7 |
|
package/package.json
CHANGED
|
@@ -29,29 +29,67 @@ Implement the plan from `docs/plans/*-implementation.md` task by task, with file
|
|
|
29
29
|
|
|
30
30
|
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.
|
|
31
31
|
|
|
32
|
-
3. **
|
|
32
|
+
3. **If worktree was chosen — hand off to new session:**
|
|
33
33
|
|
|
34
|
-
|
|
35
|
-
|
|
34
|
+
a. Ensure the worktree's `docs/plans/` directory exists:
|
|
35
|
+
```
|
|
36
|
+
mkdir -p <worktree>/docs/plans
|
|
37
|
+
mkdir -p <worktree>/docs/plans/adr
|
|
38
|
+
```
|
|
36
39
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
40
|
+
b. Move plan docs into the worktree:
|
|
41
|
+
```
|
|
42
|
+
mv docs/plans/*-design.md <worktree>/docs/plans/ 2>/dev/null || true
|
|
43
|
+
mv docs/plans/*-implementation.md <worktree>/docs/plans/ 2>/dev/null || true
|
|
44
|
+
mv docs/plans/*-progress.md <worktree>/docs/plans/ 2>/dev/null || true
|
|
45
|
+
mv docs/plans/adr/*.md <worktree>/docs/plans/adr/ 2>/dev/null || true
|
|
46
|
+
```
|
|
41
47
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
48
|
+
c. Commit the removal on the current branch (if any plan docs were committed):
|
|
49
|
+
```
|
|
50
|
+
git rm docs/plans/*-design.md docs/plans/*-implementation.md docs/plans/*-progress.md 2>/dev/null || true
|
|
51
|
+
git rm -r docs/plans/adr/ 2>/dev/null || true
|
|
52
|
+
git commit -m "chore: move plan docs to worktree for <feature-name>"
|
|
53
|
+
```
|
|
46
54
|
|
|
47
|
-
|
|
55
|
+
d. Stop and show the user:
|
|
56
|
+
```
|
|
57
|
+
✅ Worktree created at ../<repo>-<feature-name>
|
|
58
|
+
📄 Plan docs moved to the worktree.
|
|
48
59
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
git add docs/plans/ && git commit -m "docs: add design and implementation plan"
|
|
52
|
-
```
|
|
60
|
+
To continue, start a new session there:
|
|
61
|
+
cd ../<repo>-<feature-name> && pi
|
|
53
62
|
|
|
54
|
-
|
|
63
|
+
Then run: /skill:executing-tasks
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
e. **Do not proceed with task execution.** The session ends here.
|
|
67
|
+
|
|
68
|
+
4. **If branch was chosen — continue with execution:**
|
|
69
|
+
|
|
70
|
+
a. **Create the progress file** — save to `docs/plans/<plan-name>-progress.md` (replace `-implementation` with `-progress` in the plan filename):
|
|
71
|
+
|
|
72
|
+
```markdown
|
|
73
|
+
# Progress: <topic>
|
|
74
|
+
|
|
75
|
+
Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
|
|
76
|
+
Branch: <actual branch name>
|
|
77
|
+
Started: <ISO timestamp>
|
|
78
|
+
Last updated: <ISO timestamp>
|
|
79
|
+
|
|
80
|
+
| # | Status | Task | Commit |
|
|
81
|
+
|---|--------|------|--------|
|
|
82
|
+
| 1 | ⬜ pending | Task description (preserve checkpoint labels) | — |
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Use the actual branch name — whether it's the original branch or a new one from the isolation step.
|
|
86
|
+
|
|
87
|
+
b. **Commit the plan docs** — if `docs/plans/` has uncommitted files, commit them on the new branch:
|
|
88
|
+
```
|
|
89
|
+
git add docs/plans/ && git commit -m "docs: add design and implementation plan"
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
c. **Begin task execution** — start with task 1 (see [Per-task execution](#per-task-execution)).
|
|
55
93
|
|
|
56
94
|
## Resume
|
|
57
95
|
|