@jakkrichm/create-nexus-devflow 2.17.6 → 2.17.7

package/template/devflow/reference/help-playbook-protocol.md

@@ -5,14 +5,14 @@
    - **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.
+      - **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.

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 (5 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/`).
-- `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 (20 Skills)
-- `devflow`: Interactive workspace inspector and intent router.
-- `doctor`: Read-only health check for setup, adapters, and workflow drift.
-- `explore`: Fast read-only query answering and codebase orientation without writing files.
-- `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
-```