@jakkrichm/create-nexus-devflow 2.17.5 → 2.17.7

package/template/devflow/context/coding-standards.md

@@ -203,7 +203,7 @@ Testing is a core quality gate in Nexus-DevFlow, not an afterthought:
 
 ## 12. HTML Documentation & Theming Standards (Light Theme Mandate)
 
-All generated HTML artifacts across the framework (Contextual Help Playbooks `devflow/docs/playbooks/{skill}.html`, Standalone Reports `report-html`, Architecture & Workflow Diagrams `archify` / `diagram-design`, and UI Prototypes/Mockups) MUST strictly adhere to the **Paper/Ink Light Theme Design System**:
+All generated HTML artifacts across the framework (Contextual Help Playbooks `devflow/reference/playbooks/{skill}.html`, Standalone Reports `report-html`, Architecture & Workflow Diagrams `archify` / `diagram-design`, and UI Prototypes/Mockups) MUST strictly adhere to the **Paper/Ink Light Theme Design System**:
 
 - **Mandatory Default `data-theme="light"`**:
   - All HTML documents must start with `<html lang="th" data-theme="light">`.
@@ -245,6 +245,66 @@ All generated HTML artifacts across the framework (Contextual Help Playbooks `de
   - Fonts: Google Sans (`'Google Sans'`, `'Google Sans Text'`) for display headers and body text, `'JetBrains Mono'` for code and monospaced data.
   - Full support for `prefers-reduced-motion: reduce` and clear `:focus-visible` outlines.
 - **Master Reference Template**:
-  - Refer to `devflow/docs/playbooks/template.html` as the authoritative, reusable component reference for all playbook and HTML documentation generation.
+  - Refer to `devflow/reference/playbooks/template.html` as the authoritative, reusable component reference for all playbook and HTML documentation generation.
 
+---
+
+## 13. Prompt Token Economy & Mechanical Input Coverage Standards
+
+- **Skill Byte Budgets & Prompt Hygiene**:
+  - **Size Ceilings**: `SKILL.md` must not exceed **32 KB**, support/reference markdown files must not exceed **24 KB**, and frontmatter `description` must not exceed **400 characters**.
+  - **Every Line Must Earn Its Keep**: If an agent naturally behaves correctly by default, avoid adding redundant prose. Instruct directly without philosophical justification.
+  - **Completion Summaries (Lead with Essentials)**:
+    - **Headline**: One-line summary of what was accomplished.
+    - **Next**: Exactly one next recommended command or action.
+    - **Heads up**: Active blockers, decision debt, or critical items needing user attention (omitted when empty).
+    - **Pointer**: Link to the detailed artifact rather than repeating large text blocks.
+    - **No Checklist Spam**: Avoid dumping lists of obvious successes (`Semantic HTML: OK`, `Keyboard: OK`).
+- **Mechanical Input Coverage Principle (Anti-Hallucination Gate)**:
+  - Before implementation, enumerate all values and states that the code must produce or display.
+  - Each value must have an explicitly named source (Database column, Input argument, Calculated derivation, or Settled architectural decision).
+  - Any required value lacking a named source represents an **Owed Decision**; agents are prohibited from making unrecorded architectural choices or guessing implementations under the guise of "just wiring". Stop and route to `/grill` or request user clarification.
+
+---
+
+## 14. Architectural Slicing & Assumed Decision Governance
+
+- **4 Slicing Archetypes Framework (`devflow/reference/slicing-archetypes.md`)**:
+  - When decomposing large roadmaps or splitting oversized features, select from the 4 standard archetypes:
+    - **Skateboard**: Minimal functional loop (prove core logic end-to-end with minimal UI).
+    - **Facade**: Rich UI/DX with mock backend (validate user flow & interaction first).
+    - **Tracer Bullet**: Deep vertical slice across all layers (DB -> API -> UI) for 1 happy path.
+    - **Journey**: Slice along natural user workflow milestones.
+  - Avoid purely technical layer slicing (e.g. DB only or backend only) that leaves work unverifiable in a single delivery run.
+- **Assumed Decision Debt Lifecycle (`Status: Assumed`)**:
+  - For fast-tracking development when user confirmation is pending, record decisions in ADRs (`devflow/decisions/`) with `Status: Assumed`.
+  - Every assumed decision MUST specify `Assumption`, `Risk Level & Blast Radius`, and `Ratification Plan`.
+  - Untracked architectural assumptions are strictly prohibited.
+
+---
+
+## 15. Test File Classification & AC Traceability Standards
+
+- **5-Tier Test Classification**:
+  - **Tier 1: Pure Logic & Algorithms** (`src/utils/`, `services/`, `lib/`): Fast in-memory Unit Tests, 100% boundary & edge cases coverage. Use TDD.
+  - **Tier 2: UI Components** (`src/components/`, `src/pages/`): Component mounting & event interaction, visual verification via Playwright / BrowserOS Neo. Prohibit trivial unit tests for static HTML markup.
+  - **Tier 3: API & Data Integration** (`src/api/`, route handlers, DB models): Contract tests, schema validation (Zod), status codes, payload shapes.
+  - **Tier 4: Config & Build Tooling** (`*.json`, `*.yaml`, `scripts/`): Static contract validation (`npm run check:static`), budget linters (`npm run check:budgets`), smoke tests.
+  - **Tier 5: Documentation & Prose** (`*.md`, `docs/`, `scripts/data/`): Structural checks, markdown contract scans, link integrity verification.
+- **Acceptance Criteria (`AC-N`) Traceability**:
+  - All automated test suites and assertion descriptions must explicitly include the target Acceptance Criterion tag (e.g. `it('AC-1: ...')`).
+  - During `/check`, verify that 100% of defined acceptance criteria in the active living spec have matching passing empirical proof.
+
+---
 
+## 16. Token Economy & Cost Optimization Standards
+
+- **Token Economics Visibility**:
+  - Leverage `npm run analyze:tokens` (or `scripts/analyze-token-usage.ts`) to audit session token usage across Main Thread vs Subagents.
+  - Track the 4 token dimensions: **Fresh Input Tokens**, **Prompt Cache Write Tokens**, **Prompt Cache Read Tokens (Hits)**, and **Output Tokens**.
+- **Prompt Caching Optimization**:
+  - Structure documentation and context files with immutable headers first so LLM providers can achieve high prompt cache hit rates (>60%).
+  - Ensure living specs and references stay compact (under byte budgets) to prevent prompt cache misses and unnecessary token churn.
+- **Cost Metrics & Savings**:
+  - Track estimated model costs (USD) against model pricing catalogs (Claude 3.7/3.5 Sonnet, Gemini 2.5 Pro/Flash, GPT-4o).
+  - Aim for >50% cost savings through effective prompt caching reuse.

package/template/devflow/context/glossary.md

@@ -29,3 +29,23 @@
 - **Definition**: สรุปผลการเปลี่ยนแปลง, บทเรียนที่ได้รับ (Lessons Learned), และการตัดสินใจสำคัญที่บันทึกไว้ในตอนปิดรอบการพัฒนา
 - **Constraints**: บันทึกอัตโนมัติใน Living Spec ก่อนที่จะทำการ Squash Merge และ Archive
 - **Aliases / Related**: Delivery Digest, Retrospective Log
+
+### 4 Slicing Archetypes
+- **Definition**: รูปแบบมาตรฐาน 4 ประการในการแบ่งย่อยฟีเจอร์ (Skateboard, Facade, Tracer Bullet, Journey) เพื่อให้ได้รอบการส่งมอบที่เล็ก ทดสอบได้จริง และไม่ติดขัด Technical Layer Dependency
+- **Constraints**: ใช้งานใน `/discovery`, `/brainstorm`, และ `/feature` (Step 2)
+- **Aliases / Related**: `slicing-archetypes.md`, Feature Decomposition, Slicing Strategy
+
+### Assumed Decision Debt
+- **Definition**: หนี้การตัดสินใจที่เกิดขึ้นจากการตั้งสมมติฐานทางสถาปัตยกรรมชั่วคราว (`Status: Assumed` ใน ADR) เพื่อให้การพัฒนาเดินหน้าได้อย่างรวดเร็ว (Fast-track) โดยไม่สะดุด
+- **Constraints**: ต้องระบุ Assumption, Risk Level, และ Ratification Plan กำกับเสมอ และต้องได้รับการตรวจทาน/ยืนยัน (Ratified) ก่อนปล่อยสู่ Production
+- **Aliases / Related**: Assumed ADR, Decision Debt, Fast-track Assumption
+
+### AC-to-Test Traceability Matrix
+- **Definition**: ตารางเชื่อมโยงระหว่างข้อกำหนด Acceptance Criteria (`AC-N`) ใน Living Spec กับ Automated Test Cases และหลักฐานเชิงประจักษ์ เพื่อให้มั่นใจว่าทุกข้อกำหนดได้รับการทดสอบและพิสูจน์จริงแบบ 1-to-1
+- **Constraints**: ใช้ระบุใน Living Spec (`spec.md`), ตรวจทานใน `/check`, และกำกับด้วย `AC-N` Tag ในโค้ดทดสอบ
+- **Aliases / Related**: Traceability Matrix, AC Mapping, Spec Verification Trace
+
+### Prompt Caching Rate & Billed-Equivalent Cost
+- **Definition**: ดัชนีวัดประสิทธิภาพการใช้ Token ของ AI Coding Agent โดยแยกแยะระหว่าง Fresh Input Tokens, Cache Creation (Write), Cache Read (Prompt Caching Hits), และ Output Tokens เพื่อคำนวณต้นทุนจริง (USD) และ % ส่วนลดที่ประหยัดได้จาก Prompt Caching
+- **Constraints**: วิเคราะห์ผ่าน `scripts/analyze-token-usage.ts` และคำสั่ง `npm run analyze:tokens`
+- **Aliases / Related**: Token Economics, Cost Units, Cache Hit Rate

package/template/devflow/decisions/README.md

@@ -11,10 +11,14 @@ Each ADR is named `ADR-xxx-{slug}.md` (e.g. `ADR-001-database-schema-migration.m
 ```markdown
 # ADR-xxx: {Title}
 
-- **Status**: Accepted | Proposed | Deprecated | Superseded by ADR-yyy
+- **Status**: `Accepted` | `Proposed` | `Assumed` (Fast-tracked Assumption) | `Deprecated` | `Superseded by ADR-yyy`
 - **Date**: YYYY-MM-DD
 - **Context**: Problem statement, background, and why this decision was needed.
 - **Decision**: The selected architectural approach or invariant.
+- **Assumption Metadata** *(Mandatory when Status is `Assumed`)*:
+  - **Assumption**: ข้อสมมติฐานทางเทคนิคที่ตั้งขึ้นเพื่อปลดบล็อกการทำงานชั่วคราว
+  - **Risk Level & Blast Radius**: ระดับความเสี่ยงและขอบเขตผลกระทบหากข้อสมมติไม่ถูกต้อง
+  - **Ratification Plan**: เงื่อนไข, วันที่ หรือเหตุการณ์ที่จะทำการทวนสอบ (Ratify) เพื่อเปลี่ยนสถานะเป็น `Accepted` หรือ `Rejected`
 - **Alternatives Considered**:
   - *Option 1*: Pros / Cons
   - *Option 2*: Pros / Cons
@@ -22,3 +26,13 @@ Each ADR is named `ADR-xxx-{slug}.md` (e.g. `ADR-001-database-schema-migration.m
   - *Positive*: Benefits and capabilities unlocked
   - *Trade-offs / Risks*: Costs, complexity, or constraints
 ```
+
+---
+
+## ⚡ Assumed Decision Debt Policy
+
+เมื่อทีมหรือ Agent จำเป็นต้องเดินหน้าพัฒนาอย่างรวดเร็ว (Fast-track) โดยที่ข้อสรุปทางสถาปัตยกรรมยังไม่ได้รับการยืนยัน 100% จากผู้ใช้ ให้บันทึก ADR ด้วย `Status: Assumed` พร้อมกรอก **Assumption Metadata** ให้ครบถ้วน
+
+> [!WARNING]
+> **Zero Untracked Decision Debt**: ทุก ADR ที่มีสถานะ `Assumed` จะถูกตรวจสอบโดย `/audit` และ `/complete` เพื่อแจ้งเตือนให้ทีมยืนยัน (Ratify) หรือปรับแก้ก่อนส่งมอบขึ้น Production เสมอ
+

package/template/devflow/reference/feature-spec-template.md

@@ -1,110 +1,90 @@
-# [ID-slug] Feature Title
+# 📐 [{xxx-slug}] {title}
 
-> **Template Type**: Task-Isolated Living Spec
-> **Active Location**: `devflow/context/{xxx-slug}/spec.md`
-> **Archive Location**: `devflow/history/{features|fixes|rollbacks}/{ID-slug}.md`
-
-- **Feature ID**: `{xxx-slug}`
-- **Category**: `features` | `fixes` | `rollbacks`
-- **Target Branch**: `feature/{xxx-slug}`
-- **Status**: `Spec Ready` | `In-Progress` | `Verified` | `Completed`
-- **Track**: `Unified Fast-Track`
-- **Discovery Ref**: `devflow/discoveries/DISC-xxx.md` (Optional)
-- **ADR Ref**: `devflow/decisions/ADR-xxx.md` (Optional)
+> **Status**: In-Progress  
+> **Track**: Fast-Track (Task-Isolated Living Spec Mode - Feature)  
+> **Category**: Feature  
+> **Source**: `devflow/build-plan.md: Feature {n}` & `devflow/discoveries/{DISC-ID}/discovery.md`  
+> **Branch**: `feature/{xxx-slug}`  
+> **Started Date**: {YYYY-MM-DD}  
+> **Delivered Date**: TBD  
+> **Owner**: DevFlow Core Framework Team & AI  
 
 ---
 
-## 🎯 1. Define & Boundaries
+## 1. Specification & Scope
 
-### Problem Statement & Goal
-- **Problem**: อธิบายปัญหาที่พบ หรือสิ่งที่ต้องการแก้ไข/ปรับปรุง
-- **Goal**: ผลลัพธ์หรือเป้าหมายที่ต้องการให้เกิดขึ้น
+### 1.1 Problem Statement
+{Description of the problem, background, and rationale for developing this feature}
 
-### In-Scope & Out-of-Scope
-- **In-Scope**:
-  - สิ่งที่ต้องทำในรอบนี้
-- **Out-of-Scope**:
-  - สิ่งที่ไม่ทำในรอบนี้ หรือยกยอดไปทำในเฟสถัดไป
+### 1.2 In-Scope
+1. {In-scope item 1}
+2. {In-scope item 2}
 
-### Risk & Mitigation Matrix
-| Risk | Severity | Mitigation |
-| :--- | :--- | :--- |
-| ความเสี่ยงที่อาจเกิดขึ้น | Low/Medium/High | แนวทางป้องกันหรือรับมือ |
+### 1.3 Out-of-Scope
+- {Items deliberately excluded or deferred to future features}
 
-### Success Criteria
-1. เกณฑ์ชี้วัดความสำเร็จข้อที่ 1
-2. เกณฑ์ชี้วัดความสำเร็จข้อที่ 2
+### 1.4 Acceptance Criteria
+- [ ] **AC-1**: {Acceptance criterion 1}
+- [ ] **AC-2**: {Acceptance criterion 2}
 
 ---
 
-## 📐 2. Technical Spec & Contracts
-
-### Architecture & Component Design
-- อธิบายโครงสร้างหรือ Flow การทำงานของ Component/Module
+## 2. Plan & Test Strategy
 
-### Data Models & Schemas
-```typescript
-// Interface หรือ Type Definition
-```
+### 2.1 Files Modified / Created
+- `{file-path}` [NEW | MODIFY | DELETE]
 
-### API & Interface Contracts
-- **Endpoint / Function**: `methodName(params: Type): ReturnType`
-- **Error Handling**: รายละเอียด Error Codes และวิธีจัดการ
+### 2.2 Quality Gates & Sensitivity Check
+- **Quality Gate Policy (`independentReview`)**: `manual` | `always` | `when-sensitive`
+- **UI Evidence / Browser Tests**: {Not applicable | Playwright / BrowserOS Neo}
+- **Review Strategy**: One feature-level review packet at completion
 
-### Non-Functional Constraints
-- **Security**: การตรวจสอบ Input, การจัดการสิทธิ์, Secrets
-- **Performance**: ข้อจำกัดเรื่องความเร็ว หรือ Resource Usage
-
-### Acceptance Criteria (AC)
-- [ ] **AC-1**: เงื่อนไขการยอมรับข้อที่ 1
-- [ ] **AC-2**: เงื่อนไขการยอมรับข้อที่ 2
+### 2.3 Test Decision: Required (TDD) | Optional
+- **Rationale**: {Reason for requiring Unit Tests / TDD}
 
 ---
 
-## 📋 3. Execution Plan & TDD Checklist
-
-- [ ] **Task 1: Core Foundation & Types**
-  - [ ] 1.1 `[TDD-Red]` เขียน Unit Test สำหรับ Logic ส่วนที่ 1
-  - [ ] 1.2 `[TDD-Green]` Implement Logic ให้ผ่าน Test
-  - [ ] 1.3 `[TDD-Refactor]` Clean up และ Optimize โค้ด
+## 3. Implementation Checklist (Strict TDD)
 
-- [ ] **Task 2: Feature Implementation**
-  - [ ] 2.1 `[TDD-Red]` เขียน Test ครอบคลุม Edge Cases
-  - [ ] 2.2 `[TDD-Green]` Implement Feature ตาม Contract
-  - [ ] 2.3 `[TDD-Refactor]` ตรวจสอบความถูกต้องและ Architecture
+- [ ] **Task 1: {Task 1 title}**
+  - [ ] 1.1 `[TDD-Red]`: {Write failing unit or behavioral test}
+  - [ ] 1.2 `[TDD-Green]`: {Write minimal implementation to pass test}
+  - [ ] 1.3 `[TDD-Refactor]`: {Refactor and ensure 100% tests green}
 
-- [ ] **Task 3: Integration & QA Verification**
-  - [ ] 3.1 `[TDD-Green]` เชื่อมต่อ UI/API และตรวจสอบ End-to-End
+- [ ] **Task 2: {Task 2 title}**
+  - [ ] 2.1 `[TDD-Red]`: ...
+  - [ ] 2.2 `[TDD-Green]`: ...
+  - [ ] 2.3 `[TDD-Refactor]`: ...
 
 ---
 
-## ⚡ 4. Implementation Log & Evidence
+## 4. Verification Evidence Matrix
 
-*(จะถูกบันทึกและอัปเดตความคืบหน้าระหว่างรันคำสั่ง `/implement`)*
+### ⚖️ Axis 1: Standards, Architecture & Quality Gate
+- **Type Safety & Build Integrity**: TBD
+- **Automated Test Matrix**: TBD
+- **Static Contract Verification**: TBD
+- **Package Smoke Test**: TBD
+- **Findings Ledger**: Verify `findings.md` is 100% clean
 
-- **Step 1**: ...
-- **Checkpoint Commit**: `feat(scope): ...`
+### 🎯 Axis 2: Spec Fidelity & Behavioral Acceptance Gate
+- [ ] **AC-1**: {Empirical proof for AC-1}
+- [ ] **AC-2**: {Empirical proof for AC-2}
 
----
-
-## 🧪 5. Multi-Lane Verification Matrix
+### 🔗 Axis 3: AC-to-Test Traceability Matrix
 
-*(จะถูกบันทึกผลการตรวจสอบระหว่างรันคำสั่ง `/check`)*
+| Acceptance Criterion | File Tier | Automated Test Case / Assertion | Verification Command | Status |
+| :--- | :--- | :--- | :--- | :---: |
+| **AC-1** | Tier 1 (Logic) / Tier 2 (UI) | `it('AC-1: ...')` | `npm test` | ⏳ Pending |
+| **AC-2** | Tier 3 (API) / Tier 4 (Tooling) | `it('AC-2: ...')` | `npm run check:static` | ⏳ Pending |
 
-| Lane | Command / Verification Target | Result | Notes / Proof |
-| :--- | :--- | :--- | :--- |
-| **Typecheck** | `npm run typecheck` | ⏳ PENDING | |
-| **Lint** | `npm run lint` | ⏳ PENDING | |
-| **Unit Tests** | `npm test` | ⏳ PENDING | |
-| **Manual Proof** | UI / CLI Behavioral Verification | ⏳ PENDING | |
 
 ---
 
-## 📦 6. Release Digest & Retrospective
-
-*(จะถูกสรุปและบันทึกอัตโนมัติก่อนทำการ Squash Merge ในคำสั่ง `/complete`)*
+## 5. Delivery Verification & Independent Receipt
 
-- **What Changed**: สรุปสิ่งที่เปลี่ยนแปลง
-- **Key Decisions**: การตัดสินใจสำคัญระหว่างพัฒนา
-- **Lessons Learned**: บทเรียนที่ได้รับ
-- **Known Limitations**: ข้อจำกัดที่ทราบและข้อเสนอแนะในอนาคต
+- **Delivery Date**: TBD
+- **Verification Verdict**: TBD
+- **Framework Tests**: TBD
+- **Static Contract**: TBD
+- **Package Smoke Test**: TBD

package/template/devflow/reference/help-playbook-protocol.md

@@ -5,14 +5,14 @@
    - **Execution Safety Gate**: DO NOT execute the skill's primary or mutating actions (do not launch scans/attacks, do not modify source code, and do not initialize new task runs).
    - **Dynamic Workspace Inspection**: Read the target skill in the active adapter. Inspect only workspace files and selected references needed to tailor its examples; reuse current context.
    - **Persistent HTML Playbook & Token-Saving Cache**:
-     - **Output Location & Light Theme Mandate**: Compile and persist the tailored playbook as a standalone, styled HTML report at `devflow/docs/playbooks/{skill}.html` adhering to the **Paper/Ink Light Theme Standard** (`data-theme="light"`, teal accent, ruler corner, terminal mockup UI, and a real diagram). Reuse `devflow/docs/playbooks/template.html` when present; otherwise build the standalone page using these conventions.
-     - **First Run**: Render the comprehensive 5W1H playbook in chat and write the complete HTML report to `devflow/docs/playbooks/{skill}.html`.
-     - **Subsequent Invocations (Delta Updates & Zero Token Bloat)**: If `devflow/docs/playbooks/{skill}.html` already exists:
-       - Inspect the existing HTML file and compute the diff/delta against the current repository state (e.g., new file paths, modified endpoints, or newly installed vendor assets).
-       - DO NOT repeat unchanged boilerplate or full static content in chat.
-       - Provide a concise **Delta Summary** in chat (highlighting what changed, new recommendations, or newly available commands).
-       - In-place update `devflow/docs/playbooks/{skill}.html` with the fresh timestamp and state.
-       - Provide a clickable link to the actual resolved output file using the active client's supported local-file link format.
+      - **Output Location & Light Theme Mandate**: Compile and persist the tailored playbook as a standalone, styled HTML report at `devflow/reference/playbooks/{skill}.html` adhering to the **Paper/Ink Light Theme Standard** (`data-theme="light"`, teal accent, ruler corner, terminal mockup UI, and a real diagram). Build the standalone page using these conventions.
+      - **First Run**: Render the comprehensive 5W1H playbook in chat and write the complete HTML report to `devflow/reference/playbooks/{skill}.html`.
+      - **Subsequent Invocations (Delta Updates & Zero Token Bloat)**: If `devflow/reference/playbooks/{skill}.html` already exists:
+        - Inspect the existing HTML file and compute the diff/delta against the current repository state (e.g., new file paths, modified endpoints, or newly installed vendor assets).
+        - DO NOT repeat unchanged boilerplate or full static content in chat.
+        - Provide a concise **Delta Summary** in chat (highlighting what changed, new recommendations, or newly available commands).
+        - In-place update `devflow/reference/playbooks/{skill}.html` with the fresh timestamp and state.
+        - Provide a clickable link to the actual resolved output file using the active client's supported local-file link format.
    - **Render the User-Friendly 5W1H Playbook**: Emit an easy-to-read, practical guide organized around the **5W 1H Framework** (rendered on initial run or updated in the HTML playbook):
       1. **What (Concept & Capabilities)**: Clear, jargon-free summary of what this skill does, its core concept, and its bundled tools/capabilities.
       2. **Why (Problems Solved & Key Benefits)**: The problems it solves, key advantages, and why you should use it instead of ad-hoc manual work.

package/template/devflow/reference/slicing-archetypes.md

@@ -0,0 +1,105 @@
+# 🧩 4 Slicing Archetypes Framework
+
+> คู่มือมาตรฐานการแบ่งขนาดฟีเจอร์ (Feature Slicing & Decomposition) ใน Nexus-DevFlow เพื่อให้แต่ละรอบการส่งมอบ (Feature Run) มีขนาดเล็ก ส่งมอบคุณค่าได้จริง และทดสอบได้รอบด้าน
+
+---
+
+## 🎯 ทำไมต้องมี Slicing Archetypes?
+
+ในการพัฒนาซอฟต์แวร์และการทำงานร่วมกับ AI Coding Agents ปัญหาคลาสสิก 2 ประการคือ:
+1. **Slicing by Technical Layer** (เช่น ทำเฉพาะ Database หรือทำเฉพาะ Backend API ก่อน): ทำให้ในรอบนั้นไม่มี UI ให้ทดสอบ หรือไม่สามารถทดสอบแบบ End-to-End ได้
+2. **Oversized Features** (ก้อนใหญ่เกินไป): ทำให้ Context Window เต็มเร็ว AI เริ่มเพี้ยน และการ Review ทำได้ยาก
+
+**4 Slicing Archetypes** ช่วยให้คุณและ Agent เลือกกลยุทธ์การหั่นงานที่เหมาะสมที่สุดตามเป้าหมายของแต่ละ Milestone:
+
+---
+
+## 🛹 1. Skateboard Archetype (Minimal Functional Loop)
+
+> *"อย่าเริ่มสร้างรถยนต์ด้วยการทำล้อ แต่ให้เริ่มด้วยการทำสเก็ตบอร์ดที่พาผู้ใช้เคลื่อนที่ได้จริง"*
+
+### นิยาม & วัตถุประสงค์:
+- สร้าง Core Business Logic & State Machine ที่ทำงานได้จริงครบ Loop แม้ UI จะเรียบง่ายที่สุด (Minimal UI หรือ Single Route / Basic Form / CLI interface)
+- เน้นความถูกต้องของ Logic, Validation, Edge Cases และ Data Flow
+
+### เหมาะสำหรับ:
+- ฟีเจอร์ที่ Logic ซับซ้อน มีการคำนวณ การแปลงข้อมูล หรือ State transitions หลายขั้นตอน
+- ต้องการพิสูจน์ว่าแนวคิดหลัก (Core Mechanism) ทำงานได้จริงก่อนลงทุนตกแต่งหน้าจอ
+
+### ตัวอย่าง:
+- **Search & Filter**: สร้างหน้าค้นหาที่มี Search Input เรียบๆ และแสดงผลลัพธ์แบบ Text List เพื่อทดสอบ Search Query, Debounce, Pagination และ Filter Logic
+- **Payment Processing**: ระบบคำนวณราคาสินค้า ส่วนลด ภาษี และสร้าง Transaction Record โดยยังไม่ต้องมี UI สวยหรู
+
+---
+
+## 🎭 2. Facade Archetype (Rich UI / Mock-Backed DX)
+
+> *"สร้างประสบการณ์ใช้งานจริงที่สวยงามและจับต้องได้ โดยเชื่อมต่อกับ Mock Data ก่อนพัฒนา Backend จริง"*
+
+### นิยาม & วัตถุประสงค์:
+- สร้าง Full Rich Interactive UI, Component Interactions, Micro-animations และ Design System สมบูรณ์แบบ
+- จำลอง Data Source ด้วย In-Memory Mock หรือ JSON Fixtures เพื่อเก็บ Feedback เรื่อง UX/DX ทันที
+
+### เหมาะสำหรับ:
+- ฟีเจอร์ที่เน้นประสบการณ์ผู้ใช้ (UI/UX Heavy), Dashboard, Data Visualization, Complex Multi-step Wizards
+- ต้องการให้ Stakeholders / ผู้ใช้เห็นหน้าตาและสัมผัส Flow การกดจริงเพื่อสรุป Design ก่อนลงมือทำ Backend
+
+### ตัวอย่าง:
+- **Analytics Dashboard**: สร้างชาร์ต กราฟ และ Card KPIs สวยงาม Interactive เต็มรูปแบบโดยอ่านข้อมูลจาก Mock Dataset
+- **Interactive Kanban Board**: Drag & drop การ์ด ย้ายคอลัมน์ ปรับแท็กแบบ Real-time บน Local State ก่อนเชื่อมต่อ Database จริง
+
+---
+
+## 🎯 3. Tracer Bullet Archetype (End-to-End Vertical Slice)
+
+> *"ยิงกระสุนส่องวิถี ทะลวงผ่านทุกเลเยอร์ของระบบจากบนลงล่าง สำหรับ 1 Happy Path ที่สมบูรณ์"*
+
+### นิยาม & วัตถุประสงค์:
+- สร้าง Full-Stack Vertical Slice ตั้งแต่ UI -> API Controller -> Service/Logic -> Database Model & Migration สำหรับ **1 Single Happy Path**
+- พิสูจน์ Contract, Network Protocol, Serialization, Type Safety และ Infrastructure ทั้งหมดว่าเชื่อมต่อกันได้จริง
+
+### เหมาะสำหรับ:
+- สถาปัตยกรรมใหม่ หรือเมื่อต้องต่อเชื่อม Third-Party Service, DB ใหม่, หรือ Auth Flow ใหม่
+- ต้องการลดความเสี่ยงด้าน Integration Risk ในช่วงต้นของโปรเจกต์
+
+### ตัวอย่าง:
+- **User Authentication**: สร้าง Registration Form -> Submit API -> Hash Password -> บันทึกลง PostgreSQL DB -> Issue JWT Token -> Redirect ไปหน้า Profile สำหรับกรณีข้อมูลถูกต้อง 1 กรณี
+- **Report Export**: กดปุ่ม Export -> Backend Query ข้อมูล -> สร้าง PDF Stream -> Browser ดาวน์โหลดไฟล์สำเร็จ
+
+---
+
+## 🧭 4. Journey Archetype (Slice by User Workflow / Milestones)
+
+> *"แบ่งฟีเจอร์ตามขั้นตอนการเดินทางของผู้ใช้งาน (User Journey Steps)"*
+
+### นิยาม & วัตถุประสงค์:
+- หั่นงานตามลำดับขั้นตอนธรรมชาติของ Business Process (เช่น Stage 1: Onboarding -> Stage 2: Core Activity -> Stage 3: Summary & Export)
+- แต่ละชิ้นงานจบในตัว และปลดล็อคขั้นตอนถัดไปใน Journey ของผู้ใช้
+
+### เหมาะสำหรับ:
+- Workflow ขนาดใหญ่ที่มีหลายสเตจ, Checkout Flows, Multi-step Form Wizard, Approval Pipeline
+
+### ตัวอย่าง:
+- **E-Commerce Checkout**:
+  - *Slice 1 (Cart Review)*: หน้าสรุปรายการสินค้าและปรับจำนวน
+  - *Slice 2 (Shipping & Address)*: แบบฟอร์มกรอกที่อยู่จัดส่งและคำนวณค่าส่ง
+  - *Slice 3 (Payment & Order Confirmation)*: เลือกวิธีชำระเงินและสรุปใบสั่งซื้อ
+
+---
+
+## 📊 ตารางเปรียบเทียบและการเลือกใช้งาน (Selection Matrix)
+
+| Archetype | จุดเน้นหลัก (Focus) | UI Level | Backend / DB | เมื่อไหร่ควรเลือก? |
+| :--- | :--- | :---: | :---: | :--- |
+| 🛹 **Skateboard** | Core Logic & Flow | Minimal | Real | Logic ซับซ้อน ต้องการความถูกต้องก่อนตกแต่ง |
+| 🎭 **Facade** | UX, DX & Interaction | Rich / Complete | Mocked | ต้องการทดสอบ UX / รับ Feedback จากผู้ใช้เร็ว |
+| 🎯 **Tracer Bullet** | Full Architecture Path | Functional | Real | ต้องการทดสอบ Integration & Pipeline ทะลุทุกชั้น |
+| 🧭 **Journey** | Step-by-Step Workflow | Balanced | Real | Workflow ยาว แบ่งทำทีละสเตจตามลำดับ |
+
+---
+
+## 💡 แนวทางปฏิบัติใน DevFlow Workflow
+
+1. **ใน `/discovery` หรือ `/brainstorm`**: เมื่อวิเคราะห์ฟีเจอร์ใหญ่ ให้เสนอ Archetype ที่แนะนำในการแบ่ง Sub-features
+2. **ใน `/feature` (Step 2 Sizing & Splitting)**: หากต้องแยกฟีเจอร์ย่อย (เช่น 4a, 4b, 4c) ให้ระบุ Archetype กำกับ เช่น `4a. (Tracer Bullet) Core Export Engine` -> `4b. (Facade) Interactive Export Modal & Template Preview`
+3. **ใน Living Spec (`spec.md`)**: ระบุ Archetype ในส่วนหัวของ Spec เพื่อให้ Agent ในขั้นตอน `/implement` ทราบความคาดหวังเรื่องระดับ UI และ Data Source อย่างชัดเจน