@ulysses-ai/create-workspace 0.13.0-beta.0

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

@@ -0,0 +1,369 @@
+---
+name: complete-work
+description: Finalize a work session — rebase, synthesize release notes from spec/plan/session tracker/commits, create PRs with unified presentation. Handles all project repos and workspace repo. Use when work on a session is done.
+---
+
+# Complete Work
+
+Finalize the active work session. Handles all project repos (code changes, release notes, PRs) and the workspace repo (context processing, PR). Presents a unified summary with a single merge approval, then tears down the session folder.
+
+## Flow
+
+### Step 1: Detect context
+
+Read the active-session pointer from `.claude/.active-session.json` in the current worktree.
+If no active session: "No active work session. Nothing to complete."
+
+Read the full session tracker at `work-sessions/{session-name}/workspace/session.md` (use the frontmatter helper in `.claude/lib/session-frontmatter.mjs` — scripts and hooks use `_utils.mjs` which wraps it).
+
+Determine paths:
+- Session folder: `work-sessions/{session-name}/`
+- Workspace worktree: `work-sessions/{session-name}/workspace/`
+- Project worktrees: `work-sessions/{session-name}/workspace/repos/{repo}/` for each repo in the tracker's `repos:` list
+- Read each repo's default branch from workspace.json (`repos.{repo}.branch`)
+
+### Step 2: Rebase project repos
+
+For each repo in the tracker's `repos:`:
+```bash
+# {repo-branch} = repos.{repo}.branch from workspace.json
+cd work-sessions/{session-name}/workspace/repos/{repo}
+git fetch origin
+git rebase origin/{repo-branch}
+```
+If conflicts arise in any repo, STOP and present them to the user. Do not auto-resolve.
+
+### Step 3: Capture final discussion state
+
+Run `/braindump` to capture any final discussion/reasoning to the session tracker body.
+If the user declines or there's nothing to capture, skip.
+
+### Step 4: Gather source material
+
+Formally read ALL sources before synthesizing — do not write release notes from memory alone:
+
+1. **Session tracker** at `work-sessions/{session-name}/workspace/session.md` — read the full body (frontmatter is machine state, body is human content)
+
+2. **Session-scoped specs/plans** at the top of the session worktree:
+   - `work-sessions/{session-name}/workspace/design-*.md` files
+   - `work-sessions/{session-name}/workspace/plan-*.md` files
+   - Read each one fully
+
+3. **Handoffs** — any shared-context entries referencing this branch:
+   ```bash
+   grep -rl "branch: {branch}" shared-context/
+   ```
+   Read each matching file.
+
+4. **Branch commit logs** (per repo):
+   ```bash
+   # For each repo in the tracker's repos list:
+   cd work-sessions/{session-name}/workspace/repos/{repo}
+   git log origin/{repo-branch}..HEAD --oneline
+   ```
+
+### Step 5: Synthesize release notes
+
+For each repo in the tracker's `repos:` list that has commits beyond the base branch:
+
+```bash
+cd work-sessions/{session-name}/workspace/repos/{repo}
+COMMIT_ID=$(git rev-parse --short HEAD)
+mkdir -p release-notes/unreleased
+```
+
+**File 1: `release-notes/unreleased/branch-release-notes-{COMMIT_ID}.md`**
+```markdown
+---
+branch: {branch}
+type: {feature|fix|chore}
+author: {user}
+date: {YYYY-MM-DD}
+---
+
+## {Human-readable title}
+
+{Coherent narrative synthesized from tracker + spec + plan + commits.
+Written from scratch per coherent-revisions rule.}
+```
+
+**File 2: `release-notes/unreleased/branch-release-questions-{COMMIT_ID}.md`**
+```markdown
+---
+branch: {branch}
+author: {user}
+date: {YYYY-MM-DD}
+---
+
+## Open Questions
+
+{Only genuinely open questions — not things resolved during implementation.}
+```
+
+Commit per repo:
+```bash
+git add release-notes/unreleased/
+git commit -m "docs: add release notes for {branch}"
+```
+
+If a repo has no commits beyond the base, skip release notes for it.
+
+### Step 6: Consume session-scoped sources
+
+The entire `work-sessions/{session-name}/` folder is removed by the cleanup script in Step 11. Before that happens, make sure everything worth preserving has landed in release notes.
+
+No separate "consume spec and plan" commit is needed for the project repos — specs and plans now live in the session folder, not in the project worktrees. The project worktrees only carry source code changes.
+
+### Step 6c: Remove session artifacts from the workspace branch
+
+Session content (tracker, specs, plans) lives at the top of the workspace worktree on the session branch. Its purpose was synthesis into release notes in Step 5 — that work is now done. Remove the files from the branch before the final push so main's top level stays free of session artifacts:
+
+```bash
+cd work-sessions/{session-name}/workspace
+git rm -f session.md 2>/dev/null || true
+git rm -f design-*.md 2>/dev/null || true
+git rm -f plan-*.md 2>/dev/null || true
+git commit -m "chore: remove session artifacts before PR" 2>/dev/null || true
+```
+
+The `|| true` guards keep this idempotent — if a file is already gone (e.g., a session without specs), the step is a no-op. The commit is skipped when there's nothing staged.
+
+This commit persists in the branch's history. On squash merge or rebase merge, branch history collapses to one clean commit on main with no session artifacts. On merge commits, branch history is reachable but the final tree on main shows no session content.
+
+### Step 6b: Version bump (if applicable)
+
+For each repo in the tracker's `repos:`, check if the repo has versioning:
+```bash
+cd work-sessions/{session-name}/workspace/repos/{repo}
+cat package.json 2>/dev/null | grep '"version"'
+```
+
+If no `package.json` or no `version` field: skip this repo — no versioning to manage.
+
+If the repo has a version, determine the appropriate bump from the release notes just written:
+
+1. Read the `type:` field from the branch release notes created in Step 5
+2. Determine the bump:
+   - `type: fix` or `type: chore` → **patch** (auto-bump, no confirmation needed)
+   - `type: feature` → **minor** (present to user: "This session adds new functionality. Suggested bump: {current} → {next-minor}. Confirm or adjust?")
+   - Breaking changes detected (schema changes, removed APIs, convention changes) → **major** (present to user: "This session includes breaking changes. Suggested bump: {current} → {next-major}. Confirm or adjust?")
+
+3. Apply the bump:
+   ```bash
+   git add package.json
+   git commit -m "chore: bump version to {new-version}"
+   ```
+
+The user can override any suggestion. Accept their decision.
+
+### Step 7: Detect remote type per repo
+
+For each repo in the tracker's `repos:` plus the workspace repo, determine the remote type. This drives how Step 8 and Step 9 push and merge.
+
+```bash
+cd work-sessions/{session-name}/workspace/repos/{repo}
+git remote get-url origin 2>&1
+```
+
+Classify the result:
+
+- **GitHub remote** — URL contains `github.com` or `gh repo view` succeeds against origin → use the PR flow (Step 8a, Step 9a).
+- **Local / bare remote** — URL is a filesystem path (starts with `/`, `./`, `file://`, or points at a `.git` bare mirror) → use the local merge flow (Step 8b, Step 9b).
+- **Other remote** (e.g., GitLab, Bitbucket, self-hosted) — no `gh` support → fall back to the local merge flow (Step 8b, Step 9b), and mention it in the final summary.
+- **No remote at all** — "No remote configured for {repo}. Want me to create one on GitHub, add an existing URL, or keep the session local (push/merge inside the local clone only)?" Act on the user's choice. Never silently skip push.
+
+### Step 8: Push all repos
+
+#### Step 8a: GitHub remotes
+
+```bash
+# Each project repo with a GitHub remote
+cd work-sessions/{session-name}/workspace/repos/{repo}
+git push -u origin {branch}
+
+# Workspace repo — from the workspace worktree
+cd work-sessions/{session-name}/workspace
+git add .
+git commit -m "chore: finalize context for {session-name}"
+git push -u origin {branch}
+```
+
+#### Step 8b: Local/bare remotes
+
+```bash
+# Push the feature branch to the bare remote so it exists there
+cd work-sessions/{session-name}/workspace/repos/{repo}
+git push -u origin {branch}
+
+# Workspace repo — same commit + push pattern
+cd work-sessions/{session-name}/workspace
+git add .
+git commit -m "chore: finalize context for {session-name}"
+git push -u origin {branch}
+```
+
+The push shape is the same as 8a — what differs is the merge mechanics in Step 9b.
+
+### Step 9: Merge and present unified summary
+
+#### Step 9a: GitHub remotes — create PRs, unified summary, merge
+
+Create one PR per project repo plus one workspace PR:
+
+```bash
+# For each repo in the tracker's repos with a GitHub remote:
+cd work-sessions/{session-name}/workspace/repos/{repo}
+gh pr create --title "{type}: {description}" --body "..."
+
+# Workspace PR — from the workspace worktree
+cd work-sessions/{session-name}/workspace
+gh pr create --title "context: {session-name} work session" --body "..."
+```
+
+Present unified summary:
+```
+Work session complete:
+
+PROJECT: {repo-1}
+  PR #{n}: {type}: {description}
+  Branch: {branch} → {repo-1-branch}
+  Changes:
+    - {bullet points from release notes}
+  Release notes: branch-release-notes-{COMMIT_ID}.md
+
+PROJECT: {repo-2}
+  PR #{m}: {type}: {description}
+  Branch: {branch} → {repo-2-branch}
+  Changes:
+    - {bullet points from release notes}
+
+WORKSPACE: {workspace-name}
+  PR #{p}: context: {session-name} work session
+  Branch: {branch} → main
+
+Merge all? [Y/n]
+```
+
+If yes — merge all PRs atomically:
+```bash
+# For each project PR:
+gh pr merge {pr-number} --merge
+
+# Workspace PR:
+gh pr merge {workspace-pr-number} --merge
+
+# Pull all repos to their default branches
+# For each repo in the tracker's repos:
+cd repos/{repo} && git pull origin {repo-branch}
+cd {main-workspace-root} && git pull origin main
+```
+
+#### Step 9b: Local / bare / other remotes — local merge flow
+
+No PRs are created — these remotes don't have a PR concept (or we don't have a client wired up for them). Present an adjusted summary:
+
+```
+Work session complete:
+
+PROJECT: {repo-1}  (local remote)
+  Branch: {branch} → {repo-1-branch}
+  Changes:
+    - {bullet points from release notes}
+  Release notes: branch-release-notes-{COMMIT_ID}.md
+
+PROJECT: {repo-2}  (local remote)
+  Branch: {branch} → {repo-2-branch}
+  Changes:
+    - {bullet points from release notes}
+
+WORKSPACE: {workspace-name}  (local remote)
+  Branch: {branch} → main
+
+Merge all locally? [Y/n]
+```
+
+If yes — fast-forward merge on each remote, delete the feature branch, pull the source clone:
+```bash
+# For each repo in the tracker's repos with a local/bare remote:
+cd work-sessions/{session-name}/workspace/repos/{repo}
+git push origin HEAD:{repo-branch}        # fast-forward the default branch
+git push origin --delete {branch}         # remove the feature branch from the remote
+cd repos/{repo} && git checkout {repo-branch} && git pull origin {repo-branch}
+
+# Workspace repo — same pattern from the workspace worktree
+cd work-sessions/{session-name}/workspace
+git push origin HEAD:main
+git push origin --delete {branch}
+cd {main-workspace-root} && git pull origin main
+```
+
+If the fast-forward push fails because the remote's default branch has moved ahead, STOP and present the divergence — the user decides whether to rebase and retry or handle it another way. Do not auto-resolve.
+
+For repos with no remote at all (user chose "keep local"): skip push entirely. The branch lives only in the source clone after cleanup merges it:
+```bash
+cd repos/{repo} && git merge --ff-only {branch}
+```
+
+### Step 10: Close the linked issue on the tracker
+
+If the session tracker has a `workItem:` field AND `workspace.tracker` is configured, close the linked issue via the adapter after all PRs have merged:
+
+```javascript
+import { createTracker } from './.claude/scripts/trackers/interface.mjs';
+import { readFileSync } from 'node:fs';
+const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
+if (ws.workspace?.tracker) {
+  const tracker = createTracker(ws.workspace.tracker);
+  const comment = [
+    `**Completed by @${currentUser}**`,
+    '',
+    'Merged PRs:',
+    ...mergedPrs.map(p => `- ${p.repo}: ${p.url}`),
+    '',
+    releaseSummary, // 1-3 sentence synthesis of what shipped, drawn from release notes
+  ].join('\n');
+  await tracker.closeIssue(workItem, { comment });
+}
+```
+
+If `workItem:` is unset, skip the close — this was a blank session.
+
+If the close call fails (tracker unreachable, auth expired), report the error in the unified summary but do not block Step 11 cleanup. The issue can be closed manually via the GitHub UI; no data is at risk.
+
+### Step 11: Cleanup
+
+Run the cleanup helper script from the main workspace root:
+```bash
+node .claude/scripts/cleanup-work-session.mjs --session-name "{session-name}"
+```
+
+The script tears down in the **mandatory** order:
+1. Remove each nested project worktree from its project repo
+2. Remove the workspace worktree from the workspace repo
+3. `git worktree prune` on each project repo (belt-and-suspenders for orphan records)
+4. Delete local branches in all repos
+5. `rm -rf work-sessions/{session-name}/` — the tracker, specs, plans, and any local-only artifacts vanish. Their content was already archived into release notes in Step 5.
+
+Workspace-first removal silently deletes the nested project worktrees' `.git` files and leaves orphan worktree records in the project repos. The script enforces the safe order.
+
+Verify workspace root is still on main:
+```bash
+git branch --show-current  # should be "main"
+```
+
+## Handling Unformal Work Sessions
+
+If /complete-work is called but changes were made without a formal work session (no branch, changes on default branch):
+
+Ask: "These changes weren't part of a formal work session. What do you want to do?"
+- **Accept as work** — create a session retroactively, proceed with normal completion
+- **Stash for later** — create a user-scoped handoff describing what was done, stash the changes
+- **Hand off to someone** — create a team-visible handoff at root shared-context/ for another member to pick up
+- **Revert** — undo the changes (with confirmation)
+
+## Notes
+- Release notes live in the PROJECT repo worktrees — never the workspace
+- The session tracker's body is the primary source for release note synthesis — it captures the full session history alongside specs and plans
+- All repos get PRed and merged together — one approval for all
+- The teardown order is mandatory: project worktrees first, then workspace worktree, then prune, then delete the session folder
+- Context consumption, cleanup, and auto-committing release notes are intentional workflow behavior — these bypass normal commit conventions by design

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

@@ -0,0 +1,98 @@
+---
+name: handoff
+description: Save workstream state as shared context. Use anytime during work to capture progress, decisions, and next steps. Accepts optional name parameter.
+---
+
+# Handoff
+
+Save structured workstream state to shared context. Usable anytime, any number of times. User-scoped by default.
+
+## Parameters
+- `/handoff {name}` — create or update a named handoff
+- `/handoff` (no param) — analyze session and suggest name(s)
+
+## Session-Aware Behavior
+
+When called within an active work session (the active-session pointer at `.claude/.active-session.json` exists inside the current worktree):
+
+- Default behavior: update the session tracker body at `work-sessions/{session-name}/workspace/session.md`
+- Rewrite the tracker's `## Progress` section with current state (coherent-revisions rule)
+- Do NOT touch the frontmatter — it's machine state managed by hooks and scripts
+- Skip the naming and scoping questions — the tracker is already scoped to this session
+- Auto-commit from inside the worktree so the update lands on the session branch:
+  ```bash
+  cd work-sessions/{session-name}/workspace
+  git add session.md
+  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 create a `local-only-{name}.md` file
+
+The flows below apply when NOT in an active work session, or when the user explicitly asks for a standalone handoff file.
+
+## Flow: Named
+
+1. Read workspace user identity from `.claude/settings.local.json` (`workspace.user`)
+2. Check if handoff already exists in `shared-context/{user}/` or `shared-context/` root
+3. If exists: read it, prepare to update with current session state
+4. If new: prepare to create
+5. Ask: "Should this be user-scoped (default), team-visible, or local-only?"
+   - User-scoped (default): `shared-context/{user}/{name}.md`
+   - Team-visible: `shared-context/{name}.md`
+   - Local-only: `shared-context/local-only-{name}.md`
+6. Write the handoff file:
+
+```yaml
+---
+state: ephemeral
+lifecycle: active
+type: handoff
+topic: {name}
+branch: {current-branch-if-any}
+repo: {current-repo-if-any}
+author: {user}
+updated: {YYYY-MM-DD}
+---
+
+## Status
+{What was accomplished in this session}
+
+## Key Decisions
+{Important choices made and their rationale}
+
+## Next Steps
+- [ ] {Specific next actions}
+
+## Open Questions
+{Unresolved questions, if any}
+```
+
+7. Auto-commit the handoff file alone:
+   ```bash
+   git add shared-context/{path-to-file}
+   git commit -m "handoff: {name}"
+   ```
+
+## Flow: No Parameter
+
+1. Analyze the current session: what topics have been discussed?
+2. If one clear topic: suggest a name, ask to confirm
+3. If multiple topics are conflated: "I see work on {topic-1} and {topic-2}. Split into separate handoffs?"
+   - If yes: run the named flow for each topic
+   - If no: ask for a single name that covers both
+4. Proceed with the named flow for each handoff
+
+## Updating Existing Handoffs
+
+When updating an existing handoff, rewrite it as a fresh snapshot of current understanding (coherent-revisions rule). Don't append below the old content. The updated handoff should read as if written in one pass reflecting the current state.
+
+Update the `updated` date in frontmatter. Keep the `lifecycle` as-is unless the user indicates a change.
+
+## Notes
+- User-scoped is the default — root is only for content deliberately made team-visible
+- Handoffs are always committed individually — never bundled with code commits
+- One topic, one file — don't let handoffs become grab-bags
+- Name before writing — the name forces you to identify the single topic
+- Auto-committing context files without user request is a workflow artifact — this intentionally bypasses the "do not commit unless asked" convention, not the "committed individually" constraint above

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

@@ -0,0 +1,116 @@
+---
+name: maintenance
+description: Workspace maintenance — audit integrity, clean up stale context, suggest merges. Run periodically or before /release.
+---
+
+# Maintenance
+
+Keep the workspace healthy. Combines integrity auditing with active cleanup recommendations.
+
+## Parameters
+- `/maintenance` — full run (audit + cleanup)
+- `/maintenance audit` — integrity checks only (read-only)
+- `/maintenance cleanup` — stale context, suggested merges, reconciliation only
+
+## Audit
+
+Read-only integrity checks. Reports problems but never modifies files.
+
+### 1. Cross-reference consistency
+Scan all shared-context files against each other:
+- **Stale references** — file A mentions "2 mandatory rules" but there are now 4
+- **Path references** — file A mentions a file that was moved or deleted
+- **Contradictions** — file A says "user-scoped is default" but file B says "root is default"
+
+### 2. Frontmatter integrity
+For each shared-context `.md` file and each `work-sessions/*/workspace/session.md`:
+- Valid frontmatter? (state, lifecycle, type, topic, author, updated; plus name/status/branch/repos for session trackers)
+- `branch` field references a branch that still exists?
+- `repo`/`repos` field references repos that exist in workspace.json?
+- `lifecycle: active` on a file not updated in 7+ days? (stale candidate)
+- `lifecycle: resolved` files that should have been processed by /complete-work?
+- Session tracker `status: active` but the workspace worktree at `work-sessions/{name}/workspace/` is missing? (orphaned)
+
+### 3. Workspace structure
+- Actual directory layout matches what workspace-structure rule describes?
+- CLAUDE.md references skills and rules that actually exist?
+- Orphaned rules or skills not referenced anywhere?
+- workspace.json repos all present in `repos/`?
+
+### 4. Git state
+- Worktrees with no recent commits? (orphaned)
+- Local branches with no remote tracking? (unpushed work)
+- 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.
+
+## Cleanup
+
+Active recommendations. Flags problems and suggests fixes, but asks before acting.
+
+### 5. Stale context
+- 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
+- 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
+
+### 6. Context reconciliation
+- Read recent shared-context writes (last session or last N files by updated date)
+- For each, scan other shared-context files for references that are now stale
+- Surface: "{file} says X but {newer-file} now says Y. Update {file}?"
+- This is the capture-time cross-check, run retroactively instead of inline
+
+### 7. Health metrics
+- Total size of `shared-context/locked/` — flag if over 10KB target
+- Number of ephemeral files — flag if accumulating without resolution
+- Session log stats (if `workspace-scratchpad/session-log.jsonl` exists):
+  - Sessions without capture
+  - Average session length
+  - Compaction-to-capture ratio
+
+## Output Format
+
+```
+/maintenance results:
+
+Issues (3):
+  ✗ shared-context/alice/old-handoff.md references branch feature/old
+    but that branch was deleted
+  ✗ 2 inflight files exist but no active work session (orphaned?)
+  ✗ Locked context is 12.3KB (target: <10KB)
+
+Warnings (2):
+  ⚠ shared-context/alice/workspace-analytics.md not updated in 8 days
+  ⚠ Worktree work-sessions/old-feature/workspace has no commits in 5 days
+
+Cleanup suggestions (2):
+  ⊕ workspace-branching.md and persistent-work-sessions.md overlap
+    significantly — merge into one?
+  ⊕ migration-recipes.md still says "/sync handles dogfood" but
+    /sync was replaced by /sync-work — update?
+
+OK (4):
+  ✓ All CLAUDE.md skill references valid
+  ✓ Workspace structure matches rule
+  ✓ workspace.json repos all present
+  ✓ No frontmatter errors
+```
+
+## Flow
+
+1. Scan shared-context/ recursively — read all `.md` files and their frontmatter
+2. Read CLAUDE.md — extract skill and rule references
+3. Read workspace.json — extract repo manifest
+4. Check `.claude/rules/`, `.claude/skills/`, `.claude/agents/` against references
+5. Check git state (worktrees, branches, remotes)
+6. Read session-log.jsonl if it exists
+7. If cleanup mode: compare files pairwise for overlap, scan for stale cross-references
+8. Compile and present findings grouped by severity
+
+## Notes
+- Audit mode is always read-only — never modifies files
+- Cleanup mode asks before acting on any suggestion
+- Run before /release to catch drift before it compounds
+- Run after long gaps between sessions to surface stale context
+- Consider running at the start of each work session

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

@@ -0,0 +1,98 @@
+---
+name: pause-work
+description: Suspend current work — updates session tracker, captures state to the tracker body, pushes all repos, creates draft PRs. Use when stepping away from work that isn't finished.
+---
+
+# Pause Work
+
+Suspend the active work session. Captures state in the session tracker, pushes work, and marks the session as paused for later resumption.
+
+## Flow
+
+### Step 1: Detect active session
+
+Read the active-session pointer from `.claude/.active-session.json` in the current worktree.
+If no active session: "No active work session. Nothing to pause."
+
+Read the full session tracker at `work-sessions/{session-name}/workspace/session.md`.
+
+### Step 2: Update session tracker body
+
+Rewrite the `## Progress` section of `work-sessions/{session-name}/workspace/session.md` with:
+- What was accomplished in this chat session
+- Key decisions made
+- Current state of the work
+- Specific next steps for whoever resumes
+
+This is a coherent rewrite of the Progress section, not an append (coherent-revisions rule). Leave the frontmatter alone — the session-end hook will mark this chat's `ended` timestamp automatically when the chat closes.
+
+### 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.
+
+If the session tracker has a `workItem:` field AND `workspace.tracker` is configured, post a pause comment on the linked issue via the adapter:
+
+```javascript
+import { createTracker } from './.claude/scripts/trackers/interface.mjs';
+import { readFileSync } from 'node:fs';
+const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
+if (ws.workspace?.tracker) {
+  const tracker = createTracker(ws.workspace.tracker);
+  const progressBody = /* the ## Progress section of session.md, as written in Step 2 */;
+  const body = [
+    `**Session paused by @${currentUser}** (${branch})`,
+    '',
+    progressBody,
+    '',
+    `Resume with \`/start-work\` from any worktree on \`${branch}\`.`,
+  ].join('\n');
+  await tracker.comment(workItem, body);
+}
+```
+
+If `workItem:` is unset, skip the comment — this is a blank session with no tracker linkage.
+
+If the comment fails (tracker unreachable, auth expired), report the error but do not block the pause. The pause state lives locally in the session tracker regardless.
+
+### Step 4: Commit and push workspace
+
+```bash
+# From the workspace worktree
+cd work-sessions/{session-name}/workspace
+git add .
+git commit -m "handoff: pause {session-name}"
+git push -u origin {branch}
+```
+
+### Step 5: Push project repos
+
+```bash
+# For each repo in the tracker's repos:
+cd work-sessions/{session-name}/workspace/repos/{repo}
+git push -u origin {branch}
+```
+
+### Step 6: Create draft PRs
+
+```bash
+# For each repo in the tracker's repos:
+cd work-sessions/{session-name}/workspace/repos/{repo}
+gh pr create --draft --title "WIP: {description}" --body "Work in progress. Session paused."
+
+# Workspace repo — from the workspace worktree
+gh pr create --draft --title "context: {session-name} (paused)" --body "Workspace context for paused session."
+```
+
+If PRs already exist, update them to draft status if needed.
+
+### Step 7: Confirm
+
+"Session '{session-name}' paused. Resume anytime with /start-work."
+
+No worktree cleanup — the session is meant to be resumed. The `work-sessions/{session-name}/` folder stays intact.
+
+## Notes
+- Pause writes ONLY to `work-sessions/{session-name}/workspace/session.md` — never to ongoing or root shared-context
+- The session tracker's frontmatter stays in the session folder — it's the resume mechanism
+- Draft PRs signal work-in-progress without implying merge readiness
+- Auto-committing the pause capture is a workflow artifact — this intentionally bypasses normal commit conventions