@jakkrichm/create-nexus-devflow 2.18.2 → 2.19.0

package/template/devflow/context/glossary.md

@@ -4,15 +4,15 @@
 
 ---
 
-### Single Living Spec (`current-feature.md`)
-- **Definition**: เอกสาร Markdown กลางเพียงฉบับเดียวที่ใช้ขับเคลื่อนและบันทึกวงจรชีวิตของงานพัฒนาตั้งแต่ต้นจนจบ (Single Source of Truth during active delivery)
-- **Constraints**: มีได้เพียง 1 งานที่ active ในช่วงเวลาหนึ่งตามหลักการ Single Active Run Guardrail
+### Task-Isolated Living Spec (`devflow/context/{xxx-slug}/spec.md`)
+- **Definition**: เอกสาร Markdown หลักหนึ่งฉบับต่อ runที่ใช้ขับเคลื่อนและบันทึกวงจรชีวิตของงานพัฒนาตั้งแต่ต้นจนจบ (Single Source of Truth during active delivery)
+- **Constraints**: ร่างหลาย run ได้พร้อมกัน แต่แต่ละ run แยก spec, stage, findings และ branch; เลือกเป้าหมายก่อน implement
 - **Structure**: ครอบคลุม 6 ส่วนหลัก: (1) Define & Boundaries, (2) Technical Spec & Contracts, (3) Execution Plan & TDD Tasks, (4) Implementation Log & Evidence, (5) Multi-Lane Verification Matrix, (6) Release Digest & Retrospective
-- **Aliases / Related**: `current-feature.md`, Living Spec, Feature Spec
+- **Aliases / Related**: `devflow/context/{xxx-slug}/spec.md`, Living Spec, Feature Spec
 
 ### Unified Fast-Track
 - **Definition**: รูปแบบการพัฒนาหลักแบบ Single-Track ของ Nexus-DevFlow ที่รวมความสามารถเชิงสถาปัตยกรรมระดับลึก (Deep) และความคล่องตัว (Fast) เข้าด้วยกันผ่าน 4 คำสั่งหลัก: `/feature` (หรือ `/fix`), `/implement`, `/check`, และ `/complete`
-- **Constraints**: ขับเคลื่อนผ่านไฟล์ `current-feature.md` และเมื่อเสร็จสิ้นจะถูก Archive เป็นไฟล์ Markdown เดี่ยวใน `devflow/history/`
+- **Constraints**: ขับเคลื่อนผ่านไฟล์ `devflow/context/{xxx-slug}/spec.md` และเมื่อเสร็จสิ้นจะถูก Archive เป็นไฟล์ Markdown เดี่ยวใน `devflow/history/{features|fixes|rollbacks}/{xxx-slug}.md`
 - **Aliases / Related**: Fast-Track, Unified Track
 
 ### Pre-Flight Discovery
@@ -22,10 +22,30 @@
 
 ### Multi-Lane Verification Matrix
 - **Definition**: ตารางตรวจสอบคุณภาพแบบหลายมิติที่ครอบคลุม Typecheck, Linter, Automated Unit/Integration Tests, และ Manual Proof Evidence ในคำสั่ง `/check`
-- **Constraints**: ต้องมีผลลัพธ์ผ่าน (PASS) ครบทุก Lane และไม่มี P0/P1 Finding ที่ยังค้างอยู่ก่อนที่จะส่งต่อไปยัง `/complete`
+- **Constraints**: ต้องมีหลักฐานผ่านสำหรับทุก Lane ที่ใช้กับงาน ส่วนที่ไม่เกี่ยวข้องให้บันทึก N/A พร้อมเหตุผล และไม่มี P0/P1 Finding ที่ยังค้างอยู่ก่อนที่จะส่งต่อไปยัง `/complete`
 - **Aliases / Related**: QA Matrix, Lane Verification
 
 ### Release Digest & Retrospective
 - **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

@@ -0,0 +1,33 @@
+# Contextual Help Playbook
+
+**Universal Contextual Help & Playbook Protocol (`help`, `--help`, `-h`, `?`)**:
+   Whenever any skill or command is invoked with a help keyword or flag (e.g., `/bughunter help`, `bughunter --help`, `/archify -h`, `/check ?`, `/feature help`):
+   - **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/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.
+      3. **Who (Target Roles & Personas)**: Target audience or engineering role (e.g., Feature Developer, Senior QA, Security Auditor, Solo Dev, or Tech Lead).
+      4. **Where (Boundaries & Artifact Locations)**: Target workspace boundaries, affected directories, and generated artifact locations (e.g., `devflow/context/`, `devflow/discoveries/`, `findings.md`).
+      5. **When (Timing & Prerequisites/Next Steps)**:
+         - **Timing & Triggers**: Practical situations or milestones when this skill should be invoked.
+         - **Run Before (Prerequisites)**: What to check, prepare, or run beforehand to get the best result.
+         - **Run After (Next Steps)**: What DevFlow command or lifecycle stage should follow next (e.g., handing off to `/fix`, `/feature`, or `/complete`).
+      6. **How (Execution Lifecycle & Real Command Examples)**:
+         - **How It Works (Lifecycle)**: Simple, plain-language breakdown of the execution steps or phases.
+         - **Available Commands & Options**: Common sub-commands, arguments, and flags with brief explanations.
+         - **Safety, Guardrails & Precautions**: Operational boundaries, credential hygiene, read-only vs. mutating constraints, and explicit special safety constraints / precautions.
+      7. **Diagram Slot & Architecture Flow**:
+         - **Real Diagram Mandate**: MUST embed a real, verified vector SVG or interactive diagram reflecting actual skill lifecycle, state transitions, or threat models in Light Theme (`data-theme="light"`).
+         - **Thai Language & Legible Typography**: Architecture and flow diagrams must describe workflows and nodes in Thai language while preserving technical identifiers, paths, and commands in English. Typography must be sufficiently sized and legible for Thai script (Headers 13–14px, box content/descriptions 11–12px, line spacing 18–22px) to prevent tone marks and vowels from clipping or overlapping.
+         - **Strictly No Placeholders**: NEVER output empty placeholder cards, generic instruction text, or phrases like *"when invoking archify..."*. Every playbook must ship with a real visual architectural diagram.
+   - Always conclude the response with: `"Help menu displayed successfully"`.

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 อย่างชัดเจน

package/template/devflow/docs/USAGE.md

@@ -1,195 +0,0 @@
-# Nexus-DevFlow 2.13.0 Comprehensive Usage Guide
-
-This guide provides full operating instructions for **Nexus-DevFlow 2.13.0 (The 3-Pillars Workspace Architecture & Pure Task-Isolated Living Spec Model)** across Google Antigravity, OpenAI Codex, Claude Code, Cursor, GitHub Copilot, and related AI development environments.
-
----
-
-## 1. Core Architecture: The 3-Pillars Model
-
-Nexus-DevFlow structures development history and active context into three distinct temporal pillars:
-
-1. **🔮 Future (Backlog)**: [`devflow/ideas.md`](../ideas.md), [`devflow/project-plan.md`](../project-plan.md), [`devflow/build-plan.md`](../build-plan.md)
-   - Centralized Idea Inbox with AI feasibility, value scoring, and priority tagging (`[IDEA-xxx]`).
-   - Product vision and master build-plan sequencing.
-   - Quick idea capture via `/idea {description}`.
-2. **⚡ Present (Active Context)**: `devflow/context/`
-   - Global Shared Source of Truth: `project-overview.md`, `coding-standards.md`, `ai-interaction.md`, `glossary.md`.
-   - **Task-Isolated Workspaces**: `devflow/context/{xxx-slug}/`
-     - `spec.md`: The Living Spec, task checklist, and empirical proof.
-     - `stage.md`: Stage pointer and transition state.
-     - `findings.md`: Dedicated quality, security, and Fowler smell findings ledger.
-3. **📦 Past (History Archive)**: `devflow/history/`
-   - Categorized delivery archives: `features/`, `fixes/`, `rollbacks/`.
-   - Master Release Ledger: `HISTORY.md`.
-
----
-
-## 2. The Unified 4-Stage Living Spec Lifecycle
-
-All development tasks execute through the progressive 4-stage task-isolated living spec lifecycle:
-
-```text
-/feature (or /fix) ──▶ /implement ──▶ /check ──▶ /complete
-```
-
-| Step | Command | Artifact | Description |
-| :--- | :--- | :--- | :--- |
-| **1. Spec** | `/feature {title}`<br>`/fix {bug}` | `context/{xxx-slug}/spec.md` | Allocates sequential ID (`xxx-slug`), initializes task workspace, writes living spec behind review gate. |
-| **2. Build** | `/implement [id]` | `context/{xxx-slug}/spec.md` | Executes tasks incrementally with strict TDD discipline (Red-Green-Refactor) and evidence recording. |
-| **3. Verify**| `/check [id]` | `context/{xxx-slug}/spec.md` | Dual-Axis review: empirical spec fidelity plus independent standards, architecture, and quality gates. |
-| **4. Deliver** | `/complete [id]` | `history/{cat}/{xxx-slug}.md` | Final safety audit, records Release Digest, archives living spec, cleans active task folder, squash-merges branch. |
-
----
-
-## 3. Pre-Flight Discovery, SA & Architectural Alignment Suite
-
-Before committing to delivery, use specialized companion skills:
-
-```text
-/analyze ──▶ /idea (Inbox) ──▶ /grill (Socratic ADR) ──▶ /discovery (Explore) ──▶ /feature (Deliver)
-```
-
-- **`/analyze`**: Multi-format requirement ingestion (PDF, Word, Excel, Images), Codebase Impact scan & Socratic Gap checklist.
-- **`/idea`**: Capture raw ideas in `devflow/ideas.md` with instant AI feasibility scoring.
-- **`/grill`** (or **`/align`**): Socratic alignment & domain modeling; records Architecture Decision Records (`devflow/decisions/ADR-xxx.md`).
-- **`/brainstorm`**: Structured ideation with trade-off analysis.
-- **`/discovery`**: Deep inception and exploratory discovery (`devflow/discoveries/DISC-xxx.md`).
-
----
-
-## 4. Core Skills Inventory (33 Skills)
-
-DevFlow ships **33 bundled Core Skills** from the ordered `core_skills` inventory
-in `agent-bundle.manifest.json`, synchronized 1:1 across `.agents/skills/`
-(Codex / Antigravity / Copilot) and `.claude/skills/` (Claude Code). Local or
-Personal Skills may coexist in a workspace, but are excluded from the Core count
-and package template until explicitly promoted.
-
-### A. Lifecycle Delivery Skills (8 Skills)
-- `feature`: Turn a build-plan item or new idea into a task-isolated living spec (`devflow/context/{xxx-slug}/spec.md`).
-- `fix`: Document and spec an ad-hoc bug or issue into `devflow/context/{xxx-slug}/spec.md`.
-- `implement`: Step-by-step TDD implementation behind review gates.
-- `check`: Dual-Axis verification of observable spec behavior and independent architecture/standards quality.
-- `complete`: Final safety audit, Conventional Commit, archiving, and branch delivery gate.
-- `autopilot`: Bounded single-pass delivery loop with self-review and safe repair.
-- `continuous`: Autonomous serial multi-feature delivery loop completing build-plan items with quality gates.
-- `rollback`: Plan a safe reversal of a completed feature preserving history.
-
-### B. Pre-Flight Discovery, SA & Alignment Skills (6 Skills)
-- `analyze`: Multi-format requirement ingestion (PDF, Word, Excel, Images), Codebase Impact scan & Socratic Gap checklist.
-- `discovery`: Inception exploration and deep multi-turn planning (`devflow/discoveries/`).
-- `explore`: Read-only codebase exploration to investigate an idea and compare options without changing files or writing a spec.
-- `idea`: Quick idea capture and AI feasibility scoring (`devflow/ideas.md`).
-- `grill` / `align`: Socratic alignment, domain modeling, and ADR recording (`devflow/decisions/`).
-- `brainstorm`: Structured divergent & convergent ideation with trade-off matrices.
-
-### C. Workspace & Governance Skills (19 Skills)
-- `devflow`: Interactive workspace inspector and intent router.
-- `doctor`: Read-only health check for setup, adapters, and workflow drift.
-- `onboard`: Configure freshly scaffolded projects.
-- `adopt`: Bootstrap DevFlow into existing brownfield codebases.
-- `overview`: Compile living source of truth from planning docs.
-- `brief`: Feature scope and dependency briefing before speccing.
-- `audit`: Branch-aware or full-project code and security audit.
-- `bughunter`: Offensive security orchestrator, 83 vulnerability patterns & CVE payloads.
-- `ci`: Set up single Verify command and GitHub Actions.
-- `test`: Test suite runner and coverage analyzer.
-- `setup-tests`: Add or normalize unit test suite.
-- `browser-tests`: Add or normalize Playwright browser test harness & connect with MCP browseros-neo.
-- `release`: Cloud deployment readiness check (Render / Vercel).
-- `prototype`: Static HTML/CSS prototype mockups.
-- `status`: Progress summary and next action inspector.
-- `try`: Manual review testing guide.
-- `debug`: Scientific six-phase diagnosis built around a deterministic red-capable feedback loop.
-- `report-html`: Generate interactive standalone HTML report dashboard.
-- `convert-any-to-md`: Document conversion utility into markdown.
-
----
-
-## 5. Quality, Governance & Authoring Contracts
-
-- [Workflow surface map](workflow-surface-map.md): canonical command taxonomy and artifacts.
-- [Skill selection policy](skill-selection-policy.md): choose the smallest suitable workflow surface.
-- [Governance rules](governance-rules.md): public-surface and documentation placement rules.
-- [Markdown metadata contract](markdown-metadata-contract.md): frontmatter and semantic heading requirements.
-- [Manual review workflow](manual-review-workflow-spec.md): review gates from spec through delivery.
-- [Living Spec examples](examples/living-spec/): reference specs, discoveries, ADRs, and ideas.
-
-`/check` applies the Deep Modules standard independently from spec fidelity:
-small public interfaces, hidden complexity, stable seams, and no speculative
-abstraction. `/debug` diagnoses first and hands confirmed repairs to `/fix` or
-`/implement`; it does not edit source during diagnosis.
-
----
-
-### Debugging, TDD & Review Reference Guides
-
-The `debug`, `implement`, and `audit` skills include five English reference guides.
-They are supporting files read when needed, not additional commands. Both
-`.agents/skills/` and `.claude/skills/` contain matching copies; no separate
-Superpowers plugin installation is required.
-
-| Situation | Entry point | Reference guide |
-| :--- | :--- | :--- |
-| Error deep in a call stack or unclear input origin | `/debug` Phase 4 | [Root-cause tracing](../../.agents/skills/debug/root-cause-tracing.md) |
-| Confirmed root cause needs protective checks | `/debug` repair planning → `/fix` → `/implement` | [Defense-in-depth](../../.agents/skills/debug/defense-in-depth.md) |
-| Flaky async tests or guessed sleep delays | `/debug` Phase 4 | [Condition-based waiting](../../.agents/skills/debug/condition-based-waiting.md) |
-| Planning RED/GREEN or inspecting test quality | `/implement [id]` | [TDD anti-patterns](../../.agents/skills/implement/tdd-anti-patterns.md) |
-| Preparing an independent review | `/audit independent current` | [Two-stage review template](../../.agents/skills/audit/two-stage-review-template.md) |
-
-**Debugging:** Trace the trigger before planning a repair. Use validation layers
-according to actual invariants and risks, and keep diagnostic output redacted.
-The waiting example accepts synchronous predicates only; async I/O needs an
-appropriate async helper with cancellation or timeout. `/debug` remains a
-diagnostic stage. After three unsuccessful repair attempts in the supplied
-history, stop and discuss the architecture before attempting another fix.
-
-**Implementation:** Apply the Iron Law to behavior changes according to the
-spec's test decision: observe the intended failing test before production code.
-Confirm that RED reflects missing behavior rather than broken setup, implement
-the minimum change for GREEN, then refactor with tests passing. Preserve existing
-user work; verify documentation or configuration without logic as the spec directs.
-
-**Review:** Check spec compliance first, then code quality only after Stage 1
-passes. Use the template alongside the canonical
-[independent-review contract](../../.agents/skills/audit/reference/independent-review.md).
-The configured gate still determines whether review runs, and its request,
-immutable checkpoint, reviewer identity, and receipt requirements remain in force.
-Open or fixed P0/P1 findings continue to block completion.
-
-Example prompts (use `$debug` and `$implement` in Codex where appropriate):
-
-```text
-/debug "This async test passes locally but times out in CI; inspect its waiting conditions"
-/implement 085
-/audit independent current
-```
-
-Replace `085` with your active task ID. For the review prompt, ask the reviewer
-to use `audit/two-stage-review-template.md` with the canonical receipt contract;
-the template does not launch a reviewer or authorize a checkpoint commit itself.
-
----
-
-## 6. Web Dashboard & CLI Management
-
-```bash
-# Launch interactive Local Dashboard (0ms SSR Hydration & Git Cache)
-npx @jakkrichm/create-nexus-devflow dashboard
-
-# Check active project status across 3-Pillars
-npx @jakkrichm/create-nexus-devflow status
-
-# Automated Quality Gatekeeper
-npx @jakkrichm/create-nexus-devflow gate [--strict]
-
-# Model Context Protocol (MCP) Server Hub
-npx @jakkrichm/create-nexus-devflow mcp
-
-# Just-In-Time (JIT) Dynamic Context Slicing
-npx @jakkrichm/create-nexus-devflow slice --stage implement
-
-# Multi-Agent Swarm & Code Graph RAG
-npx @jakkrichm/create-nexus-devflow swarm
-npx @jakkrichm/create-nexus-devflow graph --file src/index.ts
-```