@warnyin/agents 0.11.0 → 0.12.0

package/src/.warnyin/workflow/README.md

@@ -1,101 +1,102 @@
-# Warnyin Standard Workflow
-
-มาตรฐานกลางของ "วิธีทำงาน" (ways of work) สำหรับทุกโปรเจกต์ — สร้างทีม ผลิตผลงานคุณภาพ และเร็ว
-โดยเดินผ่าน 5 stage:
-
-```
-Discovery (optional) ──▶ DESIGN ──▶ BUILD ──▶ VERIFY ──▶ SHIP
-```
-
-แต่ละ stage มี **playbook กลางหนึ่งชุด** เป็น single source of truth ที่ AI ทุกเจ้าอ่านเหมือนกัน
-
----
-
-## หลักการออกแบบ: Tool-agnostic, single source of truth
-
-แก่นของ workflow (กฎ / ขั้นตอน / เกณฑ์ผ่าน) เขียน **ครั้งเดียว** เป็น markdown ใน `.warnyin/workflow/stages/`
-ส่วน AI แต่ละเครื่องมีแค่ **adapter บางๆ** ที่ "ชี้กลับ" มาที่ playbook กลางชุดเดียวกัน
-
-| AI tool | Adapter (จุดเชื่อม) | อ่าน playbook จาก |
-|---|---|---|
-| **Claude Code** | `.claude/commands/*.md` + `CLAUDE.md` | `.warnyin/workflow/stages/*.md` |
-| **Codex** | `AGENTS.md` | `.warnyin/workflow/stages/*.md` |
-| **Antigravity** | `AGENTS.md` | `.warnyin/workflow/stages/*.md` |
-| เครื่องอื่นๆ | ชี้มาที่ `.warnyin/workflow/stages/` ได้ทันที | `.warnyin/workflow/stages/*.md` |
-
-> แก้กฎที่ `.warnyin/workflow/stages/` ที่เดียว → ทุกเครื่องได้เหมือนกันทันที
-> เพิ่ม AI เจ้าใหม่ = เพิ่ม adapter บางๆ อีกหนึ่งไฟล์ ไม่ต้องแตะ logic
-
----
-
-## โครงสร้าง repo
-
-> โครงนี้คือสิ่งที่อยู่ใน **โปรเจกต์ที่ติดตั้งแล้ว** (installer วาง `.warnyin/`+`.claude/` ให้)
-> ตัว repo `warnyin-agents` เองเก็บ source ที่จะ publish ไว้ใต้ `src/` (เช่น `src/bin/cli.mjs`, `src/.warnyin/`) — ดู `CONTRIBUTING.md`
-
-```
-.warnyin/              # ★ แก่นกลาง workflow (installer วางให้ — อัปเดตได้ด้วย --update)
-  workflow/            # playbook กลาง — single source of truth
-    README.md          #   ไฟล์นี้ — ภาพรวม + วิธีรองรับหลาย AI
-    init.md            #   playbook: INIT — วิเคราะห์โปรเจกต์ + เติม docs/ ครั้งแรก
-    codemap.md         #   playbook: CODEMAP — สแกน + สร้าง codemap แบบ token-lean
-    explore.md         #   playbook: EXPLORE — สำรวจ/ตอบคำถามแบบ read-only ไม่สร้าง artifact
-    next.md            #   playbook: NEXT — เช็คงานค้าง + แนะนำขั้นตอนถัดไป (read-only)
-    api-doc.md         #   capability: API-DOC — adaptive OpenAPI 3.1 contract (DESIGN/VERIFY/SHIP เรียกเอง)
-    stages/            #   discovery ✅ · design ✅ · build ✅ · verify ✅ · ship ✅
-    roles/             #   role card กลาง (task-level lens): ba, po, sa, tech-lead, developer, qa, security, infra
-    contexts/          #   context profile กลาง (session-level posture): research, build, review + README
-    scripts/
-      build-wave.mjs   #   Workflow script: fan-out sub-agent ต่อ task ใน wave (worktree)
-  template/            # ★ template ทั้งหมดรวมที่เดียว
-    stages/[topic]/    #   หนึ่งหน่วยงาน — copy เป็น docs/stages/<slug>
-      discovery.md  research.md            # output ของ Discovery
-      business.md  proposal.md  design.md  # output ของ DESIGN
-      tasks/[task-name]/...  build.md      # output ของ DESIGN (tasks) + BUILD
-      test.md  verify.md                   # output ของ VERIFY
-      troubleshooting.md  ship.md          # KB ระหว่างงาน + สรุปส่งมอบของ SHIP
-    docs/                                  #   โครง docs — installer seed เข้า docs/ ตอนติดตั้ง
-      project.md  rule.md  infra.md  troubleshooting.md  codemap/index.md
-      techstack/[component]/               #   copy เป็น docs/techstack/<component> (โดย /warnyin:init)
-      features/[feature-name]/             #   copy เป็น docs/features/<feature-name> (โดย SHIP) — มี spec.md (living behavior spec)
-  installer/templates/ #   template CLAUDE.md ของ target (installer ใช้เอง — ไม่ถูก copy ไป target)
-
-.claude/               # adapter Claude Code (ชี้กลับ playbook กลาง)
-  commands/warnyin/    #   slash command /warnyin:*
-  agents/              #   reviewer subagent warnyin-{sa,tech-lead,qa,security,infra}
-CLAUDE.md  AGENTS.md   # adapter + pointer ของ Claude / Codex·Antigravity
-
-docs/                  # ความรู้ถาวรระดับโปรเจกต์ + งานจริง — ของจริงล้วน (seed จาก template/docs)
-  project.md           # ★ จุดเริ่มของ Discovery — อ่านก่อนเสมอ
-  rule.md  infra.md
-  troubleshooting.md   # ★ KB ปัญหา-วิธีแก้ (อ่านก่อนเมื่อ build เจอ error; SHIP ป้อนเข้า)
-  codemap/  features/  techstack/
-  stages/              #   พื้นที่ทำงานจริง ตาม topic (<slug>/) + achieved/<YYYY-MM-DD>-<slug>/ หลัง SHIP
-```
-```
-
----
-
-## การติดตั้งไปโปรเจกต์อื่น
-
-```bash
-cd my-project
-npx @warnyin/agents             # ติดตั้ง (ข้ามไฟล์ที่มีอยู่ ไม่เขียนทับ)
-npx @warnyin/agents --update    # อัปเดต playbook กลางเป็นเวอร์ชันล่าสุด
-npx @warnyin/agents --dry-run   # ดูก่อนว่าจะสร้าง/อัปเดตอะไร
-# ทางสำรอง (ไม่ผ่าน npm): npx github:warnyin/warnyin-agents
-```
-
-- โปรเจกต์ที่มี `CLAUDE.md`/`AGENTS.md` อยู่แล้ว → installer ต่อท้ายเป็น section ไม่เขียนทับ
-- `--update` เขียนทับเฉพาะ core (`.warnyin/workflow/`, `.claude/commands/warnyin/`, template ใน `.warnyin/template/`) — ไม่แตะ `docs/` และงานจริง
-- หลังติดตั้ง → เปิด Claude Code แล้วรัน `/warnyin:init` ให้ agent วิเคราะห์โปรเจกต์ + เติม `docs/` (playbook: `.warnyin/workflow/init.md`)
-
-## วิธีใช้
-
-1. เริ่มงานใหม่ → copy `.warnyin/template/stages/[topic]/` เป็น `docs/stages/<ชื่อ-งาน-kebab-case>/`
-2. รัน stage ตามลำดับ (Discovery ข้ามได้ถ้าเข้าใจ scope ชัดแล้ว)
-   - Claude Code: `/warnyin:discovery <topic>`, `/warnyin:design <slug> <change>`
-   - Codex / Antigravity: บอกให้ทำตาม `.warnyin/workflow/stages/<stage>.md`
-3. ผ่าน "gate" ของแต่ละ stage แล้วจึงไป stage ถัดไป
-4. เมื่อ SHIP (`/warnyin:ship <slug>`) → promote ความรู้ของ topic ขึ้นเอกสารกลางใน `docs/`
-   แล้วย้าย topic ไป `docs/stages/achieved/<YYYY-MM-DD>-<topic>/`
+# Warnyin Standard Workflow
+
+มาตรฐานกลางของ "วิธีทำงาน" (ways of work) สำหรับทุกโปรเจกต์ — สร้างทีม ผลิตผลงานคุณภาพ และเร็ว
+โดยเดินผ่าน 5 stage:
+
+```
+Discovery (optional) ──▶ DESIGN ──▶ BUILD ──▶ VERIFY ──▶ SHIP
+```
+
+แต่ละ stage มี **playbook กลางหนึ่งชุด** เป็น single source of truth ที่ AI ทุกเจ้าอ่านเหมือนกัน
+
+---
+
+## หลักการออกแบบ: Tool-agnostic, single source of truth
+
+แก่นของ workflow (กฎ / ขั้นตอน / เกณฑ์ผ่าน) เขียน **ครั้งเดียว** เป็น markdown ใน `.warnyin/workflow/stages/`
+ส่วน AI แต่ละเครื่องมีแค่ **adapter บางๆ** ที่ "ชี้กลับ" มาที่ playbook กลางชุดเดียวกัน
+
+| AI tool | Adapter (จุดเชื่อม) | อ่าน playbook จาก |
+|---|---|---|
+| **Claude Code** | `.claude/commands/*.md` + `CLAUDE.md` | `.warnyin/workflow/stages/*.md` |
+| **Codex** | `AGENTS.md` | `.warnyin/workflow/stages/*.md` |
+| **Antigravity** | `AGENTS.md` | `.warnyin/workflow/stages/*.md` |
+| เครื่องอื่นๆ | ชี้มาที่ `.warnyin/workflow/stages/` ได้ทันที | `.warnyin/workflow/stages/*.md` |
+
+> แก้กฎที่ `.warnyin/workflow/stages/` ที่เดียว → ทุกเครื่องได้เหมือนกันทันที
+> เพิ่ม AI เจ้าใหม่ = เพิ่ม adapter บางๆ อีกหนึ่งไฟล์ ไม่ต้องแตะ logic
+
+---
+
+## โครงสร้าง repo
+
+> โครงนี้คือสิ่งที่อยู่ใน **โปรเจกต์ที่ติดตั้งแล้ว** (installer วาง `.warnyin/`+`.claude/` ให้)
+> ตัว repo `warnyin-agents` เองเก็บ source ที่จะ publish ไว้ใต้ `src/` (เช่น `src/bin/cli.mjs`, `src/.warnyin/`) — ดู `CONTRIBUTING.md`
+
+```
+.warnyin/              # ★ แก่นกลาง workflow (installer วางให้ — อัปเดตได้ด้วย --update)
+  workflow/            # playbook กลาง — single source of truth
+    README.md          #   ไฟล์นี้ — ภาพรวม + วิธีรองรับหลาย AI
+    init.md            #   playbook: INIT — วิเคราะห์โปรเจกต์ + เติม docs/ ครั้งแรก
+    codemap.md         #   playbook: CODEMAP — สแกน + สร้าง codemap แบบ token-lean
+    explore.md         #   playbook: EXPLORE — สำรวจ/ตอบคำถามแบบ read-only ไม่สร้าง artifact
+    next.md            #   playbook: NEXT — เช็คงานค้าง + แนะนำขั้นตอนถัดไป (read-only)
+    triage.md          #   capability: TRIAGE — ประเมินขนาด change → tier + route (read-only)
+    api-doc.md         #   capability: API-DOC — adaptive OpenAPI 3.1 contract (DESIGN/VERIFY/SHIP เรียกเอง)
+    stages/            #   discovery ✅ · design ✅ · build ✅ · verify ✅ · ship ✅
+    roles/             #   role card กลาง (task-level lens): ba, po, sa, tech-lead, developer, qa, security, infra
+    contexts/          #   context profile กลาง (session-level posture): research, build, review + README
+    scripts/
+      build-wave.mjs   #   Workflow script: fan-out sub-agent ต่อ task ใน wave (worktree)
+  template/            # ★ template ทั้งหมดรวมที่เดียว
+    stages/[topic]/    #   หนึ่งหน่วยงาน — copy เป็น docs/stages/<slug>
+      discovery.md  research.md            # output ของ Discovery
+      business.md  proposal.md  design.md  # output ของ DESIGN
+      tasks/[task-name]/...  build.md      # output ของ DESIGN (tasks) + BUILD
+      test.md  verify.md                   # output ของ VERIFY
+      troubleshooting.md  ship.md          # KB ระหว่างงาน + สรุปส่งมอบของ SHIP
+    docs/                                  #   โครง docs — installer seed เข้า docs/ ตอนติดตั้ง
+      project.md  rule.md  infra.md  troubleshooting.md  codemap/index.md
+      techstack/[component]/               #   copy เป็น docs/techstack/<component> (โดย /warnyin:init)
+      features/[feature-name]/             #   copy เป็น docs/features/<feature-name> (โดย SHIP) — มี spec.md (living behavior spec)
+  installer/templates/ #   template CLAUDE.md ของ target (installer ใช้เอง — ไม่ถูก copy ไป target)
+
+.claude/               # adapter Claude Code (ชี้กลับ playbook กลาง)
+  commands/warnyin/    #   slash command /warnyin:*
+  agents/              #   reviewer subagent warnyin-{sa,tech-lead,qa,security,infra}
+CLAUDE.md  AGENTS.md   # adapter + pointer ของ Claude / Codex·Antigravity
+
+docs/                  # ความรู้ถาวรระดับโปรเจกต์ + งานจริง — ของจริงล้วน (seed จาก template/docs)
+  project.md           # ★ จุดเริ่มของ Discovery — อ่านก่อนเสมอ
+  rule.md  infra.md
+  troubleshooting.md   # ★ KB ปัญหา-วิธีแก้ (อ่านก่อนเมื่อ build เจอ error; SHIP ป้อนเข้า)
+  codemap/  features/  techstack/
+  stages/              #   พื้นที่ทำงานจริง ตาม topic (<slug>/) + achieved/<YYYY-MM-DD>-<slug>/ หลัง SHIP
+```
+```
+
+---
+
+## การติดตั้งไปโปรเจกต์อื่น
+
+```bash
+cd my-project
+npx @warnyin/agents             # ติดตั้ง (ข้ามไฟล์ที่มีอยู่ ไม่เขียนทับ)
+npx @warnyin/agents --update    # อัปเดต playbook กลางเป็นเวอร์ชันล่าสุด
+npx @warnyin/agents --dry-run   # ดูก่อนว่าจะสร้าง/อัปเดตอะไร
+# ทางสำรอง (ไม่ผ่าน npm): npx github:warnyin/warnyin-agents
+```
+
+- โปรเจกต์ที่มี `CLAUDE.md`/`AGENTS.md` อยู่แล้ว → installer ต่อท้ายเป็น section ไม่เขียนทับ
+- `--update` เขียนทับเฉพาะ core (`.warnyin/workflow/`, `.claude/commands/warnyin/`, template ใน `.warnyin/template/`) — ไม่แตะ `docs/` และงานจริง
+- หลังติดตั้ง → เปิด Claude Code แล้วรัน `/warnyin:init` ให้ agent วิเคราะห์โปรเจกต์ + เติม `docs/` (playbook: `.warnyin/workflow/init.md`)
+
+## วิธีใช้
+
+1. เริ่มงานใหม่ → copy `.warnyin/template/stages/[topic]/` เป็น `docs/stages/<ชื่อ-งาน-kebab-case>/`
+2. รัน stage ตามลำดับ (Discovery ข้ามได้ถ้าเข้าใจ scope ชัดแล้ว)
+   - Claude Code: `/warnyin:discovery <topic>`, `/warnyin:design <slug> <change>`
+   - Codex / Antigravity: บอกให้ทำตาม `.warnyin/workflow/stages/<stage>.md`
+3. ผ่าน "gate" ของแต่ละ stage แล้วจึงไป stage ถัดไป
+4. เมื่อ SHIP (`/warnyin:ship <slug>`) → promote ความรู้ของ topic ขึ้นเอกสารกลางใน `docs/`
+   แล้วย้าย topic ไป `docs/stages/achieved/<YYYY-MM-DD>-<topic>/`

package/src/.warnyin/workflow/api-doc.md

@@ -1,93 +1,93 @@
-# API-DOC — เอกสาร REST API (OpenAPI 3.1) แบบ adaptive
-
-> **Playbook กลาง — AI ทุกเจ้าทำตามไฟล์นี้ชุดเดียวกัน** (Claude Code / Codex / Antigravity / อื่นๆ)
-> เป้าหมาย: ถ้า topic **แตะ backend/REST API จริง** → ผลิต + ยืนยัน + ส่งมอบ **OpenAPI 3.1 contract** ให้อัตโนมัติ ตลอด lifecycle (DESIGN → VERIFY → SHIP)
-
----
-
-## 1. คืออะไร / ใช้เมื่อไหร่
-
-API-DOC ไม่ใช่ stage แยก และ **ไม่มี slash command** — เป็น **capability เสริมที่ stage เรียกใช้เอง** เมื่อ auto-detect พบว่า topic เกี่ยวกับ REST API
-
-- ทำงานเป็นส่วนหนึ่งของ DESIGN / VERIFY / SHIP — stage playbook ชี้มาที่ไฟล์นี้
-- **adaptive:** ตรวจ signal ทุก topic — ถ้า **ไม่ใช่** backend/REST API → **ข้ามทั้งหมดเงียบๆ** (ไม่ยัดเยียด ไม่สร้างไฟล์เปล่า)
-- tool-agnostic: เป็นมาตรฐาน OpenAPI 3.1 ล้วน ไม่ผูกกับ AI เจ้าใดหรือเฟรมเวิร์กใด
-
----
-
-## 2. Auto-detect — topic นี้แตะ REST API ไหม?
-
-ดูสัญญาณต่อไปนี้ (เจอ **อย่างน้อยหนึ่ง** ที่ชัดเจน = ใช่):
-
-1. **techstack** — `docs/techstack/<component>/about.md` ระบุว่าเป็น backend/HTTP service / REST / web API
-2. **route ในโค้ด** — มี handler/controller ที่ผูก HTTP route เช่น Express/Fastify/NestJS/Koa/Hapi, FastAPI/Flask/Django REST, Spring/Gin/Echo, ASP.NET ฯลฯ
-3. **annotation/decorator** ที่ gen spec ได้อยู่แล้ว — tsoa, springdoc, drf-spectacular, FastAPI (Pydantic)
-4. **task ถูกจัดเป็น "API task"** ตอนแตก spec (design.md §6)
-5. **change เพิ่ม/แก้ HTTP endpoint** — request/response/error/auth/status code เปลี่ยน
-
-> สัญญาณคลุมเครือ (เช่น มีแค่ internal function ไม่ใช่ HTTP, RPC/gRPC ที่ไม่ใช่ REST, CLI/library ล้วน) → **ไม่ใช่** → ข้าม
-> ไม่แน่ใจจริง → ถาม user ทีละข้อ + เสนอคำตอบที่แนะนำ (ตามหลัก "ห้ามเดา" ของทุก stage)
-
----
-
-## 3. เลือกโหมด (เลือกตาม signal + ระยะของงาน)
-
-| โหมด | เมื่อไหร่ | วิธี |
-|---|---|---|
-| **Design-first** | endpoint **ใหม่** ยังไม่มีโค้ด | เขียน `openapi.yaml` ก่อน (ตอน DESIGN) = contract ที่ BUILD จะ implement ตาม |
-| **Code-first** | API **มีอยู่แล้ว** + เฟรมเวิร์ก gen spec ได้ (FastAPI/tsoa ฯลฯ) | generate spec จากโค้ด แล้วตรวจ/เก็บเป็น artifact |
-| **Hybrid** | โค้ดมี annotation/decorator แต่ยังไม่ครบ | gen จาก annotation + เติม schema/example ที่ขาดด้วยมือ |
-
-โปรเจกต์เดียวกันใช้คนละโหมดต่อ topic ได้ — เลือกตามจริง
-
----
-
-## 4. บทบาทต่อ stage
-
-### DESIGN — ผลิต contract
-- detect (ข้อ 2) → ถ้าใช่: ผลิต/อัปเดต `docs/stages/<slug>/openapi.yaml` (OpenAPI 3.1)
-  - endpoint ใหม่ → **design-first** เขียน contract ก่อน; API เดิม → **code-first/hybrid** gen จากโค้ดแล้วเติม
-- `tasks/<api-task>/spec.md` (API SPEC) **ชี้มาที่ `openapi.yaml`** — ไม่เขียน schema ซ้ำสองที่ (single source)
-- ถ้ามีเครื่องมือ lint ในโปรเจกต์ → รัน (ดูข้อ 5); ไม่มีก็ข้าม ไม่บังคับติดตั้ง
-
-### VERIFY — ยืนยันว่าโค้ดจริงตรง contract
-- topic มี `openapi.yaml` → **contract validation**: ยืนยันว่า implementation จริง = contract
-  - code-first: regen spec จากโค้ด → diff กับ `openapi.yaml` (ต้องไม่ต่าง)
-  - หรือยิง request จริงใน local env → ตรวจ response ตรง schema/status/error ที่ระบุ
-  - **★ runtime security:** การ regen (boot app จริง — FastAPI/tsoa) หรือยิง request จริง อยู่ใต้ runtime-security ของ `verify.md` §2 (local-only, scoped credential, no prod, no unnecessary egress) — ทบทวนก่อนปล่อย agent แตะของจริง
-- mismatch = **ไม่ผ่าน** → แก้ (โค้ด หรือ contract ตามต้นเหตุจริง) วนจนตรง — นับเป็นส่วนหนึ่งของ fix loop ใน verify.md §4
-
-### SHIP — promote contract ขึ้นเอกสารกลาง
-- ยก `openapi.yaml` → **`docs/techstack/<component>/openapi.yaml`** = living API contract ถาวร (เทียบเท่า `spec.md` ที่เป็น living behavior spec)
-- มี contract เดิมอยู่แล้ว → **merge ตาม delta** (เพิ่ม/แก้/ลบ path·schema ที่ topic แตะ) ไม่ทับทั้งไฟล์
-- อ้างถึงจาก `docs/features/<name>/spec.md` ของ feature ที่ใช้ endpoint นั้น
-
----
-
-## 5. มาตรฐาน + เครื่องมือ (reference ไม่ vendor)
-
-- **มาตรฐาน:** OpenAPI **3.1.0** — `info`/`servers`/`paths`/`components.schemas`/`components.securitySchemes`; ใช้ `$ref` reuse, ใส่ `examples`, ระบุ error + status code + auth scheme ครบ, อย่า hardcode URL (ใช้ server variable)
-- **★ secret hygiene (บังคับ — `openapi.yaml` ถูก commit ถาวร):** ก่อน commit/promote ต้อง **scrub** — `servers.url` ใช้ placeholder/variable (ไม่ใช่ internal/staging host จริง), `examples`/`example`/default ใช้ค่า dummy (`user@example.com`, `<token>`) **ห้าม secret/credential/PII จริง**, `securitySchemes` ระบุแค่รูปแบบ ไม่ใส่ค่า token จริง — โดยเฉพาะตอน code-first gen จากโค้ด ที่ค่าจริงมักหลุดติดมา (สอด `docs/rule.md` §3.2 + spec convention "ค่าสังเคราะห์เท่านั้น")
-- **เครื่องมือ (ติดตั้งเองเมื่ออยากใช้ — ไม่ผูกใน workflow):**
-
-  | งาน | เครื่องมือ | คำสั่งตัวอย่าง |
-  |---|---|---|
-  | lint spec | Spectral | `spectral lint openapi.yaml` |
-  | lint/bundle/preview | Redocly CLI | `redocly lint openapi.yaml` |
-  | gen client SDK | OpenAPI Generator | `openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./gen/ts` |
-  | gen จากโค้ด | FastAPI (auto), tsoa (`@Route`/`@Get`) | ตามเฟรมเวิร์ก |
-
-- **Skill อ้างอิง (optional):** `openapi-spec-generation` — template library เต็ม (full API spec, FastAPI, tsoa, Spectral ruleset, SDK gen)
-  ที่มา: `wshobson/agents` → `plugins/documentation-generation/skills/openapi-spec-generation/`
-  (`SKILL.md` + `references/details.md` + `references/code-first-and-tooling.md`) — โปรเจกต์ไหนอยากได้ template สำเร็จรูปค่อยติดตั้ง
-
----
-
-## 6. ที่อยู่ของ artifact
-
-| ระยะ | ที่ | หมายเหตุ |
-|---|---|---|
-| ระหว่างงาน | `docs/stages/<slug>/openapi.yaml` | optional — เฉพาะ topic ที่แตะ REST API |
-| ถาวร (หลัง SHIP) | `docs/techstack/<component>/openapi.yaml` | living API contract — SHIP merge ตาม delta |
-
-> **`<component>` resolution (ห้ามเดา):** topic แตะ **หลาย component** หรือ component ที่ **ยังไม่มีใน `docs/techstack/`** → ถาม user ว่าจะวาง contract ที่ component ไหน / สร้าง techstack entry ก่อนไหม — ไม่เดาเอง
+# API-DOC — เอกสาร REST API (OpenAPI 3.1) แบบ adaptive
+
+> **Playbook กลาง — AI ทุกเจ้าทำตามไฟล์นี้ชุดเดียวกัน** (Claude Code / Codex / Antigravity / อื่นๆ)
+> เป้าหมาย: ถ้า topic **แตะ backend/REST API จริง** → ผลิต + ยืนยัน + ส่งมอบ **OpenAPI 3.1 contract** ให้อัตโนมัติ ตลอด lifecycle (DESIGN → VERIFY → SHIP)
+
+---
+
+## 1. คืออะไร / ใช้เมื่อไหร่
+
+API-DOC ไม่ใช่ stage แยก และ **ไม่มี slash command** — เป็น **capability เสริมที่ stage เรียกใช้เอง** เมื่อ auto-detect พบว่า topic เกี่ยวกับ REST API
+
+- ทำงานเป็นส่วนหนึ่งของ DESIGN / VERIFY / SHIP — stage playbook ชี้มาที่ไฟล์นี้
+- **adaptive:** ตรวจ signal ทุก topic — ถ้า **ไม่ใช่** backend/REST API → **ข้ามทั้งหมดเงียบๆ** (ไม่ยัดเยียด ไม่สร้างไฟล์เปล่า)
+- tool-agnostic: เป็นมาตรฐาน OpenAPI 3.1 ล้วน ไม่ผูกกับ AI เจ้าใดหรือเฟรมเวิร์กใด
+
+---
+
+## 2. Auto-detect — topic นี้แตะ REST API ไหม?
+
+ดูสัญญาณต่อไปนี้ (เจอ **อย่างน้อยหนึ่ง** ที่ชัดเจน = ใช่):
+
+1. **techstack** — `docs/techstack/<component>/about.md` ระบุว่าเป็น backend/HTTP service / REST / web API
+2. **route ในโค้ด** — มี handler/controller ที่ผูก HTTP route เช่น Express/Fastify/NestJS/Koa/Hapi, FastAPI/Flask/Django REST, Spring/Gin/Echo, ASP.NET ฯลฯ
+3. **annotation/decorator** ที่ gen spec ได้อยู่แล้ว — tsoa, springdoc, drf-spectacular, FastAPI (Pydantic)
+4. **task ถูกจัดเป็น "API task"** ตอนแตก spec (design.md §6)
+5. **change เพิ่ม/แก้ HTTP endpoint** — request/response/error/auth/status code เปลี่ยน
+
+> สัญญาณคลุมเครือ (เช่น มีแค่ internal function ไม่ใช่ HTTP, RPC/gRPC ที่ไม่ใช่ REST, CLI/library ล้วน) → **ไม่ใช่** → ข้าม
+> ไม่แน่ใจจริง → ถาม user ทีละข้อ + เสนอคำตอบที่แนะนำ (ตามหลัก "ห้ามเดา" ของทุก stage)
+
+---
+
+## 3. เลือกโหมด (เลือกตาม signal + ระยะของงาน)
+
+| โหมด | เมื่อไหร่ | วิธี |
+|---|---|---|
+| **Design-first** | endpoint **ใหม่** ยังไม่มีโค้ด | เขียน `openapi.yaml` ก่อน (ตอน DESIGN) = contract ที่ BUILD จะ implement ตาม |
+| **Code-first** | API **มีอยู่แล้ว** + เฟรมเวิร์ก gen spec ได้ (FastAPI/tsoa ฯลฯ) | generate spec จากโค้ด แล้วตรวจ/เก็บเป็น artifact |
+| **Hybrid** | โค้ดมี annotation/decorator แต่ยังไม่ครบ | gen จาก annotation + เติม schema/example ที่ขาดด้วยมือ |
+
+โปรเจกต์เดียวกันใช้คนละโหมดต่อ topic ได้ — เลือกตามจริง
+
+---
+
+## 4. บทบาทต่อ stage
+
+### DESIGN — ผลิต contract
+- detect (ข้อ 2) → ถ้าใช่: ผลิต/อัปเดต `docs/stages/<slug>/openapi.yaml` (OpenAPI 3.1)
+  - endpoint ใหม่ → **design-first** เขียน contract ก่อน; API เดิม → **code-first/hybrid** gen จากโค้ดแล้วเติม
+- `tasks/<api-task>/spec.md` (API SPEC) **ชี้มาที่ `openapi.yaml`** — ไม่เขียน schema ซ้ำสองที่ (single source)
+- ถ้ามีเครื่องมือ lint ในโปรเจกต์ → รัน (ดูข้อ 5); ไม่มีก็ข้าม ไม่บังคับติดตั้ง
+
+### VERIFY — ยืนยันว่าโค้ดจริงตรง contract
+- topic มี `openapi.yaml` → **contract validation**: ยืนยันว่า implementation จริง = contract
+  - code-first: regen spec จากโค้ด → diff กับ `openapi.yaml` (ต้องไม่ต่าง)
+  - หรือยิง request จริงใน local env → ตรวจ response ตรง schema/status/error ที่ระบุ
+  - **★ runtime security:** การ regen (boot app จริง — FastAPI/tsoa) หรือยิง request จริง อยู่ใต้ runtime-security ของ `verify.md` §2 (local-only, scoped credential, no prod, no unnecessary egress) — ทบทวนก่อนปล่อย agent แตะของจริง
+- mismatch = **ไม่ผ่าน** → แก้ (โค้ด หรือ contract ตามต้นเหตุจริง) วนจนตรง — นับเป็นส่วนหนึ่งของ fix loop ใน verify.md §4
+
+### SHIP — promote contract ขึ้นเอกสารกลาง
+- ยก `openapi.yaml` → **`docs/techstack/<component>/openapi.yaml`** = living API contract ถาวร (เทียบเท่า `spec.md` ที่เป็น living behavior spec)
+- มี contract เดิมอยู่แล้ว → **merge ตาม delta** (เพิ่ม/แก้/ลบ path·schema ที่ topic แตะ) ไม่ทับทั้งไฟล์
+- อ้างถึงจาก `docs/features/<name>/spec.md` ของ feature ที่ใช้ endpoint นั้น
+
+---
+
+## 5. มาตรฐาน + เครื่องมือ (reference ไม่ vendor)
+
+- **มาตรฐาน:** OpenAPI **3.1.0** — `info`/`servers`/`paths`/`components.schemas`/`components.securitySchemes`; ใช้ `$ref` reuse, ใส่ `examples`, ระบุ error + status code + auth scheme ครบ, อย่า hardcode URL (ใช้ server variable)
+- **★ secret hygiene (บังคับ — `openapi.yaml` ถูก commit ถาวร):** ก่อน commit/promote ต้อง **scrub** — `servers.url` ใช้ placeholder/variable (ไม่ใช่ internal/staging host จริง), `examples`/`example`/default ใช้ค่า dummy (`user@example.com`, `<token>`) **ห้าม secret/credential/PII จริง**, `securitySchemes` ระบุแค่รูปแบบ ไม่ใส่ค่า token จริง — โดยเฉพาะตอน code-first gen จากโค้ด ที่ค่าจริงมักหลุดติดมา (สอด `docs/rule.md` §3.2 + spec convention "ค่าสังเคราะห์เท่านั้น")
+- **เครื่องมือ (ติดตั้งเองเมื่ออยากใช้ — ไม่ผูกใน workflow):**
+
+  | งาน | เครื่องมือ | คำสั่งตัวอย่าง |
+  |---|---|---|
+  | lint spec | Spectral | `spectral lint openapi.yaml` |
+  | lint/bundle/preview | Redocly CLI | `redocly lint openapi.yaml` |
+  | gen client SDK | OpenAPI Generator | `openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./gen/ts` |
+  | gen จากโค้ด | FastAPI (auto), tsoa (`@Route`/`@Get`) | ตามเฟรมเวิร์ก |
+
+- **Skill อ้างอิง (optional):** `openapi-spec-generation` — template library เต็ม (full API spec, FastAPI, tsoa, Spectral ruleset, SDK gen)
+  ที่มา: `wshobson/agents` → `plugins/documentation-generation/skills/openapi-spec-generation/`
+  (`SKILL.md` + `references/details.md` + `references/code-first-and-tooling.md`) — โปรเจกต์ไหนอยากได้ template สำเร็จรูปค่อยติดตั้ง
+
+---
+
+## 6. ที่อยู่ของ artifact
+
+| ระยะ | ที่ | หมายเหตุ |
+|---|---|---|
+| ระหว่างงาน | `docs/stages/<slug>/openapi.yaml` | optional — เฉพาะ topic ที่แตะ REST API |
+| ถาวร (หลัง SHIP) | `docs/techstack/<component>/openapi.yaml` | living API contract — SHIP merge ตาม delta |
+
+> **`<component>` resolution (ห้ามเดา):** topic แตะ **หลาย component** หรือ component ที่ **ยังไม่มีใน `docs/techstack/`** → ถาม user ว่าจะวาง contract ที่ component ไหน / สร้าง techstack entry ก่อนไหม — ไม่เดาเอง

package/src/.warnyin/workflow/codemap.md

@@ -1,91 +1,91 @@
-# CODEMAP — สแกนโครงสร้างโปรเจกต์ + สร้าง architecture codemap แบบ token-lean
-
-> **Playbook กลาง — AI ทุกเจ้าทำตามไฟล์นี้ชุดเดียวกัน** (Claude Code / Codex / Antigravity / อื่นๆ)
-> เป้าหมาย: `docs/codemap/` ที่ **ประหยัด token** สำหรับให้ AI โหลดเข้า context — โครงสร้างระดับสูง ไม่ใช่ implementation detail
-
----
-
-## 1. ใช้เมื่อไหร่
-
-- หลังเพิ่ม feature ใหญ่ / refactor ครั้งสำคัญ
-- `/warnyin:init` ใช้ playbook นี้ตอนสร้าง codemap ครั้งแรก
-- **SHIP** ใช้ตอนขั้น "อัปเดต code map ทั้งหมด"
-
----
-
-## 2. ขั้นตอน
-
-### Step 1: สแกนโครงสร้างโปรเจกต์
-- ระบุชนิดโปรเจกต์: monorepo / single app / library / microservice
-- หา source directory ทั้งหมด (`src/`, `lib/`, `app/`, `packages/`, ...)
-- map entry points (`main.ts`, `index.ts`, `app.py`, `main.go`, ...)
-- สแกนขนานได้: fan-out sub-agent (read-only) ต่อ component/พื้นที่ — เครื่องที่ไม่มี sub-agent → ไล่ทีละส่วน
-
-### Step 2: สร้าง/อัปเดต codemap ใน `docs/codemap/`
-
-| ไฟล์ | เนื้อหา |
-|---|---|
-| `index.md` | สารบัญทั้งชุด + ภาพรวม component + จุดเข้า |
-| `architecture.md` | system diagram ระดับสูง, service boundary, data flow |
-| `backend.md` | API routes, middleware chain, service → repository mapping |
-| `frontend.md` | page tree, component hierarchy, state management flow |
-| `data.md` | ตาราง DB, relationship, migration history |
-| `dependencies.md` | external service, third-party integration, shared library |
-
-**สร้างเฉพาะไฟล์ที่ relevant** — โปรเจกต์ไม่มี frontend → ไม่ต้องมี `frontend.md`
-
-#### รูปแบบ codemap (token-lean)
-
-```markdown
-# Backend Architecture
-
-## Routes
-POST /api/users → UserController.create → UserService.create → UserRepo.insert
-GET  /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
-
-## Key Files
-src/services/user.ts (business logic, 120 lines)
-src/repos/user.ts (database access, 80 lines)
-
-## Dependencies
-- PostgreSQL (primary data store)
-- Redis (session cache, rate limiting)
-- Stripe (payment processing)
-```
-
-### Step 3: Diff detection
-- มี codemap เดิมอยู่ → คำนวณ % การเปลี่ยนแปลง
-- เปลี่ยน **> 30%** → แสดง diff + **ขอ user อนุมัติก่อนเขียนทับ**
-- เปลี่ยน **≤ 30%** → อัปเดต in place ได้เลย
-
-### Step 4: Metadata
-ใส่ freshness header บนสุดของทุกไฟล์:
-```html
-<!-- Generated: YYYY-MM-DD | Files scanned: N | Token estimate: ~X -->
-```
-
-### Step 5: Analysis report → `.reports/codemap-diff.txt`
-- ไฟล์ added / removed / modified ตั้งแต่สแกนครั้งล่าสุด
-- dependency ใหม่ที่ตรวจพบ
-- architecture changes (route ใหม่, service ใหม่ ฯลฯ)
-- คำเตือน staleness: doc ที่ไม่ถูกอัปเดต 90+ วัน
-
----
-
-## 3. หลักการ (tips)
-
-- โฟกัสโครงสร้างระดับสูง — **ไม่ใช่** implementation detail
-- ใช้ file path + function signature แทน code block เต็ม
-- แต่ละ codemap **< 1000 tokens** เพื่อโหลดเข้า context ได้ถูก
-- ใช้ ASCII diagram แทนคำบรรยาย data flow ยืดยาว
-- **ทุกอย่างต้องมาจากโค้ดจริง ณ วันสแกน — ห้ามเดา/ห้ามเขียนจากความจำ**
-
----
-
-## 4. Gate — จบเมื่อ
-
-- [ ] codemap ทุกไฟล์ตรงโค้ดจริง + มี freshness header
-- [ ] `index.md` ลิงก์ครบทุกไฟล์ codemap ที่มี
-- [ ] ทุกไฟล์ token-lean (< 1000 tokens)
-- [ ] diff > 30% ผ่านการอนุมัติจาก user แล้ว
-- [ ] `.reports/codemap-diff.txt` เขียนแล้ว
+# CODEMAP — สแกนโครงสร้างโปรเจกต์ + สร้าง architecture codemap แบบ token-lean
+
+> **Playbook กลาง — AI ทุกเจ้าทำตามไฟล์นี้ชุดเดียวกัน** (Claude Code / Codex / Antigravity / อื่นๆ)
+> เป้าหมาย: `docs/codemap/` ที่ **ประหยัด token** สำหรับให้ AI โหลดเข้า context — โครงสร้างระดับสูง ไม่ใช่ implementation detail
+
+---
+
+## 1. ใช้เมื่อไหร่
+
+- หลังเพิ่ม feature ใหญ่ / refactor ครั้งสำคัญ
+- `/warnyin:init` ใช้ playbook นี้ตอนสร้าง codemap ครั้งแรก
+- **SHIP** ใช้ตอนขั้น "อัปเดต code map ทั้งหมด"
+
+---
+
+## 2. ขั้นตอน
+
+### Step 1: สแกนโครงสร้างโปรเจกต์
+- ระบุชนิดโปรเจกต์: monorepo / single app / library / microservice
+- หา source directory ทั้งหมด (`src/`, `lib/`, `app/`, `packages/`, ...)
+- map entry points (`main.ts`, `index.ts`, `app.py`, `main.go`, ...)
+- สแกนขนานได้: fan-out sub-agent (read-only) ต่อ component/พื้นที่ — เครื่องที่ไม่มี sub-agent → ไล่ทีละส่วน
+
+### Step 2: สร้าง/อัปเดต codemap ใน `docs/codemap/`
+
+| ไฟล์ | เนื้อหา |
+|---|---|
+| `index.md` | สารบัญทั้งชุด + ภาพรวม component + จุดเข้า |
+| `architecture.md` | system diagram ระดับสูง, service boundary, data flow |
+| `backend.md` | API routes, middleware chain, service → repository mapping |
+| `frontend.md` | page tree, component hierarchy, state management flow |
+| `data.md` | ตาราง DB, relationship, migration history |
+| `dependencies.md` | external service, third-party integration, shared library |
+
+**สร้างเฉพาะไฟล์ที่ relevant** — โปรเจกต์ไม่มี frontend → ไม่ต้องมี `frontend.md`
+
+#### รูปแบบ codemap (token-lean)
+
+```markdown
+# Backend Architecture
+
+## Routes
+POST /api/users → UserController.create → UserService.create → UserRepo.insert
+GET  /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
+
+## Key Files
+src/services/user.ts (business logic, 120 lines)
+src/repos/user.ts (database access, 80 lines)
+
+## Dependencies
+- PostgreSQL (primary data store)
+- Redis (session cache, rate limiting)
+- Stripe (payment processing)
+```
+
+### Step 3: Diff detection
+- มี codemap เดิมอยู่ → คำนวณ % การเปลี่ยนแปลง
+- เปลี่ยน **> 30%** → แสดง diff + **ขอ user อนุมัติก่อนเขียนทับ**
+- เปลี่ยน **≤ 30%** → อัปเดต in place ได้เลย
+
+### Step 4: Metadata
+ใส่ freshness header บนสุดของทุกไฟล์:
+```html
+<!-- Generated: YYYY-MM-DD | Files scanned: N | Token estimate: ~X -->
+```
+
+### Step 5: Analysis report → `.reports/codemap-diff.txt`
+- ไฟล์ added / removed / modified ตั้งแต่สแกนครั้งล่าสุด
+- dependency ใหม่ที่ตรวจพบ
+- architecture changes (route ใหม่, service ใหม่ ฯลฯ)
+- คำเตือน staleness: doc ที่ไม่ถูกอัปเดต 90+ วัน
+
+---
+
+## 3. หลักการ (tips)
+
+- โฟกัสโครงสร้างระดับสูง — **ไม่ใช่** implementation detail
+- ใช้ file path + function signature แทน code block เต็ม
+- แต่ละ codemap **< 1000 tokens** เพื่อโหลดเข้า context ได้ถูก
+- ใช้ ASCII diagram แทนคำบรรยาย data flow ยืดยาว
+- **ทุกอย่างต้องมาจากโค้ดจริง ณ วันสแกน — ห้ามเดา/ห้ามเขียนจากความจำ**
+
+---
+
+## 4. Gate — จบเมื่อ
+
+- [ ] codemap ทุกไฟล์ตรงโค้ดจริง + มี freshness header
+- [ ] `index.md` ลิงก์ครบทุกไฟล์ codemap ที่มี
+- [ ] ทุกไฟล์ token-lean (< 1000 tokens)
+- [ ] diff > 30% ผ่านการอนุมัติจาก user แล้ว
+- [ ] `.reports/codemap-diff.txt` เขียนแล้ว