@tianhai/pi-workflow-kit 0.11.1 → 0.13.1

package/README.md

@@ -74,6 +74,25 @@ Each task is labeled with its TDD scenario during planning:
 | **Modifying tested code** | Changing existing behavior | Run existing tests first → modify → verify |
 | **Trivial** | Config, docs, naming | Use judgment |
 
+### Lessons Learned
+
+A persistent rules file (`docs/lessons.md`) helps the agent learn from repeat mistakes across sessions. When the agent catches itself making the same error — like forgetting to run `make lint` — it writes a rule immediately. Future sessions (even after `/new`) pick it up automatically.
+
+```
+brainstorm → reads lessons (design context)
+plan        → reads lessons (task breakdown)
+execute     → reads lessons per task, writes new ones on repeat mistakes
+finalize    → reviews and retires stale rules
+```
+
+Rules are simple imperative bullets:
+
+- After completing each task, run `make lint && make fmt` before committing
+- Never import `testify` in this project
+- Always check for existing test helpers before writing new ones
+
+No configuration needed — the file is created automatically when the first lesson is written.
+
 ### Checkpoint Review Gates
 
 Optionally label tasks with a `checkpoint` to pause for human review. At each checkpoint the agent stops and waits for your feedback — you can approve, ask for changes, or send it back to rethink. Only when you're satisfied does it move on to the next task.

package/docs/plans/completed/2026-05-08-lessons-learned-design.md

@@ -0,0 +1,76 @@
+# Lessons Learned
+
+Date: 2026-05-08
+
+## Problem
+
+During task execution, the AI agent repeatedly makes the same project-specific mistakes — e.g., forgetting to run `make lint && make fmt` in Go projects, ignoring test helper conventions, or violating code style rules. These mistakes persist across sessions because there's no persistent memory the agent reads at the start of each task.
+
+## Solution
+
+A flat rules file (`docs/lessons.md`) that the agent reads before each task and writes to when it catches repeat mistakes. Integrated into the existing 4 workflow skills.
+
+## File: `docs/lessons.md`
+
+Created automatically when the first lesson is written. Never archived or moved.
+
+```markdown
+# Lessons Learned
+
+<!--
+Agent: read this at the start of each task during executing-tasks.
+Follow every rule. Add new rules when you catch yourself making repeat mistakes.
+Retire rules that no longer apply during finalizing.
+-->
+
+## Rules
+
+- After completing each task in a Go project, run `make lint && make fmt` before committing
+```
+
+### Rules for the agent
+
+- Each rule is a single bullet under `## Rules`
+- Write rules as imperative commands ("do X", "never Y", "always Z before W")
+- A rule is only added when it would **change future behavior** — not one-off errors
+- Rules can be removed (retired) during finalizing if they no longer apply
+
+## Data flow
+
+```
+brainstorming ──── reads lessons (context for design)
+       │
+writing-plans ──── reads lessons (informs task breakdown)
+       │
+executing-tasks ── reads lessons at start of EACH task
+       │            appends new lessons when catching repeat mistakes
+       │
+finalizing ─────── reviews session for missed lessons
+                    retires stale rules
+```
+
+Lessons are persisted to disk as soon as they're learned, so `/new` sessions don't lose them.
+
+## Skill changes
+
+### executing-tasks (3 changes)
+
+1. **Per-task execution, step 2** — add bullet: "Read `docs/lessons.md` if it exists — follow all rules listed there while working on this task."
+2. **New step between step 9 (refactor) and step 10 (checkpoint: done)** — "Learn from mistakes: if you caught yourself making a repeat mistake, append a rule to `docs/lessons.md`. Only add rules that would change future behavior."
+3. **"If you're stuck" section** — add at end: "Check `docs/lessons.md` — a previous lesson may be relevant."
+
+### finalizing (1 change)
+
+Add a new step before "Update documentation": "Review `docs/lessons.md` if it exists — add missed lessons, retire stale rules. Create it if lessons were learned but the file doesn't exist yet."
+
+### brainstorming (1 change)
+
+Step 2 (understand the idea) — add after checking package.json/dependencies: "Check `docs/lessons.md` if it exists — known constraints and patterns may affect the design."
+
+### writing-plans (1 change)
+
+Step 1 (check for a design doc) — add after reading relevant code: "Read `docs/lessons.md` if it exists — incorporate known patterns into the task breakdown."
+
+## Slice
+
+Single slice: all 5 skill changes + file format convention. No new skills, extensions, or config.

package/docs/plans/completed/2026-05-08-lessons-learned-implementation.md

@@ -0,0 +1,219 @@
+# Implementation Plan: Lessons Learned
+
+Design: `docs/plans/2026-05-08-lessons-learned-design.md`
+
+## Overview
+
+Add a `docs/lessons.md` rules file that the agent reads at natural points in the workflow and writes to when it catches repeat mistakes. Changes are purely instructional — edits to 4 SKILL.md files plus documentation updates.
+
+No TypeScript code changes. No new extensions or skills. The existing `workflow-guard.ts` already allows writes to `docs/` during execute/finalize phases (it only blocks outside `docs/plans/` during brainstorm/plan). Since `docs/lessons.md` is at `docs/` level (not inside `docs/plans/`), it won't interfere with archiving.
+
+---
+
+## Task 1: Add lessons-learned read step to executing-tasks skill
+
+<!-- tdd: trivial -->
+<!-- checkpoint: done -->
+
+**File:** `skills/executing-tasks/SKILL.md`
+
+**Change 1** — In "Per-task execution", step 2, add a new bullet after the existing ones:
+
+```
+- **Read `docs/lessons.md` if it exists** — follow all rules listed there while working on this task.
+```
+
+The full step 2 should become:
+
+```markdown
+2. **Read the plan selectively** — read the plan's overview section (everything before `## Task 1:`). Skim all `## Task N:` headings for dependency awareness. Then read the current task's body in full. **Read `docs/lessons.md` if it exists** — follow all rules listed there while working on this task.
+```
+
+**Change 2** — In "Per-task execution", insert a new step between step 9 (Refactor if needed) and step 10 (checkpoint: done). The new step becomes step 10, and all subsequent steps renumber by 1 (step 10→11, 11→12, 12→13, 13→14, 14→15):
+
+```markdown
+10. **Learn from mistakes** — if you caught yourself making a mistake during this task that you've made before or that would apply to future tasks, append a rule to `docs/lessons.md`. Only add rules that would change future behavior. If the file doesn't exist, create it with the standard format (see below). Do not add one-off errors or things you self-corrected immediately.
+
+    **`docs/lessons.md` format:**
+    ```markdown
+    # Lessons Learned
+
+    <!--
+    Agent: read this at the start of each task during executing-tasks.
+    Follow every rule. Add new rules when you catch yourself making repeat mistakes.
+    Retire rules that no longer apply during finalizing.
+    -->
+
+    ## Rules
+
+    - <new rule here>
+    ```
+```
+
+**Change 3** — In "If you're stuck" section, add a new item at the end:
+
+```markdown
+5. **Check `docs/lessons.md`** — a previous lesson may be relevant to your current problem.
+```
+
+Renumber the existing item 4 to 5 if needed (it's currently the last item).
+
+**Command:**
+```
+git add skills/executing-tasks/SKILL.md
+git commit -m "feat(executing-tasks): read and write lessons learned per task"
+```
+
+---
+
+## Task 2: Add lessons-learned review step to finalizing skill
+
+<!-- tdd: trivial -->
+<!-- checkpoint: none -->
+
+**File:** `skills/finalizing/SKILL.md`
+
+Insert a new step between the existing step 1 (Move planning docs) and step 2 (Update documentation). The new step becomes step 2, and existing steps 2-4 renumber to 3-5:
+
+```markdown
+2. **Review lessons learned** — if `docs/lessons.md` exists, review it:
+   - Add any lessons from this session that were missed during execution
+   - Retire rules that no longer apply (remove the bullet)
+   - If no changes are needed, leave it as-is
+
+   If `docs/lessons.md` doesn't exist but lessons were learned this session, create it with the standard format:
+
+   ```markdown
+   # Lessons Learned
+
+   <!--
+   Agent: read this at the start of each task during executing-tasks.
+   Follow every rule. Add new rules when you catch yourself making repeat mistakes.
+   Retire rules that no longer apply during finalizing.
+   -->
+
+   ## Rules
+
+   - <rule 1>
+   - <rule 2>
+   ```
+```
+
+**Command:**
+```
+git add skills/finalizing/SKILL.md
+git commit -m "feat(finalizing): review and update lessons learned"
+```
+
+---
+
+## Task 3: Add lessons-learned read step to brainstorming skill
+
+<!-- tdd: trivial -->
+<!-- checkpoint: none -->
+
+**File:** `skills/brainstorming/SKILL.md`
+
+In step 2 (Understand the idea), add a new bullet after "check package.json/dependencies and module structure":
+
+```markdown
+   - **Check `docs/lessons.md`** if it exists — known constraints and patterns may affect the design.
+```
+
+The full relevant part of step 2 should become:
+
+```markdown
+2. **Understand the idea** — read existing code, docs, and recent commits. Grep for related functionality, check package.json/dependencies and module structure. **Check `docs/lessons.md`** if it exists — known constraints and patterns may affect the design. Read only what's necessary to ground the design — don't read the entire codebase. Ask questions to refine the idea. Prefer multiple choice when possible. After each question, check: can you clearly articulate (a) what the user wants to build, (b) why, and (c) key constraints? If yes, present your understanding as a short summary and ask: "Should I proceed with this, or is there more to add?" The human decides when to move on.
+```
+
+**Command:**
+```
+git add skills/brainstorming/SKILL.md
+git commit -m "feat(brainstorming): read lessons learned for design context"
+```
+
+---
+
+## Task 4: Add lessons-learned read step to writing-plans skill
+
+<!-- tdd: trivial -->
+<!-- checkpoint: none -->
+
+**File:** `skills/writing-plans/SKILL.md`
+
+In step 1 (Check for a design doc), add a new sentence after "If no design doc exists, ask the user to describe what they want to build and read relevant code.":
+
+```markdown
+   **Read `docs/lessons.md`** if it exists — incorporate known patterns into the task breakdown (e.g., if a lesson says "always run lint before commit," include that in relevant task instructions).
+```
+
+**Command:**
+```
+git add skills/writing-plans/SKILL.md
+git commit -m "feat(writing-plans): read lessons learned for task breakdown"
+```
+
+---
+
+## Task 5: Update README.md with lessons-learned feature documentation
+
+<!-- tdd: trivial -->
+<!-- checkpoint: done -->
+
+**File:** `README.md`
+
+Add a new section after "TDD Three-Scenario Model" and before "Checkpoint Review Gates":
+
+```markdown
+### Lessons Learned
+
+A persistent rules file (`docs/lessons.md`) helps the agent learn from repeat mistakes across sessions. When the agent catches itself making the same error — like forgetting to run `make lint` — it writes a rule immediately. Future sessions (even after `/new`) pick it up automatically.
+
+```
+brainstorm → reads lessons (design context)
+plan        → reads lessons (task breakdown)
+execute     → reads lessons per task, writes new ones on repeat mistakes
+finalize    → reviews and retires stale rules
+```
+
+Rules are simple imperative bullets:
+
+- After completing each task, run `make lint && make fmt` before committing
+- Never import `testify` in this project
+- Always check for existing test helpers before writing new ones
+
+No configuration needed — the file is created automatically when the first lesson is written.
+```
+
+**Command:**
+```
+git add README.md
+git commit -m "docs: add lessons-learned section to README"
+```
+
+---
+
+## Task 6: Update CHANGELOG.md
+
+<!-- tdd: trivial -->
+<!-- checkpoint: none -->
+
+**File:** `CHANGELOG.md`
+
+Add a new entry at the top (after the header):
+
+```markdown
+## [0.13.0] - 2026-05-08
+
+### Added
+
+- Lessons learned: persistent rules file (`docs/lessons.md`) read at every workflow phase and written to when the agent catches repeat mistakes. Survives `/new` sessions.
+```
+
+Bump version in `package.json` from `0.12.0` to `0.13.0`.
+
+**Command:**
+```
+git add CHANGELOG.md package.json
+git commit -m "chore: bump version to 0.13.0"
+```

package/docs/plans/completed/2026-05-08-lessons-learned-progress.md

@@ -0,0 +1,15 @@
+# Progress: Lessons Learned
+
+Plan: docs/plans/2026-05-08-lessons-learned-implementation.md
+Branch: lessons-learned
+Started: 2026-05-08T04:21:50Z
+Last updated: 2026-05-08T04:27:15Z
+
+| # | Status | Task | Commit |
+|---|--------|------|--------|
+| 1 | ✅ done | Add lessons-learned read step to executing-tasks skill | 0ad24d6 |
+| 2 | ✅ done | Add lessons-learned review step to finalizing skill | 7ac8097 |
+| 3 | ✅ done | Add lessons-learned read step to brainstorming skill | 7cb69fe |
+| 4 | ✅ done | Add lessons-learned read step to writing-plans skill | ed0aab7 |
+| 5 | ✅ done | Update README.md with lessons-learned feature documentation | d16e407 |
+| 6 | ✅ done | Update CHANGELOG.md | 2525662 |

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/package.json

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

package/skills/brainstorming/SKILL.md

@@ -10,7 +10,7 @@ Read-only exploration. You may **not** edit or create any files except under `do
 ## Process
 
 1. **Check git state** — run `git status` and `git log --oneline -5`. If there's uncommitted work, ask the user what to do with it first.
-2. **Understand the idea** — read existing code, docs, and recent commits. Grep for related functionality, check package.json/dependencies and module structure. Read only what's necessary to ground the design — don't read the entire codebase. Ask questions to refine the idea. Prefer multiple choice when possible. After each question, check: can you clearly articulate (a) what the user wants to build, (b) why, and (c) key constraints? If yes, present your understanding as a short summary and ask: "Should I proceed with this, or is there more to add?" The human decides when to move on.
+2. **Understand the idea** — read existing code, docs, and recent commits. Grep for related functionality, check package.json/dependencies and module structure. **Check `docs/lessons.md`** if it exists — known constraints and patterns may affect the design. Read only what's necessary to ground the design — don't read the entire codebase. Ask questions to refine the idea. Prefer multiple choice when possible. After each question, check: can you clearly articulate (a) what the user wants to build, (b) why, and (c) key constraints? If yes, present your understanding as a short summary and ask: "Should I proceed with this, or is there more to add?" The human decides when to move on.
 3. **Explore approaches** — propose 2-3 approaches. For each approach, sketch the concrete interface (types, method signatures, example caller code) so the comparison is grounded in actual code, not abstract descriptions. Lead with your recommendation.
 4. **Present the design** — break it into focused sections. Each section should be one screen of reading. Present each section to the human and wait for approval before continuing. Cover: architecture, components, data flow, error handling, testing. On feedback, incorporate it and re-present the revised section.
 

package/skills/executing-tasks/SKILL.md

@@ -29,29 +29,84 @@ 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. **Create the progress file** in the worktree — save to `<worktree>/docs/plans/<plan-name>-progress.md`:
+
+      ```markdown
+      # Progress: <topic>
+
+      Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
+      Branch: <feature-name>
+      Started: <ISO timestamp>
+      Last updated: <ISO timestamp>
+
+      | # | Status | Task | Commit |
+      |---|--------|------|--------|
+      | 1 | ⬜ pending | Task description (preserve checkpoint labels) | — |
+      ```
+
+      This ensures the new session in the worktree will detect the progress file and resume correctly.
+
+   f. **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
 
@@ -94,7 +149,7 @@ Implement the plan from `docs/plans/*-implementation.md` task by task, with file
 For each task the agent works on:
 
 1. **Mark in-progress** — update the progress file: `🔄 in-progress`
-2. **Read the plan selectively** — read the plan's overview section (everything before `## Task 1:`). Skim all `## Task N:` headings for dependency awareness. Then read the current task's body in full.
+2. **Read the plan selectively** — read the plan's overview section (everything before `## Task 1:`). Skim all `## Task N:` headings for dependency awareness. Then read the current task's body in full. **Read `docs/lessons.md` if it exists** — follow all rules listed there while working on this task.
 3. **Write the test** — for `new-feature`: write a failing test. For `modifying-tested-code`: run existing tests first. For `trivial`: skip steps 3-5, go to step 6.
 4. **Run the test** — confirm it fails (new-feature) or passes (modifying-tested-code). Fix if needed.
 5. **⏸ PAUSE if `checkpoint: test`** — present the [checkpoint review](#checkpoint-review) below. Wait for human input. On changes, update and re-present at this same pause.
@@ -108,10 +163,26 @@ For each task the agent works on:
    - **Seam discipline** — don't introduce abstraction unless something actually varies across it. One adapter = hypothetical seam. Two adapters = real seam
 
    Run tests after each refactor step. Never refactor while tests are failing.
-10. **⏸ PAUSE if `checkpoint: done`** — present the [checkpoint review](#checkpoint-review) below. Wait for human input. On changes, update and re-present at this same pause.
-11. **Commit** — `git add` the relevant files and commit with a clear message.
-12. **Update progress** — mark `✅ done` + record the commit hash.
-13. **Suggest session break if needed** — after completing ~3-5 tasks since the last break, suggest:
+10. **Learn from mistakes** — if you caught yourself making a mistake during this task that you've made before or that would apply to future tasks, append a rule to `docs/lessons.md`. Only add rules that would change future behavior. If the file doesn't exist, create it with the standard format (see below). Do not add one-off errors or things you self-corrected immediately.
+
+    **`docs/lessons.md` format:**
+    ```markdown
+    # Lessons Learned
+
+    <!--
+    Agent: read this at the start of each task during executing-tasks.
+    Follow every rule. Add new rules when you catch yourself making repeat mistakes.
+    Retire rules that no longer apply during finalizing.
+    -->
+
+    ## Rules
+
+    - <new rule here>
+    ```
+11. **⏸ PAUSE if `checkpoint: done`** — present the [checkpoint review](#checkpoint-review) below. Wait for human input. On changes, update and re-present at this same pause.
+12. **Commit** — `git add` the relevant files and commit with a clear message.
+13. **Update progress** — mark `✅ done` + record the commit hash.
+14. **Suggest session break if needed** — after completing ~3-5 tasks since the last break, suggest:
     ```
     ✅ Tasks N-M done (commits: abc, def)
     Progress: X/Y tasks done
@@ -121,7 +192,7 @@ For each task the agent works on:
        (or just say "continue" to keep going here)
     ```
     Also suggest at checkpoint review pauses when multiple tasks have been completed since the last break. Respect the user's choice if they say "continue".
-14. **Loop** — go back to step 1 for the next `⬜ pending` task, or see [After all tasks](#after-all-tasks) if none remain.
+15. **Loop** — go back to step 1 for the next `⬜ pending` task, or see [After all tasks](#after-all-tasks) if none remain.
 
 ## Checkpoint review
 
@@ -199,6 +270,7 @@ When the user shares code review feedback (outside of a checkpoint pause):
 2. Check git log — recent commits may reveal context
 3. Ask the user — it's better to clarify than to guess wrong
 4. If still stuck after asking, mark the task `❌ failed` with the reason in the progress file and move to the next task
+5. **Check `docs/lessons.md`** — a previous lesson may be relevant to your current problem.
 
 ## After all tasks
 

package/skills/finalizing/SKILL.md

@@ -35,12 +35,34 @@ Wait for the user to confirm before proceeding.
 
    Each `mv` gracefully handles the case where no matching files exist (e.g., if the user skipped straight from brainstorm to finalize without executing tasks).
 
-2. **Update documentation** — if the API or surface changed:
+2. **Review lessons learned** — if `docs/lessons.md` exists, review it:
+   - Add any lessons from this session that were missed during execution
+   - Retire rules that no longer apply (remove the bullet)
+   - If no changes are needed, leave it as-is
+
+   If `docs/lessons.md` doesn't exist but lessons were learned this session, create it with the standard format:
+
+   ```markdown
+   # Lessons Learned
+
+   <!--
+   Agent: read this at the start of each task during executing-tasks.
+   Follow every rule. Add new rules when you catch yourself making repeat mistakes.
+   Retire rules that no longer apply during finalizing.
+   -->
+
+   ## Rules
+
+   - <rule 1>
+   - <rule 2>
+   ```
+
+3. **Update documentation** — if the API or surface changed:
    - Update README.md
    - Update CHANGELOG.md
    - Update any inline docs
 
-3. **Choose a merge strategy** — ask the human which option they prefer:
+4. **Choose a merge strategy** — ask the human which option they prefer:
 
    1. **Create PR** — push and open a PR for external review:
       ```
@@ -87,7 +109,7 @@ Wait for the user to confirm before proceeding.
 
    For options 2–4, confirm the detected parent branch with the human before proceeding.
 
-4. **Clean up** — if a worktree was used, remove it:
+5. **Clean up** — if a worktree was used, remove it:
    ```
    git worktree remove ../<repo>-<feature-name>
    ```

package/skills/writing-plans/SKILL.md

@@ -9,7 +9,7 @@ You may only create or edit files under `docs/plans/`. Do not modify source code
 
 ## Process
 
-1. **Check for a design doc** — look for `docs/plans/*-design.md`. If one exists, use it as the basis for the plan. If the design doc is incomplete, fill gaps by asking the human. If no design doc exists, ask the user to describe what they want to build and read relevant code.
+1. **Check for a design doc** — look for `docs/plans/*-design.md`. If one exists, use it as the basis for the plan. If the design doc is incomplete, fill gaps by asking the human. If no design doc exists, ask the user to describe what they want to build and read relevant code. **Read `docs/lessons.md`** if it exists — incorporate known patterns into the task breakdown (e.g., if a lesson says "always run lint before commit," include that in relevant task instructions).
 2. **Write the implementation plan** — break the design into tasks. Save to `docs/plans/YYYY-MM-DD-<topic>-implementation.md`. If the design is too large for ~15 tasks, flag this to the human and ask whether to reduce scope or proceed with the full plan.
 3. **Present the plan** — show the complete plan to the human. Wait for approval before suggesting execution.