@tianhai/pi-workflow-kit 0.18.1 → 1.1.0

package/skills/pwk-brainstorming/SKILL.md

@@ -5,55 +5,58 @@ description: "Use this before any creative work — creating features, building
 
 # Brainstorming
 
-Read-only exploration. You may **not** edit or create any files except under `docs/plans/`.
+Read-only exploration of source code; every file you create or edit goes under `docs/plans/`. (Once an ADR is approved by the human, `docs/adr/` becomes writable too — ask the user to unlock or run the write.) Planning produces the document the executor builds from; source-writing happens in later phases.
 
-## Process
+## Proportionality: trivial vs non-trivial
 
-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.
+Classify the change at the start.
 
-   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:
+- **Trivial** — typo or obvious bugfix with no open design questions, config/version bump, single-function change, or anything the human flags as trivial. Skip steps 3–5; write a **minimal** design doc in one turn (one-line context, a `## Requirements` list with the single requirement, optional `## Production-risk areas` line), and hand off to `/skill:pwk-writing-plans`. The guard still enforces read-only — trivial compresses the phase to one turn, it doesn't skip it.
+- **Non-trivial** — open design questions, multiple approaches, cross-module impact, or new behavior. Run the full process below.
 
-   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
+When unsure, ask: "This looks trivial — fast-path it, or full brainstorm?" Default to full.
 
-   ADR format — a title and 1-3 sentences covering context, decision, and why:
+## Granularity
 
-   ```markdown
-   # <Short title of the decision>
+**One design doc = one PR; one requirement = one testable slice within it.**
 
-   <1-3 sentences: context, decision, and why.>
-   ```
+- Split into **multiple design docs** only when each part could ship as its own PR (independently reviewable and mergeable). Each runs its own plan → execute → finalize pipeline.
+- Within a doc, decompose into **requirements**, each one testable behavior. Decision rule: could this part be reviewed and merged on its own? Yes → separate design doc. No → one doc, multiple requirements. Most work is a single doc; splitting is opt-in.
+
+## Process
+
+1. **Check git state** — `git status` + `git log --oneline -5`. Uncommitted work? Ask the user what to do first.
+2. **Discovery** *(skip in a brand-new repo with no `docs/plans/`)* — glob `docs/plans/*-design.md`; report in-flight topics. If the new idea continues an existing topic, ask whether to extend it or start fresh.
+3. **Understand the idea** — read only enough code/docs/commits to ground the design. **Check `docs/lessons.md`** — known constraints may shape it. Ask questions one at a time, prefer multiple choice. Once you can articulate what/why/constraints, present a short summary and ask: "Should I proceed, or is there more?" The human decides when to move on.
+4. **Explore approaches** — propose 2–3, leading with your recommendation. Sketch the concrete interface (types, signatures, example caller) for each so the comparison is grounded in code, not abstractions.
+5. **Present the design** in one pass, organized into sections (architecture, components, data flow, error handling, testing) — the human comments on any section; re-present only revised sections.
+
+   Identified a significant architectural decision? Offer an ADR in `docs/adr/`. Only when all three hold: **hard to reverse**, **surprising without context**, **a real trade-off**. Format: title + 1–3 sentences of context/decision/why. ADRs are permanent institutional memory — they stay out of archive/rotation forever. (Guard note: `docs/adr/` is outside the writable `docs/plans/`; write it only after the user approves and unlocks.)
+6. **Write the design doc** — `docs/plans/YYYY-MM-DD-<topic>-design.md`, descriptive (not a task list). **Open with `## Requirements`** — one testable behavior each; `pwk-writing-plans` derives acceptance criteria and tests from these. Then: problem, approaches considered, architecture, components, data flow, error handling, testing.
 
-   ADRs live under `docs/plans/adr/` and are archived during finalizing alongside the design doc.
+   Touches a production-risk area (DB schema/migrations, auth, external APIs, concurrency/batch, uploads/large data flows, Redis/caching/queues)? Add a brief `## Production-risk areas` — `pwk-writing-plans` carries it into the plan and `pwk-code-review` audits it per requirement.
 
-5. **Write the design doc** — save it to `docs/plans/YYYY-MM-DD-<topic>-design.md`. Include a `## Features` table listing each feature as a testable, observable behavior. Simple features get one row. Complex features get many.
+   **End with `## Feature acceptance`** — one or more end-to-end `Given/When/Then` scenarios proving the requirements *compose* into the feature. This is the feature's definition-of-done; the human approves it as what "the feature works" means. `pwk-writing-plans` derives a feature-level test from it; `pwk-executing-tasks` runs it at the integration gate. Treat "I can write this scenario" as the green light to finish designing — if you can't, keep designing because the requirements don't yet compose into a coherent feature.
 
-   Table format:
    ```markdown
-   ## Features
+   ## Feature acceptance
 
-   | # | Feature | Status | Observable Behavior |
-   |---|---------|--------|---------------------|
-   | 1 | Feature name | ⬜ pending | What the user can do when this is complete |
+   - Given <starting state>, When <trigger>, Then <end-to-end outcome the feature promises>.
    ```
 
-   Status values: `⬜ pending`, `🔄 planned`, `✅ done`, `⏭ skipped`.
+   Example (rate limiting): "Given a new API consumer with no prior usage, When they exceed 100 requests/minute for 3 consecutive minutes, Then they're throttled, a `rate_limited` event is emitted, and further requests return 429."
 
-   For trivial changes where the entire feature is a single row, note "Simple change — no design review needed" below the table. For non-trivial designs, note 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).
+   **Splitting large issues:** propose multiple design docs (one `<topic>` per sub-issue) and get human approval first — see [Granularity](#granularity). Each runs its own pipeline.
 
-   Branch creation, committing, and workspace setup are handled by `/skill:pwk-executing-tasks`.
+The session stays read-only and uncommitted through brainstorm and plan: branch creation happens at the end of `/skill:pwk-writing-plans`; plan docs are committed at the start of `pwk-executing-tasks`.
 
 ## Principles
 
 - One question at a time
 - YAGNI — remove unnecessary features
 - Design for testability
-- Always explore alternatives before settling
+- Explore alternatives before settling
 
 ## After the design
 
-Ask: "Ready to plan? Run `/skill:pwk-writing-plans`"
+Ask: "Ready to plan? Run `/skill:pwk-writing-plans`"

package/skills/pwk-code-review/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: pwk-code-review
+description: "Review a completed requirement's code — trace the logic, check spec alignment against the acceptance criteria, fix code smells, and run a production hazard check. Runs after each requirement in pwk-executing-tasks. Unlocked: may edit code to apply smell fixes."
+---
+
+# Code Review
+
+Review the code just implemented for a requirement. **Unlocked** — you may edit code to apply smell fixes; flag everything else as a follow-up.
+
+## Process
+
+1. **Identify the scope** — the requirement just completed (from the progress file / most recent commit). Read its acceptance criteria and integration tests from the plan doc. Run `git log --oneline -5` and `git diff` to see exactly what changed for this requirement.
+
+2. **🔍 Code tracing** — trace the new/changed code paths end-to-end against the integration tests. For each path: does data flow correctly from entry to the asserted outcome? Note any branch the tests don't exercise, any dead branch, any path where the trace breaks.
+
+3. **📐 Spec alignment** — for each acceptance criterion, point to the code and the test that satisfy it. A criterion with no covering code or no test is a **gap**. Code that does more than the criteria specify is **scope creep** — flag it.
+
+4. **🧹 Code smells — fix these directly:**
+   - Shallow modules (interface nearly as complex as the implementation)
+   - Duplication
+   - Missing seams / premature abstraction
+   - Poor naming, magic values, dead code
+   Apply the fix, re-run the integration tests (must stay green), and commit. If a smell needs a refactor large enough to risk the requirement, **flag** it instead of applying.
+
+5. **⚠️ Production hazard check** — audit the changed code against the high-risk hazards. For each, write `[SAFE]` (1-line justification) or `[TRIGGERED]` (concrete mitigation):
+   1. **Unbounded operations** — multi-key deletions/scans (`KEYS`, raw `SCAN` loops), or full-table loads filtered in memory.
+   2. **Missing indexes** — hot queries on unindexed columns (table scans under load).
+   3. **Unbounded concurrency** — unthrottled fan-out (`Promise.all` without batch limits).
+   4. **Long-running transactions** — holding DB connections/locks across slow external calls.
+   5. **Query/command interpolation** — raw variables merged into SQL or shell (injection).
+   6. **Unrestricted uploads / temp flooding** — uploads to local temp without limits or `finally` cleanup.
+   7. **Silent swallowing loops** — background workers catching and suppressing exceptions without logging/back-off.
+   Also check the design's `## Production-risk areas`, if any.
+
+6. **Report** — summarize: tracing findings, spec gaps, smells fixed (with commits), hazards `[TRIGGERED]`. Non-trivial findings become follow-up items — the user decides whether to address now or defer.
+7. **Mark done** — update the requirement's progress-file row from `🔎 review` to `✅ done`. Done means reviewed, not just committed.
+
+## Principles
+
+- **Tracing and spec alignment are the core** — they catch what tests miss: untested branches, missing criteria, scope creep.
+- **Fix smells in place; flag everything else.** Keep the review scoped — the goal is polish on the requirement that just landed, not a redesign pass.
+- **Be proportional** — a one-function change doesn't need the depth of a batch pipeline. When this skill runs as the inline path because the plan tagged the requirement `Review: inline`, that was a deliberate call at plan time — keep the review focused and don't second-guess the tag.
+
+## After the review
+
+Return to `/skill:pwk-executing-tasks` for the next requirement, or `/skill:pwk-finalizing` if all requirements are done.

package/skills/pwk-diagnose/SKILL.md

@@ -7,6 +7,8 @@ description: "Disciplined debugging loop for hard bugs and performance regressio
 
 A 6-phase debugging discipline. Phase 1 is the skill — spend disproportionate effort here.
 
+Invoking `/skill:pwk-diagnose` **exits the gated brainstorm/plan phase** (the workflow guard unlocks) — diagnosis needs to write failing tests and `[DEBUG-…]` instrumentation. If you only wanted read-only investigation, use `/skill:pwk-status` (stays gated) or reinstate the lock with `/pwk-guard on`.
+
 ## 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.
@@ -19,7 +21,7 @@ The loop must produce the failure mode the **user** described — not a nearby b
 
 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.
+Hold at Phase 1 until you have a loop you believe in. Everything downstream — hypotheses, instrumentation, the fix — depends on that loop actually reproducing the user's symptom.
 
 ## Phase 2 — Reproduce
 
@@ -53,4 +55,5 @@ Required before declaring done:
 - 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
+- If the answer is a repeatable pattern, append a **generic** rule to `docs/lessons.md` (strip domain specifics) so future sessions catch it early.
+- If the bug was caused by an architectural problem (no good test seam, tangled callers, hidden coupling), suggest writing an ADR to `docs/adr/` capturing that insight