@warnyin/agents 0.5.0 → 0.5.2

package/warnyin/workflow/scripts/build-wave.mjs

@@ -1,107 +1,107 @@
-// build-wave — fan-out หนึ่ง sub-agent ต่อหนึ่ง task ใน "หนึ่ง wave" (task ที่ independent กัน)
-// main loop (BUILD command) เรียก script นี้ทีละ wave ตาม dependency แล้ว integrate ระหว่าง wave
-//
-// args = {
-//   slug: string,            // ชื่อ topic เช่น "billing-redesign"
-//   tasks: string[],         // ชื่อ task ใน wave นี้ (โฟลเดอร์ warnyin/stages/<slug>/tasks/<task>)
-//   isolate?: boolean,       // true = worktree ต่อ task (ดีฟอลต์), false = shared tree (sequential)
-// }
-
-export const meta = {
-  name: 'build-wave',
-  description: 'BUILD: fan-out sub-agent ต่อ task ใน wave เดียว — implement + test/lint + commit แล้วรายงานผล',
-  phases: [{ title: 'Build wave', detail: 'parallel agent, หนึ่งตัวต่อหนึ่ง task (worktree isolation)' }],
-}
-
-const slug = args && args.slug
-const tasks = (args && args.tasks) || []
-const isolate = !(args && args.isolate === false)
-
-if (!slug || tasks.length === 0) {
-  log('ไม่มี slug หรือ tasks — ไม่มีอะไรให้ build')
-  return { slug: slug || null, results: [], failed: [] }
-}
-
-phase('Build wave')
-log(`Build ${tasks.length} task ของ "${slug}"${isolate ? ' · worktree isolation' : ' · shared tree'}`)
-
-const RESULT_SCHEMA = {
-  type: 'object',
-  additionalProperties: false,
-  required: ['task', 'status', 'summary'],
-  properties: {
-    task: { type: 'string', description: 'ชื่อ task' },
-    status: { enum: ['passed', 'failed'], description: 'passed ก็ต่อเมื่อ test/lint เขียวจริง' },
-    summary: { type: 'string', description: 'สรุปสั้นๆ ว่าทำอะไร' },
-    branch: { type: 'string', description: 'ชื่อ git branch ของ worktree (ถ้า isolate) ให้ main loop merge' },
-    filesChanged: { type: 'array', items: { type: 'string' } },
-    testResult: { type: 'string', description: 'ผล test-flow + build/lint' },
-    notes: { type: 'string', description: 'conflict/ข้อควรระวัง/ rule ใหม่ที่ note ไว้' },
-    troubleshooting: {
-      type: 'array',
-      description: 'ปัญหายาก/เจอซ้ำที่แก้สำเร็จ — main loop จะเขียนรวมลง topic troubleshooting.md',
-      items: {
-        type: 'object',
-        additionalProperties: false,
-        required: ['title', 'rootCause', 'solution'],
-        properties: {
-          title: { type: 'string' },
-          symptom: { type: 'string', description: 'อาการ/error message' },
-          rootCause: { type: 'string' },
-          solution: { type: 'string' },
-          prevention: { type: 'string', description: 'วิธีป้องกันไม่ให้เกิดซ้ำ' },
-        },
-      },
-    },
-  },
-}
-
-function prompt(task) {
-  const dir = `warnyin/stages/${slug}/tasks/${task}`
-  const lines = [
-    `คุณคือ build sub-agent ของ task "${task}" (vertical slice) ทำตาม playbook warnyin/workflow/stages/build.md`,
-    ``,
-    `1. อ่านให้ครบก่อนเขียนโค้ด:`,
-    `   - warnyin/workflow/roles/developer.md (role card: lens + checklist ก่อนส่งงาน — ทำตามทุกข้อ)`,
-    `   - ${dir}/task.md (เป้าหมาย + sub-tasks + dependency + acceptance)`,
-    `   - ${dir}/spec.md (API/UXUI/data-flow/user-flow/persona/test-flow)`,
-    `   - ${dir}/standard.md (pattern โค้ด, shared component — reuse ห้ามเขียนซ้ำ)`,
-    `   - ${dir}/rule.md (กฎที่ต้อง follow)`,
-    `   - ภาพรวม: warnyin/stages/${slug}/design.md, proposal.md`,
-    `   - rule/standard กลางที่อ้างถึงใน docs/techstack/<component>/`,
-    `2. Implement ให้ครบทุก sub-task แบบ vertical slice (end-to-end) ทำตาม standard.md + rule.md เคร่งครัด`,
-    `3. รัน test-flow ใน spec.md + build/lint ของ component นั้น`,
-    `4. ถ้าเจอ error/ติดปัญหา → อ่าน docs/troubleshooting.md ก่อน เผื่อเคยแก้แล้ว`,
-    `5. รายงาน status=passed เฉพาะเมื่อ test/build เขียวจริง; ถ้าแก้ไม่ได้ → status=failed พร้อมเหตุผล`,
-    `   ห้ามรายงานผ่านทั้งที่ยังแดง`,
-    `6. ห้ามแก้ไฟล์ rule/standard กลางใน docs/ (rule ใหม่ note ไว้ใน ${dir}/rule.md อยู่แล้ว รอ SHIP)`,
-    `7. อัปเดตสถานะ + acceptance ที่ผ่านใน ${dir}/task.md`,
-    `8. ปัญหาที่ "ยาก/เจอซ้ำ" และแก้สำเร็จ → ใส่ในฟิลด์ troubleshooting (main loop จะรวมลง topic troubleshooting.md)`,
-  ]
-  if (isolate) {
-    lines.push(
-      `9. คุณอยู่ใน git worktree แยก: เมื่อเสร็จและเขียวแล้ว ให้ commit งาน (git add -A && git commit -m "build(${task}): ...")`,
-      `   แล้วรายงานชื่อ branch (git rev-parse --abbrev-ref HEAD) ในฟิลด์ branch เพื่อให้ main loop merge`,
-    )
-  } else {
-    lines.push(`9. (shared tree) อย่า commit เอง — main loop จะ commit ให้หลังตรวจ`)
-  }
-  lines.push(``, `คืนผลตาม schema.`)
-  return lines.join('\n')
-}
-
-const results = await parallel(
-  tasks.map((task) => () =>
-    agent(prompt(task), isolate
-      ? { label: `build:${task}`, schema: RESULT_SCHEMA, isolation: 'worktree' }
-      : { label: `build:${task}`, schema: RESULT_SCHEMA })
-  )
-)
-
-const clean = results.filter(Boolean)
-const failed = clean.filter((r) => r.status === 'failed').map((r) => r.task)
-const skipped = tasks.filter((t) => !clean.some((r) => r.task === t))
-
-log(`เสร็จ ${clean.length}/${tasks.length} · ผ่าน ${clean.length - failed.length} · ล้ม ${failed.length}${skipped.length ? ` · ข้าม ${skipped.length}` : ''}`)
-
-return { slug, results: clean, failed, skipped }
+// build-wave — fan-out หนึ่ง sub-agent ต่อหนึ่ง task ใน "หนึ่ง wave" (task ที่ independent กัน)
+// main loop (BUILD command) เรียก script นี้ทีละ wave ตาม dependency แล้ว integrate ระหว่าง wave
+//
+// args = {
+//   slug: string,            // ชื่อ topic เช่น "billing-redesign"
+//   tasks: string[],         // ชื่อ task ใน wave นี้ (โฟลเดอร์ warnyin/stages/<slug>/tasks/<task>)
+//   isolate?: boolean,       // true = worktree ต่อ task (ดีฟอลต์), false = shared tree (sequential)
+// }
+
+export const meta = {
+  name: 'build-wave',
+  description: 'BUILD: fan-out sub-agent ต่อ task ใน wave เดียว — implement + test/lint + commit แล้วรายงานผล',
+  phases: [{ title: 'Build wave', detail: 'parallel agent, หนึ่งตัวต่อหนึ่ง task (worktree isolation)' }],
+}
+
+const slug = args && args.slug
+const tasks = (args && args.tasks) || []
+const isolate = !(args && args.isolate === false)
+
+if (!slug || tasks.length === 0) {
+  log('ไม่มี slug หรือ tasks — ไม่มีอะไรให้ build')
+  return { slug: slug || null, results: [], failed: [] }
+}
+
+phase('Build wave')
+log(`Build ${tasks.length} task ของ "${slug}"${isolate ? ' · worktree isolation' : ' · shared tree'}`)
+
+const RESULT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['task', 'status', 'summary'],
+  properties: {
+    task: { type: 'string', description: 'ชื่อ task' },
+    status: { enum: ['passed', 'failed'], description: 'passed ก็ต่อเมื่อ test/lint เขียวจริง' },
+    summary: { type: 'string', description: 'สรุปสั้นๆ ว่าทำอะไร' },
+    branch: { type: 'string', description: 'ชื่อ git branch ของ worktree (ถ้า isolate) ให้ main loop merge' },
+    filesChanged: { type: 'array', items: { type: 'string' } },
+    testResult: { type: 'string', description: 'ผล test-flow + build/lint' },
+    notes: { type: 'string', description: 'conflict/ข้อควรระวัง/ rule ใหม่ที่ note ไว้' },
+    troubleshooting: {
+      type: 'array',
+      description: 'ปัญหายาก/เจอซ้ำที่แก้สำเร็จ — main loop จะเขียนรวมลง topic troubleshooting.md',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['title', 'rootCause', 'solution'],
+        properties: {
+          title: { type: 'string' },
+          symptom: { type: 'string', description: 'อาการ/error message' },
+          rootCause: { type: 'string' },
+          solution: { type: 'string' },
+          prevention: { type: 'string', description: 'วิธีป้องกันไม่ให้เกิดซ้ำ' },
+        },
+      },
+    },
+  },
+}
+
+function prompt(task) {
+  const dir = `warnyin/stages/${slug}/tasks/${task}`
+  const lines = [
+    `คุณคือ build sub-agent ของ task "${task}" (vertical slice) ทำตาม playbook warnyin/workflow/stages/build.md`,
+    ``,
+    `1. อ่านให้ครบก่อนเขียนโค้ด:`,
+    `   - warnyin/workflow/roles/developer.md (role card: lens + checklist ก่อนส่งงาน — ทำตามทุกข้อ)`,
+    `   - ${dir}/task.md (เป้าหมาย + sub-tasks + dependency + acceptance)`,
+    `   - ${dir}/spec.md (API/UXUI/data-flow/user-flow/persona/test-flow)`,
+    `   - ${dir}/standard.md (pattern โค้ด, shared component — reuse ห้ามเขียนซ้ำ)`,
+    `   - ${dir}/rule.md (กฎที่ต้อง follow)`,
+    `   - ภาพรวม: warnyin/stages/${slug}/design.md, proposal.md`,
+    `   - rule/standard กลางที่อ้างถึงใน docs/techstack/<component>/`,
+    `2. Implement ให้ครบทุก sub-task แบบ vertical slice (end-to-end) ทำตาม standard.md + rule.md เคร่งครัด`,
+    `3. รัน test-flow ใน spec.md + build/lint ของ component นั้น`,
+    `4. ถ้าเจอ error/ติดปัญหา → อ่าน docs/troubleshooting.md ก่อน เผื่อเคยแก้แล้ว`,
+    `5. รายงาน status=passed เฉพาะเมื่อ test/build เขียวจริง; ถ้าแก้ไม่ได้ → status=failed พร้อมเหตุผล`,
+    `   ห้ามรายงานผ่านทั้งที่ยังแดง`,
+    `6. ห้ามแก้ไฟล์ rule/standard กลางใน docs/ (rule ใหม่ note ไว้ใน ${dir}/rule.md อยู่แล้ว รอ SHIP)`,
+    `7. อัปเดตสถานะ + acceptance ที่ผ่านใน ${dir}/task.md`,
+    `8. ปัญหาที่ "ยาก/เจอซ้ำ" และแก้สำเร็จ → ใส่ในฟิลด์ troubleshooting (main loop จะรวมลง topic troubleshooting.md)`,
+  ]
+  if (isolate) {
+    lines.push(
+      `9. คุณอยู่ใน git worktree แยก: เมื่อเสร็จและเขียวแล้ว ให้ commit งาน (git add -A && git commit -m "build(${task}): ...")`,
+      `   แล้วรายงานชื่อ branch (git rev-parse --abbrev-ref HEAD) ในฟิลด์ branch เพื่อให้ main loop merge`,
+    )
+  } else {
+    lines.push(`9. (shared tree) อย่า commit เอง — main loop จะ commit ให้หลังตรวจ`)
+  }
+  lines.push(``, `คืนผลตาม schema.`)
+  return lines.join('\n')
+}
+
+const results = await parallel(
+  tasks.map((task) => () =>
+    agent(prompt(task), isolate
+      ? { label: `build:${task}`, schema: RESULT_SCHEMA, isolation: 'worktree' }
+      : { label: `build:${task}`, schema: RESULT_SCHEMA })
+  )
+)
+
+const clean = results.filter(Boolean)
+const failed = clean.filter((r) => r.status === 'failed').map((r) => r.task)
+const skipped = tasks.filter((t) => !clean.some((r) => r.task === t))
+
+log(`เสร็จ ${clean.length}/${tasks.length} · ผ่าน ${clean.length - failed.length} · ล้ม ${failed.length}${skipped.length ? ` · ข้าม ${skipped.length}` : ''}`)
+
+return { slug, results: clean, failed, skipped }

package/warnyin/workflow/stages/build.md

@@ -1,94 +1,94 @@
-# Stage: BUILD
-
-> **Playbook กลาง — AI ทุกเจ้าทำตามไฟล์นี้ชุดเดียวกัน** (Claude Code / Codex / Antigravity / อื่นๆ)
-> เป้าหมาย: ลงมือทำ task ที่ DESIGN เตรียมไว้ โดย **fan-out sub-agent อัตโนมัติต่อ task ตาม dependency**
-
----
-
-## 1. BUILD คืออะไร / ใช้เมื่อไหร่
-
-ใช้เมื่อ DESIGN ผ่าน Gate แล้ว มี `tasks/<task>/` ครบ (task.md + spec.md + standard.md + rule.md)
-BUILD จะ **orchestrate การ implement** โดยกระจายงานเป็น sub-agent หนึ่งตัวต่อหนึ่ง task/slice และเดินตาม dependency graph
-
----
-
-## 2. Input ที่ต้องอ่านก่อนเริ่ม
-
-1. `warnyin/stages/<slug>/design.md` — dependency graph ระหว่าง task/slice (section 7)
-2. `warnyin/stages/<slug>/proposal.md` — scope ของ change
-3. `warnyin/stages/<slug>/tasks/<task>/task.md` ทุกใบ — dependency ของแต่ละ task + sub-tasks
-4. `docs/techstack/<component>/rule.md` + `standard.md` — กฎ/มาตรฐานที่ต้อง follow
-
----
-
-## 3. หลักการทำงาน (operating principles)
-
-1. **ถาม user ยืนยัน "ครั้งเดียวก่อนเริ่ม"** — แสดง execution plan (DAG + wave ไหนรัน parallel + isolation) ให้ user อนุมัติ แล้วจึง fan-out อัตโนมัติ ไม่ถามซ้ำระหว่างทาง
-2. **Fan-out ตาม dependency (wave-based)** — จัด task เป็น "wave" ตาม topological order ของ dependency:
-   - task ใน wave เดียวกัน = independent → รัน **parallel**
-   - ข้าม wave = มี dependency → wave ถัดไปเริ่มหลัง wave ก่อนหน้ารวมผลเสร็จ
-3. **Worktree isolation ต่อ task** — แต่ละ parallel task ทำใน git worktree ของตัวเอง ไม่แก้ไฟล์ชนกัน แล้ว **integrate (merge) เข้า build branch หลังจบแต่ละ wave**
-   - ถ้า target ไม่ใช่ git repo → fallback เป็น **sequential shared-tree** (ทีละ task ตาม dependency)
-4. **แต่ละ build agent ต้อง self-verify** — implement → รัน test-flow ใน `spec.md` + build/lint → **ต้องผ่านก่อนถึง mark passed**; ถ้าแก้ไม่ได้ให้รายงาน `failed` พร้อมเหตุผล **ห้ามรายงานผ่านทั้งที่ยังแดง**
-5. **เคารพ standard/rule ของ task** — ทำตาม `standard.md` (pattern โค้ด, reuse shared component) และ `rule.md` (กฎ) อย่างเคร่งครัด
-6. **ห้ามแตะ rule/standard กลางใน `docs/`** — rule ใหม่ที่เสนอถูก note ไว้ใน `tasks/<task>/rule.md` แล้ว รอ SHIP ค่อยอัปเดตไฟล์กลาง
-7. **fail = หยุดที่ wave นั้น** — ถ้า task ใน wave ล้ม ให้รายงาน user ก่อนไป wave ถัดไป (เพราะ wave ถัดไปอาจ depend อยู่)
-8. **★ ปิดท้ายด้วย full build + full test เสมอ** — หลัง merge ทุก wave แล้ว ต้องรัน build ทั้งหมด + test suite ทั้งหมด (รวม unit test) บน build branch ที่ integrate; **แก้วนจนเขียวหมด** ก่อนปิด BUILD (กันกรณี task รายเดี่ยวเขียวแต่พอรวมกันแล้วพัง)
-9. **ทุก build agent สวม role Developer** — ทำตาม role card `warnyin/workflow/roles/developer.md` (lens + checklist ก่อนส่งงาน) — build-wave.mjs ใส่ให้ใน prompt แล้ว
-10. **★ ใช้ Troubleshooting KB** — เจอปัญหา/error ระหว่าง build ให้ **อ่าน `docs/troubleshooting.md` ก่อนเสมอ** เผื่อเคยแก้แล้ว; เมื่อแก้ปัญหาที่ **ยาก/เจอซ้ำ** สำเร็จ ให้บันทึก entry ลง `warnyin/stages/<slug>/troubleshooting.md` (ปัญหา/อาการ/root cause/วิธีแก้/ป้องกันซ้ำ) — ตอน SHIP จะยกขึ้น KB กลาง
-
----
-
-## 4. ลำดับขั้นการทำงาน (orchestration)
-
-> ผู้ orchestrate คือ AI ตัวหลัก (main loop) — sub-agent คือคนลงมือ implement
-
-0. **★ เช็ค context window ก่อนเริ่ม:** ประเมินว่า context ของ session ปัจจุบันถูกใช้ไปมากน้อยแค่ไหน — ถ้าใช้ไปเยอะหรือ **เกินครึ่ง** → **เสนอ user ให้ `/compact` หรือ `/clear` ก่อนเสมอ** แล้วค่อยเริ่ม BUILD ใน context ที่โล่ง (สถานะงานอยู่ในไฟล์ `warnyin/stages/<slug>/` ครบ ไม่หายไปกับ context) — BUILD เป็นงานยาว ต้องมี context เหลือมากพอ; เครื่องอื่นที่ไม่มีคำสั่งนี้ → แนะนำเริ่ม session ใหม่
-1. **อ่าน task ทั้งหมด** → ดึง dependency ของแต่ละ task จาก `task.md` (section 2) + `design.md` (section 7)
-2. **สร้าง DAG + จัด wave** (topological sort): wave 1 = task ที่ไม่มี dependency, wave 2 = task ที่ depend เฉพาะ wave 1, ...
-3. **Pre-check:** target เป็น git repo ไหม (สำหรับ worktree) — ถ้าไม่ใช่ → fallback sequential shared-tree และแจ้ง user
-4. **เสนอ execution plan + ขออนุมัติ (ครั้งเดียว):** แสดง wave / task ในแต่ละ wave / อันไหน parallel / isolation mode → ถาม user go/no-go
-5. **เดินทีละ wave:**
-   - fan-out sub-agent ของ task ใน wave นั้น (parallel, worktree isolation) ผ่าน **Workflow** (`warnyin/workflow/scripts/build-wave.mjs`)
-   - แต่ละ agent: implement → test/lint → commit (ถ้า worktree) → รายงานผลแบบ structured (status, files, branch, test result)
-   - **integrate:** main loop merge worktree branch ของ wave นั้นเข้า build branch (ทีละอันเพื่อเลี่ยง conflict); ถ้า conflict → แก้/รายงาน
-   - ถ้ามี task `failed` → หยุด รายงาน user
-6. **★ Full build & test gate (หลังทุก wave merge เสร็จ):** บน build branch ที่ integrate แล้ว รัน **build ทั้งหมด + test suite ทั้งหมด (รวม unit test)** ของทุก component ที่กระทบ
-   - มี error / test แดง → **แก้จนเขียวหมด (loop)** อาจ delegate fix ให้ sub-agent ทีละจุด แล้ว rerun ใหม่
-   - **ห้ามปิด BUILD ถ้ายังมี build error หรือ test ตัวใดแดง**
-   - ถ้าวนแก้หลายรอบยังไม่ผ่าน → หยุด รายงาน user พร้อม log error
-7. **ปิดงาน:** อัปเดต `build.md` (รายงานผลต่อ task + ผล full build/test) + สถานะใน `task.md` แต่ละใบ → เสนอเข้า VERIFY ด้วย `/warnyin:verify`
-
----
-
-## 5. Output
-
-| ไฟล์ | เนื้อหา |
-|---|---|
-| โค้ดจริงใน target repo | การ implement ของแต่ละ task (merge เข้า build branch) |
-| `warnyin/stages/<slug>/build.md` | รายงานผล build: สถานะ/ผล test/ไฟล์ที่แก้ ต่อ task + integration notes |
-| `warnyin/stages/<slug>/troubleshooting.md` | ปัญหายาก/ซ้ำที่แก้สำเร็จ (SHIP ยกขึ้น `docs/troubleshooting.md`) |
-| `tasks/<task>/task.md` (อัปเดต) | สถานะ task → เสร็จ + acceptance ที่ผ่าน |
-
----
-
-## 6. Workflow script (Claude Code)
-
-ใช้ `warnyin/workflow/scripts/build-wave.mjs` — fan-out หนึ่ง agent ต่อหนึ่ง task ใน **หนึ่ง wave** (parallel, worktree isolation), คืนผลแบบ structured
-main loop เรียก script นี้ **ทีละ wave** แล้ว integrate ระหว่าง wave (ดูรายละเอียดใน `.claude/commands/warnyin/build.md`)
-
-> เครื่องอื่น (Codex/Antigravity) ที่ไม่มี Workflow tool: ทำตามหลักการข้อ 3-4 โดย implement task ตามลำดับ wave เอง (parallel เท่าที่เครื่องรองรับ)
-
----
-
-## 7. Gate → เข้า VERIFY ได้เมื่อ
-
-- [ ] ทุก task ใน DAG ถูก implement และ merge เข้า build branch แล้ว
-- [ ] ทุก task รายงาน `passed` (test-flow + build/lint เขียว) — ไม่มี `failed` ค้าง
-- [ ] ไม่มี merge conflict ค้าง
-- [ ] **★ Full build ของทุก component ผ่าน — ไม่มี build error**
-- [ ] **★ test suite ทั้งหมด (รวม unit test) เขียวทั้งหมดบน build branch**
-- [ ] `build.md` สรุปผลครบทุก task + ผล full build/test
-- [ ] ไม่มีการแตะ rule/standard กลางใน `docs/` (rule ใหม่ยัง note รอ SHIP)
-
-ยังไม่ครบ → อยู่ BUILD ต่อ ห้ามข้ามไป VERIFY
+# Stage: BUILD
+
+> **Playbook กลาง — AI ทุกเจ้าทำตามไฟล์นี้ชุดเดียวกัน** (Claude Code / Codex / Antigravity / อื่นๆ)
+> เป้าหมาย: ลงมือทำ task ที่ DESIGN เตรียมไว้ โดย **fan-out sub-agent อัตโนมัติต่อ task ตาม dependency**
+
+---
+
+## 1. BUILD คืออะไร / ใช้เมื่อไหร่
+
+ใช้เมื่อ DESIGN ผ่าน Gate แล้ว มี `tasks/<task>/` ครบ (task.md + spec.md + standard.md + rule.md)
+BUILD จะ **orchestrate การ implement** โดยกระจายงานเป็น sub-agent หนึ่งตัวต่อหนึ่ง task/slice และเดินตาม dependency graph
+
+---
+
+## 2. Input ที่ต้องอ่านก่อนเริ่ม
+
+1. `warnyin/stages/<slug>/design.md` — dependency graph ระหว่าง task/slice (section 7)
+2. `warnyin/stages/<slug>/proposal.md` — scope ของ change
+3. `warnyin/stages/<slug>/tasks/<task>/task.md` ทุกใบ — dependency ของแต่ละ task + sub-tasks
+4. `docs/techstack/<component>/rule.md` + `standard.md` — กฎ/มาตรฐานที่ต้อง follow
+
+---
+
+## 3. หลักการทำงาน (operating principles)
+
+1. **ถาม user ยืนยัน "ครั้งเดียวก่อนเริ่ม"** — แสดง execution plan (DAG + wave ไหนรัน parallel + isolation) ให้ user อนุมัติ แล้วจึง fan-out อัตโนมัติ ไม่ถามซ้ำระหว่างทาง
+2. **Fan-out ตาม dependency (wave-based)** — จัด task เป็น "wave" ตาม topological order ของ dependency:
+   - task ใน wave เดียวกัน = independent → รัน **parallel**
+   - ข้าม wave = มี dependency → wave ถัดไปเริ่มหลัง wave ก่อนหน้ารวมผลเสร็จ
+3. **Worktree isolation ต่อ task** — แต่ละ parallel task ทำใน git worktree ของตัวเอง ไม่แก้ไฟล์ชนกัน แล้ว **integrate (merge) เข้า build branch หลังจบแต่ละ wave**
+   - ถ้า target ไม่ใช่ git repo → fallback เป็น **sequential shared-tree** (ทีละ task ตาม dependency)
+4. **แต่ละ build agent ต้อง self-verify** — implement → รัน test-flow ใน `spec.md` + build/lint → **ต้องผ่านก่อนถึง mark passed**; ถ้าแก้ไม่ได้ให้รายงาน `failed` พร้อมเหตุผล **ห้ามรายงานผ่านทั้งที่ยังแดง**
+5. **เคารพ standard/rule ของ task** — ทำตาม `standard.md` (pattern โค้ด, reuse shared component) และ `rule.md` (กฎ) อย่างเคร่งครัด
+6. **ห้ามแตะ rule/standard กลางใน `docs/`** — rule ใหม่ที่เสนอถูก note ไว้ใน `tasks/<task>/rule.md` แล้ว รอ SHIP ค่อยอัปเดตไฟล์กลาง
+7. **fail = หยุดที่ wave นั้น** — ถ้า task ใน wave ล้ม ให้รายงาน user ก่อนไป wave ถัดไป (เพราะ wave ถัดไปอาจ depend อยู่)
+8. **★ ปิดท้ายด้วย full build + full test เสมอ** — หลัง merge ทุก wave แล้ว ต้องรัน build ทั้งหมด + test suite ทั้งหมด (รวม unit test) บน build branch ที่ integrate; **แก้วนจนเขียวหมด** ก่อนปิด BUILD (กันกรณี task รายเดี่ยวเขียวแต่พอรวมกันแล้วพัง)
+9. **ทุก build agent สวม role Developer** — ทำตาม role card `warnyin/workflow/roles/developer.md` (lens + checklist ก่อนส่งงาน) — build-wave.mjs ใส่ให้ใน prompt แล้ว
+10. **★ ใช้ Troubleshooting KB** — เจอปัญหา/error ระหว่าง build ให้ **อ่าน `docs/troubleshooting.md` ก่อนเสมอ** เผื่อเคยแก้แล้ว; เมื่อแก้ปัญหาที่ **ยาก/เจอซ้ำ** สำเร็จ ให้บันทึก entry ลง `warnyin/stages/<slug>/troubleshooting.md` (ปัญหา/อาการ/root cause/วิธีแก้/ป้องกันซ้ำ) — ตอน SHIP จะยกขึ้น KB กลาง
+
+---
+
+## 4. ลำดับขั้นการทำงาน (orchestration)
+
+> ผู้ orchestrate คือ AI ตัวหลัก (main loop) — sub-agent คือคนลงมือ implement
+
+0. **★ เช็ค context window ก่อนเริ่ม:** ประเมินว่า context ของ session ปัจจุบันถูกใช้ไปมากน้อยแค่ไหน — ถ้าใช้ไปเยอะหรือ **เกินครึ่ง** → **เสนอ user ให้ `/compact` หรือ `/clear` ก่อนเสมอ** แล้วค่อยเริ่ม BUILD ใน context ที่โล่ง (สถานะงานอยู่ในไฟล์ `warnyin/stages/<slug>/` ครบ ไม่หายไปกับ context) — BUILD เป็นงานยาว ต้องมี context เหลือมากพอ; เครื่องอื่นที่ไม่มีคำสั่งนี้ → แนะนำเริ่ม session ใหม่
+1. **อ่าน task ทั้งหมด** → ดึง dependency ของแต่ละ task จาก `task.md` (section 2) + `design.md` (section 7)
+2. **สร้าง DAG + จัด wave** (topological sort): wave 1 = task ที่ไม่มี dependency, wave 2 = task ที่ depend เฉพาะ wave 1, ...
+3. **Pre-check:** target เป็น git repo ไหม (สำหรับ worktree) — ถ้าไม่ใช่ → fallback sequential shared-tree และแจ้ง user
+4. **เสนอ execution plan + ขออนุมัติ (ครั้งเดียว):** แสดง wave / task ในแต่ละ wave / อันไหน parallel / isolation mode → ถาม user go/no-go
+5. **เดินทีละ wave:**
+   - fan-out sub-agent ของ task ใน wave นั้น (parallel, worktree isolation) ผ่าน **Workflow** (`warnyin/workflow/scripts/build-wave.mjs`)
+   - แต่ละ agent: implement → test/lint → commit (ถ้า worktree) → รายงานผลแบบ structured (status, files, branch, test result)
+   - **integrate:** main loop merge worktree branch ของ wave นั้นเข้า build branch (ทีละอันเพื่อเลี่ยง conflict); ถ้า conflict → แก้/รายงาน
+   - ถ้ามี task `failed` → หยุด รายงาน user
+6. **★ Full build & test gate (หลังทุก wave merge เสร็จ):** บน build branch ที่ integrate แล้ว รัน **build ทั้งหมด + test suite ทั้งหมด (รวม unit test)** ของทุก component ที่กระทบ
+   - มี error / test แดง → **แก้จนเขียวหมด (loop)** อาจ delegate fix ให้ sub-agent ทีละจุด แล้ว rerun ใหม่
+   - **ห้ามปิด BUILD ถ้ายังมี build error หรือ test ตัวใดแดง**
+   - ถ้าวนแก้หลายรอบยังไม่ผ่าน → หยุด รายงาน user พร้อม log error
+7. **ปิดงาน:** อัปเดต `build.md` (รายงานผลต่อ task + ผล full build/test) + สถานะใน `task.md` แต่ละใบ → เสนอเข้า VERIFY ด้วย `/warnyin:verify`
+
+---
+
+## 5. Output
+
+| ไฟล์ | เนื้อหา |
+|---|---|
+| โค้ดจริงใน target repo | การ implement ของแต่ละ task (merge เข้า build branch) |
+| `warnyin/stages/<slug>/build.md` | รายงานผล build: สถานะ/ผล test/ไฟล์ที่แก้ ต่อ task + integration notes |
+| `warnyin/stages/<slug>/troubleshooting.md` | ปัญหายาก/ซ้ำที่แก้สำเร็จ (SHIP ยกขึ้น `docs/troubleshooting.md`) |
+| `tasks/<task>/task.md` (อัปเดต) | สถานะ task → เสร็จ + acceptance ที่ผ่าน |
+
+---
+
+## 6. Workflow script (Claude Code)
+
+ใช้ `warnyin/workflow/scripts/build-wave.mjs` — fan-out หนึ่ง agent ต่อหนึ่ง task ใน **หนึ่ง wave** (parallel, worktree isolation), คืนผลแบบ structured
+main loop เรียก script นี้ **ทีละ wave** แล้ว integrate ระหว่าง wave (ดูรายละเอียดใน `.claude/commands/warnyin/build.md`)
+
+> เครื่องอื่น (Codex/Antigravity) ที่ไม่มี Workflow tool: ทำตามหลักการข้อ 3-4 โดย implement task ตามลำดับ wave เอง (parallel เท่าที่เครื่องรองรับ)
+
+---
+
+## 7. Gate → เข้า VERIFY ได้เมื่อ
+
+- [ ] ทุก task ใน DAG ถูก implement และ merge เข้า build branch แล้ว
+- [ ] ทุก task รายงาน `passed` (test-flow + build/lint เขียว) — ไม่มี `failed` ค้าง
+- [ ] ไม่มี merge conflict ค้าง
+- [ ] **★ Full build ของทุก component ผ่าน — ไม่มี build error**
+- [ ] **★ test suite ทั้งหมด (รวม unit test) เขียวทั้งหมดบน build branch**
+- [ ] `build.md` สรุปผลครบทุก task + ผล full build/test
+- [ ] ไม่มีการแตะ rule/standard กลางใน `docs/` (rule ใหม่ยัง note รอ SHIP)
+
+ยังไม่ครบ → อยู่ BUILD ต่อ ห้ามข้ามไป VERIFY