@jakkrichm/create-nexus-devflow 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexus-DevFlow Contributors / Jakkrich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @jakkrichm/create-nexus-devflow
+
+> **Nexus-DevFlow 2.0 Scaffolder & Overlay Tool** — Safely overlay the stage-based agentic workflow layer onto any scaffolded or existing codebase.
+
+[![npm version](https://img.shields.io/npm/v/@jakkrichm/create-nexus-devflow.svg)](https://www.npmjs.com/package/@jakkrichm/create-nexus-devflow)
+[![license](https://img.shields.io/npm/l/@jakkrichm/create-nexus-devflow.svg)](https://github.com/Jakkrich/nexus-devflow/blob/main/LICENSE)
+
+---
+
+## Quick Start
+
+### 1. Overlay into Current Project
+```bash
+npx @jakkrichm/create-nexus-devflow
+```
+
+### 2. Overlay into Specific Directory
+```bash
+npx @jakkrichm/create-nexus-devflow ./my-project
+```
+
+### 3. Specify Tool Adapters
+```bash
+# Install both OpenAI Codex / Antigravity (.agents) and Claude Code (.claude)
+npx @jakkrichm/create-nexus-devflow --adapter both
+
+# Install Codex & Google Antigravity adapter only
+npx @jakkrichm/create-nexus-devflow --adapter codex
+
+# Install Claude Code adapter only
+npx @jakkrichm/create-nexus-devflow --adapter claude
+```
+
+### 4. Update Existing DevFlow Installation
+```bash
+npx @jakkrichm/create-nexus-devflow update
+```
+
+---
+
+## CLI Options
+
+| Flag | Shortcut | Description | Default |
+| :--- | :--- | :--- | :--- |
+| `--adapter <name>` | | Select AI tool adapters (`codex`, `antigravity`, `claude`, `both`) | `both` |
+| `--force` | `-f` | Overwrite conflicting files without prompting | `false` |
+| `--dry-run` | | Preview changes without modifying disk | `false` |
+| `--yes` | `-y` | Automatically confirm interactive prompts | `false` |
+| `--version` | `-v` | Display package version | |
+| `--help` | `-h` | Display help screen | |
+
+---
+
+## Workflow Timeline & Stage Lifecycle
+
+```text
+/00-Discover -> /10-Define -> /20-Spec -> /30-Plan -> /40-Implement -> /50-Verify -> /60-Report -> /70-Release
+```
+
+1. **`/00-Discover`**: Explore requests before delivery commitment under a Discovery ID.
+2. **`/10-Define`**: Lock delivery boundaries and allocate Running IDs (`.workspaces/specs/{RUNNING_ID}`).
+3. **`/20-Spec`**: Formalize markdown-first specification contracts and done-when criteria.
+4. **`/30-Plan`**: Transform specs into executable task breakdowns.
+5. **`/40-Implement`**: Execute planned tasks incrementally with implementation evidence.
+6. **`/50-Verify`**: Senior QA review and runtime validation check.
+7. **`/60-Report`**: Generate standardized markdown and HTML stage reports.
+8. **`/70-Release`**: Package verified work for PR merge or production deployment.
+
+---
+
+## Tool Adapters Architecture
+
+- **`AGENTS.md`**: Universal cross-tool entry point and source of truth for Codex, Antigravity, Cursor, Gemini CLI, Aider, and Zed.
+- **`CLAUDE.md`**: Imports `@AGENTS.md` for Claude Code.
+- **`.agents/skills/`**: Stores stage workflows and discipline skills for Codex & Google Antigravity.
+- **`.claude/skills/`**: Stores synced stage workflows and skills for Claude Code.
+
+---
+
+## License
+
+MIT License — Copyright (c) 2026 Nexus-DevFlow Contributors / Jakkrich

package/bin/create-nexus-devflow.js

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs/promises");
+const fsSync = require("node:fs");
+const path = require("node:path");
+const readline = require("node:readline/promises");
+const {
+  MANIFEST_PATH,
+  applyPreparedUpdate,
+  prepareUpdate,
+  writeInstallManifest
+} = require("../lib/update");
+
+const packageRoot = path.resolve(__dirname, "..");
+const templateRoot = path.join(packageRoot, "template");
+
+const adapterChoices = new Set(["codex", "antigravity", "claude", "both", "all"]);
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  if (options.version) {
+    console.log(readPackageVersion());
+    return;
+  }
+
+  if (!fsSync.existsSync(templateRoot)) {
+    throw new Error(
+      "Installer template is missing. Run `npm run prepare-template` before local testing."
+    );
+  }
+
+  const targetDir = path.resolve(process.cwd(), options.target || ".");
+  const version = readPackageVersion();
+
+  if (options.command === "update") {
+    const prepared = await prepareUpdate({
+      targetDir,
+      templateRoot,
+      version,
+      adapter: options.adapter
+    });
+    printUpdatePlan(prepared);
+
+    if (options.dryRun) {
+      return;
+    }
+
+    const replaceConflicts =
+      options.force || (await confirmUpdateConflicts(prepared, options));
+    const result = await applyPreparedUpdate(prepared, { replaceConflicts });
+    printUpdateSuccess(prepared, result);
+    return;
+  }
+
+  const prepared = await prepareUpdate({
+    targetDir,
+    templateRoot,
+    version,
+    adapter: options.adapter
+  });
+
+  printInstallPlan(prepared, options);
+
+  if (options.dryRun) {
+    return;
+  }
+
+  if (prepared.conflictList.length > 0 && !options.force) {
+    const proceed = await confirmInstallConflicts(prepared, options);
+    if (!proceed) {
+      console.log("Install cancelled.");
+      return;
+    }
+  }
+
+  const result = await applyPreparedUpdate(prepared, {
+    replaceConflicts: options.force || prepared.conflictList.length > 0
+  });
+
+  printInstallSuccess(targetDir, result, options);
+}
+
+function parseArgs(args) {
+  let command = "install";
+  let target = null;
+  let adapter = "both";
+  let force = false;
+  let dryRun = false;
+  let help = false;
+  let version = false;
+  let yes = false;
+
+  const positional = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === "--help" || arg === "-h") {
+      help = true;
+      continue;
+    }
+
+    if (arg === "--version" || arg === "-v") {
+      version = true;
+      continue;
+    }
+
+    if (arg === "--force" || arg === "-f") {
+      force = true;
+      continue;
+    }
+
+    if (arg === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+
+    if (arg === "-y" || arg === "--yes") {
+      yes = true;
+      continue;
+    }
+
+    if (arg === "--adapter") {
+      const value = args[++i];
+      if (!value || !adapterChoices.has(value.toLowerCase())) {
+        throw new Error(
+          `Invalid --adapter value "${value}". Expected one of: codex, antigravity, claude, both, all`
+        );
+      }
+      adapter = value.toLowerCase();
+      continue;
+    }
+
+    if (arg.startsWith("--adapter=")) {
+      const value = arg.slice("--adapter=".length);
+      if (!adapterChoices.has(value.toLowerCase())) {
+        throw new Error(
+          `Invalid --adapter value "${value}". Expected one of: codex, antigravity, claude, both, all`
+        );
+      }
+      adapter = value.toLowerCase();
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown option "${arg}". Use --help to see available options.`);
+    }
+
+    positional.push(arg);
+  }
+
+  if (positional.length > 0) {
+    if (positional[0] === "update") {
+      command = "update";
+      target = positional[1] || ".";
+    } else {
+      target = positional[0];
+    }
+  }
+
+  return {
+    command,
+    target,
+    adapter,
+    force,
+    dryRun,
+    help,
+    version,
+    yes
+  };
+}
+
+function readPackageVersion() {
+  const pkgPath = path.join(packageRoot, "package.json");
+  const content = fsSync.readFileSync(pkgPath, "utf8");
+  return JSON.parse(content).version;
+}
+
+function printHelp() {
+  console.log(`
+Nexus-DevFlow Installer v${readPackageVersion()}
+
+Usage:
+  npx @jakkrichm/create-nexus-devflow [target-dir] [options]
+  npx @jakkrichm/create-nexus-devflow update [target-dir] [options]
+
+Options:
+  --adapter <name>   Tool adapters to install: codex, antigravity, claude, both (default: both)
+  --force, -f        Overwrite conflicting files without prompting
+  --dry-run          Preview changes without modifying disk
+  -y, --yes          Automatically confirm interactive prompts
+  --version, -v      Show version number
+  --help, -h         Show help screen
+`);
+}
+
+function printInstallPlan(prepared, options) {
+  console.log(`\nNexus-DevFlow v${readPackageVersion()}`);
+  console.log(`Target Directory: ${prepared.targetDir}`);
+  console.log(`Active Adapters : ${prepared.activeAdapters.join(", ")}\n`);
+
+  console.log(`Files to create : ${prepared.createList.length}`);
+  console.log(`Files to update : ${prepared.updateList.length}`);
+  console.log(`Conflicts found : ${prepared.conflictList.length}`);
+
+  if (prepared.conflictList.length > 0) {
+    console.log("\nConflicting files:");
+    for (const conflict of prepared.conflictList) {
+      console.log(`  - ${conflict.relativePath} (${conflict.detail})`);
+    }
+  }
+}
+
+function printUpdatePlan(prepared) {
+  console.log(`\nNexus-DevFlow Update Plan (v${readPackageVersion()})`);
+  console.log(`Target Directory: ${prepared.targetDir}`);
+  console.log(`Active Adapters : ${prepared.activeAdapters.join(", ")}\n`);
+
+  console.log(`Files to create : ${prepared.createList.length}`);
+  console.log(`Files to update : ${prepared.updateList.length}`);
+  console.log(`Orphaned files  : ${prepared.orphanedFiles.length}`);
+  console.log(`Conflicts found : ${prepared.conflictList.length}`);
+}
+
+async function confirmInstallConflicts(prepared, options) {
+  if (options.yes) return true;
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  const answer = await rl.question(
+    `\nOverwrite ${prepared.conflictList.length} conflicting file(s)? [y/N] `
+  );
+  rl.close();
+  return answer.trim().toLowerCase() === "y";
+}
+
+async function confirmUpdateConflicts(prepared, options) {
+  if (options.yes) return true;
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  const answer = await rl.question(
+    `\nOverwrite ${prepared.conflictList.length} customized file(s) with update? [y/N] `
+  );
+  rl.close();
+  return answer.trim().toLowerCase() === "y";
+}
+
+function printInstallSuccess(targetDir, result, options) {
+  console.log("\nNexus-DevFlow overlay successfully installed!");
+  console.log(`Applied ${result.appliedCount} file(s).`);
+  console.log("\nNext steps:");
+  console.log("  1. Open your project in your AI IDE (Antigravity, Codex, Claude Code, etc.)");
+  console.log("  2. Run `/00-Discover` or `/help` to start your DevFlow workspace workflow.");
+}
+
+function printUpdateSuccess(prepared, result) {
+  console.log("\nNexus-DevFlow update successfully applied!");
+  console.log(`Applied ${result.appliedCount} file(s), removed ${result.removedCount} orphaned file(s).`);
+}
+
+main().catch((err) => {
+  console.error(`\nError: ${err.message}`);
+  process.exit(1);
+});