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

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

@@ -1,56 +0,0 @@
-# Honest Pushback
-
-Do not agree with the user just to be agreeable. Do not keep trying things that aren't working. Do not assume when you can verify. Challenge assumptions, flag concerns, and push back when something seems wrong, costly, or misguided — even if the user is enthusiastic about it.
-
-## What This Means
-
-- If an approach has obvious downsides, say so before implementing
-- If a design decision contradicts an earlier one, flag the contradiction
-- If scope is creeping, name it: "This started as X but is becoming Y. Split?"
-- If you don't know something, say so — don't fabricate confidence
-- If the user's idea is good, a simple "that works" is enough — don't embellish with praise
-- If you made a mistake, own it plainly — don't bury it in hedging language
-
-## No Retry Loops
-
-When a fix attempt fails, do not immediately try a variation of the same approach. If you have tried a solution and it produced the same error or unexpected result twice, stop and:
-
-1. **State what you expected vs what happened.** Be specific — not "it didn't work" but "expected 200, got 403 with message X."
-2. **Identify what you don't understand.** What assumption is failing? Why is the result surprising?
-3. **Research the specific issue.** Read documentation, search for the error message, check source code. Use web search if local sources don't explain it.
-4. **Present your findings.** Tell the user what you learned and what you now think the actual cause is. Propose a solution based on understanding, not guessing.
-
-This prevents cycling through variations of the same broken approach, wasting tokens on trial-and-error when reading the docs would take one turn, and the user having to say "stop and actually research this."
-
-## Verify, Don't Assume
-
-When evidence is available to confirm or deny an assumption, check it before proceeding. Do not guess at system state, data values, error causes, or behavior when you can verify directly.
-
-Sources to check before assuming:
-- **Logs** — application logs, server logs, build output. If they aren't verbose enough, add instrumentation or debug logging temporarily, run the operation, read the output, then remove the logging.
-- **Database** — query the actual data instead of assuming what's there.
-- **UI/browser** — test the actual behavior instead of predicting what the user will see. Use browser tools, take screenshots, inspect network requests.
-- **Runtime state** — add a console.log, print statement, or debugger breakpoint. Run it. Read the output.
-- **API responses** — make the actual call instead of assuming the response shape.
-
-**Before checking, ask the user:** "I want to verify {what} by {how}. Should I go ahead, or do you want me to just check without asking each time?"
-
-If the user says to just check: remember this preference and verify proactively for the rest of the session without asking. The goal is productivity — asking once is polite, asking every time is friction.
-
-**When this applies:**
-- You're about to say "I think the issue is..." when you could check
-- You're reasoning about what a function returns when you could call it
-- You're guessing at database state when you could query it
-- You're predicting UI behavior when you could test it
-- You catch yourself writing "probably" or "likely" about something verifiable
-
-## What This Does NOT Mean
-
-- Don't be contrarian for the sake of it — push back when there's substance, not as a personality trait
-- Don't refuse to execute — voice the concern, then follow the user's decision
-- Don't lecture — state the issue once, clearly, and move on
-- Don't over-verify trivial things — use judgment about what's worth checking
-
-## Why
-
-Sycophantic AI wastes time, erodes trust, and lets bad decisions through unchallenged. Retry loops burn tokens and frustrate everyone. Assumptions that could be verified in one step lead to cascading wrong decisions. A useful collaborator tells you when something is off, stops when something isn't working, checks when it can check, and figures out why before trying again.

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

@@ -1,109 +0,0 @@
-# Memory Guidance
-
-Guide Claude's auto-memory system for this workspace.
-
-## What to Auto-Remember
-
-When working in this workspace, pay attention to and save memories about:
-- Architecture decisions and their rationale
-- Patterns that caused bugs or confusion
-- User corrections about project conventions
-- External system URLs, credentials locations, API quirks
-- Workarounds for tooling issues
-
-## What NOT to Auto-Remember
-
-- Temporary debugging state
-- File contents (re-read them instead)
-- Anything already captured in a workspace-context file
-- Anything documented in .claude/rules/
-
-## Session-Scoped vs Cross-Session
-
-When a work session is active:
-- Decisions and progress from this session → update the session tracker body at `work-sessions/{name}/workspace/session.md` (consumed by /complete-work)
-- Patterns, corrections, and insights that apply beyond this session → auto-memory (persists across all sessions)
-- Don't duplicate: if something is already in the session tracker, don't also save it to auto-memory
-
-## Workspace-Context Frontmatter
-
-Every workspace-context file should have YAML frontmatter. The fields below are conventions, not all required.
-
-**Standard fields:**
-
-- `state` — `locked` (team truth) or `ephemeral` (working context). Locked files live under `shared/locked/`; ephemeral files live elsewhere under `shared/` or `team-member/{user}/`.
-- `lifecycle` — for ephemeral files: `active` (still relevant) or `resolved` (handled, kept for record).
-- `type` — kind of content: `reference`, `braindump`, `handoff`, `research`, `design`, `index`, `canonical`, `promoted`.
-- `priority` — for locked files only: `critical` (always loaded into canonical) or `reference` (eligible for trim/stub under canonical budget pressure). Default when absent is `critical`. See `build-workspace-context.mjs` for selection semantics.
-- `topic` — kebab-case slug matching the filename (after the type prefix, when one is present).
-- `author` — username scope owner. Required for `team-member/{user}/` files.
-- `updated` — ISO date of last meaningful edit. `/maintenance` flags stale `lifecycle: active` files based on this.
-
-**Index-feeding field:**
-
-- `description` — one-line summary, used verbatim by `workspace-context/index.md` and per-user team-member indexes. When omitted, the index falls back to the first sentence of the body, then the filename slug (with the `braindump_`/`handoff_`/`research_` prefix stripped). Adding a `description:` to a file with a weak fallback is the cheapest way to improve the index.
-
-**Optional confidence marker:**
-
-- `confidence` — `high` | `medium` | `low`. Apply to research, design, and exploration files where the conclusions might still shift. Skip on locked files (locked = high by definition) and on workflow artifacts like handoffs and braindumps. The frontmatter integrity check in `/maintenance` validates the value if present.
-
-**Example for a research file:**
-
-```yaml
----
-state: ephemeral
-lifecycle: active
-type: research
-topic: vector-search-evaluation
-description: Evaluation of FAISS for workspace-context — concluded NL index is sufficient at our scale.
-author: alex
-confidence: medium
-updated: 2026-04-25
----
-```
-
-## Workspace-Context Auto-Generated Files
-
-A single generator at `.claude/scripts/build-workspace-context.mjs` produces three artifacts in one pass:
-
-- `workspace-context/index.md` — navigation catalog of everything under `shared/` (locked files first, then the rest). Imported by the workspace-level `CLAUDE.md`.
-- `workspace-context/canonical.md` — verbatim concatenation of `shared/locked/*.md` so team truths are loaded into every session prompt. Also imported by `CLAUDE.md`.
-- `workspace-context/team-member/{user}/index.md` — per-user navigation catalog, one per team member. Imported by each user's gitignored `CLAUDE.local.md`.
-
-Gitignored files (e.g. anything matching `local-only-*`) are excluded automatically, and `workspace-context/.indexignore` adds path-prefix excludes for tracked files that shouldn't appear in the shared index (e.g. archived release notes).
-
-When `workspace-context/canonical.md` exceeds `workspace.canonicalBudgetBytes` (default 40960), the builder honors per-file `priority` and section-level `<!-- canonical:trim --> ... <!-- canonical:end-trim -->` markers to fit: `priority: reference` files are trimmed first, then stubbed, while `priority: critical` files are always included in full. `/maintenance` audits the budget and offers a triage flow when over.
-
-```bash
-node .claude/scripts/build-workspace-context.mjs --check --root .   # exits 1 if any artifact is stale or missing
-node .claude/scripts/build-workspace-context.mjs --write --root .   # regenerate all three
-```
-
-`/maintenance` checks staleness in audit mode and regenerates in cleanup mode. Hand edits to `index.md`, `canonical.md`, or any `team-member/{user}/index.md` are overwritten — update source files (or their `description:` frontmatter) instead.
-
-## What Belongs in Canonical
-
-Canonical content is loaded verbatim into every session prompt. It frames how Claude reads the rest of the conversation, so the bar for what goes in is narrower than the bar for `shared/` (root) or `team-member/{user}/`. The principle: canonical should describe what *is* and what *to do*, not what *to think*.
-
-**Belongs in canonical (`shared/locked/`):**
-
-- **Facts about the system** — current architecture, supported targets, naming conventions, where things live, what's published.
-- **Hard constraints** — "must work on Windows and macOS," "PRs only, no direct push to main," "this directory is gitignored." Constraints scope the solution space without prejudging which solution to pick.
-- **Process rules** — workflow discipline that applies regardless of the task. Branch protection, release cadence, mandatory review gates.
-- **Settled-rejection guardrails** — "we evaluated approach X, rejected because Y, do not propose this again." Saves Claude from spending tokens re-proposing already-evaluated options. The guardrail must include the *why*, so future-Claude can recognize when an edge case actually warrants revisiting the rejection.
-- **Meta-principles for debiasing** — explicit reminders to widen evaluation, like the dogfood-bias risk doc. Anti-shading by design.
-
-**Does NOT belong in canonical:**
-
-- **Opinions on open technical questions** — "library X is better than Y for this kind of problem," "approach A is preferred over B." These shape Claude's reasoning starting point so it begins from the conclusion rather than reasoning toward it. If the team has a strong preference, write it as a constraint ("use X, not Y") with the reason — or keep it in `shared/` (root) where it is reference material but not always-loaded.
-- **Conclusions Claude might be asked to question** — "we believe the architecture is correct," "feature Z is the right shape." If a topic is the subject of ongoing design work, locking a conclusion biases the discussion before it starts.
-- **Personal preferences** — what one contributor finds elegant or annoying. Belongs in `team-member/{user}/`.
-- **Status snapshots that age fast** — sprint-current priorities, "we're working on X this week." `project-status.md` is the bounded exception for high-level project status; finer-grained "what's in flight" lives in the tracker.
-
-**The test before promoting to canonical:**
-
-> 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 Claude toward a particular answer to a question that hasn't been asked yet?
-
-(a) is canonical. (b) is `shared/` (root) at most, more often `team-member/{user}/`.
-
-The distinction matters because pre-loaded conclusions in always-loaded context don't read like opinions to Claude — they read like ground truth. A reference doc Claude *finds* during research is weighed against the question; a canonical doc loaded before the question is asked frames what Claude considers in the first place. `/release` and `/promote` should apply this test before locking content.

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

@@ -1,90 +0,0 @@
-# Work Item Tracking
-
-When a workspace has an issue tracker configured, all work items — bugs, features, chores — live in that tracker. Skills and scripts read and write the tracker through the adapter at `.claude/scripts/trackers/{type}.mjs`. There is no local file that mirrors the tracker's state.
-
-## Why external-first
-
-- **Atomic assignment.** Two teammates can't accidentally start the same ticket — the tracker is the source of truth for "who has this."
-- **Real-time state.** Status changes propagate to the whole team the moment they happen, not after a commit + push.
-- **Tool parity.** Humans and Claude see the same list of tickets in the same place.
-
-## Configuration
-
-`workspace.json` → `workspace.tracker`:
-
-```json
-{
-  "workspace": {
-    "tracker": {
-      "type": "github-issues",
-      "repo": "your-org/your-workspace"
-    }
-  }
-}
-```
-
-- `type` — identifies the adapter module at `.claude/scripts/trackers/{type}.mjs`. Only `github-issues` ships in the template; others are additive.
-- `repo` — adapter-specific. For `github-issues`, the owner/name slug of the repo where issues live. `"auto"` resolves to the workspace's own git remote.
-
-Absence of `workspace.tracker` means tracking is disabled. Skills handle this by falling back to a blank/describe-the-work flow — they do not fabricate a local mirror.
-
-## Adapter interface (for Claude)
-
-Import from `.claude/scripts/trackers/interface.mjs`:
-
-```javascript
-import { createTracker, AlreadyAssignedError } from '.claude/scripts/trackers/interface.mjs';
-
-const tracker = createTracker(workspace.tracker);
-
-const mine = await tracker.listAssignedToMe();        // Issue[]
-const open = await tracker.listUnassigned();          // Issue[]
-const issue = await tracker.claim('gh:42');           // throws AlreadyAssignedError on contention
-const created = await tracker.createIssue({ title, body, labels: ['feat', 'P2'], milestone: 'Backlog' });
-await tracker.comment('gh:42', 'paused here; see branch X');
-await tracker.closeIssue('gh:42', { comment: 'shipped in PR #99' });
-
-// Setup-time: idempotent milestone / label creation
-await tracker.ensureLabels();                          // creates bug/feat/chore/P1/P2/P3 if absent
-await tracker.ensureMilestone({ title: 'Backlog', description: 'Triage later' });
-```
-
-All skills that touch work items use this interface. Adapters are not called directly.
-
-## Session linkage
-
-When `/start-work` links a session to a tracker issue, the session tracker's frontmatter gets:
-
-```yaml
-workItem: gh:42
-```
-
-The value is the adapter-prefixed issue ID. This survives adapter swaps — replacing the GitHub adapter with a Linear adapter later doesn't require re-linking session trackers (though the prefix changes for *new* sessions).
-
-## When to create issues
-
-- **User describes new work during `/start-work`** → skill calls `createIssue` after session creation.
-- **Bug or feature discovered mid-session** → Claude proactively asks "Create an issue for this? [Y/n]"; if yes, calls `createIssue` and links the session (if it's scoped to this session) or leaves it unassigned (if it's a future concern).
-- **Never during braindumps or handoffs** — those are discussion artifacts, not work items. Action items can later graduate to issues during `/start-work`.
-
-## When NOT to maintain local state
-
-- Do not create, write to, or read `workspace-context/open-work.md`. That file is deprecated.
-- Do not write ticket state into `session.md` frontmatter beyond the `workItem:` pointer. Status, assignment, milestone, and labels live in the tracker.
-- Do not cache issue bodies locally. Always fetch via `tracker.getIssue(id)` when the content is needed.
-
-## Skill behavior
-
-Skills that interact with the tracker:
-
-- **`/setup-tracker`** — configures `workspace.json` → `tracker` block, calls `ensureLabels()`.
-- **`/start-work`** — fetches assigned-to-me first; falls back to unassigned; claims atomically on pick. Records `workItem:` in session tracker.
-- **`/pause-work`** — comments the pause capture on the linked issue.
-- **`/complete-work`** — closes the linked issue after PRs merge, with a final comment linking them.
-- **`/workspace-init`** — prompts to run `/setup-tracker` at the end of init. Does not pre-populate tickets.
-
-## What this rule does NOT do
-
-- Does not prescribe a specific tracker type. Adapter choice is per workspace.
-- Does not prescribe label or milestone schemas beyond the six standard labels (`bug`, `feat`, `chore`, `P1`, `P2`, `P3`) created by `ensureLabels()`. Teams with existing trackers can skip label creation during setup.
-- Does not replace tracker-native features (comments, reactions, linked PRs) — use the tracker's UI for those.

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

@@ -1,137 +0,0 @@
-# Workspace Structure
-
-This workspace follows the claude-workspace convention. All paths are relative to the workspace root.
-
-## Directory Layout
-
-| Directory | Purpose | Tracked in git? |
-|-----------|---------|-----------------|
-| `repos/` | Source clones of project repositories (one per repo, stays on default branch) | No (gitignored, lazy) |
-| `work-sessions/` | Per-session folders — one folder per active or paused work session | No (gitignored entirely at the launcher) |
-| `work-sessions/{name}/workspace/` | Workspace worktree for this session, on the session branch | Yes — on the session branch, not on main |
-| `work-sessions/{name}/workspace/session.md` | Unified session tracker at the top of the session branch (frontmatter = machine state, body = human content) | Yes — on the session branch |
-| `work-sessions/{name}/workspace/design-*.md` | Specs for this session — consumed into release notes by /complete-work | Yes — on the session branch |
-| `work-sessions/{name}/workspace/plan-*.md` | Plans for this session — consumed into release notes by /complete-work | Yes — on the session branch |
-| `work-sessions/{name}/workspace/goal-*.md` | Goal artifacts for /goal-driven multi-phase work — consumed into release notes by /complete-work | Yes — on the session branch |
-| `work-sessions/{name}/workspace/research-*.md` | Phase-output research artifacts produced by goal-driven sessions — consumed into release notes by /complete-work | Yes — on the session branch |
-| `work-sessions/{name}/workspace/crossref-*.md` | Phase-output crossref artifacts produced by goal-driven sessions — consumed into release notes by /complete-work | Yes — on the session branch |
-| `work-sessions/{name}/workspace/repos/` | Real directory holding nested project worktrees for this session | No (gitignored) |
-| `work-sessions/{name}/workspace/repos/{repo}/` | Project worktree nested inside the workspace worktree | No (gitignored) |
-| `workspace-context/` | Team knowledge and per-user context | Yes |
-| `workspace-context/shared/` | Team-visible content — handoffs, braindumps, research, references | Yes |
-| `workspace-context/shared/locked/` | Canonical team truths — auto-concatenated into `canonical.md` and loaded into every session | Yes |
-| `workspace-context/team-member/{user}/` | Per-user working context — default destination for personal captures | Yes |
-| `workspace-context/index.md` | Auto-generated navigation catalog of `shared/` (locked first, then ephemerals) | Yes |
-| `workspace-context/canonical.md` | Auto-generated verbatim concatenation of `shared/locked/*.md` | Yes |
-| `workspace-context/team-member/{user}/index.md` | Auto-generated per-user navigation catalog | Yes |
-| `workspace-context/.indexignore` | Path prefixes to exclude from `index.md` (e.g., archived release notes) | Yes |
-| `workspace-context/release-notes/` | Per-branch release-note artifacts — `unreleased/` and `archive/` | Yes |
-| `workspace-scratchpad/` | Disposable workspace-scoped files — session log, hook debug output | No (gitignored, lazy) |
-| `CLAUDE.md` | Workspace launcher prompt — imports `canonical.md` and `index.md` | Yes |
-| `CLAUDE.local.md` | Per-user prompt — imports `team-member/{user}/index.md` | No (gitignored) |
-| `.claude/` | Claude Code configuration — rules, agents, skills, hooks, scripts, lib | Yes (except settings.local.json) |
-
-Session content (tracker, specs, plans) lives at the top of each session's workspace worktree. It is tracked on the session branch, not on main. Pushing the session branch carries durable session thinking across machines. When `/complete-work` finalizes the session, it synthesizes the content into release notes and removes the files from the branch before the final PR so main's top level stays free of session artifacts.
-
-## Workspace-Context Levels
-
-Three layers, in increasing trust order:
-
-| Level | Path | What lives there | How it gets there |
-|-------|------|-----------------|--------------------|
-| Personal | `team-member/{user}/` | Per-user braindumps, handoffs, research notes | Default destination for `/braindump`, `/handoff`, `/aside` |
-| Shared | `shared/` (root) | Team-visible ephemerals — cross-team handoffs, post-release leftovers, references | Explicit choice via `--scope shared` or `/promote` |
-| Canonical | `shared/locked/` | Promoted truths — naming conventions, post-release discipline, project status | Promoted by `/release` (or `/promote` with explicit locked target) |
-
-Canonical content is verbatim-loaded into every session via `CLAUDE.md` → `@workspace-context/canonical.md`. Personal content is loaded only for the active user via the gitignored `CLAUDE.local.md`.
-
-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.**
-
-- Specs: `design-{topic}.md` at the top of `work-sessions/{session-name}/workspace/`
-- Plans: `plan-{topic}.md` at the top of `work-sessions/{session-name}/workspace/`
-- Goals: `goal-{topic}.md` at the top of `work-sessions/{session-name}/workspace/`, with goal-native phase outputs as `research-{topic}.md` and `crossref-{topic}.md` siblings. See `goal-driven-work.md` for the schema and when to reach for `/goal`.
-
-From inside the worktree, these are plain top-level files (`design-{topic}.md`, `plan-{topic}.md`, `goal-{topic}.md`) sitting alongside `CLAUDE.md` and `workspace.json`. They are tracked on the session branch and travel with the branch on `git push`.
-
-This overrides any default paths specified by external skills (e.g., Superpowers brainstorming defaults to `docs/superpowers/specs/`). Those skills state that user preferences override their defaults — this rule IS that override. Do not create `docs/superpowers/` directories. Do not write specs, plans, or goal artifacts anywhere other than the top of the active worktree.
-
-If a spec/plan/goal already exists for the current session, version it: `design-{topic}-v2.md`, `design-{topic}-v3.md`.
-
-`/complete-work` reads specs, plans, and goal artifacts (including `research-*.md` and `crossref-*.md` phase outputs) from the worktree to synthesize release notes, then removes them in a dedicated commit before the final PR so main's tree stays pristine.
-
-## File Naming Conventions
-
-- Session folders: `work-sessions/{session-name}/`
-- Workspace worktrees: `work-sessions/{session-name}/workspace/`
-- Project worktrees: `work-sessions/{session-name}/workspace/repos/{repo-name}/`
-- Session trackers: `work-sessions/{session-name}/workspace/session.md`
-- Specs: `design-{topic}.md` (top of worktree)
-- Plans: `plan-{topic}.md` (top of worktree)
-- Goals: `goal-{topic}.md` (top of worktree)
-- Goal-native research outputs: `research-{topic}.md` (top of worktree)
-- Goal-native crossref outputs: `crossref-{topic}.md` (top of worktree)
-
-For ephemeral content under `shared/` and `team-member/{user}/`, the filename prefix signals the type:
-
-| Skill | Filename prefix |
-|-------|-----------------|
-| `/braindump` | `braindump_{topic}.md` |
-| `/handoff` | `handoff_{topic}.md` |
-| `/aside` (full mode, dispatches researcher) | `research_{topic}.md` |
-| `/aside --quick` | `braindump_{topic}.md` (with `variant: aside` in frontmatter) |
-| `/promote` | preserves source prefix |
-| `/release` | strips prefix when locking — `shared/locked/` files use bare names since location signals the type |
-
-Local-only personal drafts get an additional `local-only-` prefix (e.g., `local-only-braindump_x.md`) which keeps them gitignored until promoted.
-
-## Rules
-
-- The workspace root stays on main — it is the launcher, not the workspace.
-- All real work happens in workspace worktrees at `work-sessions/{name}/workspace/`.
-- Session content (tracker, specs, plans) is written from inside the worktree and committed on the session branch. Writes from the launcher cannot reach files that live inside a worktree's git-path space.
-- Source clones at `repos/{repo-name}/` stay on their default branch — never checkout a feature branch there.
-- `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`).

package/template/.claude/scripts/cleanup-work-session.mjs

@@ -1,247 +0,0 @@
-#!/usr/bin/env node
-// Tear down a work session's worktrees, branches, and folder.
-//
-// Teardown order is MANDATORY:
-//   1. Remove each project worktree from its project repo
-//   2. Remove the workspace worktree from the workspace repo
-//   3. Prune each project repo (belt-and-suspenders)
-//   4. Delete all local branches
-//   5. Remove the whole work-sessions/{name}/ folder
-//
-// Workspace-first removal silently deletes the nested project worktrees'
-// .git files and leaves orphan worktree records in the project repos.
-// The safe order keeps both sides of the relationship in sync.
-//
-// State discovery is defensive: the session tracker (session.md) may have
-// been stripped by /complete-work Step 7 before this script runs, leaving
-// no `repos:` or `branch:` to read. When that happens we discover repos
-// from the work-sessions/{name}/workspace/repos/ directory listing and the
-// branch from `git branch --show-current` on the workspace worktree —
-// BEFORE removing anything. Without that, the per-repo loops silently
-// no-op and the script reports success while leaving orphans behind
-// (gh:119).
-//
-// `success: true` means VERIFIED: every project worktree record is gone
-// (no prunable entries left over), every local branch is deleted, and the
-// session folder is removed. The script post-verifies all of these and
-// surfaces any leftover state as an error rather than swallowing it.
-import '../lib/require-node.mjs';
-import { execSync } from 'child_process';
-import { existsSync, readdirSync, statSync } from 'fs';
-import { join } from 'path';
-import {
-  getWorkspaceRoot,
-  readSessionTracker,
-  deleteSessionFolder,
-  sessionFolderPath,
-  normalizeRepos,
-} from '../hooks/_utils.mjs';
-
-const args = process.argv.slice(2);
-const getArg = (name) => {
-  const idx = args.indexOf(`--${name}`);
-  return idx >= 0 && args[idx + 1] ? args[idx + 1] : null;
-};
-
-const sessionName = getArg('session-name');
-if (!sessionName) {
-  console.error('Usage: cleanup-work-session.mjs --session-name NAME');
-  process.exit(1);
-}
-
-const root = getWorkspaceRoot(import.meta.url);
-const reposDir = join(root, 'repos');
-const sessionFolder = sessionFolderPath(root, sessionName);
-const wsWorktree = join(sessionFolder, 'workspace');
-
-const removed = [];
-const skipped = [];
-const errors = [];
-
-// === Discovery: where session.md is silent or missing, fall back to disk ===
-//
-// The tracker may have been stripped before this script runs. Read whatever
-// is still there, then fill gaps from the live worktree state.
-
-const tracker = readSessionTracker(root, sessionName);
-let repos = normalizeRepos(tracker?.repos);
-let branch = tracker?.branch || null;
-
-// If repos is empty, discover from work-sessions/{name}/workspace/repos/.
-// That directory is the workspace worktree's nested-project-worktrees dir;
-// each entry is one project repo this session checked out.
-if (repos.length === 0) {
-  const nestedReposDir = join(wsWorktree, 'repos');
-  if (existsSync(nestedReposDir)) {
-    try {
-      const discovered = readdirSync(nestedReposDir).filter((entry) => {
-        try {
-          return statSync(join(nestedReposDir, entry)).isDirectory();
-        } catch {
-          return false;
-        }
-      });
-      if (discovered.length > 0) {
-        repos = discovered;
-        skipped.push({
-          step: 'discovery',
-          reason: `Tracker missing repos; discovered ${discovered.length} from ${nestedReposDir}: ${discovered.join(', ')}`,
-        });
-      }
-    } catch (err) {
-      skipped.push({ step: 'discovery', reason: `Failed to list ${nestedReposDir}: ${err.message}` });
-    }
-  }
-}
-
-// If branch is missing, ask the workspace worktree itself.
-if (!branch && existsSync(wsWorktree)) {
-  try {
-    branch = execSync('git rev-parse --abbrev-ref HEAD', { cwd: wsWorktree, stdio: 'pipe', encoding: 'utf-8' }).trim();
-    if (branch) {
-      skipped.push({ step: 'discovery', reason: `Tracker missing branch; discovered from worktree: ${branch}` });
-    }
-  } catch (err) {
-    skipped.push({ step: 'discovery', reason: `Failed to read branch from ${wsWorktree}: ${err.message}` });
-  }
-}
-
-// === Step 1: Remove each project worktree FIRST, from its project repo ===
-for (const repo of repos) {
-  const projWorktree = join(wsWorktree, 'repos', repo);
-  const repoDir = join(reposDir, repo);
-  if (!existsSync(projWorktree)) {
-    skipped.push({ step: 'remove-project-worktree', repo, reason: `${projWorktree} does not exist` });
-    continue;
-  }
-  if (!existsSync(repoDir)) {
-    errors.push(`Cannot remove ${repo} worktree: source clone missing at ${repoDir}`);
-    continue;
-  }
-  try {
-    execSync(`git worktree remove "${projWorktree}" --force`, { cwd: repoDir, stdio: 'pipe' });
-    removed.push(`project worktree ${repo}`);
-  } catch (err) {
-    errors.push(`Failed to remove ${repo} worktree: ${err.message.trim()}`);
-  }
-}
-
-// === Step 2: Remove the workspace worktree AFTER project worktrees are gone ===
-if (existsSync(wsWorktree)) {
-  try {
-    execSync(`git worktree remove "${wsWorktree}" --force`, { cwd: root, stdio: 'pipe' });
-    removed.push('workspace worktree');
-  } catch (err) {
-    errors.push(`Failed to remove workspace worktree: ${err.message.trim()}`);
-  }
-} else {
-  skipped.push({ step: 'remove-workspace-worktree', reason: `${wsWorktree} does not exist` });
-}
-
-// === Step 3: Prune each project repo to mop up orphans ===
-for (const repo of repos) {
-  const repoDir = join(reposDir, repo);
-  if (!existsSync(repoDir)) continue;
-  try {
-    execSync('git worktree prune', { cwd: repoDir, stdio: 'pipe' });
-  } catch (err) {
-    // Prune is a safety net, but if it fails on a repo we touched, surface
-    // it — verification below will catch leftover orphans either way.
-    errors.push(`Prune failed in ${repo}: ${err.message.trim()}`);
-  }
-}
-
-// === Step 4: Delete local branches ===
-if (branch) {
-  for (const repo of repos) {
-    const repoDir = join(reposDir, repo);
-    if (!existsSync(repoDir)) continue;
-    try {
-      execSync(`git branch --list "${branch}"`, { cwd: repoDir, stdio: 'pipe', encoding: 'utf-8' });
-    } catch {
-      continue; // Repo broken; verification will catch downstream impact.
-    }
-    const exists = execSync(`git branch --list "${branch}"`, { cwd: repoDir, encoding: 'utf-8' }).trim();
-    if (!exists) continue; // Already gone (e.g., gh pr merge --delete-branch did it).
-    try {
-      execSync(`git branch -D "${branch}"`, { cwd: repoDir, stdio: 'pipe' });
-    } catch (err) {
-      errors.push(`Failed to delete branch ${branch} in ${repo}: ${err.message.trim()}`);
-    }
-  }
-  // Same for the workspace repo (root).
-  try {
-    const exists = execSync(`git branch --list "${branch}"`, { cwd: root, encoding: 'utf-8' }).trim();
-    if (exists) {
-      try {
-        execSync(`git branch -D "${branch}"`, { cwd: root, stdio: 'pipe' });
-      } catch (err) {
-        errors.push(`Failed to delete branch ${branch} in workspace repo: ${err.message.trim()}`);
-      }
-    }
-  } catch {
-    // workspace root not a git repo — unusual, skip.
-  }
-}
-
-// === Step 5: Delete the whole work-sessions/{name}/ folder ===
-try {
-  deleteSessionFolder(root, sessionName);
-} catch (err) {
-  errors.push(`Failed to delete session folder ${sessionFolder}: ${err.message.trim()}`);
-}
-
-// === Post-verification: success means VERIFIED, not "no try/catch threw" ===
-//
-// Without these checks, an empty repos list (the gh:119 root cause) lets
-// every silent skip add up to a "success" output while leaving orphans
-// behind. The verification turns silent skips into honest errors.
-
-if (existsSync(sessionFolder)) {
-  errors.push(`Session folder still present after cleanup: ${sessionFolder}`);
-}
-
-const wsPath = wsWorktree; // canonical path the worktree had
-for (const repo of repos) {
-  const repoDir = join(reposDir, repo);
-  if (!existsSync(repoDir)) continue;
-  let wtList = '';
-  try {
-    wtList = execSync('git worktree list --porcelain', { cwd: repoDir, encoding: 'utf-8' });
-  } catch (err) {
-    errors.push(`Could not list worktrees in ${repo}: ${err.message.trim()}`);
-    continue;
-  }
-  if (wtList.includes('prunable')) {
-    errors.push(`Prunable worktree record remains in ${repo} after cleanup (gh:119 symptom)`);
-  }
-  if (wtList.includes(wsPath)) {
-    errors.push(`${repo} still has a worktree record referencing the session path`);
-  }
-  if (branch) {
-    const branchStill = execSync(`git branch --list "${branch}"`, { cwd: repoDir, encoding: 'utf-8' }).trim();
-    if (branchStill) {
-      errors.push(`Branch ${branch} still present in ${repo} after cleanup`);
-    }
-  }
-}
-
-if (branch) {
-  try {
-    const branchStill = execSync(`git branch --list "${branch}"`, { cwd: root, encoding: 'utf-8' }).trim();
-    if (branchStill) {
-      errors.push(`Branch ${branch} still present in workspace repo after cleanup`);
-    }
-  } catch {
-    // not a git repo — already noted
-  }
-}
-
-console.log(JSON.stringify({
-  success: errors.length === 0,
-  removed,
-  skipped: skipped.length > 0 ? skipped : undefined,
-  errors: errors.length > 0 ? errors : undefined,
-}));
-
-if (errors.length > 0) process.exit(1);