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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Myron Davis
+
+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,108 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ukt-solutions/create-ulysses-workspace/main/docs/assets/logo.png" alt="Ulysses Workspace" width="220">
+</p>
+
+# @ulysses-ai/create-workspace
+
+[![npm version](https://img.shields.io/npm/v/@ulysses-ai/create-workspace.svg)](https://www.npmjs.com/package/@ulysses-ai/create-workspace)
+
+> 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.
+
+## Quick start
+
+```bash
+# npm
+npm create @ulysses-ai/workspace@latest
+
+# yarn
+yarn create @ulysses-ai/workspace
+
+# pnpm
+pnpm create @ulysses-ai/workspace
+
+# bun
+bun create @ulysses-ai/workspace
+```
+
+Then:
+
+```bash
+cd my-workspace
+claude
+/workspace-init
+/start-work
+```
+
+## 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.
+
+Rules say what's safe. Skills say how to do the recurring things. Hooks notice what would otherwise slip through. The combination is what gets you home.
+
+## What it gives you
+
+Four things, in the order you'll touch them:
+
+1. **A workflow lifecycle that survives chat boundaries.** `/start-work` provisions a session — branch, worktree, tracker — atomically. `/pause-work` and `/sync-work` checkpoint mid-stream. `/complete-work` rebases, synthesizes release notes, opens PRs, and tears down. The same session resumes cleanly in a fresh chat.
+
+2. **Parallel work sessions you can run from separate terminals.** Each session lives in its own folder under `work-sessions/{name}/` with its own workspace worktree and nested project worktrees. Two sessions can't collide on a branch or a working directory.
+
+3. **Multi-repo support with versioning across repos.** A workspace wraps your project repos rather than replacing them. Each session can span one repo or many. `/release` synthesizes versioned release docs across the repos that contributed.
+
+4. **Shared context with a locked layer that stays in the window.** `shared-context/locked/` is loaded every turn and injected into subagents. Team truths arrive in the model's context window without anyone remembering to paste them.
+
+> Everything Claude needs is in the file system. Everything a team shares is in git.
+
+## What you get
+
+A scaffolded workspace with:
+
+- **14 skills** covering the workflow lifecycle, releases, handoffs, and maintenance
+- **6 active rules** + **8 optional `.skip` rules** for behaviors you can opt into
+- **8 hooks** for SessionStart, SubagentStart, PreCompact, WorktreeCreate, and the rest of the small set the conventions rely on
+- A **`shared-context/`** memory system with three visibility levels: locked (team truths), root (team-visible ephemerals), user-scoped (personal)
+- Conventions for **multi-repo work sessions** with isolated git worktrees, parallelizable from separate terminals
+
+(Counts are static prose, but a `prepublishOnly` audit script verifies them against the template at publish time — they don't drift.)
+
+## CLI
+
+| 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 |
+
+> **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.
+
+## Documentation
+
+Start here:
+
+- **[Solo Developer Guide](https://github.com/ukt-solutions/create-ulysses-workspace/blob/main/docs/guides/solo-developer.md)** — recommended starting point
+- **[Team Lead Guide](https://github.com/ukt-solutions/create-ulysses-workspace/blob/main/docs/guides/team-lead.md)**
+- **[New Team Member Guide](https://github.com/ukt-solutions/create-ulysses-workspace/blob/main/docs/guides/new-team-member.md)**
+
+The eleven [chapters](https://github.com/ukt-solutions/create-ulysses-workspace/blob/main/docs/) cover the model in depth — concepts, the toolkit, the release lifecycle, behavioral patterns:
+
+| Part | Chapter | Topic |
+|------|---------|-------|
+| Concepts | [01](https://github.com/ukt-solutions/create-ulysses-workspace/blob/main/docs/chapters/01-what-is-a-workspace.md) | What Is a Workspace |
+| | [02](https://github.com/ukt-solutions/create-ulysses-workspace/blob/main/docs/chapters/02-work-sessions.md) | Work Sessions |
+| | [03](https://github.com/ukt-solutions/create-ulysses-workspace/blob/main/docs/chapters/03-shared-context.md) | Shared Context |
+| The Toolkit | [04](https://github.com/ukt-solutions/create-ulysses-workspace/blob/main/docs/chapters/04-claude-md.md) | CLAUDE.md |
+| | [05](https://github.com/ukt-solutions/create-ulysses-workspace/blob/main/docs/chapters/05-rules.md) | Rules |
+| | [06](https://github.com/ukt-solutions/create-ulysses-workspace/blob/main/docs/chapters/06-skills.md) | Skills |
+| | [07](https://github.com/ukt-solutions/create-ulysses-workspace/blob/main/docs/chapters/07-hooks-and-scripts.md) | Hooks and Scripts |
+| | [08](https://github.com/ukt-solutions/create-ulysses-workspace/blob/main/docs/chapters/08-agents.md) | Agents |
+| Lifecycle | [09](https://github.com/ukt-solutions/create-ulysses-workspace/blob/main/docs/chapters/09-the-release-cycle.md) | The Release Cycle |
+| | [10](https://github.com/ukt-solutions/create-ulysses-workspace/blob/main/docs/chapters/10-installation-and-upgrades.md) | Installation and Upgrades |
+| Practice | [11](https://github.com/ukt-solutions/create-ulysses-workspace/blob/main/docs/chapters/11-behavioral-patterns.md) | Behavioral Patterns |
+
+## Status
+
+In active pre-1.0 development. Used as dogfood and validated against external workspaces. Conventions and CLI flags are stable; small refinements continue. v1.0 will mark a stability commitment.
+
+## License
+
+MIT

package/bin/create.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (major < 20 || (major === 20 && minor < 9)) {
+  console.error(`@ulysses-ai/create-workspace requires Node.js 20.9 or later.`);
+  console.error(`  You have:  ${process.versions.node}`);
+  console.error(`  Required:  >=20.9.0`);
+  console.error(`  Try installing a newer Node via nvm, fnm, or the Node website.`);
+  process.exit(1);
+}
+
+import { runPrompts } from '../lib/prompts.mjs';
+import { scaffold } from '../lib/scaffold.mjs';
+import { initGit, cloneRepos } from '../lib/git.mjs';
+import { resolve } from 'path';
+
+async function main() {
+  console.log('\n  Ulysses Workspace\n');
+
+  const initFlag = process.argv.includes('--init');
+  const upgradeFlag = process.argv.includes('--upgrade');
+  const migrateFlag = process.argv.includes('--migrate');
+
+  // Deprecated --migrate
+  if (migrateFlag) {
+    console.error('  --migrate is deprecated. Use --init (fresh install) or --upgrade (template update).');
+    console.error('');
+    console.error('  Fresh install:    npx @ulysses-ai/create-workspace --init [target-dir]');
+    console.error('  Template update:  npx @ulysses-ai/create-workspace --upgrade [target-dir]');
+    console.error('');
+    process.exit(1);
+  }
+
+  if (initFlag) {
+    const { initWorkspace } = await import('../lib/init.mjs');
+    const args = process.argv.slice(process.argv.indexOf('--init') + 1);
+    const targetDir = resolve(args.find(a => !a.startsWith('--')) || '.');
+    await initWorkspace(targetDir);
+    return;
+  }
+
+  if (upgradeFlag) {
+    const { upgradeWorkspace } = await import('../lib/upgrade.mjs');
+    const args = process.argv.slice(process.argv.indexOf('--upgrade') + 1);
+    const targetDir = resolve(args.find(a => !a.startsWith('--')) || '.');
+    await upgradeWorkspace(targetDir);
+    return;
+  }
+
+  // Default: interactive scaffold
+  const answers = await runPrompts();
+
+  if (!answers) {
+    console.log('Setup cancelled.');
+    process.exit(0);
+  }
+
+  const workspacePath = await scaffold(answers);
+  await initGit(workspacePath);
+
+  if (answers.repos.length > 0) {
+    await cloneRepos(workspacePath, answers.repos);
+  }
+
+  console.log(`
+  \u2713 Workspace created at ${workspacePath}
+  \u2713 Git repo initialized${answers.repos.length > 0 ? `\n  \u2713 ${answers.repos.length} repo(s) cloned to repos/` : ''}
+
+  Next steps:
+    cd ${workspacePath}
+    claude
+    /start-work blank
+  `);
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/lib/git.mjs

@@ -0,0 +1,26 @@
+import { execSync } from 'child_process';
+import { join } from 'path';
+
+export async function initGit(workspacePath) {
+  execSync('git init', { cwd: workspacePath, stdio: 'pipe' });
+  execSync('git add -A', { cwd: workspacePath, stdio: 'pipe' });
+  execSync('git commit -m "chore: initialize claude-workspace"', {
+    cwd: workspacePath,
+    stdio: 'pipe',
+  });
+}
+
+export async function cloneRepos(workspacePath, repos) {
+  const reposDir = join(workspacePath, 'repos');
+
+  for (const repo of repos) {
+    const targetDir = join(reposDir, repo.name);
+    console.log(`  Cloning ${repo.name}...`);
+    try {
+      execSync(`git clone "${repo.remote}" "${targetDir}"`, { stdio: 'pipe' });
+    } catch (err) {
+      console.warn(`  \u26A0 Failed to clone ${repo.name}: ${err.message}`);
+      console.warn(`    You can clone it manually later or run /setup in Claude Code.`);
+    }
+  }
+}

package/lib/init.mjs

@@ -0,0 +1,129 @@
+// lib/init.mjs
+import { existsSync, readFileSync, writeFileSync, mkdirSync, cpSync, readdirSync, statSync } from 'fs';
+import { join, basename } from 'path';
+import { stagePayload } from './payload.mjs';
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+export async function initWorkspace(targetDir) {
+  const name = basename(targetDir);
+  const workspaceJsonPath = join(targetDir, 'workspace.json');
+  const claudeMdPath = join(targetDir, 'CLAUDE.md');
+  const gitignorePath = join(targetDir, '.gitignore');
+
+  console.log(`\n  @ulysses-ai/create-workspace --init`);
+  console.log(`  Target: ${targetDir}\n`);
+
+  // Stage payload
+  const { toVersion, payloadDir } = stagePayload(targetDir, { action: 'init' });
+  console.log(`  Staged template payload (v${toVersion})`);
+
+  // Install only the bootstrap skills needed to complete initialization
+  const bootstrapSkills = ['workspace-init', 'workspace-update'];
+  const payloadSkills = join(payloadDir, '.claude', 'skills');
+  const targetSkills = join(targetDir, '.claude', 'skills');
+  for (const skill of bootstrapSkills) {
+    const src = join(payloadSkills, skill);
+    const dest = join(targetSkills, skill);
+    if (existsSync(src) && !existsSync(dest)) {
+      ensureDir(dest);
+      cpSync(src, dest, { recursive: true });
+    }
+  }
+  console.log('  Installed bootstrap skills (workspace-init, workspace-update)');
+
+  // Install hooks, scripts, and lib (needed for workspace to function)
+  for (const dir of ['hooks', 'scripts', 'lib']) {
+    const src = join(payloadDir, '.claude', dir);
+    const dest = join(targetDir, '.claude', dir);
+    if (!existsSync(src)) continue;
+    ensureDir(dest);
+    for (const entry of readdirSync(src)) {
+      const srcEntry = join(src, entry);
+      const destEntry = join(dest, entry);
+      if (!existsSync(destEntry) && !statSync(srcEntry).isDirectory()) {
+        cpSync(srcEntry, destEntry);
+      }
+    }
+    console.log(`  Installed ${dir}`);
+  }
+
+  // Create shared-context structure. We always want shared-context/ and
+  // shared-context/locked/ to exist after init, even if the payload ships
+  // no files for them yet — locked/ is referenced by CLAUDE.md.tmpl via
+  // the @shared-context/locked/ import directive.
+  const payloadContext = join(payloadDir, 'shared-context');
+  const targetContext = join(targetDir, 'shared-context');
+  if (existsSync(payloadContext) && !existsSync(targetContext)) {
+    cpSync(payloadContext, targetContext, { recursive: true });
+    console.log('  Created shared-context/');
+  }
+  ensureDir(join(targetDir, 'shared-context', 'locked'));
+
+  // Everything else (repos/, work-sessions/, workspace-scratchpad/) is
+  // lazy-created by scripts and hooks when they first need to write.
+  // We intentionally do NOT pre-create these dirs — they get made on demand.
+
+  // Create workspace.json if missing
+  if (!existsSync(workspaceJsonPath)) {
+    writeFileSync(workspaceJsonPath, JSON.stringify({
+      workspace: {
+        name,
+        templateVersion: toVersion,
+        scratchpadDir: 'workspace-scratchpad',
+        workSessionsDir: 'work-sessions',
+        sharedContextDir: 'shared-context',
+        releaseNotesDir: 'release-notes',
+        subagentContextMaxBytes: 10240,
+        greeting: `Welcome back to ${name}.`,
+      },
+      repos: {},
+    }, null, 2) + '\n');
+    console.log('  Created workspace.json');
+  }
+
+  // Replace CLAUDE.md with template version (back up existing)
+  const tmplPath = join(payloadDir, 'CLAUDE.md.tmpl');
+  let claudeContent;
+  if (existsSync(tmplPath)) {
+    claudeContent = readFileSync(tmplPath, 'utf-8').replace(/\{\{project-name\}\}/g, name);
+  } else {
+    claudeContent = `## Workspace: ${name}\n\nThis is a claude-workspace. All conventions are defined in .claude/rules/.\n`;
+  }
+
+  if (existsSync(claudeMdPath)) {
+    cpSync(claudeMdPath, claudeMdPath + '.bak');
+    console.log('  Backed up existing CLAUDE.md to CLAUDE.md.bak');
+  }
+  writeFileSync(claudeMdPath, claudeContent);
+  console.log('  Created CLAUDE.md');
+
+  // Set up .gitignore
+  const payloadGitignore = join(payloadDir, '_gitignore');
+  if (existsSync(payloadGitignore)) {
+    if (existsSync(gitignorePath)) {
+      const existing = readFileSync(gitignorePath, 'utf-8');
+      const template = readFileSync(payloadGitignore, 'utf-8');
+      const existingLines = new Set(existing.split('\n').map(l => l.trim()));
+      const newLines = template.split('\n').filter(l => l.trim() && !existingLines.has(l.trim()));
+      if (newLines.length > 0) {
+        writeFileSync(gitignorePath, existing.trimEnd() + '\n\n# From workspace template\n' + newLines.join('\n') + '\n');
+        console.log('  Merged template entries into .gitignore');
+      }
+    } else {
+      cpSync(payloadGitignore, gitignorePath);
+      console.log('  Created .gitignore');
+    }
+  }
+
+  console.log(`
+  Workspace initialized (v${toVersion}).
+
+  Next steps:
+    cd ${targetDir}
+    claude
+    /workspace-init
+`);
+}

package/lib/payload.mjs

@@ -0,0 +1,44 @@
+// lib/payload.mjs
+import { existsSync, cpSync, rmSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = join(__dirname, '..', 'template');
+
+export function getTemplateVersion() {
+  return JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8')).version;
+}
+
+export function stagePayload(targetDir, { action, fromVersion = null }) {
+  const payloadDir = join(targetDir, '.workspace-update');
+  const toVersion = getTemplateVersion();
+
+  // Clean any existing payload
+  if (existsSync(payloadDir)) {
+    rmSync(payloadDir, { recursive: true });
+  }
+
+  // Copy template to payload directory
+  cpSync(TEMPLATE_DIR, payloadDir, { recursive: true });
+
+  // Write manifest
+  const manifest = {
+    action,
+    templateVersion: toVersion,
+    timestamp: new Date().toISOString(),
+    source: '@ulysses-ai/create-workspace',
+  };
+  if (fromVersion) manifest.fromVersion = fromVersion;
+
+  writeFileSync(join(payloadDir, '.manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+
+  return { payloadDir, toVersion, fromVersion };
+}
+
+export function cleanPayload(targetDir) {
+  const payloadDir = join(targetDir, '.workspace-update');
+  if (existsSync(payloadDir)) {
+    rmSync(payloadDir, { recursive: true });
+  }
+}

package/lib/prompts.mjs

@@ -0,0 +1,113 @@
+import prompts from 'prompts';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export async function runPrompts() {
+  const onCancel = () => {
+    return false;
+  };
+
+  // Workspace name
+  const { name } = await prompts({
+    type: 'text',
+    name: 'name',
+    message: 'Workspace name:',
+    validate: (v) => (v.trim() ? true : 'Name is required'),
+  }, { onCancel });
+  if (!name) return null;
+
+  // Directory
+  const defaultDir = join(homedir(), 'claude-workspaces', name);
+  const { directory } = await prompts({
+    type: 'text',
+    name: 'directory',
+    message: 'Directory:',
+    initial: defaultDir,
+  }, { onCancel });
+  if (!directory) return null;
+
+  // Repos
+  const repos = [];
+  let addMore = true;
+  while (addMore) {
+    const { addRepo } = await prompts({
+      type: 'confirm',
+      name: 'addRepo',
+      message: repos.length === 0 ? 'Add a repository?' : 'Add another repository?',
+      initial: repos.length === 0,
+    }, { onCancel });
+    if (addRepo === undefined) return null;
+
+    if (!addRepo) {
+      addMore = false;
+      break;
+    }
+
+    const repoAnswers = await prompts([
+      {
+        type: 'text',
+        name: 'remote',
+        message: '  Remote URL:',
+        validate: (v) => (v.trim() ? true : 'URL is required'),
+      },
+      {
+        type: 'text',
+        name: 'branch',
+        message: '  Default branch:',
+        initial: 'main',
+      },
+      {
+        type: 'confirm',
+        name: 'primary',
+        message: '  Primary repo?',
+        initial: repos.length === 0,
+      },
+    ], { onCancel });
+    if (!repoAnswers.remote) return null;
+
+    // Extract repo name from remote URL
+    const repoName = repoAnswers.remote
+      .split('/')
+      .pop()
+      .replace(/\.git$/, '');
+
+    repos.push({ name: repoName, ...repoAnswers });
+  }
+
+  // User name
+  const defaultUser = process.env.USER || process.env.USERNAME || 'user';
+  const { userName } = await prompts({
+    type: 'text',
+    name: 'userName',
+    message: 'Your name (for handoff scoping):',
+    initial: defaultUser,
+  }, { onCancel });
+  if (!userName) return null;
+
+  // Optional rules
+  const skipRules = [
+    { title: 'cloud-infrastructure', value: 'cloud-infrastructure' },
+    { title: 'superpowers-workflow', value: 'superpowers-workflow' },
+    { title: 'documentation', value: 'documentation' },
+    { title: 'scope-guard', value: 'scope-guard' },
+    { title: 'token-economics', value: 'token-economics' },
+    { title: 'agent-rules', value: 'agent-rules' },
+  ];
+
+  const { activateRules } = await prompts({
+    type: 'multiselect',
+    name: 'activateRules',
+    message: 'Activate optional rules:',
+    choices: skipRules,
+    hint: '- Space to select, Enter to confirm',
+  }, { onCancel });
+  if (!activateRules) return null;
+
+  return {
+    name,
+    directory,
+    repos,
+    userName,
+    activateRules,
+  };
+}

package/lib/scaffold.mjs

@@ -0,0 +1,84 @@
+import { cpSync, mkdirSync, readFileSync, writeFileSync, renameSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = join(__dirname, '..', 'template');
+
+export async function scaffold(answers) {
+  const { name, directory, repos, userName, activateRules } = answers;
+
+  // Create target directory
+  mkdirSync(directory, { recursive: true });
+
+  // Copy template files
+  cpSync(TEMPLATE_DIR, directory, {
+    recursive: true,
+    filter: (src) => {
+      // Skip .tmpl files — we'll process them separately
+      return !src.endsWith('.tmpl');
+    },
+  });
+
+  // Ensure shared-context/locked/ exists so the CLAUDE.md import resolves.
+  // repos/, work-sessions/, and workspace-scratchpad/ are lazy-created when
+  // scripts and hooks first need them — we do NOT pre-create them here.
+  mkdirSync(join(directory, 'shared-context', 'locked'), { recursive: true });
+
+  // Rename _gitignore to .gitignore
+  const gitignoreSrc = join(directory, '_gitignore');
+  const gitignoreDest = join(directory, '.gitignore');
+  if (existsSync(gitignoreSrc)) {
+    renameSync(gitignoreSrc, gitignoreDest);
+  }
+
+  // Process CLAUDE.md template
+  const claudeMdTmpl = readFileSync(join(TEMPLATE_DIR, 'CLAUDE.md.tmpl'), 'utf-8');
+  const claudeMd = claudeMdTmpl.replace(/\{\{project-name\}\}/g, name);
+  writeFileSync(join(directory, 'CLAUDE.md'), claudeMd);
+
+  // Process workspace.json template
+  const workspaceJsonTmpl = readFileSync(join(TEMPLATE_DIR, 'workspace.json.tmpl'), 'utf-8');
+  const workspaceConfig = JSON.parse(workspaceJsonTmpl.replace(/\{\{project-name\}\}/g, name));
+
+  // Stamp template version
+  const pkgJson = JSON.parse(readFileSync(join(TEMPLATE_DIR, '..', 'package.json'), 'utf-8'));
+  workspaceConfig.workspace.templateVersion = pkgJson.version;
+
+  // Populate repos
+  for (const repo of repos) {
+    workspaceConfig.repos[repo.name] = {
+      remote: repo.remote,
+      branch: repo.branch,
+    };
+    if (repo.primary) {
+      workspaceConfig.repos[repo.name].primary = true;
+    }
+  }
+  writeFileSync(
+    join(directory, 'workspace.json'),
+    JSON.stringify(workspaceConfig, null, 2) + '\n'
+  );
+
+  // Write settings.local.json with user identity
+  const settingsLocal = {
+    workspace: {
+      user: userName,
+    },
+  };
+  writeFileSync(
+    join(directory, '.claude', 'settings.local.json'),
+    JSON.stringify(settingsLocal, null, 2) + '\n'
+  );
+
+  // Activate selected optional rules (rename .md.skip → .md)
+  for (const rule of activateRules) {
+    const skipPath = join(directory, '.claude', 'rules', `${rule}.md.skip`);
+    const activePath = join(directory, '.claude', 'rules', `${rule}.md`);
+    if (existsSync(skipPath)) {
+      renameSync(skipPath, activePath);
+    }
+  }
+
+  return directory;
+}

package/lib/upgrade.mjs

@@ -0,0 +1,42 @@
+// lib/upgrade.mjs
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { stagePayload } from './payload.mjs';
+
+export async function upgradeWorkspace(targetDir) {
+  const workspaceJsonPath = join(targetDir, 'workspace.json');
+
+  console.log(`\n  @ulysses-ai/create-workspace --upgrade`);
+  console.log(`  Target: ${targetDir}\n`);
+
+  // Verify workspace exists and is initialized
+  if (!existsSync(workspaceJsonPath)) {
+    console.error(`  Error: No workspace.json found at ${targetDir}.`);
+    console.error(`  Run with --init instead:\n    npx @ulysses-ai/create-workspace --init ${targetDir}\n`);
+    process.exit(1);
+  }
+
+  const config = JSON.parse(readFileSync(workspaceJsonPath, 'utf-8'));
+  const initialized = config.workspace?.initialized || config.workspace?.templateVersion;
+  if (!initialized) {
+    console.error(`  Error: Workspace not initialized.`);
+    console.error(`  Run with --init instead:\n    npx @ulysses-ai/create-workspace --init ${targetDir}\n`);
+    process.exit(1);
+  }
+
+  const fromVersion = config.workspace?.templateVersion || 'unknown';
+
+  // Stage payload
+  const { toVersion } = stagePayload(targetDir, { action: 'upgrade', fromVersion });
+
+  if (fromVersion === toVersion) {
+    console.log(`  Workspace is already on template v${toVersion}.`);
+    console.log(`  Payload staged anyway — run /workspace-update to verify integrity.\n`);
+  } else {
+    console.log(`  Staged template payload (v${fromVersion} → v${toVersion})`);
+  }
+
+  console.log(`  Template payload staged. The workspace will update on your
+  next Claude Code prompt.
+`);
+}