@jakkrichm/create-nexus-devflow 2.5.0 → 2.6.1

package/README.md

@@ -1,6 +1,6 @@
 # @jakkrichm/create-nexus-devflow
 
-Install and manage **Nexus-DevFlow 2.0** — an agentic workflow layer supporting **The 3-Pillars Model & Dual-Track Delivery** into any web app, backend, or existing codebase.
+Install and manage **Nexus-DevFlow** — an enterprise-grade agentic workflow layer supporting **The 3-Pillars Model & Single Living Spec Model** into any web app, backend, or existing codebase.
 
 [![npm version](https://img.shields.io/npm/v/@jakkrichm/create-nexus-devflow?style=flat-square&color=155eef)](https://www.npmjs.com/package/@jakkrichm/create-nexus-devflow)
 [![Validate DevFlow](https://github.com/Jakkrich/nexus-devflow/actions/workflows/validate.yml/badge.svg)](https://github.com/Jakkrich/nexus-devflow/actions/workflows/validate.yml)
@@ -25,79 +25,92 @@ npx @jakkrichm/create-nexus-devflow@latest
 ```
 
 The installer overlays the DevFlow workflow layer into your workspace:
-- `AGENTS.md` & `CLAUDE.md` (Universal AI guidelines)
-- `.agents/skills/` (28 Core Skills for Google Antigravity & OpenAI Codex)
+- `AGENTS.md` & `CLAUDE.md` (Universal AI guidelines & cross-tool entry point)
+- `.agents/skills/` (28 Core Skills for Google Antigravity, OpenAI Codex, Cursor, Copilot)
 - `.claude/skills/` (28 Core Skills for Claude Code)
-- `devflow/ideas.md` (Idea inbox & backlog)
-- `devflow/context/` (Living spec & active state)
+- `devflow/ideas.md` (Idea inbox with AI feasibility scoring)
+- `devflow/context/` (Living spec & active delivery context)
 - `devflow/history/` (Categorized delivery archives)
 
+The 28 names come from the canonical bundled inventory. Local or Personal Skills
+may coexist in a maintainer workspace, but the package builder excludes them
+unless they are explicitly promoted into that inventory.
+
 ---
 
-## 🏎️ Dual-Track Delivery Model
+## ⚡ The Unified 4-Stage Living Spec Lifecycle
+
+All development tasks execute through the 4-stage single living spec lifecycle:
 
-### 1. Fast-Track (Blueprint Mode — 4 Steps)
-*Recommended for 85% of daily work (features, bug fixes, UI improvements):*
 ```text
 /feature (or /fix) ──▶ /implement ──▶ /check ──▶ /complete
 ```
 
-### 2. Deep-Track (Architect Mode — 8 Steps)
-*Recommended for large architectural epics and database migrations:*
-```text
-discovery ──▶ 10-define ──▶ 20-spec ──▶ 30-plan ──▶ 40-execute ──▶ 50-verify ──▶ 60-report ──▶ 70-deliver
-```
+1. **`feature` / `fix` (`/feature`, `/fix`)**: Combines Discover, Define, Spec, and Plan. Allocates sequential ID (`xxx-slug`) and initializes the **Single Living Spec (`devflow/context/current-feature.md`)**.
+2. **`implement` (`/implement`)**: Incrementally executes checklist tasks with strict **TDD discipline (Red-Green-Refactor)**.
+3. **`check` (`/check`)**: Dual-Axis review combining empirical spec fidelity with independent standards, architecture, and quality gates.
+4. **`complete` (`/complete`)**: Final safety pass, records Release Digest, auto-archives living spec to `devflow/history/`, resets the stub, and manages the git delivery gate.
 
 ---
 
-## 🛠️ CLI Management Commands
+## 🔮 Pre-Flight Discovery Suite
 
-```bash
-# Quality Gatekeeper & Pre-commit Hooks
-npx @jakkrichm/create-nexus-devflow check-gate [--strict]
-npx @jakkrichm/create-nexus-devflow hook install pre-commit
+- **`/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 divergent/convergent ideation with trade-off analysis.
+- **`/discovery`**: Deep inception and exploratory discovery (`devflow/discoveries/DISC-xxx.md`).
 
-# Model Context Protocol (MCP) Server Hub
-npx @jakkrichm/create-nexus-devflow mcp
+For failures, `/debug` follows a scientific six-phase diagnosis built around a
+red-capable feedback loop and does not modify source. Architecture review follows
+Deep Modules principles: small public interfaces, hidden implementation
+complexity, and stable seams.
 
-# JIT Dynamic Context Slicing (60-70% Token Savings)
-npx @jakkrichm/create-nexus-devflow slice --stage implement
+Maintainer contracts and examples are available in the repository:
+[governance rules](https://github.com/Jakkrich/nexus-devflow/blob/main/docs/governance-rules.md),
+[Markdown metadata](https://github.com/Jakkrich/nexus-devflow/blob/main/docs/markdown-metadata-contract.md),
+[manual review workflow](https://github.com/Jakkrich/nexus-devflow/blob/main/docs/manual-review-workflow-spec.md), and
+[Living Spec examples](https://github.com/Jakkrich/nexus-devflow/tree/main/docs/examples/living-spec).
 
-# Git Drift Detection & Self-Healing State
-npx @jakkrichm/create-nexus-devflow drift
-npx @jakkrichm/create-nexus-devflow reconcile --fix
+---
 
-# Visual Webview Studio Dashboard
-npx @jakkrichm/create-nexus-devflow studio
+## 🌐 Web Dashboard & Real-Time Studio
 
-# Multi-Agent Swarm Orchestration & Code Graph Blast Radius
-npx @jakkrichm/create-nexus-devflow swarm
-npx @jakkrichm/create-nexus-devflow graph --file <path>
+Launch the local interactive Web Dashboard with 0ms SSR First Paint and Single-Flight Git caching:
 
-# Status & Updates
-npx @jakkrichm/create-nexus-devflow status
-npx @jakkrichm/create-nexus-devflow update
-npx @jakkrichm/create-nexus-devflow uninstall --keep-history -y
-npx @jakkrichm/create-nexus-devflow eject -y
+```bash
+# Launch dashboard on http://127.0.0.1:4318
+npx @jakkrichm/create-nexus-devflow dashboard
 ```
 
 ---
 
-## 🤖 Model Context Protocol (MCP) Server & Tools
+## 🛠️ CLI Management Commands
 
-Exposes 12 typed MCP tools for AI Coding Agents (`devflow_get_status`, `devflow_get_sliced_context`, `devflow_get_context`, `devflow_query_code_graph`, `devflow_swarm_plan`, `devflow_detect_drift`, `devflow_reconcile_state`, `devflow_evaluate_gate`, `devflow_get_studio_html`, `devflow_add_idea`, `devflow_record_finding`, `devflow_resolve_finding`).
+```bash
+# Start Web Dashboard
+npx @jakkrichm/create-nexus-devflow dashboard [--port 4318]
 
+# Automated Quality Gatekeeper & Pre-commit Hooks
+npx @jakkrichm/create-nexus-devflow check-gate [--strict]
+npx @jakkrichm/create-nexus-devflow hook install pre-commit
 
----
+# Model Context Protocol (MCP) Server Hub (12 Native Tools)
+npx @jakkrichm/create-nexus-devflow mcp
 
-## 🤖 Tool Support & Invocation
+# Just-In-Time (JIT) Dynamic Context Slicing
+npx @jakkrichm/create-nexus-devflow slice --stage implement
+
+# Git Diff Drift Detection & Reconciler
+npx @jakkrichm/create-nexus-devflow drift
+npx @jakkrichm/create-nexus-devflow reconcile
 
-| Tool | Installed Adapter | Example Invocations |
-| :--- | :--- | :--- |
-| **Google Antigravity** | `.agents/skills/` | `/feature`, `/fix`, `/implement`, `/devflow`, `/adopt`, `/doctor` |
-| **OpenAI Codex** | `.agents/skills/` | `$feature`, `$fix`, `$implement`, `$devflow`, `$adopt`, `$doctor` |
-| **Claude Code** | `.claude/skills/` | `/feature`, `/fix`, `/implement`, `/devflow`, `/adopt`, `/doctor` |
-| **Cursor / Others** | `AGENTS.md` + `.agents/` | Follow `SKILL.md` or invoke matching command names |
+# Multi-Agent Swarm & Code Graph
+npx @jakkrichm/create-nexus-devflow swarm
+npx @jakkrichm/create-nexus-devflow graph --file src/index.ts
+
+# Framework Update & Safety Rollback
+npx @jakkrichm/create-nexus-devflow update [--check]
+```
 
 ---
 

package/dist/lib/branch-context.d.ts

@@ -7,29 +7,82 @@ export interface ActiveContextPaths {
     stagePath: string;
     findingsPath: string;
 }
+export interface RunContextPaths {
+    isMultiRun: boolean;
+    runId: string | null;
+    runDir: string | null;
+    specPath: string;
+    stagePath: string;
+    findingsPath: string;
+    globalOverviewPath: string;
+    globalStandardsPath: string;
+}
+export interface ActiveRunSummary {
+    runId: string;
+    title: string;
+    status: string;
+    track: string;
+    branch: string;
+    totalTasks: number;
+    completedTasks: number;
+    remainingTasks: number;
+    hasOpenFindings: boolean;
+    runDir: string;
+    specPath: string;
+}
+export interface InitRunOptions {
+    branch?: string;
+    track?: string;
+    status?: string;
+    initialSpec?: string;
+}
 /**
  * Sanitizes a Git branch name into a cross-platform safe directory name.
  * e.g. "feature/044-auth#login" -> "feature-044-auth-login"
  */
 export declare function sanitizeBranchName(branch: string): string;
 /**
- * Resolves active context paths for the current repository and git branch.
- * Checks for branch-isolated context in:
- *   1. devflow/context/<sanitized>/ (Primary user-visible multi-dev location)
- *   2. .nexus/branches/<sanitized>/ (Internal branch cache)
- *   3. devflow/context/ (Default fallback)
+ * Lists all active run contexts under devflow/context/{xxx-slug}/
+ */
+export declare function listActiveRunContexts(projectRoot: string): Promise<ActiveRunSummary[]>;
+/**
+ * Fuzzy matches a user input string to an ActiveRunSummary.
+ * Matches:
+ * 1. Exact runId
+ * 2. Leading number (e.g. "1" -> "001-*", "12" -> "012-*")
+ * 3. Case-insensitive substring match in runId or title
+ */
+export declare function fuzzyMatchRunId(targetInput: string, activeRuns: ActiveRunSummary[]): ActiveRunSummary | null;
+/**
+ * Resolves active run context with Multi-Run and fallback support.
+ */
+export declare function resolveActiveRunContext(projectRoot: string, targetIdOrBranch?: string): Promise<RunContextPaths>;
+/**
+ * Initializes a new run context under devflow/context/{runId}/
+ */
+export declare function initRunContext(projectRoot: string, runId: string, title: string, options?: InitRunOptions): Promise<RunContextPaths>;
+/**
+ * Cleans up a run context directory after completion.
+ */
+export declare function cleanupRunContext(projectRoot: string, runId: string): Promise<boolean>;
+/**
+ * Calculates the next sequential 3-digit running ID by scanning history archives and active run contexts.
+ */
+export declare function calculateNextRunningId(projectRoot: string): Promise<string>;
+/**
+ * Resolves active context paths for the current repository and git branch (Legacy/Interoperable helper).
  */
 export declare function resolveActiveContextPaths(projectRoot: string, explicitBranch?: string): Promise<ActiveContextPaths>;
 /**
- * Initializes a branch-scoped context directory under devflow/context/<sanitized>/ (or .nexus/branches/)
+ * Initializes a branch-scoped context directory (Backward compatibility wrapper).
  */
 export declare function initBranchContext(projectRoot: string, branchName: string, initialSpec?: string, useDevflowContextDir?: boolean): Promise<ActiveContextPaths>;
 /**
- * Cleans up branch-scoped context directories after completion.
+ * Cleans up branch-scoped context directories (Backward compatibility wrapper).
  */
 export declare function cleanupBranchContext(projectRoot: string, branchName: string): Promise<boolean>;
 /**
- * Lists all active branch isolated contexts.
+ * Lists all active branch isolated contexts (Backward compatibility wrapper).
  */
 export declare function listBranchContexts(projectRoot: string): Promise<Array<{
     branch: string;