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

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

@@ -0,0 +1,91 @@
+---
+name: release
+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
+
+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
+
+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}` — release a specific version
+- `/release` — ask for the version
+
+## Flow
+
+**Step 1: Determine version and repo**
+
+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:
+
+```bash
+git -C repos/{repo} describe --tags --abbrev=0
+```
+
+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.
+
+**Step 2: Preflight the tag**
+
+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.
+
+```bash
+git -C repos/{repo} ls-remote --exit-code origin refs/tags/v{version}
+```
+
+**Step 3: Bump on a branch**
+
+Create a task worktree for the release branch:
+
+```bash
+node .claude/scripts/task-worktree.mjs --root . --create --repo "{repo}" --branch "release/v{version}"
+```
+
+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.
+
+**Step 4: Merge**
+
+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).
+
+**Step 5: Tag and publish**
+
+Pull the merge, tag it, and push the tag:
+
+```bash
+git -C repos/{repo} pull --ff-only
+git -C repos/{repo} tag v{version}
+git -C repos/{repo} push origin v{version}
+```
+
+Who creates the release depends on the repo. If `.github/workflows/publish.yml` exists and itself creates the release (it contains `gh release create`, `softprops/action-gh-release`, or `actions/create-release`), the workflow owns the release — do not call `releaseCreate`; racing it duplicates the release or fails. Instead 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 — then confirm the release exists with `forge.releaseView({ tag: 'v{version}', repo })`.
+
+Otherwise the skill creates the release itself:
+
+```js
+await forge.releaseCreate({ tag: 'v{version}', repo, generateNotes: true });
+```
+
+If a `publish.yml` without release creation exists, still find and watch its run the same way.
+
+**Step 6: Tear down and report**
+
+Remove the release worktree:
+
+```bash
+node .claude/scripts/task-worktree.mjs --root . --remove --repo "{repo}" --branch "release/v{version}" --delete-branch
+```
+
+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
+
+- 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 → _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.** If the invocation's arguments already name an issue — `gh:N`, `#N`, or an issue URL — normalize it to the adapter's id (`#42` and a `.../issues/42` URL both mean `gh:42`), fetch it with `tracker.getIssue(id)`, claim it when it is not yet assigned to you (with the same `ALREADY_ASSIGNED` handling as the fallback pick below), and skip the candidate list entirely. Otherwise, list the candidates — 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, run `node .claude/scripts/chat-record.mjs --whoami --root .` first — compaction can drop the hook line, and this recovers the name by matching the chat's session id. When that too prints nothing, 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 → _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 → _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/_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

package/template/workspace.json.tmpl

@@ -6,11 +6,12 @@
     "scratchpadDir": "workspace-scratchpad",
     "workSessionsDir": "work-sessions",
     "workspaceContextDir": "workspace-context",
-    "releaseNotesDir": "workspace-context/release-notes",
-    "canonicalBudgetBytes": 40960,
-    "subagentContextMaxBytes": 10240,
+    "alwaysLoadedBudgetBytes": 65536,
+    "subagentContextMaxBytes": 32768,
+    "subagentInlineMaxBytes": 8192,
     "greeting": "Welcome back to {{project-name}}.",
     "releaseMode": "per-repo",
+    "sessionModel": "session",
     "tracker": null,
     "forge": { "type": "github" }
   },

package/template/.claude/hooks/repo-write-detection.mjs

@@ -1,107 +0,0 @@
-#!/usr/bin/env node
-// PreToolUse hook — enforce workspace root write restrictions and detect
-// out-of-session repo writes.
-//
-// New layout paths:
-//   Workspace worktree: work-sessions/{name}/workspace/
-//   Project worktree:   work-sessions/{name}/workspace/repos/{repo}/
-//   Bare clone:         repos/{repo}/  (at workspace root)
-import { join, basename } from 'path';
-import {
-  getWorkspaceRoot,
-  readStdin,
-  respond,
-  getActiveSessionPointer,
-  readSessionTracker,
-  readJSON,
-  getWorkspacePaths,
-} from './_utils.mjs';
-
-const root = getWorkspaceRoot(import.meta.url);
-const input = await readStdin();
-const toolName = input.tool_name || '';
-
-if (!['Bash', 'Edit', 'Write'].includes(toolName)) {
-  respond();
-  process.exit(0);
-}
-
-const toolInput = input.tool_input || {};
-const paths = [toolInput.file_path, toolInput.command, toolInput.path]
-  .filter(Boolean)
-  .join(' ')
-  .replace(/\\/g, '/');
-
-// If we're in a workspace worktree, check for out-of-session repo writes
-const pointer = getActiveSessionPointer(root);
-if (pointer) {
-  const mainRoot = pointer.rootPath || root;
-  const config = readJSON(join(mainRoot, 'workspace.json'));
-  const tracker = readSessionTracker(mainRoot, pointer.name);
-
-  if (tracker && config?.repos) {
-    // Find references to repos inside work-sessions/{name}/workspace/repos/{repo}/
-    // and also the workspace-root repos/{repo}/ for direct writes.
-    const wtMatch = paths.match(/work-sessions\/[^/\s]+\/workspace\/repos\/([^/\s]+)/);
-    const cloneMatch = paths.match(/(?:^|\s|\/)repos\/([^/\s]+)/);
-    const targetRepo = wtMatch ? wtMatch[1] : (cloneMatch ? cloneMatch[1] : null);
-    if (targetRepo) {
-      const sessionRepos = tracker.repos || [];
-      if (config.repos[targetRepo] && !sessionRepos.includes(targetRepo)) {
-        respond(`You're about to write to ${targetRepo}, which isn't part of this session. Consider adding it first so changes land on the session branch.`);
-        process.exit(0);
-      }
-    }
-  }
-
-  respond();
-  process.exit(0);
-}
-
-// We're at the main workspace root — restrict writes
-
-const { scratchpadDir } = getWorkspacePaths(root);
-const scratchpadName = scratchpadDir.slice(root.length + 1); // "workspace-scratchpad"
-
-// Allow writes to the workspace scratchpad
-if (paths.includes(scratchpadName)) {
-  respond();
-  process.exit(0);
-}
-
-// Allow writes to local-only-* files
-const filePathArg = toolInput.file_path || '';
-if (basename(filePathArg).startsWith('local-only-')) {
-  respond();
-  process.exit(0);
-}
-
-// For Bash commands, check if the command targets allowed paths
-if (toolName === 'Bash') {
-  const cmd = toolInput.command || '';
-  if (/^\s*(git|ls|cat|head|tail|grep|rg|find|echo|pwd|cd|which|node\s+-c)\b/.test(cmd)) {
-    respond();
-    process.exit(0);
-  }
-  if (cmd.includes(scratchpadName) || cmd.includes('local-only-')) {
-    respond();
-    process.exit(0);
-  }
-  // Allow helper script invocations from the workspace root
-  if (/node\s+.*\.claude\/scripts\//.test(cmd)) {
-    respond();
-    process.exit(0);
-  }
-}
-
-// Check if this write targets repos/, workspace-context/, work-sessions/, or template files
-const isRepoWrite = /(?:^|[\s/])repos\//.test(paths) || paths.includes('work-sessions/');
-const isContextWrite = paths.includes('workspace-context/') && !basename(filePathArg).startsWith('local-only-');
-const isTemplateWrite = paths.includes('.claude/') && !paths.includes(scratchpadName);
-
-if (isRepoWrite || isContextWrite || isTemplateWrite) {
-  respond("You're on main. All work should happen in a workspace worktree. Run /start-work to create or resume a work session.");
-  process.exit(0);
-}
-
-respond();

package/template/.claude/hooks/subagent-start.mjs

@@ -1,44 +0,0 @@
-#!/usr/bin/env node
-// SubagentStart hook — inject workspace-context/shared/locked/ into subagent context
-import { readdirSync, readFileSync, existsSync } from 'fs';
-import { join, basename } from 'path';
-import { getWorkspaceRoot, readJSON, respond } from './_utils.mjs';
-
-const root = getWorkspaceRoot(import.meta.url);
-const config = readJSON(join(root, 'workspace.json'));
-const lockedDir = join(root, 'workspace-context', 'shared', 'locked');
-
-const maxBytes = config?.workspace?.subagentContextMaxBytes || 10240;
-
-if (!existsSync(lockedDir)) {
-  respond();
-  process.exit(0);
-}
-
-const files = readdirSync(lockedDir)
-  .filter(f => f.endsWith('.md') && f !== '.keep')
-  .sort();
-
-if (files.length === 0) {
-  respond();
-  process.exit(0);
-}
-
-let context = '';
-for (const file of files) {
-  const name = basename(file, '.md');
-  const content = readFileSync(join(lockedDir, file), 'utf-8');
-  context += `\n--- ${name} ---\n${content}\n`;
-}
-
-if (Buffer.byteLength(context) > maxBytes) {
-  const summary = files.map(f => {
-    const content = readFileSync(join(lockedDir, f), 'utf-8');
-    const firstLine = content.split('\n').find(l => l.trim() && !l.startsWith('---'))?.replace(/^#*\s*/, '') || '';
-    return `- ${basename(f, '.md')}: ${firstLine}`;
-  }).join('\n');
-
-  context = `[Locked shared context exceeds ${maxBytes} byte limit (${Buffer.byteLength(context)} bytes). Summary of ${files.length} files:]\n${summary}\n[Read individual files from workspace-context/shared/locked/ if you need full content.]`;
-}
-
-respond(context);

package/template/.claude/rules/forge-operations.md

@@ -1,107 +0,0 @@
-Activate this rule if the workspace creates PRs, watches CI runs, or interacts with releases from skills. Sibling to `work-item-tracking.md` (which covers issues); together they cover everything a workspace needs to do against a code-hosting forge.
-
-# Forge Operations
-
-When a workspace has a forge configured, all pull-request, release, and workflow-run operations from skills and scripts go through the adapter at `.claude/scripts/forges/{type}.mjs`. Skills never call `gh` (or `glab`, or any forge CLI) inline.
-
-## Why the abstraction
-
-- **Swap by config.** Moving from GitHub to GitLab is a `workspace.json` field change plus an adapter file — not a sweep across six skill files.
-- **Testable.** The adapter takes an injectable `spawnFn`; unit tests mock subprocess calls instead of running them.
-- **One vocabulary.** Skills reason about `forge.prCreate`, `forge.prMerge`, `forge.workflowRunFind`, `forge.workflowRunWatch`, `forge.releaseView` regardless of backend. Failure modes share typed errors (`PrNotFound`, `MergeRejected`, `WorkflowNotFound`, `ReleaseNotFound`) instead of every callsite parsing stderr.
-
-## Configuration
-
-`workspace.json` → `workspace.forge`:
-
-```json
-{
-  "workspace": {
-    "forge": {
-      "type": "github"
-    }
-  }
-}
-```
-
-- `type` — identifies the adapter module at `.claude/scripts/forges/{type}.mjs`. `github` is the default and the only fully-implemented adapter today. `gitlab.mjs` ships as a stub that throws `NOT_IMPLEMENTED` with a contribution pointer.
-- `repo` (optional) — adapter-specific. For `github`, the `owner/name` slug to target. When unset or `"auto"`, the adapter resolves the repo from the local git `origin` remote.
-
-Absence of `workspace.forge` is treated as `{ type: 'github' }` (back-compat for workspaces that predate the field). Setting `workspace.forge: false` explicitly disables forge operations — every adapter method then throws `FORGE_DISABLED`.
-
-## Adapter interface (for Claude)
-
-Import from `.claude/scripts/forges/interface.mjs`:
-
-```javascript
-import { createForge, PrNotFound, MergeRejected, WorkflowNotFound, ReleaseNotFound } from '.claude/scripts/forges/interface.mjs';
-import { readFileSync } from 'node:fs';
-
-const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
-const forge = createForge(ws.workspace?.forge);
-
-// Pull request lifecycle
-const pr = await forge.prCreate({
-  title: 'feat: add forge adapter',
-  body: 'long-form body',
-  draft: false,                // omit or false for normal PRs; true for /pause-work drafts
-  base: 'main',                // optional; defaults to repo default branch
-  head: 'feature/forge',       // optional; defaults to current branch
-});                            // → { id: 'owner/repo#42', url, number }
-
-await forge.prMerge({
-  id: pr.id,
-  strategy: 'squash',          // 'merge' | 'squash' | 'rebase'
-  deleteBranch: true,
-});
-
-const view = await forge.prView({ id: pr.id });
-// → { state, mergeable, mergeStateStatus, reviewDecision, ... }
-
-// Releases (lookup only — release creation lives in the workflow tag-push)
-const release = await forge.releaseView({ tag: 'v1.2.3' });
-// → { tag, name, url, publishedAt, isDraft, isPrerelease }
-// throws ReleaseNotFound if the tag has no release
-
-// Workflow runs (used by /complete-work to follow the publish workflow)
-const run = await forge.workflowRunFind({
-  workflow: 'publish.yml',
-  branch: 'v1.2.3',
-  limit: 1,
-});                            // → { runId, status, conclusion, url } | null
-const result = await forge.workflowRunWatch({
-  runId: run.runId,
-  exitStatus: true,            // true: exit non-zero on workflow failure
-});                            // → { exitCode } — does NOT throw on workflow failure
-```
-
-All methods are async. Adapter-detectable failures throw typed errors; raw spawn failures throw `Error`.
-
-## Skill behavior
-
-Skills that interact with forge operations:
-
-- **`/pause-work`** — creates draft PRs via `forge.prCreate({ draft: true })`.
-- **`/complete-work`** — creates PRs, merges them with `strategy: 'squash'`, and (release sessions only) finds + watches the publish workflow via `workflowRunFind` + `workflowRunWatch`. Uses `releaseView` to investigate existing tag conflicts before re-tagging.
-
-Skills outside that list do not call the forge adapter; they either don't touch the forge or they touch it for tracker-setup-specific operations that are deliberately scoped out (see below).
-
-## What this rule does NOT cover
-
-- **Issue lifecycle.** Issues, comments, labels, milestones live in `work-item-tracking.md` via the tracker adapter at `.claude/scripts/trackers/{type}.mjs`. The two abstractions are intentionally separate.
-- **Tracker-setup repo configuration.** `/setup-tracker` uses `gh repo view --json hasIssuesEnabled` and `gh api repos/{slug} -X PATCH -f has_issues=true` to inspect and enable the Issues feature on a GitHub repo. Those are GitHub-API-specific setup operations, not the cross-cutting PR/release ops the forge abstraction targets. A GitLab user running `/setup-tracker` would follow a different setup flow entirely, so wrapping these in the forge adapter would create a leaky abstraction. They remain direct `gh` calls.
-- **`gh repo view` as a remote-type probe.** `/complete-work` uses `gh repo view` to detect whether a remote is a GitHub remote (separately from any PR operation that follows). This is a one-line capability check, not an operation that benefits from forge wrapping. It stays direct.
-- **Repo creation.** `gh repo create` (in `/sync-work` and `/workspace-init` setup narratives) is an interactive one-off used when a workspace lacks a remote. No forge adapter method for it — pointing users at a wrapped form when none exists would be worse than the current direct mention.
-- **Manual operator recovery.** `gh run rerun`, `gh run view`, `gh release view` referenced in `/release` recovery guidance are documented for an operator at a terminal investigating a failed publish. The forge adapter is for *skill code*, not the manual recovery prose.
-
-## Migration
-
-Existing workspaces predate `workspace.forge`. They continue to work because `createForge(undefined)` defaults to `{ type: 'github' }`. The `/maintenance` audit surfaces a notice when `workspace.tracker.type === 'github-issues'` and `workspace.forge` is unset, suggesting the explicit value — a one-line `workspace.json` addition with no behavior change.
-
-A workspace switching to GitLab implements `.claude/scripts/forges/gitlab.mjs` against the interface (the stub file documents the shape) and sets `workspace.forge.type: 'gitlab'`. No skill rewrite is required; the abstraction does the routing.
-
-## What this rule does NOT do
-
-- Does not prescribe a specific forge type. Adapter choice is per workspace.
-- Does not replace forge-native features (PR comments, review-requested webhooks, branch protection settings) — those remain UI / direct-CLI territory.
-- Does not promise that every `gh` capability is wrapped. The adapter covers the operations the template's skills actually perform. New operations land via additive interface methods, not by skills going around the adapter.

package/template/.claude/rules/git-conventions.md

@@ -1,34 +0,0 @@
-# Git Conventions
-
-## Branching
-
-- Prefixes: `feature/`, `bugfix/`, `chore/`
-- Names: kebab-case after prefix, no grouping/nesting
-- Examples: `feature/ble-provisioning`, `bugfix/mqtt-reconnect`
-- All branches merge to the repo's default branch
-- Branch names should be unique — if revisiting previous work, distinguish the new branch name
-
-## Worktrees
-
-- Work sessions get N+1 worktrees: one for the workspace, plus one per project repo
-- Each session lives in a self-contained folder at `work-sessions/{session-name}/`
-- The workspace worktree is at `work-sessions/{session-name}/workspace/`
-- Project worktrees are nested inside the workspace worktree at `work-sessions/{session-name}/workspace/repos/{repo-name}/`
-- Example: for a session `fix-auth` on branch `bugfix/fix-auth` touching repos `my-app` and `my-api`:
-  - `work-sessions/fix-auth/workspace/` — workspace worktree
-  - `work-sessions/fix-auth/workspace/repos/my-app/` — project worktree
-  - `work-sessions/fix-auth/workspace/repos/my-api/` — project worktree
-- The workspace repo's `.gitignore` pattern `repos` (no trailing slash) covers both the workspace root's `repos/` and the nested `repos/` inside every worktree
-- Source clones at `repos/{repo-name}/` (at the workspace root) stay on their default branch at all times
-- Remove worktrees when the work session is completed — use the cleanup helper to enforce the mandatory teardown order (project worktrees first, then workspace worktree, then prune)
-
-## Branch Maintenance
-
-- Before creating a PR, fetch and rebase onto the latest parent branch
-- If conflicts arise during rebase, stop and present them to the user — do not auto-resolve
-
-## Commits
-
-- Conventional commit format: `feat:`, `fix:`, `refactor:`, `chore:`, `docs:`
-- Never amend commits unless explicitly asked
-- Never force push unless explicitly asked