gnd-workflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jared Geller
+
+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,104 @@
+# Great Northern Diver
+
+A small installer for a planning, execution, and critique prompt set. Writes managed files into `.agents` inside the target repo so the workflow lives next to the code it operates on.
+
+## Install
+
+One-shot scaffold. No global install or project dependency required.
+
+```bash
+npx gnd-workflow@latest install
+# or
+pnpm dlx gnd-workflow@latest install
+```
+
+Target another repo or pin a version:
+
+```bash
+npx gnd-workflow@latest install ../my-repo
+npx gnd-workflow@0.1.0 install
+```
+
+## What It Writes
+
+The installer writes managed files into `.agents/`. The workflow itself creates
+`.planning/` at runtime for structured plans:
+
+```text
+.agents/                  ← managed by the installer
+  .gnd-version.json
+  agents/
+    gnd-diver.agent.md
+    gnd-navigator.agent.md
+  skills/
+    gnd-chart/SKILL.md
+    gnd-critique/SKILL.md
+.planning/                ← created by gnd-chart and gnd-navigator
+  active-plan-*.md
+  archive/                ← completed plans moved here by gnd-critique
+```
+
+- `.gnd-version.json` records which gnd-workflow version scaffolded the files.
+- `gnd-chart` is the planning skill.
+- `gnd-navigator` dispatches approved plan legs.
+- `gnd-diver` executes one leg.
+- `gnd-critique` reviews delivered work and feeds corrections back into the process.
+
+All of these are plain text. Whether to track them in git is up to you:
+
+- **`.agents/`** — tracking lets collaborators (or yourself on another machine)
+  see the workflow files without re-running the installer. Ignoring keeps
+  generated files out of your repo; `npx gnd-workflow@latest install`
+  re-creates them.
+- **`.planning/`** — tracking preserves plan history alongside code. Ignoring
+  treats plans as ephemeral working state.
+
+Neither directory needs to be tracked or ignored for the workflow to function.
+
+## Philosophy
+
+This is an agentic-development-first workflow. The navigator commits and pushes
+directly to the default branch — no feature branches, no pull requests, no
+staging area. Plan → execute → critique → push, in a tight loop.
+
+That model works well for solo and hobby projects where you're the only
+collaborator and velocity matters more than ceremony
+([peninsular-reveries](https://github.com/ironloon/peninsular-reveries) is
+the project it was built around). It's a poor fit for teams that rely on branch
+protection, code review gates, or CI pipelines that run before merge.
+
+If your project needs those guardrails, you can still use the planning and
+critique skills on their own — just override the navigator's landing step to
+target a branch instead of pushing directly.
+
+## Updating
+
+```bash
+npx gnd-workflow@latest install
+```
+
+If a managed file already exists:
+
+- unchanged files are left alone
+- changed files trigger an interactive prompt before overwrite
+- non-interactive runs fail closed unless you pass `--force`
+
+Flags:
+
+- `--dry-run` shows what would change.
+- `--force` replaces differing managed files without prompting.
+- `--version` shows the installed version.
+- `-C, --cwd <path>` resolves the target project root from a specific working directory.
+
+The target project root must be a real directory; symlinked and junctioned roots are rejected.
+
+## Development
+
+```bash
+npm test
+node ./bin/gnd-workflow.js help
+node ./bin/gnd-workflow.js install --dry-run
+npm pack --dry-run
+```
+
+Maintainer release steps live in [RELEASING.md](RELEASING.md).

package/bin/gnd-workflow.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.js";
+
+const exitCode = await main(process.argv.slice(2));
+process.exit(exitCode);

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "gnd-workflow",
+  "version": "0.1.0",
+  "description": "Installable agent and skill files for coding projects.",
+  "type": "module",
+  "bin": {
+    "gnd-workflow": "bin/gnd-workflow.js"
+  },
+  "exports": {
+    ".": "./src/install.js"
+  },
+  "files": [
+    "bin",
+    "src/!(*.test|*-test-helpers).js",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test src/**/*.test.js package-smoke.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "workflow",
+    "planning",
+    "orchestration",
+    "critique",
+    "project-planning",
+    "agent-workflow",
+    "developer-workflow",
+    "great-northern-diver"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ironloon/the-great-northern-diver.git"
+  },
+  "homepage": "https://github.com/ironloon/the-great-northern-diver#readme",
+  "bugs": {
+    "url": "https://github.com/ironloon/the-great-northern-diver/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.js

@@ -0,0 +1,319 @@
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+import { DEFAULT_INSTALL_DIR, installWorkflow, readPackageVersion } from "./install.js";
+import { normalizePathForContent } from "./path-policy.js";
+
+function printHelp(stream) {
+  stream.write(
+    [
+      "Great Northern Diver",
+      "",
+      "Usage:",
+      "  gnd-workflow install [project-root] [options]",
+      "  gnd-workflow help",
+      "",
+      `Writes managed agent files into ${normalizePathForContent(DEFAULT_INSTALL_DIR)} in the target project.`,
+      "",
+      "Options:",
+      "  --force                       Replace differing managed files without prompting",
+      "  --dry-run                     Print the install plan without writing files",
+      "  -C, --cwd <path>              Resolve paths from a specific working directory",
+      "  --version                     Show version number",
+      "  --help                        Show this help text",
+      ""
+    ].join("\n")
+  );
+}
+
+function formatPath(projectRoot, filePath) {
+  return path.relative(projectRoot, filePath).replaceAll("\\", "/") || ".";
+}
+
+function printFileGroup(stream, title, projectRoot, entries) {
+  if (entries.length === 0) {
+    return;
+  }
+
+  stream.write(`${title}:\n`);
+
+  for (const entry of entries) {
+    stream.write(`  ${entry.status.padEnd(9)} ${formatPath(projectRoot, entry.path)}\n`);
+  }
+}
+
+function printConflicts(stream, conflicts) {
+  if (conflicts.length === 0) {
+    return;
+  }
+
+  stream.write("Conflicts requiring confirmation without --force:\n");
+
+  for (const conflict of conflicts) {
+    stream.write(`  overwrite ${conflict.relativePath}\n`);
+  }
+}
+
+function parseInstallArgs(argv, cwd) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    strict: true,
+    options: {
+      "dry-run": {
+        type: "boolean"
+      },
+      force: {
+        type: "boolean"
+      },
+      cwd: {
+        type: "string",
+        short: "C"
+      },
+      help: {
+        type: "boolean"
+      },
+      version: {
+        type: "boolean"
+      },
+    }
+  });
+
+  if (positionals.length > 1) {
+    throw new Error(`Unexpected positional argument '${positionals[1]}'.`);
+  }
+
+  const baseProjectRoot = values.cwd ? path.resolve(cwd, values.cwd) : cwd;
+  const options = {
+    projectRoot: baseProjectRoot,
+    dryRun: values["dry-run"] ?? false,
+    force: values.force ?? false,
+    version: values.version ?? false,
+    help: values.help ?? false
+  };
+
+  if (positionals.length === 1) {
+    options.projectRoot = path.resolve(baseProjectRoot, positionals[0]);
+  }
+
+  return options;
+}
+
+function formatErrorMessage(error) {
+  return error?.message !== undefined ? String(error.message) : String(error);
+}
+
+function formatConflictPrompt(conflict) {
+  return [
+    "Managed file differs from the packaged version:",
+    `  ${conflict.relativePath}`,
+    "Replace it? [y]es/[n]o/[a]ll: "
+  ].join("\n");
+}
+
+const DEFAULT_PROMPT_TIMEOUT_MS = 300_000;
+
+function questionWithTtyLifecycle(prompt, input, message, timeoutMs) {
+  if (input.readableEnded || input.destroyed) {
+    return Promise.resolve(null);
+  }
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let timer = null;
+
+    const cleanup = () => {
+      if (timer !== null) clearTimeout(timer);
+      input.off("end", handleInputEnded);
+      input.off("close", handleInputClosed);
+      input.off("error", handleInputError);
+    };
+
+    const settle = (callback) => (value) => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      cleanup();
+      callback(value);
+    };
+
+    const handleInputEnded = settle(() => {
+      prompt.close();
+      resolve(null);
+    });
+    const handleInputClosed = settle(() => {
+      prompt.close();
+      resolve(null);
+    });
+    const handleInputError = settle(reject);
+    const handleTimeout = settle(() => {
+      prompt.close();
+      resolve(null);
+    });
+
+    input.once("end", handleInputEnded);
+    input.once("close", handleInputClosed);
+    input.once("error", handleInputError);
+
+    if (timeoutMs != null && timeoutMs > 0) {
+      timer = setTimeout(handleTimeout, timeoutMs);
+    }
+
+    prompt.question(message).then(
+      settle(resolve),
+      settle(reject)
+    );
+  });
+}
+
+function createInteractiveConflictPrompter(input, output, options = {}) {
+  if (!input?.isTTY || !output?.isTTY) {
+    return null;
+  }
+
+  const promptTimeoutMs = options.promptTimeoutMs ?? DEFAULT_PROMPT_TIMEOUT_MS;
+  let acceptAll = false;
+  let prompt = null;
+
+  return {
+    async confirmManagedFileConflict(conflict) {
+      if (acceptAll) {
+        return true;
+      }
+
+      prompt ??= createInterface({
+        input,
+        output
+      });
+
+      while (true) {
+        const answer = await questionWithTtyLifecycle(prompt, input, formatConflictPrompt(conflict), promptTimeoutMs);
+
+        if (answer === null) {
+          return false;
+        }
+
+        const normalizedAnswer = answer.trim().toLowerCase();
+
+        if (normalizedAnswer === "y" || normalizedAnswer === "yes") {
+          return true;
+        }
+
+        if (normalizedAnswer === "a" || normalizedAnswer === "all") {
+          acceptAll = true;
+          return true;
+        }
+
+        if (normalizedAnswer === "" || normalizedAnswer === "n" || normalizedAnswer === "no") {
+          return false;
+        }
+
+        output.write("Please answer y, n, or a.\n");
+      }
+    },
+    close() {
+      prompt?.close();
+    }
+  };
+}
+
+function printInstallResult(stream, result) {
+  stream.write("Great Northern Diver install summary\n\n");
+  stream.write(`Project root: ${result.projectRoot}\n`);
+  stream.write(`Install root: ${normalizePathForContent(result.installDir)}\n`);
+
+  if (result.dryRun) {
+    stream.write("Mode: dry-run\n");
+  }
+
+  stream.write("\n");
+  printFileGroup(stream, "Managed files", result.projectRoot, result.managedFiles);
+  printConflicts(stream, result.conflicts ?? []);
+}
+
+async function runInstallCommand(rest, io, promptController) {
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  const cwd = io.cwd ?? process.cwd();
+  const runInstallWorkflow = io.installWorkflow ?? installWorkflow;
+
+  let options;
+
+  try {
+    options = parseInstallArgs(rest, cwd);
+  } catch (error) {
+    stderr.write(`${formatErrorMessage(error)}\n\n`);
+    printHelp(stderr);
+    return 1;
+  }
+
+  if (options.help) {
+    printHelp(stdout);
+    return 0;
+  }
+
+  if (options.version) {
+    stdout.write(`${await readPackageVersion()}\n`);
+    return 0;
+  }
+
+  if (options.dryRun && options.force) {
+    stderr.write("Warning: --force has no effect in --dry-run mode.\n");
+  }
+
+  const result = await runInstallWorkflow(
+    promptController !== null && !options.force && !options.dryRun
+      ? {
+          ...options,
+          confirmManagedFileConflict: promptController.confirmManagedFileConflict
+        }
+      : options
+  );
+
+  printInstallResult(stdout, result);
+  return 0;
+}
+
+export async function main(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  const stdin = io.stdin ?? process.stdin;
+  const [command = "install", ...rest] = argv;
+  const promptController = io.confirmManagedFileConflict
+    ? {
+        confirmManagedFileConflict: io.confirmManagedFileConflict,
+        close() {}
+      }
+    : createInteractiveConflictPrompter(stdin, stderr, { promptTimeoutMs: io.promptTimeoutMs });
+
+  if (command === "version" || command === "--version" || command === "-v") {
+    stdout.write(`${await readPackageVersion()}\n`);
+    promptController?.close();
+    return 0;
+  }
+
+  if (command === "help" || command === "--help" || command === "-h") {
+    printHelp(stdout);
+    promptController?.close();
+    return 0;
+  }
+
+  if (command !== "install") {
+    stderr.write(`Unknown command '${command}'.\n\n`);
+    printHelp(stderr);
+    promptController?.close();
+    return 1;
+  }
+
+  try {
+    return await runInstallCommand(rest, io, promptController);
+  } catch (error) {
+    stderr.write(`${formatErrorMessage(error)}\n`);
+    return 1;
+  } finally {
+    promptController?.close();
+  }
+}
+