@jakkrichm/create-nexus-devflow 2.18.1 → 2.19.0

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

@@ -131,12 +131,13 @@ nexus-devflow/
 
 Testing is a core quality gate in Nexus-DevFlow, not an afterthought:
 
-- **Unit Test Mandate**: Any new feature, modified logic, parser improvement, or bug fix **MUST ship with automated unit tests** in the same diff.
+- **Unit Test Mandate**: Logic or behavior changes must include meaningful automated coverage when the spec's test gate is enabled. Documentation, prompt wording, or formatting-only changes use structural checks and review instead of artificial unit tests.
 - **Strict TDD (Red-Green-Refactor) Protocol**:
   1. **🔴 RED (Test First)**: Always write automated tests *before* writing or modifying functional logic. Run the test command and verify that it fails for the expected reason.
   2. **🟢 GREEN (Minimal Code)**: Write only the minimal production code necessary to make the failing test pass. Run the test command and verify 100% green pass.
   3. **🔵 REFACTOR (Clean & Robust)**: Refactor code for readability, performance, and DRY/YAGNI discipline while ensuring all tests stay green.
   - *Code Deletion / Reversion Rule*: If functional code is created without a prior failing test for behavior changes, it must be reverted or immediately backed by tests before continuing.
+- **Verification Scope**: Run focused checks during edits and required project gates before handoff. Repeat passing checks only after relevant changes, new failures, or unresolved risk.
 - **Test Framework**: Use Node.js native test runner executed via `tsx --test test/*.test.ts` under `packages/create-nexus-devflow/`.
 - **Test Design (AAA Pattern)**:
   - Structure each test case cleanly: **Arrange** (setup fixtures/mock directories), **Act** (execute function), **Assert** (verify invariants).
@@ -149,7 +150,7 @@ Testing is a core quality gate in Nexus-DevFlow, not an afterthought:
     2. *Interactive AI Visual QA (MCP)*: Live DOM and styling inspection via MCP `browseros-neo` (`http://127.0.0.1:9010/mcp`) during `/check` and `/try`.
 - **Two-Stage Review Pattern (Verification Gate)**:
   - **Stage 1: Spec Fidelity & Acceptance Gate**:
-    - Verify 100% conformance against the Single Living Spec (`current-feature.md`).
+    - Verify 100% conformance against the Single Living Spec (`devflow/context/{xxx-slug}/spec.md`).
     - Validate all Acceptance Criteria (ACs) and "Done When" observables without missing requirements or scope creep.
     - Test edge cases and boundary conditions defined in the specification.
   - **Stage 2: Code Quality, Security & Architecture Gate**:
@@ -157,13 +158,13 @@ Testing is a core quality gate in Nexus-DevFlow, not an afterthought:
     - **Lane 2 (Automated Test Suites & Evals)**: `npm test` (Unit tests 100% pass) + `npm run test:routing` (Skill routing accuracy).
     - **Lane 3 (Scrutinize & Security Audit)**: Edge cases, null-safety, 0 secrets, safe inputs.
     - **Lane 4 (Manual / Scenario Proof)**: Concrete walkthrough steps ("Where to go", "What to run", "What to expect").
-    - **Findings Ledger State**: 0 blockers (P0/P1) in `devflow/context/findings.md`.
+    - **Findings Ledger State**: 0 blockers (P0/P1) in `devflow/context/{xxx-slug}/findings.md`.
 
 ---
 
 ## 8. Findings Ledger & Quality Gates (`findings.md`, `review.md`)
 
-- All quality defects, security findings, or regression issues identified during review must be logged in `devflow/context/findings.md`.
+- All quality defects, security findings, or regression issues identified during review must be logged in `devflow/context/{xxx-slug}/findings.md`.
 - **Finding State Machine**:
   - `open`: Confirmed issue waiting to be fixed.
   - `fixed`: Repaired in code, pending QA re-verification.
@@ -214,7 +215,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">`.
@@ -256,6 +257,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

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