@jakkrichm/create-nexus-devflow 2.17.2 → 2.17.4

package/template/devflow/project-plan.md

@@ -1,79 +1,52 @@
-# 🗺️ Project Plan (User-Owned Architectural Vision)
+# Project Plan
 
-> **Document Type**: Project Plan (User-Owned)  
-> **Purpose**: แหล่งความจริงหลัก (Single Source of Truth) สำหรับวิสัยทัศน์ผลิตภัณฑ์ สถาปัตยกรรมระบบ มาตรการความปลอดภัย กฎเกณฑ์การส่งมอบ และแผนงานพัฒนาต่อยอด ถูกนำไปประมวลผลเป็น `devflow/context/project-overview.md` ผ่านคำสั่ง `/overview`
+> **Document Type**: Project Plan (User-Owned)
+> **Purpose**: แหล่งความจริงหลัก (Single Source of Truth) สำหรับวิสัยทัศน์ผลิตภัณฑ์ สถาปัตยกรรมระบบ ขอบเขตการทำงาน และข้อกำหนดทางเทคนิค
+> **Workflow**: กรอกข้อมูลให้ครบถ้วนแล้วรัน `/overview` เพื่อประมวลผลเป็น `project-overview.md`
 
 ---
 
-## 1. Product Vision & Problem Statement
+## 1. Problem - What problem are we solving?
 
-- **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**: ระบบปฏิเสธการปล่อยงานเมื่อไม่ผ่านเกณฑ์การทดสอบ หรือมีข้อบกพร่องความปลอดภัยค้างอยู่
+- **Core Problem**: [ระบุปัญหาหลักที่ผู้ใช้กำลังเผชิญ]
+- **Main Purpose**: [ระบุเป้าหมายหลักของระบบ]
 
 ---
 
-## 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`)
+## 2. Users - Who is this for?
+
+- **Primary Audience**: [เช่น Solo Developers, Content Creators]
+- **Secondary Audience (Later)**: [เช่น ทีมงานองค์กร, ลูกค้าปลายทาง]
+- **User Personas & Access Tiers**:
+  - `Anonymous / Guest`: [สิทธิ์การใช้งานทั่วไป]
+  - `Authenticated User`: [สิทธิ์การใช้งานหลัก]
+  - `Admin`: [สิทธิ์การจัดการระบบ]
+
+---
+
+## 3. Features - What does v1 need?
+
+### Core MVP Features (v1):
+- **Feature 1**: [คำอธิบายฟีเจอร์]
+- **Feature 2**: [คำอธิบายฟีเจอร์]
+- **Feature 3**: [คำอธิบายฟีเจอร์]
+
+### Later / Post-MVP (Not in v1):
+- [เช่น ระบบสมัครสมาชิกและ Billing]
+- [เช่น การส่งออกข้อมูลปริมาณมาก]
 
 ---
 
-## 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. Data - What are we storing?
+
+- **Core Entities**:
+  - [Entity 1]: [Attributes & Purpose]
+  - [Entity 2]: [Attributes & Purpose]
 
 ---
 
-## 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 เพื่อดึงบริบทที่แม่นยำสูงสุด
+## 5. Technology Stack & Constraints
+
+- **Language / Framework**: [เช่น Node.js, TypeScript, Next.js / Express]
+- **Database**: [เช่น SQLite, PostgreSQL]
+- **Hosting / Deployment**: [เช่น Local CLI, Vercel, Render, Docker]

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/docs/playbooks/{skill}.html` adhering to the **Paper/Ink Light Theme Standard** (`data-theme="light"`, teal accent, ruler corner, terminal mockup UI, and a real diagram). Reuse `devflow/docs/playbooks/template.html` when present; otherwise build the standalone page using these conventions.
+     - **First Run**: Render the comprehensive 5W1H playbook in chat and write the complete HTML report to `devflow/docs/playbooks/{skill}.html`.
+     - **Subsequent Invocations (Delta Updates & Zero Token Bloat)**: If `devflow/docs/playbooks/{skill}.html` already exists:
+       - Inspect the existing HTML file and compute the diff/delta against the current repository state (e.g., new file paths, modified endpoints, or newly installed vendor assets).
+       - DO NOT repeat unchanged boilerplate or full static content in chat.
+       - Provide a concise **Delta Summary** in chat (highlighting what changed, new recommendations, or newly available commands).
+       - In-place update `devflow/docs/playbooks/{skill}.html` with the fresh timestamp and state.
+       - Provide a clickable link to the actual resolved output file using the active client's supported local-file link format.
+   - **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/runs/.gitkeep

@@ -0,0 +1 @@
+