@tianhai/pi-workflow-kit 0.8.4 → 0.10.0

package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-implementation.md

@@ -0,0 +1,315 @@
+# Implementation Plan: Incorporate mattpocock/skills Ideas
+
+Design doc: `docs/plans/2026-05-01-incorporate-mattpocock-skills-design.md`
+
+## Task 1: Update brainstorming skill — design it twice + ADRs
+
+<!-- tdd: trivial -->
+<!-- checkpoint: none -->
+
+Edit `skills/brainstorming/SKILL.md`:
+
+**Step 3** — change from:
+
+```
+3. **Explore approaches** — propose 2-3 approaches with trade-offs. Lead with your recommendation.
+```
+
+to:
+
+```
+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.
+```
+
+**Step 4** — change from:
+
+```
+4. **Present the design** — break it into sections of 200-300 words. Check after each section whether it looks right. Cover: architecture, components, data flow, error handling, testing.
+```
+
+to:
+
+```
+4. **Present the design** — break it into sections of 200-300 words. Check after each section whether it looks right. Cover: architecture, components, data flow, error handling, testing.
+
+   When a significant architectural decision is identified, offer to write a lightweight ADR to `docs/plans/adr/`. Only write an ADR when all three are true:
+
+   1. **Hard to reverse** — changing your mind later has meaningful cost
+   2. **Surprising without context** — a future reader will wonder "why?"
+   3. **A real trade-off** — there were genuine alternatives
+
+   ADR format — a title and 1-3 sentences covering context, decision, and why:
+
+   ```markdown
+   # <Short title of the decision>
+
+   <1-3 sentences: context, decision, and why.>
+   ```
+
+   ADRs live under `docs/plans/adr/` and are archived during finalizing alongside the design doc.
+```
+
+```bash
+git commit -m "feat(brainstorming): add design-it-twice interface sketches and ADR output"
+```
+
+---
+
+## Task 2: Update writing-plans skill — vertical slices
+
+<!-- tdd: trivial -->
+<!-- checkpoint: none -->
+
+Edit `skills/writing-plans/SKILL.md` — add a new section after "## Task format" and before "## TDD in the plan":
+
+```markdown
+## Vertical slices
+
+Each task should be a **vertical slice** — a thin path through ALL relevant layers end-to-end, delivering one complete piece of observable behavior.
+
+```
+WRONG (horizontal):
+  Task 1: Create database schema for users
+  Task 2: Write user API endpoints
+  Task 3: Build user UI components
+  Task 4: Wire everything together
+
+RIGHT (vertical):
+  Task 1: User can sign up (model + endpoint + validation + test)
+  Task 2: User can log in (auth check + token + test)
+  Task 3: User can view profile (query + endpoint + test)
+```
+
+Vertical slices ensure every committed task leaves the codebase in a testable state and reduces the blast radius of a bad task.
+```
+
+```bash
+git commit -m "feat(writing-plans): add vertical slice guidance with anti-pattern example"
+```
+
+---
+
+## Task 3: Update executing-tasks skill — deep modules refactoring
+
+<!-- tdd: trivial -->
+<!-- checkpoint: none -->
+
+Edit `skills/executing-tasks/SKILL.md` — add a new section after "## TDD discipline":
+
+```markdown
+## Refactoring
+
+After all tests pass for a task, check for refactoring opportunities:
+
+- **Shallow modules** — is the interface nearly as complex as the implementation? Can complexity be hidden behind a simpler interface?
+- **Deletion test** — if you deleted this module, would complexity vanish (pass-through) or reappear across callers (earning its keep)?
+- **Duplication** — extract repeated patterns
+- **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.
+
+Key vocabulary: **depth** (lots of behavior behind a small interface), **seam** (where behavior can be altered without editing in place), **locality** (change concentrated in one place).
+```
+
+```bash
+git commit -m "feat(executing-tasks): add refactoring checklist with deep modules vocabulary"
+```
+
+---
+
+## Task 4: Create diagnose skill
+
+<!-- tdd: trivial -->
+<!-- checkpoint: none -->
+
+Create `skills/diagnose/SKILL.md`:
+
+```markdown
+---
+name: diagnose
+description: "Disciplined debugging loop for hard bugs and performance regressions. Use when a test fails unexpectedly, a bug is found during execution, or something is broken."
+---
+
+# Diagnose
+
+A 6-phase debugging discipline. Phase 1 is the skill — spend disproportionate effort here.
+
+## Phase 1 — Build a feedback loop
+
+Create a fast, deterministic, agent-runnable pass/fail signal for the bug before doing anything else. Try in this order: failing test, curl script, CLI invocation, headless browser script.
+
+The loop must produce the failure mode the **user** described — not a nearby but different failure. Iterate on the loop itself: can you make it faster? Sharper? More deterministic?
+
+If you genuinely cannot build a loop, stop and say so. List what you tried. Ask for access to a reproducing environment or a captured artifact.
+
+Do not proceed until you have a loop you believe in.
+
+## Phase 2 — Reproduce
+
+Run the loop. Confirm:
+- The failure matches the user's reported symptom
+- The failure is reproducible across multiple runs
+- You've captured the exact symptom (error message, wrong output, slow timing)
+
+## Phase 3 — Hypothesise
+
+Generate 3-5 ranked hypotheses. Each must be falsifiable:
+
+> "If `<X>` is the cause, then `<changing Y>` will make the bug disappear / `<changing Z>` will make it worse."
+
+Show the ranked list to the user before testing. They often have domain knowledge that re-ranks instantly.
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific hypothesis. Change one variable at a time. Tag every debug log with a unique prefix (e.g. `[DEBUG-a4f2]`) for easy cleanup later. Prefer a debugger breakpoint over logs when available.
+
+## Phase 5 — Fix + regression test
+
+Write the regression test **before** the fix — but only if there's a correct seam (one that exercises the real bug pattern at the call site). If no correct seam exists, note it — the codebase architecture is preventing the bug from being locked down.
+
+## Phase 6 — Cleanup
+
+Required before declaring done:
+- Original repro no longer triggers
+- Regression test passes (or absence of seam is documented)
+- All `[DEBUG-...]` instrumentation removed
+- Ask: what would have prevented this bug?
+```
+
+```bash
+git commit -m "feat(diagnose): add standalone debugging skill with 6-phase loop"
+```
+
+---
+
+## Task 5: Update finalizing skill — archive ADRs
+
+<!-- tdd: trivial -->
+<!-- checkpoint: none -->
+
+Edit `skills/finalizing/SKILL.md` — update step 1 from:
+
+```
+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"
+   ```
+```
+
+to:
+
+```
+1. **Move planning docs** — archive the design, implementation, progress docs, and ADRs (if any), then commit:
+   ```
+   mkdir -p docs/plans/completed
+   mkdir -p docs/plans/completed/adr
+   mv docs/plans/*-design.md docs/plans/completed/
+   mv docs/plans/*-implementation.md docs/plans/completed/
+   mv docs/plans/*-progress.md docs/plans/completed/
+   mv docs/plans/adr/*.md docs/plans/completed/adr/ 2>/dev/null || true
+   rmdir docs/plans/adr 2>/dev/null || true
+   git add docs/plans/ && git commit -m "chore: archive planning docs"
+   ```
+```
+
+```bash
+git commit -m "feat(finalizing): archive ADRs alongside planning docs"
+```
+
+---
+
+## Task 6: Update documentation
+
+<!-- tdd: trivial -->
+<!-- checkpoint: none -->
+
+### README.md
+
+Update the intro line from:
+
+```
+**4 workflow skills** that guide the agent through a structured development process:
+```
+
+to:
+
+```
+**4 workflow skills** and **1 utility skill** that guide the agent through a structured development process:
+```
+
+Update the pipeline diagram from:
+
+```
+brainstorm → plan → execute → finalize
+```
+
+to:
+
+```
+brainstorm → plan → execute → finalize
+                          ↕
+                      diagnose (on demand)
+```
+
+Add `diagnose` to the skills table:
+
+```
+| `diagnose` | ~35 | 6-phase debugging loop: build feedback loop, reproduce, hypothesise, instrument, fix, cleanup |
+```
+
+Update the Architecture section to include `diagnose/`:
+
+```
+├── skills/
+│   ├── brainstorming/SKILL.md
+│   ├── writing-plans/SKILL.md
+│   ├── executing-tasks/SKILL.md
+│   ├── finalizing/SKILL.md
+│   └── diagnose/SKILL.md
+```
+
+### docs/developer-usage-guide.md
+
+Add to the brainstorm section (after "Outcome"):
+
+```
+- Optionally writes ADRs to `docs/plans/adr/` for significant architectural decisions
+```
+
+Add a new section after the 4 workflow phases:
+
+```markdown
+### 5. Diagnose (on demand)
+
+```
+/skill:diagnose
+```
+
+A 6-phase debugging loop you invoke when something is broken. Build a feedback loop first, then reproduce, hypothesise, instrument, fix, and cleanup. Not a pipeline phase — use whenever needed.
+```
+
+### docs/workflow-phases.md
+
+Add a new section at the end:
+
+```markdown
+## diagnose
+
+```
+/skill:diagnose
+```
+
+Not a pipeline phase. A utility skill invoked on demand when debugging is needed.
+
+- Build a feedback loop (failing test, curl script, etc.)
+- Reproduce, hypothesise, instrument, fix, cleanup
+- No write restrictions (used during execute/finalize, or outside the pipeline)
+```
+
+```bash
+git commit -m "docs: update README, usage guide, and workflow phases for new skills"
+```

package/docs/plans/completed/2026-05-01-incorporate-mattpocock-skills-progress.md

@@ -0,0 +1,15 @@
+# Progress: incorporate-mattpocock-skills
+
+Plan: docs/plans/2026-05-01-incorporate-mattpocock-skills-implementation.md
+Branch: incorporate-mattpocock-skills
+Started: 2026-05-01T00:00:00Z
+Last updated: 2026-05-01T00:00:00Z
+
+| # | Status | Task | Commit |
+|---|--------|------|--------|
+| 1 | ✅ done | Update brainstorming skill — design it twice + ADRs | 0231b84 |
+| 2 | ✅ done | Update writing-plans skill — vertical slices | 22a46df |
+| 3 | ✅ done | Update executing-tasks skill — deep modules refactoring | c405634 |
+| 4 | ✅ done | Create diagnose skill | 5e39e2d |
+| 5 | ✅ done | Update finalizing skill — archive ADRs | e31a1af |
+| 6 | ✅ done | Update documentation (README, usage guide, workflow phases) | 8c1c4eb |

package/docs/workflow-phases.md

@@ -1,6 +1,6 @@
 # Workflow Phases
 
-`pi-workflow-kit` has 4 phases. You invoke each one explicitly with `/skill:`.
+`pi-workflow-kit` has 4 phases and 1 utility skill. You invoke each one explicitly with `/skill:`.
 
 ```
 brainstorm → plan → execute → finalize
@@ -55,3 +55,15 @@ No write restrictions. All tools available.
 - Clean up worktree if one was used
 
 No write restrictions. All tools available.
+
+## diagnose
+
+```
+/skill:diagnose
+```
+
+Not a pipeline phase. A utility skill invoked on demand when debugging is needed.
+
+- Build a feedback loop (failing test, curl script, etc.)
+- Reproduce, hypothesise, instrument, fix, cleanup
+- No write restrictions (used during execute/finalize, or outside the pipeline)

package/package.json

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

package/skills/brainstorming/SKILL.md

@@ -11,8 +11,24 @@ Read-only exploration. You may **not** edit or create any files except under `do
 
 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. Ask questions one at a time to refine the idea. Prefer multiple choice when possible.
-3. **Explore approaches** — propose 2-3 approaches with trade-offs. Lead with your recommendation.
+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 sections of 200-300 words. Check after each section whether it looks right. Cover: architecture, components, data flow, error handling, testing.
+
+   When a significant architectural decision is identified, offer to write a lightweight ADR to `docs/plans/adr/`. Only write an ADR when all three are true:
+
+   1. **Hard to reverse** — changing your mind later has meaningful cost
+   2. **Surprising without context** — a future reader will wonder "why?"
+   3. **A real trade-off** — there were genuine alternatives
+
+   ADR format — a title and 1-3 sentences covering context, decision, and why:
+
+   ```markdown
+   # <Short title of the decision>
+
+   <1-3 sentences: context, decision, and why.>
+   ```
+
+   ADRs live under `docs/plans/adr/` and are archived during finalizing alongside the design doc.
 5. **Write the design doc** — save it to `docs/plans/YYYY-MM-DD-<topic>-design.md`. Ask the user to commit it. Branch creation and worktree setup should be deferred to the execution phase (`/skill:executing-tasks`).
 
 ## Principles

package/skills/diagnose/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: diagnose
+description: "Disciplined debugging loop for hard bugs and performance regressions. Use when a test fails unexpectedly, a bug is found during execution, or something is broken."
+---
+
+# Diagnose
+
+A 6-phase debugging discipline. Phase 1 is the skill — spend disproportionate effort here.
+
+## Phase 1 — Build a feedback loop
+
+Create a fast, deterministic, agent-runnable pass/fail signal for the bug before doing anything else. Try in this order: failing test, curl script, CLI invocation, headless browser script.
+
+Other strategies when the basics don't work:
+- **Bisection** — bug appeared between two known states? Automate "boot at state X, check, repeat" to bisect
+- **Replay** — save a real network request or event log to disk, replay it through the code path in isolation
+
+The loop must produce the failure mode the **user** described — not a nearby but different failure. Iterate on the loop itself: can you make it faster? Sharper? More deterministic?
+
+If you genuinely cannot build a loop, stop and say so. List what you tried. Ask for access to a reproducing environment or a captured artifact.
+
+Do not proceed until you have a loop you believe in.
+
+## Phase 2 — Reproduce
+
+Run the loop. Confirm:
+- The failure matches the user's reported symptom
+- The failure is reproducible across multiple runs
+- You've captured the exact symptom (error message, wrong output, slow timing)
+
+Then **minimize the repro** — strip it down to the smallest input, shortest path, or fewest steps that still triggers the bug. A minimized repro dramatically narrows the hypothesis space.
+
+## Phase 3 — Hypothesise
+
+Generate 3-5 ranked hypotheses. Each must be falsifiable:
+
+> "If `<X>` is the cause, then `<changing Y>` will make the bug disappear / `<changing Z>` will make it worse."
+
+Show the ranked list to the user before testing. They often have domain knowledge that re-ranks instantly.
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific hypothesis. Change one variable at a time. Tag every debug log with a unique prefix (e.g. `[DEBUG-a4f2]`) for easy cleanup later. Prefer a debugger breakpoint over logs when available.
+
+## Phase 5 — Fix + regression test
+
+Write the regression test **before** the fix — but only if there's a correct seam (one that exercises the real bug pattern at the call site). If no correct seam exists, note it — the codebase architecture is preventing the bug from being locked down.
+
+## Phase 6 — Cleanup
+
+Required before declaring done:
+- Original repro no longer triggers
+- Regression test passes (or absence of seam is documented)
+- All `[DEBUG-...]` instrumentation removed
+- Ask: what would have prevented this bug?
+- If the bug was caused by an architectural problem (no good test seam, tangled callers, hidden coupling), suggest writing an ADR to `docs/plans/adr/` capturing that insight

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,76 @@ 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.
+
+## Refactoring
+
+After all tests pass for a task, check for refactoring opportunities:
+
+- **Shallow modules** — is the interface nearly as complex as the implementation? Can complexity be hidden behind a simpler interface?
+- **Deletion test** — if you deleted this module, would complexity vanish (pass-through) or reappear across callers (earning its keep)?
+- **Duplication** — extract repeated patterns
+- **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.
+
+Key vocabulary: **depth** (lots of behavior behind a small interface), **seam** (where behavior can be altered without editing in place), **locality** (change concentrated in one place).
+
+## 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 +226,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`
+```