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

package/template/.claude/rules/scope-guard.md.skip

@@ -0,0 +1,22 @@
+# Scope Guard
+
+Activate this rule to detect and push back on scope creep during work sessions.
+
+## Detection
+
+- When a task grows beyond its original description, flag it: "This started as {original} but is becoming {current}. Split into a separate branch?"
+- When a bugfix turns into a refactor, name it: "The fix is done but you're now restructuring {module}. That's a separate chore/ branch."
+- When "one more thing" keeps happening, count them: "That's the third addition beyond the original scope. Consider /handoff the extras as follow-up work."
+
+## Response
+
+- State the scope drift once, clearly
+- Suggest how to split: which part is current branch, which is follow-up
+- Follow the user's decision — if they want to keep going, proceed
+- Don't lecture or repeat the concern after the user decides
+
+## YAGNI Enforcement
+
+- Resist building for hypothetical future requirements
+- Question abstractions that don't serve the current task: "Do we need this interface right now, or is the concrete implementation enough?"
+- Three similar lines of code is better than a premature abstraction

package/template/.claude/rules/superpowers-workflow.md.skip

@@ -0,0 +1,22 @@
+# Superpowers Workflow
+
+Activate this rule if the superpowers plugin is installed.
+
+## Research Phase (mandatory before implementation)
+
+- Review existing codebase for relevant patterns and prior art
+- Search official documentation for the technologies involved
+- Research best practices, production hardening, and known pitfalls via web search
+- Summarize findings for the user before proceeding to design
+
+## Specs and Plans
+
+- Specs and plans live in the active worktree during development
+- They are ephemeral — consumed by /complete-work into release notes, then removed
+- If a spec/plan already exists for the current branch, version it: `-v2`, `-v3`, etc.
+
+## Execution
+
+- Use subagent-driven development for executing plans
+- One subagent per task, sequential implementation, parallel review
+- Never dispatch parallel implementation subagents on the same codebase

package/template/.claude/rules/token-economics.md.skip

@@ -0,0 +1,31 @@
+# Token Economics
+
+Activate this rule for token-aware behavior — cost-conscious model selection, context efficiency, and waste reduction.
+
+## Model Selection
+
+- Suggest appropriate model/effort for each task:
+  - Search and exploration → Sonnet (fast, cheap)
+  - Focused implementation → inherit or Sonnet
+  - Review and judgment → Opus (best reasoning)
+- Don't use Opus for tasks Sonnet can handle
+- When dispatching subagents, choose the cheapest model that can succeed
+
+## Context Efficiency
+
+- Don't read files that aren't needed for the current task
+- When searching, use targeted queries rather than broad exploration
+- If a tool result is large and mostly irrelevant, note what matters and move on
+- Prefer exact file paths over glob searches when you know where things are
+
+## Waste Detection
+
+- Flag when context is heavy with resolved discussions that could be compacted
+- Suggest /braindump to offload discussion into files, freeing context for work
+- Note when subagent context is bloated relative to the task size
+- If locked context exceeds the 10KB target, mention it
+
+## Compaction Awareness
+
+- When approaching compaction threshold, prioritize capturing over continuing
+- After compaction, avoid re-reading files that were already discussed — check shared-context first

package/template/.claude/rules/work-item-tracking.md

@@ -0,0 +1,90 @@
+# Work Item Tracking
+
+When a workspace has an issue tracker configured, all work items — bugs, features, chores — live in that tracker. Skills and scripts read and write the tracker through the adapter at `.claude/scripts/trackers/{type}.mjs`. There is no local file that mirrors the tracker's state.
+
+## Why external-first
+
+- **Atomic assignment.** Two teammates can't accidentally start the same ticket — the tracker is the source of truth for "who has this."
+- **Real-time state.** Status changes propagate to the whole team the moment they happen, not after a commit + push.
+- **Tool parity.** Humans and Claude see the same list of tickets in the same place.
+
+## Configuration
+
+`workspace.json` → `workspace.tracker`:
+
+```json
+{
+  "workspace": {
+    "tracker": {
+      "type": "github-issues",
+      "repo": "your-org/your-workspace"
+    }
+  }
+}
+```
+
+- `type` — identifies the adapter module at `.claude/scripts/trackers/{type}.mjs`. Only `github-issues` ships in the template; others are additive.
+- `repo` — adapter-specific. For `github-issues`, the owner/name slug of the repo where issues live. `"auto"` resolves to the workspace's own git remote.
+
+Absence of `workspace.tracker` means tracking is disabled. Skills handle this by falling back to a blank/describe-the-work flow — they do not fabricate a local mirror.
+
+## Adapter interface (for Claude)
+
+Import from `.claude/scripts/trackers/interface.mjs`:
+
+```javascript
+import { createTracker, AlreadyAssignedError } from '.claude/scripts/trackers/interface.mjs';
+
+const tracker = createTracker(workspace.tracker);
+
+const mine = await tracker.listAssignedToMe();        // Issue[]
+const open = await tracker.listUnassigned();          // Issue[]
+const issue = await tracker.claim('gh:42');           // throws AlreadyAssignedError on contention
+const created = await tracker.createIssue({ title, body, labels: ['feat', 'P2'], milestone: 'Backlog' });
+await tracker.comment('gh:42', 'paused here; see branch X');
+await tracker.closeIssue('gh:42', { comment: 'shipped in PR #99' });
+
+// Setup-time: idempotent milestone / label creation
+await tracker.ensureLabels();                          // creates bug/feat/chore/P1/P2/P3 if absent
+await tracker.ensureMilestone({ title: 'Backlog', description: 'Triage later' });
+```
+
+All skills that touch work items use this interface. Adapters are not called directly.
+
+## Session linkage
+
+When `/start-work` links a session to a tracker issue, the session tracker's frontmatter gets:
+
+```yaml
+workItem: gh:42
+```
+
+The value is the adapter-prefixed issue ID. This survives adapter swaps — replacing the GitHub adapter with a Linear adapter later doesn't require re-linking session trackers (though the prefix changes for *new* sessions).
+
+## When to create issues
+
+- **User describes new work during `/start-work`** → skill calls `createIssue` after session creation.
+- **Bug or feature discovered mid-session** → Claude proactively asks "Create an issue for this? [Y/n]"; if yes, calls `createIssue` and links the session (if it's scoped to this session) or leaves it unassigned (if it's a future concern).
+- **Never during braindumps or handoffs** — those are discussion artifacts, not work items. Action items can later graduate to issues during `/start-work`.
+
+## When NOT to maintain local state
+
+- Do not create, write to, or read `shared-context/open-work.md`. That file is deprecated.
+- Do not write ticket state into `session.md` frontmatter beyond the `workItem:` pointer. Status, assignment, milestone, and labels live in the tracker.
+- Do not cache issue bodies locally. Always fetch via `tracker.getIssue(id)` when the content is needed.
+
+## Skill behavior
+
+Skills that interact with the tracker:
+
+- **`/setup-tracker`** — configures `workspace.json` → `tracker` block, calls `ensureLabels()`.
+- **`/start-work`** — fetches assigned-to-me first; falls back to unassigned; claims atomically on pick. Records `workItem:` in session tracker.
+- **`/pause-work`** — comments the pause capture on the linked issue.
+- **`/complete-work`** — closes the linked issue after PRs merge, with a final comment linking them.
+- **`/workspace-init`** — prompts to run `/setup-tracker` at the end of init. Does not pre-populate tickets.
+
+## What this rule does NOT do
+
+- Does not prescribe a specific tracker type. Adapter choice is per workspace.
+- Does not prescribe label or milestone schemas beyond the six standard labels (`bug`, `feat`, `chore`, `P1`, `P2`, `P3`) created by `ensureLabels()`. Teams with existing trackers can skip label creation during setup.
+- Does not replace tracker-native features (comments, reactions, linked PRs) — use the tracker's UI for those.

package/template/.claude/rules/workspace-structure.md

@@ -0,0 +1,69 @@
+# Workspace Structure
+
+This workspace follows the claude-workspace convention. All paths are relative to the workspace root.
+
+## Directory Layout
+
+| Directory | Purpose | Tracked in git? |
+|-----------|---------|-----------------|
+| `repos/` | Source clones of project repositories (one per repo, stays on default branch) | No (gitignored, lazy) |
+| `work-sessions/` | Per-session folders — one folder per active or paused work session | No (gitignored entirely at the launcher) |
+| `work-sessions/{name}/workspace/` | Workspace worktree for this session, on the session branch | Yes — on the session branch, not on main |
+| `work-sessions/{name}/workspace/session.md` | Unified session tracker at the top of the session branch (frontmatter = machine state, body = human content) | Yes — on the session branch |
+| `work-sessions/{name}/workspace/design-*.md` | Specs for this session — consumed into release notes by /complete-work | Yes — on the session branch |
+| `work-sessions/{name}/workspace/plan-*.md` | Plans for this session — consumed into release notes by /complete-work | Yes — on the session branch |
+| `work-sessions/{name}/workspace/repos/` | Real directory holding nested project worktrees for this session | No (gitignored) |
+| `work-sessions/{name}/workspace/repos/{repo}/` | Project worktree nested inside the workspace worktree | No (gitignored) |
+| `shared-context/` | Shared memory — handoffs, braindumps, team knowledge | Yes |
+| `shared-context/locked/` | Team truths — loaded every session, injected into subagents | Yes |
+| `shared-context/{user}/` | User-scoped working context — default for all captures | Yes |
+| `workspace-scratchpad/` | Disposable workspace-scoped files — session log, hook debug output | No (gitignored, lazy) |
+| `.claude/` | Claude Code configuration — rules, agents, skills, hooks, scripts, lib | Yes (except settings.local.json) |
+
+Session content (tracker, specs, plans) lives at the top of each session's workspace worktree. It is tracked on the session branch, not on main. Pushing the session branch carries durable session thinking across machines. When `/complete-work` finalizes the session, it synthesizes the content into release notes and removes the files from the branch before the final PR so main's top level stays free of session artifacts.
+
+## Shared Context Levels
+
+| Level | What lives there | Default? |
+|-------|-----------------|----------|
+| `locked/` | Team truths — always loaded, injected into subagents | Promoted by /release |
+| Root | Team-visible ephemerals — cross-team handoffs, post-release leftovers | Explicit choice |
+| `{user}/` | Ongoing personal context — persists across work sessions | Default for captures |
+
+Inflight session state lives inside the session worktree at `work-sessions/{name}/workspace/session.md`, not in `shared-context/`. Shared-context is for knowledge that outlives any individual session.
+
+User-scoped is the default for captures. Root is only for content deliberately made team-visible.
+
+## Spec and Plan Locations — MANDATORY OVERRIDE
+
+**Specs and plans MUST be written at the top of the active session's workspace worktree, not to `docs/superpowers/` or any other location.**
+
+- Specs: `design-{topic}.md` at the top of `work-sessions/{session-name}/workspace/`
+- Plans: `plan-{topic}.md` at the top of `work-sessions/{session-name}/workspace/`
+
+From inside the worktree, these are plain top-level files (`design-{topic}.md`, `plan-{topic}.md`) sitting alongside `CLAUDE.md` and `workspace.json`. They are tracked on the session branch and travel with the branch on `git push`.
+
+This overrides any default paths specified by external skills (e.g., Superpowers brainstorming defaults to `docs/superpowers/specs/`). Those skills state that user preferences override their defaults — this rule IS that override. Do not create `docs/superpowers/` directories. Do not write specs or plans anywhere other than the top of the active worktree.
+
+If a spec/plan already exists for the current session, version it: `design-{topic}-v2.md`, `design-{topic}-v3.md`.
+
+`/complete-work` reads specs and plans from the worktree to synthesize release notes, then removes them in a dedicated commit before the final PR so main's tree stays pristine.
+
+## Naming Conventions
+
+- Session folders: `work-sessions/{session-name}/`
+- Workspace worktrees: `work-sessions/{session-name}/workspace/`
+- Project worktrees: `work-sessions/{session-name}/workspace/repos/{repo-name}/`
+- Session trackers: `work-sessions/{session-name}/workspace/session.md`
+- Specs: `design-{topic}.md` (top of worktree)
+- Plans: `plan-{topic}.md` (top of worktree)
+- Handoffs and braindumps: named by topic (no date prefix — use frontmatter `updated:`)
+
+## Rules
+
+- The workspace root stays on main — it is the launcher, not the workspace.
+- All real work happens in workspace worktrees at `work-sessions/{name}/workspace/`.
+- Session content (tracker, specs, plans) is written from inside the worktree and committed on the session branch. Writes from the launcher cannot reach files that live inside a worktree's git-path space.
+- Source clones at `repos/{repo-name}/` stay on their default branch — never checkout a feature branch there.
+- `workspace-scratchpad/` is for disposable files only — session log, hook debug output, temporary pointers.
+- Project worktrees are nested inside the workspace worktree's real `repos/` directory — no symlink.

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

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// 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 { execSync } from 'child_process';
+import { join } from 'path';
+import {
+  getWorkspaceRoot,
+  getMainRoot,
+  readJSON,
+  readSessionTracker,
+  updateSessionTracker,
+  sessionFolderPath,
+  normalizeRepos,
+} from '../hooks/_utils.mjs';
+
+const args = process.argv.slice(2);
+const getArg = (name) => {
+  const idx = args.indexOf(`--${name}`);
+  return idx >= 0 && args[idx + 1] ? args[idx + 1] : null;
+};
+
+const sessionName = getArg('session-name');
+const repo = getArg('repo');
+
+if (!sessionName || !repo) {
+  console.error('Usage: add-repo-to-session.mjs --session-name NAME --repo REPO');
+  process.exit(1);
+}
+
+// Promote to the launcher root via the active-session pointer so session
+// paths resolve correctly whether the script is invoked from the launcher
+// or from inside a worktree.
+const root = getMainRoot(getWorkspaceRoot(import.meta.url));
+const config = readJSON(join(root, 'workspace.json'));
+const tracker = readSessionTracker(root, sessionName);
+
+if (!tracker) {
+  console.log(JSON.stringify({ success: false, error: `No session tracker found for "${sessionName}"` }));
+  process.exit(1);
+}
+
+if (!config?.repos?.[repo]) {
+  console.log(JSON.stringify({ success: false, error: `Repo "${repo}" not found in workspace.json` }));
+  process.exit(1);
+}
+
+const existingRepos = normalizeRepos(tracker.repos);
+if (existingRepos.includes(repo)) {
+  console.log(JSON.stringify({ success: false, error: `Repo "${repo}" is already in this session` }));
+  process.exit(1);
+}
+
+const repoBranch = config.repos[repo].branch || 'main';
+const reposDir = join(root, 'repos');
+const repoDir = join(reposDir, repo);
+const wsWorktree = join(sessionFolderPath(root, sessionName), 'workspace');
+const projWorktree = join(wsWorktree, 'repos', repo);
+
+try {
+  execSync(`git fetch origin`, { cwd: repoDir, stdio: 'pipe', timeout: 30000 });
+  execSync(`git branch "${tracker.branch}" "origin/${repoBranch}"`, { cwd: repoDir, stdio: 'pipe' });
+  execSync(`git worktree add "${projWorktree}" "${tracker.branch}"`, { cwd: repoDir, stdio: 'pipe' });
+
+  const newRepos = [...existingRepos, repo];
+  const today = new Date().toISOString().slice(0, 10);
+  updateSessionTracker(root, sessionName, { repos: newRepos, updated: today });
+
+  const rel = (p) => p.startsWith(root + '/') ? p.slice(root.length + 1) : p;
+  console.log(JSON.stringify({
+    success: true,
+    projWorktree: rel(projWorktree),
+    repos: newRepos,
+  }));
+} catch (err) {
+  console.log(JSON.stringify({ success: false, error: err.message }));
+  process.exit(1);
+}

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

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// Tear down a work session's worktrees, branches, and folder.
+//
+// Teardown order is MANDATORY:
+//   1. Remove each project worktree from its project repo
+//   2. Remove the workspace worktree from the workspace repo
+//   3. Prune each project repo (belt-and-suspenders)
+//   4. Delete all local branches
+//   5. Remove the whole work-sessions/{name}/ folder
+//
+// 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 { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import {
+  getWorkspaceRoot,
+  readSessionTracker,
+  deleteSessionFolder,
+  sessionFolderPath,
+  normalizeRepos,
+} from '../hooks/_utils.mjs';
+
+const args = process.argv.slice(2);
+const getArg = (name) => {
+  const idx = args.indexOf(`--${name}`);
+  return idx >= 0 && args[idx + 1] ? args[idx + 1] : null;
+};
+
+const sessionName = getArg('session-name');
+if (!sessionName) {
+  console.error('Usage: cleanup-work-session.mjs --session-name NAME');
+  process.exit(1);
+}
+
+const root = getWorkspaceRoot(import.meta.url);
+const tracker = readSessionTracker(root, sessionName);
+const repos = normalizeRepos(tracker?.repos);
+const branch = tracker?.branch;
+const reposDir = join(root, 'repos');
+const sessionFolder = sessionFolderPath(root, sessionName);
+const wsWorktree = join(sessionFolder, 'workspace');
+
+const removed = [];
+const errors = [];
+
+// Step 1: Remove each project worktree FIRST, from its project repo
+for (const repo of repos) {
+  const projWorktree = join(wsWorktree, 'repos', repo);
+  const repoDir = join(reposDir, repo);
+  if (existsSync(projWorktree)) {
+    try {
+      execSync(`git worktree remove "${projWorktree}" --force`, { cwd: repoDir, stdio: 'pipe' });
+      removed.push(`project worktree ${repo}`);
+    } catch (err) {
+      errors.push(`Failed to remove ${repo} worktree: ${err.message}`);
+    }
+  }
+}
+
+// Step 2: Remove the workspace worktree AFTER project worktrees are gone
+if (existsSync(wsWorktree)) {
+  try {
+    execSync(`git worktree remove "${wsWorktree}" --force`, { cwd: root, stdio: 'pipe' });
+    removed.push('workspace worktree');
+  } catch (err) {
+    errors.push(`Failed to remove workspace worktree: ${err.message}`);
+  }
+}
+
+// Step 3: Prune each project repo to mop up orphans from any prior misuses
+for (const repo of repos) {
+  const repoDir = join(reposDir, repo);
+  try {
+    execSync('git worktree prune', { cwd: repoDir, stdio: 'pipe' });
+  } catch {
+    // Non-fatal — prune is a safety net
+  }
+}
+
+// Step 4: Delete local branches
+if (branch) {
+  for (const repo of repos) {
+    const repoDir = join(reposDir, repo);
+    try {
+      execSync(`git branch -D "${branch}"`, { cwd: repoDir, stdio: 'pipe' });
+    } catch {
+      // Non-fatal — branch may already be gone or refuse to delete
+    }
+  }
+  try {
+    execSync(`git branch -D "${branch}"`, { cwd: root, stdio: 'pipe' });
+  } catch {
+    // Non-fatal
+  }
+}
+
+// Step 5: Delete the whole work-sessions/{name}/ folder. The session.md,
+// specs, plans, and any local-only artifacts vanish. Their content was
+// archived into release notes by /complete-work before this script ran.
+deleteSessionFolder(root, sessionName);
+
+console.log(JSON.stringify({
+  success: errors.length === 0,
+  removed,
+  errors: errors.length > 0 ? errors : undefined,
+}));

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

@@ -0,0 +1,124 @@
+#!/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 { execSync } from 'child_process';
+import { existsSync, mkdirSync, copyFileSync } from 'fs';
+import { join, resolve } from 'path';
+import {
+  getWorkspaceRoot,
+  readJSON,
+  sessionFilePath,
+  sessionFolderPath,
+  createSessionTracker,
+  writeActiveSessionPointer,
+} from '../hooks/_utils.mjs';
+
+const args = process.argv.slice(2);
+const getArg = (name) => {
+  const idx = args.indexOf(`--${name}`);
+  return idx >= 0 && args[idx + 1] ? args[idx + 1] : null;
+};
+
+const sessionName = getArg('session-name');
+const branch = getArg('branch');
+const repoArg = getArg('repo');
+const user = getArg('user');
+const description = getArg('description') || '';
+
+if (!sessionName || !branch || !repoArg || !user) {
+  console.error('Usage: create-work-session.mjs --session-name NAME --branch BRANCH --repo REPO[,REPO2,...] --user USER [--description DESC]');
+  process.exit(1);
+}
+
+const repos = repoArg.split(',').map(r => r.trim()).filter(Boolean);
+const root = getWorkspaceRoot(import.meta.url);
+const config = readJSON(join(root, 'workspace.json'));
+const reposDir = join(root, 'repos');
+
+const sessionFolder = sessionFolderPath(root, sessionName);
+const wsWorktree = join(sessionFolder, 'workspace');
+
+try {
+  // Ensure the work-sessions/ parent and the session folder exist
+  mkdirSync(sessionFolder, { recursive: true });
+
+  // Create the workspace branch and worktree
+  execSync(`git branch "${branch}" main`, { cwd: root, stdio: 'pipe' });
+  execSync(`git worktree add "${wsWorktree}" "${branch}"`, { cwd: root, stdio: 'pipe' });
+
+  // Real repos/ directory inside the workspace worktree (no symlink).
+  // The workspace .gitignore pattern `repos` (no slash) covers both the
+  // workspace root's repos/ and this one.
+  const nestedReposDir = join(wsWorktree, 'repos');
+  mkdirSync(nestedReposDir, { recursive: true });
+
+  // Create each project branch and nest its worktree inside the workspace worktree
+  const projWorktrees = [];
+  for (const repo of repos) {
+    const repoBranch = config?.repos?.[repo]?.branch || 'main';
+    const repoDir = join(reposDir, repo);
+    const projWorktree = join(nestedReposDir, repo);
+
+    execSync(`git fetch origin`, { cwd: repoDir, stdio: 'pipe', timeout: 30000 });
+    execSync(`git branch "${branch}" "origin/${repoBranch}"`, { cwd: repoDir, stdio: 'pipe' });
+    execSync(`git worktree add "${projWorktree}" "${branch}"`, { cwd: repoDir, stdio: 'pipe' });
+
+    projWorktrees.push(projWorktree);
+  }
+
+  // Copy settings.local.json into the workspace worktree if present at root
+  const settingsSrc = join(root, '.claude', 'settings.local.json');
+  const settingsDst = join(wsWorktree, '.claude', 'settings.local.json');
+  if (existsSync(settingsSrc)) {
+    copyFileSync(settingsSrc, settingsDst);
+  }
+
+  // Write the active-session pointer inside the worktree's .claude/ dir so
+  // hooks running inside the worktree know which session is in scope.
+  writeActiveSessionPointer(wsWorktree, { name: sessionName, rootPath: root });
+
+  // Write the unified session.md tracker inside the worktree (at the top of
+  // the session branch) and commit it on the branch as the branch's first
+  // commit above main. Frontmatter holds machine state; body holds human
+  // content. Hooks and skills update the frontmatter via session-frontmatter
+  // helpers; humans update the body directly.
+  const now = new Date().toISOString();
+  const today = now.slice(0, 10);
+  createSessionTracker(
+    root,
+    sessionName,
+    {
+      type: 'session-tracker',
+      name: sessionName,
+      description,
+      status: 'active',
+      branch,
+      created: now,
+      user,
+      repos,
+      chatSessions: [],
+      author: user,
+      updated: today,
+    },
+    `\n# Work Session: ${sessionName}\n\n${description}\n\n## Progress\n\n(Updated as the session progresses)\n`
+  );
+  execSync('git add session.md', { cwd: wsWorktree, stdio: 'pipe' });
+  execSync(`git commit -m "chore: initialize session tracker for ${sessionName}"`, {
+    cwd: wsWorktree,
+    stdio: 'pipe',
+  });
+
+  // Paths for the success payload, relative to the workspace root
+  const rel = (p) => p.startsWith(root + '/') ? p.slice(root.length + 1) : p;
+
+  console.log(JSON.stringify({
+    success: true,
+    sessionFolder: rel(sessionFolder),
+    wsWorktree: rel(wsWorktree),
+    projWorktrees: projWorktrees.map(rel),
+    tracker: rel(sessionFilePath(root, sessionName)),
+  }));
+} catch (err) {
+  console.log(JSON.stringify({ success: false, error: err.message }));
+  process.exit(1);
+}

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

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// One-shot migration: read an open-work.md file and create real issues via the
+// configured tracker adapter. Prints the {source_id → issue_id} mapping at the
+// end. NOT idempotent — if it fails partway, clean up orphan issues manually
+// and re-run.
+//
+// Usage:
+//   node .claude/scripts/migrate-open-work.mjs <path-to-open-work.md> [workspace-json-path]
+
+import { readFileSync } from 'node:fs';
+import { createTracker } from './trackers/interface.mjs';
+
+const openWorkPath = process.argv[2];
+const workspaceJsonPath = process.argv[3] || 'workspace.json';
+
+if (!openWorkPath) {
+  console.error('Usage: migrate-open-work.mjs <path-to-open-work.md> [workspace-json-path]');
+  process.exit(1);
+}
+
+const workspace = JSON.parse(readFileSync(workspaceJsonPath, 'utf-8'));
+const trackerConfig = workspace.workspace?.tracker;
+if (!trackerConfig) {
+  console.error('No tracker configured in workspace.json — run /setup-tracker first.');
+  process.exit(1);
+}
+
+const tracker = createTracker(trackerConfig);
+const content = readFileSync(openWorkPath, 'utf-8');
+
+// Parse ticket rows. Matches the 8-column milestone-aware format.
+const rowRe = /^\|\s*(\d+)\s*\|\s*(bug|feat|chore)\s*\|\s*(P[123])\s*\|\s*([^|]+?)\s*\|\s*(open|in-progress|paused|done)\s*\|\s*([^|]+?)\s*\|\s*(.+?)\s*\|\s*$/gm;
+const detailRe = /^### #(\d+)\s*—\s*[^\n]+\n\n([\s\S]+?)(?=^### #\d+|<!-- tracker-state|\Z)/gm;
+
+const details = {};
+for (const m of content.matchAll(detailRe)) {
+  details[parseInt(m[1], 10)] = m[2].trim();
+}
+
+const tickets = [];
+for (const m of content.matchAll(rowRe)) {
+  const id = parseInt(m[1], 10);
+  const msRaw = m[4].trim();
+  tickets.push({
+    id,
+    type: m[2],
+    priority: m[3],
+    milestone: msRaw === '—' || msRaw === '' ? null : msRaw,
+    status: m[5],
+    branch: m[6].trim() === '—' ? null : m[6].trim(),
+    title: m[7].trim(),
+    body: details[id] || '',
+  });
+}
+
+console.log(`Tracker: ${tracker.identity}`);
+console.log(`Found ${tickets.length} tickets in ${openWorkPath}.\n`);
+
+const mapping = [];
+
+for (const ticket of tickets) {
+  console.log(`Creating #${ticket.id} — ${ticket.title} [${ticket.type}/${ticket.priority}]`);
+  const labels = [ticket.type, ticket.priority];
+  const body = [
+    ticket.body || '_No details in open-work.md._',
+    '',
+    '---',
+    '',
+    `Migrated from \`shared-context/open-work.md\` ticket #${ticket.id} (status at migration: \`${ticket.status}\`${ticket.branch ? `, branch: \`${ticket.branch}\`` : ''}).`,
+  ].join('\n');
+
+  const issue = await tracker.createIssue({ title: ticket.title, body, labels, milestone: ticket.milestone });
+  mapping.push({ sourceId: ticket.id, issueId: issue.id, number: issue.number, url: issue.url, status: ticket.status });
+
+  if (ticket.status === 'in-progress' || ticket.status === 'paused') {
+    try {
+      await tracker.claim(issue.id);
+      console.log(`  → claimed (status was ${ticket.status})`);
+    } catch (e) {
+      console.warn(`  ! claim failed: ${e.message}`);
+    }
+  }
+
+  console.log(`  → ${issue.url}`);
+}
+
+console.log('\n=== Migration mapping ===');
+for (const row of mapping) {
+  console.log(`#${row.sourceId} → ${row.issueId} (${row.url}) [was ${row.status}]`);
+}
+console.log(`\nDone. Delete ${openWorkPath} on its branch after verifying the issues.`);