@tianhai/pi-workflow-kit 0.14.0 → 0.16.0

package/README.md

@@ -33,20 +33,21 @@ Enforces phase-appropriate tool access — not just guidelines, but hard blocks:
 
 The agent can read code and discuss design with you during brainstorm/plan, but it physically cannot modify source files or run mutating commands.
 
-### 🧠 5 Workflow Skills
+### 🧠 6 Workflow Skills
 
 Guide the agent through a disciplined development process:
 
 ```
-brainstorm → plan → execute → finalize
-              ↕
-           diagnose (anytime)
+brainstorm → design-review → plan → execute → finalize
+                                    ↕
+                                 diagnose (anytime)
 ```
 
 | Phase | Trigger | What Happens |
 |-------|---------|--------------|
 | **Brainstorm** | `/skill:brainstorming` | Explore approaches, debate tradeoffs, produce a design doc |
-| **Plan** | `/skill:writing-plans` | Break design into bite-sized TDD tasks with file paths and acceptance criteria |
+| **Design Review** | `/skill:design-review` | Audit design for production risks (security, scalability, fault tolerance) |
+| **Plan** | `/skill:writing-plans` | Break design into bite-sized TDD tasks with acceptance criteria and concrete code |
 | **Execute** | `/skill:executing-tasks` | Implement tasks one-by-one with TDD discipline and pre-commit checkpoint review gates |
 | **Finalize** | `/skill:finalizing` | Archive plan docs, update README/CHANGELOG, create PR |
 | **Diagnose** | `/skill:diagnose` | 6-phase debugging loop: reproduce → hypothesize → instrument → fix → verify |
@@ -59,6 +60,7 @@ You control each phase — the agent never advances on its own. Invoke a skill t
 
 ```
 /skill:brainstorming   →  discuss and design
+/skill:design-review   →  audit for production risks (non-trivial designs)
 /skill:writing-plans   →  break into tasks
 /skill:executing-tasks →  implement with TDD
 /skill:finalizing      →  ship it
@@ -116,15 +118,20 @@ pi install npm:@tianhai/pi-workflow-kit
 # (agent explores approaches, writes design doc)
 # (write/edit are blocked — your code is safe)
 
+> /skill:design-review
+
+# (agent audits for security, scalability, fault tolerance)
+# (trivial changes can skip this step)
+
 > /skill:writing-plans
 
-# (agent breaks design into TDD tasks)
+# (agent breaks design into TDD tasks with acceptance criteria)
 > /skill:executing-tasks
 
-# (agent implements with TDD, all tools unlocked)
+# (agent implements with TDD, cognitive persona shifts, all tools unlocked)
 > /skill:finalizing
 
-# (agent archives docs, updates changelog, creates PR)
+# (agent archives docs, curates lessons, creates PR)
 ```
 
 ## Why?
@@ -142,6 +149,7 @@ pi-workflow-kit/
 │   └── workflow-guard.ts      # Write blocker during brainstorm/plan
 ├── skills/
 │   ├── brainstorming/SKILL.md
+│   ├── design-review/SKILL.md
 │   ├── writing-plans/SKILL.md
 │   ├── executing-tasks/SKILL.md
 │   ├── finalizing/SKILL.md

package/docs/plans/completed/2026-05-20-generic-lessons-design.md

@@ -0,0 +1,70 @@
+# Design: Enforce Generic Lessons in `docs/lessons.md`
+
+## Problem
+
+During `executing-tasks`, the agent writes lessons to `docs/lessons.md` scoped to the task at hand. In a monorepo, this produces domain-specific rules that are only useful within one feature or sprint — for example:
+
+> "Always validate `userId` before calling `UserProfile.Get`"
+
+The real lesson — applicable across any domain — would be:
+
+> "Always validate required ID fields at the service boundary — missing IDs should return 400, not 500"
+
+Domain-specific rules decay immediately after the feature is done and pollute the lessons file for future work.
+
+## Goal
+
+Rules in `docs/lessons.md` should be generic patterns applicable to any domain or feature in the repo, not instances of a pattern tied to one service or entity.
+
+## Affected files
+
+- `skills/executing-tasks/SKILL.md`
+- `skills/finalizing/SKILL.md`
+
+## Changes
+
+### 1. `executing-tasks` — Step 6 "Learn from mistakes"
+
+Add a **generalization test** after "Only add rules that would change future behavior."
+
+```
+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"
+```
+
+### 2. `executing-tasks` — `docs/lessons.md` format template comment
+
+Add one line to the comment block so the constraint is visible every time the agent opens the file:
+
+```
+Rules must be generic patterns applicable to any domain or feature — not specific to
+one service, entity, or use case.
+```
+
+### 3. `finalizing` — Step 2 "Review lessons learned"
+
+Add a generalization audit bullet between "Add any lessons..." and "Retire rules...":
+
+```
+- 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
+```
+
+### 4. `finalizing` — `docs/lessons.md` format template comment
+
+Same addition as change 2 — keep both template definitions consistent.
+
+## Slice summary
+
+One end-to-end slice:
+
+> **Lessons stay generic** — at write-time (executing-tasks step 6) the agent is required to generalize before writing; the file's own comment reinforces the constraint; at finalization the agent audits and cleans up anything that slipped through.

package/docs/plans/completed/2026-05-20-generic-lessons-implementation.md

@@ -0,0 +1,114 @@
+# Implementation Plan: Enforce Generic Lessons in `docs/lessons.md`
+
+Design: docs/plans/2026-05-20-generic-lessons-design.md
+
+Two skill files need four text edits total. No tests (markdown-only changes). Both
+tasks are trivial — exact old/new text is specified so the executor can apply them
+without guessing.
+
+---
+
+## Task 1: Add generalization test + update format comment in `executing-tasks`
+
+<!-- tdd: trivial -->
+
+File: `skills/executing-tasks/SKILL.md`
+
+Two edits in one file:
+
+### Edit A — Step 6 "Learn from mistakes"
+
+Replace:
+```
+6. **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).
+```
+
+With:
+```
+6. **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"
+```
+
+### Edit B — `docs/lessons.md` format template comment
+
+Replace:
+```
+<!--
+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.
+Retire rules that no longer apply during finalizing.
+-->
+```
+
+With:
+```
+<!--
+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.
+-->
+```
+
+Steps:
+1. Apply Edit A to `skills/executing-tasks/SKILL.md`
+2. Apply Edit B to `skills/executing-tasks/SKILL.md`
+3. Verify: open the file and confirm both edits are present and the surrounding text is intact
+
+---
+
+## Task 2: Add generalization audit bullet + update format comment in `finalizing`
+
+<!-- tdd: trivial -->
+
+File: `skills/finalizing/SKILL.md`
+
+Two edits in one file:
+
+### Edit A — Step 2 "Review lessons learned"
+
+Replace:
+```
+   - Add any lessons from this session that were missed during execution
+   - Retire rules that no longer apply (remove the bullet)
+```
+
+With:
+```
+   - Add any lessons from this session that were missed 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
+   - Retire rules that no longer apply (remove the bullet)
+```
+
+### Edit B — `docs/lessons.md` format template comment
+
+Replace:
+```
+<!--
+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.
+Retire rules that no longer apply during finalizing.
+-->
+```
+
+With:
+```
+<!--
+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.
+-->
+```
+
+Steps:
+1. Apply Edit A to `skills/finalizing/SKILL.md`
+2. Apply Edit B to `skills/finalizing/SKILL.md`
+3. Verify: open the file and confirm both edits are present and the surrounding text is intact

package/docs/plans/completed/2026-05-20-generic-lessons-progress.md

@@ -0,0 +1,11 @@
+# Progress: generic-lessons
+
+Plan: docs/plans/2026-05-20-generic-lessons-implementation.md
+Branch: generic-lessons
+Started: 2026-05-20T00:00:00Z
+Last updated: 2026-05-20T00:00:00Z
+
+| # | Status | Task | Commit |
+|---|--------|------|--------|
+| 1 | ✅ done | Add generalization test + update format comment in `executing-tasks` | 96010f7 |
+| 2 | ✅ done | Add generalization audit bullet + update format comment in `finalizing` | 72f088d |

package/docs/plans/completed/2026-05-22-agentic-agile-enhancements-design.md

@@ -0,0 +1,77 @@
+# Design: Agentic Agile & Architectural Rigor Enhancements
+
+Enforcing rigorous Agile engineering discipline within `pi-workflow-kit` by introducing Behavioral Acceptance Criteria, Cognitive Persona Shifts, automated Lessons Curation, strict Multi-Pillar Architectural Reviews, and High-Risk Operation Safeguards.
+
+## Context & Objectives
+Based on industry standards and modern agentic development templates (such as Microsoft's Agentic Agile model), autonomous coding agents succeed most when operating under tight behavioral boundaries, specialized cognitive roles, and continuous retro/learning loops.
+
+We are enhancing `pi-workflow-kit` by mapping out distinct engineering "Hats" and rigorous check-gates directly into our existing phase-based skills without adding repository clutter or introducing flaky external file lookups:
+1. **The QA Engineer Hat** (in `writing-plans`): Defines rigid, testable `Given/When/Then` Acceptance Criteria for both happy and edge paths during planning.
+2. **The Pragmatic Developer & Senior Refactorer Hats** (in `executing-tasks`): Guides the execution loop through clear cognitive phases (Green Light → Polish / Software Craftsmanship).
+3. **The Agile Scrum Master Hat** (in `finalizing`): Cleans up, de-duplicates, and categorizes persistent lessons to prevent context-bloat and maximize the utility of future sprints.
+4. **Architectural Review & Audit Gates**: Formally audits both the design (brainstorming) and the plan (writing-plans) against the 6 core pillars of production-grade software (Robustness, Atomicity, Security, Scalability, Compatibility, and Testability) before allowing the agent to move forward.
+5. **High-Risk Operation Safeguards**: Auto-detects critical execution hazards (unbounded Redis scans, in-memory OOM loops, unthrottled concurrency, long-running transactions, etc.) and mandates strict mitigation steps and verification checkpoints.
+
+---
+
+## Architecture & Detailed Design
+
+Because agent workspaces default tool execution and file-reading relative to the user's project directory, external files bundled in NPM global modules are not reliably reachable. Therefore, all guidelines are **inlined directly within the respective `SKILL.md` prompts**. This guarantees 100% reliability, zero repository pollution, and zero runtime performance overhead.
+
+### Slice 1: Multi-Pillar Design Review & Risk Detection (`brainstorming`)
+Before concluding a brainstorm and generating a design doc, the agent must put on its **Architect Hat** and evaluate the proposed system against the **6 Pillars of Production-Grade Design**:
+1. **Robustness & Fault Tolerance**: How expected failures are handled, subsystem isolation, and graceful degradation.
+2. **Atomicity & Consistency**: Database transactions, state rollback on error, and endpoint idempotency.
+3. **Security & Access Control**: Input validation/sanitization and authorization checks at the boundary.
+4. **Scalability & Performance**: Connection pooling, closing resource leaks, and preventing N+1 queries.
+5. **Backwards Compatibility**: Schema migration safety, zero-downtime deployment, and API versioning.
+6. **Testability**: Injection seams for external dependencies (APIs, system clocks, randomizers) to keep tests 100% deterministic.
+
+#### ⚠️ High-Risk Hazard Auditing
+The agent must proactively audit the design for the **8 High-Risk Production Hazards**:
+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 (e.g., `p-limit`).
+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.
+
+#### 🔍 Discovering Unknown & Contextual Risks (Socratic Heuristics)
+To identify novel or domain-specific risks that fall outside the standard checklist, the agent must put on its **SRE Hat** and audit the proposed logic against the **3 Socratic Heuristics**:
+* **The "Scale to 100x" Heuristic (Resource Exhaustion)**: 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 (Security & Malice)**: 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 (Observability & Partitioning)**: If this downstream dependency or query hangs or fails silently, how does our server react? Is there a timeout, a back-off, or logging?
+
+If any of the standard hazards or Socratic risks are identified, the design document **must** include a dedicated `⚠️ High-Risk Operations & Mitigations` section detailing the exact safety protocols applied.
+
+### Slice 2: Behavioral Acceptance Criteria & Plan Audit (`writing-plans`)
+The planning process is enhanced to mandate behavior-driven specifications and an automated plan verification step.
+
+- **Role**: QA Engineer Hat.
+- **Specification Format**: Mandatory `Given/When/Then` blocks covering the Happy Path and Edge/Error Paths.
+- **Plan Acceptance Audit**: Before presenting the plan to the user, the agent must verify:
+  - Every task is a complete vertical slice.
+  - Sizing is correct (no monolithic tasks).
+  - Checkpoint gates are placed on the most critical/risky tasks.
+  - **Risk Enforcement**: Any task containing any of the **8 High-Risk Hazards** or **Socratic Heuristics risks** is strictly required to have a mandatory `checkpoint: done` gate and explicit verification guidelines.
+
+### Slice 3: Cognitive Persona Shifts (`executing-tasks`)
+The implementation execution loop is updated to divide the cognitive workload of a single task into three distinct phases.
+
+- **Phase 1: QA Test Phase**: Translate the Given/When/Then specs into failing test cases.
+- **Phase 2: Pragmatic Developer Phase**: Implement the simplest, raw code to green the tests.
+- **Phase 3: Senior Refactoring Phase**: Refactor and polish using software craftsmanship principles (Shallow Modules, Deletion Test, Duplication, Seam Discipline).
+
+### Slice 4: Lessons Curation & Caching (`finalizing`)
+The finalizing phase is upgraded to run a structured retrospective on our persistent learning files.
+
+- **Role**: Agile Scrum Master Hat.
+- **Curating Rules**: De-duplicate, validate against the Generalization Test, and categorize rules under distinct headers (e.g., `# Tool Usage`, `# Testing Patterns`, `# Architecture Rules`).
+
+---
+
+## Verification & Testing Plan
+- **Manual Verification**: Run a mock `/skill:writing-plans` and `/skill:executing-tasks` to verify the generated implementation plan matches our QA template and the task-running agent correctly segments its progress through the three cognitive hats.
+- **Automated Tests**: Confirm existing Vitest suites run successfully without side-effects.