@tianhai/pi-workflow-kit 0.12.0 → 0.13.2

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-migrate-earendil-works-design.md

@@ -0,0 +1,39 @@
+# Migrate from @mariozechner to @earendil-works
+
+## Context
+
+pi has moved from `@mariozechner` to `@earendil-works` on GitHub and npm. The old `@mariozechner/pi-coding-agent@0.73.1` is deprecated. This package has two unused peer deps (`pi-ai`, `pi-tui`) that should be cleaned up.
+
+## Changes
+
+### 1. `extensions/workflow-guard.ts` — update import
+
+```diff
+-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
++import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+```
+
+### 2. `package.json` — update peerDependencies
+
+```diff
+ "peerDependencies": {
+-    "@mariozechner/pi-ai": "*",
+-    "@mariozechner/pi-coding-agent": "*",
+-    "@mariozechner/pi-tui": "*",
++    "@earendil-works/pi-coding-agent": "*",
+     "@sinclair/typebox": "*"
+ },
+```
+
+- Rename `pi-coding-agent` to `@earendil-works/pi-coding-agent`
+- Remove `@mariozechner/pi-ai` (unused)
+- Remove `@mariozechner/pi-tui` (unused)
+
+## Verification
+
+- `ExtensionAPI` is exported identically from both old and new packages (same export map, same `.d.ts` path)
+- No other imports from `@mariozechner/*` exist in the codebase
+
+## Impact
+
+Users on old `@mariozechner/pi-coding-agent` will get a peer dependency resolution error — they must update pi. The old package is explicitly deprecated pointing to the new one.

package/docs/plans/completed/2026-05-08-migrate-earendil-works-implementation.md

@@ -0,0 +1,45 @@
+# Implementation Plan: Migrate from @mariozechner to @earendil-works
+
+## Task 1: Update package scope and clean up peer dependencies
+
+<!-- tdd: trivial -->
+<!-- checkpoint: done -->
+
+Migrate the sole import and peerDependencies from `@mariozechner/*` to `@earendil-works/pi-coding-agent`, dropping the two unused deps (`pi-ai`, `pi-tui`).
+
+### Files to modify
+
+1. **`extensions/workflow-guard.ts`** — line 2:
+
+```diff
+-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
++import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+```
+
+2. **`package.json`** — `peerDependencies`:
+
+```diff
+ "peerDependencies": {
+-    "@mariozechner/pi-ai": "*",
+-    "@mariozechner/pi-coding-agent": "*",
+-    "@mariozechner/pi-tui": "*",
++    "@earendil-works/pi-coding-agent": "*",
+     "@sinclair/typebox": "*"
+ },
+```
+
+### Verify
+
+```bash
+grep -r "@mariozechner" extensions/ package.json
+# Expected: no output
+
+npm run check
+# Expected: passes (lint + tests)
+```
+
+### Commit
+
+```
+chore: migrate from @mariozechner to @earendil-works, drop unused peer deps
+```

package/docs/plans/completed/2026-05-08-migrate-earendil-works-progress.md

@@ -0,0 +1,10 @@
+# Progress: Migrate from @mariozechner to @earendil-works
+
+Plan: docs/plans/2026-05-08-migrate-earendil-works-implementation.md
+Branch: migrate-earendil-works
+Started: 2026-05-08T00:00:00Z
+Last updated: 2026-05-08T00:02:00Z
+
+| # | Status | Task | Commit |
+|---|--------|------|--------|
+| 1 | ✅ done | Update package scope and clean up peer dependencies (checkpoint: done) | 0a29af0 |

package/extensions/workflow-guard.ts

@@ -1,5 +1,5 @@
 import { resolve } from "node:path";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 /**
  * Workflow Guard extension.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "0.12.0",
+  "version": "0.13.2",
   "description": "Enforce structured brainstorm→plan→execute→finalize workflow with TDD discipline in AI coding agents",
   "keywords": [
     "pi-package",
@@ -40,13 +40,12 @@
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-ai": "*",
-    "@mariozechner/pi-coding-agent": "*",
-    "@mariozechner/pi-tui": "*",
+    "@earendil-works/pi-coding-agent": "*",
     "@sinclair/typebox": "*"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.15",
+    "@earendil-works/pi-coding-agent": "*",
     "vitest": "^4.0.18"
   }
 }

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

@@ -63,7 +63,24 @@ Implement the plan from `docs/plans/*-implementation.md` task by task, with file
       Then run: /skill:executing-tasks
       ```
 
-   e. **Do not proceed with task execution.** The session ends here.
+   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:**
 
@@ -132,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.
@@ -146,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
@@ -159,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
 
@@ -237,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.