@jakkrichm/create-nexus-devflow 2.2.1 → 2.5.0

package/template/devflow/context/ai-interaction.md

@@ -27,59 +27,74 @@ Format every response for fast scanning and readability:
 
 ---
 
-## 3. Dual-Track Workflow Lifecycle (The 3-Pillars Model)
+## 3. The 3-Pillars Unified Architecture (DevFlow 2.5.0)
 
 ```text
 devflow/
-├── 🔮 ideas.md        # [Future] Idea Inbox
-├── ⚡ context/         # [Present] Living Spec (current-feature.md) & Active State
+├── 🔮 ideas.md        # [Future] Idea Inbox with AI Feasibility Scoring
+├── ⚡ context/         # [Present] Single Living Spec (current-feature.md) & Active State
 └── 📦 history/         # [Past] features/, fixes/, rollbacks/, and HISTORY.md
 ```
 
-### 🏎️ Track 1: Fast-Track (Blueprint Mode — 4 Steps)
-*Recommended for 85% of daily engineering work (features, bug fixes, UI improvements, iterative refactoring).*
-
-The entire lifecycle is driven by the **Single Living Spec (`devflow/context/current-feature.md`)**:
-
-1. **Spec (`/feature` or `/fix`)**:
-   - Checks **Single Active Run Guardrail** (rejects if an uncompleted task is still active).
-   - Analyzes request (or consumes `IDEA-xxx` from `devflow/ideas.md`).
-   - Allocates sequential ID without prefix (e.g. `022-{slug}`) and creates branch `feature/{xxx-slug}` or `fix/{xxx-slug}`.
-   - Generates `devflow/context/current-feature.md` containing **Section 1 (Scope & AC)**, **Section 2 (Plan & Test Strategy)**, and **Section 3 (Checklist)**.
-2. **Implement (`/implement`)**:
-   - Executes checklist tasks incrementally one small diff at a time using **TDD (Red-Green-Refactor)**.
-   - Updates `## 4. Implementation Record` and marks tasks `- [x]` in `current-feature.md`.
-3. **Check (`/check`)**:
-   - Senior QA multi-lane verification (Lane 1: Typecheck/Lint, Lane 2: Test Suites, Lane 3: Manual Proof).
-   - Records empirical proof under `## 5. Verification Evidence` in `current-feature.md`.
-4. **Complete (`/complete`)**:
-   - Final safety pass, updates `## 6. Release & Handoff` digest in `current-feature.md`.
-   - Automatically archives `current-feature.md` ➔ `devflow/history/{features|fixes|rollbacks}/{xxx-slug}.md`.
-   - Appends resolved findings and cleans `findings.md`.
-   - Resets `current-feature.md` back to the idle stub.
-   - Performs Git squash-merge into `main`, updates `devflow/history/HISTORY.md`, and sets workspace to Idle.
+### ⚡ The Unified 4-Stage Living Spec Lifecycle
+*ขับเคลื่อนการพัฒนาทุกระดับ (ตั้งแต่ Fast Fix จนถึง Architectural Epic) ด้วยเอกสารฉบับเดียว **Single Living Spec (`devflow/context/current-feature.md`)** ที่รวมความลึกระดับ Architect Mode เข้ากับความคล่องตัวระดับ Lean Velocity:*
+
+```text
+/feature (หรือ /fix) ──▶ /implement ──▶ /check ──▶ /complete
+```
+
+1. **Stage 1: Spec (`/feature` หรือ `/fix`)**:
+   - ตรวจสอบ **Single Active Run Guardrail** (บล็อกการเปิดงานซ้อนถ้ามีงานที่ยังไม่เสร็จ)
+   - ดึงบริบทจาก `devflow/discoveries/`, `devflow/ideas.md`, หรือคำขอของผู้ใช้
+   - จัดสรร Running ID (`xxx-slug`) และสร้าง Branch `feature/{xxx-slug}` หรือ `fix/{xxx-slug}`
+   - เขียน **Single Living Spec (`current-feature.md`)** ครอบคลุม:
+     - `## 🎯 1. Define & Boundaries` (Problem, In/Out Scope, Risks, Success Criteria)
+     - `## 📐 2. Technical Spec & Contracts` (Architecture, Models, Interface Contracts, Non-functional, ACs)
+     - `## 📋 3. Execution Plan & TDD Checklist` (Atomic tasks, `[TDD-Red/Green/Refactor]` Triplets)
+
+2. **Stage 2: Implement (`/implement`)**:
+   - ดำเนินการ Task-by-task ตาม Checklist อย่างเคร่งครัดด้วย **TDD (Red-Green-Refactor)**
+   - ติ๊กเครื่องหมาย `- [x]` และบันทึก `## ⚡ 4. Implementation Log & Evidence` (Diff summary, Checkpoints) ลงใน `current-feature.md`
+
+3. **Stage 3: Check (`/check`)**:
+   - Senior QA Multi-Lane Verification (Typecheck, Lint, Test Suites, Manual Proof)
+   - บันทึกผลการพิสูจน์เชิงประจักษ์ลงใน `## 🧪 5. Multi-Lane Verification Matrix` ใน `current-feature.md`
+
+4. **Stage 4: Complete (`/complete`)**:
+   - สรุปผล `## 📦 6. Release Digest & Retrospective` (Changelog, Lessons Learned, ADRs)
+   - ทำการ Archive `current-feature.md` ไปเป็นไฟล์เดี่ยวที่ `devflow/history/{features|fixes|rollbacks}/{xxx-slug}.md`
+   - **Mandatory Delivery Gate**: บังคับถามผู้ใช้ก่อนเสมอว่าต้องการ Delivery รูปแบบใด:
+     - **Option 1 (Team MR/PR Flow)**: Pull master/main ล่าสุดมารวมกับ Feature/Dev Branch แล้ว push branch ขึ้นไปเพื่อเปิด MR/PR (ไม่ merge เข้า main/master ในเครื่อง และไม่แตะ protected branch)
+     - **Option 2 (Direct Squash-Merge)**: ทำการ Squash-merge เข้า main/master ในเครื่องเฉพาะเมื่อผู้ใช้สั่งโดยตรงเท่านั้น
+   - รีเซ็ต `current-feature.md` กลับเป็น Idle stub เมื่อปิดรอบงานเรียบร้อย
 
 ---
 
-### 🏗️ Track 2: Deep-Track (Architect Mode — 8 Steps)
-*Recommended for large architectural epics, database migrations, security audits, and multi-agent coordination.*
+### 🔮 Pre-Flight Discovery & Architectural Alignment (Companion Tools)
+สำหรับงานที่ต้องการสำรวจไอเดีย, ค้นคว้าทางเทคนิค, หรือการออกแบบสถาปัตยกรรมก่อนเริ่มสร้าง Spec:
+- `/discovery`: Unified Pre-delivery Discovery & Research (บันทึกใน `devflow/discoveries/`)
+- `/idea`: วิเคราะห์และบันทึกไอเดียลงใน `devflow/ideas.md`
+- `/grill` (หรือ `/align`): Socratic Alignment, Domain Modeling & บันทึก ADRs ลงใน `devflow/decisions/`
+- `/brainstorm`: เครื่องมือระดมความคิดทางเลือก 2-3 Options พร้อมเปรียบเทียบ Trade-offs
 
-```text
-00-explore ➔ 10-define ➔ 20-spec ➔ 30-plan ➔ 40-execute ➔ 50-verify ➔ 60-report ➔ 70-deliver
-```
 
-1. `00-explore`: Explore request before delivery commitment (`DISC-YYYYMMDD-NNN`).
-2. `10-define`: Turn approved discovery into bounded delivery run in `devflow/context/current-run/10-define.md`.
-3. `20-spec`: Formalize markdown delivery contract & acceptance criteria (`20-spec.md`).
-4. `30-plan`: Breakdown spec into executable tasks with test decisions (`30-plan.md` + checklists).
-5. `40-execute`: Incremental task execution behind review gates (`40-execute.md`).
-6. `50-verify`: Senior QA review & multi-lane verification checks (`50-verify.md`).
-7. `60-report`: Standardized markdown delivery digest (`60-report.md`).
-8. `70-deliver`: Release packaging, git merge, archives `devflow/context/current-run/` ➔ `devflow/history/{features|fixes|rollbacks}/{xxx-slug}/`, and closes the run.
+## 4. Strict TDD & Two-Stage Review Interaction Rules
+
+### 🔴🟢 Strict TDD Execution Discipline
+During implementation in `/implement` and `40-execute`:
+- **Show Red Phase**: First execute tests to demonstrate expected failure *before* adding production code.
+- **Show Green Phase**: Add minimal production code, re-run tests, and report pass rate.
+- **Show Refactor Phase**: Polish and clean up with zero test regression.
+- **Forbidden**: Never present functional code changes without matching test execution evidence.
+
+### 🛡️ Two-Stage Verification Reporting
+During `/check` and `50-verify`:
+- **Stage 1 (Spec Fidelity Gate)**: Report each Acceptance Criterion and "Done When" status.
+- **Stage 2 (Code Quality & Security Gate)**: Report Typecheck, Lint, Test Suites, Security checks, and Findings Ledger (0 blockers).
 
 ---
 
-## 4. Standalone HTML Reporting Policy
+## 5. Standalone HTML Reporting Policy
 
 > [!IMPORTANT]
 > **No Auto-Generated HTML**: Mainline stages (`/complete` and `60-report`) strictly output Markdown only.

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

@@ -91,22 +91,33 @@ nexus-devflow/
 
 ---
 
-## 7. Testing & Empirical Proof Standards
+## 7. Testing & Empirical Proof Standards (Strict TDD & Two-Stage Review)
 
 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.
+- **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.
 - **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).
   - Use isolated temporary directories (`fs.mkdtemp` in `os.tmpdir()`) and ensure cleanup in `finally` blocks.
 - **Empirical Proof Contract**:
   - Never claim a task is "working", "tested", or "verified" without providing concrete empirical proof (exact command executed, terminal output, pass/fail counts, exit code).
-- **Multi-Lane Verification Matrix**:
-  - **Lane 1 (Type & Syntax Safety)**: `tsc --noEmit` (0 type errors).
-  - **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").
+- **Two-Stage Review Pattern (Verification Gate)**:
+  - **Stage 1: Spec Fidelity & Acceptance Gate**:
+    - Verify 100% conformance against the living spec (`current-feature.md` or `20-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**:
+    - **Lane 1 (Type & Syntax Safety)**: `tsc --noEmit` (0 type errors).
+    - **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`.
 
 ---
 

package/template/devflow/context/findings.md

@@ -1,13 +1,10 @@
-# Findings Ledger
+# Findings
 
-> **Generated Ledger File.** Tracks quality findings, security vulnerabilities, regression risks, and architectural debt raised during review and QA passes.
->
-> **Finding Format**:
-> `### <ID> [<SEVERITY>] <STATUS> - <Title>`
-> - **Severities**: `P0` (Critical Blocker), `P1` (High Blocker), `P2` (Medium), `P3` (Low / Polish)
-> - **Statuses**: `unverified`, `open`, `fixed`, `closed`, `accepted`, `invalid`
-> - **Release Gate Rule**: Any `P0` or `P1` finding in `open` or `fixed` status unconditionally blocks `/complete` and `70-deliver`.
+> **Generated file.** The findings ledger: review findings raised by `/audit`
+> against the work in progress, each with a durable ID, severity (P0-P3), and
+> status. `/implement` marks repaired findings `fixed`, a later `/audit` pass
+> moves them to `closed`, and `/complete` refuses to merge while any P0 or P1
+> finding is `open` or `fixed`, then archives resolved findings with the work
+> and resets this file.
 
----
-
-_No active findings recorded. QA and audit passes append findings here as they are discovered._
+_No findings recorded. `/audit` appends findings here when it finds them._

package/template/devflow/context/glossary.md

@@ -0,0 +1,31 @@
+# Nexus-DevFlow Domain Glossary
+
+> พจนานุกรมศัพท์โดเมนและนิยามสถาปัตยกรรมสำหรับ Nexus-DevFlow
+
+---
+
+### Single Living Spec (`current-feature.md`)
+- **Definition**: เอกสาร Markdown กลางเพียงฉบับเดียวที่ใช้ขับเคลื่อนและบันทึกวงจรชีวิตของงานพัฒนาตั้งแต่ต้นจนจบ (Single Source of Truth during active delivery)
+- **Constraints**: มีได้เพียง 1 งานที่ active ในช่วงเวลาหนึ่งตามหลักการ Single Active Run Guardrail
+- **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
+
+### Unified Fast-Track
+- **Definition**: รูปแบบการพัฒนาหลักแบบ Single-Track ของ Nexus-DevFlow ที่รวมความสามารถเชิงสถาปัตยกรรมระดับลึก (Deep) และความคล่องตัว (Fast) เข้าด้วยกันผ่าน 4 คำสั่งหลัก: `/feature` (หรือ `/fix`), `/implement`, `/check`, และ `/complete`
+- **Constraints**: ขับเคลื่อนผ่านไฟล์ `current-feature.md` และเมื่อเสร็จสิ้นจะถูก Archive เป็นไฟล์ Markdown เดี่ยวใน `devflow/history/`
+- **Aliases / Related**: Fast-Track, Unified Track
+
+### Pre-Flight Discovery
+- **Definition**: กระบวนการสำรวจไอเดีย, ทำการวิจัย (Research), กลั่นกรอง PRD, วิเคราะห์ Trade-offs และจัดทำ ADR ก่อนที่จะเริ่มเปิดรอบพัฒนาจริง
+- **Constraints**: ไม่แก้ไขซอร์สโค้ดโปรเจกต์ และไม่ถือว่าเป็น Active Run จนกว่าจะถูกส่งต่อเข้าสู่ `/feature`
+- **Aliases / Related**: `/discovery`, `/idea`, `/brainstorm`, `/grill`
+
+### Multi-Lane Verification Matrix
+- **Definition**: ตารางตรวจสอบคุณภาพแบบหลายมิติที่ครอบคลุม Typecheck, Linter, Automated Unit/Integration Tests, และ Manual Proof Evidence ในคำสั่ง `/check`
+- **Constraints**: ต้องมีผลลัพธ์ผ่าน (PASS) ครบทุก Lane และไม่มี 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

package/template/devflow/reference/build-plan-template.md

@@ -0,0 +1,65 @@
+# Build Plan
+
+> **Document Type**: Build Plan (User-Owned)
+> **Purpose**: รายการฟีเจอร์ตามลำดับการพัฒนาจริง (Ordered Feature Roadmap Checklist)
+> **Workflow**: ใช้เครื่องหมาย Checkbox `- [ ]` เรียงลำดับ 1, 2, 3... เพื่อให้ `/feature` ดึงไปทำทีละงาน
+
+---
+
+## 🚀 Phase 1: Core Foundation & Data Layer
+
+- [ ] 1. **Core Schema & Data Models** - สร้าง Data Models, Schemas (Zod) และ Database Migrations เบื้องต้น
+- [ ] 2. **Base Layout & Main UI Shell** - วางโครงสร้างหน้าจอหลัก, Navigation Shell และ Design Tokens
+- [ ] 3. **Primary Feature Flow** - พัฒนาฟังก์ชันการทำงานหลัก พร้อม Input Form และ Validation
+
+---
+
+## ⚡ Phase 2: Interactivity & Core Capabilities
+
+- [ ] 4. **Live Preview / Action Pipeline** - เชื่อมต่อ Input เข้าสู่ระบบประมวลผลและการแสดงผลแบบ Real-time
+- [ ] 5. **Export / Output Engine** - พัฒนาระบบส่งออกข้อมูล เช่น Image Generation, PDF Download หรือ API Response
+- [ ] 6. **Local Persistence & Settings** - บันทึกการตั้งค่าและประวัติการใช้งานลงใน Local Storage หรือ Database
+  - [ ] 6a. **Settings Panel** - UI สำหรับปรับแต่งค่าและการจัดเก็บ State
+  - [ ] 6b. **History & Recall** - แสดงรายการประวัติย้อนหลังและปุ่มเรียกข้อมูลกลับมาใช้
+
+---
+
+## 🚢 Phase 3: Polish, Quality & Production Hardening
+
+- [ ] 7. **Edge Cases & Input Polish** - จัดการ Loading States, Error Boundaries และ Responsive Layout
+- [ ] 8. **Deployment Readiness & Production Verification** - ตั้งค่า Environment Config, ตรวจสอบ Production Build และ Health Check
+
+---
+
+## 🛠️ Architecture & Deployment Notes (Optional)
+<!-- 
+บันทึกการตัดสินใจทางสถาปัตยกรรมที่ตกลงกันไว้ล่วงหน้า เพื่อป้องกันการสับสนระหว่างการ Implement
+-->
+
+- **Key Technical Decisions**:
+  - [เช่น ใช้ Full Puppeteer พร้อม Bundled Chromium แทน Serverless Chromium เพื่อความเสถียรของ Font]
+  - [เช่น จัดเก็บ User Session ผ่าน JWT ใน HttpOnly Cookies]
+- **Environment & Hosting Constraints**:
+  - [เช่น ต้องการ Memory ขั้นต่ำ 1GB บน Render หรือ Docker Container]
+  - [เช่น กำหนด Concurrency Limits ไม่เกิน 2 worker processes ต่อ instance]
+
+---
+
+## 🔮 Later / Post-MVP Backlog (Not in v1)
+<!-- 
+ฟีเจอร์ที่วางแผนไว้สำหรับอนาคต (หลังจาก v1 ส่งมอบเรียบร้อยแล้ว)
+-->
+
+- [ ] **Cloud Sync & User Accounts** - ระบบสมัครสมาชิกและซิงค์ข้อมูลบน Cloud (Clerk / Supabase)
+- [ ] **Batch Processing** - อัปโหลดไฟล์ CSV และประมวลผลพร้อมกันทีละหลายรายการ
+- [ ] **Paid Subscription & Billing** - เชื่อมต่อ Stripe และจัดการ Tier จำกัดการใช้งาน
+
+---
+
+<!--
+💡 คำแนะนำในการเขียน Build Plan ที่ดี:
+1. แต่ละข้อต้องเป็น "Feature-Sized Outcome" ที่มองเห็นผลลัพธ์ได้ (ไม่ใช่แค่ task ย่อยๆ เช่น "เขียน function x")
+2. ห้ามใส่ Scaffolding Chores (เช่น "สร้างโปรเจกต์ Next.js", "ติดตั้ง Tailwind") เพราะทำก่อนหน้าแล้ว
+3. ฟีเจอร์ที่มีความซับซ้อน สามารถแตกเป็น Sub-items ย่อยได้ เช่น 6a, 6b
+4. อย่าจัดกลุ่มฟีเจอร์หลายๆ อย่างรวมในข้อเดียว (เช่น "Auth + Database + Dashboard + Deploy")
+-->

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

@@ -0,0 +1,110 @@
+# [ID-slug] Feature Title
+
+> **Template Type**: Single Living Spec (DevFlow 2.5.0)
+> **Active Location**: `devflow/context/current-feature.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)
+
+---
+
+## 🎯 1. Define & Boundaries
+
+### Problem Statement & Goal
+- **Problem**: อธิบายปัญหาที่พบ หรือสิ่งที่ต้องการแก้ไข/ปรับปรุง
+- **Goal**: ผลลัพธ์หรือเป้าหมายที่ต้องการให้เกิดขึ้น
+
+### In-Scope & Out-of-Scope
+- **In-Scope**:
+  - สิ่งที่ต้องทำในรอบนี้
+- **Out-of-Scope**:
+  - สิ่งที่ไม่ทำในรอบนี้ หรือยกยอดไปทำในเฟสถัดไป
+
+### Risk & Mitigation Matrix
+| Risk | Severity | Mitigation |
+| :--- | :--- | :--- |
+| ความเสี่ยงที่อาจเกิดขึ้น | Low/Medium/High | แนวทางป้องกันหรือรับมือ |
+
+### Success Criteria
+1. เกณฑ์ชี้วัดความสำเร็จข้อที่ 1
+2. เกณฑ์ชี้วัดความสำเร็จข้อที่ 2
+
+---
+
+## 📐 2. Technical Spec & Contracts
+
+### Architecture & Component Design
+- อธิบายโครงสร้างหรือ Flow การทำงานของ Component/Module
+
+### Data Models & Schemas
+```typescript
+// Interface หรือ Type Definition
+```
+
+### API & Interface Contracts
+- **Endpoint / Function**: `methodName(params: Type): ReturnType`
+- **Error Handling**: รายละเอียด Error Codes และวิธีจัดการ
+
+### Non-Functional Constraints
+- **Security**: การตรวจสอบ Input, การจัดการสิทธิ์, Secrets
+- **Performance**: ข้อจำกัดเรื่องความเร็ว หรือ Resource Usage
+
+### Acceptance Criteria (AC)
+- [ ] **AC-1**: เงื่อนไขการยอมรับข้อที่ 1
+- [ ] **AC-2**: เงื่อนไขการยอมรับข้อที่ 2
+
+---
+
+## 📋 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 โค้ด
+
+- [ ] **Task 2: Feature Implementation**
+  - [ ] 2.1 `[TDD-Red]` เขียน Test ครอบคลุม Edge Cases
+  - [ ] 2.2 `[TDD-Green]` Implement Feature ตาม Contract
+  - [ ] 2.3 `[TDD-Refactor]` ตรวจสอบความถูกต้องและ Architecture
+
+- [ ] **Task 3: Integration & QA Verification**
+  - [ ] 3.1 `[TDD-Green]` เชื่อมต่อ UI/API และตรวจสอบ End-to-End
+
+---
+
+## ⚡ 4. Implementation Log & Evidence
+
+*(จะถูกบันทึกและอัปเดตความคืบหน้าระหว่างรันคำสั่ง `/implement`)*
+
+- **Step 1**: ...
+- **Checkpoint Commit**: `feat(scope): ...`
+
+---
+
+## 🧪 5. Multi-Lane Verification Matrix
+
+*(จะถูกบันทึกผลการตรวจสอบระหว่างรันคำสั่ง `/check`)*
+
+| 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`)*
+
+- **What Changed**: สรุปสิ่งที่เปลี่ยนแปลง
+- **Key Decisions**: การตัดสินใจสำคัญระหว่างพัฒนา
+- **Lessons Learned**: บทเรียนที่ได้รับ
+- **Known Limitations**: ข้อจำกัดที่ทราบและข้อเสนอแนะในอนาคต

package/template/devflow/reference/project-plan-template.md

@@ -0,0 +1,128 @@
+# Project Plan
+
+> **Document Type**: Project Plan (User-Owned)
+> **Purpose**: แหล่งความจริงหลัก (Single Source of Truth) สำหรับวิสัยทัศน์ผลิตภัณฑ์ สถาปัตยกรรมระบบ ขอบเขตการทำงาน และข้อกำหนดทางเทคนิค
+> **Workflow**: กรอกข้อมูลให้ครบถ้วนแล้วรัน `/overview` เพื่อประมวลผลเป็น `project-overview.md`
+
+---
+
+## 1. Problem - What problem are we solving?
+<!-- 
+อธิบายปัญหาที่ระบบนี้เข้ามาแก้ไข วัตถุประสงค์หลัก และทำไมโปรเจกต์นี้จึงควรมีอยู่ (2-4 ประโยค)
+- ปัญหาในปัจจุบันคืออะไร ทำไมวิธีเดิมถึงไม่ตอบโจทย์
+- ผลลัพธ์ที่ต้องการ (Desired Outcome) หลังระบบนี้สร้างเสร็จ
+-->
+
+- **Core Problem**: [ระบุปัญหาหลักที่ผู้ใช้กำลังเผชิญ เช่น การทำงานแบบ Manual ที่เสียเวลาและผิดพลาดง่าย]
+- **Main Purpose**: [ระบุเป้าหมายหลักของระบบ เช่น แปลง Input 3 อย่างเป็นผลลัพธ์พร้อมใช้งานในไม่กี่วินาที]
+
+---
+
+## 2. Users - Who is this for?
+<!-- 
+กลุ่มผู้ใช้งานเป้าหมายและ Use Cases หลัก
+- Primary Users: ผู้ใช้งานหลักกลุ่มแรก
+- Secondary / Later: กลุ่มผู้ใช้ในอนาคต
+- Access Tiers: สิทธิ์การเข้าถึง เช่น Guest / Registered / Admin
+-->
+
+- **Primary Audience**: [เช่น Solo Developers, Content Creators, นักเรียน/นักศึกษา]
+- **Secondary Audience (Later)**: [เช่น ทีมงานองค์กร, ลูกค้าปลายทาง]
+- **User Personas & Access Tiers**:
+  - `Anonymous / Guest`: [สิทธิ์การใช้งานทั่วไป เช่น ดูข้อมูลสาธารณะ, ทดลองเล่นแบบจำกัด]
+  - `Authenticated User`: [สิทธิ์การใช้งานหลัก เช่น จัดการข้อมูลตนเอง, บันทึกประวัติ]
+  - `Admin`: [สิทธิ์การจัดการระบบ เช่น ดูแลผู้ใช้, ตรวจสอบ Log]
+
+---
+
+## 3. Features - What does v1 need?
+<!-- 
+รายการฟีเจอร์ระดับสูงสำหรับเวอร์ชันแรก (MVP / v1)
+- เขียนสรุปสั้นๆ บรรทัดละ 1 ข้อ ไม่ต้องลงรายละเอียดทางเทคนิคลึก
+- แยกส่วน Out of Scope / Later ให้ชัดเจนเพื่อคุมขอบเขต (Prevent Scope Creep)
+-->
+
+### Core MVP Features (v1):
+- **Feature 1**: [คำอธิบายสั้นๆ เกี่ยวกับสิ่งที่ฟีเจอร์นี้ทำ]
+- **Feature 2**: [คำอธิบายสั้นๆ เกี่ยวกับสิ่งที่ฟีเจอร์นี้ทำ]
+- **Feature 3**: [คำอธิบายสั้นๆ เกี่ยวกับสิ่งที่ฟีเจอร์นี้ทำ]
+- **Feature 4**: [คำอธิบายสั้นๆ เกี่ยวกับสิ่งที่ฟีเจอร์นี้ทำ]
+
+### Later / Post-MVP (Not in v1):
+<!-- สิ่งที่เก็บไว้ทำในอนาคต แต่ยังไม่ทำในรอบแรก -->
+- [เช่น ระบบสมัครสมาชิกและจัดการ Billing ผ่าน Stripe]
+- [เช่น การส่งออกข้อมูลปริมาณมากแบบ Batch/CSV]
+- [เช่น Cloud Sync และการแชร์ข้อมูลข้ามอุปกรณ์]
+
+---
+
+## 4. Data - What are we storing?
+<!-- 
+โครงสร้างข้อมูลและ Entity หลักที่ระบบต้องจัดเก็บ
+- ข้อมูลที่อยู่ใน Code (Static / Config)
+- ข้อมูลที่เก็บใน Browser (LocalStorage / Session / Cookies)
+- ข้อมูลที่เก็บใน Database (Entities, Fields, Relationships)
+-->
+
+- **In-Code / Static**: [เช่น Template Definitions, App Constants, Fixed Options]
+- **Client Storage (LocalStorage/Session)**: [เช่น User Preferences, Form Draft, UI Settings]
+- **Database Entities (If applicable)**:
+  - **`User`**: `id` (String/UUID), `email` (String, Unique), `name` (String), `role` (Enum), `createdAt` (DateTime)
+  - **`Resource`**: `id` (UUID), `userId` (FK -> User.id), `title` (String), `status` (Enum), `metadata` (JSON), `updatedAt` (DateTime)
+- **Relationships**:
+  - `User` 1-to-Many `Resource`
+
+---
+
+## 5. Tech - What stack are we using?
+<!-- 
+เทคโนโลยี ไลบรารี และเครื่องมือที่เลือกใช้ พร้อมระบุหน้าที่
+-->
+
+- **Framework & Runtime**: [เช่น Next.js 15 (App Router), TypeScript, Node.js >=20]
+- **Styling & UI**: [เช่น Tailwind CSS v4, Shadcn UI / Radix Primitives, Lucide Icons]
+- **State & Data Access**: [เช่น Zustand, TanStack Query, Prisma ORM / Drizzle]
+- **Database**: [เช่น PostgreSQL on Neon / Supabase, SQLite on LibSQL]
+- **Authentication**: [เช่น NextAuth.js (Auth.js), Clerk, Supabase Auth, หรือ None in v1]
+- **Validation**: [เช่น Zod for Schema & Input Validation]
+- **Special Engines / Libraries**: [เช่น Puppeteer for Headless PDF/Image Export, Sharp for Image Processing]
+
+---
+
+## 6. Monetize - How will this make money?
+<!-- 
+โมเดลทางธุรกิจหรือแผนการสร้างรายได้ (หากเป็น Free Tool หรือ Internal App ให้ระบุให้ชัด)
+-->
+
+- **Model in v1**: [เช่น Free / Open-Source / Internal Utility (ไม่มีการเก็บเงินใน v1)]
+- **Future Monetization (If applicable)**: [เช่น Freemium, Subscription $10/mo, Usage-based API credits]
+
+---
+
+## 7. UI/UX - How should this look and feel?
+<!-- 
+ธีม โครงสร้างหน้าจอ สไตล์การออกแบบ และประสบการณ์ผู้ใช้
+-->
+
+- **Design Aesthetic**: [เช่น Clean & Modern, Dark-Mode First, Glassmorphism, Minimalist]
+- **Layout Structure**: [เช่น Single-page dashboard with Split View (Form on left, Live Preview on right)]
+- **Key Routes / Screens**:
+  - `/`: [หน้า Landing & Main Generator Workflow]
+  - `/dashboard`: [หน้าจัดการ Resource และดูประวัติย้อนหลัง]
+  - `/settings`: [หน้าตั้งค่า Profile และ Preferences]
+
+---
+
+## 8. Deployment - Where and how will this ship?
+<!-- 
+เป้าหมายการ Deploy, คำสั่ง Build/Start, และ Environment Variables
+-->
+
+- **Target Platform**: [เช่น Vercel, Render, Cloudflare Pages, Fly.io, Self-hosted Docker]
+- **Build Command**: `npm run build`
+- **Start Command / Output**: `npm run start` (หรือ Static Output `out/`)
+- **Required Environment Variables**:
+  - `DATABASE_URL`: Connection string สำหรับ Database
+  - `NEXTAUTH_SECRET`: Secret key สำหรับ Session signing
+  - `API_KEY`: Key สำหรับเชื่อมต่อ Third-party Service
+- **Health Check Endpoint**: `/api/health`

package/template/devflow/reference/running-id-contract.md

@@ -1,4 +1,4 @@
-# DevFlow 2.0 Running ID & 3-Pillars Workspace Contract
+# DevFlow 2.5.0 Running ID & 3-Pillars Workspace Contract
 
 ## The 3-Pillars Workspace Architecture
 
@@ -11,19 +11,20 @@ devflow/
 ├── ⚡ context/                  # [2. Present / Active] Living Source of Truth & Active Work
 │   ├── project-overview.md     # Primary source of truth for project architecture and tech stack
 │   ├── coding-standards.md     # Engineering, code quality, TDD, and testing standards
-│   ├── ai-interaction.md       # AI agent interaction rules, dual-track flow, and Thai defaults
+│   ├── ai-interaction.md       # AI agent interaction rules, unified living spec flow, and Thai defaults
 │   ├── findings.md             # Open and resolved audit findings ledger (P0-P3)
+│   ├── glossary.md             # Domain glossary and architecture vocabulary
 │   ├── current-stage.md        # Active state pointer and run tracker
-│   ├── current-feature.md      # Fast-Track Single Living Spec (Active work / stub when idle)
-│   └── current-run/            # Deep-Track Active Run folder (Temporary during 10-70 execution)
+│   └── current-feature.md      # Single Living Spec (Active work / stub when idle)
 │
 ├── 📦 history/                  # [3. Past / Completed] Permanent Delivery & Release Archives
-│   ├── features/               # Completed features, architecture migrations, tooling (xxx-slug.md or xxx-slug/)
+│   ├── features/               # Completed features, architecture migrations, tooling (xxx-slug.md)
 │   ├── fixes/                  # Completed bug fixes, hotfixes, security patches (xxx-slug.md)
 │   ├── rollbacks/              # Completed feature reversals (YYYY-MM-DD-xxx-slug.md)
 │   └── HISTORY.md              # Master release ledger summary table
 │
-└── 🔍 discoveries/              # Pre-delivery discovery records (DISC-YYYYMMDD-NNN-slug/00-explore.md)
+├── 🔍 discoveries/              # Pre-delivery discovery records (DISC-YYYYMMDD-NNN-slug/discovery.md)
+└── 🏛️ decisions/                # Architecture Decision Records (ADR-xxx-slug.md)
 ```
 
 ---
@@ -31,9 +32,9 @@ devflow/
 ## Running ID Naming Convention
 
 ### 1. Standard Running IDs
-- **Format**: `xxx-slug` (e.g. `001-setup-auth`, `021-categorized-history-and-clean-living-spec-architecture`)
+- **Format**: `xxx-slug` (e.g. `001-setup-auth`, `053-unify-deep-and-fast-track-model`)
 - **Prefix Removal**: The legacy `RUN-` prefix is discontinued in favor of clean 3-digit sequential numbering.
-- **Git Branch Standard**: `feature/{xxx-slug}` or `fix/{xxx-slug}`.
+- **Git Branch Standard**: `feature/{xxx-slug}` or `fix/{xxx-slug}` (or specific release branches such as `2.5.0`).
 
 ### 2. Sub-Feature Running IDs (`xxx[a-z]-slug`)
 - **Format**: `xxx[a-z]-slug` (e.g. `038a-backend-schema-and-api`, `038b-frontend-ui-and-state`)
@@ -56,6 +57,6 @@ When detected during `/feature` or `/brief`, the AI triggers the **Interactive S
 
 ## Single Active Run Rule (One Thing at a Time)
 
-1. Only **one active run** is permitted at any given time across both Fast-Track and Deep-Track.
-2. Before opening a new run (`/feature`, `/fix`, or `10-define`), the AI checks `current-stage.md` and `current-feature.md`.
-3. If an active run is in progress, the AI **blocks** starting a new task and requires closing the active run via `/complete` or `70-deliver` (or explicitly cancelling/rolling back).
+1. Only **one active run** is permitted at any given time in `current-feature.md`.
+2. Before opening a new run (`/feature` or `/fix`), the AI checks `current-stage.md` and `current-feature.md`.
+3. If an active run is in progress, the AI **blocks** starting a new task and requires closing the active run via `/complete` (or explicitly cancelling/rolling back).