@ulysses-ai/create-workspace 0.16.0-beta.1 → 0.17.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
@@ -117,6 +120,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 +261,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 +447,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
+- **Subdirectory launch:** Once initialized, `claude` can be launched from `work-sessions/{name}/workspace/repos/{repo}/` instead of the workspace root. Claude walks up the filesystem loading every `CLAUDE.md` it finds, so starting from inside a project worktree loads both the per-repo conventions and the workspace conventions automatically. This is useful for repo-focused tasks — no configuration change needed, just a different launch point.
+- **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/.claudeignore

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

package/template/CLAUDE.md.tmpl

@@ -14,6 +14,7 @@ This is a claude-workspace. All conventions are defined in .claude/rules/.
 @local-only-template-freshness.md
 
 ## Team Knowledge
+@CODEBASE.md
 @workspace-context/canonical.md
 @workspace-context/index.md
 

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/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

@@ -11,7 +11,8 @@
     "subagentContextMaxBytes": 10240,
     "greeting": "Welcome back to {{project-name}}.",
     "releaseMode": "per-repo",
-    "tracker": null
+    "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();
-}