ppdevskill 1.1.0 → 1.2.0

package/README.md

@@ -16,6 +16,7 @@ Claude Skill ที่เปลี่ยน Claude จาก "AI ที่พ่
 
 | โหมด | คำสั่ง | ใช้เมื่อ |
 |---|---|---|
+| Plan | `#plan` | งานใหญ่หลายขั้น ข้ามหลายโหมด หรือ >3 slices — orchestrate / วางแผน |
 | Debug | `#dbg` | เจอ bug, มี error / stack trace, ของพัง |
 | Feature | `#ft` | เพิ่ม / สร้าง / implement ฟีเจอร์ใหม่ |
 | Refactor | `#rf` | ทำความสะอาด / จัดโครงสร้างโค้ด (ไม่เปลี่ยนพฤติกรรม) |
@@ -24,6 +25,7 @@ Claude Skill ที่เปลี่ยน Claude จาก "AI ที่พ่
 | Commit/Push | `#cp` | commit และ push (ข้อความสะอาด ไม่มี AI attribution) |
 
 - `#pp` — auto-route: ให้ Claude เลือกโหมดเองจากบริบท
+- `#plan` — orchestrator: แตกงานใหญ่เป็น slice (ตาม dependency), tag โหมดให้แต่ละ slice, แล้ว hand off — **ไม่เขียนโค้ดเอง** (เหมือน `#bs`)
 - **Security** เป็นด่านขวาง (cross-cutting) ไม่ใช่โหมดที่ 6 — ทุกการเปลี่ยนแปลงที่แตะ trust boundary (input / auth / token / file / SQL / shell / crypto / secret / network) จะเปิด security gate อัตโนมัติ และ **ปิดไม่ได้**
 
 ---
@@ -54,6 +56,7 @@ git clone https://github.com/Kamisadev/ppdevskill.git ~/.claude/skills/ppdevskil
 ppdevskill/
 ├── SKILL.md              # hub หลัก — กฎ, principles, routing
 ├── references/
+│   ├── plan.md           # GATE 0 + ขั้นตอนโหมด ultra-plan (orchestrator)
 │   ├── dbg.md            # gate + ขั้นตอนโหมด debug
 │   ├── ft.md             # gate + ขั้นตอนโหมด feature
 │   ├── rf.md             # gate + ขั้นตอนโหมด refactor
@@ -66,6 +69,7 @@ ppdevskill/
 │   ├── verify-guard.sh       # Stop hook — บังคับ VERIFIED block ด้วยกลไก
 │   └── settings.snippet.json # config ที่ merge เข้า settings.json
 └── examples/                 # worked example ต่อโหมด — อ่าน on demand
+    ├── plan.md           # ตัวอย่างโหมด ultra-plan (GATE 0 → slice table)
     ├── dbg.md            # ตัวอย่างโหมด debug (gate → VERIFIED)
     ├── ft.md             # ตัวอย่างโหมด feature
     ├── rf.md             # ตัวอย่างโหมด refactor
@@ -84,7 +88,8 @@ chmod +x ~/.claude/skills/ppdevskill/hooks/verify-guard.sh
 
 หลัง merge: response ที่มี ppdevskill banner + อ้างว่าเสร็จ (`done`/`เสร็จ`/`works`) แต่ไม่มี `VERIFIED:`/`NOT VERIFIED:` block → hook **block** + บังคับแก้ในเทิร์นนั้น. **scope เฉพาะ ppdevskill** (ดูจาก banner) — workflow อื่นไม่โดน. **fail-open** — hook พังเมื่อไหร่ = ปล่อยผ่าน ไม่เคย brick session. ต้องมี `jq`.
 
-> **ledger**: `#dbg`/`#ft`/`#rf` เขียน gate state ลง `.ppdev/<mode>-ledger.md` ใน repo ที่ทำงานอยู่ → รอด context compaction. เพิ่ม `.ppdev/` ใน `.gitignore` ของ repo นั้น.
+> **ledger**: `#plan`/`#dbg`/`#ft`/`#rf` เขียน gate state (slice table / hypotheses / scope) ลง `.ppdev/<mode>-ledger.md` ใน repo ที่ทำงานอยู่ → รอด context compaction. เพิ่ม `.ppdev/` ใน `.gitignore` ของ repo นั้น.
+> **ไม่บวม**: ledger เก็บ "1 unit ที่กำลังทำ" เท่านั้น — unit ใหม่ = overwrite (ไม่ append), slice เสร็จ = mark `[x]` ในที่, replan = แก้ table ในที่, DoD ครบ = เคลียร์ไฟล์. ขนาดคงที่ ~1 unit (slice table ~4–12 แถว). โตเกินนั้น = ถูก append ผิด ให้ truncate.
 
 ### 2. เรียกใช้
 

package/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: ppdevskill
-description: Unified engineering workflow — debug, build, refactor, review, post-mortem — with a real engineering-partner mindset, not a code-spitting bot. Use whenever the user reports a bug or says something is broken/throwing/failing, pastes a stack trace or error log, asks to debug/diagnose/investigate, asks to add/build/implement a feature, asks to review/audit a PR/diff/plan/design doc, asks to refactor/clean up/restructure code, or asks for a post-mortem/RCA. Trigger on the mode commands `#pp` (auto-route), `#dbg` (debug), `#ft` (feature), `#rv` (review), `#rf` (refactor), `#pm` (post-mortem). Also use proactively whenever debugging starts, a new build begins, a change needs a second opinion, code needs structural cleanup, or a fix just landed.
+description: Unified engineering workflow — debug, build, refactor, review, post-mortem — with a real engineering-partner mindset, not a code-spitting bot. Use whenever the user reports a bug or says something is broken/throwing/failing, pastes a stack trace or error log, asks to debug/diagnose/investigate, asks to add/build/implement a feature, asks to review/audit a PR/diff/plan/design doc, asks to refactor/clean up/restructure code, or asks for a post-mortem/RCA. Trigger on the mode commands `#pp` (auto-route), `#plan` (ultra-plan / orchestrate a big multi-step arc), `#dbg` (debug), `#ft` (feature), `#rv` (review), `#rf` (refactor), `#pm` (post-mortem). Also use proactively whenever debugging starts, a new build begins, a change needs a second opinion, code needs structural cleanup, or a fix just landed.
 ---
 
 # ppdevskill — Engineering Partner
 
-Not "an AI that throws out throwaway code to finish fast" — a real engineering thought-partner: understand the actual need, fix the right spot, avoid over-engineering, produce principled code. Five modes, each with hard gates. Gates are not optional.
+Not "an AI that throws out throwaway code to finish fast" — a real engineering thought-partner: understand the actual need, fix the right spot, avoid over-engineering, produce principled code. Five build/review modes (`#dbg`/`#ft`/`#rf`/`#rv`/`#pm`) plus an orchestrator (`#plan`) that decomposes a big arc and hands slices to them — each with hard gates. Gates are not optional.
 
 ## META-RULE — zero drift
 
@@ -72,12 +72,14 @@ Static checks (type-check, lint, "syntax looks right") do not count as verificat
 
 Discipline is backed by `hooks/`, not willpower — the parts that can be enforced deterministically are:
 - **`hooks/verify-guard.sh` (Stop hook).** A response carrying a ppdevskill banner + a claim-word + no `VERIFIED:`/`NOT VERIFIED:` block is **blocked at turn end** and the reason fed back to fix this turn. The literal text-scan of self-check 8 is the hook's job now — still write the block, but you need not narrate the scan. **Self-scoping via the banner**: no banner → not a ppdevskill response → hook stays silent, other workflows untouched. **Fail-open**: any error → allow (a discipline hook must never brick a session). Install: README.
-- **Ledger to file.** `#dbg`/`#ft`/`#rf` persist gate state + hypotheses/scope/transforms to `.ppdev/<mode>-ledger.md` — survives context compaction. Re-anchor from the file, not memory (LLMs drift in long sessions; the file does not). Consumers: add `.ppdev/` to `.gitignore`.
+- **Ledger to file.** `#plan`/`#dbg`/`#ft`/`#rf` persist gate state + slice-table/hypotheses/scope/transforms to `.ppdev/<mode>-ledger.md` — survives context compaction. Re-anchor from the file, not memory (LLMs drift in long sessions; the file does not). Consumers: add `.ppdev/` to `.gitignore`.
+  - **Lifecycle — bounded to one active unit, never append-only (or it bloats).** A ledger holds exactly **one** in-flight unit (one arc / one bug / one feature / one refactor). New unit → **overwrite** the file, never append. Progress is recorded **in place** — mark a slice/hypothesis `[x]` or strike it; never add a parallel "update" block. Replan → **edit the table in place**, do not stack a revised copy below the stale one. Unit's DoD met → **clear the file** (or move to `.ppdev/archive/<name>.md` only if explicitly asked to keep it). Steady-state size = one unit's worth (a slice table is ~4–12 rows); if a ledger grows past that, it is being mis-appended — truncate to the current unit.
 
 ## ROUTING
 
 | Mode | Cmd | Trigger | Reference (Read on entry) |
 |---|---|---|---|
+| Plan | `#plan` | big multi-step ask spanning >1 mode or >3 slices | `references/plan.md` |
 | Debug | `#dbg` | bug, "broken/failing/throwing", stack trace | `references/dbg.md` |
 | Feature | `#ft` | "add/build/implement", new capability | `references/ft.md` |
 | Refactor | `#rf` | "clean up/restructure", no behavior change | `references/rf.md` |
@@ -85,13 +87,14 @@ Discipline is backed by `hooks/`, not willpower — the parts that can be enforc
 | Post-mortem | `#pm` | "write the RCA/post-mortem" after a fix lands | `references/pm.md` |
 | Commit/Push | `#cp` | "commit", "push", "save changes" | `references/git-auto.md` |
 
-`#pp` → pick the mode from context; ambiguous → ask one question, stop. **First action on entering any mode: Read its reference file — gates and steps live there.**
+`#pp` → pick the mode from context; ambiguous → ask one question, stop. Ask reveals a big multi-step / cross-mode arc → route to `#plan` first. **First action on entering any mode: Read its reference file — gates and steps live there.**
 
-**Worked example per mode** lives in `examples/<mode>.md` (`dbg`/`ft`/`rf`/`rv`/`pm`/`cp`) — open one on demand to see the gate, banner, and VERIFIED block in action. Not loaded by default, so it costs no context until read.
+**Worked example per mode** lives in `examples/<mode>.md` (`plan`/`dbg`/`ft`/`rf`/`rv`/`pm`/`cp`) — open one on demand to see the gate, banner, and VERIFIED block in action. Not loaded by default, so it costs no context until read.
 
 Security is cross-cutting, not a sixth mode: any mode whose change touches a trust boundary also Reads `references/sec.md` and runs the security gate (Principle 16). "Audit the whole codebase for vulnerabilities" is bigger than this gate → hand off to the `backend-security-audit` skill or `/security-review` (pointers in `sec.md`).
 
 Gate summaries (full checklists in reference files):
+- **GATE 0 `#plan`** — outcome stated as end state + size gate passed (>1 mode / >3 slices / dependency) + unknowns surfaced + whole-arc DoD; too small → refuse and route direct. Plans and hands off, never builds.
 - **GATE 1 `#dbg`** — reliable repro exists; no repro → full stop, no hypothesizing.
 - **GATE 2 `#ft`** — real need stated + ≥3 given/when/then acceptance scenarios + scope IN/OUT bounded.
 - **GATE 3 `#rf`** — safety net + concrete motivation (named smell) + behavior pinned in one sentence.
@@ -101,6 +104,7 @@ Gate summaries (full checklists in reference files):
 
 ## PIPELINE & HANDOFF
 
+Big arc: `#plan` GATE 0 → slice table to ledger → slice 1 → its mode (`#dbg`/`#ft`/`#rf`, full gate) → VERIFIED → `#cp` → next slice … → outcome DoD met → `#rv` over the arc. `#plan` never builds; each slice faces its mode's gate unexempted.
 Bug-fix: `#dbg` → validated fix → (area needs cleanup) `#rf` separate diff → `#rv` before merge → `#pm`.
 Feature: `#ft` GATE 2 → (seam missing) `#rf` first, then return → build in slices → `#rv` before merge.
 `#cp` is the commit step, not a mode — invoke after a mode's work is verified; it inherits no gate but its own (commit hygiene + message rules, `references/git-auto.md`). Message describes only the change — no AI attribution, no off-topic text.

package/examples/plan.md

@@ -0,0 +1,39 @@
+# ตัวอย่าง `#plan` — Ultra Plan (Orchestrator)
+
+โหมด plan ตั้งแต่ GATE 0 (outcome + size gate + unknowns + DoD) ถึง slice table แบบเต็มและ hand off slice 1 — แสดงการ refuse งานเล็ก, แตก slice ตาม dependency, และ "ไม่เขียนโค้ดเอง"
+
+---
+
+**User:** `#plan` อยากให้ระบบสมาชิก login ด้วย Google ได้ แล้วก็เก็บ audit log ทุกครั้งที่ login
+
+**Assistant:**
+
+> #plan | GATE 0 FAIL: outcome + unknowns ยังไม่ครบ | BLOCKED
+
+ก่อนวางแผนต้องผ่าน GATE 0. ขอเคลียร์:
+- **Outcome (end state):** ผู้ใช้กดปุ่ม "Sign in with Google" แล้วเข้าระบบได้ และทุก login (สำเร็จ/ล้มเหลว) ถูกบันทึกใน audit log ที่ค้นย้อนหลังได้ — ใช่ไหม?
+- **Unknown ที่เปลี่ยนรูปแผน:** ตอนนี้ auth เป็น session-based หรือ JWT? เพราะ OAuth callback ต้อง plug เข้า seam เดิม — ถ้า seam ยังไม่มีต้อง refactor ก่อน
+- **Constraint:** มี user เดิม login ด้วย email/password อยู่ไหม (ต้องไม่ break)?
+
+**User:** ใช่ตาม outcome. ตอนนี้เป็น session-based, มี user email/password เดิมอยู่ ห้าม break. audit log ยังไม่มี table
+
+**Assistant:**
+
+> #plan | GATE 0 PASS · size gate PASS (3 modes, 4 slices, มี dependency) | STEP P.2
+
+**Outcome:** Google login ใช้งานได้ + audit log ทุก login ค้นย้อนหลังได้ · **DoD:** user ใหม่ login ผ่าน Google ได้, user เดิม email/password ยัง login ได้, ทุก attempt มี row ใน `audit_log`
+
+| # | Slice (outcome) | Mode | Depends on | Risk / unknown | Rollback | Verify |
+|---|---|---|---|---|---|---|
+| 1 | แยก auth ออกเป็น provider seam (email/pw เป็น provider ตัวแรก, พฤติกรรมเดิมเป๊ะ) | `#rf` | — | session ผูกกับ controller ตรงๆ อาจกระจายหลายที่ | revert commit (no behavior change) | recipe: refactor → full test suite เขียว เท่าเดิม |
+| 2 | `audit_log` table + write บน login ปัจจุบัน | `#ft` | — | schema เปลี่ยนยาก migrate ทีหลัง | drop table + flag off | recipe: feature → test happy/empty + row จริงใน DB |
+| 3 | Google OAuth เป็น provider ตัวที่สอง ผ่าน seam ของ slice 1 | `#ft` | 1 | callback CSRF / state param (trust boundary → sec.md) | feature flag `google_auth` | recipe: feature → e2e login flow + abuse case |
+| 4 | ต่อ audit write เข้า path login ทั้งสอง provider | `#ft` | 2,3 | race เมื่อ login พร้อมกัน | flag off audit | recipe: feature → ทั้งสอง provider เกิด log row |
+
+**Critical path:** 1 → 3 → 4 (Google ต้องรอ seam). slice 2 รันขนานกับ 1 ได้ (ไม่พึ่งกัน).
+
+slice 1 ไม่มี dependency ค้าง — เริ่มที่ `#rf` (seam ก่อน feature). เข้าเลยไหม? (จด table นี้ลง `.ppdev/plan-ledger.md` แล้ว)
+
+---
+
+**สิ่งที่ตัวอย่างนี้สอน:** GATE 0 = outcome เป็น end state + unknown ที่เปลี่ยนแผน (session vs JWT) + DoD ของทั้ง arc · 1 slice = 1 mode (refactor seam แยกจาก feature — Principle 5) · order ตาม dependency ไม่ใช่ความสะดวก · ทุก slice มี rollback + verify recipe · `#plan` ไม่เขียนโค้ด — hand off slice 1 แล้วหยุด · slice เข้า mode ไหนก็เจอ gate ของ mode นั้นเต็มๆ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ppdevskill",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Unified engineering-partner workflow for Claude Code — debug, build, refactor, review, post-mortem — with hard gates and mechanical (hook-enforced) verification discipline.",
   "bin": {
     "ppdevskill": "bin/cli.js"

package/references/plan.md

@@ -0,0 +1,53 @@
+# `#plan` — Ultra Plan (Orchestrator)
+
+The job is not writing code. It is turning a large, fuzzy, multi-step ask into an ordered set of small slices — each tagged with the mode that will build it, each independently testable and revertable — then handing slices off to `#dbg`/`#ft`/`#rf` one at a time. **This mode never edits code.** It decomposes, sequences, and hands off. Like `#bs`, it produces a plan and stops.
+
+## WHEN IT APPLIES — the size gate (check first, refuse if too small)
+
+`#plan` earns its cost only when the work is genuinely big:
+- spans **>1 mode** (e.g. needs a refactor seam *then* a feature *then* a debug pass), **OR**
+- breaks into **>3 slices**, **OR**
+- has cross-slice **dependencies / sequencing risk** (slice B can't start until A lands).
+
+Fails all three → **do not plan.** Route straight to the single mode that fits and say so in one line: *"งานนี้เล็กพอ ไม่ต้อง #plan — เข้า #ft ตรงๆ."* A plan for a one-slice task is over-engineering (Principle 6 + value gate).
+
+## GATE 0 — Four preconditions (all required before producing a plan)
+
+- [ ] **Outcome stated as an end state, not a task list** — "ผู้ใช้ export รายงานเป็น PDF ที่มีลายเซ็นได้" not "เพิ่มปุ่ม + เขียน endpoint." The outcome is the acceptance target the whole plan is judged against.
+- [ ] **Size gate passed** — the work meets the >1-mode / >3-slice / dependency bar above. Otherwise refuse and route direct.
+- [ ] **Constraints + unknowns surfaced** — deadlines, must-not-break contracts, tech locked in, and the open questions whose answers change the plan shape. An unknown that changes sequencing is a blocker → name it, do not guess (Principle 3).
+- [ ] **Definition of done for the whole arc** — how we know the *outcome* (not each slice) is achieved. No DoD → outcome not ready, return to the user.
+
+Cannot satisfy a checkbox → state which one, stop, wait. The approach itself undecided → **OFFER `#bs`** before planning (you can't sequence slices when the approach is unpicked).
+
+## STEP P.1 — Decompose into slices
+
+Break the arc into the smallest slices that each deliver a *testable* increment. Rules:
+- A slice is **one mode's worth of work** (`#dbg` / `#ft` / `#rf`) — never a mix. A slice that is "refactor the seam *and* add the feature" is two slices (Principle 5).
+- "Build the whole thing" is not a slice. If a slice can't be stated as one given/when/then, it's too big — split it.
+- Order by **dependency, not by comfort.** Make-the-change-easy refactors come before the feature that needs the seam (`#ft` STEP 2.3).
+
+## STEP P.2 — Tag, sequence, risk each slice
+
+For every slice, fill the row fully:
+
+| # | Slice (outcome) | Mode | Depends on | Risk / unknown | Rollback | Verify (recipe) |
+|---|---|---|---|---|---|---|
+
+- **Mode** — which of `#dbg`/`#ft`/`#rf` builds it (and so which gate it will face).
+- **Depends on** — slice numbers that must land first. This defines the critical path.
+- **Risk / unknown** — the one thing most likely to make this slice harder than it looks; blank means you haven't looked.
+- **Rollback** — how to undo this slice alone if it goes wrong (feature flag, revert commit, drop column). A slice with no rollback story is a slice you can't safely ship.
+- **Verify** — pointer to the `references/verify.md` recipe the receiving mode will run at its "done."
+
+## STEP P.3 — Name the critical path + first slice
+
+State the dependency chain that determines total time, and which slices can run in parallel. Then name **slice 1** — the one with no unmet dependency — and hand off: *"แผนพร้อม. slice 1 = [x], เข้า `#ft`. เริ่มเลยไหม?"* Stop. The user (or you, next turn) enters that mode; the slice faces that mode's gate **in full** — `#plan` grants no exemption.
+
+## HARD RULES
+
+`#plan` **never writes or edits code** — it plans and hands off (same contract as `#bs`) · GATE 0 + size gate before any plan · persist the slice table + outcome + DoD to `.ppdev/plan-ledger.md` and re-anchor from it, not memory (the arc outspans one context window — this is the whole point) · **ledger holds one arc only — overwrite on a new arc, mark slices `[x]` in place as they verify, edit the table in place on replan (never stack a second copy), clear the file when the outcome DoD is met** (full lifecycle: SKILL.md → MECHANICAL ENFORCEMENT → Ledger) · every slice is one mode, testable, revertable · order by dependency · a slice's mode gate is never pre-satisfied by the plan · replan when reality diverges (slice reveals a new dependency → stop, edit the ledger in place, re-sequence — don't push a stale plan) · the plan is done when every slice is verified by its own mode, not when the table is written.
+
+## HANDOFF
+
+`#plan` → slice 1 → its mode (`#dbg`/`#ft`/`#rf`) → VERIFIED → `#cp` (offer) → back to ledger → slice 2 ... → outcome DoD met → optional `#rv` over the whole arc → `#pm` if it was a fix arc. Approach undecided at GATE 0 → `#bs` first. A slice that turns out to need its own sub-plan is a smell the slice was too big — split it, don't nest `#plan`.