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

package/template/.claude/skills/workspace-init/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: workspace-init
 description: First-time workspace initialization. Clones repos, installs template components, extracts team knowledge from documentation sources and Claude chat history, activates rules, configures user identity. Run once after scaffolding with --init.
+
+# scope example (remove # to activate path-scoped loading):
+# scope: repos/my-api/
 ---
 
 # Workspace Init
@@ -53,6 +56,8 @@ For each repo in `workspace.json`:
 - If confirmed: `git clone {remote} repos/{name}`
 - If exists: report "repos/{name} already present"
 
+While workspace.json is open, confirm the work lifecycle. `workspace.sessionModel` selects where `/start-work` routes new work: `"task"` (one tracker issue + one branch + one worktree per touched repo; recommended for new workspaces) or `"session"` (self-contained `work-sessions/{name}/` folders; the template default — keep it for teams already mid-flight on sessions). Ask: "Which lifecycle should new work use — task (recommended for a new workspace) or session (default)?" and write the answer to `workspace.sessionModel` only if it differs from the current value. Never flip an existing non-default value silently.
+
 ### Step 3: Identify documentation sources
 
 Ask the user:
@@ -117,6 +122,9 @@ Also install these top-level files from the payload:
 - **`.claude/settings.json`** — Merge payload settings into existing file. Preserve user-added settings, add missing entries.
 - **`.gitignore`** — Merge: add lines from payload not already present.
 - **`CLAUDE.md`** — Generate from `.workspace-update/CLAUDE.md.tmpl`, substituting `{{project-name}}` with the workspace name. If the existing CLAUDE.md has user-added content beyond the bootstrap template, preserve it.
+- **`CODEBASE.md` (optional)** — Ask: "Generate CODEBASE.md? This produces a lightweight file-tree map that helps Claude navigate the codebase without exhaustive exploration. [Y/n]". If yes: scaffold `CODEBASE.md` from `.workspace-update/CODEBASE.md.tmpl`, substitute `{{project-name}}`, then pre-populate `## Top-level layout` by listing the top-level entries of each `repos/{repo}/` directory using `fs.readdirSync` (Node.js, no network calls). If no: skip — `CODEBASE.md` can always be created manually later by copying and filling the template.
+
+**Per-repo CLAUDE.md stubs:** For each repo in `workspace.json`, check if `repos/{repo}/CLAUDE.md` exists. If not, ask "Scaffold a CLAUDE.md for {repo}? [Y/n]". If yes, write a blank stub from `.workspace-update/repo-claude.md.tmpl`, substituting `{{repo-name}}` with the repo name. The stub body is comment text only — no workspace-specific content — and its `## Commands` section is where you will add repo-specific test, lint, and build commands.
 
 **Commit:** `git commit -m "feat: install template components from payload"`
 
@@ -255,6 +263,29 @@ If you discovered candidate work items during earlier steps (bugs in braindumps,
 
 Do NOT batch-create issues automatically — the user should review and prune the list.
 
+### Step 12.5: Configure MCP servers
+
+MCP (Model Context Protocol) servers extend what Claude can do inside the workspace. The template ships with a Playwright MCP server entry in `.mcp.json` for browser automation and visual testing. Additional servers open up two particularly useful capabilities:
+
+- **LSP symbol navigation** — a Language Server Protocol server gives Claude go-to-definition, find-all-references, and call-graph queries without false positives from text search. The right server depends on your language stack:
+  - TypeScript / JavaScript: `typescript-language-server` (via `npx typescript-language-server --stdio`)
+  - Python: `pylsp` (via `pip install python-lsp-server`)
+  - Go, Rust, Java, and others: consult your language's LSP documentation.
+- **Internal tool access** — if your team has internal APIs, databases, or services, an MCP server can expose them as tools Claude can call directly. The shape of an `mcpServers` entry in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-lsp": {
+      "command": "npx",
+      "args": ["typescript-language-server", "--stdio"]
+    }
+  }
+}
+```
+
+**This step is guidance only.** The right LSP server depends on your language; the right internal-tool server depends on what your team builds. Configure `.mcp.json` after init when you know what you need — there is no pressure to choose now. The Playwright entry already present in `.mcp.json` satisfies the template's audit assertion; additional servers are additive.
+
 ### Step 13: Configure user identity
 
 Ask: "What name should be used for your user-scoped context? [{system-username}]"
@@ -418,3 +449,6 @@ This session is done. Start a fresh Claude Code session and run /start-work to b
 - Documentation sources are first-class — always ask, always confirm access, always report failures
 - Chat history scanning uses a manifest to survive auto-compaction
 - Existing worktrees are formalized with session markers, trackers, and linked chat history
+- **Launch point:** Launch `claude` from the workspace root. A worktree is a context boundary — `CLAUDE.md` discovery stops at its root and gitignored content is absent — so a chat started inside a project worktree (a session's `work-sessions/{name}/workspace/repos/{repo}/` or a task's `repos/{repo}/.claude/worktrees/{slug}/`) loads only that repo's own `CLAUDE.md`, without the workspace conventions or hooks. That is occasionally what you want for isolated, repo-only work; for normal work, stay at the root and reach worktrees by path.
+- **Skills are on-demand, not pre-loaded:** Skills are invoked explicitly by name (`/skill-name`) when needed; they are not loaded at session start. The `.skip` mechanism in `.claude/rules/` provides the analogous progressive-disclosure pattern for rules — a `.md.skip` file is present but inactive; rename it to `.md` to activate, rename it back to deactivate. Step 6 of this skill walks through the activation choices.
+- **`scope:` for path-scoped skills:** The `scope:` frontmatter field (shown as a commented-out example at the top of this file) restricts a skill so it activates only when the working directory is inside the declared path. Removing the `#` prefix from the example line turns this skill into a path-scoped skill — useful when you want a repo-specific skill available only from inside that repo's worktree.

package/template/.claude/skills/workspace-update/SKILL.md

@@ -119,6 +119,10 @@ git commit -m "chore: update workspace from template v{fromVersion} to v{toVersi
 
 Report: "Workspace updated to v{toVersion}. Restart Claude Code if rules or hooks changed."
 
+### Step 8: Session-model migration nudge
+
+After the update is applied, if the sessions directory (`workspace.workSessionsDir`, default `work-sessions/`) has entries and `workspace.sessionModel` is not `"task"`, append one line to the report: "This workspace still has {N} session(s) under the session model — `/migrate-sessions` can inventory and drain them and switch to the task model whenever you're ready." Suggest only; the operator decides whether and when.
+
 ## Notes
 
 - The CLI (`npx @ulysses-ai/create-workspace --upgrade`) stages the payload. This skill processes it.

package/template/.claudeignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.build/

package/template/CLAUDE.md.tmpl

@@ -8,12 +8,14 @@ This is a claude-workspace. All conventions are defined in .claude/rules/.
 - Each session is a self-contained folder at `work-sessions/{name}/` containing the worktree, nested project worktrees, and the session tracker
 - From root: only `local-only-*` and `workspace-scratchpad/` are writable
 - Team knowledge lives in `workspace-context/`
+- Run `/rename` to label this chat before `/clear` — keeps the chat findable in your CLI history after the context is wiped
 
 ## Workspace Config
 @workspace.json
 @local-only-template-freshness.md
 
 ## Team Knowledge
+@CODEBASE.md
 @workspace-context/canonical.md
 @workspace-context/index.md
 
@@ -24,11 +26,27 @@ This is a claude-workspace. All conventions are defined in .claude/rules/.
 - `/braindump [name]` — capture discussion/reasoning
 - `/aside [--quick] <thought>` — capture a drive-by idea without interrupting current work
 - `/pause-work` — suspend work, push, draft PR
-- `/complete-work` — finalize branch, release notes, real PR
+- `/complete-work` — finalize the work — rebase, PR, merge, close the issue
 - `/promote` — move personal memory to shared context
-- `/release [version]` — combine unreleased notes into versioned doc
+- `/release [version]` — cut a versioned release: bump, tag, forge release with generated notes
 - `/sync-work` — push branches without ceremony
 - `/workspace-update` — apply template updates (runs maintenance before/after)
 - `/setup-tracker` — wire this workspace to an issue tracker (GitHub Issues shipped; others pluggable)
 - `/maintenance [audit|cleanup]` — workspace health checks and cleanup
 - `/build-docs-site` — build a comprehensive Docusaurus documentation site for a project
+
+## Compact Instructions
+
+When auto-compacting context, preserve in the summary:
+- Decisions made in this session and their rationale
+- Constraints and conventions established or confirmed
+- Active task list state and the next concrete step
+- File paths touched and the nature of the change
+- Errors hit and what was tried
+
+Drop from the summary:
+- Verbose tool output already reflected in committed code
+- Exploratory reads that did not lead to a change
+- Conversational asides
+
+Files in `workspace-context/`, the session tracker (`session.md`) or chat drawer (`workspace-scratchpad/chats/{chat}/`), and any `design-*.md`/`plan-*.md` survive compaction — they're on disk. Re-read them on demand instead of trying to keep their contents in summary.

package/template/CODEBASE.md.tmpl

@@ -0,0 +1,13 @@
+# {{project-name}} Codebase Map
+
+## Top-level layout
+<!-- fill in -->
+
+## Key entry points
+<!-- fill in -->
+
+## Conventions
+<!-- fill in -->
+
+## External dependencies
+<!-- fill in -->

package/template/_gitignore

@@ -17,6 +17,10 @@ workspace-scratchpad/
 .claude/.active-session.json
 CLAUDE.local.md
 
+# Worktrees of the workspace repo itself — task worktrees (repo ".") and
+# Claude Code's native worktrees both live under .claude/worktrees/
+.claude/worktrees/
+
 # Local-only convention — machine-local state, any depth
 local-only-*
 
@@ -26,3 +30,8 @@ local-only-*
 # OS
 .DS_Store
 Thumbs.db
+
+# Per-user workspace-context indexes are generated per machine and read only
+# through CLAUDE.local.md, which is itself gitignored — no mechanism reads
+# another user's index. Regenerated by build-workspace-context.mjs on demand.
+workspace-context/team-member/*/index.md

package/template/repo-claude.md.tmpl

@@ -0,0 +1,10 @@
+# {{repo-name}}
+
+## Purpose
+<!-- fill in -->
+
+## Conventions
+<!-- fill in -->
+
+## Commands
+<!-- fill in: test, lint, build commands for this repo -->

package/template/workspace.json.tmpl

@@ -6,12 +6,14 @@
     "scratchpadDir": "workspace-scratchpad",
     "workSessionsDir": "work-sessions",
     "workspaceContextDir": "workspace-context",
-    "releaseNotesDir": "workspace-context/release-notes",
     "canonicalBudgetBytes": 40960,
-    "subagentContextMaxBytes": 10240,
+    "subagentContextMaxBytes": 32768,
+    "subagentInlineMaxBytes": 8192,
     "greeting": "Welcome back to {{project-name}}.",
     "releaseMode": "per-repo",
-    "tracker": null
+    "sessionModel": "session",
+    "tracker": null,
+    "forge": { "type": "github" }
   },
   "repos": {}
 }

package/template/.claude/hooks/worktree-create.mjs

@@ -1,53 +0,0 @@
-#!/usr/bin/env node
-// WorktreeCreate hook — scan for stale worktrees across project repos and
-// flag them. Project worktrees live inside work-sessions/{name}/workspace/repos/
-// in the new layout. The scan walks each project repo's worktree admin list
-// rather than a filesystem pattern, so it keeps working regardless of where
-// worktrees are physically located.
-import { readdirSync, existsSync } from 'fs';
-import { join, basename } from 'path';
-import { execSync } from 'child_process';
-import { getWorkspaceRoot, respond } from './_utils.mjs';
-
-const root = getWorkspaceRoot(import.meta.url);
-const reposDir = join(root, 'repos');
-const stale = [];
-
-if (!existsSync(reposDir)) {
-  respond();
-  process.exit(0);
-}
-
-for (const entry of readdirSync(reposDir)) {
-  const repoPath = join(reposDir, entry);
-  if (!existsSync(join(repoPath, '.git'))) continue;
-
-  let worktreeOutput;
-  try {
-    worktreeOutput = execSync('git worktree list', { cwd: repoPath, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
-  } catch { continue; }
-
-  for (const line of worktreeOutput.trim().split('\n')) {
-    const parts = line.trim().split(/\s+/);
-    const wtPath = parts[0];
-    if (!wtPath || wtPath === repoPath) continue;
-    if (!existsSync(wtPath)) continue;
-
-    const branchMatch = line.match(/\[(.+?)\]/);
-    const branch = branchMatch ? branchMatch[1] : 'unknown';
-
-    try {
-      const lastCommit = execSync('git log -1 --format=%ci', { cwd: wtPath, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
-      const daysAgo = Math.floor((Date.now() - new Date(lastCommit).getTime()) / 86400000);
-      if (daysAgo > 3) {
-        stale.push(`- ${basename(wtPath)} (${branch}): no commits in ${daysAgo} days`);
-      }
-    } catch {}
-  }
-}
-
-if (stale.length > 0) {
-  respond(`Stale worktrees found:\n${stale.join('\n')}\n\nConsider cleaning up with: git worktree remove {path}`);
-} else {
-  respond();
-}