@tianhai/pi-workflow-kit 0.17.1 → 1.0.0

package/skills/brainstorming/SKILL.md

@@ -1,48 +0,0 @@
----
-name: brainstorming
-description: "Use this before any creative work — creating features, building components, adding functionality, or modifying behavior. Explores intent and design before implementation. Use this skill whenever the user describes something they want to build, change, or improve, even if they don't say 'brainstorm' — phrases like 'I want to add X', 'let's build Y', 'we need a way to Z', or 'help me design' all apply."
----
-
-# Brainstorming
-
-Read-only exploration. You may **not** edit or create any files except under `docs/plans/`.
-
-## Process
-
-1. **Check git state** — run `git status` and `git log --oneline -5`. If there's uncommitted work, ask the user what to do with it first.
-2. **Understand the idea** — read existing code, docs, and recent commits. Grep for related functionality, check package.json/dependencies and module structure. **Check `docs/lessons.md`** if it exists — known constraints and patterns may affect the design. Read only what's necessary to ground the design — don't read the entire codebase. Ask questions to refine the idea. Prefer multiple choice when possible. After each question, check: can you clearly articulate (a) what the user wants to build, (b) why, and (c) key constraints? If yes, present your understanding as a short summary and ask: "Should I proceed with this, or is there more to add?" The human decides when to move on.
-3. **Explore approaches** — propose 2-3 approaches. For each approach, sketch the concrete interface (types, method signatures, example caller code) so the comparison is grounded in actual code, not abstract descriptions. Lead with your recommendation.
-4. **Present the design** — break it into focused sections. Each section should be one screen of reading. Present each section to the human and wait for approval before continuing. Cover: architecture, components, data flow, error handling, testing. On feedback, incorporate it and re-present the revised section.
-
-   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.
-
-   For non-trivial designs, note any areas that may need production-risk review (database schema changes, authentication or authorization, external API integrations, concurrency or batch processing, file uploads or large data flows, Redis/caching/message queues). You don't need to audit them here — just flag them for the design-review stage.
-
-   For trivial changes (config, naming, simple field additions), note "Simple change — no design review needed" in the design doc.
-5. **Write the design doc** — save it to `docs/plans/YYYY-MM-DD-<topic>-design.md`. Organize features as end-to-end slices (each slice delivers one observable behavior through all relevant layers) so the planning phase can decompose them directly into tasks. Branch creation, committing, and workspace setup are handled by `/skill:executing-tasks`.
-
-## Principles
-
-- One question at a time
-- YAGNI — remove unnecessary features
-- Design for testability
-- Always explore alternatives before settling
-
-## After the design
-
-- **Non-trivial design**: Ask: "Design looks good. Run `/skill:design-review` to check for production risks before planning."
-- **Trivial change**: Ask: "Simple change — skip design review. Ready to plan? Run `/skill:writing-plans`"

package/skills/design-review/SKILL.md

@@ -1,113 +0,0 @@
----
-name: design-review
-description: "Audit a design doc for production risks — security, scalability, fault tolerance, and operational hazards. Use after brainstorming for non-trivial designs, or when you want to stress-test a design for production readiness."
----
-
-# Design Review
-
-Read-only exploration of the design doc. You **may** edit the design doc to append review findings. You may **not** edit source code or configuration.
-
-## Process
-
-1. **Find the design doc** — look for `docs/plans/*-design.md`. If none exists, say "No design doc found. Run `/skill:brainstorming` first." and stop.
-
-2. **Check triviality** — if the design doc notes "Simple change — no design review needed", append a brief section:
-
-   ```markdown
-   ## Architectural Review
-
-   **Status**: Skipped — trivial change. No high-risk operations detected.
-   ```
-
-   Then say: "Ready to plan? Run `/skill:writing-plans`" and stop.
-
-3. **Read the design doc in full** — understand the architecture, data flow, components, and error handling proposed.
-
-4. **🏛️ Architectural Pillars Review** — evaluate the design against the 6 Pillars of Production-Grade Design:
-
-   1. **Robustness & Fault Tolerance**: How expected failures are handled, subsystem isolation, graceful degradation.
-   2. **Atomicity & Consistency**: Database transactions, state rollback on error, endpoint idempotency.
-   3. **Security & Access Control**: Input validation/sanitization, authorization checks at the boundary.
-   4. **Scalability & Performance**: Connection pooling, closing resource leaks, preventing N+1 queries.
-   5. **Backwards Compatibility**: Schema migration safety, zero-downtime deployment, API versioning.
-   6. **Testability**: Injection seams for external dependencies (APIs, system clocks, randomizers) to keep tests 100% deterministic.
-
-   For each pillar, write a 1-2 sentence assessment. Flag any concerns.
-
-5. **⚠️ High-Risk Hazard Audit** — evaluate the design against the 8 High-Risk Production Hazards. For each hazard, write either `[SAFE]` (with a 1-sentence justification) or `[TRIGGERED]` (detailing the mitigation):
-
-   1. **Unbounded Redis Deletions / Operations**: Multi-key deletion or scans (e.g. `KEYS` or raw `SCAN` loops) that block single-threaded performance.
-   2. **In-Memory OOM Loops**: Fetching complete database datasets into server memory (e.g., raw `select *`) to filter, sort, or map in runtime heap.
-   3. **Unbounded Concurrency Spikes**: Running concurrent network requests (e.g. unthrottled `Promise.all`) without strict batch limits.
-   4. **Missing High-Frequency Indexes**: Running queries on unindexed columns, forcing expensive table-scans under load.
-   5. **Nested/Long-Running Transactions**: Holding database connections and locks open while awaiting slow external HTTP, disk, or cryptographic tasks.
-   6. **Unrestricted Uploads & Temp Flooding**: Writing uploaded data directly to local temporary paths without validation limits or explicit `finally` cleanup blocks.
-   7. **Raw Query String Interpolation**: Merging raw variables into SQL queries or shell command inputs (susceptible to injection).
-   8. **Silent Swallowing Loops**: Background workers or cron tasks silently catching and suppressing exceptions without logging, back-offs, or alerts.
-
-6. **🔍 Socratic Risk Discovery** — put on your **SRE Hat** and audit the proposed logic against 3 heuristics to identify novel or domain-specific risks:
-
-   - **The "Scale to 100x" Heuristic**: If this operation is run 100x/sec or on 100k items, what breaks? (Memory, CPU, Disk I/O, sockets, database connection limits).
-   - **The "Hostile World" Heuristic**: If a malicious actor has complete control over these inputs (headers, payloads, IDs), how can they exploit, crash, or extract data?
-   - **The "Silent Error" Heuristic**: If this downstream dependency or query hangs or fails silently, how does our server react? Is there a timeout, a back-off, or logging?
-
-   For each heuristic, note any risks discovered. If a risk overlaps with a triggered hazard, cross-reference it.
-
-7. **Present findings** — show the full review to the user. For each triggered hazard or Socratic risk, propose a concrete mitigation. Wait for user feedback and incorporate changes.
-
-8. **Append to design doc** — add a `## Architectural Review` section to the design doc. Two cases:
-
-   **All clear** (no hazards triggered, no Socratic risks):
-   ```markdown
-   ## Architectural Review
-
-   **Status**: ✅ No high-risk hazards detected.
-
-   **Pillars reviewed**: All 6 — no concerns.
-   **Hazards audited**: All 8 [SAFE].
-   **Socratic risks**: None identified.
-   ```
-
-   **Hazards or risks found**:
-   ```markdown
-   ## Architectural Review
-
-   **Status**: ⚠️ High-risk operations detected — see mitigations below.
-
-   ### Pillar Assessments
-   - **Robustness**: [assessment]
-   - **Atomicity**: [assessment]
-   - **Security**: [assessment]
-   - **Scalability**: [assessment]
-   - **Backwards Compatibility**: [assessment]
-   - **Testability**: [assessment]
-
-   ### Hazard Audit
-   - 1. Unbounded Redis: [SAFE / TRIGGERED — mitigation]
-   - 2. In-Memory OOM: [SAFE / TRIGGERED — mitigation]
-   - 3. Unbounded Concurrency: [SAFE / TRIGGERED — mitigation]
-   - 4. Missing Indexes: [SAFE / TRIGGERED — mitigation]
-   - 5. Long-Running Transactions: [SAFE / TRIGGERED — mitigation]
-   - 6. Unrestricted Uploads: [SAFE / TRIGGERED — mitigation]
-   - 7. Query Interpolation: [SAFE / TRIGGERED — mitigation]
-   - 8. Silent Swallowing: [SAFE / TRIGGERED — mitigation]
-
-   ### ⚠️ High-Risk Operations & Mitigations
-   [Detailed mitigation for each TRIGGERED hazard and Socratic risk]
-
-   ### Socratic Risks
-   - **Scale to 100x**: [finding or "none identified"]
-   - **Hostile World**: [finding or "none identified"]
-   - **Silent Error**: [finding or "none identified"]
-   ```
-
-## Principles
-
-- Be specific — every `[TRIGGERED]` hazard must include a concrete mitigation, not just "be careful"
-- Be honest — if the design is risky and the risk can't be mitigated easily, say so
-- Be proportional — a simple CRUD endpoint doesn't need the same depth as a batch processing pipeline
-- Don't redesign — flag risks and propose mitigations, but the design owner decides
-
-## After the review
-
-Ask: "Ready to plan? Run `/skill:writing-plans`"

package/skills/executing-tasks/SKILL.md

@@ -1,350 +0,0 @@
----
-name: executing-tasks
-description: "Use this to implement an approved plan task-by-task. Run after writing-plans, before finalizing."
----
-
-# Executing Tasks
-
-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. **Find the plan** — look for `docs/plans/*-implementation.md`. If none exist, say "No implementation plan found. Run `/skill:writing-plans` first." and stop. 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. **Suggest workspace isolation** — if the user isn't already on a feature branch or worktree, present the options:
-
-   - **Branch** (smaller changes):
-     ```
-     git checkout -b <feature-name>
-     ```
-   - **Worktree** (larger features, keeps main clean):
-     ```
-     git worktree add ../<repo>-<feature-name> -b <feature-name>
-     ```
-
-   Derive `<feature-name>` from the plan doc (e.g. `docs/plans/2026-04-16-auth-design.md` → `auth`). Ask the user which they prefer, then wait for confirmation before proceeding.
-
-3. **If worktree was chosen — hand off to new session:**
-
-   a. Ensure the worktree's `docs/plans/` directory exists:
-      ```
-      mkdir -p <worktree>/docs/plans
-      mkdir -p <worktree>/docs/plans/adr
-      ```
-
-   b. Move plan docs into the worktree:
-      ```
-      mv docs/plans/*-design.md <worktree>/docs/plans/ 2>/dev/null || true
-      mv docs/plans/*-implementation.md <worktree>/docs/plans/ 2>/dev/null || true
-      mv docs/plans/*-progress.md <worktree>/docs/plans/ 2>/dev/null || true
-      mv docs/plans/adr/*.md <worktree>/docs/plans/adr/ 2>/dev/null || true
-      ```
-
-   c. Commit the removal on the current branch (if any plan docs were committed):
-      ```
-      git rm docs/plans/*-design.md docs/plans/*-implementation.md docs/plans/*-progress.md 2>/dev/null || true
-      git rm -r docs/plans/adr/ 2>/dev/null || true
-      git commit -m "chore: move plan docs to worktree for <feature-name>"
-      ```
-
-   d. Stop and show the user:
-      ```
-      ✅ Worktree created at ../<repo>-<feature-name>
-      📄 Plan docs moved to the worktree.
-
-      To continue, start a new session there:
-        cd ../<repo>-<feature-name> && pi
-
-      Then run: /skill:executing-tasks
-      ```
-
-   e. **Create the progress file** in the worktree — save to `<worktree>/docs/plans/<plan-name>-progress.md`:
-
-      ```markdown
-      # Progress: <topic>
-
-      Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
-      Branch: <feature-name>
-      Started: <ISO timestamp>
-      Last updated: <ISO timestamp>
-
-      | # | Status | Task | Commit |
-      |---|--------|------|--------|
-      | 1 | ⬜ pending | Task description (preserve checkpoint labels) | — |
-      ```
-
-      This ensures the new session in the worktree will detect the progress file and resume correctly.
-
-   f. **Do not proceed with task execution.** The session ends here.
-
-4. **If branch was chosen — continue with execution:**
-
-   a. **Create the progress file** — save to `docs/plans/<plan-name>-progress.md` (replace `-implementation` with `-progress` in the plan filename):
-
-      ```markdown
-      # Progress: <topic>
-
-      Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
-      Branch: <actual branch name>
-      Started: <ISO timestamp>
-      Last updated: <ISO timestamp>
-
-      | # | Status | Task | Commit |
-      |---|--------|------|--------|
-      | 1 | ⬜ pending | Task description (preserve checkpoint labels) | — |
-      ```
-
-      Use the actual branch name — whether it's the original branch or a new one from the isolation step.
-
-   b. **Commit the plan docs** — if `docs/plans/` has uncommitted files, commit them on the new branch:
-      ```
-      git add docs/plans/ && git commit -m "docs: add design and implementation plan"
-      ```
-
-   c. **Begin task execution** — start with task 1 (see [Per-task execution](#per-task-execution)).
-
-## Resume
-
-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 executing plan steps |
-| `⏸ test-review` | Paused at checkpoint: test, waiting for human approval |
-| `⏸ done-review` | Paused at checkpoint: done, waiting for human approval |
-| `✅ 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 `⏸ test-review` or `⏸ done-review` when the agent reaches a `⏸ CHECKPOINT` gate in the plan — this must happen BEFORE any `git add` or `git commit`
-- Can only return to `🔄 in-progress` after the human explicitly says "approve"
-- Mark `✅ done` + record commit hash only after successful `git commit`
-- Cannot go from `🔄 in-progress` → `✅ done` if the task has a checkpoint — must go through the review status first
-- `git add` and `git commit` happen AFTER human approval, never before
-- 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:
-
-1. **Mark in-progress** — update the progress file: `🔄 in-progress`
-2. **Read the plan** — read the plan's overview section (everything before `## Task 1:`). Skim all `## Task N:` headings for dependency awareness. Then read the current task's body in full. **Read `docs/lessons.md` if it exists** — follow all rules listed there while working on this task.
-3. **Execute the plan steps** — follow each numbered step in the task body, in order. As you work, shift your cognitive focus through three frames:
-
-   **QA Test frame** (when writing/running tests): Focus entirely on translating the task's `Given/When/Then` Acceptance Criteria into precise failing tests. Before running tests, verify the test environment is sandboxed — no real database connections, API calls, or live services. External dependencies must be mocked or stubbed. Ensure the test environment is isolated (e.g., `NODE_ENV=test`, `GO_ENV=test`, or equivalent for your stack).
-
-   **Pragmatic Developer frame** (when implementing): Focus on the simplest possible code to make the tests green. Do not over-engineer or add code for future requirements. Keep complexity to a bare minimum.
-
-   **Senior Refactoring frame** (when refactoring): Evaluate the craftsmanship of the code. Check for:
-   - **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.
-
-   Stop at any `⏸ CHECKPOINT` gate (see [Checkpoint gates](#checkpoint-gates--when-the-plan-says-stop)).
-4. **Verify against task description** — re-read the task from the plan. Does the implementation satisfy every requirement listed? If not, fix before proceeding.
-5. **Learn from mistakes** — if you caught yourself making a mistake during this task that you've made before or that would apply to future tasks, append a rule to `docs/lessons.md`. Only add rules that would change future behavior. If the file doesn't exist, create it with the standard format (see below).
-
-   Before writing, apply the **generalization test**: would this rule apply equally to a completely different feature or domain in this repo? If not, rewrite it — strip out specific service names, entity types, and domain concepts, and express the underlying pattern instead. If you can't express a generic form, don't write the rule.
-
-   ❌ **Domain-specific** (only survives this sprint):
-   > "Always validate `userId` before calling `UserProfile.Get`"
-
-   ✅ **Generic** (applies across the whole repo):
-   > "Always validate required ID fields at the service boundary — missing IDs should return 400, not 500"
-6. **Commit** — after all steps are done (no checkpoint gates remain in the task), `git add` the relevant files and commit with a clear message.
-7. **Update progress** — mark `✅ done` + record the commit hash.
-8. **Suggest session break if needed** — after completing ~3-5 tasks since the last break, suggest:
-   ```
-   ✅ Tasks N-M done (commits: abc, def)
-   Progress: X/Y tasks done
-   ⏭  Next: Task [N+1] — [description]
-   💡 Context is building up. For clean context on remaining tasks:
-      /new  then  /skill:executing-tasks
-      (or just say "continue" to keep going here)
-   ```
-   Also suggest at checkpoint review pauses when multiple tasks have been completed since the last break. Respect the user's choice if they say "continue".
-9. **Loop** — go back to step 1 for the next `⬜ pending` task, or see [After all tasks](#after-all-tasks) if none remain.
-
-### `docs/lessons.md` format
-
-```markdown
-# Lessons Learned
-
-<!--
-Agent: read this at the start of each task during executing-tasks.
-Follow every rule. Add new rules when you catch yourself making repeat mistakes.
-Rules must be generic patterns applicable to any domain or feature — not specific to one service, entity, or use case.
-Retire rules that no longer apply during finalizing.
--->
-
-## Rules
-
-- <new rule here>
-```
-
-When adding a new rule during execution, always append it under `## Rules`. The categorization into specific headers (e.g., `## Tool Usage`, `## Testing Patterns`) is done during finalizing — never during execution.
-
-### Checkpoint gates — when the plan says STOP
-
-The plan marks certain steps with `⏸ **CHECKPOINT: test**` or `⏸ **CHECKPOINT: done**`. These are hard stop points. When you reach one:
-
-1. **Stop executing immediately.** Do not proceed to the next step in the task. Do not pass go.
-2. **Do NOT run `git add` or `git commit`.** The code stays uncommitted until the human approves.
-3. Update the progress file to `⏸ test-review` or `⏸ done-review`.
-4. Present the checkpoint review (see below).
-5. **Wait for the human to respond.** Do not continue executing steps, do not commit, do not move to the next task.
-6. On approval, update progress back to `🔄 in-progress` and continue with the next step in the task.
-
-The whole point of checkpoints is that the human reviews code at critical moments before the agent proceeds further. If you skip past a checkpoint without waiting, you defeat this purpose.
-
-| Checkpoint type | What the agent has done at this point | What needs human approval |
-|---|---|---|
-| `checkpoint: test` | Written failing tests, confirmed they fail | The test design — are the right things being tested? |
-| `checkpoint: done` | Implemented, refactored, written lessons | The implementation approach, the refactoring choices |
-
-**For `checkpoint: test`:** Only the test file should exist at this point. No implementation code yet. The human reviews the test to confirm the right behavior is being specified.
-
-**For `checkpoint: done`:** All code changes are made but NOT committed. Run `git diff` (not `git diff --cached` — nothing should be staged) to show the human what changed. The human reviews before anything is committed.
-
-## Checkpoint review
-
-When you hit a checkpoint gate, present a review to the human and **stop all execution** until they respond.
-
-### At `checkpoint: test`
-
-You have written the failing tests and confirmed they fail. No implementation code exists yet.
-
-Present:
-```
-⏸ Paused at checkpoint: test for task [N]
-
-**Test file:** `path/to/test.ts`
-
-**Test code:**
-[show the full test code]
-
-**Test results:** [paste the failing test output showing which tests fail and why]
-
-**What this validates:** [summarize the behavior these tests specify]
-**Next step after approval:** Write the implementation to make these tests pass
-
-What would you like to do?
-- **approve** — I'll implement to make these tests pass
-- **request changes** — tell me what to change in the tests
-- **revert** — undo this task and go back to pending
-- **skip** — skip this task entirely
-- **stop** — pause here, resume later with /skill:executing-tasks
-- **status** — show the full progress table
-```
-
-### At `checkpoint: done`
-
-You have implemented the code, run the refactor step, and written any lessons. Nothing is committed yet.
-
-Present:
-```
-⏸ Paused at checkpoint: done for task [N]
-
-**What was done:** [brief summary — what feature/fix was implemented]
-
-**Test results:** [run tests now, paste the passing output]
-
-**Diff:** [run `git diff` — the unstaged changes are what this task produced]
-[paste the full diff]
-
-**Refactoring done:** [what changed during refactor, or "none needed — [reason]"]
-**Lessons learned:** [new rule added to docs/lessons.md, or "none"]
-**Next step after approval:** git add, commit, and move to next task
-
-What would you like to do?
-- **approve** — I'll commit and move to the next task
-- **request changes** — tell me what to change, I'll update and re-present
-- **revert** — undo this task and go back to pending
-- **skip** — skip this task entirely
-- **stop** — pause here, resume later with /skill:executing-tasks
-- **status** — show the full progress table
-```
-
-**Do not commit before the human approves.** The diff you show at `checkpoint: done` is the uncommitted work. If the human requests changes, make the edits, re-run tests, and re-present the updated diff at the same checkpoint. Repeat until they say "approve".
-
-Only after approval: `git add` the relevant files, commit, and mark the task `✅ done`.
-
-## Progress file updates
-
-Update the progress file by reading it, modifying the relevant row's status and commit hash, and writing it back. Target the specific task row — do not use pattern-matching approaches (e.g. sed) that could corrupt the table.
-
-Update `Last updated` timestamp on every change.
-
-## 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 (outside of a checkpoint pause):
-
-1. **Verify the criticism** — read the relevant code. Is the feedback accurate?
-2. **Evaluate the suggestion** — is the proposed fix the right approach? Consider alternatives.
-3. **Implement or push back** — if valid, fix it, re-run tests, and amend the commit. If not, explain why with evidence from the codebase.
-4. **Don't blindly implement** — every suggestion should be verified against the code before accepting.
-
-## If you're stuck
-
-1. Re-read the current task section from the plan — you may have drifted from the spec
-2. Check git log — recent commits may reveal context
-3. Ask the user — it's better to clarify than to guess wrong
-4. If still stuck after asking, mark the task `❌ failed` with the reason in the progress file and move to the next task
-5. **Check `docs/lessons.md`** — a previous lesson may be relevant to your current problem.
-
-## After all tasks
-
-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

@@ -1,119 +0,0 @@
----
-name: finalizing
-description: "Use this after all tasks are complete to clean up, document, and ship the work."
----
-
-# Finalizing
-
-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, 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/ 2>/dev/null || true
-   mv docs/plans/*-implementation.md docs/plans/completed/ 2>/dev/null || true
-   mv docs/plans/*-progress.md docs/plans/completed/ 2>/dev/null || true
-   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"
-   ```
-
-   Each `mv` gracefully handles the case where no matching files exist (e.g., if the user skipped straight from brainstorm to finalize without executing tasks).
-
-2. **Review & Polish Lessons (Agile Scrum Master Hat)** — if `docs/lessons.md` exists, put on your **Agile Scrum Master Hat** to curate and optimize it for future sprints:
-   - **Add missed lessons** — capture any lessons from this session that weren't written during execution
-   - **Generalize domain-specific rules** — if a rule names a specific service, entity, or feature, either rewrite it as a generic pattern or remove it if no generic form exists
-   - **De-duplicate** — combine overlapping or redundant rules into single, sharper entries
-   - **Categorize** — group the rules under clear, structured markdown headers (e.g., `## Tool Usage`, `## Testing Patterns`, `## Architecture Rules`) to make the document highly scannable for future sessions. Keep the `## Rules` section as the append target for new entries during execution — categorization moves rules out of `## Rules` into the appropriate category headers.
-   - **Retire stale rules** — remove bullets that no longer apply
-   - If no changes are needed, leave it as-is
-
-   If `docs/lessons.md` doesn't exist but lessons were learned this session, create it with the standard format:
-
-   ```markdown
-   # Lessons Learned
-
-   <!--
-   Agent: read this at the start of each task during executing-tasks.
-   Follow every rule. Add new rules when you catch yourself making repeat mistakes.
-   Rules must be generic patterns applicable to any domain or feature — not specific to one service, entity, or use case.
-   Retire rules that no longer apply during finalizing.
-   -->
-
-   ## Rules
-
-   - <rule 1>
-   - <rule 2>
-   ```
-
-3. **Update documentation** — if the API or surface changed:
-   - Update README.md
-   - Update CHANGELOG.md
-   - Update any inline docs
-
-4. **Choose a merge strategy** — ask the human which option they prefer:
-
-   1. **Create PR** — push and open a PR for external review:
-      ```
-      git push origin <branch>
-      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/[\^~].*//')
-      git checkout "$parent" && git pull
-      git checkout - && git rebase "$parent"
-      git checkout "$parent" && git merge --ff-only -
-      git push origin "$parent"
-      git branch -d - && git push origin --delete -
-      ```
-
-   3. **Squash & merge** — squash all commits into one on parent, 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/[\^~].*//')
-      git checkout "$parent" && git pull
-      git merge --squash -
-      git commit -m "feat: <summary>"
-      git push origin "$parent"
-      git branch -d - && git push origin --delete -
-      ```
-
-   4. **Merge commit** — merge with `--no-ff`, 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/[\^~].*//')
-      git checkout "$parent" && git pull
-      git checkout - && git merge --no-ff -m "Merge branch '<branch>'" -
-      git push origin "$parent"
-      git branch -d - && git push origin --delete -
-      ```
-
-   For options 2–4, confirm the detected parent branch with the human before proceeding.
-
-5. **Clean up** — if a worktree was used, remove it:
-   ```
-   git worktree remove ../<repo>-<feature-name>
-   ```