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

package/README.md

@@ -89,8 +89,8 @@ Four things, in the order you'll touch them:
 A scaffolded workspace with:
 
 - **14 skills** covering the workflow lifecycle, releases, handoffs, and maintenance
-- **8 active rules** + **8 optional `.skip` rules** for behaviors you can opt into
-- **10 hooks** for SessionStart, SubagentStart, PreCompact, WorktreeCreate, and the rest of the small set the conventions rely on
+- **9 active rules** + **9 optional `.skip` rules** for behaviors you can opt into
+- **9 hooks** for SessionStart, SubagentStart, PreCompact, and the rest of the small set the conventions rely on
 - A **`shared-context/`** memory system with three visibility levels: locked (team truths), root (team-visible ephemerals), user-scoped (personal)
 - Conventions for **multi-repo work sessions** with isolated git worktrees, parallelizable from separate terminals
 

package/lib/init.mjs

@@ -105,6 +105,25 @@ export async function initWorkspace(targetDir) {
     }
   }
 
+  // Set up .claudeignore
+  const payloadClaudeignore = join(payloadDir, '.claudeignore');
+  const claudeignorePath = join(targetDir, '.claudeignore');
+  if (existsSync(payloadClaudeignore)) {
+    if (existsSync(claudeignorePath)) {
+      const existing = readFileSync(claudeignorePath, 'utf-8');
+      const template = readFileSync(payloadClaudeignore, 'utf-8');
+      const existingLines = new Set(existing.split('\n').map(l => l.trim()));
+      const newLines = template.split('\n').filter(l => l.trim() && !existingLines.has(l.trim()));
+      if (newLines.length > 0) {
+        writeFileSync(claudeignorePath, existing.trimEnd() + '\n\n# From workspace template\n' + newLines.join('\n') + '\n');
+        console.log('  Merged template entries into .claudeignore');
+      }
+    } else {
+      cpSync(payloadClaudeignore, claudeignorePath);
+      console.log('  Created .claudeignore');
+    }
+  }
+
   console.log(`
   Workspace initialized (v${toVersion}).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulysses-ai/create-workspace",
-  "version": "0.16.0-beta.0",
+  "version": "0.17.0-beta.0",
   "description": "A workspace convention for Claude Code: sessions, handoffs, and shared context as files in git",
   "keywords": [
     "claude",

package/template/.claude/hooks/session-end.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 // SessionEnd hook — mark this chat's `ended` timestamp in the session
-// tracker and append a small safety-net note to the session.md body.
-import { appendFileSync, mkdirSync, existsSync } from 'fs';
+// tracker, append a small safety-net note to the session.md body, and
+// write a disk-durable reflection record if the session.md ## Progress
+// section contains heuristic correction-pattern sentences.
+import { appendFileSync, mkdirSync, existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { execSync } from 'child_process';
 import {
@@ -71,6 +73,70 @@ if (pointer && sessionId) {
       } catch {
         // Non-fatal
       }
+
+      // Disk-durable reflection sub-step (BP-10).
+      // Read the ## Progress section of session.md (last 2000 chars max),
+      // scan for heuristic correction-pattern sentences, and write any
+      // candidates to workspace-scratchpad/session-reflect.json. The file
+      // is gitignored (workspace-scratchpad/ is in _gitignore). We do NOT
+      // emit additionalContext for this — per the canonical known limitation,
+      // additionalContext does not always reach Claude. Disk is the primary
+      // durable output.
+      try {
+        const sessionContent = readFileSync(trackerPath, 'utf8');
+
+        // Extract ## Progress section — find the section and take last 2000 chars.
+        const progressMatch = sessionContent.match(/^## Progress\s*\n([\s\S]*?)(?=\n^##|\s*$)/m);
+        const progressText = progressMatch
+          ? progressMatch[1].slice(-2000)
+          : sessionContent.slice(-2000);
+
+        // Split into sentences on '. ' or '.\n' boundaries.
+        const sentences = progressText
+          .split(/(?<=\.)\s+|\n/)
+          .map(s => s.trim())
+          .filter(s => s.length > 10);
+
+        // Correction-pattern keywords — case-insensitive.
+        const correctionPatterns = [
+          /actually/i,
+          /instead of/i,
+          /the right way is/i,
+          /i was wrong/i,
+          /correction:/i,
+        ];
+
+        const candidates = sentences
+          .filter(sentence => correctionPatterns.some(re => re.test(sentence)))
+          .map(text => ({ text, source: '## Progress' }));
+
+        if (candidates.length > 0) {
+          if (!existsSync(scratchpadDir)) mkdirSync(scratchpadDir, { recursive: true });
+          const reflectPath = join(scratchpadDir, 'session-reflect.json');
+
+          // Read existing records to append (create-or-append pattern).
+          let records = [];
+          if (existsSync(reflectPath)) {
+            try {
+              records = JSON.parse(readFileSync(reflectPath, 'utf8'));
+              if (!Array.isArray(records)) records = [records];
+            } catch {
+              records = [];
+            }
+          }
+
+          records.push({
+            sessionId: sessionId || `ts-${Date.now()}`,
+            date: new Date().toISOString(),
+            workSession: pointer.name,
+            candidates,
+          });
+
+          writeFileSync(reflectPath, JSON.stringify(records, null, 2), 'utf8');
+        }
+      } catch {
+        // Non-fatal — reflection is best-effort.
+      }
     }
   }
 }

package/template/.claude/rules/config-review.md.skip

@@ -0,0 +1,29 @@
+# Config Review Cadence
+
+Opt-in reminder to review `.claude` component files on a regular schedule. Activate by removing the `.skip` extension (`mv config-review.md.skip config-review.md`). Add it back to deactivate.
+
+## When to review
+
+Review the files in `.claude/rules/`, `.claude/skills/*/SKILL.md`, `.claude/agents/*.md`, and `.claude/hooks/*.mjs` after each major model release and at least every 180 days. Claude Code evolves quickly — conventions that matched platform behavior six months ago may no longer be accurate, optimal, or even meaningful.
+
+The 180-day threshold is not arbitrary: it corresponds to roughly two major Claude model generations. Conventions written for an older model generation can silently mis-steer the newer one without anyone noticing, because the file still runs without error.
+
+## Connection to /maintenance
+
+The `/maintenance` skill's **Component age check** (step 7 in the Cleanup section) surfaces which files have drifted past 180 days by reading their frontmatter `updated:` field. Files without an `updated:` field are skipped — the check is incremental and only flags files that have opted in by carrying the field.
+
+When `/maintenance` reports stale components, the recommended action is to open each flagged file, read it against the current Claude Code documentation and platform behavior, update the content where needed, and bump `updated:` to today.
+
+## Why this ships as .skip
+
+Review cadence is org-specific. A solo maintainer doing active weekly development may want a shorter cadence; a team with a slower release cycle may need a longer one; some workspaces may defer review entirely to a dedicated maintenance session. Making this rule mandatory by default would encode one team's preference as a universal constraint — exactly the failure mode described in `product-bias-risk.md`.
+
+Activate the rule only if your team wants the reminder to appear in every session. If 180 days is wrong for your cadence, edit the threshold in the rule body after activating it.
+
+## Activating
+
+```
+mv .claude/rules/config-review.md.skip .claude/rules/config-review.md
+```
+
+Once active, this reminder loads into every session context. To deactivate, rename it back.

package/template/.claude/rules/forge-operations.md

@@ -0,0 +1,107 @@
+Activate this rule if the workspace creates PRs, watches CI runs, or interacts with releases from skills. Sibling to `work-item-tracking.md` (which covers issues); together they cover everything a workspace needs to do against a code-hosting forge.
+
+# Forge Operations
+
+When a workspace has a forge configured, all pull-request, release, and workflow-run operations from skills and scripts go through the adapter at `.claude/scripts/forges/{type}.mjs`. Skills never call `gh` (or `glab`, or any forge CLI) inline.
+
+## Why the abstraction
+
+- **Swap by config.** Moving from GitHub to GitLab is a `workspace.json` field change plus an adapter file — not a sweep across six skill files.
+- **Testable.** The adapter takes an injectable `spawnFn`; unit tests mock subprocess calls instead of running them.
+- **One vocabulary.** Skills reason about `forge.prCreate`, `forge.prMerge`, `forge.workflowRunFind`, `forge.workflowRunWatch`, `forge.releaseView` regardless of backend. Failure modes share typed errors (`PrNotFound`, `MergeRejected`, `WorkflowNotFound`, `ReleaseNotFound`) instead of every callsite parsing stderr.
+
+## Configuration
+
+`workspace.json` → `workspace.forge`:
+
+```json
+{
+  "workspace": {
+    "forge": {
+      "type": "github"
+    }
+  }
+}
+```
+
+- `type` — identifies the adapter module at `.claude/scripts/forges/{type}.mjs`. `github` is the default and the only fully-implemented adapter today. `gitlab.mjs` ships as a stub that throws `NOT_IMPLEMENTED` with a contribution pointer.
+- `repo` (optional) — adapter-specific. For `github`, the `owner/name` slug to target. When unset or `"auto"`, the adapter resolves the repo from the local git `origin` remote.
+
+Absence of `workspace.forge` is treated as `{ type: 'github' }` (back-compat for workspaces that predate the field). Setting `workspace.forge: false` explicitly disables forge operations — every adapter method then throws `FORGE_DISABLED`.
+
+## Adapter interface (for Claude)
+
+Import from `.claude/scripts/forges/interface.mjs`:
+
+```javascript
+import { createForge, PrNotFound, MergeRejected, WorkflowNotFound, ReleaseNotFound } 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);
+
+// Pull request lifecycle
+const pr = await forge.prCreate({
+  title: 'feat: add forge adapter',
+  body: 'long-form body',
+  draft: false,                // omit or false for normal PRs; true for /pause-work drafts
+  base: 'main',                // optional; defaults to repo default branch
+  head: 'feature/forge',       // optional; defaults to current branch
+});                            // → { id: 'owner/repo#42', url, number }
+
+await forge.prMerge({
+  id: pr.id,
+  strategy: 'squash',          // 'merge' | 'squash' | 'rebase'
+  deleteBranch: true,
+});
+
+const view = await forge.prView({ id: pr.id });
+// → { state, mergeable, mergeStateStatus, reviewDecision, ... }
+
+// Releases (lookup only — release creation lives in the workflow tag-push)
+const release = await forge.releaseView({ tag: 'v1.2.3' });
+// → { tag, name, url, publishedAt, isDraft, isPrerelease }
+// throws ReleaseNotFound if the tag has no release
+
+// Workflow runs (used by /complete-work to follow the publish workflow)
+const run = await forge.workflowRunFind({
+  workflow: 'publish.yml',
+  branch: 'v1.2.3',
+  limit: 1,
+});                            // → { runId, status, conclusion, url } | null
+const result = await forge.workflowRunWatch({
+  runId: run.runId,
+  exitStatus: true,            // true: exit non-zero on workflow failure
+});                            // → { exitCode } — does NOT throw on workflow failure
+```
+
+All methods are async. Adapter-detectable failures throw typed errors; raw spawn failures throw `Error`.
+
+## Skill behavior
+
+Skills that interact with forge operations:
+
+- **`/pause-work`** — creates draft PRs via `forge.prCreate({ draft: true })`.
+- **`/complete-work`** — creates PRs, merges them with `strategy: 'squash'`, and (release sessions only) finds + watches the publish workflow via `workflowRunFind` + `workflowRunWatch`. Uses `releaseView` to investigate existing tag conflicts before re-tagging.
+
+Skills outside that list do not call the forge adapter; they either don't touch the forge or they touch it for tracker-setup-specific operations that are deliberately scoped out (see below).
+
+## What this rule does NOT cover
+
+- **Issue lifecycle.** Issues, comments, labels, milestones live in `work-item-tracking.md` via the tracker adapter at `.claude/scripts/trackers/{type}.mjs`. The two abstractions are intentionally separate.
+- **Tracker-setup repo configuration.** `/setup-tracker` uses `gh repo view --json hasIssuesEnabled` and `gh api repos/{slug} -X PATCH -f has_issues=true` to inspect and enable the Issues feature on a GitHub repo. Those are GitHub-API-specific setup operations, not the cross-cutting PR/release ops the forge abstraction targets. A GitLab user running `/setup-tracker` would follow a different setup flow entirely, so wrapping these in the forge adapter would create a leaky abstraction. They remain direct `gh` calls.
+- **`gh repo view` as a remote-type probe.** `/complete-work` uses `gh repo view` to detect whether a remote is a GitHub remote (separately from any PR operation that follows). This is a one-line capability check, not an operation that benefits from forge wrapping. It stays direct.
+- **Repo creation.** `gh repo create` (in `/sync-work` and `/workspace-init` setup narratives) is an interactive one-off used when a workspace lacks a remote. No forge adapter method for it — pointing users at a wrapped form when none exists would be worse than the current direct mention.
+- **Manual operator recovery.** `gh run rerun`, `gh run view`, `gh release view` referenced in `/release` recovery guidance are documented for an operator at a terminal investigating a failed publish. The forge adapter is for *skill code*, not the manual recovery prose.
+
+## Migration
+
+Existing workspaces predate `workspace.forge`. They continue to work because `createForge(undefined)` defaults to `{ type: 'github' }`. The `/maintenance` audit surfaces a notice when `workspace.tracker.type === 'github-issues'` and `workspace.forge` is unset, suggesting the explicit value — a one-line `workspace.json` addition with no behavior change.
+
+A workspace switching to GitLab implements `.claude/scripts/forges/gitlab.mjs` against the interface (the stub file documents the shape) and sets `workspace.forge.type: 'gitlab'`. No skill rewrite is required; the abstraction does the routing.
+
+## What this rule does NOT do
+
+- Does not prescribe a specific forge type. Adapter choice is per workspace.
+- Does not replace forge-native features (PR comments, review-requested webhooks, branch protection settings) — those remain UI / direct-CLI territory.
+- Does not promise that every `gh` capability is wrapped. The adapter covers the operations the template's skills actually perform. New operations land via additive interface methods, not by skills going around the adapter.

package/template/.claude/rules/goal-driven-work.md

@@ -15,6 +15,7 @@ If any of the three fails, prefer plain session work or a single skill invocatio
 ## File layout
 
 - One `goal-{topic}.md` artifact at the top of the active worktree, alongside `session.md`. One goal per worktree.
+- The artifact's frontmatter holds machine state; its body holds the human-readable goal statement, per-phase intent, and a mandatory `## Start command` section (see "Kicking off the goal") with the literal `/goal "..."` invocation the user runs to start the loop.
 - Phase output artifacts live as siblings. `research-*.md` and `crossref-*.md` are goal-native (produced by `parallel-research` and `crossref` phase types). `design-*.md` and `plan-*.md` are pre-existing session-artifact patterns that `type: skill` phases reuse when the wrapped skill is `superpowers:brainstorming` or `superpowers:writing-plans`; they are not goal-specific.
 - The artifact is tracked on the session branch and lives there until `/complete-work` runs. It is removed from the branch before the final PR alongside other session artifacts.
 
@@ -106,6 +107,19 @@ The evaluator's "no, awaiting review" response after a gated phase does not bypa
 
 `gate: auto` is allowed in the format but discouraged in v1. Earn it after the workflow has been exercised at least once on the work in question.
 
+## Gate-budget interaction and turn-budget sizing
+
+A goal's `turn_budget` is a backstop that counts every orchestrator turn — including the short "awaiting your gate decision" exchanges that happen at every `gate: review` phase. The `/goal` evaluator re-pings the session whenever it tries to settle without the completion condition being met, and each ping consumes a turn. Concretely: a multi-phase gated goal whose author is away for stretches can spend a meaningful fraction of its budget *idling at gates* rather than advancing work. A run with six `gate: review` phases burned roughly half of a 150-turn budget on gate-idle pings before the actual work completed.
+
+This is a structural property of `/goal` + review gates, not a per-goal accident. Plan for it:
+
+- **Drop `gate: review` from early phases when the human is expected to be away for stretches.** Research, crossref, spec, and plan phases produce artifacts that the final session→main PR consumes anyway. The integration-branch model (`main` untouched until `/complete-work` opens the final PR for human review) already provides one strong human review point; piling per-phase gates on top of that, with no human watching, just burns budget. Set those phases to `gate: auto` when the run will be unattended.
+- **Keep `gate: review` for phases with irreversible side effects or for phases whose outcome reshapes subsequent phases.** A spec gate that lets the human reprioritize the ranked execution list before `executing-plans` walks it is worth its cost; a research-synthesis gate that just rubber-stamps a matrix the human will see again in the final PR is not.
+- **Size `turn_budget` for the worst case you actually expect.** If every phase is `gate: auto`: budget ≈ (estimated work-turns) × 1.2 (small headroom for retries). If any phases are `gate: review` and the human may be unavailable for hours: multiply the work-turn estimate by **2–3×** to absorb gate-idle pings, or raise the budget mid-goal by editing the goal artifact's `completion_condition` and `turn_budget` fields. The Stop-hook condition string is fixed from the original `/goal` invocation; raising `turn_budget` in the artifact keeps the auditable source-of-truth correct for resume but does not change the running evaluator's text — the user can re-run the (updated) `## Start command` to refresh it after `/goal clear`.
+- **If the goal stops on the backstop mid-work because of gate-idle waste, that is the system working as designed.** `claude --resume` plus re-running the `## Start command` continues from durable phase state; phase artifacts and per-phase `status: complete` markers survive. Do not treat backstop-stop as a failure of the goal.
+
+This guidance is workspace-side mitigation only. The underlying friction — the evaluator pinging during gate-idle — is `/goal` harness behavior, not workspace code. A cleaner fix (suspend the evaluator at review gates so it does not re-ping until a new user message arrives) is tracked separately and would obsolete the multiplier above when it lands.
+
 ## Integration branch and per-phase sub-PRs
 
 While a `/goal`-driven session is running, the session branch (`feature/{session-name}`) acts as the goal's integration branch. Main is untouched until `/complete-work` opens the final session→main PR for human review. This is the key autonomy boundary: phase agents can merge their own work, repeatedly, throughout the goal — but only into the integration branch, never into main.
@@ -192,9 +206,31 @@ All phases in goal-<topic>.md show status: complete. Phase artifacts exist at: <
 
 Fill in `<topic>`, paths, and `<N>` per goal. Anchor on artifacts and committed state, not on feelings.
 
+## Kicking off the goal
+
+`/goal` is a Claude Code built-in that the **user** types — the agent cannot invoke it. So the moment the artifact is ready is the load-bearing hand-off, and the artifact itself carries the instruction rather than relying on an agent chat message that vanishes on the next compaction or resume.
+
+Every `goal-{topic}.md` body MUST include a `## Start command` section containing the literal, copy-paste-ready invocation:
+
+````markdown
+## Start command
+
+```
+/goal "All phases in goal-<topic>.md show status: complete. Phase artifacts exist at: <paths>. The /complete-work skill has produced release notes and opened the final PR; the PR URL appeared in the transcript. Or stop after <N> turns."
+```
+````
+
+Rules for the `## Start command`:
+
+- It is the `completion_condition` flattened to a **single line** and wrapped in `/goal "..."`. The frontmatter `completion_condition:` (a multi-line folded scalar) is the auditable source of truth; the start command is its runnable rendering. The two must express the same condition — if you edit one, re-derive the other.
+- Flatten by collapsing the folded scalar's newlines to single spaces. Escape any embedded double quotes. Keep it within the 4000-character `/goal` limit.
+- It lives in the body, not the frontmatter, because it is for a human to copy, not for machine parsing.
+
+When the artifact is drafted and the user has reviewed it, the agent's hand-off is: point the user at the `## Start command` block and let them run it. Running it flips the goal from `status: pending` to `status: active` (the first `/goal` turn updates the frontmatter per the dispatch pattern). The agent never types `/goal` itself.
+
 ## Lifecycle integration
 
-- `/goal` runs inside an active work session. It does NOT replace `/start-work`. The session is created the normal way, the goal artifact is drafted at the worktree top, then `/goal "<condition>"` kicks off the loop.
+- `/goal` runs inside an active work session. It does NOT replace `/start-work`. The session is created the normal way, the goal artifact is drafted at the worktree top (including its `## Start command` block), and the user runs that block's `/goal "..."` command to kick off the loop.
 - The goal artifact lives on the session branch and travels with `git push`. It survives across machines and `--resume`.
 - `session.md`'s `## Tasks` should mirror the phase list at coarse grain (one task per phase) so `TodoWrite` shows high-level progress. The main agent updates `## Tasks` at phase transitions via the helper specified by the `task-list-mirroring` rule, in addition to updating `goal-{topic}.md`.
 - `/pause-work` works without special handling. The goal-evaluator state resets on resume per the Claude Code docs; phase state is durable in the artifact.
@@ -218,9 +254,9 @@ When the goal artifact is itself the deliverable for a future session to execute
 
 ## Appendix: worked example
 
-A complete `goal-evaluate-rate-limiting.md` illustrating all three phase types. The topic is intentionally generic — the example is reference material, not prescriptive.
+A complete `goal-evaluate-rate-limiting.md` illustrating all three phase types. The topic is intentionally generic — the example is reference material, not prescriptive. (The appendix is fenced with four backticks so the example's own `## Start command` code block renders intact.)
 
-```yaml
+````yaml
 ---
 type: goal
 topic: evaluate-rate-limiting
@@ -357,6 +393,14 @@ The api-gateway needs rate limiting before the next traffic step-up. This
 goal runs the full arc from candidate-algorithm research through implementation
 on the session branch.
 
+## Start command
+
+```
+/goal "All 5 phases in goal-evaluate-rate-limiting.md show status: complete. Phase artifacts exist at: research-rate-limiting-strategies.md, crossref-existing-infrastructure.md, design-rate-limiting.md, plan-rate-limiting.md, and the implementation commits land on the session branch (visible in git log). The /complete-work skill has produced release notes and opened the final PR; the PR URL appeared in the transcript. Or stop after 60 turns."
+```
+
+This is the frontmatter `completion_condition` flattened to one line. Run it after reviewing the artifact; it flips the goal to `status: active`.
+
 ## Per-phase intent
 
 1. **strategy-research** runs three researchers in parallel, one per
@@ -385,4 +429,4 @@ All phase agents and synthesizers run on Sonnet (the default for team work).
 The main agent reading and orchestrating this goal runs on Opus. Haiku is
 unused in this example; it would be appropriate for a phase whose sole job
 is, e.g., scanning a tree and returning a tagged file list.
-```
+````

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

@@ -47,6 +47,16 @@ Canonical content is verbatim-loaded into every session via `CLAUDE.md` → `@wo
 
 Inflight session state lives inside the session worktree at `work-sessions/{name}/workspace/session.md`, not in `workspace-context/`. Workspace-context is for knowledge that outlives any individual session.
 
+## Dynamic context loading (hooks)
+
+Two hooks extend static `CLAUDE.md` loading with context that varies per session and per invocation:
+
+- **`session-start.mjs`** (`SessionStart` hook): reads the active session pointer from `workspace-scratchpad/` and injects the current session's name, branch, linked work item, and shared context catalog into Claude's context. The injection is conditional — if no session is active, or if the relevant fields are absent from the session frontmatter, nothing is added. This avoids noise in non-session contexts (e.g., a quick launcher query).
+
+- **`subagent-start.mjs`** (`SubagentStart` hook): reads every file under `workspace-context/shared/locked/` and injects their content into subagent context. A `subagentContextMaxBytes` field in `workspace.json` (default 10240) acts as a byte-budget fallback — if the total locked content exceeds the budget, files are truncated in reverse-priority order rather than silently dropped. This ensures subagents that never load `CLAUDE.md` still receive canonical team truths.
+
+Both hooks are at `.claude/hooks/session-start.mjs` and `.claude/hooks/subagent-start.mjs`. They are registered as Node.js scripts — cross-platform, no shell dependency.
+
 ## Spec and Plan Locations — MANDATORY OVERRIDE
 
 **Specs, plans, and goal artifacts MUST be written at the top of the active session's workspace worktree, not to `docs/superpowers/` or any other location.**
@@ -97,3 +107,31 @@ Local-only personal drafts get an additional `local-only-` prefix (e.g., `local-
 - `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.
 - Hand edits to `index.md`, `canonical.md`, or any per-user `team-member/{user}/index.md` are overwritten by `build-workspace-context.mjs`. Update source files (or their `description:` frontmatter) instead.
+
+## Per-repo commands
+
+Per-repo test, lint, and build commands belong in `repos/{repo}/CLAUDE.md` under a `## Commands` section. This scopes Claude's command invocations to the specific repo rather than triggering monorepo-wide runs that may time out or produce irrelevant output. The `/workspace-init` skill scaffolds a blank `repos/{repo}/CLAUDE.md` stub with a `## Commands` placeholder — fill it in once the repo is cloned.
+
+## Explore before editing
+
+Before modifying files in a large or unfamiliar codebase, use read-only tools to map the affected surface. The workflow: dispatch a researcher-type subagent to read, grep, and navigate the codebase; have it return a summary of the affected files, callers, and dependencies; then edit only after the map is established.
+
+The `researcher.md` agent enforces this pattern mechanically via `disallowedTools: [Edit, Write, Bash]` — it can read and search but cannot change anything. Use it for initial exploration, then hand the findings back to the main agent for the actual edit. This avoids partial edits that break callers, catches ripple effects before they happen, and keeps the edit surface as small as possible.
+
+## Launching Claude from a project worktree
+
+Claude can be launched from any directory, and it walks up the filesystem loading every `CLAUDE.md` it finds. This means starting `claude` from `work-sessions/{name}/workspace/repos/{repo}/` loads both the per-repo conventions (from `repos/{repo}/CLAUDE.md`, if it exists) and the full workspace conventions (from the workspace `CLAUDE.md` further up the tree) — all without extra configuration.
+
+For repo-focused work — debugging a single service, reviewing a specific module, running targeted tests — launching from the project worktree gives Claude a tighter codebase context. It sees the repo's own file tree first and reaches workspace-level conventions by traversal. The session hooks still fire (they read from `workspace-scratchpad/`, which is always relative to the workspace root), and `session.md` and all session artifacts remain at the workspace worktree top.
+
+This is purely a launch-point choice; no workspace configuration changes are needed to enable it.
+
+## Grep vs LSP
+
+Two complementary search strategies cover different parts of the navigation surface:
+
+- **Grep / Ripgrep** — searches file content as text. Fast, requires no server, and works across any file type. Use for free-text pattern search: finding a string literal, locating config values, scanning comments, searching across heterogeneous files. The downside: no language awareness — a search for `_toMs` matches comments, string literals, and variable names alike, producing false positives that require manual filtering.
+
+- **LSP tools (`mcp__lsp__*`)** — powered by a running Language Server Protocol server that has indexed the codebase. LSP understands the language's type system and scope rules, so `find-all-references` on `_toMs` returns only actual symbol usages, not textual coincidences. Go-to-definition, rename-symbol, and callers/callees are accurate even across files and module boundaries. The tradeoff: requires a running LSP MCP server configured in `.mcp.json`.
+
+The practical rule: reach for Grep first when you don't know where to look or when the pattern is not a symbol. Switch to LSP when you have a specific symbol and need precise cross-file navigation — especially before refactoring or understanding a call graph. The `researcher.md` agent lists the LSP tool among its allowed tools; activating LSP requires adding the appropriate language server to `.mcp.json` (see the MCP servers step in `/workspace-init`).