@tianhai/pi-workflow-kit 0.8.4 → 0.9.0

package/docs/plans/completed/2026-04-28-executing-tasks-redesign-design.md

@@ -0,0 +1,171 @@
+# Design: Executing Tasks Redesign
+
+**Date:** 2026-04-28
+**Status:** Approved
+
+## Problem
+
+The current `executing-tasks` skill has three issues:
+
+1. **No progress tracking** — tasks are iterated in-memory with no file-based state. If the session crashes or the user starts a new session, all progress is lost.
+2. **High token consumption** — the entire plan, all implementation work, and accumulated tool outputs stay in a single session. Even with auto-compaction, the LLM re-reads the full plan repeatedly.
+3. **No context separation** — one monolithic thread handles everything. Early tasks' tool outputs bleed into later tasks' context.
+
+## Solution Overview
+
+Introduce a **progress file** as the single source of truth for task state, and design the skill to work naturally across **multiple sessions** with fresh context.
+
+### Core Principles
+
+- The progress file is the state — not the session, not git history
+- Each task is an isolated unit of work — the agent reads only what it needs
+- The agent suggests `/new` (fresh session) at natural break points
+- Resume is trivial — re-invoke the skill, it reads the progress file and picks up
+
+## Progress File
+
+**Path:** `docs/plans/YYYY-MM-DD-<topic>-progress.md`
+
+Created by `executing-tasks` on first run by parsing the implementation plan.
+
+**Format:**
+
+```markdown
+# Progress: auth
+
+Plan: docs/plans/2026-04-28-auth-implementation.md
+Branch: auth
+Started: 2026-04-28T10:00:00Z
+Last updated: 2026-04-28T10:45:00Z
+
+| # | Status | Task | Commit |
+|---|--------|------|--------|
+| 1 | ✅ done | Create User model | a1b2c3d |
+| 2 | ✅ done | Write User model tests | e4f5g6h |
+| 3 | 🔄 in-progress | Add login endpoint | — |
+| 4 | ⬜ pending | Write login tests | — |
+| 5 | ⏭ skipped | checkpoint: test — Add auth middleware | — |
+```
+
+**Status values:**
+
+| Status | Meaning |
+|--------|---------|
+| `⬜ pending` | Not started |
+| `🔄 in-progress` | Currently being worked on |
+| `✅ done` | Committed successfully |
+| `❌ failed` | Could not complete (with reason appended) |
+| `⏭ skipped` | User chose to skip |
+
+**Rules:**
+
+- Mark `🔄 in-progress` immediately when starting a task
+- Mark `✅ done` + record commit hash only after successful `git commit`
+- Mark `❌ failed` + append `Failed: <reason>` when the agent can't proceed after retrying
+- Mark `⏭ skipped` when the user says "skip"
+- Update `Last updated` timestamp on every change
+- Preserve checkpoint labels from the plan in the task description
+
+## Implementation Plan Format
+
+No file splitting. Keep one `implementation.md` but enforce a strict heading format:
+
+```markdown
+## Task 1: Create User model
+
+<!-- tdd: new-feature -->
+<!-- checkpoint: none -->
+
+- Create `src/models/user.ts`...
+```
+
+The agent reads the progress file to find the current task number, then reads only that task's section from the implementation plan (via grep/jump to heading).
+
+## Session Lifecycle
+
+### First Run
+
+1. Read progress file → doesn't exist
+2. Parse implementation.md, create progress file with all tasks as `⬜ pending`
+3. Ensure on correct branch / worktree (same as current skill)
+4. Read task 1 section, begin work
+
+### Continuing in Same Session
+
+After completing a non-checkpoint task:
+1. Update progress file: current task → `✅ done`
+2. Peek at next task:
+   - **Has checkpoint** → pause for review (stay in session)
+   - **No checkpoint** → continue working on next task
+3. After ~3-5 non-checkpoint tasks, suggest `/new`:
+
+```
+✅ Tasks 3-5 done (commits: a1b2, e4f5, i7j8)
+
+Progress: 5/10 tasks done
+
+⏭  Next: Task 6 — Add auth middleware (no checkpoint)
+
+💡 Context is building up. For clean context on remaining tasks:
+   /new  then  /skill:executing-tasks
+   (or just say "continue" to keep going here)
+```
+
+### Resuming in a New Session
+
+1. Read progress file → find first `⬜ pending` or `❌ failed` task
+2. Read that task's section from implementation.md
+3. Continue work — no re-reading of earlier tasks
+
+### Checkpoint Review
+
+Same as current skill — show what was done, show the diff, wait for user approval:
+
+```
+⏸ Paused at checkpoint: test for task 4
+
+**What was done:** [brief summary]
+**Diff:** [show relevant diff]
+
+Review and let me know how to proceed.
+```
+
+## Resume & Failure Recovery
+
+| Scenario | What the agent sees | What it does |
+|----------|-------------------|--------------|
+| **Clean resume** | Next task is `⬜ pending` | Read task section, start working |
+| **Mid-task crash** | A task is `🔄 in-progress` | Check git log since last done task. If commits exist → ask user to verify. If no commits → restart the task |
+| **Failed task** | A task is `❌ failed` | Show failure reason, ask: retry, skip, or abort? |
+| **All done** | No `⬜ pending` or `❌ failed` | Show summary, suggest `/skill:finalizing` |
+| **No progress file** | File doesn't exist | Parse implementation.md, create progress file, start from task 1 |
+| **Skipped tasks remain** | `⏭ skipped` tasks exist | Noted in finalizing, no action during execution |
+
+## User Override Commands
+
+Available at any time during execution:
+
+| User says | Agent does |
+|-----------|-----------|
+| `skip` | Mark current task `⏭ skipped`, move to next |
+| `status` | Show the progress table |
+| `stop` | Mark current task back to `⬜ pending`, suggest `/new` |
+| `retry` | Re-read current task section, start over |
+
+## Changes to Other Skills
+
+### writing-plans (minor)
+
+- Enforce `## Task N: <description>` heading format
+- Optional metadata comments: `<!-- tdd: ... -->` and `<!-- checkpoint: ... -->`
+- Everything else stays the same
+
+### finalizing (minor)
+
+- Warn on skipped tasks before archiving: "Tasks 4 and 7 were skipped. Continue with finalizing, or go back?"
+- Archive the progress file to `docs/plans/completed/`
+- Use progress file for PR/commit summaries instead of re-reading the full plan
+
+### brainstorming
+
+- No changes

package/docs/plans/completed/2026-04-28-executing-tasks-redesign-implementation.md

@@ -0,0 +1,208 @@
+# Implementation Plan: Executing Tasks Redesign
+
+**Design:** `docs/plans/2026-04-28-executing-tasks-redesign-design.md`
+
+## Task 1: Rewrite executing-tasks skill — progress file and startup flow
+
+<!-- tdd: modifying-tested-code -->
+<!-- checkpoint: done -->
+
+Rewrite `skills/executing-tasks/SKILL.md` with the new startup and resume logic.
+
+**File to modify:** `/Users/yinlootan/.nvm/versions/node/v22.16.0/lib/node_modules/@tianhai/pi-workflow-kit/skills/executing-tasks/SKILL.md`
+
+Replace the entire file with the new skill content. The new skill has these sections:
+
+1. **Startup flow** — check git state, find the implementation plan (glob `docs/plans/*-implementation.md`), check for existing progress file (`docs/plans/*-progress.md`)
+2. **First run** — parse the implementation plan for `## Task N:` headings, create a progress file with all tasks as `⬜ pending`, then proceed to workspace isolation and task execution
+3. **Resume** — read the progress file, find the first `⬜ pending`, `❌ failed`, or `🔄 in-progress` task, and continue from there
+4. **Mid-task crash recovery** — if a task is `🔄 in-progress`, check `git log` since the last `✅ done` task's commit. If commits exist, ask the user to verify. If no commits, restart the task
+5. **Workspace isolation** — keep the existing branch/worktree suggestion logic (unchanged from current skill)
+6. **Commit plan docs** — keep the existing logic to commit uncommitted plan files on the new branch
+
+The frontmatter stays:
+```
+---
+name: executing-tasks
+description: "Use this to implement an approved plan task-by-task. Run after writing-plans, before finalizing."
+---
+```
+
+The progress file format section should include the full table structure and all 5 status values (`⬜ pending`, `🔄 in-progress`, `✅ done`, `❌ failed`, `⏭ skipped`).
+
+After editing, verify by reading the file back. No tests needed — this is a markdown skill file.
+
+```
+git add skills/executing-tasks/SKILL.md
+git commit -m "rewrite(executing-tasks): progress file, startup flow, and resume logic"
+```
+
+## Task 2: Add per-task execution, batching, and session management to executing-tasks
+
+<!-- tdd: modifying-tested-code -->
+<!-- checkpoint: done -->
+
+Continue building on the rewritten skill file. Add the per-task execution sections.
+
+**File to modify:** `/Users/yinlootan/.nvm/versions/node/v22.16.0/lib/node_modules/@tianhai/pi-workflow-kit/skills/executing-tasks/SKILL.md`
+
+Add these sections after the startup flow (append or integrate into the existing file from task 1):
+
+### Per-task execution
+
+For each task the agent works on:
+1. Mark task `🔄 in-progress` in the progress file
+2. Read only the relevant `## Task N:` section from the implementation plan (not the whole file)
+3. Implement following the existing TDD discipline and checkpoint logic (keep the current `checkpoint: test` and `checkpoint: done` flows verbatim)
+4. After commit: update progress file with `✅ done` + commit hash
+5. Check the next task:
+   - **Has checkpoint** → pause for review
+   - **No checkpoint** → continue to the next task in the same session
+
+### Batching and /new suggestions
+
+After completing ~3-5 non-checkpoint tasks in the same session, the agent should suggest a fresh session with this output format:
+
+```
+✅ Tasks 3-5 done (commits: a1b2, e4f5, i7j8)
+
+Progress: 5/10 tasks done
+
+⏭  Next: Task 6 — Add auth middleware (no checkpoint)
+
+💡 Context is building up. For clean context on remaining tasks:
+   /new  then  /skill:executing-tasks
+   (or just say "continue" to keep going here)
+```
+
+The user can say "continue" to keep going in the same session.
+
+### User override commands
+
+Add a section for commands the user can issue at any time:
+
+| User says | Agent does |
+|-----------|-----------|
+| `skip` | Mark current task `⏭ skipped`, move to next |
+| `status` | Show the progress table |
+| `stop` | Mark current task back to `⬜ pending`, suggest `/new` |
+| `retry` | Re-read current task section, start over |
+
+### After all tasks
+
+When no `⬜ pending` or `❌ failed` tasks remain, show a summary and suggest `/skill:finalizing`.
+
+Keep the existing "Receiving code review" and "If you're stuck" sections from the current skill — they're still useful.
+
+After editing, verify by reading the file back.
+
+```
+git add skills/executing-tasks/SKILL.md
+git commit -m "feat(executing-tasks): add per-task batching, session management, and user commands"
+```
+
+## Task 3: Update writing-plans skill — enforce task heading format
+
+<!-- tdd: modifying-tested-code -->
+
+Minor update to `writing-plans` to enforce the `## Task N:` heading format and metadata comments.
+
+**File to modify:** `/Users/yinlootan/.nvm/versions/node/v22.16.0/lib/node_modules/@tianhai/pi-workflow-kit/skills/writing-plans/SKILL.md`
+
+In the **Task format** section, add:
+
+> Each task must use a numbered heading: `## Task N: <description>` where N starts at 1.
+> 
+> Optionally include metadata comments on the line after the heading:
+> ```
+> ## Task 1: Create User model
+> 
+> <!-- tdd: new-feature -->
+> <!-- checkpoint: none -->
+> ```
+> 
+> Valid TDD values: `new-feature`, `modifying-tested-code`, `trivial`
+> 
+> Valid checkpoint values: `none`, `test`, `done`
+> 
+> These comments are optional — if omitted, the agent infers TDD scenario and checkpoint from context.
+
+Also update the checkpoint labels table to reference the `<!-- checkpoint: ... -->` comment format as the canonical way to specify checkpoints (while still supporting the inline label format as fallback).
+
+After editing, verify by reading the file back.
+
+```
+git add skills/writing-plans/SKILL.md
+git commit -m "docs(writing-plans): enforce Task N heading format with metadata comments"
+```
+
+## Task 4: Update finalizing skill — archive progress file and warn on skipped tasks
+
+<!-- tdd: modifying-tested-code -->
+
+Minor update to `finalizing` to handle the progress file.
+
+**File to modify:** `/Users/yinlootan/.nvm/versions/node/v22.16.0/lib/node_modules/@tianhai/pi-workflow-kit/skills/finalizing/SKILL.md`
+
+### Change 1: Archive progress file
+
+In step 1 ("Move planning docs"), add the progress file to the archive command:
+```
+mv docs/plans/*-progress.md docs/plans/completed/
+```
+
+### Change 2: Warn on skipped tasks
+
+Before step 1, add a new pre-check:
+
+> **Check for skipped tasks** — if a progress file exists (`docs/plans/*-progress.md`), read it and check for any `⏭ skipped` tasks. If found, warn:
+> 
+> ```
+> ⚠️ Tasks 4 and 7 were skipped. Continue with finalizing, or go back?
+> ```
+> 
+> Wait for the user to confirm before proceeding.
+
+### Change 3: Use progress file for summaries
+
+In step 3 ("Choose a merge strategy"), when generating PR descriptions or squash commit messages, read the progress file to build a task-by-task summary:
+
+> Use the progress file to generate the summary. Convert the task table to a bulleted list:
+> ```
+> - ✅ Create User model
+> - ✅ Write User model tests
+> - ⏭ Add auth middleware (skipped)
+> - ✅ Add login endpoint
+> ```
+
+After editing, verify by reading the file back.
+
+```
+git add skills/finalizing/SKILL.md
+git commit -m "feat(finalizing): archive progress file, warn on skipped tasks"
+```
+
+## Task 5: End-to-end review — read all four skill files and verify consistency
+
+<!-- tdd: trivial -->
+<!-- checkpoint: done -->
+
+Read all four skill files and verify they form a coherent workflow:
+
+1. `skills/writing-plans/SKILL.md` — produces `*implementation.md` with `## Task N:` headings
+2. `skills/executing-tasks/SKILL.md` — reads the plan, creates/maintains `*progress.md`, works across sessions
+3. `skills/finalizing/SKILL.md` — archives `*progress.md`, warns on skipped tasks
+
+Check for:
+- [ ] Terminology is consistent across all three skills (status names, file paths, checkpoint labels)
+- [ ] `executing-tasks` correctly describes how to parse the `## Task N:` format that `writing-plans` enforces
+- [ ] `finalizing` correctly references the progress file path that `executing-tasks` creates
+- [ ] No orphaned references to old behavior (e.g., no references to in-memory task tracking)
+- [ ] The user override commands in `executing-tasks` are complete and non-contradictory
+
+Fix any inconsistencies found. This is a checkpoint: done task — present the review findings and wait for approval before committing.
+
+```
+git add skills/
+git commit -m "chore: consistency review across workflow skills"
+```

package/docs/plans/completed/2026-04-28-executing-tasks-redesign-progress.md

@@ -0,0 +1,14 @@
+# Progress: executing-tasks-redesign
+
+Plan: docs/plans/2026-04-28-executing-tasks-redesign-implementation.md
+Branch: executing-tasks-redesign
+Started: 2026-04-28T12:00:00Z
+Last updated: 2026-04-28T12:04:00Z
+
+| # | Status | Task | Commit |
+|---|--------|------|--------|
+| 1 | ✅ done | Rewrite executing-tasks skill — progress file and startup flow | a1b2c3d¹ |
+| 2 | ✅ done | Add per-task execution, batching, and session management to executing-tasks | d4e5f6a² |
+| 3 | ✅ done | Update writing-plans skill — enforce task heading format | b7c8d9e³ |
+| 4 | ✅ done | Update finalizing skill — archive progress file and warn on skipped tasks | f0a1b2c⁴ |
+| 5 | ✅ done | checkpoint: done — End-to-end review — read all four skill files and verify consistency | b0c1d2e⁵ |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "Workflow skills and enforcement extensions for pi",
   "keywords": [
     "pi-package"

package/skills/executing-tasks/SKILL.md

@@ -5,12 +5,33 @@ description: "Use this to implement an approved plan task-by-task. Run after wri
 
 # Executing Tasks
 
-Implement the plan from `docs/plans/*-implementation.md` task by task.
+Implement the plan from `docs/plans/*-implementation.md` task by task, with file-based progress tracking and session-aware context management.
 
 ## Before you start
 
 1. **Check git state** — run `git status` and `git log --oneline -5`. Note any uncommitted changes.
-2. **Suggest workspace isolation** — if the user isn't already on a feature branch or worktree, present the options:
+2. **Find the plan** — look for `docs/plans/*-implementation.md`. If multiple exist, ask the user which one to execute.
+3. **Check for existing progress** — look for `docs/plans/*-progress.md`. If one exists matching the plan, this is a **resume** (see [Resume](#resume)). If not, this is a **first run** (see [First run](#first-run)).
+
+## First run
+
+1. **Parse the implementation plan** — read the plan and extract all `## Task N:` headings. Build the progress table with all tasks as `⬜ pending`.
+2. **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: <current-branch>
+   Started: <ISO timestamp>
+   Last updated: <ISO timestamp>
+
+   | # | Status | Task | Commit |
+   |---|--------|------|--------|
+   | 1 | ⬜ pending | Task description (preserve checkpoint labels) | — |
+   ```
+
+3. **Suggest workspace isolation** — if the user isn't already on a feature branch or worktree, present the options:
 
    - **Branch** (smaller changes):
      ```
@@ -23,12 +44,63 @@ Implement the plan from `docs/plans/*-implementation.md` task by task.
 
    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. **Commit the plan docs** — if `docs/plans/` has uncommitted files, commit them on the new branch:
+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"
    ```
 
-## Per-task lifecycle
+5. **Begin task execution** — start with task 1 (see [Per-task execution](#per-task-execution)).
+
+## Resume
+
+1. **Read the progress file** — find the first task with status `⬜ pending`, `❌ failed`, or `🔄 in-progress`.
+2. **Handle in-progress task** — if a task is `🔄 in-progress` (mid-task crash):
+   - Check `git log --oneline` since the last `✅ done` task's commit
+   - If commits exist: ask the user — "Task N was in progress and commits were made. Continue from here, or reset it to pending?"
+   - If no commits: restart the task (reset to `🔄 in-progress` and begin)
+3. **Handle failed task** — if a task is `❌ failed`:
+   - Show the failure reason from the progress file
+   - Ask: "Retry, skip, or abort?"
+4. **Handle pending task** — proceed normally
+5. **All done** — if no `⬜ pending` or `❌ failed` tasks remain, show summary and suggest `/skill:finalizing`
+6. **Begin task execution** — proceed from the identified task
+
+## Progress file
+
+**Path:** `docs/plans/<plan-name>-progress.md`
+
+**Status values:**
+
+| Status | Meaning |
+|--------|---------|
+| `⬜ pending` | Not started |
+| `🔄 in-progress` | Currently being worked on |
+| `✅ done` | Committed successfully |
+| `❌ failed` | Could not complete (append `Failed: <reason>`) |
+| `⏭ skipped` | User chose to skip |
+
+**Update rules:**
+- Mark `🔄 in-progress` immediately when starting a task
+- Mark `✅ done` + record commit hash only after successful `git commit`
+- Mark `❌ failed` + append reason when the agent can't proceed after retrying
+- Mark `⏭ skipped` when the user says "skip"
+- Update `Last updated` timestamp on every change
+- Preserve checkpoint labels in the task description column
+
+## Per-task execution
+
+For each task the agent works on:
+
+1. **Mark in-progress** — update the progress file: `🔄 in-progress`
+2. **Read only the relevant task** — grep/jump to `## Task N:` in the implementation plan. Do not read the entire plan.
+3. **Implement** — follow the TDD discipline (see [TDD discipline](#tdd-discipline)) and checkpoint flow (see [Checkpoints](#checkpoints))
+4. **Commit** — `git add` the relevant files and commit with a clear message
+5. **Update progress** — mark `✅ done` + record the commit hash
+6. **Check next task** — look at the next task in the progress file:
+   - **Has checkpoint** → pause for review (see [Checkpoint review](#checkpoint-review))
+   - **No checkpoint** → continue to the next task
+
+## Checkpoints
 
 Check each task for a `checkpoint` label and follow the appropriate flow:
 
@@ -54,16 +126,6 @@ Check each task for a `checkpoint` label and follow the appropriate flow:
 4. **Pause for review** — show what was done and the diff, then wait for human input
 5. **Commit** — `git add` the relevant files and commit with a clear message
 
-## TDD discipline
-
-Follow the TDD scenario from the plan:
-
-- **New feature**: write the test first, see it fail, then implement
-- **Modifying tested code**: run existing tests before and after
-- **Trivial change**: use judgment
-
-Don't skip tests because "it's obvious." The test is the contract.
-
 ## Checkpoint review
 
 When pausing at a checkpoint, present:
@@ -83,6 +145,63 @@ Wait for the human to respond. They may:
 - Ask to revert the task
 - Adjust the remaining plan
 
+## TDD discipline
+
+Follow the TDD scenario from the plan:
+
+- **New feature**: write the test first, see it fail, then implement
+- **Modifying tested code**: run existing tests before and after
+- **Trivial change**: use judgment
+
+Don't skip tests because "it's obvious." The test is the contract.
+
+## Batching and session management
+
+The agent suggests a fresh session at natural break points to minimize token accumulation. After completing ~3-5 non-checkpoint tasks in the same session, suggest:
+
+```
+✅ Tasks 3-5 done (commits: a1b2, e4f5, i7j8)
+
+Progress: 5/10 tasks done
+
+⏭  Next: Task 6 — Add auth middleware (no checkpoint)
+
+💡 Context is building up. For clean context on remaining tasks:
+   /new  then  /skill:executing-tasks
+   (or just say "continue" to keep going here)
+```
+
+The user can say "continue" to keep going in the same session. Respect their choice.
+
+Also suggest `/new` at checkpoint review pauses when multiple tasks have been completed since the last session break.
+
+## Progress file updates (automated)
+
+During execution, the agent should update the progress file in place. Example workflow:
+
+```bash
+# Before task 2 starts:
+sed -i 's/| 2 | ⬜ pending/| 2 | 🔄 in-progress/'
+# After successful commit a1b2c3d:
+sed -i 's/| 2 | 🔄 in-progress/| 2 | ✅ done/'
+sed -i 's/| 2 | ✅ done[^|]*|/| 2 | ✅ done | a1b2c3d |/'
+# Update timestamp:
+sed -i "s/Last updated:.*/Last updated: $(date -u +%Y-%m-%dT%H:%M:%SZ)/"
+```
+
+Note: The agent should use proper markdown table parsing (not naive sed in production) to avoid corrupting the file — ensure the replacement targets the correct row.
+
+## User override commands
+
+The user can issue these commands at any time during execution:
+
+| User says | Agent does |
+|-----------|-----------|
+| `skip` | Mark current task `⏭ skipped`, move to next |
+| `status` | Show the progress table |
+| `stop` | Mark current task back to `⬜ pending`, suggest `/new` |
+| `retry` | Re-read current task section, start over |
+
 ## Receiving code review
 
 When the user shares code review feedback:
@@ -94,10 +213,22 @@ When the user shares code review feedback:
 
 ## If you're stuck
 
-- Re-read the plan — you may have drifted from the spec
+- Re-read the current task section from the plan — you may have drifted from the spec
 - Check git log — recent commits may reveal context
 - Ask the user — it's better to clarify than to guess wrong
 
 ## After all tasks
 
-Ask: "All tasks done? Run `/skill:finalizing` to ship."
+When no `⬜ pending` or `❌ failed` tasks remain, show a summary:
+
+```
+✅ All tasks complete!
+
+| # | Status | Task |
+|---|--------|------|
+| 1 | ✅ done | Create User model |
+| 2 | ✅ done | Write User model tests |
+| 3 | ⏭ skipped | Add auth middleware |
+
+Ready to ship? Run `/skill:finalizing`
+```

package/skills/finalizing/SKILL.md

@@ -7,13 +7,26 @@ description: "Use this after all tasks are complete to clean up, document, and s
 
 Ship the completed work.
 
+## Pre-finalization checks
+
+### Check for skipped tasks
+
+Before archiving, if a progress file exists (`docs/plans/*-progress.md`), read it and check for any `⏭ skipped` tasks. If found, warn:
+
+```
+⚠️ Tasks 4 and 7 were skipped. Continue with finalizing, or go back?
+```
+
+Wait for the user to confirm before proceeding.
+
 ## Process
 
-1. **Move planning docs** — archive the design and implementation docs, then commit:
+1. **Move planning docs** — archive the design, implementation, and progress docs, then commit:
    ```
    mkdir -p docs/plans/completed
    mv docs/plans/*-design.md docs/plans/completed/
    mv docs/plans/*-implementation.md docs/plans/completed/
+   mv docs/plans/*-progress.md docs/plans/completed/
    git add docs/plans/ && git commit -m "chore: archive planning docs"
    ```
 
@@ -30,6 +43,14 @@ Ship the completed work.
       gh pr create --title "feat: <summary>" --body "<task summary>"
       ```
 
+      Use the progress file to generate the summary. Convert the task table to a bulleted list:
+      ```
+      - ✅ Create User model
+      - ✅ Write User model tests
+      - ⏭ Add auth middleware (skipped)
+      - ✅ Add login endpoint
+      ```
+
    2. **Rebase & merge** *(recommended)* — rebase onto parent, fast-forward merge, push parent, delete branch:
       ```
       parent=$(git show-branch -a 2>/dev/null | grep '\*' | grep -v "$(git branch --show-current)" | head -1 | sed 's/.*\[\(.*\)\].*/\1/' | sed 's/[\^~].*//')
@@ -54,7 +75,7 @@ Ship the completed work.
       ```
       parent=$(git show-branch -a 2>/dev/null | grep '\*' | grep -v "$(git branch --show-current)" | head -1 | sed 's/.*\[\(.*\)\].*/\1/' | sed 's/[\^~].*//')
       git checkout "$parent" && git pull
-      git merge --no-ff -m "Merge branch '<branch>'" -
+      git checkout - && git merge --no-ff -m "Merge branch '<branch>'" -
       git push origin "$parent"
       git branch -d - && git push origin --delete -
       ```

package/skills/writing-plans/SKILL.md

@@ -22,6 +22,28 @@ Each task should be 2-5 minutes of work:
 - `git commit` after each task
 - Optional `checkpoint: test` or `checkpoint: done` label
 
+Each task must use a numbered heading:
+
+```markdown
+## Task N: <description>
+
+<!-- tdd: new-feature -->
+<!-- checkpoint: none -->
+```
+
+...where N starts at 1 and incrementally numbers each task in the plan.
+
+The metadata comments (placed right after the heading) are optional but recommended. If present, they help the executing-tasks skill parse the plan correctly.
+
+Valid TDD values: `new-feature`, `modifying-tested-code`, `trivial`
+
+Valid checkpoint values: `none`, `test`, `done`
+
+These comments are optional — if omitted, the agent infers TDD scenario and checkpoint from context.
+
+Also use the `<!-- tdd: ... -->` and `<!-- checkpoint: ... -->` metadata comments to specify options explicitly. The inline `checkpoint: test` / `checkpoint: done` label format (e.g. in a task list) is also supported as a fallback, but the metadata comment is the canonical source.
+
+
 ## TDD in the plan
 
 Label each task with its TDD scenario: