@ulysses-ai/create-workspace 0.13.0-beta.0 → 0.13.0-beta.1

package/README.md

@@ -8,20 +8,24 @@
 
 > Rules, skills, and hooks that steer Claude Code through real work. Sessions you can pause and resume, multi-repo with versioning, shared context that survives chat boundaries.
 
+> **Beta.** Currently shipping as `0.13.0-beta.x` under the `@beta` dist-tag. Conventions and CLI flags are stable; the `latest` tag will appear when `0.13.0` cuts. Beta testers welcome — please [open an issue](https://github.com/ukt-solutions/create-ulysses-workspace/issues) if anything's confusing.
+
+Requires Node 20.9 or later.
+
 ## Quick start
 
 ```bash
 # npm
-npm create @ulysses-ai/workspace@latest
+npm create @ulysses-ai/workspace@beta
 
 # yarn
-yarn create @ulysses-ai/workspace
+yarn create @ulysses-ai/workspace@beta
 
 # pnpm
-pnpm create @ulysses-ai/workspace
+pnpm create @ulysses-ai/workspace@beta
 
 # bun
-bun create @ulysses-ai/workspace
+bun create @ulysses-ai/workspace@beta
 ```
 
 Then:
@@ -33,6 +37,30 @@ claude
 /start-work
 ```
 
+## Migrate an existing project
+
+Already have a project directory? Run `--init` from inside it with no target argument:
+
+```bash
+cd my-existing-project
+npx @ulysses-ai/create-workspace@beta --init
+```
+
+The scaffolder treats the current directory as the workspace root. If a `CLAUDE.md` already exists, it's backed up to `CLAUDE.md.bak` and replaced with the workspace template — your old content is preserved for `/workspace-init` to extract from.
+
+Then run `claude` and `/workspace-init`. The skill discovers any repos already present, asks which to register in `workspace.json`, prompts for any additional repos to add, extracts documentation from existing sources, and formalizes any in-progress git worktrees as work sessions. Then `/start-work` to begin.
+
+## Upgrade an existing workspace
+
+When a new template version ships, upgrade in place:
+
+```bash
+cd my-workspace
+npx @ulysses-ai/create-workspace@beta --upgrade
+```
+
+This stages the new template payload to `.workspace-update/` without changing anything yet. Open Claude Code and run `/workspace-update` — the skill applies each change interactively (asks how to resolve any file you've customized) and runs a maintenance audit before and after.
+
 ## Why "Ulysses"?
 
 Ulysses lashed himself to the mast so he could hear the Sirens without being steered into the rocks. A workspace does the same for Claude — freedom to do the work, constraints that keep it on course.
@@ -69,9 +97,9 @@ A scaffolded workspace with:
 
 | Command | What it does |
 | --- | --- |
-| `npm create @ulysses-ai/workspace@latest` | Interactive scaffolder (recommended) |
-| `npx @ulysses-ai/create-workspace --init [dir]` | Non-interactive fresh install (pass dir directly) |
-| `npx @ulysses-ai/create-workspace --upgrade [dir]` | Apply template updates to an existing workspace |
+| `npm create @ulysses-ai/workspace@beta` | Interactive scaffolder (recommended) |
+| `npx @ulysses-ai/create-workspace@beta --init [dir]` | Non-interactive fresh install (pass dir directly) |
+| `npx @ulysses-ai/create-workspace@beta --upgrade [dir]` | Apply template updates to an existing workspace |
 
 > **Why two forms?** `npm create <pkg>` resolves to `npx create-<pkg>`, but it consumes the `--init` flag for itself (npm's own subcommand alias). Use the bare `npm create` form for interactive scaffolding; use `npx` directly when you want to pass `--init <dir>` non-interactively.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulysses-ai/create-workspace",
-  "version": "0.13.0-beta.0",
+  "version": "0.13.0-beta.1",
   "description": "A workspace convention for Claude Code: sessions, handoffs, and shared context as files in git",
   "keywords": [
     "claude",

package/template/.claude/hooks/_utils.mjs

@@ -1,3 +1,4 @@
+import '../lib/require-node.mjs';
 import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, unlinkSync, statSync, rmSync } from 'fs';
 import { resolve, dirname, join } from 'path';
 import { fileURLToPath } from 'url';

package/template/.claude/lib/require-node.mjs

@@ -0,0 +1,17 @@
+// Hard Node version requirement for the workspace runtime.
+// Imported by hook utilities and every script entry point so a workspace
+// running on too-old Node fails fast with a clear message instead of
+// later, deeper, with cryptic syntax/feature errors.
+
+const REQUIRED_MAJOR = 20;
+const REQUIRED_MINOR = 9;
+
+const [major, minor] = process.versions.node.split('.').map(Number);
+
+if (major < REQUIRED_MAJOR || (major === REQUIRED_MAJOR && minor < REQUIRED_MINOR)) {
+  console.error(`This workspace requires Node.js ${REQUIRED_MAJOR}.${REQUIRED_MINOR} or later.`);
+  console.error(`  You have:  ${process.versions.node}`);
+  console.error(`  Required:  >=${REQUIRED_MAJOR}.${REQUIRED_MINOR}.0`);
+  console.error(`  Install a newer Node via nvm, fnm, or https://nodejs.org`);
+  process.exit(1);
+}

package/template/.claude/scripts/add-repo-to-session.mjs

@@ -2,6 +2,7 @@
 // Add a project repo to an existing work session mid-flight. Creates a
 // nested project worktree inside the workspace worktree's repos/ dir and
 // appends the new repo to the session tracker's `repos:` list.
+import '../lib/require-node.mjs';
 import { execSync } from 'child_process';
 import { join } from 'path';
 import {

package/template/.claude/scripts/cleanup-work-session.mjs

@@ -11,6 +11,7 @@
 // Workspace-first removal silently deletes the nested project worktrees'
 // .git files and leaves orphan worktree records in the project repos.
 // The safe order keeps both sides of the relationship in sync.
+import '../lib/require-node.mjs';
 import { execSync } from 'child_process';
 import { existsSync } from 'fs';
 import { join } from 'path';

package/template/.claude/scripts/create-work-session.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // Create a work session: workspace worktree + nested project worktrees +
 // session.md tracker. Produces a self-contained work-sessions/{name}/ folder.
+import '../lib/require-node.mjs';
 import { execSync } from 'child_process';
 import { existsSync, mkdirSync, copyFileSync } from 'fs';
 import { join, resolve } from 'path';

package/template/.claude/scripts/migrate-open-work.mjs

@@ -7,6 +7,7 @@
 // Usage:
 //   node .claude/scripts/migrate-open-work.mjs <path-to-open-work.md> [workspace-json-path]
 
+import '../lib/require-node.mjs';
 import { readFileSync } from 'node:fs';
 import { createTracker } from './trackers/interface.mjs';
 

package/template/.claude/scripts/migrate-session-layout.mjs

@@ -13,6 +13,7 @@
 //   node migrate-session-layout.mjs --main
 //   node migrate-session-layout.mjs --all --main     (runs all sessions then main)
 //   Optional: --root PATH to override auto-detection
+import '../lib/require-node.mjs';
 import { execSync } from 'child_process';
 import {
   readFileSync,

package/template/.claude/scripts/trackers/github-issues.mjs

@@ -2,6 +2,7 @@
 // Issue IDs are opaque strings of the form "gh:N" — adapters outside this file
 // don't need to parse them; routing is handled by interface.mjs.
 
+import '../../lib/require-node.mjs';
 import { spawnSync as nodeSpawnSync } from 'node:child_process';
 import { AlreadyAssignedError } from './interface.mjs';
 

package/template/.claude/scripts/trackers/interface.mjs

@@ -1,6 +1,7 @@
 // Tracker adapter interface. Skills import only from this module.
 // See design-tracker-abstraction.md for the full Issue shape and method contracts.
 
+import '../../lib/require-node.mjs';
 import { createGithubAdapter } from './github-issues.mjs';
 
 export class AlreadyAssignedError extends Error {