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

package/template/{.claude → _claude}/lib/session-frontmatter.mjs

@@ -263,3 +263,31 @@ export function writeSessionFile(filePath, fields, body = '') {
 export function readSessionFields(filePath) {
   return readSessionFile(filePath).fields;
 }
+
+// This module is a LIBRARY, not a CLI. Several skills say "update the tracker
+// via the session-frontmatter helper", and the natural reading of that — given
+// that everything else a skill invokes (sync-tasks.mjs, create-work-session.mjs,
+// build-workspace-context.mjs) is a real CLI — is to run this file with flags.
+//
+// Without this guard, Node imports the module, finds no side effects, ignores
+// the arguments and EXITS 0. The caller sees success, the frontmatter is
+// untouched, and a `cmd || fallback` idiom never fires because exit 0 is
+// success. That silently dropped a `workItem:` linkage during the gh:89
+// session and was only caught by re-reading the file (gh:143).
+//
+// So: fail loudly and say what to call instead.
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+  process.stderr.write(
+    'session-frontmatter.mjs is a library, not a CLI — it takes no arguments.\n' +
+    '\n' +
+    'Import it instead:\n' +
+    '  node --input-type=module -e \'\n' +
+    '  import { updateSessionFile } from "./.claude/lib/session-frontmatter.mjs";\n' +
+    '  updateSessionFile("session.md", { workItem: "gh:42" });\n' +
+    '  \'\n' +
+    '\n' +
+    'Exports: parseSessionContent, updateSessionContent, updateSessionFile,\n' +
+    'readSessionFile, readSessionFields, writeSessionFile.\n',
+  );
+  process.exit(2);
+}

package/template/{.claude → _claude}/rules/coherent-revisions.md

@@ -19,6 +19,6 @@ Injected revisions create fragmented, hard-to-follow output where the seams betw
 
 - When updating a section of a document, rewrite the entire section — not just the changed sentences
 - When updating a workspace-context file, rewrite it as a fresh snapshot of current understanding
-- When synthesizing multiple sources into release notes, write the narrative from scratch — don't concatenate
+- When synthesizing multiple sources into a PR body or summary, write the narrative from scratch — don't concatenate
 - When revising code with comments, ensure the comments tell a coherent story, not a changelog
 - Small, isolated edits (fixing a typo, updating a single value) are fine — this rule targets substantive revisions

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

@@ -0,0 +1,57 @@
+---
+paths:
+  - "**/.claude/skills/**"
+  - "**/.claude/scripts/**"
+---
+
+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 does against a code-hosting forge.
+
+# Forge Operations
+
+**Skills never call `gh` (or `glab`, or any forge CLI) inline for pull-request, release, or
+workflow-run operations.** They go through the adapter at `.claude/scripts/forges/{type}.mjs`,
+reached via `createForge()` from `.claude/scripts/forges/interface.mjs`.
+
+The interface module is the source of truth for the available methods and their shapes —
+read it when you need the API. `/complete-work` and `/pause-work` each carry the exact calls
+they make, so in practice you rarely need to look.
+
+## Why
+
+Switching code hosts becomes a `workspace.json` field plus one adapter file instead of a
+sweep across six skills. Failure modes share typed errors — `PrNotFound`, `MergeRejected`,
+`WorkflowNotFound`, `ReleaseNotFound` — instead of every callsite parsing stderr. And the
+adapter takes an injectable `spawnFn`, so tests mock subprocesses rather than running them.
+
+## Configuration
+
+`workspace.json` → `workspace.forge`: `{ "type": "github" }`. `type` names the adapter module;
+`github` is the default and the only complete one, `gitlab.mjs` is a stub that throws
+`NOT_IMPLEMENTED`. Optional `repo` is an `owner/name` slug; unset or `"auto"` resolves from the
+git `origin` remote. An absent `workspace.forge` is treated as `{ type: 'github' }`; setting it
+to `false` makes every adapter method throw `FORGE_DISABLED`.
+
+## Deliberate exceptions — do not "fix" these
+
+These stay as direct `gh` calls. Wrapping them would create a leaky abstraction, so leave them
+alone:
+
+- **Issue lifecycle** — issues, comments, labels and milestones belong to the tracker adapter.
+  See `work-item-tracking.md`. The two abstractions are intentionally separate.
+- **`/setup-tracker` repo configuration** — `gh repo view --json hasIssuesEnabled` and
+  `gh api repos/{slug} -X PATCH -f has_issues=true` are GitHub-API-specific setup, not
+  cross-cutting operations. A GitLab user's setup flow differs entirely.
+- **`gh repo view` as a remote-type probe** — a one-line capability check, not an operation.
+- **`gh repo create`** — an interactive one-off when a workspace has no remote.
+- **Manual recovery prose** — `gh run rerun`, `gh run view`, `gh release view` in `/release`
+  guidance are for an operator at a terminal, not for skill code.
+
+## Boundaries
+
+The adapter covers the operations the template's skills actually perform, not every `gh`
+capability. New operations land as additive interface methods, never by a skill going around
+the adapter. Forge-native features — PR comments, review webhooks, branch protection — remain
+UI and direct-CLI territory.
+
+Workspaces predating `workspace.forge` keep working, since `createForge(undefined)` defaults to
+GitHub. `/maintenance` surfaces a notice suggesting the explicit value.

package/template/_claude/rules/git-conventions.md

@@ -0,0 +1,39 @@
+# Git Conventions
+
+## Branching
+
+- Prefixes: `feature/`, `bugfix/`, `chore/`
+- Names: kebab-case after prefix, no grouping/nesting
+- Examples: `feature/ble-provisioning`, `bugfix/mqtt-reconnect`
+- All branches merge to the repo's default branch
+- Branch names should be unique — if revisiting previous work, distinguish the new branch name
+
+## Worktrees
+
+Both lifecycles are built on worktrees; `workspace.sessionModel` in `workspace.json` routes new work to one of them.
+
+**Task model** (`"task"`): one worktree per repo the task touches, created and removed with `.claude/scripts/task-worktree.mjs` (the chat stays at the workspace root):
+
+- Project repos: `repos/{repo}/.claude/worktrees/{slug}/`, where `{slug}` is the branch with `/` replaced by `-`
+- The workspace repo itself, addressed as `.`: `.claude/worktrees/{slug}/` — Claude Code's native worktree location
+- Source clones at `repos/{repo}/` stay on their default branch; `/complete-work` tears each worktree down with `task-worktree.mjs --remove` (worktree first, then the branch)
+
+**Session model** (default): N+1 worktrees in one self-contained folder at `work-sessions/{session-name}/`:
+
+- `work-sessions/{session-name}/workspace/` — workspace worktree
+- `work-sessions/{session-name}/workspace/repos/{repo-name}/` — project worktrees nested inside it (no symlink)
+- Example, session `fix-auth` on `bugfix/fix-auth` touching `my-app` and `my-api`: `work-sessions/fix-auth/workspace/` plus `workspace/repos/my-app/` and `workspace/repos/my-api/`
+- Teardown order is mandatory: project worktrees first, then the workspace worktree, then prune — the cleanup helper enforces it
+
+The workspace `.gitignore` covers all of it: `repos` (no trailing slash) matches the root's `repos/` and every session worktree's nested `repos/`; `.claude/worktrees/` matches task worktrees of the workspace repo itself.
+
+## Branch Maintenance
+
+- Before creating a PR, fetch and rebase onto the latest parent branch
+- If conflicts arise during rebase, stop and present them to the user — do not auto-resolve
+
+## Commits
+
+- Conventional commit format: `feat:`, `fix:`, `refactor:`, `chore:`, `docs:`
+- Never amend commits unless explicitly asked
+- Never force push unless explicitly asked

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

@@ -0,0 +1,24 @@
+# Goal-Driven Work
+
+How to use Claude Code's built-in `/goal` command in a Ulysses workspace for multi-phase, agent-team-driven work. `/goal` is the autonomy loop; this rule is the convention layer that gives the main agent durable phase state and a consistent dispatch pattern across turns and resumes.
+
+## When to reach for `/goal`
+
+Use `/goal` when the work meets all three:
+
+1. **Multi-phase.** It naturally decomposes into discrete phases (research, design, implementation, validation, etc.) and the phases produce intermediate artifacts before the work is done.
+2. **Verifiable end state.** "Done" can be demonstrated from the conversation transcript — a PR opened, a set of artifacts written, a test suite passing — rather than judged subjectively.
+3. **Spans more than one or two turns of natural conversation.** Single-skill invocations (one brainstorm, one plan, one fix) don't need `/goal`; the existing skills carry them.
+
+If any of the three fails, prefer plain session work or a single skill invocation. `/goal` is overhead. Pay it only when the work is long enough to earn it.
+
+## The convention lives in a skill
+
+Everything past this decision — the `goal-{topic}.md` frontmatter schema, the three phase
+types, agent-team dispatch, gate conventions, the integration-branch model with per-phase
+sub-PRs, model tiering, and the worked example — is in the `goal-driven-work` skill.
+
+Invoke it before drafting a goal artifact or running a goal phase. It is a skill rather than
+a rule because it is a procedure needed by the small number of sessions that run `/goal`,
+not a constraint every session must carry. Loading it on demand keeps roughly 27 KB out of
+every session's always-loaded context.

package/template/_claude/rules/honest-pushback.md

@@ -0,0 +1,56 @@
+# Honest Pushback
+
+Do not agree to be agreeable. Do not keep trying things that aren't working. Do not assume
+when you can verify. Challenge assumptions and flag concerns even when the user is
+enthusiastic.
+
+## What this means
+
+- If an approach has obvious downsides, say so before implementing.
+- If a decision contradicts an earlier one, name the contradiction.
+- If scope is creeping, name it: "This started as X but is becoming Y. Split?"
+- If you don't know, say so — don't fabricate confidence.
+- If the idea is good, "that works" is enough. No embellishment.
+- If you made a mistake, own it plainly. No hedging.
+
+## No retry loops
+
+If a fix produced the same error or an unexpected result twice, stop. Do not try a variation
+of the same approach. Instead:
+
+1. **State expected vs actual**, specifically — not "it didn't work" but "expected 200, got
+   403 with message X".
+2. **Name the failing assumption.** What is surprising, and why?
+3. **Research it.** Read the docs, search the error, read the source. Use web search if local
+   sources don't explain it.
+4. **Report what you learned** and propose a fix based on understanding, not guessing.
+
+This stops the cycle of trying broken variations when reading the docs would take one turn.
+
+## Verify, don't assume
+
+When evidence is available, check it before proceeding. Logs, the database, the actual UI,
+runtime state, a real API call — whichever settles the question. If the logs aren't verbose
+enough, add instrumentation, run it, read the output, remove it.
+
+The tell is reaching for "I think the issue is…", "probably", or "likely" about something
+you could check in one step. Reasoning about what a function returns when you could call it
+is the same mistake.
+
+**Ask once**, then stop asking: "I want to verify {what} by {how}. Go ahead, or should I
+just check without asking each time?" If the user says just check, verify proactively for
+the rest of the session. Asking once is polite; asking every time is friction.
+
+Use judgment — don't over-verify the trivial.
+
+## What this does not mean
+
+Don't be contrarian as a personality trait; push back where there is substance. Don't refuse
+to execute — voice the concern, then follow the user's decision. Don't lecture: state it
+once and move on.
+
+## Why
+
+Sycophancy wastes time and lets bad decisions through. Retry loops burn tokens. Assumptions
+that could have been checked cascade into wrong decisions. A useful collaborator says when
+something is off, stops when it isn't working, and finds out why before trying again.

package/template/_claude/rules/memory-guidance.md

@@ -0,0 +1,66 @@
+# Memory and Placement Guidance
+
+Where durable content goes, and what each destination costs.
+
+## Where durable content goes
+
+Eight destinations, ordered cheapest first. Work down and stop at the first that genuinely
+fits. The right column is what every session pays, forever, for the choice.
+
+| destination | for | always-loaded cost |
+|---|---|---|
+| nowhere | already covered, or true only today | zero |
+| `.claude/rules/*.md` with `paths:` | an instruction that applies only to certain files | zero until a match is read |
+| a skill | a procedure with steps, invoked on demand | its `description` line |
+| auto-memory | machine-local preference or correction; not shared, not reviewable | one `MEMORY.md` line |
+| `team-member/{user}/` | one person's working context | one index line, that user |
+| `shared/` | team-visible reference, looked up when relevant | one index line |
+| `shared/locked/` | canonical team truth | **the whole file, every session** |
+| `.claude/rules/*.md` (no `paths:`) | an instruction that must hold in every session | **the whole file, every session** |
+
+**`nowhere` is the most common correct answer.** A second copy in a second location is
+worse than none — they drift, and the reader cannot tell which is current.
+
+The two bold rows tax every session in this workspace, and anything shipped in the template
+taxes every downstream workspace too. Reach them only after the cheaper rows are actually
+ruled out. Prefer `paths:` for anything domain-specific: a rule about migration scripts does
+not need to be in context while editing documentation.
+
+**Before writing to either bold row, state the cost:**
+
+```bash
+node .claude/scripts/context-footprint.mjs --root . --add <bytes> --as <destination>
+```
+
+A rule that applies only to certain files should carry `paths:` frontmatter — it costs nothing
+until a matching file is touched — and the same script checks the live total against
+`workspace.alwaysLoadedBudgetBytes`.
+
+## The canonical test
+
+Canonical describes what *is* and what *to do*, never what *to think*.
+
+> If Claude read this for the first time during a session about an unrelated topic, would it
+> (a) help frame the problem correctly, or (b) push it toward a particular answer to a
+> question that hasn't been asked yet?
+
+(a) is canonical. (b) is `shared/` at most, more often `team-member/{user}/`. Pre-loaded
+conclusions don't read as opinions to Claude — they read as ground truth, and they frame
+what Claude considers before the question is asked.
+
+## Auto-memory specifically
+
+Save: architecture decisions and their rationale, patterns that caused bugs, user
+corrections about project conventions, external URLs and API quirks, tooling workarounds.
+
+Don't save: temporary debugging state, file contents (re-read them), anything already in a
+workspace-context file or a rule.
+
+When work is in flight, its decisions and progress go in the lifecycle's own state — the
+session tracker body at `work-sessions/{name}/workspace/session.md` (session model) or the
+chat drawer at `workspace-scratchpad/chats/{chat}/` (task model) — which `/complete-work`
+consumes. Auto-memory is for what outlives the work. Never both.
+
+For the full routing procedure, the frontmatter schema, the generator invocations, and the
+belongs/doesn't-belong lists behind the canonical test, invoke the `context-placement`
+skill.

package/template/{.claude → _claude}/rules/superpowers-workflow.md.skip

@@ -12,7 +12,7 @@ Activate this rule if the superpowers plugin is installed.
 ## Specs and Plans
 
 - Specs and plans live in the active worktree during development
-- They are ephemeral — consumed by /complete-work into release notes, then removed
+- They are ephemeral — consumed by /complete-work into the PR body, then removed
 - If a spec/plan already exists for the current branch, version it: `-v2`, `-v3`, etc.
 
 ## Execution

package/template/{.claude → _claude}/rules/task-list-mirroring.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - "work-sessions/**"
+  - "**/session.md"
+---
+
 # Task List Mirroring
 
 The Claude Code `TodoWrite` checklist is a live mirror of the workspace lifecycle. The durable backing store is a `## Tasks` section in `session.md`, round-tripped by `.claude/scripts/sync-tasks.mjs`. This rule defines the contract.

package/template/_claude/rules/work-item-tracking.md

@@ -0,0 +1,48 @@
+# Work Item Tracking
+
+When a workspace has a tracker configured, **all work items — bugs, features, chores — live
+in that tracker.** There is no local file mirroring its state. Skills reach it through
+`createTracker()` from `.claude/scripts/trackers/interface.mjs`; that module is the source of
+truth for the available methods, and the four skills that use it (`start-work`, `pause-work`,
+`complete-work`, `setup-tracker`) each carry the exact calls they make.
+
+## Why external-first
+
+Two people can't start the same ticket — the tracker is the source of truth for who has what.
+Status changes reach the whole team the moment they happen rather than after a push. And
+humans and Claude read the same list in the same place.
+
+## Configuration
+
+`workspace.json` → `workspace.tracker`: `{ "type": "github-issues", "repo": "owner/name" }`.
+`type` names the adapter at `.claude/scripts/trackers/{type}.mjs`; only `github-issues` ships.
+`repo` is adapter-specific — for GitHub, the slug where issues live, or `"auto"` to resolve
+from the git remote. No `workspace.tracker` means tracking is disabled, and skills fall back
+to a blank describe-the-work flow rather than fabricating a local mirror.
+
+## Session linkage
+
+`/start-work` records the adapter-prefixed issue ID in session frontmatter as `workItem: gh:42`.
+The prefix makes it self-describing across adapter swaps.
+
+## When to create issues
+
+- **Work described during `/start-work`** → create the issue, then claim it.
+- **A bug or feature found mid-session** → ask "Create an issue for this? [Y/n]". Link it to
+  the session if it is in scope; leave it unassigned if it is a future concern.
+- **Never during braindumps or handoffs.** Those are discussion artifacts. Action items can
+  graduate to issues later, at `/start-work`.
+
+## What not to do
+
+- Do not create, read, or write `workspace-context/open-work.md`. It is deprecated.
+- Do not put ticket state in session frontmatter beyond the `workItem:` pointer. Status,
+  assignment, labels and milestone live in the tracker.
+- Do not cache issue bodies locally. Fetch with `tracker.getIssue(id)` when you need one.
+
+## Boundaries
+
+Adapter choice is per workspace; this rule prescribes no particular tracker. Beyond the six
+labels `ensureLabels()` creates (`bug`, `feat`, `chore`, `P1`, `P2`, `P3`), it prescribes no
+schema — teams with an existing tracker skip label creation. Tracker-native features like
+comments, reactions and linked PRs stay in the tracker's own UI.

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

@@ -0,0 +1,79 @@
+# Workspace Structure
+
+All paths are relative to the workspace root. Two work lifecycles coexist, selected for new work by `workspace.sessionModel` in `workspace.json`: **task** (the forward path — one issue, one branch, one worktree per touched repo, chat at the root) and **session** (supported — a self-contained `work-sessions/{name}/` folder per effort with a workspace worktree and a `session.md` tracker).
+
+## Directory Layout
+
+| Path | Purpose | Tracked? |
+|------|---------|----------|
+| `repos/{repo}/` | Source clones (always on the default branch) | No |
+| `repos/{repo}/.claude/worktrees/{slug}/` | Task worktree for a project repo (`{slug}` = branch with `/` → `-`) | No |
+| `.claude/worktrees/{slug}/` | Task worktree for the workspace repo (`--repo .`) — Claude Code's native worktree location; the two converge | No |
+| `work-sessions/{name}/workspace/…` | Session lifecycle: workspace worktree, nested project worktrees at `workspace/repos/{repo}/`, `session.md` + artifacts (`design/plan/goal/research/crossref-*.md`) on top | Session branch |
+| `workspace-context/` | Team knowledge: `shared/` (ephemerals), `shared/locked/` (canonical truths), `team-member/{user}/` (per-user) | Yes |
+| `workspace-context/index.md`, `canonical.md`, `team-member/{user}/index.md` | Auto-generated catalogs (`canonical.md` = verbatim `shared/locked/`; `.indexignore` excludes paths) — regenerate with `build-workspace-context.mjs`, never hand-edit | Yes |
+| `workspace-scratchpad/` | Machine-local, regenerable: session log, hook debug output, chat records `chats/{chat}.json`, chat drawers `chats/{chat}/` (task-lifecycle designs, plans, braindumps, research in progress) | No |
+| `CLAUDE.md`, `CLAUDE.local.md`, `.claude/` | Launcher prompt (imports `canonical.md` + `index.md`); per-user prompt; rules, agents, skills, hooks, scripts | All but `CLAUDE.local.md`, `settings.local.json`, `.claude/.active-session.json`, and `.claude/worktrees/` |
+
+## Workspace-Context Levels
+
+| Level | Path | What lives there | How it gets there |
+|-------|------|------------------|-------------------|
+| Personal | `team-member/{user}/` | Per-user braindumps, handoffs, research | Default for `/braindump`, `/handoff`, `/aside` (session lifecycle / no drawer; task-lifecycle chats default to the chat drawer) |
+| Shared | `shared/` | Team-visible ephemerals | Explicit `--scope shared` or `/promote` |
+| Canonical | `shared/locked/` | Promoted truths — conventions, discipline, status | `/promote` (locked target) |
+
+Canonical loads verbatim into every session (`CLAUDE.md` → `@workspace-context/canonical.md`); personal only for the active user (`CLAUDE.local.md`). Inflight work state (session tracker, chat drawer) never lives in `workspace-context/` — that is for knowledge that outlives any single effort.
+
+## Dynamic context loading (hooks)
+
+- **`session-start.mjs`** (`SessionStart`): injects the workspace name, a `Chat record:` line naming this chat's record, and a `Workspace root:` line with the launcher's absolute path (git-derived roots land on the source clone from inside a task worktree); with an active session pointer, also the session's name, branch, work item, and shared-context catalog.
+- **`subagent-start.mjs`** (`SubagentStart`): gives subagents the canonical truths they miss (subagents do not load `CLAUDE.md`) — locked files under `workspace.subagentInlineMaxBytes` (8192) are inlined with frontmatter stripped, larger ones become pointers, and past `workspace.subagentContextMaxBytes` (32768) the largest demote first. Gitignored and `local-only-*` files are excluded.
+
+Both are Node.js scripts — cross-platform, no shell dependency.
+
+## Spec and Plan Locations — MANDATORY OVERRIDE
+
+**Specs, plans, and goal artifacts MUST be written to the current lifecycle's work area, not to `docs/superpowers/` or any other location.**
+
+- Session: top of the session worktree — `design-{topic}.md`, `plan-{topic}.md`, `goal-{topic}.md`, plus goal-native `research-*.md`/`crossref-*.md` siblings. On the session branch; stripped before the final PR.
+- Task: the chat drawer `workspace-scratchpad/chats/{chat}/` — same artifact names. Machine-local; `/complete-work` promotes what deserves to survive into `workspace-context/`.
+
+This overrides external skills' default paths (e.g., Superpowers' `docs/superpowers/specs/`) — those skills defer to user preferences, and this rule IS that override. Never create `docs/superpowers/` directories. Version an existing artifact: `design-{topic}-v2.md`.
+
+## File Naming Conventions
+
+Ephemeral files under `shared/` and `team-member/{user}/` carry a type prefix:
+
+| Skill | Filename prefix |
+|-------|-----------------|
+| `/braindump` | `braindump_{topic}.md` |
+| `/handoff` | `handoff_{topic}.md` |
+| `/aside` (full) / `--quick` | `research_{topic}.md` / `braindump_{topic}.md` (`variant: aside`) |
+| `/promote` | preserves source prefix |
+
+Local-only drafts add a `local-only-` prefix to stay gitignored until promoted.
+
+## Rules
+
+- The workspace root stays on its default branch — it is the launcher, not a worktree.
+- All real work happens in worktrees — `work-sessions/{name}/workspace/` (session) or a `.claude/worktrees/{slug}/` location (task). Source clones at `repos/{repo}/` never take a feature branch.
+- Session content commits to the session branch; task work to task worktrees; drawer writes need no commit (gitignored, machine-local).
+- `workspace-scratchpad/` is machine-local and regenerable — losing it costs a re-derivation, not the work. Not all of it is disposable: `session-log.jsonl` is real history no other file carries.
+- Hand edits to auto-generated catalogs are overwritten by `build-workspace-context.mjs` — update the source files (or their `description:` frontmatter) instead.
+
+## Per-repo commands
+
+Per-repo test, lint, and build commands belong in `repos/{repo}/CLAUDE.md` under `## Commands`, scoping invocations to that repo instead of the whole monorepo. `/workspace-init` scaffolds the stub.
+
+## Explore before editing
+
+Before editing an unfamiliar codebase, map the affected surface first — typically a `researcher.md` subagent dispatch (`disallowedTools: [Edit, Write, Bash]`) returning affected files, callers, and dependencies. Edit only after the map is established.
+
+## Launching Claude inside a worktree
+
+A git worktree is a context boundary: `CLAUDE.md` discovery stops at the worktree's root, and gitignored content (`repos/`, `local-only-*`, `workspace-scratchpad/`) is absent from it. So a chat launched inside a project worktree — a session's `workspace/repos/{repo}/` or a task's `repos/{repo}/.claude/worktrees/{slug}/` — sees only that repo's own `CLAUDE.md`, not the workspace conventions or hooks. Keep the chat at the workspace root and reach worktrees by path; launch inside one only for deliberately isolated, repo-only work.
+
+## Grep vs LSP
+
+**Grep/Ripgrep** searches content as text — fast, no server, but no language awareness, so symbol searches surface false positives. **LSP** (`mcp__lsp__*`) understands types and scope — find-all-references returns only real usages — but needs an LSP MCP server in `.mcp.json`. Grep when you don't know where to look; LSP for precise navigation of a specific symbol.