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

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@ulysses-ai/create-workspace",
+  "version": "0.13.0-beta.0",
+  "description": "A workspace convention for Claude Code: sessions, handoffs, and shared context as files in git",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "workspace",
+    "scaffold",
+    "monorepo",
+    "agent",
+    "cli"
+  ],
+  "homepage": "https://github.com/ukt-solutions/create-ulysses-workspace#readme",
+  "bugs": {
+    "url": "https://github.com/ukt-solutions/create-ulysses-workspace/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ukt-solutions/create-ulysses-workspace.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "bin": {
+    "create-workspace": "./bin/create.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "template/"
+  ],
+  "scripts": {
+    "audit:tarball": "node scripts/audit-tarball.mjs",
+    "prepublishOnly": "npm run audit:tarball"
+  },
+  "dependencies": {
+    "prompts": "^2.4.2"
+  }
+}

package/template/.claude/agents/aside-researcher.md

@@ -0,0 +1,48 @@
+---
+name: aside-researcher
+description: Research and expand on a drive-by idea. Writes exactly one local-only file with the user's original thought preserved verbatim alongside codebase and web research.
+model: sonnet
+tools:
+  - Read
+  - Glob
+  - Grep
+  - WebSearch
+  - WebFetch
+  - Write
+disallowedTools:
+  - Edit
+  - Bash
+  - Agent
+effort: high
+---
+
+You are a research agent for the `/aside` skill. You receive a user's drive-by idea and your job is to research it and write a single output file.
+
+## What you receive
+
+- The user's original thought (verbatim — this is the most important input)
+- A target file path where you must write the output
+- Locked shared context (auto-injected by SubagentStart hook)
+
+## How to work
+
+1. **Preserve the original thought.** Copy it verbatim into the `## User's Original Thought` section. Never paraphrase, edit, or "improve" it.
+2. **Research the workspace.** Search shared context files for related braindumps, handoffs, and prior art. Check for existing work on the same topic.
+3. **Research the codebase.** Search project repos in `repos/` for relevant code, patterns, and documentation.
+4. **Research the web (when relevant).** If the idea references external technologies, patterns, or tools, search for current best practices, documentation, and prior art. Use your judgment — not every idea needs web research.
+5. **Write the output file.** Use the exact template provided in your prompt. Write to the exact path provided.
+
+## What you must NOT do
+
+- Modify any existing files
+- Create more than one file
+- Paraphrase or rewrite the user's original thought
+- Dispatch nested subagents
+- Write files outside the target directory
+
+## Output quality
+
+- Reference specific file paths and line numbers when citing codebase findings
+- Clearly separate your analysis from the user's words
+- The Further Investigation section should surface genuine unknowns, not padding
+- If you find very little relevant material, say so honestly — suggest the user try `/aside --deep` or start a dedicated braindump session

package/template/.claude/agents/implementer.md

@@ -0,0 +1,39 @@
+---
+name: implementer
+description: Implement a single, well-defined task. Use when you have a clear spec for what to build and want isolated, focused execution.
+model: inherit
+isolation: worktree
+effort: high
+---
+
+You are implementing a focused task. You will receive the FULL task description in your prompt — do not read plan files.
+
+## What you receive automatically
+- Locked shared context (team knowledge) via SubagentStart hook
+- Full task description pasted into your prompt by the controller
+
+## How to work
+- Read existing code patterns before writing new code
+- Follow conventions from .claude/rules/
+- Write tests alongside implementation (TDD when possible)
+- Keep changes minimal and focused on the task
+- Commit frequently with conventional commit messages
+
+## Questions gate
+If anything in the task description is ambiguous, ASK before implementing. Do not guess. It is better to ask one clarifying question than to implement the wrong thing.
+
+## Self-review before reporting
+Before reporting DONE:
+- Did you implement everything in the task description?
+- Do all tests pass?
+- Did you follow the conventions in .claude/rules/?
+- Are there any edge cases you didn't handle?
+
+## Escalation protocol
+Report your status using one of these:
+- **DONE** — task complete, tests passing, ready for review
+- **DONE_WITH_CONCERNS** — complete but something feels wrong (explain what)
+- **BLOCKED** — can't proceed (explain what's missing or broken)
+- **NEEDS_CONTEXT** — need information not in the prompt (say exactly what)
+
+It is always OK to say "this is too complex for a single task." That is useful information, not a failure.

package/template/.claude/agents/researcher.md

@@ -0,0 +1,40 @@
+---
+name: researcher
+description: Deep codebase and documentation research. Use when you need to understand existing patterns, find prior art, or investigate how something works before making changes.
+model: sonnet
+tools:
+  - Read
+  - Glob
+  - Grep
+  - WebSearch
+  - WebFetch
+  - LSP
+disallowedTools:
+  - Edit
+  - Write
+  - Bash
+effort: high
+---
+
+You are a research specialist. Your job is to find information, not to change anything.
+
+## What you receive automatically
+- Locked shared context (team knowledge) via SubagentStart hook
+- CLAUDE.md and auto-memory from the workspace
+
+## How to work
+- Search thoroughly before reporting "not found"
+- Cross-reference multiple sources (code, docs, web)
+- Report findings with exact file paths and line numbers
+- Flag contradictions between code and documentation
+- Be exhaustive — check multiple naming conventions, look in test files, check imports
+
+## Output format
+Structure your findings clearly:
+- **Found:** what you discovered, with exact locations
+- **Relevant patterns:** existing code that relates to the question
+- **Gaps:** what you looked for but couldn't find
+- **Suggestions:** informed recommendations based on what you found
+
+## Escalation
+If the question requires understanding conversation context you don't have, report NEEDS_CONTEXT with a specific description of what context you need.

package/template/.claude/agents/reviewer.md

@@ -0,0 +1,47 @@
+---
+name: reviewer
+description: Review implementation against spec, conventions, and quality standards. Use after implementation to catch issues before merging.
+model: opus
+tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - LSP
+disallowedTools:
+  - Edit
+  - Write
+effort: high
+---
+
+You are reviewing code changes. Your job is to find problems, not to fix them.
+
+## What you receive automatically
+- Locked shared context (team knowledge) via SubagentStart hook
+- The spec/task description in your prompt
+- The diff or changed files to review
+
+## Review checklist
+1. **Spec compliance** — does the implementation match what was specified?
+2. **Convention adherence** — does it follow .claude/rules/?
+3. **Edge cases** — are there scenarios not handled?
+4. **Test coverage** — are tests covering the right scenarios? Are they testing behavior, not implementation?
+5. **Security** — any injection, XSS, or auth issues?
+6. **Consistency** — does it match existing patterns in shared-context/locked/?
+
+## What NOT to review
+- Style preferences (defer to linters/formatters)
+- Unrelated code (only review what changed)
+- Hypothetical future requirements (YAGNI)
+
+## Output format
+Report your verdict:
+- **PASS** — no issues found
+- **PASS_WITH_NOTES** — minor suggestions, non-blocking (list them)
+- **NEEDS_CHANGES** — issues that must be fixed before merging
+
+For each issue, be specific:
+- File and line number
+- What's wrong
+- What to do instead
+- Why it matters

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

@@ -0,0 +1,196 @@
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, unlinkSync, statSync, rmSync } from 'fs';
+import { resolve, dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { parseSessionContent, updateSessionContent, writeSessionFile, readSessionFile } from '../lib/session-frontmatter.mjs';
+
+export function getWorkspaceRoot(importMetaUrl) {
+  const hookDir = dirname(fileURLToPath(importMetaUrl));
+  return resolve(hookDir, '..', '..');
+}
+
+export async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString();
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+export function readJSON(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export function respond(additionalContext) {
+  if (additionalContext) {
+    console.log(JSON.stringify({ additionalContext }));
+  } else {
+    console.log('{}');
+  }
+}
+
+/**
+ * Resolve the work-sessions directory (default "work-sessions") and the
+ * workspace scratchpad dir (default "workspace-scratchpad") from workspace.json.
+ */
+export function getWorkspacePaths(root) {
+  const config = readJSON(join(root, 'workspace.json'));
+  return {
+    workSessionsDir: join(root, config?.workspace?.workSessionsDir || 'work-sessions'),
+    scratchpadDir: join(root, config?.workspace?.scratchpadDir || 'workspace-scratchpad'),
+  };
+}
+
+/**
+ * Defensive normalization for a session tracker's `repos` field. A fresh
+ * tracker written by create-work-session always holds an array, but an
+ * older hand-edited tracker or a tracker migrated from the previous layout
+ * might carry a scalar string (single repo) or null. Iterating a string
+ * with `for (const x of s)` yields characters — this helper prevents that.
+ */
+export function normalizeRepos(value) {
+  if (Array.isArray(value)) return value;
+  if (value === null || value === undefined || value === '') return [];
+  return [String(value)];
+}
+
+// === Session tracker helpers ===
+
+export function sessionFilePath(root, sessionName) {
+  const { workSessionsDir } = getWorkspacePaths(root);
+  return join(workSessionsDir, sessionName, 'workspace', 'session.md');
+}
+
+export function sessionFolderPath(root, sessionName) {
+  const { workSessionsDir } = getWorkspacePaths(root);
+  return join(workSessionsDir, sessionName);
+}
+
+export function sessionWorktreePath(root, sessionName) {
+  const { workSessionsDir } = getWorkspacePaths(root);
+  return join(workSessionsDir, sessionName, 'workspace');
+}
+
+/**
+ * Walk work-sessions/ and return one descriptor per session.md found.
+ * Each descriptor is { name, path, ...frontmatterFields }.
+ */
+export function getSessionTrackers(root) {
+  const { workSessionsDir } = getWorkspacePaths(root);
+  if (!existsSync(workSessionsDir)) return [];
+  const results = [];
+  for (const entry of readdirSync(workSessionsDir)) {
+    const sessionPath = join(workSessionsDir, entry, 'workspace', 'session.md');
+    if (!existsSync(sessionPath)) continue;
+    try {
+      const parsed = readSessionFile(sessionPath);
+      results.push({
+        ...parsed.fields,
+        _path: sessionPath,
+        _folder: join(workSessionsDir, entry),
+      });
+    } catch {
+      // Skip malformed session files rather than crashing hooks
+    }
+  }
+  return results;
+}
+
+/**
+ * Read a single session tracker by name. Returns the parsed fields object
+ * (not the full { fields, body, raw } shape). Returns null if missing.
+ */
+export function readSessionTracker(root, sessionName) {
+  const path = sessionFilePath(root, sessionName);
+  if (!existsSync(path)) return null;
+  try {
+    return readSessionFile(path).fields;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Update specific fields in an existing session tracker. Lossless for
+ * unchanged fields and the body. Creates the file if it does not exist.
+ */
+export function updateSessionTracker(root, sessionName, updates) {
+  const path = sessionFilePath(root, sessionName);
+  if (!existsSync(path)) {
+    // Create a minimal stub; callers will usually supply all fields
+    const folder = dirname(path);
+    if (!existsSync(folder)) mkdirSync(folder, { recursive: true });
+    writeSessionFile(path, updates, '\n# Work Session\n');
+    return;
+  }
+  const content = readFileSync(path, 'utf-8');
+  const next = updateSessionContent(content, updates);
+  if (next !== content) writeFileSync(path, next);
+}
+
+/**
+ * Create a brand-new session tracker file with the given fields and body.
+ * Creates the work-sessions/{name}/ folder if it does not exist.
+ */
+export function createSessionTracker(root, sessionName, fields, body) {
+  const path = sessionFilePath(root, sessionName);
+  const folder = dirname(path);
+  if (!existsSync(folder)) mkdirSync(folder, { recursive: true });
+  writeSessionFile(path, fields, body);
+}
+
+/**
+ * Delete the entire work-sessions/{name}/ folder. Used by /complete-work
+ * after the session is finalized and archived into release notes.
+ * Caller is responsible for any git bookkeeping (branch deletes, prunes).
+ */
+export function deleteSessionFolder(root, sessionName) {
+  const folder = sessionFolderPath(root, sessionName);
+  if (!existsSync(folder)) return;
+  rmSync(folder, { recursive: true, force: true });
+}
+
+// === Active session pointer (per-worktree) ===
+// A workspace worktree writes a tiny JSON pointer file at:
+//   {worktree}/.claude/.active-session.json
+// to tell hooks which session is currently in scope. Scoped to the
+// worktree itself — each worktree has its own pointer.
+
+export function activeSessionPointerPath(worktreeRoot) {
+  return join(worktreeRoot, '.claude', '.active-session.json');
+}
+
+export function getActiveSessionPointer(worktreeRoot) {
+  return readJSON(activeSessionPointerPath(worktreeRoot));
+}
+
+export function writeActiveSessionPointer(worktreeRoot, data) {
+  const path = activeSessionPointerPath(worktreeRoot);
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+}
+
+export function getMainRoot(root) {
+  const pointer = getActiveSessionPointer(root);
+  return pointer?.rootPath || root;
+}
+
+export function timeAgo(isoString) {
+  if (!isoString) return 'unknown';
+  const diff = Date.now() - new Date(isoString).getTime();
+  const mins = Math.floor(diff / 60000);
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}

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

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// Unit tests for _utils.mjs tracker path helpers.
+// Run: node .claude/hooks/_utils.test.mjs
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import {
+  sessionFilePath,
+  sessionWorktreePath,
+  sessionFolderPath,
+  getSessionTrackers,
+} from './_utils.mjs';
+
+let failed = 0;
+let passed = 0;
+
+function assertEq(actual, expected, msg) {
+  const a = JSON.stringify(actual);
+  const e = JSON.stringify(expected);
+  if (a === e) {
+    passed++;
+  } else {
+    failed++;
+    console.error(`  FAIL: ${msg}\n    expected: ${e}\n    actual:   ${a}`);
+  }
+}
+
+function fixture() {
+  const root = mkdtempSync(join(tmpdir(), 'utils-test-'));
+  writeFileSync(
+    join(root, 'workspace.json'),
+    JSON.stringify({
+      workspace: { workSessionsDir: 'work-sessions', scratchpadDir: 'workspace-scratchpad' },
+    })
+  );
+  mkdirSync(join(root, 'work-sessions', 'demo', 'workspace'), { recursive: true });
+  writeFileSync(
+    join(root, 'work-sessions', 'demo', 'workspace', 'session.md'),
+    '---\ntype: session-tracker\nname: demo\nstatus: active\n---\n\nbody\n'
+  );
+  return root;
+}
+
+// sessionFilePath points inside the worktree
+{
+  const root = fixture();
+  try {
+    assertEq(
+      sessionFilePath(root, 'demo'),
+      join(root, 'work-sessions', 'demo', 'workspace', 'session.md'),
+      'sessionFilePath resolves to in-worktree tracker'
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// sessionWorktreePath returns the workspace worktree root
+{
+  const root = fixture();
+  try {
+    assertEq(
+      sessionWorktreePath(root, 'demo'),
+      join(root, 'work-sessions', 'demo', 'workspace'),
+      'sessionWorktreePath returns worktree root'
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// sessionFolderPath still returns the session parent folder
+{
+  const root = fixture();
+  try {
+    assertEq(
+      sessionFolderPath(root, 'demo'),
+      join(root, 'work-sessions', 'demo'),
+      'sessionFolderPath unchanged'
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// getSessionTrackers walks the in-worktree path
+{
+  const root = fixture();
+  try {
+    const trackers = getSessionTrackers(root);
+    assertEq(trackers.length, 1, 'getSessionTrackers finds demo session');
+    assertEq(trackers[0].name, 'demo', 'tracker name parsed');
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+console.log(`Passed: ${passed}, Failed: ${failed}`);
+if (failed > 0) process.exit(1);

package/template/.claude/hooks/post-compact.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// PostCompact hook — remind user that earlier context was lost
+import { respond } from './_utils.mjs';
+
+respond(`Earlier context was compacted. Discussion details from before this point may be incomplete.
+
+If you had uncaptured decisions or progress, use /braindump or /handoff now while you still remember.`);

package/template/.claude/hooks/pre-compact.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// PreCompact hook — session-aware context capture nudge.
+import { existsSync, statSync } from 'fs';
+import {
+  getWorkspaceRoot,
+  respond,
+  getActiveSessionPointer,
+  getMainRoot,
+  sessionFilePath,
+  timeAgo,
+} from './_utils.mjs';
+
+const root = getWorkspaceRoot(import.meta.url);
+const pointer = getActiveSessionPointer(root);
+
+if (pointer) {
+  const mainRoot = getMainRoot(root);
+  const trackerPath = sessionFilePath(mainRoot, pointer.name);
+
+  if (existsSync(trackerPath)) {
+    const stat = statSync(trackerPath);
+    const minsAgo = Math.floor((Date.now() - stat.mtimeMs) / 60000);
+
+    if (minsAgo > 30) {
+      respond(`Context is about to be compacted. Your session tracker for "${pointer.name}" was last updated ${timeAgo(stat.mtime.toISOString())}.\n\nConsider /handoff to update the tracker before context is lost.`);
+    } else {
+      respond(`Context compacting. Session tracker for "${pointer.name}" is recent (updated ${minsAgo}m ago). Earlier conversation details may still be lost — use /handoff if needed.`);
+    }
+  } else {
+    respond(`Context is about to be compacted. No session tracker found for "${pointer.name}". Use /handoff to capture progress before context is lost.`);
+  }
+} else {
+  respond(`Context is about to be compacted — earlier conversation details will be lost.\n\nIf this session produced decisions or progress worth keeping:\n  /braindump [name] — capture discussion and reasoning\n  /handoff [name]   — capture workstream state and next steps\n\nFiles in shared-context/ will persist. Conversation details won't.`);
+}

package/template/.claude/hooks/repo-write-detection.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// PreToolUse hook — enforce workspace root write restrictions and detect
+// out-of-session repo writes.
+//
+// New layout paths:
+//   Workspace worktree: work-sessions/{name}/workspace/
+//   Project worktree:   work-sessions/{name}/workspace/repos/{repo}/
+//   Bare clone:         repos/{repo}/  (at workspace root)
+import { join, basename } from 'path';
+import {
+  getWorkspaceRoot,
+  readStdin,
+  respond,
+  getActiveSessionPointer,
+  readSessionTracker,
+  readJSON,
+  getWorkspacePaths,
+} from './_utils.mjs';
+
+const root = getWorkspaceRoot(import.meta.url);
+const input = await readStdin();
+const toolName = input.tool_name || '';
+
+if (!['Bash', 'Edit', 'Write'].includes(toolName)) {
+  respond();
+  process.exit(0);
+}
+
+const toolInput = input.tool_input || {};
+const paths = [toolInput.file_path, toolInput.command, toolInput.path]
+  .filter(Boolean)
+  .join(' ')
+  .replace(/\\/g, '/');
+
+// If we're in a workspace worktree, check for out-of-session repo writes
+const pointer = getActiveSessionPointer(root);
+if (pointer) {
+  const mainRoot = pointer.rootPath || root;
+  const config = readJSON(join(mainRoot, 'workspace.json'));
+  const tracker = readSessionTracker(mainRoot, pointer.name);
+
+  if (tracker && config?.repos) {
+    // Find references to repos inside work-sessions/{name}/workspace/repos/{repo}/
+    // and also the workspace-root repos/{repo}/ for direct writes.
+    const wtMatch = paths.match(/work-sessions\/[^/\s]+\/workspace\/repos\/([^/\s]+)/);
+    const cloneMatch = paths.match(/(?:^|\s|\/)repos\/([^/\s]+)/);
+    const targetRepo = wtMatch ? wtMatch[1] : (cloneMatch ? cloneMatch[1] : null);
+    if (targetRepo) {
+      const sessionRepos = tracker.repos || [];
+      if (config.repos[targetRepo] && !sessionRepos.includes(targetRepo)) {
+        respond(`You're about to write to ${targetRepo}, which isn't part of this session. Consider adding it first so changes land on the session branch.`);
+        process.exit(0);
+      }
+    }
+  }
+
+  respond();
+  process.exit(0);
+}
+
+// We're at the main workspace root — restrict writes
+
+const { scratchpadDir } = getWorkspacePaths(root);
+const scratchpadName = scratchpadDir.slice(root.length + 1); // "workspace-scratchpad"
+
+// Allow writes to the workspace scratchpad
+if (paths.includes(scratchpadName)) {
+  respond();
+  process.exit(0);
+}
+
+// Allow writes to local-only-* files
+const filePathArg = toolInput.file_path || '';
+if (basename(filePathArg).startsWith('local-only-')) {
+  respond();
+  process.exit(0);
+}
+
+// For Bash commands, check if the command targets allowed paths
+if (toolName === 'Bash') {
+  const cmd = toolInput.command || '';
+  if (/^\s*(git|ls|cat|head|tail|grep|rg|find|echo|pwd|cd|which|node\s+-c)\b/.test(cmd)) {
+    respond();
+    process.exit(0);
+  }
+  if (cmd.includes(scratchpadName) || cmd.includes('local-only-')) {
+    respond();
+    process.exit(0);
+  }
+  // Allow helper script invocations from the workspace root
+  if (/node\s+.*\.claude\/scripts\//.test(cmd)) {
+    respond();
+    process.exit(0);
+  }
+}
+
+// Check if this write targets repos/, shared-context/, work-sessions/, or template files
+const isRepoWrite = /(?:^|[\s/])repos\//.test(paths) || paths.includes('work-sessions/');
+const isContextWrite = paths.includes('shared-context/') && !basename(filePathArg).startsWith('local-only-');
+const isTemplateWrite = paths.includes('.claude/') && !paths.includes(scratchpadName);
+
+if (isRepoWrite || isContextWrite || isTemplateWrite) {
+  respond("You're on main. All work should happen in a workspace worktree. Run /start-work to create or resume a work session.");
+  process.exit(0);
+}
+
+respond();