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

package/template/.claude/skills/handoff/SKILL.md

@@ -11,7 +11,7 @@ Save structured workstream state to workspace-context. Usable anytime, any numbe
 - `/handoff {name}` — create or update a named handoff
 - `/handoff` (no param) — analyze session and suggest name(s)
 
-## Session-Aware Behavior
+## Lifecycle-Aware Behavior
 
 When called within an active work session (the active-session pointer at `.claude/.active-session.json` exists inside the current worktree):
 
@@ -26,9 +26,16 @@ When called within an active work session (the active-session pointer at `.claud
   git commit -m "handoff: update {session-name} tracker"
   ```
 
-When called from the workspace root (no active session):
-- Only `local-only-*` files are writable from the root
-- Suggest starting a work session first, or use the helper with `--local-only`
+Under the task model — `workspace.sessionModel` is `"task"` in `workspace.json` AND the SessionStart hook injected a `Chat record:` line (`{chat}` is its name):
+
+- Default behavior: write `handoff_{topic}.md` directly into that chat's drawer at `workspace-scratchpad/chats/{chat}/` — the drawer sits outside `workspace-context/`, so `capture-context.mjs` is not involved
+- No commit for drawer writes: the drawer is gitignored and machine-local; `/complete-work` lists it and asks what to promote into `workspace-context/`
+
+When called from the workspace root with no active session — every other case, including a `sessionModel: "session"` workspace (the `Chat record:` line is injected in every chat, so it alone does not select the drawer):
+
+- Use `--local-only` so the captured file is gitignored (the root only allows local-only writes), landing in `team-member/{user}/`
+- If the task model applies but the `Chat record:` line is absent, say the drawer destination is unavailable for that reason
+- Suggest starting work (`/start-work`) first if the handoff is about actionable work
 
 The flows below apply when NOT in an active work session, or when the user explicitly asks for a standalone handoff file.
 

package/template/.claude/skills/maintenance/SKILL.md

@@ -44,6 +44,10 @@ For each workspace-context `.md` file and each `work-sessions/*/workspace/sessio
 - Worktrees whose branch has already been merged? (cleanup candidates)
 - Workspace repo on expected branch?
 - Orphan worktree records in project repos — run `git -C repos/{repo} worktree list` for each repo and flag any `prunable` markers. These usually come from a workspace-first teardown (the unsafe order) leaving stale admin records behind. Suggest `git worktree prune` on the affected repo.
+- Task-model state (gh:146), three checks:
+  - **Unrecorded task worktrees** — list `repos/*/.claude/worktrees/*` and `.claude/worktrees/*`, read each candidate's branch (`git -C "{path}" rev-parse --abbrev-ref HEAD`), and keep only those on a task-prefixed branch (`feature/`, `bugfix/`, `chore/`) — Claude Code's own worktrees carry other branch names, so the prefix filter skips them without guessing a name convention. Cross-reference the chat records (`node .claude/scripts/chat-record.mjs --root . --list`): a task-prefixed worktree no record entry claims is *unrecorded* — it may be a legitimate no-tracker task (those are never recorded), so present it and ask before suggesting `node .claude/scripts/task-worktree.mjs --root . --remove --repo "{repo}" --branch "{branch}"`.
+  - **Stale record entries** — a record task entry whose worktree is gone (neither `repos/{repo}/.claude/worktrees/{slug}/` nor, for `repo: "."`, `.claude/worktrees/{slug}/` exists). Suggest `node .claude/scripts/chat-record.mjs --root . --remove-task --chat "{chat}" --work-item "{workItem}" --repo "{repo}"` (omit `--repo` when the entry has none).
+  - **Merged but never completed** — a recorded task branch that already merged. Judge merged-ness by the forge's merged PRs for that repo, matching on head branch — never `git branch --merged`, which a squash merge (never an ancestor) silently misses. `/complete-work` never ran. Suggest running `/complete-work` for that branch (detection from the chat record finds it).
 
 ### 5. Workspace-context auto-file integrity
 
@@ -126,6 +130,9 @@ When stale candidates are found, surface them as warnings in the output format a
 - Ephemeral files not updated in 7+ days — suggest resolve, update, or archive
 - `work-sessions/{name}/` folders whose worktrees are gone — suggest cleanup
 - Session trackers whose branches have been merged — suggest `/complete-work` post-flight cleanup
+- Unrecorded task-prefixed worktrees (no chat-record entry claims them; may be no-tracker tasks) — ask, then suggest `task-worktree.mjs --remove`
+- Chat-record task entries whose worktree is gone — suggest `chat-record.mjs --remove-task`
+- Recorded task branches already merged (per the forge's merged PRs, not `git branch --merged`) — suggest `/complete-work`
 - Braindumps that overlap significantly — suggest merging (e.g., "workspace-branching.md and persistent-work-sessions.md cover the same topic")
 - Handoffs referencing deleted branches — suggest resolve or remove
 

package/template/.claude/skills/migrate-sessions/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: migrate-sessions
+description: Migrate this workspace from the session lifecycle to the task lifecycle — inventory old work sessions, decide each one with the operator, finish or archive them, and switch workspace.json to the task model. Runs only inside the current workspace; never deletes anything.
+---
+
+# Migrate Sessions
+
+Drain a workspace's accumulated session entries and switch new work to the task lifecycle. The script is `.claude/scripts/migrate-sessions.mjs`; this skill is the operator procedure around it.
+
+**Scope rule, before anything else: this skill acts only on the workspace it is run in.** Never read, inventory, or act on any other workspace or directory — even if asked to "do them all." Each workspace runs its own migration from its own root, by its own operator, on its own schedule.
+
+**Run from the launcher root only** — the workspace root itself, never a session folder or any other worktree. The script refuses a linked-worktree `--root` on its own (one exception, the Switch step below), and it refuses to back up or archive the session that hosts the current chat, so there is no way to drain the session you are sitting in from inside it.
+
+## 1. Inventory
+
+```bash
+node .claude/scripts/migrate-sessions.mjs --inventory
+```
+
+Read-only. Present the stderr table plus each session's proposal with its reasons and warnings. Say plainly that the proposals are proposals — evidence and a starting point, not decisions. Pay particular attention to the per-remote state shown per worktree (`same`, `ahead +N`, `behind -N`, `diverged +N/-M`, `not-fetched`, `unknown`) and to `unbacked` warnings: they change what Finish and Archive mean for that session. Entries shown as `foreign` (symlinked) are never acted on — surface them for manual reconciliation.
+
+## 2. Decide per session, with the operator — one at a time
+
+For each session, lay out its evidence and ask the operator which way to go. Never infer the decision from the proposal. The options:
+
+- **Finish** (typical for MERGEABLE) — resume the session with `/start-work`, then run `/complete-work`; its own merge confirmation applies there. But if the inventory shows a **diverged** remote for that session, say so *before* the operator chooses Finish: `/complete-work`'s plain push will be rejected, and pushing the rewritten history needs `--force-with-lease` — which you run only on the operator's explicit yes naming the branch. Never force silently.
+- **Archive** (typical for ABANDONED, a broken shell, or a MERGEABLE the operator gives up on) — take it out of the active lifecycle without destroying anything. Two steps, each its own decision:
+  1. **Offer a backup.** Archiving keeps everything on this machine; a backup adds an off-machine copy of the session's commits, and it is what makes a later deletion safe. It creates `drain/{session}/…` tags and pushes them to the resolved remote(s) — tags may land in a public repository, so show the plan first: `node .claude/scripts/migrate-sessions.mjs --backup --session {name} --dry-run` (add `--remote <name>` to aim somewhere other than the resolved default). It lists, per tip, the tag, the remote, and which tips a remote branch or tag already holds exactly, with no side effects. On the operator's yes, run it without `--dry-run` and show the tags it created. Declining is fine — the archive still keeps everything locally. A repo with no remote at all is refused by backup; say so.
+  2. **Archive after an explicit yes naming the session:** `node .claude/scripts/migrate-sessions.mjs --archive --session {name}`. The whole session folder moves to `{sessions}/.archived/{name}--{timestamp}/` and git's worktree links are repaired to follow it — every commit, uncommitted edit, untracked or ignored file, and embedded repository comes along. If the move or the repair fails, the session is put back and the result says whether every link was verified. The session's branches stay checked out in the archived worktrees, so a new task cannot reuse those branch names until the archive is deleted. The archive refuses, touching nothing, when a directory in the folder cannot be read, when the folder holds a worktree of a repository outside this workspace, or when it holds a submodule checkout (its link cannot be repaired) — surface the reason; for a submodule the options are Finish or Keep. Relay any `warnings` (relative symlinks that pointed outside the session no longer resolve after the move).
+- **Keep** (typical for ACTIVE, and the only sane answer for UNKNOWN) — leave it; it completes later under the session lifecycle.
+
+Unbacked commits (present on no remote) are safe in an archive — they are only ever at risk when someone deletes one. Say so when you archive such a session, and offer the backup.
+
+## 3. Switch — never write the launcher's tracked `workspace.json` directly
+
+The switch procedure:
+
+1. Create a workspace task worktree for the change:
+   ```bash
+   node .claude/scripts/task-worktree.mjs --root . --create --repo . --branch chore/enable-task-model
+   ```
+2. Run the switch against that worktree (the one mode that accepts a linked-worktree root — it only edits `workspace.json`):
+   ```bash
+   node .claude/scripts/migrate-sessions.mjs --enable-task-model --root .claude/worktrees/chore-enable-task-model
+   ```
+3. Commit there, open a PR through the workspace's normal flow, and pull the launcher after merge. The launcher root never commits to its default branch.
+
+The switch output reports `remainingSessions: null` when run from the worktree — the real remaining-sessions list comes from a separate `--inventory` at the launcher root. Remaining sessions are fine either way: they keep resuming and completing under the session lifecycle after the switch.
+
+## 4. Verify
+
+Re-run `--inventory` at the launcher root and report what remains and why — kept sessions, anything the operator deferred, foreign entries, or an empty list.
+
+## 5. Afterwards
+
+The first new piece of work starts with `/start-work` under the task lifecycle.
+
+## Deleting an archive — the operator's call, never this skill's
+
+Archives are meant to be kept until the operator has looked at them. When the operator asks to delete one, first show them — for the whole archive, not just its top level — everything that deletion would destroy, per worktree (list them with `git -C {repo} worktree list --porcelain` in the workspace repo and each `repos/{name}`, filtered to paths under the archive):
+
+- commits no remote holds: `git -C {worktree} log --oneline --branches --not --remotes` and whether a `drain/*` tag covers the tip;
+- uncommitted, untracked and ignored files: `git -C {worktree} status --porcelain --ignored`;
+- edits hidden from status: `git -C {worktree} ls-files -v` — any lowercase tag (assume-unchanged) or `S` (skip-worktree) whose file differs from the index;
+- per-worktree refs that die with the worktree: `git -C {worktree} for-each-ref refs/worktree refs/bisect`;
+- an operation in progress: `MERGE_HEAD`, `rebase-merge`, `rebase-apply` under `git -C {worktree} rev-parse --git-dir`;
+- embedded repositories (any `.git` directory under the archive) and their unpushed branches;
+- files in the archive outside the worktrees (e.g. beside `workspace/`).
+
+Only on their explicit yes naming the archive: remove the worktrees deepest-first (`git -C {repo} worktree remove --force {path}`), delete each branch they confirm (`git -C {repo} branch -D {branch}`), then delete the archive folder. Nothing in this workspace does this automatically.

package/template/.claude/skills/pause-work/SKILL.md

@@ -28,7 +28,15 @@ This is a coherent rewrite of the Progress section, not an append (coherent-revi
 
 ### Step 3: Update frontmatter status and post pause comment on tracker
 
-Use the session-frontmatter helper to set `status: paused` in the tracker's frontmatter.
+Set `status: paused` in the tracker's frontmatter. `.claude/lib/session-frontmatter.mjs` is
+a library, not a CLI — running it with flags does nothing and exits 2:
+
+```bash
+node --input-type=module -e '
+import { updateSessionFile } from "./.claude/lib/session-frontmatter.mjs";
+updateSessionFile("session.md", { status: "paused" });
+'
+```
 
 If the session tracker has a `workItem:` field AND `workspace.tracker` is configured, post a pause comment on the linked issue via the adapter:
 

package/template/.claude/skills/release/SKILL.md

@@ -1,151 +1,87 @@
 ---
 name: release
-description: Prepend a new CHANGELOG.md entry per project repo by synthesizing unreleased branch notes. Deletes consumed branch notes and synthesizes workspace-context into canonical (locked) entries. Use at release time.
+description: Cut a versioned release of one project repo — bump the version, merge it through a PR, tag it, and publish a forge release whose notes are generated from merged PRs. No release-notes files.
 ---
 
 # Release
 
-Synthesize unreleased branch notes (in the **workspace** repo) into a concise, user-facing entry at the top of each project repo's `CHANGELOG.md`. Delete the consumed branch notes from the workspace. Bump the project repo's `package.json` version. In parallel, promote resolved workspace-context into canonical (locked) team knowledge.
+Cut a versioned release of one project repo. The version bump travels through a PR like any other change; the tag marks the merge commit; the forge generates the release notes from merged PR titles. The workspace keeps no release-notes files of its own.
 
 ## Why this shape
 
-Branch notes are detailed dogfood-retrospective artifacts that should not bloat public project repos. By keeping them in the workspace repo until release time, the project repo stays lean — it only ever sees code commits and `CHANGELOG.md` entries. A single `CHANGELOG.md` with one concise entry per version is what users of a published package actually want. Branch notes remain the input format for `/complete-work` (they capture per-session detail at the right moment), but they live in the workspace and are consumed-then-deleted by `/release`.
-
-Versions are bumped here, not in `/complete-work`, because version semantics describe what shipped — accumulated changes since the last release — not the timing of any individual feature merge.
+Release notes come from the forge. GitHub's generated notes (merged PR titles) are what users of a published release actually read; the detail behind each PR already lives in the issue and the PR body, so duplicating it into workspace files buys nothing. Projects that use changesets, semantic-release, or their own release tooling simply don't use this skill. A repo's `CHANGELOG.md`, if it has one, is historical — this skill never writes it.
 
 ## Parameters
-- `/release {version}` — create a release entry for a specific version
+
+- `/release {version}` — release a specific version
 - `/release` — ask for the version
 
 ## Flow
 
 **Step 1: Determine version and repo**
-If no version parameter: ask "What version is this release? (e.g., 1.2.0)"
-
-Check `workspace.json` for `releaseMode`:
-- **per-repo** (default): ask which repo to release
-- **workspace**: process all repos together
-- **ask**: "Process all repos together or individually?"
 
-**Release-notes base directory.** Read `workspace.releaseNotesDir` from `workspace.json` (default `workspace-context/release-notes` if the field is absent). Throughout this skill `{releaseNotesDir}` refers to that resolved value; every branch-note path is `{releaseNotesDir}/unreleased/{repo}/…`. Never use a bare `release-notes/`.
+Ask which repo to release — read `repos` from `workspace.json` and default to the entry with `"primary": true`. If no version was given, ask the bump kind (patch/minor/major) after showing the merged PRs since the last tag, so the operator can judge the impact:
 
-**Step 2: Read unreleased notes**
-Branch notes live in the **workspace** repo, written there by `/complete-work`. For each target repo, list the workspace's unreleased subdirectory for that project:
 ```bash
-ls {releaseNotesDir}/unreleased/{repo}/
+git -C repos/{repo} describe --tags --abbrev=0
 ```
-Read all `branch-release-notes-*.md` and `branch-release-questions-*.md` files.
 
-If no unreleased files exist for a target repo: "No unreleased notes found for {repo}. Nothing to release."
+Then call the forge adapter's `prList` with a merged-after search bounded by that tag's date (e.g. `merged:>{date}`). Pre-v1.0 breaking changes are a minor bump.
 
-The frontmatter `repo:` field on each branch-notes file confirms which project repo the notes belong to — match that to the directory name as a sanity check. Notes mismatched on `repo:` are a sign of manual file moves; surface to the user.
+**Step 2: Preflight the tag**
 
-**Step 3: Group and organize**
-Group notes by `type:` frontmatter (feature, fix, chore). Within each group, order chronologically by date. This ordering drives bullet sequence in the synthesized entry.
+If `v{version}` already exists on origin, stop and ask — reuse it, investigate with `forge.releaseView`, or pick another version. Never force-push a tag.
 
-**Step 4: Handle questions**
-Present all open questions from `branch-release-questions-*.md` files:
-"These questions are still open from development. For each one:"
-- **Answer** — provide the answer, remove from questions
-- **Defer** — keep as a "Known issues" sub-bullet in the CHANGELOG entry
-- **Discard** — no longer relevant
+```bash
+git -C repos/{repo} ls-remote --exit-code origin refs/tags/v{version}
+```
 
-**Step 5: Synthesize the CHANGELOG entry**
+**Step 3: Bump on a branch**
 
-Read the current `repos/{repo}/CHANGELOG.md` (if it exists) so the new entry matches the existing voice and structure. If no CHANGELOG exists, create one with a short header explaining that entries are written for package users, not contributors.
+Create a task worktree for the release branch:
 
-Prepend a new section at the top of the changelog body (after the header, before any existing version entries). Write it user-facing — what shipped, not how it shipped:
+```bash
+node .claude/scripts/task-worktree.mjs --root . --create --repo "{repo}" --branch "release/v{version}"
+```
 
-```markdown
-## v{version} — {YYYY-MM-DD}
+If the repo has a `package.json` with a `version`, set it to `{version}` (edit the JSON; keep formatting) and update `package-lock.json`'s top-level version fields if that file is present. Commit `chore: release v{version}`. If the repo has no version file, skip the commit — step 5 tags the current default-branch head instead.
 
-- {Concise bullet per meaningful change. Features, fixes, and chores interleaved
-  by significance, not by category. Each bullet is one sentence or short paragraph
-  in plain user-facing language: "the CLI now supports X", "corrected Y behavior
-  on Z", not "we decided" or "the team merged." Deduplicate related items.
-  Write from scratch per the coherent-revisions rule.}
+**Step 4: Merge**
 
-### Known issues
-- {Deferred questions from Step 4, if any. Omit this subsection when empty.}
-```
+Push the branch and open a PR through the forge adapter — per-repo `createForge({ ...ws.workspace?.forge, repo: '{owner}/{name}' })` with head `release/v{version}`. Ask `Merge? [Y/n]`, then merge (squash, delete branch).
 
-The entry stays short. If a change needs more detail, reference the repo's docs or a dedicated design doc — do not inline session-level retrospection into the public changelog.
+**Step 5: Tag and publish**
 
-**Step 6: Delete consumed branch notes from the workspace**
-```bash
-rm {releaseNotesDir}/unreleased/{repo}/branch-release-*
-# If the directory is now empty, remove it too:
-rmdir {releaseNotesDir}/unreleased/{repo} 2>/dev/null || true
-```
-The branch notes were an intermediate capture; their content is now in the CHANGELOG entry and their raw form in git history. They do not survive into the project repo.
+Pull the merge, tag it, push the tag, and publish the forge release:
 
-**Step 7: Commit the CHANGELOG entry to the project repo**
 ```bash
-cd repos/{repo}
-git add CHANGELOG.md
-git commit -m "docs: v{version} changelog entry"
+git -C repos/{repo} pull --ff-only
+git -C repos/{repo} tag v{version}
+git -C repos/{repo} push origin v{version}
 ```
-This commit lands on the project repo's source clone (which stays on its default branch). The user pushes it when ready — `/release` does not push automatically.
 
-**Step 7b: Bump package.json version (project repo)**
-If the project repo has a `package.json` with a `version` field, update it to match the release version:
-```bash
-cd repos/{repo}
-# Update "version": "..." in package.json to the release version
-git add package.json
-git commit -m "chore: bump version to v{version}"
+```js
+await forge.releaseCreate({ tag: 'v{version}', repo, generateNotes: true });
 ```
-Skip this step if the repo has no package.json or no version field.
 
-**Step 7c: Commit the consumed-notes deletion in the workspace**
+If the repo has `.github/workflows/publish.yml`, find and watch its run with `workflowRunFind` / `workflowRunWatch` — retry the find up to 5 times with 3 s backoff (the run may not be registered the moment the tag lands). A failed run is reported to the operator, not thrown.
+
+**Step 6: Tear down and report**
+
+Remove the release worktree:
+
 ```bash
-# From the workspace root
-git add {releaseNotesDir}/unreleased/
-git commit -m "release: consume {repo} branch notes for v{version}"
+node .claude/scripts/task-worktree.mjs --root . --remove --repo "{repo}" --branch "release/v{version}" --delete-branch
 ```
-Workspace and project repos have separate commits — they are separate git histories.
-
-**Step 8: Consume project-scoped specs**
-Project-scoped specs and plans in `workspace-context/team-member/{user}/` (ongoing) that are fully covered by this release:
-- Consume into the CHANGELOG entry (their content is now captured there)
-- Remove the source files
-- If partially covered: rewrite the spec to reflect only what remains unimplemented
-
-**Step 9: Synthesize workspace-context for canonical promotion**
-Process ephemeral workspace-context entries:
-
-1. List all ephemeral entries with `lifecycle: resolved` (across `shared/` and any `team-member/{user}/`).
-2. For each, determine:
-   - Does an existing locked entry cover this topic? → Merge into it (enrich)
-   - Are there related resolved entries? → Combine into a new locked entry
-   - Is it stale/fully consumed by release notes? → Archive or delete
-   - Is it unresolvable but still valuable? → Move to `team-member/{user}/` ongoing or keep at `shared/` root ephemeral
-3. For merged/new locked entries:
-   - Set `state: locked`, `type: synthesized` (or `type: reference` for clean truths)
-   - Write to `workspace-context/shared/locked/{bare-name}.md` — locked files use bare names (location signals the type), so strip any `braindump_/handoff_/research_` prefix when promoting
-   - Write concise, focused content — team truths, not session history
-4. Regenerate auto-files so `canonical.md` and `index.md` reflect the new locked content:
-   ```bash
-   node .claude/scripts/build-workspace-context.mjs --write --root .
-   ```
-5. Commit:
-   ```bash
-   git add workspace-context/
-   git commit -m "release: synthesize workspace-context for v{version}"
-   ```
-
-**Step 10: Report**
-"Release v{version} complete for {repo}. {N} branch notes consumed into CHANGELOG.md. {M} context entries synthesized into {K} locked entries."
+
+Report the PR, the tag, the release URL, and the publish status.
+
+**Step 7: Update workspace release state**
+
+If the workspace keeps release state in `workspace-context/` (for example a current-release line in a status file under `shared/locked/`), offer to update it — through a workspace task worktree and PR, never on the launcher.
 
 ## Notes
 
-- Release entries live in `CHANGELOG.md` at the project repo root — one file, one concise entry per version. No `release-notes/v*.md`, no `release-notes/archive/`.
-- Branch notes live in the WORKSPACE at `{releaseNotesDir}/unreleased/{repo}/` (resolved from `workspace.json` → `workspace.releaseNotesDir`, default `workspace-context/release-notes`). `/complete-work` writes them; `/release` consumes and deletes them. They never reach project repos.
-- Versions are bumped here, not in `/complete-work`. This keeps the version semantics aligned with what actually shipped (accumulated changes since last release).
-- The public repo stays lean. Detailed per-branch retrospection exists in workspace git history (the consumed-notes commit) but is not surfaced as standalone files in either repo.
-- Context synthesis happens in the WORKSPACE repo — Step 7c (consumed-notes) and Step 9 (workspace-context synthesis) are separate workspace commits.
-- Per-repo is the default — each project repo has its own release cadence.
-- The coherent-revisions rule applies: write the CHANGELOG entry from scratch, don't concatenate branch notes.
-- Tagging happens in `/complete-work`, not here. When the session branch starts with `release/`, `/complete-work` tags the merge commit on the project repo's default branch and pushes the tag, which triggers `.github/workflows/publish.yml` to publish to npm. `/release` produces the synthesis (CHANGELOG entry + version bump + consumed-notes deletion); `/complete-work` does the push, PR, merge, and tag.
-- Do not run `npm publish` locally. The publish workflow is the only path that exercises OIDC trusted publishing — local publish requires 2FA OTP and bypasses that. If the workflow fails, investigate via `gh run view`; do not fall back to local publish.
-- Recovery from a failed publish. Transient failure: rerun via `gh run rerun {run_id}`. Content failure: delete the tag (`git push origin --delete v{version} && git tag -d v{version}`), then redo the release in a new release session — `/start-work`, then `/release v{version}`, then `/complete-work`. Once a version is published to npm, that version is committed on the registry; bump and start a new release.
+- Never run `npm publish` locally. The publish workflow is the only path that exercises OIDC trusted publishing; a local publish requires a 2FA OTP and bypasses it. If the workflow fails, investigate via `gh run view` — do not fall back to a local publish.
+- Recovery from a failed publish: transient failures rerun via `gh run rerun {run_id}`; content failures mean deleting the tag and redoing the release. Once a version is published to a registry, that version number is committed — bump and release a new version instead.
+- Pre-v1.0 breaking changes are a minor bump, not major.

package/template/.claude/skills/start-work/SKILL.md

@@ -5,6 +5,8 @@ description: Begin or resume a work session. Creates a self-contained work-sessi
 
 # Start Work
 
+Two lifecycles share this skill. `workspace.sessionModel` in `workspace.json` selects for new work: `"task"` routes new work to **Flow: Task** (session model v2 — no session folder, no `session.md`); absent or `"session"` keeps the existing flows below, unchanged. Resuming an existing `work-sessions/` session always uses the existing Resume flow regardless of the setting.
+
 Begin or resume a persistent work session. Each session lives in its own `work-sessions/{name}/` folder containing one workspace worktree, nested project worktrees, and a unified `session.md` tracker. Sessions can run in parallel from separate terminals.
 
 ## Parameters
@@ -13,6 +15,55 @@ Begin or resume a persistent work session. Each session lives in its own `work-s
 - `/start-work handoff` — list shared context to resume from
 - `/start-work all` — list active sessions across all users (for shared debugging or multi-user workspaces)
 
+## Flow: Task (session model v2)
+
+New work as a task: one tracker issue, one branch, one worktree per repo the work touches. This flow creates no `work-sessions/` folder, no `session.md`, and seeds no task list — the issue, the branch, and the chat record are the entire state. The chat stays at the workspace root — `{launcher-root}`, the absolute path on the `Workspace root:` line the SessionStart hook injects (at /start-work time you are normally already there); the worktrees are reached by path.
+
+If `workspace.tracker` is absent, say tracking is off and skip step 1 — but still ask for the type (`bug` / `feat` / `chore`) and a one-line description, because the type picks the branch prefix — then continue with steps 2–6. Tell the user plainly what that costs: without a tracker there is no `workItem`, the task is not recorded on the chat record, and `/complete-work` cannot find it from the launcher. It is completed either by running `/complete-work` from inside the worktree (cwd detection) or by opening the PR by hand.
+
+1. **Identify or create the tracker issue and claim it** — the same adapter calls as Flow: Blank steps 3–6:
+
+   ```javascript
+   import { createTracker } from './.claude/scripts/trackers/interface.mjs';
+   import { readFileSync } from 'node:fs';
+   const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
+   const tracker = createTracker(ws.workspace.tracker);
+   const assigned = await tracker.listAssignedToMe();
+   const candidates = assigned.length > 0 ? assigned : await tracker.listUnassigned();
+   ```
+
+   Present the list as Flow: Blank step 4 does. When the pick came from the unassigned fallback, claim it atomically and re-fetch on `ALREADY_ASSIGNED` exactly as Blank step 5 shows; for "something new", create and self-assign per Blank step 6:
+
+   ```javascript
+   const newIssue = await tracker.createIssue({
+     title: description,
+     body: `Created at /start-work by ${user}.`,
+     labels: [type, priority],
+     milestone: milestone || null,
+   });
+   await tracker.claim(newIssue.id);
+   ```
+
+   Remember `workItem: {issue.id}`.
+
+2. **Pick repo(s)** — the same numbered multi-select as Blank step 7 (e.g. `1,3` or `all`), defaulting to the repo marked `"primary": true` under `repos` in `workspace.json`, falling back to the first entry when none is marked. The list also offers the **workspace repo itself**, shown as `workspace (this repo)` and addressed as `.`. Include it when the task changes anything tracked in the workspace repo — `workspace-context/`, the workspace's own `.claude/` (rules, hooks, scripts, skills), or, in a dogfood workspace, mirrors of template changes. Steps 4 and 5 take `.` like any other repo name (`--repo "."`).
+
+3. **Propose the branch** — `{prefix}/{slug}` with the prefix from type (`feature/`, `bugfix/`, `chore/`), per the branch-naming step in Flow: Blank.
+
+4. **Create one worktree per repo the work touches:**
+   ```bash
+   node .claude/scripts/task-worktree.mjs --root . --create --repo "{repo}" --branch "{branch}"
+   ```
+   The script fetches origin best-effort (offline is fine) before choosing the base. A project repo's worktree lands at `repos/{repo}/.claude/worktrees/{slug}/` — Claude Code's native worktree location — based on `origin/{defaultBranch}` when that ref exists, and never tracking it. For `.` the worktree lands at `.claude/worktrees/{slug}/` — the same native location, one level up — based on the workspace origin's HEAD (falling back to `main`); the workspace's own `.gitignore` already covers the path.
+
+5. **Record the task on this chat's record** (only when a `workItem` exists — see the no-tracker note above):
+   ```bash
+   node .claude/scripts/chat-record.mjs --root . --add-task --chat "{chat}" --work-item "{workItem}" --branch "{branch}" --repo "{repo}"
+   ```
+   `{chat}` is the name from the `Chat record:` line the SessionStart hook injected into this conversation. If there is no such line, say so and skip recording rather than guessing a name.
+
+6. **Tell the user where the work happens:** the worktree path(s) above — edits belong there, not in the source clones at `repos/{repo}/`. Work continues from this chat by path. A chat started inside a **project** worktree would not load the workspace's conventions or hooks (a worktree is a context boundary), so staying here is the default. A `.` worktree does load a copy of the workspace's `CLAUDE.md`/`.claude/` — but with the worktree as root, so its chat records land in the worktree's own scratchpad rather than the launcher's; the task still belongs to this chat.
+
 ## Flow: No Parameter
 
 1. Read the current user from `.claude/settings.local.json` → `workspace.user`. If unset, behave as `/start-work all` (no user filter). If the user invoked `/start-work all`, also skip filtering.
@@ -40,7 +91,7 @@ Begin or resume a persistent work session. Each session lives in its own `work-s
    - Workspace: `work-sessions/{name}/workspace/`
    - For each repo in `repos:` frontmatter: `work-sessions/{name}/workspace/repos/{repo}/`
    - If any are missing, recreate from the branch
-3. The session-start hook automatically registers each chat in the session tracker's `chatSessions` frontmatter when Claude opens in a worktree. Verify the current chat is registered — if not (e.g., the hook didn't fire), add an entry manually via the session-frontmatter helper.
+3. The session-start hook automatically registers each chat in the session tracker's `chatSessions` frontmatter when Claude opens in a worktree. Verify the current chat is registered — if not (e.g., the hook didn't fire), append an entry using the invocation shown under "Create work session" below (the helper is an importable library, not a CLI).
 
    Each `chatSessions` entry has this shape:
    ```yaml
@@ -55,7 +106,7 @@ Begin or resume a persistent work session. Each session lives in its own `work-s
 4. Update the tracker `status:` to `active` if it was `paused`
 5. Restore the task list from `## Tasks` per the `task-list-mirroring` rule:
    ```bash
-   cd work-sessions/{name}/workspace
+   cd "work-sessions/{name}/workspace"
    node .claude/scripts/sync-tasks.mjs --read session.md
    ```
    Pass the parsed `todos` array to `TodoWrite` so the live UI matches the durable state. If the section is missing (legacy session predating this feature), seed it first via `--write` with an empty `todos` array — the helper will insert the bookends.
@@ -165,9 +216,40 @@ The script creates:
 - Active-session pointer at `work-sessions/{session-name}/workspace/.claude/.active-session.json`
 - Copies `settings.local.json` into the worktree if it exists at the workspace root
 
-If a `workItem:` was set in step 5 or 6, write it into the tracker's frontmatter via the session-frontmatter helper after creation. This is what `/pause-work` and `/complete-work` use to locate the linked issue.
+If a `workItem:` was set in step 5 or 6, write it into the tracker's frontmatter after
+creation. `/pause-work` and `/complete-work` both use this to locate the linked issue, and
+a session created without it looks fine until one of them silently cannot find the ticket.
+
+`.claude/lib/session-frontmatter.mjs` is a **library, not a CLI** — running it with flags
+does nothing and exits 2. Import it:
+
+```bash
+cd "work-sessions/{session-name}/workspace"
+node --input-type=module -e '
+import { updateSessionFile, readSessionFields } from "./.claude/lib/session-frontmatter.mjs";
+updateSessionFile("session.md", { workItem: "{workItem}" });
+console.log("workItem =", readSessionFields("session.md").workItem);
+'
+```
+
+Read the value back, as above, and confirm it before moving on — this write has failed
+silently before (gh:143).
+
+Register this chat in the tracker's `chatSessions` frontmatter. For new sessions, the session-start hook has already fired (before /start-work was invoked) but the session folder didn't exist yet. Find the current chat's UUID from the most recently modified `.jsonl` file in
+`~/.claude/projects/{project-path}/` and append the entry with the same library:
+
+```bash
+node --input-type=module -e '
+import { updateSessionFile, readSessionFields } from "./.claude/lib/session-frontmatter.mjs";
+const existing = readSessionFields("session.md").chatSessions || [];
+updateSessionFile("session.md", {
+  chatSessions: [...existing, { id: "{uuid}", names: [], started: new Date().toISOString(), ended: null }],
+});
+'
+```
 
-Register this chat in the tracker's `chatSessions` frontmatter. For new sessions, the session-start hook has already fired (before /start-work was invoked) but the session folder didn't exist yet. Find the current chat's UUID from the most recently modified `.jsonl` file in `~/.claude/projects/{project-path}/` and add the entry manually via the session-frontmatter helper. Subsequent chats on this session will be registered automatically by the hook.
+Append — never replace: the list is the session'"'"'s whole chat history. Subsequent chats are
+registered automatically by the hook.
 
 The tracker already reflects the correct state — assignment happened in step 5 or 6 via `adapter.claim()`. Do not write to any local file mirror. There is no `open-work.md`.
 
@@ -177,7 +259,7 @@ After session creation, seed the `## Tasks` section in the new tracker so `TodoW
 
 ```bash
 # Build the seed from inside the worktree so the helper resolves workspace.json correctly.
-cd work-sessions/{session-name}/workspace
+cd "work-sessions/{session-name}/workspace"
 echo '{"todos": []}' | node .claude/scripts/sync-tasks.mjs --write session.md
 ```
 
@@ -199,7 +281,7 @@ The auto-commit at the end of "Capture prior conversation context" picks up the
 
 ### Capture prior conversation context
 
-If brainstorming, spec writing, or design discussion happened in this conversation before `/start-work` was called, that reasoning needs to be captured into the session tracker body. Otherwise it will be lost when the conversation ends and `/complete-work` will produce thin release notes.
+If brainstorming, spec writing, or design discussion happened in this conversation before `/start-work` was called, that reasoning needs to be captured into the session tracker body. Otherwise it will be lost when the conversation ends and `/complete-work` will write a thin PR body.
 
 Check: has the current conversation included substantive discussion (design decisions, requirements exploration, approach selection) before this point?
 
@@ -208,7 +290,7 @@ If yes:
 2. Write the summary into `work-sessions/{session-name}/workspace/session.md`'s body, in a `## Pre-session context` or `## Progress` section
 3. Auto-commit from inside the worktree so the capture lands on the session branch:
    ```bash
-   cd work-sessions/{session-name}/workspace
+   cd "work-sessions/{session-name}/workspace"
    git add session.md
    git commit -m "chore: capture pre-session discussion for {session-name}"
    ```

package/template/.claude/skills/workspace-init/SKILL.md

@@ -56,6 +56,8 @@ For each repo in `workspace.json`:
 - If confirmed: `git clone {remote} repos/{name}`
 - If exists: report "repos/{name} already present"
 
+While workspace.json is open, confirm the work lifecycle. `workspace.sessionModel` selects where `/start-work` routes new work: `"task"` (one tracker issue + one branch + one worktree per touched repo; recommended for new workspaces) or `"session"` (self-contained `work-sessions/{name}/` folders; the template default — keep it for teams already mid-flight on sessions). Ask: "Which lifecycle should new work use — task (recommended for a new workspace) or session (default)?" and write the answer to `workspace.sessionModel` only if it differs from the current value. Never flip an existing non-default value silently.
+
 ### Step 3: Identify documentation sources
 
 Ask the user:
@@ -447,6 +449,6 @@ This session is done. Start a fresh Claude Code session and run /start-work to b
 - Documentation sources are first-class — always ask, always confirm access, always report failures
 - Chat history scanning uses a manifest to survive auto-compaction
 - Existing worktrees are formalized with session markers, trackers, and linked chat history
-- **Subdirectory launch:** Once initialized, `claude` can be launched from `work-sessions/{name}/workspace/repos/{repo}/` instead of the workspace root. Claude walks up the filesystem loading every `CLAUDE.md` it finds, so starting from inside a project worktree loads both the per-repo conventions and the workspace conventions automatically. This is useful for repo-focused tasks — no configuration change needed, just a different launch point.
+- **Launch point:** Launch `claude` from the workspace root. A worktree is a context boundary — `CLAUDE.md` discovery stops at its root and gitignored content is absent — so a chat started inside a project worktree (a session's `work-sessions/{name}/workspace/repos/{repo}/` or a task's `repos/{repo}/.claude/worktrees/{slug}/`) loads only that repo's own `CLAUDE.md`, without the workspace conventions or hooks. That is occasionally what you want for isolated, repo-only work; for normal work, stay at the root and reach worktrees by path.
 - **Skills are on-demand, not pre-loaded:** Skills are invoked explicitly by name (`/skill-name`) when needed; they are not loaded at session start. The `.skip` mechanism in `.claude/rules/` provides the analogous progressive-disclosure pattern for rules — a `.md.skip` file is present but inactive; rename it to `.md` to activate, rename it back to deactivate. Step 6 of this skill walks through the activation choices.
 - **`scope:` for path-scoped skills:** The `scope:` frontmatter field (shown as a commented-out example at the top of this file) restricts a skill so it activates only when the working directory is inside the declared path. Removing the `#` prefix from the example line turns this skill into a path-scoped skill — useful when you want a repo-specific skill available only from inside that repo's worktree.

package/template/.claude/skills/workspace-update/SKILL.md

@@ -119,6 +119,10 @@ git commit -m "chore: update workspace from template v{fromVersion} to v{toVersi
 
 Report: "Workspace updated to v{toVersion}. Restart Claude Code if rules or hooks changed."
 
+### Step 8: Session-model migration nudge
+
+After the update is applied, if the sessions directory (`workspace.workSessionsDir`, default `work-sessions/`) has entries and `workspace.sessionModel` is not `"task"`, append one line to the report: "This workspace still has {N} session(s) under the session model — `/migrate-sessions` can inventory and drain them and switch to the task model whenever you're ready." Suggest only; the operator decides whether and when.
+
 ## Notes
 
 - The CLI (`npx @ulysses-ai/create-workspace --upgrade`) stages the payload. This skill processes it.

package/template/CLAUDE.md.tmpl

@@ -8,6 +8,7 @@ This is a claude-workspace. All conventions are defined in .claude/rules/.
 - Each session is a self-contained folder at `work-sessions/{name}/` containing the worktree, nested project worktrees, and the session tracker
 - From root: only `local-only-*` and `workspace-scratchpad/` are writable
 - Team knowledge lives in `workspace-context/`
+- Run `/rename` to label this chat before `/clear` — keeps the chat findable in your CLI history after the context is wiped
 
 ## Workspace Config
 @workspace.json
@@ -25,11 +26,27 @@ This is a claude-workspace. All conventions are defined in .claude/rules/.
 - `/braindump [name]` — capture discussion/reasoning
 - `/aside [--quick] <thought>` — capture a drive-by idea without interrupting current work
 - `/pause-work` — suspend work, push, draft PR
-- `/complete-work` — finalize branch, release notes, real PR
+- `/complete-work` — finalize the work — rebase, PR, merge, close the issue
 - `/promote` — move personal memory to shared context
-- `/release [version]` — combine unreleased notes into versioned doc
+- `/release [version]` — cut a versioned release: bump, tag, forge release with generated notes
 - `/sync-work` — push branches without ceremony
 - `/workspace-update` — apply template updates (runs maintenance before/after)
 - `/setup-tracker` — wire this workspace to an issue tracker (GitHub Issues shipped; others pluggable)
 - `/maintenance [audit|cleanup]` — workspace health checks and cleanup
 - `/build-docs-site` — build a comprehensive Docusaurus documentation site for a project
+
+## Compact Instructions
+
+When auto-compacting context, preserve in the summary:
+- Decisions made in this session and their rationale
+- Constraints and conventions established or confirmed
+- Active task list state and the next concrete step
+- File paths touched and the nature of the change
+- Errors hit and what was tried
+
+Drop from the summary:
+- Verbose tool output already reflected in committed code
+- Exploratory reads that did not lead to a change
+- Conversational asides
+
+Files in `workspace-context/`, the session tracker (`session.md`) or chat drawer (`workspace-scratchpad/chats/{chat}/`), and any `design-*.md`/`plan-*.md` survive compaction — they're on disk. Re-read them on demand instead of trying to keep their contents in summary.

package/template/_gitignore

@@ -17,6 +17,10 @@ workspace-scratchpad/
 .claude/.active-session.json
 CLAUDE.local.md
 
+# Worktrees of the workspace repo itself — task worktrees (repo ".") and
+# Claude Code's native worktrees both live under .claude/worktrees/
+.claude/worktrees/
+
 # Local-only convention — machine-local state, any depth
 local-only-*
 
@@ -26,3 +30,8 @@ local-only-*
 # OS
 .DS_Store
 Thumbs.db
+
+# Per-user workspace-context indexes are generated per machine and read only
+# through CLAUDE.local.md, which is itself gitignored — no mechanism reads
+# another user's index. Regenerated by build-workspace-context.mjs on demand.
+workspace-context/team-member/*/index.md