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

package/template/.claude/skills/complete-work/SKILL.md

@@ -21,6 +21,7 @@ Determine paths:
 - Workspace worktree: `work-sessions/{session-name}/workspace/`
 - Project worktrees: `work-sessions/{session-name}/workspace/repos/{repo}/` for each repo in the tracker's `repos:` list
 - Read each repo's default branch from workspace.json (`repos.{repo}.branch`)
+- **Release-notes base directory.** Read `workspace.releaseNotesDir` from `workspace.json` (default `workspace-context/release-notes` if the field is absent). Throughout this skill `{releaseNotesDir}` refers to that resolved value; every branch-note path is `{releaseNotesDir}/unreleased/{repo}/…`. Never use a bare `release-notes/`.
 
 ### Step 2: Rebase project repos
 
@@ -86,10 +87,10 @@ For each repo in the tracker's `repos:` list that has commits beyond the base br
 cd work-sessions/{session-name}/workspace/repos/{repo}
 COMMIT_ID=$(git rev-parse --short HEAD)
 cd ../..  # back to the workspace worktree
-mkdir -p release-notes/unreleased/{repo-name}
+mkdir -p {releaseNotesDir}/unreleased/{repo-name}
 ```
 
-**File 1: `release-notes/unreleased/{repo-name}/branch-release-notes-{COMMIT_ID}.md`** (relative to the workspace worktree)
+**File 1: `{releaseNotesDir}/unreleased/{repo-name}/branch-release-notes-{COMMIT_ID}.md`** (relative to the workspace worktree)
 ```markdown
 ---
 branch: {branch}
@@ -105,7 +106,7 @@ date: {YYYY-MM-DD}
 Written from scratch per coherent-revisions rule.}
 ```
 
-**File 2: `release-notes/unreleased/{repo-name}/branch-release-questions-{COMMIT_ID}.md`**
+**File 2: `{releaseNotesDir}/unreleased/{repo-name}/branch-release-questions-{COMMIT_ID}.md`**
 ```markdown
 ---
 branch: {branch}
@@ -124,7 +125,7 @@ The `repo:` frontmatter field is what `/release` uses to know which project repo
 After all repos are processed, commit once on the workspace branch:
 ```bash
 cd work-sessions/{session-name}/workspace
-git add release-notes/unreleased/
+git add {releaseNotesDir}/unreleased/
 git commit -m "docs: add release notes for {branch}"
 ```
 
@@ -217,16 +218,27 @@ The push shape is the same as 9a — what differs is the merge mechanics in Step
 
 #### Step 10a: GitHub remotes — create PRs, unified summary, merge
 
-Create one PR per project repo plus one workspace PR:
+Create one PR per project repo plus one workspace PR. PR operations go through the forge adapter (`.claude/scripts/forges/interface.mjs`), not `gh` directly — see `.claude/rules/forge-operations.md` for the contract. The adapter resolves the target repo from `workspace.forge.repo` or the local git remote.
 
-```bash
-# For each repo in the tracker's repos with a GitHub remote:
-cd work-sessions/{session-name}/workspace/repos/{repo}
-gh pr create --title "{type}: {description}" --body "..."
+```javascript
+import { createForge } from './.claude/scripts/forges/interface.mjs';
+import { readFileSync } from 'node:fs';
 
-# Workspace PR — from the workspace worktree
-cd work-sessions/{session-name}/workspace
-gh pr create --title "context: {session-name} work session" --body "..."
+const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
+const forge = createForge(ws.workspace?.forge);
+
+// For each repo in the tracker's repos with a GitHub remote, from
+// work-sessions/{session-name}/workspace/repos/{repo}:
+const projectPr = await forge.prCreate({
+  title: `${type}: ${description}`,
+  body: prBody,  // synthesized release notes + verification section
+});
+
+// Workspace PR — from the workspace worktree:
+const workspacePr = await forge.prCreate({
+  title: `context: ${sessionName} work session`,
+  body: workspacePrBody,
+});
 ```
 
 Present unified summary:
@@ -253,15 +265,21 @@ WORKSPACE: {workspace-name}
 Merge all? [Y/n]
 ```
 
-If yes — merge all PRs atomically:
-```bash
-# For each project PR:
-gh pr merge {pr-number} --merge
+If yes — merge all PRs atomically through the forge adapter:
+
+```javascript
+// For each project PR returned from Step 10a's prCreate calls:
+await forge.prMerge({ id: projectPr.id, strategy: 'squash', deleteBranch: true });
+
+// Workspace PR:
+await forge.prMerge({ id: workspacePr.id, strategy: 'squash', deleteBranch: true });
+```
 
-# Workspace PR:
-gh pr merge {workspace-pr-number} --merge
+`strategy: 'squash'` matches the workspace convention from `post-release-discipline` (`create-ulysses-workspace` requires linear history, so squash is the only strategy that merges cleanly; squash also lifts the PR body into the commit message). `deleteBranch: true` cleans the remote feature branch on success.
 
-# Pull all repos to their default branches
+Then pull all repos to their default branches (still plain git):
+
+```bash
 # For each repo in the tracker's repos:
 cd repos/{repo} && git pull origin {repo-branch}
 cd {main-workspace-root} && git pull origin main
@@ -273,7 +291,7 @@ The next three sub-substeps run only when the session branch starts with `releas
 
 Derive the version tag from the branch name by stripping the `release/` prefix (so `release/v0.15.0-beta.0` yields `v0.15.0-beta.0`). For each project repo whose `package.json` declares a `version` field, verify that version matches the derived tag. The workspace repo is **never** tagged — only project repos with publishable `package.json` files get tagged, since the tag triggers `.github/workflows/publish.yml` in that project repo. If a project repo's `package.json` version doesn't match the release tag, skip that repo with a warning rather than failing the whole completion flow — the mismatch usually means `/release` was run against a different version than the branch name suggests, and the user needs to investigate before publishing.
 
-Before tagging, preflight against origin: if `v{version}` already exists remotely, surface the conflict to the user with three explicit recovery options — **Reuse** (skip to 10a.2 if the existing tag points at the right commit), **Replace** (`git push origin --delete v{version}` then re-run 10a.1), or **Investigate** (`gh release view v{version}` to see what shipped). Do **not** silently force-push the tag; an existing tag means a published artifact, and overwriting it without confirmation can corrupt the npm registry's view of the release history.
+Before tagging, preflight against origin: if `v{version}` already exists remotely, surface the conflict to the user with three explicit recovery options — **Reuse** (skip to 10a.2 if the existing tag points at the right commit), **Replace** (`git push origin --delete v{version}` then re-run 10a.1), or **Investigate** (`forge.releaseView({ tag: 'v{version}', repo: '{org}/{repo}' })` — or `gh release view v{version}` as a manual fallback — to see what shipped). Do **not** silently force-push the tag; an existing tag means a published artifact, and overwriting it without confirmation can corrupt the npm registry's view of the release history.
 
 If the tag is absent on origin, tag the merge commit (HEAD on `{default-branch}` after the prior `git pull origin {default-branch}`) and push the tag. The tag push triggers `.github/workflows/publish.yml`.
 
@@ -304,7 +322,8 @@ for repo in {project-repos-with-package-json}; do
     # Tag exists. Surface to user with three options:
     # 1. Reuse — skip to 10a.2 if the existing tag points at the right commit.
     # 2. Replace — `git push origin --delete $version_tag` then re-run 10a.1.
-    # 3. Investigate — `gh release view $version_tag` to see what shipped.
+    # 3. Investigate — call forge.releaseView({ tag: '$version_tag' }) — or
+    #    `gh release view $version_tag` as a manual fallback — to see what shipped.
     # Do NOT silently force-push.
     echo "Tag $version_tag already exists on origin. Aborting with recovery options."
     return 1
@@ -318,27 +337,39 @@ done
 
 **Step 10a.2: Watch the publish workflow (release sessions only)**
 
-For each project repo tagged in 10a.1, find and follow the `publish.yml` workflow run on GitHub. The workflow takes a moment to register against the new tag — poll `gh run list` up to 5 times with a 3-second backoff before giving up. Once the run is found, attach with `gh run watch` so the maintainer sees progress live alongside the unified summary. Append `|| true` to the watch command so a workflow failure does **not** abort the rest of `/complete-work`: the maintainer still needs to see the unified summary, including the failure URL, to decide whether to rerun, redo the release, or roll the tag back. If no run registers within the retry window, log a warning with the manual investigation command and continue.
+For each project repo tagged in 10a.1, find and follow the `publish.yml` workflow run on GitHub. The workflow takes a moment to register against the new tag — poll up to 5 times with a 3-second backoff before giving up. Once the run is found, attach with `workflowRunWatch` so the maintainer sees progress live alongside the unified summary. The adapter's `exitStatus: true` makes the underlying `gh run watch --exit-status` exit non-zero on workflow failure; the adapter returns the exit code via `res.exitCode` instead of throwing, so a failure does **not** abort the rest of `/complete-work` — the maintainer still needs to see the unified summary, including the failure URL, to decide whether to rerun, redo the release, or roll the tag back. If no run registers within the retry window, log a warning with the manual investigation command and continue.
 
-```bash
-# Retry up to 5 times with 3-second backoff — the run takes a moment to register.
-for i in 1 2 3 4 5; do
-  run_id=$(gh run list \
-    --repo {org}/{repo} \
-    --workflow publish.yml \
-    --branch "$version_tag" \
-    --limit 1 \
-    --json databaseId \
-    --jq '.[0].databaseId')
-  if [ -n "$run_id" ]; then break; fi
-  sleep 3
-done
+```javascript
+import { createForge } from './.claude/scripts/forges/interface.mjs';
+import { readFileSync } from 'node:fs';
 
-if [ -z "$run_id" ]; then
-  echo "Warning: no publish workflow run found for $version_tag after 15s. Investigate via 'gh run list'."
-else
-  gh run watch "$run_id" --exit-status --repo {org}/{repo} || true
-fi
+const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
+const forge = createForge(ws.workspace?.forge);
+
+// Retry up to 5 times with 3-second backoff — the run takes a moment to register.
+let run = null;
+for (let i = 0; i < 5; i++) {
+  run = await forge.workflowRunFind({
+    workflow: 'publish.yml',
+    branch: versionTag,        // e.g. 'v0.15.0-beta.0'
+    repo: `${org}/${repo}`,
+    limit: 1,
+  });
+  if (run) break;
+  await new Promise(r => setTimeout(r, 3000));
+}
+
+if (!run) {
+  console.warn(`Warning: no publish workflow run found for ${versionTag} after 15s. Investigate via 'gh run list --workflow publish.yml --branch ${versionTag}'.`);
+} else {
+  const result = await forge.workflowRunWatch({
+    runId: run.runId,
+    repo: `${org}/${repo}`,
+    exitStatus: true,
+  });
+  // result.exitCode === 0 on success; non-zero on workflow failure (NOT thrown).
+  // result.exitCode and run.url feed into the unified summary in Step 10a.3.
+}
 ```
 
 **Step 10a.3: Update the unified summary (release sessions only)**
@@ -353,7 +384,7 @@ PUBLISH ({repo}):
   Published: {dist-tag}@{version} on npm
 ```
 
-Pull `Status` from the `gh run watch` exit code (success when the watch returned 0, failure otherwise). Pull `Published: {dist-tag}@{version}` from the workflow's published-package output if available; if the workflow failed before publishing, omit the `Published:` line and rely on `Status: failure` plus the workflow URL to point the maintainer at the failure.
+Pull `Status` from the watch result's `exitCode` (success when `result.exitCode === 0`, failure otherwise). Pull `Workflow` from `run.url` captured in 10a.2. Pull `Published: {dist-tag}@{version}` from the workflow's published-package output if available; if the workflow failed before publishing, omit the `Published:` line and rely on `Status: failure` plus the workflow URL to point the maintainer at the failure.
 
 #### Step 10b: Local / bare / other remotes — local merge flow
 
@@ -459,7 +490,7 @@ Ask: "These changes weren't part of a formal work session. What do you want to d
 - **Revert** — undo the changes (with confirmation)
 
 ## Notes
-- Branch release notes live in the WORKSPACE repo at `release-notes/unreleased/{repo-name}/` — never in project repos. Project repos only ever see code commits and (at release time) `CHANGELOG.md` entries written by `/release`.
+- Branch release notes live in the WORKSPACE repo at `{releaseNotesDir}/unreleased/{repo-name}/` (resolved from `workspace.json` → `workspace.releaseNotesDir`, default `workspace-context/release-notes`) — never in project repos. Project repos only ever see code commits and (at release time) `CHANGELOG.md` entries written by `/release`.
 - The session tracker's body is the primary source for release note synthesis — it captures the full session history alongside specs and plans
 - All repos get PRed and merged together — one approval for all
 - Version bumps happen in `/release`, not `/complete-work` — this avoids version drift when multiple feature branches land between releases

package/template/.claude/skills/maintenance/SKILL.md

@@ -108,22 +108,36 @@ Report one of:
 
 Active recommendations. Flags problems and suggests fixes, but asks before acting.
 
-### 7. Stale context
+### 7. Component age check
+
+Scan the following file sets for a YAML frontmatter `updated:` field:
+- `.claude/rules/*.md` (active rules only — `.md.skip` files are included too, since the rule content can still drift)
+- `.claude/skills/*/SKILL.md`
+- `.claude/agents/*.md`
+- `.claude/hooks/*.mjs`
+
+For each file that has an `updated:` field, compute the age in days from today. If the age exceeds 180 days, flag the file as a stale component candidate. Print the file name, the `updated:` date, and the age in days so the contributor knows how far the file has drifted.
+
+Files without an `updated:` field are skipped — the check is opt-in and activates the discipline incrementally as contributors add frontmatter to the files they own. To start tracking a file, add `updated: <today>` to its frontmatter; the check will surface it if it goes stale.
+
+When stale candidates are found, surface them as warnings in the output format and link to `config-review.md.skip` (in `.claude/rules/`) as the opt-in rule that documents the review cadence and rationale.
+
+### 8. Stale context
 - Ephemeral files not updated in 7+ days — suggest resolve, update, or archive
 - `work-sessions/{name}/` folders whose worktrees are gone — suggest cleanup
 - Session trackers whose branches have been merged — suggest `/complete-work` post-flight cleanup
 - Braindumps that overlap significantly — suggest merging (e.g., "workspace-branching.md and persistent-work-sessions.md cover the same topic")
 - Handoffs referencing deleted branches — suggest resolve or remove
 
-### 8. Context reconciliation
+### 9. Context reconciliation
 - Read recent workspace-context writes (last session or last N files by updated date)
 - For each, scan other workspace-context files for references that are now stale
 - Surface: "{file} says X but {newer-file} now says Y. Update {file}?"
 - This is the capture-time cross-check, run retroactively instead of inline
 
-### 9. Canonical budget triage
+### 10. Canonical budget triage
 
-This step runs only when the post-regen `--check` from step 8 still reports `selectionStatus: 'over-budget'`. If the regular regen pass cleared the budget — or if `--check` was already `ok`, `trimmed`, or `stubbed` after step 8 — skip this step entirely.
+This step runs only when the post-regen `--check` from step 9 still reports `selectionStatus: 'over-budget'`. If the regular regen pass cleared the budget — or if `--check` was already `ok`, `trimmed`, or `stubbed` after step 9 — skip this step entirely.
 
 The rest of cleanup is suggestion-list-with-confirmation: surface a candidate, ask before applying, move on. Triage is the one meaningfully more interactive surface in `/maintenance`. It runs as a small REPL: present the budget state and a triage menu, take one action, re-run `--check`, present the menu again with the new state. No suggestion is auto-applied; every action is the user's choice.
 
@@ -168,7 +182,19 @@ For each chosen action:
 
 Trim markers and demotions only matter for `priority: reference` files — `<!-- canonical:trim -->` spans on a `priority: critical` file are inert until the file is demoted. The triage flow never auto-decides which file to demote or which section to wrap; it surfaces the data, presents options, and waits.
 
-### 10. Health metrics
+### 11. Forge configuration
+
+Read `workspace.json`. If `workspace.tracker?.type === 'github-issues'` and `workspace.forge` is unset, emit a notice (not an error):
+
+```
+ℹ workspace.json has tracker.type='github-issues' but no workspace.forge field.
+  Skills default to GitHub forge operations; add `"forge": {"type": "github"}`
+  to workspace.json to make the choice explicit. See .claude/rules/forge-operations.md.
+```
+
+This is migration guidance for workspaces created before the `forge` field landed — the field is back-compat with a sensible default, so the unset case is not a bug, just an opportunity to make the implicit explicit. If `workspace.forge.type` is set to a value with no adapter at `.claude/scripts/forges/{type}.mjs`, that IS an error and goes in the Issues section.
+
+### 12. Health metrics
 - Canonical budget — read from the same `--check` invocation as step 5. Reported as `current / budget` bytes with the selection status (e.g., `full`, `2 reference files trimmed`). Over-budget cases are deferred to the cleanup triage flow rather than re-reported here.
 - Number of ephemeral files — flag if accumulating without resolution
 - Session log stats (if `workspace-scratchpad/session-log.jsonl` exists):
@@ -215,7 +241,7 @@ OK (5):
 5. Check git state (worktrees, branches, remotes)
 6. Run `node .claude/scripts/build-workspace-context.mjs --check --root .` — capture status. Exit `0` = clean and within budget, `1` = artifact missing or stale, `2` = artifacts current but canonical body over budget. The `canonical` block in the JSON output drives both the audit budget line and the cleanup triage decision.
 7. Read session-log.jsonl if it exists
-8. If cleanup mode: regenerate the workspace-context auto-files if stale (index.md, canonical.md, per-user team-member indexes); compare files pairwise for overlap; scan for stale cross-references. If post-regen `--check` reports `over-budget`, enter the canonical-budget triage flow described in cleanup step 9.
+8. If cleanup mode: regenerate the workspace-context auto-files if stale (index.md, canonical.md, per-user team-member indexes); compare files pairwise for overlap; scan for stale cross-references. If post-regen `--check` reports `over-budget`, enter the canonical-budget triage flow described in cleanup step 10.
 9. Compile and present findings grouped by severity
 
 ## Notes

package/template/.claude/skills/pause-work/SKILL.md

@@ -95,16 +95,33 @@ git push -u origin {branch}
 
 ### Step 7: Create draft PRs
 
-```bash
-# For each repo in the tracker's repos:
-cd work-sessions/{session-name}/workspace/repos/{repo}
-gh pr create --draft --title "WIP: {description}" --body "Work in progress. Session paused."
+PR creation goes through the forge adapter (`.claude/scripts/forges/interface.mjs`), not directly through `gh` — see `.claude/rules/forge-operations.md` for the contract and why. The adapter resolves the target repo from `workspace.forge.repo` or the local git remote.
 
-# Workspace repo — from the workspace worktree
-gh pr create --draft --title "context: {session-name} (paused)" --body "Workspace context for paused session."
+```javascript
+import { createForge } from './.claude/scripts/forges/interface.mjs';
+import { readFileSync } from 'node:fs';
+
+const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
+const forge = createForge(ws.workspace?.forge);
+
+// For each repo in the tracker's repos, from work-sessions/{session-name}/workspace/repos/{repo}:
+const projectPr = await forge.prCreate({
+  title: `WIP: ${description}`,
+  body: 'Work in progress. Session paused.',
+  draft: true,
+});
+console.log(projectPr.url);
+
+// Workspace repo — from the workspace worktree:
+const workspacePr = await forge.prCreate({
+  title: `context: ${sessionName} (paused)`,
+  body: 'Workspace context for paused session.',
+  draft: true,
+});
+console.log(workspacePr.url);
 ```
 
-If PRs already exist, update them to draft status if needed.
+If PRs already exist, update them to draft status if needed (use `gh pr ready --undo` directly until a `forge.prSetDraft` method lands — that's tracked as a future forge adapter extension, not blocking here).
 
 ### Step 8: Confirm
 

package/template/.claude/skills/release/SKILL.md

@@ -27,10 +27,12 @@ Check `workspace.json` for `releaseMode`:
 - **workspace**: process all repos together
 - **ask**: "Process all repos together or individually?"
 
+**Release-notes base directory.** Read `workspace.releaseNotesDir` from `workspace.json` (default `workspace-context/release-notes` if the field is absent). Throughout this skill `{releaseNotesDir}` refers to that resolved value; every branch-note path is `{releaseNotesDir}/unreleased/{repo}/…`. Never use a bare `release-notes/`.
+
 **Step 2: Read unreleased notes**
 Branch notes live in the **workspace** repo, written there by `/complete-work`. For each target repo, list the workspace's unreleased subdirectory for that project:
 ```bash
-ls release-notes/unreleased/{repo}/
+ls {releaseNotesDir}/unreleased/{repo}/
 ```
 Read all `branch-release-notes-*.md` and `branch-release-questions-*.md` files.
 
@@ -71,9 +73,9 @@ The entry stays short. If a change needs more detail, reference the repo's docs
 
 **Step 6: Delete consumed branch notes from the workspace**
 ```bash
-rm release-notes/unreleased/{repo}/branch-release-*
+rm {releaseNotesDir}/unreleased/{repo}/branch-release-*
 # If the directory is now empty, remove it too:
-rmdir release-notes/unreleased/{repo} 2>/dev/null || true
+rmdir {releaseNotesDir}/unreleased/{repo} 2>/dev/null || true
 ```
 The branch notes were an intermediate capture; their content is now in the CHANGELOG entry and their raw form in git history. They do not survive into the project repo.
 
@@ -98,7 +100,7 @@ Skip this step if the repo has no package.json or no version field.
 **Step 7c: Commit the consumed-notes deletion in the workspace**
 ```bash
 # From the workspace root
-git add release-notes/unreleased/
+git add {releaseNotesDir}/unreleased/
 git commit -m "release: consume {repo} branch notes for v{version}"
 ```
 Workspace and project repos have separate commits — they are separate git histories.
@@ -138,7 +140,7 @@ Process ephemeral workspace-context entries:
 ## Notes
 
 - Release entries live in `CHANGELOG.md` at the project repo root — one file, one concise entry per version. No `release-notes/v*.md`, no `release-notes/archive/`.
-- Branch notes live in the WORKSPACE at `release-notes/unreleased/{repo}/`. `/complete-work` writes them; `/release` consumes and deletes them. They never reach project repos.
+- Branch notes live in the WORKSPACE at `{releaseNotesDir}/unreleased/{repo}/` (resolved from `workspace.json` → `workspace.releaseNotesDir`, default `workspace-context/release-notes`). `/complete-work` writes them; `/release` consumes and deletes them. They never reach project repos.
 - Versions are bumped here, not in `/complete-work`. This keeps the version semantics aligned with what actually shipped (accumulated changes since last release).
 - The public repo stays lean. Detailed per-branch retrospection exists in workspace git history (the consumed-notes commit) but is not surfaced as standalone files in either repo.
 - Context synthesis happens in the WORKSPACE repo — Step 7c (consumed-notes) and Step 9 (workspace-context synthesis) are separate workspace commits.

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();
-}