@jakkrichm/create-nexus-devflow 2.0.16 → 2.0.18

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

@@ -1,35 +1,122 @@
-# AI Interaction Guidelines for DevFlow
+# AI Interaction Guidelines for Nexus-DevFlow
 
-> **DevFlow is an agentic workflow layer**, overlaying on top of scaffolded or existing codebases.
+> **Nexus-DevFlow is an agentic workflow layer**, overlaying on top of scaffolded or existing codebases. Never run a framework scaffolder inside an initialized DevFlow directory.
 
-## Communication & Interaction
+---
 
-- Be concise and direct in communication.
-- Explain technical trade-offs and non-obvious design decisions briefly.
-- Always confirm before performing major refactors or destructive operations.
-- Maintain markdown-first evidence for all stage activities.
+## 1. Communication & Principles
 
-## Artifact Language
+- **Be Concise and Direct**: State conclusions, status, and findings first; provide supporting context afterward.
+- **Explain Non-Obvious Decisions Briefly**: Highlight architectural trade-offs, edge-case rationale, or safety considerations in 1–2 sentences.
+- **Ask Before Destructive or Architectural Changes**: Always obtain explicit confirmation before deleting files, executing major refactors, or altering public interfaces.
+- **Don't Add Unplanned Scope**: Stick strictly to the Acceptance Criteria defined in the spec. Avoid adding "nice-to-have" features that were not requested.
+- **Preserve Existing Codebase Patterns**: Respect existing file structure, typing patterns, naming conventions, and deep module boundaries.
 
-- Default language for user-facing artifacts and summaries is Thai (`th`), while code, paths, and identifiers remain in English.
-- Use exact schema headings when validators check for specific contract sections.
+---
 
-## Output Formatting
+## 2. Output Formatting
 
-- Use GitHub-style markdown for clean scanning.
-- Use lists for steps, options, and findings.
-- Use tables for comparative matrices or stage summaries.
-- Use backticks for paths, filenames, identifiers, and CLI commands.
+Format every response for fast scanning and readability:
 
-## DevFlow Timeline Lifecycle
+- **Real Markdown, Not Prose Walls**: Use bold labels, concise bullet points, and blank lines between blocks.
+- **Enumerations Are Lists**: Numbered or bulleted lists for sequential steps or findings, never inline runs crammed into paragraphs.
+- **Tables for Comparative Matrices**: Use markdown tables when comparing status, options, test results, or trade-offs.
+- **Backticks for Code References**: Wrap file paths, variable names, functions, CLI flags, and commands in backticks (e.g. `current-feature.md`, `npm run check`).
+- **Clickable File Links**: Use GitHub-style markdown links with `file://` scheme (e.g. `[current-feature.md](file:///d:/path/to/current-feature.md)`).
+- **Lead With the Result**: State pass/fail status or completed action before presenting logs.
+
+---
+
+## 3. Dual-Track Workflow Lifecycle (The 3-Pillars Model)
 
 ```text
-/00-Discover -> /10-Define -> /20-Spec -> /30-Plan -> /40-Execute -> /50-Verify -> /60-Report -> /70-Release
+devflow/
+├── 🔮 ideas.md        # [Future] Idea Inbox
+├── ⚡ context/         # [Present] Living Spec (current-feature.md) & Active State
+└── 📦 history/         # [Past] features/, fixes/, rollbacks/, and HISTORY.md
 ```
 
-- Run `/00-Discover` to explore requests under a Discovery ID.
-- Run `/10-Define` to set delivery boundaries and allocate Running IDs.
-- Run `/20-Spec` and `/30-Plan` to establish formal delivery specifications and execution plans.
-- Run `/40-Execute` for step-by-step code implementation with evidence.
-- Run `/50-Verify`, `/60-Report`, and `/70-Release` for quality verification, reporting, and release packaging.
-- Use **Fast-Track / Quick-Fix mode** for minor hotfixes to skip heavy ceremony while keeping test evidence.
+### 🏎️ 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.
+
+---
+
+### 🏗️ Track 2: Deep-Track (Architect Mode — 8 Steps)
+*Recommended for large architectural epics, database migrations, security audits, and multi-agent coordination.*
+
+```text
+00-discover ➔ 10-define ➔ 20-spec ➔ 30-plan ➔ 40-execute ➔ 50-verify ➔ 60-report ➔ 70-release
+```
+
+1. `00-discover`: 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-release`: Release packaging, git merge, archives `devflow/context/current-run/` ➔ `devflow/history/{features|fixes|rollbacks}/{xxx-slug}/`, and closes the run.
+
+---
+
+## 4. Standalone HTML Reporting Policy
+
+> [!IMPORTANT]
+> **No Auto-Generated HTML**: Mainline stages (`/complete` and `60-report`) strictly output Markdown only.
+> When an interactive web dashboard is desired for presentation or sharing, invoke the standalone companion command:
+> `/report:html` (or `npm run report:html -- {ID}`).
+
+---
+
+## 5. Resuming After Context Clear
+
+Progress lives in persistent files, not in transient chat history:
+
+- In Fast-Track: `devflow/context/current-feature.md` maintains ticked checklist boxes `- [x]`.
+- In Deep-Track: `devflow/context/current-run/` maintains stage markdown files.
+- In Git: Commits, branches, and working tree maintain the code history.
+- When starting a fresh session after a context clear, run `devflow` or inspect `current-stage.md` to pick up immediately from the next pending step.
+
+---
+
+## 6. Single Active Run Guardrail (One Thing at a Time)
+
+- Only one active run is allowed at a time across both Fast-Track and Deep-Track.
+- The AI will actively block opening a new feature or fix until the current one is completed with `/complete` or `70-release` (or explicitly rolled back/cancelled).
+
+---
+
+## 7. Branching & Git Conventions
+
+- **Branch Naming**: `feature/{xxx-slug}` or `fix/{xxx-slug}`.
+- **Commit Messages**: Conventional imperative format (e.g. `feat(uninstall): add clean eject CLI command`, `fix(parser): handle undefined metadata field`).
+- **No AI Attribution in Commits**: Never include "Generated with AI" or agent metadata in Git commit logs.
+- **Explicit Approval for Push & Deploy**: Merge approval is strictly separate from consent to `git push` to remote repositories or deploy to production.
+
+---
+
+## 8. Autopilot Policy
+
+- `autopilot` is an explicit opt-in command (`/autopilot`). Never suggest it as the default next action.
+- When invoked, it runs one bounded spec/plan/implement/verify pass.
+- Autopilot **MUST stop** before `/complete`, merge, push, deploy, or any destructive action.

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

@@ -1,40 +1,131 @@
-# Coding Standards & Guidelines
+# Coding Standards & Engineering Guidelines
 
-General engineering standards for code, tests, and documentation in Nexus-DevFlow.
+> Engineering standards, architecture conventions, testing policies, and code quality guidelines for **Nexus-DevFlow**.
 
-## 1. Code Quality & Architecture
+---
 
-- Write clear, self-documenting code with single-responsibility functions.
-- Avoid unnecessary complexity (prefer simple solutions over indirect abstractions).
-- Maintain type safety and static validation across module boundaries.
-- Treat `project-overview.md` as the single source of truth for concrete data models and entity definitions.
+## 1. TypeScript & Runtime Standards
 
-## 2. Testing & Empirical Proof Standards
+- **Strict Mode Enabled**: Always adhere to strict TypeScript compilation (`"strict": true` in `tsconfig.json`).
+- **No `any` Types**: Prohibit the use of `any`. Use precise interface definitions, generics, or `unknown` with runtime type narrowing.
+- **Type Definitions**: Define clear interfaces and types for all function options, CLI arguments, parse results, and data payloads.
+- **Type Inference vs. Explicit Types**: Use type inference for straightforward local variables, and explicit return types for public functions, exports, and complex utilities.
+- **ESM-First Architecture**: Use native Node.js ESM (`"type": "module"`). Always use explicit `node:` protocol imports (e.g. `node:fs`, `node:path`, `node:os`, `node:child_process`).
 
-- **Unit Test Mandate**: Any logic modification or bug fix must be accompanied by new or updated unit tests.
-- **Empirical Proof Contract**: Never claim "passed", "verified", or "working" without citing exact command outputs, test run reports, route responses, logs, or screenshots.
-- **Manual Try Guide**: Every delivery run must provide a human-testable Try Guide ("Where to go", "What to click", "What to expect") for manual validation.
+---
 
-## 3. Findings Ledger & Quality Gates (`findings.md`)
+## 2. CLI Architecture & Engineering Principles
 
-- All audit, security, and verification issues must be tracked in `devflow/context/findings.md`.
+- **Separation of Concerns (Deep Modules)**:
+  - Keep CLI entry points (`bin/create-nexus-devflow.ts`) thin: handle argument parsing, option normalization, and terminal formatting.
+  - Encapsulate all core business logic, filesystem operations, and parsing inside modular libraries (`lib/current-work.ts`, `lib/findings.ts`, `lib/git.ts`, `lib/uninstall.ts`, `lib/update.ts`).
+- **Safety Flags & Idempotency**:
+  - Destructive or mutating operations (e.g. `uninstall`, `update`, `install`) must support safety flags:
+    - `--dry-run`: Preview actions and affected files without modifying the disk.
+    - `-y`, `--yes`, `-f`, `--force`: Non-interactive mode for CI/CD automation.
+    - `--json`: Machine-readable structured output for integrations.
+- **Cross-Platform Compatibility**:
+  - Never assume POSIX-only paths or Windows-only backslashes. Always use `path.join()`, `path.resolve()`, or normalize paths with forward slashes for URLs and identifiers.
+  - Handle Windows permission quirks (EPERM, EBUSY) with graceful retries or clear explanatory messages.
+- **Terminal UX & ANSI Formatting**:
+  - Provide clear, high-contrast, and aesthetic terminal outputs.
+  - Automatically respect `process.stdout.isTTY` and support `--no-color` / `NO_COLOR` environment variables.
+
+---
+
+## 3. File Organization & Directory Structure
+
+```text
+nexus-devflow/
+├── .agents/skills/             # Codex & Google Antigravity skill definitions
+├── .claude/skills/             # Claude Code mirrored skill adapters
+├── .nexus/                     # Metadata tracking & upstream baseline ledger
+├── devflow/                    # Framework workspace context, runs, and discoveries
+│   ├── context/                # Living source-of-truth context files
+│   ├── discoveries/            # Pre-delivery discovery records (00-discover.md)
+│   ├── runs/                   # Running delivery artifacts (current-feature.md / 00-70)
+│   ├── history/                # Master delivery archive (HISTORY.md)
+│   └── ideas.md                # Idea Inbox and backlog
+├── packages/
+│   └── create-nexus-devflow/   # Distribution npm package source
+│       ├── bin/                # CLI executable binaries
+│       ├── lib/                # Modular domain libraries
+│       └── test/               # Automated unit tests (*.test.ts)
+└── scripts/                    # Maintainer verification & automation scripts
+```
+
+---
+
+## 4. Naming Conventions
+
+- **Files & Directories**:
+  - Skills and command directories: `kebab-case` (e.g. `00-discover`, `report-html`, `sync-upstream`).
+  - Source modules and scripts: `kebab-case.ts` / `kebab-case.mjs` (e.g. `current-work.ts`, `check-devflow.ts`).
+  - Test files: `[module].test.ts` (e.g. `status.test.ts`, `uninstall.test.ts`).
+- **Identifiers**:
+  - Functions & methods: `camelCase` (e.g. `parseCurrentWork`, `applyUninstall`, `readProjectStatus`).
+  - Variables & properties: `camelCase`.
+  - Types & Interfaces: `PascalCase` without prefixes like `I` or `T` (e.g. `ProjectStatus`, `RunWorkSummary`).
+  - Constants & Enums: `SCREAMING_SNAKE_CASE` (e.g. `LEGACY_FEATURE_PATH`, `DEFAULT_ADAPTERS`).
+
+---
+
+## 5. Testing & Empirical Proof Standards
+
+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.
+- **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).
+- **3-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 (Manual / Scenario Proof)**: Concrete walkthrough steps ("Where to go", "What to run", "What to expect").
+
+---
+
+## 6. Findings Ledger & Quality Gates (`findings.md`)
+
+- All quality defects, security findings, or regression issues identified during review must be logged in `devflow/context/findings.md`.
 - **Finding State Machine**:
-  - `open`: Confirmed defect not yet repaired.
-  - `fixed`: Repaired in code, pending verification.
-  - `closed`: Verified in `50-verify` as completely resolved without regressions.
-  - `accepted`: Waived with recorded user rationale.
-  - `invalid`: Proven non-issue with concrete evidence.
-- **P0/P1 Blockers**: P0 and P1 findings in `open` or `fixed` status block `70-release` unconditionally. `fixed` status must be promoted to `closed` via `50-verify` re-examination.
-
-## 4. Git Workflow & Release Safety
- 
-- Commit messages follow conventional/imperative format (e.g., `feat(RUN-007): ...`).
-- Feature branches follow `feature/{slug}-{running-id}` or `fix/{slug}-{running-id}`.
-- **2-Stage Release Approvals**: Explicit consent to merge into `main` is strictly separate from consent to `git push` to remote repositories or deploy to production.
-
-## 5. Fast-Track & Quick-Fix Guidelines (Lean Mode)
-
-- For trivial bug fixes, typo corrections, or single-file non-architectural changes, developers and agents may use the **Quick-Fix Fast-Track**:
-  - Consolidate Discovery, Define, and Spec into an inline fix brief (`devflow/runs/{fix-id}/fix-brief.md`).
-  - Jump directly to `40-execute` (with reproduction unit test) ➔ `50-verify` ➔ `70-release`.
-  - Avoid creating heavy redundant documentation for changes under 20 lines of code while preserving Empirical Proof and Unit Test requirements.
+  - `open`: Confirmed issue waiting to be fixed.
+  - `fixed`: Repaired in code, pending QA re-verification.
+  - `closed`: Verified by QA as completely resolved without regressions.
+  - `accepted`: Formally waived with recorded user justification.
+- **P0/P1 Blockers**: Any P0 or P1 finding in `open` or `fixed` status unconditionally blocks `/complete` and `70-release`.
+
+---
+
+## 7. Error Handling & Exit Codes
+
+- Use structured `try / catch` blocks around filesystem and process operations.
+- Create meaningful, actionable error messages for the user (explain what failed and how to resolve it).
+- Exit cleanly with standard POSIX process exit codes:
+  - `0`: Successful execution.
+  - `1`: Validation failure, missing arguments, or runtime error.
+
+---
+
+## 8. Comments & Documentation Discipline
+
+Write code that explains itself; comment only what the code cannot say:
+
+- Comment the **why**, not the **what**. Avoid comments that simply rephrase the line of code.
+- Avoid noisy banner blocks, section divider lines (`// ====================`), or obvious step narrations.
+- Comments earn their place when documenting:
+  - Non-obvious architectural decisions.
+  - Upstream compatibility quirks or workarounds.
+  - Edge-case handling rationale.
+- Keep JSDoc minimal and useful: provide a one-line summary and document non-obvious parameters.
+
+---
+
+## 9. Writing & Language Conventions
+
+- **Default Communication & Artifacts**: Thai (`th`) for all generated markdown stage artifacts (`current-feature.md`, `00-discover.md`, etc.), explanations, and user interactions.
+- **Code & Identifiers**: English for all source code, variable names, file paths, CLI flags, and commit messages.
+- **Typography**: Do not use em dashes (`—`) in AI-generated commit messages or technical summaries; use standard hyphens (`-`) or colons.

package/template/devflow/context/current-feature.md

@@ -0,0 +1,3 @@
+# Current Feature
+
+_Nothing in progress. Run /feature, /fix, or /rollback to start._

package/template/devflow/context/current-stage.md

@@ -1,8 +1,8 @@
 # Current DevFlow Run Status
 
-- **Active Discovery ID**: None
-- **Active Running ID**: None
-- **Current Stage**: Idle (Ready for next run)
-- **Living Spec**: None
-- **Last Completed Run**: RUN-019-sync-upstream-status-cli-and-project-detection (2026-08-20)
-- **Last Updated**: 2026-08-20
+- **Active Discovery ID**: `None`
+- **Active Running ID**: `None`
+- **Current Stage**: `Idle (Ready for new /feature, /fix, /00-discover, or /10-define)`
+- **Living Spec**: `None`
+- **Last Completed Run**: `None`
+- **Last Updated**: `None`

package/template/devflow/context/findings.md

@@ -1,13 +1,13 @@
-# Audit Findings Ledger
+# Findings Ledger
 
-Summary of audit findings, quality checks, security bugs, and debt tracked across DevFlow runs.
+> **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-release`.
 
-## Open Findings
+---
 
-| ID | Severity | Category | Title | Discovered Run | Status |
-| :- | :--- | :--- | :--- | :--- | :--- |
-
-## Resolved Findings
-
-| ID | Severity | Category | Title | Resolved Run | Date |
-| :- | :--- | :--- | :--- | :--- | :--- |
+_No active findings recorded. QA and audit passes append findings here as they are discovered._

package/template/devflow/context/project-overview.md

@@ -1,41 +1,27 @@
-# Project Overview
+# Project Overview & Source of Truth
 
-Primary source of truth for the project context, architecture, tech stack, and active DevFlow stage status.
+> Living context artifact automatically synchronized with codebase reality and DevFlow delivery history.
+> Run `/onboard` (for new projects) or `/adopt` (for existing codebases) to populate this file.
 
-## Application Summary
+---
 
-- **Project Name**: Nexus-DevFlow
-- **Goal**: Agent-ready DevFlow 2.0 workflow layer framework with .agents and .claude adapter tooling, living context synchronization, and automated AI Blueprint upstream monitoring.
-- **Target Audience**: AI coding assistants (Google Antigravity, OpenAI Codex, Claude Code, Cursor) and software development teams building resilient agentic delivery workflows.
+## 1. Project Purpose & Target Users
+- Describe what this application does, who it is for, and the problems it solves.
 
-## Tech Stack
+## 2. Architecture & Directory Layout
+- Visual directory layout and overview of core modules.
 
-- **Core & Runtime**: Node.js (>=18.17 / Node 22), TypeScript 5.7, Node Next ESM (`"type": "module"`)
-- **Execution & Tooling**: `tsx` (TypeScript execute/test runner), `tsc` (Typecheck & compilation)
-- **Installer Package**: `@jakkrichm/create-nexus-devflow` (with `dist/` compilation pipeline)
-- **Documentation**: VitePress / Astro website under `website/` (GitHub Pages)
-- **Upstream Integration**: Automated GitHub Actions monitor (`.github/workflows/check-upstream.yml`) tracking `aiblueprinthq/ai-blueprint`
-- **Verification Gate**: `npm run check` (TypeScript typechecking, static contract validation, TF-IDF skill routing evaluations, installer unit tests, packed smoke tests)
+## 3. Technology Stack & Key Tooling
+- Frameworks, languages, databases, ORMs, package managers, and runtime environment.
 
-## Architecture & Key Modules
+## 4. Concrete Data Models & Entities
+- Core entities, database schemas, API interfaces, and types.
 
-- **Dual-Track Delivery Engine**:
-  - **Fast-Track (Blueprint Mode — 4 Steps)**: High-velocity spec loop (`/feature` or `/fix` ➔ `/implement` ➔ `/check` ➔ `/complete`) with Single Living Spec (`spec.md`).
-  - **Deep-Track (Architect Mode — 8 Steps)**: Full-lifecycle delivery pipeline (`00-discover` ➔ `10-define` ➔ `20-spec` ➔ `30-plan` ➔ `40-execute` ➔ `50-verify` ➔ `60-report` ➔ `70-release`).
-- **`packages/create-nexus-devflow/`**: Distribution CLI package with TypeScript compilation (`dist/bin/create-nexus-devflow.js`), atomic update engine (`lib/update.ts`), and prepack template bundler (`scripts/prepare-template.ts`).
-- **`.agents/skills/` & `.claude/skills/`**: 80 synchronized AI agent skills covering Dual-Track workflows and companion tools (`devflow`, `idea`, `report-html`, `try`, `doctor`, `overview`, `sync-upstream`, `ci`, `rollback`).
-- **`scripts/`**: Maintainer infrastructure (`check-devflow.ts`, `validate-framework.ts`, `smoke-package.ts`, `upstream-monitor.ts`, `evals/routing.ts`).
-- **`devflow/`**: Workspace state, discoveries, runs, ideas, context, reference contracts, and master release history ledger.
+## 5. Shipped Capabilities & Milestones
+- Verified features and components currently functional in the codebase.
 
-## Shipped Capabilities (Recent Milestones)
+## 6. Verified Commands & Developer Workflow
+- Dev Server, Build, Test, Lint, and Verify commands.
 
-- **`RUN-017` (2026-08-20)**: Separate Fast-Track skills (`/feature`, `/fix`) and rename Deep-Track stage 40 to `40-execute` to eliminate command collisions.
-- **`RUN-016` (2026-08-20)**: Quick Idea Capture and AI Feasibility Assessment (`/idea`) with centralized Idea Inbox (`devflow/ideas.md`).
-- **`RUN-015` (2026-08-20)**: Dual-Track Architecture (Fast-Track 4 Steps & Deep-Track 8 Steps) + Living Spec (`spec.md`) + Standalone HTML Reporting Policy.
-- **`RUN-014` (2026-08-20)**: Upgraded DevFlow to full TypeScript architecture (`tsconfig.json`, `tsx`, `tsc`, `dist/`), migrated AI Blueprint Upstream Monitor workflow to DevFlow, and established multi-lane verification matrix.
-
-## DevFlow Workspace Status
-
-- **Active Discovery ID**: None (Idle)
-- **Active Running ID**: `RUN-018-update-documentation-and-guides`
-- **Last Completed Run**: `RUN-017-split-spec-and-rename-40-execute`
+## 7. Known Architectural Focus Areas
+- Upcoming priorities, refactoring targets, or known technical considerations.

package/template/devflow/history/HISTORY.md

@@ -1,34 +1,19 @@
-# Nexus-DevFlow Master Release History Ledger
+# Master Release History Ledger
 
-This master ledger tracks all released delivery runs, milestones, and rollbacks in chronological order. Each entry is recorded during the `70-release` stage and links to its exact Git commit hash, release tag, and generated delivery artifacts.
+This master ledger tracks all released delivery runs, milestones, and rollbacks in chronological order. Each entry is recorded during `/complete` or `70-release` and links to its exact Git commit hash, release status, category, and archived delivery artifacts.
 
 ---
 
-## 📜 Release Log
+## 📜 Master Release Log
 
-| Release Date | Running ID | Title | Git Tag / Commit | Release Status | Report Link |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| 2026-08-20 | `RUN-019` | ซิงก์ฟีเจอร์ Status CLI, Project Detection, Unit Tests และ Upstream Baseline จาก AI Blueprint v0.9.1 | `HEAD` | `Released` | [`60-report.md`](../runs/RUN-019-sync-upstream-status-cli-and-project-detection/60-report.md) |
-| 2026-08-20 | `RUN-018` | อัปเดตคู่มือ เอกสาร และ Website Documentation ให้เป็นปัจจุบันและครอบคลุม Dual-Track Model ล่าสุด | `HEAD` | `Released` | [`spec.md`](../runs/RUN-018-update-documentation-and-guides/spec.md) |
-| 2026-08-20 | `RUN-017` | แยกคำสั่ง Fast-Track เป็น `/feature`, `/fix` และเปลี่ยน Deep-Track สเตจ 40 เป็น `40-execute` | `HEAD` | `Released` | [`spec.md`](../runs/RUN-017-split-spec-and-rename-40-execute/spec.md) |
-| 2026-08-20 | `RUN-016` | ระบบบันทึกไอเดียพร้อม AI วิเคราะห์ความเป็นไปได้ (`/idea`) และเชื่อมต่อกับ Status Backlog | `HEAD` | `Released` | [`spec.md`](../runs/RUN-016-idea-capture-inbox-and-status-integration/spec.md) |
-| 2026-08-20 | `RUN-015` | Dual-Track Architecture (Fast-Track 4 Steps & Deep-Track 8 Steps) + Living Spec (`spec.md`) + Standalone HTML Report Policy | `HEAD` | `Released` | [`spec.md`](../runs/RUN-015-fast-track-and-living-blueprint/spec.md) |
-| 2026-08-20 | `RUN-014` | ยกระดับสถาปัตยกรรม DevFlow สู่ TypeScript และย้ายระบบ Check AI Blueprint Upstream Monitor | `HEAD` | `Released` | [`60-report.md`](../runs/RUN-014-typescript-migration-and-upstream-monitor-for-devflow/60-report.md) |
-| 2026-08-20 | `RUN-013` | เพิ่ม Skill `/overview` และระบบ Living Context Sync สำหรับ Nexus-DevFlow | `e30375b` | `Released` | [`60-report.md`](../runs/RUN-013-add-overview-and-context-sync-skill/60-report.md) |
-| 2026-08-18 | `RUN-008` | ปรับปรุงโครงสร้าง Nexus-DevFlow ให้ Lean & Clean ยุบรวม Skills บริหารจัดการ History และ Safe Rollback | `be713ea` | `Released` | [`60-report.md`](../runs/RUN-008-lean-and-clean-devflow-optimization/60-report.md) |
-| 2026-08-18 | `RUN-007` | ยกระดับระบบ Nexus-DevFlow ด้วยวินัยและกลไกสำคัญจาก Blueprint | `e79528b` | `Released` | [`60-report.md`](../runs/RUN-007-integrate-blueprint-skills-enhancements/60-report.md) |
-| 2026-08-18 | `RUN-006` | Standardize Command Naming and Provider Invocation | `HEAD` | `Released` | [`60-report.md`](../runs/RUN-006-standardize-command-naming-and-provider-invocation/60-report.md) |
-| 2026-08-18 | `RUN-005` | Add DevFlow Prefix to Skill Descriptions | `HEAD` | `Released` | [`60-report.md`](../runs/RUN-005-add-devflow-prefix-to-skill-descriptions/60-report.md) |
-| 2026-08-18 | `RUN-004` | Add Autopilot Skill | `HEAD` | `Released` | [`60-report.md`](../runs/RUN-004-add-autopilot-skill/60-report.md) |
-| 2026-08-18 | `RUN-003` | Add Try, Rollback, CI, Brief Skills | `HEAD` | `Released` | [`60-report.md`](../runs/RUN-003-add-try-rollback-ci-brief-skills/60-report.md) |
-| 2026-08-18 | `RUN-002` | Add Onboard, Adopt, Doctor Skills | `HEAD` | `Released` | [`60-report.md`](../runs/RUN-002-add-onboard-adopt-doctor-skills/60-report.md) |
-| 2026-08-18 | `RUN-001` | Align DevFlow with Blueprint Architecture | `HEAD` | `Released` | [`60-report.md`](../runs/RUN-001-align-devflow-blueprint/60-report.md) |
+| Completed Date | Run ID | Category | Title | Git Commit | Status | Archive Link |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| _No shipped runs yet_ | - | - | Run `/feature` or `/00-discover` to start your first delivery run | - | - | - |
 
 ---
 
-## 🗄️ Run Lifecycle States
+## 🗄️ History Categories (The Core 3 Model)
 
-- **Active**: Currently executing in `devflow/runs/{running-id}-{slug}/` (tracked in `devflow/context/current-stage.md`).
-- **Released**: Finished `70-release`, merged, and logged in this master ledger.
-- **Archived**: Older historical runs moved to `devflow/history/archived-runs/` to maintain a clean workspace.
-- **Rolled Back**: Features safely reversed via `/rollback` with documented post-reversal verification.
+- **`features/`**: New user-facing features, enhancements, architecture migrations, refactoring, and tooling/infra.
+- **`fixes/`**: Bug fixes, hotfixes, regressions, security patches, and performance optimizations.
+- **`rollbacks/`**: Safe feature reversal and rollback execution records.

package/template/devflow/ideas.md

@@ -1,15 +1,19 @@
-# 💡 DevFlow Idea Inbox & Backlog
+# 🔮 Centralized Idea Inbox & Backlog
 
-บันทึกไอเดียที่รอดำเนินการ พร้อมบทวิเคราะห์ความเป็นไปได้เบื้องต้นจาก AI (บันทึกด้วยคำสั่ง `/idea "<text>"`)
+> Record, analyze, and prioritize feature ideas before starting active delivery.
+> Use the `/idea` command to quickly capture and evaluate new ideas.
 
 ---
 
-## 📌 Pending Ideas
+## 💡 Active Idea Inbox
 
-*(ยังไม่มีไอเดียค้างอยู่ — เพิ่มไอเดียใหม่ได้ด้วยคำสั่ง `/idea "<ข้อความไอเดีย>" หรือ `$idea "<text>"`)*
+| ID | Title | Value (1-5) | Feasibility (1-5) | Status | Notes |
+| :--- | :--- | :---: | :---: | :--- | :--- |
+| _No pending ideas_ | - | - | - | Use `/idea <your idea>` to capture | - |
 
 ---
 
 ## 📦 Archived / Shipped Ideas
 
-*(ไอเดียที่ถูกหยิบไปทำด้วย `/feature IDEA-xxx`, `/fix IDEA-xxx` หรือ `/00-discover IDEA-xxx` จะถูกย้ายมาบันทึกที่นี่)*
+| ID | Title | Shipped In | Completed Date |
+| :--- | :--- | :--- | :--- |

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

@@ -1,39 +1,39 @@
-# DevFlow 2.0 Running ID & Workspace Contract Reference
-
-## DevFlow Workspace Directory Structure
-
-All DevFlow framework context, active runs, templates, and history are consolidated under `devflow/`:
-
-- **Context (`devflow/context/`)**:
-  - `project-overview.md` - Primary source of truth for project architecture and stack.
-  - `coding-standards.md` - Development, code quality, and testing standards.
-  - `ai-interaction.md` - AI agent interaction rules and Thai artifact defaults.
-  - `current-stage.md` - Active stage run state.
-  - `findings.md` - Open and resolved audit findings ledger.
-
-- **Active Delivery Runs (`devflow/runs/{RUNNING_ID}/`)**:
-  - `10-define.md`
-  - `20-spec.md`
-  - `30-plan.md`
-  - `40-execute.md`
-  - `50-verify.md`
-  - `60-report.md` (and `60-report.html`)
-  - `70-release.md`
-
-- **Active Discoveries (`devflow/discoveries/{DISCOVERY_ID}-{slug}/`)**:
-  - `00-discover.md`
-
-- **History Archive (`devflow/history/`)**:
-  - `discoveries/` - Completed discovery archives.
-  - `runs/` - Completed delivery run archives.
-  - `reports/` - Completed stage reports.
-
-- **Reference Contracts (`devflow/reference/`)**:
-  - `running-id-contract.md`
-  - `stage-lifecycle-contract.md`
-
-## Mainline Lifecycle Rules
-
-1. Mainline stages move linearly: `/00-Discover` ➔ `/10-Define` ➔ `/20-Spec` ➔ `/30-Plan` ➔ `/40-Execute` ➔ `/50-Verify` ➔ `/60-Report` ➔ `/70-Release`.
-2. Companion commands (`Goal`, `Brainstorm`, `Research`, `Debug`, `PRD`, `Issue-Triage`, `Security-Review`, `Check-For-Updates`, `Help`) provide supporting context without replacing mainline stage numbers.
-3. Every stage produces markdown-first evidence in `devflow/runs/` before passing verification gates.
+# DevFlow 2.0 Running ID & 3-Pillars Workspace Contract
+
+## The 3-Pillars Workspace Architecture
+
+All DevFlow framework assets are organized into three clean pillars representing Future, Present, and Past:
+
+```text
+devflow/
+├── 🔮 ideas.md                 # [1. Future / Backlog] Centralized Idea Inbox with AI scoring
+│
+├── ⚡ 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
+│   ├── findings.md             # Open and resolved audit findings ledger (P0-P3)
+│   ├── 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)
+│
+├── 📦 history/                  # [3. Past / Completed] Permanent Delivery & Release Archives
+│   ├── features/               # Completed features, architecture migrations, tooling (xxx-slug.md or xxx-slug/)
+│   ├── 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-discover.md)
+```
+
+## Running ID Naming Convention
+
+- **Format**: `xxx-slug` (e.g. `001-setup-auth`, `021-categorized-history-and-clean-living-spec-architecture`)
+- **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}`.
+
+## 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-release` (or explicitly cancelling/rolling back).