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

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

@@ -1,56 +1,56 @@
 # 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.
+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
+## 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 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 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
+- 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
+## 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:
+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 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.
+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 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."
+This stops the cycle of trying broken variations when reading the docs would take one turn.
 
-## Verify, Don't Assume
+## 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.
+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.
 
-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.
+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.
 
-**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?"
+**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.
 
-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.
+Use judgment — don't over-verify the trivial.
 
-**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
 
-## 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
+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
 
-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.
+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

@@ -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,137 +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.
 
 ## 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.
+- **`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 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.
+Both are 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.
+**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 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.
+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 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.
+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.
 
-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.
+## Launching Claude inside a worktree
 
-This is purely a launch-point choice; no workspace configuration changes are needed to enable it.
+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
 
-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`).
+**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.