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

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

@@ -0,0 +1,77 @@
+---
+name: promote
+description: Move personal auto-memory or local-only files into shared context. Use when you've discovered something valuable that the team should know.
+---
+
+# Promote
+
+Promote personal knowledge into shared context. Assess all candidates, recommend actions, let the user decide with coded references.
+
+## Sources
+
+This skill can promote from three sources:
+1. **Auto-memory (AM)** — files in `~/.claude/projects/*/memory/`
+2. **Local-only context (LOC)** — `shared-context/local-only-*.md`
+3. **Local-only rules (LOR)** — `.claude/rules/local-only-*.md`
+
+## Flow
+
+**Step 1: List all candidates**
+
+Show ALL candidates from all sources in a single coded table. The user should see everything at once to make informed decisions.
+
+```
+| Code | File                          | Assessment                              | Recommendation    |
+|------|-------------------------------|-----------------------------------------|-------------------|
+| AM1  | feedback_no_injection_rev...  | Redundant — coherent-revisions rule     | Drop from memory  |
+| AM2  | project_create_claude_work... | Stale — references deleted spec         | Drop or update    |
+| AM3  | feedback_subagent_perms...    | Personal setup quirk                    | Keep as memory    |
+| LOC1 | local-only-naming-ideas.md    | Team should see naming options          | Promote to alice/ |
+| LOC2 | local-only-release-checkli... | Personal task tracker                   | Keep local        |
+| LOR1 | local-only-dogfood-sync.md    | Dogfood-specific, not for template      | Keep local        |
+```
+
+For each candidate, assess:
+- Is it redundant with an existing rule or context file? → recommend drop
+- Is it stale or outdated? → recommend drop or update
+- Is it personal/setup-specific? → recommend keep as-is
+- Would the team benefit from seeing it? → recommend promote
+
+**Step 2: User decides**
+
+The user responds using codes:
+- "Promote: LOC1, LOC2. Drop: AM1, AM2. Keep the rest."
+- "Promote all LOC. Drop AM1-AM3."
+- Or any combination.
+
+**Step 3: Execute decisions**
+
+For each **promote** action:
+- Ask: "Team-visible, user-scoped (default), or locked?"
+- Copy to destination, set `type: promoted` in frontmatter
+- Remove the local-only original
+- Commit individually: `git commit -m "promote: {name}"`
+
+For each **drop** action:
+- Delete the file (auto-memory from `~/.claude/projects/*/memory/`, local-only from workspace)
+- Update MEMORY.md index if auto-memory was removed
+
+For each **keep** action:
+- No changes
+
+**Step 4: Report**
+
+"Promoted {N} files. Dropped {M} files. {K} files unchanged."
+
+## Rewrite on Promote
+
+Auto-memory files are terse notes written for Claude's internal use. When promoting to shared context, rewrite into proper format with:
+- Frontmatter (state, lifecycle, type: promoted, topic, author, updated)
+- Sections with enough context to be useful to someone who wasn't in the original session
+- Local-only files may already be well-formatted — copy as-is if so, just update frontmatter
+
+## Notes
+- Promotion is one-way: shared context should not be demoted back to local-only
+- Use this when you discover a pattern, convention, or decision that would benefit the team
+- The coded table makes bulk decisions fast — no need to type full filenames
+- Assess everything upfront so the user sees the full picture before deciding

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

@@ -0,0 +1,126 @@
+---
+name: release
+description: Combine unreleased branch notes into a versioned release document. Targets project repos, not the workspace. Synthesizes ephemeral shared context into locked entries. Use at release time.
+---
+
+# Release
+
+Combine unreleased branch-release-notes into a versioned document per project repo. Synthesize ephemeral workspace context into locked team knowledge.
+
+## Parameters
+- `/release {version}` — create release notes for 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?"
+
+**Step 2: Read unreleased notes**
+For each target repo:
+```bash
+ls repos/{repo}/release-notes/unreleased/
+```
+Read all `branch-release-notes-*.md` and `branch-release-questions-*.md` files.
+
+If no unreleased files exist: "No unreleased notes found for {repo}. Nothing to release."
+
+**Step 3: Group and organize**
+Group notes by type using `type:` frontmatter (feature, fix, chore):
+- Features first, then fixes, then chores
+- Within each group, order chronologically by date
+
+**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 in a "Known Issues" section of the release notes
+- **Discard** — no longer relevant
+
+**Step 5: Synthesize release document**
+Write `repos/{repo}/release-notes/v{version}.md`:
+```markdown
+# v{version} Release Notes
+
+**Date:** {YYYY-MM-DD}
+
+## Features
+{Coherent narrative combining all feature branch-release-notes.
+Deduplicate related items. Credit authors.
+Write from scratch — don't concatenate. Coherent-revisions rule applies.}
+
+## Fixes
+{Same treatment for bugfix branches.}
+
+## Maintenance
+{Same for chore branches.}
+
+## Known Issues
+{Deferred questions from Step 4, if any.}
+
+## Contributors
+{List of unique authors from all branch notes.}
+```
+
+**Step 6: Archive unreleased files**
+```bash
+mkdir -p repos/{repo}/release-notes/archive/v{version}
+mv repos/{repo}/release-notes/unreleased/branch-release-* repos/{repo}/release-notes/archive/v{version}/
+```
+
+**Step 7: Commit release notes to project repo**
+```bash
+cd repos/{repo}
+git add release-notes/
+git commit -m "docs: v{version} release notes"
+```
+
+**Step 7b: Bump package.json version**
+If the project repo has a `package.json` with a `version` field (as in the scaffolder repo), 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}"
+```
+Skip this step if the repo has no package.json or no version field.
+
+**Step 8: Consume project-scoped specs**
+Project-scoped specs and plans in `shared-context/{user}/` (ongoing) that are fully covered by this release:
+- Consume into the release notes (their content is now captured in the versioned doc)
+- Remove the source files
+- If partially covered: rewrite the spec to reflect only what remains unimplemented
+
+**Step 9: Synthesize workspace shared context**
+Process ephemeral shared-context entries:
+
+1. List all ephemeral entries with `lifecycle: resolved`
+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 `{user}/` ongoing or keep as root ephemeral
+3. For merged/new locked entries:
+   - Set `state: locked`, `type: synthesized`
+   - Move to `shared-context/locked/`
+   - Write concise, focused content — team truths, not session history
+4. Commit:
+   ```bash
+   git add shared-context/
+   git commit -m "release: synthesize shared context for v{version}"
+   ```
+
+**Step 10: Report**
+"Release v{version} complete for {repo}. {N} branch notes combined. {M} context entries synthesized into {K} locked entries."
+
+## Notes
+- Release notes live in the PROJECT repo — the workspace never gets versioned
+- Context synthesis happens in the WORKSPACE repo — both get separate commits
+- The archive directory preserves raw branch notes for audit
+- Per-repo is the default — each repo has its own release cadence
+- The coherent-revisions rule applies: write the release narrative from scratch, don't concatenate branch notes

package/template/.claude/skills/setup-tracker/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: setup-tracker
+description: Configure an issue tracker for this workspace — writes workspace.json → tracker block and initializes labels. GitHub Issues is the only backend shipped; others can be added by dropping an adapter at .claude/scripts/trackers/{type}.mjs. Runnable during /workspace-init or standalone.
+---
+
+# Setup Tracker
+
+Wire this workspace up to an external issue tracker. The tracker becomes the source of truth for all work items; the workspace does not maintain a local mirror.
+
+## Prerequisites
+
+- `.claude/rules/work-item-tracking.md` should be active. If missing, warn but continue.
+- The adapter for the chosen backend must exist at `.claude/scripts/trackers/{type}.mjs`. The template ships `github-issues.mjs`.
+
+## Flow
+
+### Step 1: Check current state
+
+Read `workspace.json` → `workspace.tracker`. If already configured: "Tracker is {type} on {repo}. Reconfigure? [y/N]." If declined, exit.
+
+### Step 2: Pick a backend
+
+Ask: "Which issue tracker?"
+1. GitHub Issues (shipped)
+2. Linear — not yet supported
+3. Jira — not yet supported
+4. None — skip
+
+For (2) and (3): tell the user the adapter isn't shipped and exit. To add one, write a module at `.claude/scripts/trackers/{type}.mjs` that implements the contract in `.claude/scripts/trackers/interface.mjs`.
+
+For (4): exit — no changes.
+
+### Step 3: GitHub Issues configuration
+
+1. **Verify `gh` auth.** Run `gh auth status`. If not authenticated, walk the user through `gh auth login`. Do not proceed until authenticated.
+
+2. **Resolve the target repo.** Default to the workspace's own git remote:
+   ```bash
+   git -C {workspace-root} remote get-url origin
+   ```
+   Parse the GitHub slug. Ask: "Use `{slug}` for issues, or a different repo?" If the user wants a different repo, accept any `owner/name` slug.
+
+3. **Verify issues are enabled:**
+   ```bash
+   gh repo view {slug} --json hasIssuesEnabled
+   ```
+   If `hasIssuesEnabled` is `false`, offer: "Issues are disabled on `{slug}`. Enable? [Y/n]" → `gh api repos/{slug} -X PATCH -f has_issues=true`.
+
+4. **Write `workspace.json`:**
+   ```json
+   {
+     "workspace": {
+       "tracker": {
+         "type": "github-issues",
+         "repo": "{slug}"
+       }
+     }
+   }
+   ```
+   Preserve all other fields. Commit:
+   ```bash
+   git add workspace.json
+   git commit -m "chore: configure github-issues tracker on {slug}"
+   ```
+
+5. **Initialize labels** by calling the adapter's `ensureLabels()` from a shell one-liner:
+   ```bash
+   node --input-type=module -e "
+     import { createTracker } from './.claude/scripts/trackers/interface.mjs';
+     import { readFileSync } from 'node:fs';
+     const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
+     const t = createTracker(ws.workspace.tracker);
+     await t.ensureLabels();
+     console.log('Labels initialized.');
+   "
+   ```
+   Creates the six standard labels: `bug`, `feat`, `chore`, `P1`, `P2`, `P3`.
+
+6. **Optional: create milestones.** Ask if the user wants a starter milestone list (e.g., `Backlog`, `v0.1 — Alpha`, `v1.0 — Launch`). If yes, call the adapter for each — idempotent, so re-running setup won't duplicate:
+   ```bash
+   node --input-type=module -e "
+     import { createTracker } from './.claude/scripts/trackers/interface.mjs';
+     import { readFileSync } from 'node:fs';
+     const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
+     const t = createTracker(ws.workspace.tracker);
+     await t.ensureMilestone({ title: 'Backlog', description: 'Triage later' });
+     await t.ensureMilestone({ title: 'v0.1 — Alpha' });
+     await t.ensureMilestone({ title: 'v1.0 — Launch' });
+   "
+   ```
+   Skip if the user declines — milestones can be added anytime by calling `tracker.ensureMilestone(...)` or via the GitHub UI.
+
+7. **Verify:**
+   ```bash
+   gh issue list --repo {slug} --limit 5
+   ```
+   Expected: empty list (no tickets yet) or the existing ones if the repo already had issues.
+
+### Step 4: Report
+
+```
+Tracker configured:
+  Type: github-issues
+  Repo: {slug}
+  Labels: bug, feat, chore, P1, P2, P3
+  Milestones: {list or "(none — add via GitHub UI or gh api)"}
+
+Next: run /start-work to pick or create an issue and begin.
+```
+
+## Notes
+
+- The workspace repo is the default target — no separate `workspace-{project}` repo needed.
+- Issues track everything across all project repos in the workspace. Cross-repo work items live in one place.
+- One-way integration: the tracker is the source of truth. Skills read and write via the adapter; nothing else reflects tracker state locally.
+- If `gh auth login` later expires, skill flows will surface `gh` errors — re-run `gh auth login` and try again.
+- Adding a new backend: write an adapter module at `.claude/scripts/trackers/{type}.mjs` implementing the interface in `interface.mjs`, then add a case in the `createTracker` switch statement.

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

@@ -0,0 +1,234 @@
+---
+name: start-work
+description: Begin or resume a work session. Creates a self-contained work-sessions/{name}/ folder containing the workspace worktree and nested project worktrees. Accepts optional parameter "handoff" or "blank".
+---
+
+# Start Work
+
+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
+- `/start-work` (no param) — list your active sessions, then resume or start new
+- `/start-work blank` — start new work from scratch
+- `/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: 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.
+2. Walk `work-sessions/` — each `work-sessions/{name}/workspace/session.md` is one session. Read frontmatter for `status`, `description`, `branch`, `repos`, and `user`.
+3. Filter to sessions whose `status` is `active` or `paused`. When a current user is known and the user did not pass `all`, additionally filter to sessions whose `user` field matches the current user (or is missing — unscoped legacy sessions stay visible to everyone).
+4. If matching sessions exist, present them:
+   ```
+   Your active work sessions:
+     1. migrate-tool (active, last chat ended 2h ago)
+        "Rewriting the migration module"
+        Branch: bugfix/migrate-rewrite | Repos: my-app
+
+     [N] Start something new
+
+   Which one?
+   ```
+5. User picks one → resume flow
+6. User picks "new" → blank flow
+7. If no matching sessions exist but other users have active/paused sessions, note it briefly before falling through to `blank`: "No active sessions for you. {N} session(s) belong to other users — run `/start-work all` to see them." If no sessions exist at all, proceed silently as `blank`.
+
+## Flow: Resume
+
+1. Read the selected session tracker at `work-sessions/{name}/workspace/session.md`
+2. Verify worktrees exist:
+   - 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.
+
+   Each `chatSessions` entry has this shape:
+   ```yaml
+   - id: {uuid}
+     names: [{name-if-any}]
+     started: {iso-timestamp}
+     ended: null
+   ```
+   - `id` is the authoritative identifier — the UUID from Claude Code's session. The session-start hook gets it from `input.session_id`.
+   - `names` is a list of all names the chat has had (users can rename). Append, never replace.
+   - `ended` is set by the session-end hook when the chat closes.
+4. Update the tracker `status:` to `active` if it was `paused`
+5. Run history reconstruction (see below)
+6. Tell user: "Resuming {name}. Work from `work-sessions/{name}/workspace/`."
+
+### History Reconstruction
+
+On resume, check for uncaptured work from previous chats:
+
+1. Read the session tracker's `chatSessions` list
+2. For the most recent ended chat, use its `id` field (UUID) to locate the conversation log at `~/.claude/projects/{project-path}/{id}.jsonl`
+3. Check if the session.md body was updated after that chat ended
+4. If there's a gap (conversation log has content newer than the body's last update): scan the log and generate a summary of decisions, progress, and context
+5. Append the summary to the session.md body's `## Progress` section (or create one if it doesn't exist)
+6. Tell user: "Found uncaptured work from your last chat. Updated the session tracker."
+
+If no gap is found, skip silently.
+
+## Flow: Blank (new session)
+
+1. **Check for a configured tracker.** Read `workspace.tracker` from `workspace.json`.
+
+2. **If no tracker is configured:** Ask: "No tracker configured. Want to run `/setup-tracker` first, or start a blank session (no issue linkage)?" If setup-tracker: invoke that skill, then re-enter this flow. If blank: proceed to the description-only path (step 6 below) with no `workItem:` linkage.
+
+3. **Fetch the candidate list via the adapter.** Build the adapter and pull two lists — issues assigned to the current user first, falling back to all unassigned issues if the assigned list is empty:
+   ```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();
+   const fallbackNote = assigned.length === 0 ? '(fallback — no issues assigned to you; showing unassigned)' : '';
+   ```
+
+4. **Present the list.** Group by milestone when the adapter provides one; sort by priority label (P1 before P2 before P3) within each group:
+   ```
+   {fallbackNote}
+   Backlog:
+     1. [P1 bug] Auth timeout on mobile (gh:3)
+     2. [P1 feat] JWT refresh logic (gh:8)
+
+   v0.1:
+     3. [P2 feat] Full-text search (gh:5)
+
+     [N] Something new
+
+   Which one, or describe something new?
+   ```
+   Accept a number or "N".
+
+5. **User picked an existing issue.**
+   - If it came from the unassigned fallback list, atomically claim it:
+     ```javascript
+     try {
+       await tracker.claim(issue.id);
+     } catch (e) {
+       if (e.code === 'ALREADY_ASSIGNED') {
+         console.log(`${issue.id} was just claimed by ${e.assignees.join(', ')}. Refreshing list.`);
+         // Re-enter step 3 — someone else grabbed the ticket between fetch and claim.
+         return restart();
+       }
+       throw e;
+     }
+     ```
+   - If it came from the assigned-to-me list, skip the claim call (already mine).
+   - Generate the session name from the issue title (kebab-case slug, max ~40 chars).
+   - Remember `workItem: {issue.id}` for the session tracker.
+
+6. **User picked "Something new" (or fell through from step 2 with no tracker).**
+   - Ask for a description, type (`bug` / `feat` / `chore`), priority (`P1` / `P2` / `P3`), optional milestone.
+   - If a tracker is configured, create the issue and self-assign:
+     ```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: {newIssue.id}` for the session tracker.
+   - If no tracker: proceed without a `workItem:` linkage — the session is a pure blank.
+
+7. **Pick repo(s)** — present numbered list from workspace.json, allow multi-select (e.g., `1,3` or `all`).
+
+8. **Propose branch:** `{prefix}/{session-name}` where prefix comes from type (`feature/` for feat, `bugfix/` for bug, `chore/` for chore). Wait for confirmation.
+
+### Create work session
+
+Run the helper script:
+```bash
+node .claude/scripts/create-work-session.mjs \
+  --session-name "{session-name}" \
+  --branch "{branch}" \
+  --repo "{repo1},{repo2}" \
+  --user "{user}" \
+  --description "{description}"
+```
+
+The script creates:
+- Session folder at `work-sessions/{session-name}/`
+- Workspace worktree at `work-sessions/{session-name}/workspace/` with a real `repos/` directory inside
+- Project worktree per repo nested at `work-sessions/{session-name}/workspace/repos/{repo}/`
+- Unified session tracker at `work-sessions/{session-name}/workspace/session.md` (frontmatter + body)
+- 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.
+
+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.
+
+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`.
+
+### 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.
+
+Check: has the current conversation included substantive discussion (design decisions, requirements exploration, approach selection) before this point?
+
+If yes:
+1. Summarize the prior discussion — key decisions, requirements established, approaches chosen/rejected, constraints identified
+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
+   git add session.md
+   git commit -m "chore: capture pre-session discussion for {session-name}"
+   ```
+
+If no prior discussion: skip silently.
+
+Tell user: "Work session started. Work from `work-sessions/{session-name}/workspace/`."
+
+### Add repo to active session
+
+If there's an active session and the user wants to add a repo (explicitly or prompted by repo-write-detection):
+
+1. Confirm: "Add {repo} to the current session '{session-name}'?"
+2. Run the helper script:
+   ```bash
+   node .claude/scripts/add-repo-to-session.mjs \
+     --session-name "{session-name}" \
+     --repo "{repo}"
+   ```
+3. Tell user: "Added {repo}. Worktree at `work-sessions/{session-name}/workspace/repos/{repo}/`."
+
+### Stale worktree check
+
+Before creating a new session, scan for existing sessions:
+```bash
+ls work-sessions/ 2>/dev/null
+```
+If stale sessions exist (no recent commits on the branch, no open PR, tracker `status` is `active` but worktrees are gone):
+- "You have existing sessions for {names}. Clean up? [y/N]"
+- If yes: run cleanup script for each
+
+### Next steps
+
+If superpowers-workflow rule is active: run mandatory research phase, then invoke brainstorming skill.
+If not: ask "Ready to start implementing, or want to brainstorm first?"
+
+## Flow: Retroactive (called mid-session)
+
+When /start-work is called after work has already begun:
+
+1. Detect uncommitted changes in `repos/` or `shared-context/`
+2. "It looks like you've already been working. Let me formalize this."
+3. If changes are on a default branch: stash → create session → pop stash
+4. If changes are already on a feature branch: create workspace worktree and nest the existing project worktree(s) under it, or create a fresh session if the work is small enough to re-apply
+5. Summarize: "Formalized as work session: {name}. Work from `work-sessions/{name}/workspace/`."
+
+## Notes
+- All repos (workspace + project repos) get the same branch name for traceability
+- Each session lives in a single self-contained folder at `work-sessions/{name}/`
+- The workspace worktree contains a real `repos/` directory with nested project worktrees — no symlink
+- `session.md` is the single source of truth for session state: frontmatter is machine state (status, branch, chatSessions, workItem), body is human content (decisions, progress)
+- The `workItem:` field in session frontmatter holds the adapter-prefixed issue ID (e.g., `gh:42`) — the tracker itself is authoritative for status, assignment, and labels
+- Session trackers, specs, and plans live at the top of the session worktree and are tracked on the session branch. Pushing the branch carries durable session thinking across machines. `/complete-work` removes them from the branch before the final PR so main's top level stays free of session artifacts
+- Worktrees and local artifacts are gitignored — recreate them on first resume on each machine
+- Auto-committing session state is a workflow artifact — this intentionally bypasses normal commit conventions

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

@@ -0,0 +1,73 @@
+---
+name: sync-work
+description: Push branches without ceremony — all project and workspace repos. No PR, no status change, no forced capture. Use for backing up work in progress.
+---
+
+# Sync
+
+Push current branches to remote for all project repos and the workspace repo. Lightest-touch backup — no PRs, no lifecycle changes, no forced context capture.
+
+## Flow
+
+**Step 1: Detect active branches**
+```bash
+# Workspace worktree
+cd work-sessions/{session-name}/workspace
+git branch --show-current
+
+# Project worktree(s) — for each repo in the session tracker's repos:
+git -C work-sessions/{session-name}/workspace/repos/{repo} branch --show-current
+```
+
+**Step 2: Check for uncommitted changes**
+For each repo in the session tracker's `repos:` list plus the workspace:
+```bash
+cd work-sessions/{session-name}/workspace/repos/{repo}
+git status --short
+```
+If uncommitted changes exist: "You have uncommitted changes in {repo}. Commit before syncing? [Y/n]"
+If yes: ask for a commit message or suggest one based on the changes.
+If no: skip that repo (can't push uncommitted work).
+
+**Step 3: Check for remotes**
+For each repo in the session tracker's `repos:`:
+```bash
+cd work-sessions/{session-name}/workspace/repos/{repo}
+git remote -v
+```
+If no remote: "No remote configured for {repo}. Want me to create one on GitHub, or provide a URL?"
+Create via `gh repo create` or add the provided URL. Never silently skip.
+
+**Step 4: Push**
+For each repo with committed changes and a remote:
+```bash
+cd work-sessions/{session-name}/workspace/repos/{repo}
+git push -u origin {branch-name}
+```
+
+Then push the workspace repo from the workspace worktree:
+```bash
+cd work-sessions/{session-name}/workspace
+git push -u origin {branch-name}
+```
+
+The session-branch top-level files (`session.md`, `design-*.md`, `plan-*.md`) ride along with the workspace push — they live on the session branch, not on main, so pushing the branch is how durable session thinking reaches another machine.
+Report per repo: "Synced: {repo} ({branch-name}) pushed to origin."
+
+**Step 5: Optionally offer capture**
+"Want to /braindump or /handoff while syncing? [n/Y]"
+Default is no — /sync-work is about backing up, not capturing. But the offer is there.
+
+## Three Intents, Three Skills
+
+| Skill | Intent | What happens |
+|---|---|---|
+| /pause-work | Stopping, someone else might pick up | Capture + push + draft PR + mark paused |
+| /complete-work | Done with this branch | Synthesize + push + real PR + resolve context |
+| /sync-work | Still working, just backing up | Push + no PR + no status change |
+
+## Notes
+- No PRs created — this is a checkpoint, not a milestone
+- No lifecycle changes — context stays `active`
+- All repos pushed if they have branches with changes
+- Safe to run repeatedly — just pushes latest commits