@jakkrichm/create-nexus-devflow 2.17.1 → 2.17.3

package/template/devflow/30-planning/project-plan.md

@@ -1,79 +0,0 @@
-# 🗺️ Project Plan (User-Owned Architectural Vision)
-
-> **Document Type**: Project Plan (User-Owned)  
-> **Purpose**: แหล่งความจริงหลัก (Single Source of Truth) สำหรับวิสัยทัศน์ผลิตภัณฑ์ สถาปัตยกรรมระบบ มาตรการความปลอดภัย กฎเกณฑ์การส่งมอบ และแผนงานพัฒนาต่อยอด ถูกนำไปประมวลผลเป็น `devflow/context/project-overview.md` ผ่านคำสั่ง `/overview`
-
----
-
-## 1. Product Vision & Problem Statement
-
-- **What this is**: **Nexus-DevFlow** คือระบบ **Agentic Workflow Layer & Pair Programming Operating System** ที่เชื่อมต่อระหว่างนักพัฒนา (Human Developer) และปัญญาประดิษฐ์ (AI Coding Agents เช่น Google Antigravity, Claude Code, OpenAI Codex, Cursor, GitHub Copilot) เพื่อยกระดับการพัฒนาซอฟต์แวร์สู่มาตรฐานระดับวิศวกรรมสากล
-- **Target Audience**:
-  - นักพัฒนาเดี่ยว (Solo Developers) ที่ต้องการความเร็วสูงแต่ยังคงมีระเบียบวินัยและหลักฐานการทดสอบที่ชัดเจน
-  - ทีมพัฒนาและองค์กร (Engineering Teams & Tech Leads) ที่ต้องการมาตรฐานการส่งมอบโค้ดที่ตรวจสอบได้ (Traceable), ตรวจสอบย้อนหลังได้ (Auditable) และไม่มีปัญหาโค้ดตีกัน (Zero Merge Conflict)
-- **Core Value Proposition**:
-  - **The 3-Pillars Model**: จัดระเบียบบริบทเป็น 3 เสาหลักอย่างชัดเจน — *🔮 Future (Inbox `ideas.md`)* ➔ *⚡ Present (Living Context `devflow/context/`)* ➔ *📦 Past (Categorized History `devflow/history/`)*
-  - **Single Living Spec Delivery Model**: งานทุกขนาดใช้วงจรเดียว `/feature` (หรือ `/fix`) ➔ `/implement` ➔ `/check` ➔ `/complete` โดยเพิ่มความลึกของสเปกและหลักฐานตามความซับซ้อนของงาน
-  - **Hard Quality Gates**: ระบบปฏิเสธการปล่อยงานเมื่อไม่ผ่านเกณฑ์การทดสอบ หรือมีข้อบกพร่องความปลอดภัยค้างอยู่
-
----
-
-## 2. Architecture & Tech Stack
-
-- **Runtime & Language**: Node.js (>=18.17.0), TypeScript (Strict ESM-First `"type": "module"`)
-- **Persistence & State**:
-  - Markdown-First Architecture พร้อม Type-Safe Schema Validation (Zod)
-  - Git-Backed History Archive (`devflow/history/features/`, `devflow/history/fixes/`, `devflow/history/rollbacks/`, `HISTORY.md`)
-  - Local State Management & Backup Snapshots (`.nexus/`)
-- **Key Modules & Subsystems**:
-  - **Distribution CLI & Package**: `packages/create-nexus-devflow` (Scaffolding, Doctor, Status, Update, Gatekeeper)
-  - **Interactive Web Dashboard**: Embedded Local Webview Dashboard (`/dashboard`) พร้อม Living Spec Visualizer และ Real-time Snapshot
-  - **Gatekeeper Engine**: ระบบตรวจสอบคุณภาพโค้ดและ Finding Blockers (`nexus-devflow check-gate`)
-  - **Model Context Protocol (MCP) Server**: JSON-RPC Hub สำหรับเชื่อมต่อ AI Agents แบบ Type-Safe
-  - **Dynamic Context Slicer**: ระบบจัดสรรและตัดตอนบริบทแบบ Just-In-Time (JIT) เพื่อประหยัด Token
-- **Integration Points & AI Adapters**:
-  - Google Antigravity & OpenAI Codex (`.agents/skills/`)
-  - Claude Code (`.claude/skills/`)
-  - Model Context Protocol (`@modelcontextprotocol/sdk`)
-
----
-
-## 3. Constraints, Defensive Guardrails & Non-Goals
-
-- **5 เสาหลักมาตรการป้องกันความเสี่ยง (Hard Defensive Guardrails)**:
-  1. *Hard Quality Gates & Git Hooks*: บล็อกการ Commit ทันทีหาก Spec ไม่ครบ หรือมี `P0/P1 Finding` ค้างอยู่ในสถานะ `open`
-  2. *Model Context Protocol (MCP)*: บังคับใช้ Typed Function Calling เพื่อป้องกันความเสียหายจากการ Parse ข้อความ Markdown
-  3. *Branch-Scoped Context Isolation*: แยกโฟลเดอร์ State ตาม Git Branch ใน `.nexus/branches/<name>/` ป้องกัน Merge Conflict เมื่อทำงานเป็นทีม
-  4. *Dynamic Context Slicing*: ส่งเฉพาะบริบทที่จำเป็นต่อ Stage นั้นๆ เข้าสู่ AI ลด Token Bloat 60–70%
-  5. *State Drift Reconciler*: ตรวจจับความไม่สอดคล้องระหว่าง Git Diffs กับ Spec Tasks และเสนอทางเลือก Auto-Sync ทันที
-- **Non-Goals**:
-  - ไม่ใช่ Proprietary IDE หรือ Closed Cloud SaaS — DevFlow เป็น Transparent Git-Native Layer ที่ฝังตัวในโปรเจกต์ใดก็ได้
-  - ไม่ใช่ Auto-GPT ที่ปล่อยให้ AI เขียนโค้ดตามใจโดยไม่มี Human-in-the-Loop Review Gates
-- **Delivery Rules**:
-  - เคร่งครัดใน TDD Mandate: โค้ดที่เพิ่มหรือแก้ไขต้องมี Automated Unit Tests เสมอ
-  - ห้ามข้ามขั้นตอน Verification: ต้องมีหลักฐานเชิงประจักษ์ (Empirical Proof) ใน `/check` ก่อนอนุมัติ `/complete`
-
----
-
-## 4. Key Milestones & Evolution Roadmap
-
-- **🚀 Milestone 1: Hard Quality Gates & Pre-commit Enforcement**
-  - ติดตั้ง `check-gate` เข้าสู่ Git Pre-commit Hooks และ CI Pipeline
-  - บล็อกการส่งมอบเมื่อมี Unchecked Tasks หรือ P0/P1 Blockers
-- **⚡ Milestone 2: DevFlow MCP Server Hub & Type-Safe Schemas (`IDEA-004`)**
-  - พัฒนา MCP Server ผ่าน JSON-RPC สำหรับ Antigravity, Claude, Codex, Cursor
-  - ใช้ Zod Schema ควบคุมการอัปเดต Task, Findings, และ Stage State 100% Type-safe
-- **🌿 Milestone 3: Branch-Scoped Context Isolation & Dynamic Router**
-  - รองรับการเก็บ State แยกตาม Git Branch ป้องกัน Merge Conflict ในทีม
-  - ระบบ Auto-Cleanup ลบ Branch State หลังจบ `/complete` และย้ายเข้าสู่ History
-- **✂️ Milestone 4: JIT Context Slicing & Token Budgeting Engine**
-  - ปรับระบบส่ง Context ให้ AI ตาม Stage แบบไดนามิก ประหยัด Token 70%
-  - ควบคุมขนาด `project-overview.md` ไม่ให้เกินงบประมาณ Token
-- **🔄 Milestone 5: Git Diff Reconciler & Self-Healing State**
-  - ตรวจจับความคลาดเคลื่อนระหว่างการแก้โค้ดของมนุษย์กับ Living Spec
-  - ระบบ Smart Reconciliation แจ้งเตือนและซิงค์สเปกอัตโนมัติ
-- **🖥️ Milestone 6: IDE Native Extension & Visual Kanban Studio**
-  - ส่วนขยายบน VS Code / Antigravity Webview สำหรับควบคุม DevFlow ครบวงจรใน IDE
-- **🤖 Milestone 7: Multi-Agent Swarm Orchestration & Semantic Code RAG**
-  - ระบบประสานงาน Subagents หลายตัว (Coder, QA, Auditor) ทำงานขนานกัน
-  - Local Dependency Graph & Semantic Code Search เพื่อดึงบริบทที่แม่นยำสูงสุด

package/template/devflow/40-tasks/README.md

@@ -1,11 +0,0 @@
-# ⚡ 40-tasks: Active Living Spec Workspaces
-
-This directory contains active, isolated task workspaces (`{xxx-slug}/`) during development.
-
-Each active task folder contains:
-- `spec.md` - Task-isolated living specification and implementation checklist
-- `stage.md` - Lifecycle stage tracker (`defined`, `in-progress`, `checked`, `verified`)
-- `findings.md` - Dedicated findings ledger for audit and verification proof
-- `review.md` - Optional independent review request and receipt
-
-When a task is completed via `/complete`, its spec is archived to `devflow/50-history/features/` (or `fixes/`, `rollbacks/`) and the active folder in `40-tasks/` is cleanly removed.

package/template/devflow/60-docs/migration-guide-decade-numbered.md

@@ -1,93 +0,0 @@
-# คู่มือการย้ายโครงสร้างโฟลเดอร์สู่ Decade-Numbered Stages (Migration Guide)
-
-> **DevFlow Version**: 2.16.5+  
-> **Topic**: การจัดระเบียบโฟลเดอร์ `devflow/` ตามลำดับขั้นตอนด้วย Decade-Numbered Stages และการอัปเกรดจากโครงสร้างเดิม
-
----
-
-## 🌟 1. สถาปัตยกรรมโฟลเดอร์ Decade-Numbered Stages
-
-เพื่อแก้ปัญหาโฟลเดอร์ใน `devflow/` กระจัดกระจายและไม่มีตัวเลขจัดเรียงสายตาใน IDE ทาง DevFlow ได้แนะนำโครงสร้าง **Decade-Numbered Stages Structure** (`00-`, `10-`, `20-`, ...) ที่ช่วยให้ทั้งผู้ใช้งานและ AI Agent ไล่ลำดับขั้นตอนการพัฒนาได้อย่างเป็นธรรมชาติ:
-
-```text
-devflow/
-├── config.json                     # Root configuration
-├── .state/                         # Runtime state (run.json - Git ignored)
-├── .vendor/                        # External vendor skills (bughunter, ponytail, ฯลฯ)
-│
-├── 00-context/                     # [Foundation & Source of Truth]
-│   ├── project-overview.md         # Living overview (สถาปัตยกรรม & tech stack ล่าสุด)
-│   ├── coding-standards.md         # กฎระเบียบและมาตรฐานการเขียนโค้ด
-│   ├── ai-interaction.md           # ข้อกำหนดการทำงานร่วมกับ AI Agent
-│   └── glossary.md                 # พจนานุกรมศัพท์เฉพาะของระบบ
-│
-├── 10-ideation/                    # [Input & Reference Ingestion]
-│   ├── ideas.md                    # บันทึกไอเดียใหม่ (Idea Inbox)
-│   ├── inbox/                      # ไฟล์ดิบจากภายนอก (PDF, Excel, Word, ภาพ)
-│   └── reference/                  # เอกสารที่แปลงเป็น Markdown สะอาดพร้อมใช้งาน
-│
-├── 20-discovery/                   # [Analysis, Exploration & Architecture]
-│   ├── analysis/                   # ผลการวิเคราะห์ System Analyst (/analyze)
-│   ├── discoveries/                # Pre-flight Spikes & Research (/discovery)
-│   ├── decisions/                  # บันทึกการตัดสินใจ ADRs (/grill)
-│   ├── research/                   # เอกสารวิจัยเชิงลึกและ Benchmark
-│   ├── 21-prototype/               # (Optional: Static UI mockups / prototype)
-│   └── 22-diagrams/                # (Optional: System & Architecture Diagrams)
-│
-├── 30-planning/                    # [Roadmap & Master Plans]
-│   ├── project-plan.md             # Master Roadmap & Milestones
-│   └── build-plan.md               # Master Delivery Checklist
-│
-├── 40-tasks/                       # [Active Living Spec Workspaces]
-│   └── {xxx-slug}/                 # Active task workspace (สร้างตอนทำฟีเจอร์/แก้บั๊ก)
-│       ├── spec.md                 # Task-Isolated Living Spec
-│       ├── stage.md                # ตัวชี้สถานะ Stage
-│       ├── findings.md             # บันทึกบั๊ก/Audit ประจำงาน
-│       └── tickets/                # Tracer-bullet tickets ย่อย
-│
-├── 50-history/                     # [Shipped & Delivered Archives]
-│   ├── HISTORY.md                  # Release Ledger สรุปภาพรวมประวัติ
-│   ├── features/                   # ฟีเจอร์ที่ส่งมอบแล้ว
-│   ├── fixes/                      # บั๊กที่แก้แล้ว
-│   └── rollbacks/                  # ฟีเจอร์ที่ถูก rollback
-│
-└── 60-docs/                        # [Documentation & System Playbooks]
-    └── playbooks/                  # Interactive HTML Playbooks (5W1H)
-```
-
----
-
-## ⚡ 2. จุดเด่นของการใช้เลขทศวรรษ (Decade Convention: `00-`, `10-`, `20-`)
-
-1. **ลำดับสายตาใน Editor สวยงาม**: เรียงตามลำดับความก้าวหน้าของโครงการ
-2. **ขยาย Sub-stages ในอนาคตได้ง่าย (Future-Proof)**: สามารถสร้างโฟลเดอร์แทรก เช่น `21-prototype`, `22-diagrams` ได้โดยไม่ต้องแก้เลขนำหน้าของโฟลเดอร์อื่น
-3. **ตัดโฟลเดอร์ Legacy ออก 100%**: ลบโฟลเดอร์ `devflow/runs/` ที่ไม่ได้ใช้งานตั้งแต่ v1.x ออกอย่างปลอดภัย
-
----
-
-## 🚀 3. วิธีการ Migrate อัตโนมัติ
-
-### 1) รันอัตโนมัติผ่านคำสั่ง `update` (แนะนำที่สุด):
-เมื่อโปรเจกต์ Client สั่งอัปเดตเวอร์ชัน DevFlow ด้วยคำสั่ง:
-```bash
-npx nexus-devflow update
-```
-ระบบจะตรวจจับโครงสร้างโฟลเดอร์อัตโนมัติ:
-* **หากยังเป็นโครงสร้างเดิม (Legacy)**: ระบบจะรันกระบวนการ `migrate-structure` ให้อัตโนมัติทันที พร้อมย้ายไฟล์เข้า `00-`, `10-`, `20-`, `30-`, `40-`, `50-`, `60-` และลบ `devflow/runs/`
-* **หากเป็นโครงสร้าง Decade-Numbered อยู่แล้ว**: ระบบจะไม่ทำอะไรกับโฟลเดอร์ (No-op) และดำเนินการอัปเดตโค้ดต่อไปอย่างปลอดภัย
-
-### 2) สั่ง Migrate ด้วยตัวเองโดยตรง:
-หากต้องการย้ายโครงสร้างทันทีโดยไม่อัปเดตส่วนอื่น สามารถสั่งได้ผ่านคำสั่ง:
-```bash
-npx nexus-devflow migrate-structure
-```
-
-
----
-
-## 🛡️ 4. การรองรับ Client เวอร์ชันเก่า (Zero-Breaking Compatibility)
-
-ระบบ DevFlow มีกลไก **Dynamic Workspace Path Resolver** (`resolveWorkspacePaths`) ที่จะ:
-1. ตรวจสอบว่าโปรเจกต์ใช้โครงสร้าง Decade-Numbered หรือไม่ (มี `devflow/00-context` หรือไม่)
-2. หากไม่พบ จะ **Fallback กลับไปหา Path เดิม (`devflow/context/`, `devflow/history/`) อัตโนมัติ 100%**
-3. โปรเจกต์เก่าที่ยังไม่ได้ Migrate จึงยังคงรันคำสั่งสถานะ, ตรวจสอบคุณภาพ, และบิวด์ได้ตามปกติโดยไม่มีข้อผิดพลาด