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

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

@@ -1,109 +1,62 @@
-# Memory Guidance
+# Memory and Placement Guidance
 
-Guide Claude's auto-memory system for this workspace.
+Where durable content goes, and what each destination costs.
 
-## What to Auto-Remember
+## Where durable content goes
 
-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
+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.
 
-## What NOT to Auto-Remember
+| 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** |
 
-- Temporary debugging state
-- File contents (re-read them instead)
-- Anything already captured in a workspace-context file
-- Anything documented in .claude/rules/
+**`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.
 
-## Session-Scoped vs Cross-Session
+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.
 
-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.
+**Before writing to either bold row, state the cost:**
 
 ```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
+node .claude/scripts/context-footprint.mjs --root . --add <bytes> --as <destination>
 ```
 
-`/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*.
+## The canonical test
 
-**Belongs in canonical (`shared/locked/`):**
+Canonical describes what *is* and what *to do*, never what *to think*.
 
-- **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.
+> 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?
 
-**Does NOT belong in canonical:**
+(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.
 
-- **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.
+## Auto-memory specifically
 
-**The test before promoting to canonical:**
+Save: architecture decisions and their rationale, patterns that caused bugs, user
+corrections about project conventions, external URLs and API quirks, tooling workarounds.
 
-> 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?
+Don't save: temporary debugging state, file contents (re-read them), anything already in a
+workspace-context file or a rule.
 
-(a) is canonical. (b) is `shared/` (root) at most, more often `team-member/{user}/`.
+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.
 
-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.
+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/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/rules/work-item-tracking.md

@@ -1,90 +1,48 @@
 # 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.
+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
 
-- **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.
+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`:
-
-```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.
+`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
 
-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).
+`/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
 
-- **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
+- **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`.
 
-Skills that interact with the tracker:
+## What not to do
 
-- **`/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.
+- 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.
 
-## What this rule does NOT do
+## Boundaries
 
-- 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.
+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

@@ -1,99 +1,79 @@
 # Workspace Structure
 
-This workspace follows the claude-workspace convention. All paths are relative to the workspace root.
+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
 
-| 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.
+| 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
 
-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`.
+|-------|------|------------------|-------------------|
+| 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) |
 
-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.
+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.
 
-## Spec and Plan Locations — MANDATORY OVERRIDE
+## Dynamic context loading (hooks)
 
-**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.**
+- **`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.
 
-- 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`.
+Both are Node.js scripts — cross-platform, no shell dependency.
 
-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`.
+## Spec and Plan Locations — MANDATORY OVERRIDE
 
-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.
+**Specs, plans, and goal artifacts MUST be written to the current lifecycle's work area, not to `docs/superpowers/` or any other location.**
 
-If a spec/plan/goal already exists for the current session, version it: `design-{topic}-v2.md`, `design-{topic}-v3.md`.
+- 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/`.
 
-`/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.
+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
 
-- 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:
+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 mode, dispatches researcher) | `research_{topic}.md` |
-| `/aside --quick` | `braindump_{topic}.md` (with `variant: aside` in frontmatter) |
+| `/aside` (full) / `--quick` | `research_{topic}.md` / `braindump_{topic}.md` (`variant: aside`) |
 | `/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.
+Local-only drafts add a `local-only-` prefix to stay 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.
+- 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.