@tianhai/pi-workflow-kit 0.8.3 → 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.3",
+  "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,14 +7,27 @@ 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/
-   git add docs/plans/completed/ && git commit -m "chore: archive planning docs"
+   mv docs/plans/*-progress.md docs/plans/completed/
+   git add docs/plans/ && git commit -m "chore: archive planning docs"
    ```
 
 2. **Update documentation** — if the API or surface changed:
@@ -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:

package/docs/plans/2026-04-21-workflow-guard-safe-commands-design.md

@@ -1,172 +0,0 @@
-# Workflow Guard: Safe Commands Expansion
-
-**Date:** 2026-04-21
-**Status:** Draft
-
-## Problem
-
-The workflow guard blocks several read-only bash commands that are genuinely needed during brainstorm and plan phases. Two specific user reports:
-
-1. `cd /path && git remote -v 2>/dev/null; echo "---"; ls` — blocked due to `cd` not being allowlisted and `2>/dev/null` caught by the stdout-redirect pattern.
-2. `gh pr view 1564 --json ... 2>/dev/null || echo "gh failed"` — blocked because `gh` is not allowlisted at all.
-
-Additionally, `git status --short` is blocked because the safe regex only allows `git status` without flags.
-
-## Design
-
-### 1. Harmless redirect stripping
-
-Add a `stripHarmlessRedirects(cmd)` helper that removes `2>/dev/null` and `2>&1` before pattern matching. These are purely cosmetic (suppress stderr noise) and have no side effects.
-
-```ts
-function stripHarmlessRedirects(cmd: string): string {
-  return cmd.replace(/\s*2\s*>\s*(\/dev\/null|&1)\b/g, "");
-}
-```
-
-Apply it inside `isSafeCommand` on each sub-command before checking DESTRUCTIVE and SAFE patterns. This fixes `2>/dev/null` without loosening the redirect catch (which still blocks real writes).
-
-### 2. New SAFE_PATTERNS entries
-
-| Pattern | Rationale |
-|---------|-----------|
-| `/^\s*cd\b/` | Directory navigation — zero side effects |
-| `/^\s*gh\s+pr\s+(view\|list\|diff\|checks\|status)\b/i` | Read-only PR inspection |
-| `/^\s*gh\s+issue\s+(view\|list)\b/i` | Read-only issue inspection |
-| `/^\s*gh\s+repo\s+(view\|fork\|list)\b/i` | Read-only repo metadata |
-| `/^\s*gh\s+release\s+(view\|list\|download)\b/i` | Read-only release inspection |
-| `/^\s*gh\s+run\s+(view\|list)\b/i` | Read-only CI run inspection |
-| `/^\s*git\s+blame\b/` | Read-only file annotation |
-| `/^\s*git\s+shortlog\b/` | Read-only commit summary |
-| `/^\s*git\s+stash\s+list\b/i` | Read-only stash listing |
-| `/^\s*git\s+tag\s+(-l\|--list)\b/i` | Read-only tag listing |
-| `/^\s*git\s+describe\b/` | Read-only version info |
-
-### 3. Fix: `git status` flag handling
-
-Current regex `/^\s*git\s+(status|log|...)/i` doesn't allow common flags like `--short`, `--oneline`, `--format=...`. Refine all git safe patterns to optionally accept trailing flags and args:
-
-```ts
-/^\s*git\s+status\b/i,
-/^\s*git\s+log\b/i,
-/^\s*git\s+diff\b/i,
-/^\s*git\s+show\b/i,
-/^\s*git\s+blame\b/i,
-// etc.
-```
-
-The existing patterns already anchor to `^\s*git\s+<subcommand>` — the issue was that `git status --short` didn't match because some patterns had more restrictive anchoring. Reviewing the code: the patterns use `\b` word boundaries which should allow flags. The actual issue with `git status --short && git log --oneline -5` is that the `git log --oneline -5` part is safe, but `git status --short` — let me verify: `/^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get)/i` — `git status` has a `\b` after the group? No, there's no trailing `\b`. So `git status --short` **should** match since the pattern doesn't require end-of-string. The real blocker for that compound command was the `&&` splitting — `git log --oneline -5` — `-5` shouldn't be an issue either.
-
-**Conclusion on item 3:** The `git status --short` case was a false alarm caused by compound command parsing combined with the `2>/dev/null` redirect in the user's actual commands, not a pattern bug. No change needed here beyond the redirect fix.
-
-### 4. What we're NOT adding (YAGNI)
-
-- `sed -i` (in-place editing) — correctly destructive
-- `gh pr create/merge/close` — write operations
-- `curl -o file` (output to file) — the redirect catch blocks this
-- `cut`, `tr`, `column`, `base64` — rarely needed; can add later on demand
-- `gh api` — too broad; can be used for mutations. Require specific subcommands.
-
-## Data flow
-
-No new data flow. The changes are purely additive to the pattern-matching logic in `isSafeCommand`.
-
-## Error handling
-
-No new error paths. The existing block-and-warn behavior remains unchanged.
-
-## Testing
-
-Manual verification with the exact commands that were blocked:
-
-1. `cd /some/path && git remote -v 2>/dev/null; echo "---"; ls` → allowed
-2. `gh pr view 1564 --repo owner/repo --json title,body,files 2>/dev/null || echo "gh failed"` → allowed
-3. `git stash list` → allowed
-4. `git tag -l` → allowed
-5. `rm -rf /` → still blocked ✓
-6. `git push origin main` → still blocked ✓
-
-## Tests
-
-Add the following test cases to the existing `tests/workflow-guard.test.ts` `isSafeCommand` describe block:
-
-### New: `cd` navigation
-```ts
-it("allows cd", () => {
-	expect(isSafeCommand("cd /some/path")).toBe(true);
-	expect(isSafeCommand("cd src && ls")).toBe(true);
-});
-```
-
-### New: GitHub CLI read-only subcommands
-```ts
-it("allows gh read-only subcommands", () => {
-	expect(isSafeCommand("gh pr view 1564 --json title,body")).toBe(true);
-	expect(isSafeCommand("gh pr list --repo owner/repo")).toBe(true);
-	expect(isSafeCommand("gh pr diff 1564")).toBe(true);
-	expect(isSafeCommand("gh issue view 42")).toBe(true);
-	expect(isSafeCommand("gh issue list --label bug")).toBe(true);
-	expect(isSafeCommand("gh repo view owner/repo")).toBe(true);
-	expect(isSafeCommand("gh run view 12345")).toBe(true);
-});
-
-it("blocks gh write subcommands", () => {
-	expect(isSafeCommand("gh pr create --title 'fix'")).toBe(false);
-	expect(isSafeCommand("gh pr merge 1564")).toBe(false);
-	expect(isSafeCommand("gh issue close 42")).toBe(false);
-	expect(isSafeCommand("gh release create v1.0")).toBe(false);
-});
-```
-
-### New: Git read-only subcommands
-```ts
-it("allows git read-only subcommands (new additions)", () => {
-	expect(isSafeCommand("git blame src/index.ts")).toBe(true);
-	expect(isSafeCommand("git shortlog -sn")).toBe(true);
-	expect(isSafeCommand("git stash list")).toBe(true);
-	expect(isSafeCommand("git tag -l")).toBe(true);
-	expect(isSafeCommand("git tag --list 'v*'")).toBe(true);
-	expect(isSafeCommand("git describe --tags")).toBe(true);
-});
-
-it("still blocks git stash mutations", () => {
-	expect(isSafeCommand("git stash push -m 'wip'")).toBe(false);
-	expect(isSafeCommand("git stash pop")).toBe(false);
-});
-```
-
-### New: Harmless stderr redirect stripping
-```ts
-it("allows 2>/dev/null on safe commands", () => {
-	expect(isSafeCommand("git remote -v 2>/dev/null")).toBe(true);
-	expect(isSafeCommand("gh pr view 1564 2>/dev/null")).toBe(true);
-	expect(isSafeCommand("npm list 2>/dev/null")).toBe(true);
-});
-
-it("allows 2>&1 on safe commands", () => {
-	expect(isSafeCommand("git log 2>&1")).toBe(true);
-});
-
-it("still blocks stdout redirects even with stderr redirect present", () => {
-	expect(isSafeCommand("echo 'hello' > file.ts 2>/dev/null")).toBe(false);
-	expect(isSafeCommand("cat config > backup.txt 2>/dev/null")).toBe(false);
-});
-```
-
-### New: Compound commands from real user scenarios
-```ts
-it("allows the exact user-reported blocked commands", () => {
-	// Scenario 1: directory navigation + git remote + ls
-	expect(isSafeCommand("cd /Users/u/partying/pt-room && git remote -v 2>/dev/null; echo '---'; ls")).toBe(true);
-	// Scenario 2: gh pr view with fallback
-	expect(isSafeCommand("gh pr view 1564 --repo olachat/pt-partying --json title,body,files,additions,deletions 2>/dev/null || echo 'gh failed'")).toBe(true);
-});
-```
-
-## Summary
-
-| Change | Location | Size |
-|--------|----------|------|
-| Add `stripHarmlessRedirects()` | Above `isSafeCommand` | ~3 lines |
-| Call it in `isSafeCommand` loop body | Inside `isSafeCommand` | 1 line changed |
-| Add 10 new SAFE_PATTERNS entries | `SAFE_PATTERNS` array | ~10 lines |

package/docs/plans/2026-04-21-workflow-guard-safe-commands-implementation.md

@@ -1,168 +0,0 @@
-# Workflow Guard: Safe Commands Expansion — Implementation Plan
-
-**Design:** `docs/plans/2026-04-21-workflow-guard-safe-commands-design.md`
-**Date:** 2026-04-21
-
----
-
-## Task 1: Add `stripHarmlessRedirects` helper and wire it into `isSafeCommand`
-
-**Scenario:** Modifying tested code
-**File:** `extensions/workflow-guard.ts`
-
-1. Run existing tests to confirm baseline:
-   ```bash
-   npx vitest run tests/workflow-guard.test.ts
-   ```
-   Expected: all pass.
-
-2. Add `stripHarmlessRedirects` function above `isSafeCommand`:
-   ```ts
-   /** Strip stderr redirects that are purely cosmetic (no side effects). */
-   function stripHarmlessRedirects(cmd: string): string {
-   	return cmd.replace(/\s*2\s*>\s*(\/dev\/null|&1)\b/g, "");
-   }
-   ```
-
-3. Wire it into `isSafeCommand` — apply `stripHarmlessRedirects` to each part before pattern matching:
-   ```ts
-   export function isSafeCommand(command: string): boolean {
-   	const parts = splitCompoundCommand(command);
-   	return parts.every((part) => {
-   		const cleaned = stripHarmlessRedirects(part);
-   		const isDestructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(cleaned));
-   		const isSafe = SAFE_PATTERNS.some((p) => p.test(cleaned));
-   		return !isDestructive && isSafe;
-   	});
-   }
-   ```
-
-4. Run tests:
-   ```bash
-   npx vitest run tests/workflow-guard.test.ts
-   ```
-   Expected: all existing tests still pass (no behavior change yet since no new SAFE_PATTERNS).
-
-5. Commit:
-   ```bash
-   git add extensions/workflow-guard.ts
-   git commit -m "feat(workflow-guard): add stripHarmlessRedirects helper"
-   ```
-
----
-
-## Task 2: Add new SAFE_PATTERNS entries
-
-**Scenario:** Modifying tested code
-**File:** `extensions/workflow-guard.ts`
-
-1. Add the following entries to the `SAFE_PATTERNS` array (after the existing `gh`-related area or at end):
-
-   ```ts
-   /^\s*cd\b/,
-   /^\s*gh\s+pr\s+(view|list|diff|checks|status)\b/i,
-   /^\s*gh\s+issue\s+(view|list)\b/i,
-   /^\s*gh\s+repo\s+(view|fork|list)\b/i,
-   /^\s*gh\s+release\s+(view|list|download)\b/i,
-   /^\s*gh\s+run\s+(view|list)\b/i,
-   /^\s*git\s+blame\b/,
-   /^\s*git\s+shortlog\b/,
-   /^\s*git\s+stash\s+list\b/i,
-   /^\s*git\s+tag\s+(-l|--list)\b/i,
-   /^\s*git\s+describe\b/,
-   ```
-
-2. Run tests:
-   ```bash
-   npx vitest run tests/workflow-guard.test.ts
-   ```
-   Expected: all existing tests pass.
-
-3. Commit:
-   ```bash
-   git add extensions/workflow-guard.ts
-   git commit -m "feat(workflow-guard): add safe patterns for cd, gh, and git read-only subcommands"
-   ```
-
----
-
-## Task 3: Add tests for `cd`, `gh`, git new subcommands, and redirect stripping
-
-**Scenario:** New feature (test-first)
-**File:** `tests/workflow-guard.test.ts`
-
-**checkpoint: test** — pause after writing failing tests, before implementation.
-
-> Note: Implementation was already done in Tasks 1–2. These tests should all pass immediately. The checkpoint label is kept for review purposes in case the user wants to verify test design.
-
-1. Add the following test blocks inside the `describe("isSafeCommand", ...)` block, after the existing tests:
-
-   ```ts
-   it("allows cd", () => {
-   	expect(isSafeCommand("cd /some/path")).toBe(true);
-   	expect(isSafeCommand("cd src && ls")).toBe(true);
-   });
-
-   it("allows gh read-only subcommands", () => {
-   	expect(isSafeCommand("gh pr view 1564 --json title,body")).toBe(true);
-   	expect(isSafeCommand("gh pr list --repo owner/repo")).toBe(true);
-   	expect(isSafeCommand("gh pr diff 1564")).toBe(true);
-   	expect(isSafeCommand("gh issue view 42")).toBe(true);
-   	expect(isSafeCommand("gh issue list --label bug")).toBe(true);
-   	expect(isSafeCommand("gh repo view owner/repo")).toBe(true);
-   	expect(isSafeCommand("gh run view 12345")).toBe(true);
-   });
-
-   it("blocks gh write subcommands", () => {
-   	expect(isSafeCommand("gh pr create --title 'fix'")).toBe(false);
-   	expect(isSafeCommand("gh pr merge 1564")).toBe(false);
-   	expect(isSafeCommand("gh issue close 42")).toBe(false);
-   	expect(isSafeCommand("gh release create v1.0")).toBe(false);
-   });
-
-   it("allows git read-only subcommands (new additions)", () => {
-   	expect(isSafeCommand("git blame src/index.ts")).toBe(true);
-   	expect(isSafeCommand("git shortlog -sn")).toBe(true);
-   	expect(isSafeCommand("git stash list")).toBe(true);
-   	expect(isSafeCommand("git tag -l")).toBe(true);
-   	expect(isSafeCommand("git tag --list 'v*'")).toBe(true);
-   	expect(isSafeCommand("git describe --tags")).toBe(true);
-   });
-
-   it("still blocks git stash mutations", () => {
-   	expect(isSafeCommand("git stash push -m 'wip'")).toBe(false);
-   	expect(isSafeCommand("git stash pop")).toBe(false);
-   });
-
-   it("allows 2>/dev/null on safe commands", () => {
-   	expect(isSafeCommand("git remote -v 2>/dev/null")).toBe(true);
-   	expect(isSafeCommand("gh pr view 1564 2>/dev/null")).toBe(true);
-   	expect(isSafeCommand("npm list 2>/dev/null")).toBe(true);
-   });
-
-   it("allows 2>&1 on safe commands", () => {
-   	expect(isSafeCommand("git log 2>&1")).toBe(true);
-   });
-
-   it("still blocks stdout redirects even with stderr redirect present", () => {
-   	expect(isSafeCommand("echo 'hello' > file.ts 2>/dev/null")).toBe(false);
-   	expect(isSafeCommand("cat config > backup.txt 2>/dev/null")).toBe(false);
-   });
-
-   it("allows the exact user-reported blocked commands", () => {
-   	expect(isSafeCommand("cd /Users/u/partying/pt-room && git remote -v 2>/dev/null; echo '---'; ls")).toBe(true);
-   	expect(isSafeCommand("gh pr view 1564 --repo olachat/pt-partying --json title,body,files,additions,deletions 2>/dev/null || echo 'gh failed'")).toBe(true);
-   });
-   ```
-
-2. Run tests:
-   ```bash
-   npx vitest run tests/workflow-guard.test.ts
-   ```
-   Expected: all tests pass (including new ones).
-
-3. Commit:
-   ```bash
-   git add tests/workflow-guard.test.ts
-   git commit -m "test(workflow-guard): add tests for cd, gh, git read-only subcommands, and redirect stripping"
-   ```