@ulysses-ai/create-workspace 0.14.0-beta.3 → 0.15.0-beta.1

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

@@ -12,31 +12,34 @@ Capture a drive-by idea without interrupting the current conversation. By defaul
 - `/aside <thought>` — researched mode (default). Background subagent explores the idea.
 - `/aside --quick <thought>` — note only. No subagent, no research. Just park the thought.
 
-Everything after `/aside` (or `/aside --quick`) is the user's thought. No name parameter — the filename is generated from the content.
+Everything after `/aside` (or `/aside --quick`) is the user's thought. No name parameter — the slug is generated from the content.
 
 ## Quick Mode (`--quick`)
 
 No subagent. Execute these steps directly:
 
-1. Parse the user's thought from the arguments (everything after `--quick`)
-2. Generate a kebab-case slug from the content (3-5 words that capture the core idea)
-3. Check if `shared-context/{user}/local-only-{slug}.md` exists. If so, append `-2`, `-3`, etc.
-4. Infer 2-3 threads worth exploring later for the Further Investigation section
-5. Write the file using the Quick Mode template below
-6. Report the file path to the user: "Noted: `shared-context/{user}/local-only-{slug}.md`"
+1. Parse the user's thought from the arguments (everything after `--quick`).
+2. Generate a kebab-case slug from the content (3-5 words that capture the core idea).
+3. Compose the body using the Quick Mode template below (verbatim user thought + a Further Investigation section with 2-3 inferred threads).
+4. Use the centralized helper to compute the path, apply the `braindump_` prefix, write the frontmatter (with `variant: aside`), and stay gitignored:
+
+```bash
+echo "$BODY" | node .claude/scripts/capture-context.mjs \
+  --type braindump \
+  --topic {kebab-slug} \
+  --scope team-member \
+  --user {workspace.user} \
+  --variant aside \
+  --local-only
+```
 
-### Quick Mode Template
+5. Report the printed path to the user: "Noted: `{path}`."
 
-```yaml
----
-state: ephemeral
-lifecycle: active
-type: braindump
-variant: aside
-author: {user}
-updated: {YYYY-MM-DD}
----
+The helper handles collisions automatically by appending `-2`, `-3`, etc.
+
+### Quick Mode Body Template
 
+```markdown
 ## User's Original Thought
 {Verbatim text from the user — copy exactly as provided}
 
@@ -47,37 +50,38 @@ related areas to check. Quick inference, not deep research.}
 
 ## Research Mode (default)
 
-Dispatch the `aside-researcher` agent in the background:
-
-1. Parse the user's thought from the arguments (everything after `/aside`)
-2. Generate a kebab-case slug from the content (3-5 words that capture the core idea)
-3. Check if `shared-context/{user}/local-only-{slug}.md` exists. If so, append `-2`, `-3`, etc.
-4. Determine the target file path: `shared-context/{user}/local-only-{slug}.md`
-5. Dispatch the `aside-researcher` agent using the Agent tool:
+Dispatch the `aside-researcher` agent in the background. The full mode uses `--type research` so the file is named `local-only-research_{slug}.md`, distinguishing it from quick asides.
+
+1. Parse the user's thought from the arguments (everything after `/aside`).
+2. Generate a kebab-case slug from the content.
+3. Compute the target path with `--print-only` so you can hand it to the subagent:
+   ```bash
+   node .claude/scripts/capture-context.mjs \
+     --type research \
+     --topic {kebab-slug} \
+     --scope team-member \
+     --user {workspace.user} \
+     --variant aside \
+     --local-only \
+     --print-only
+   ```
+4. Dispatch the `aside-researcher` agent using the Agent tool:
    - `subagent_type`: use the `aside-researcher` agent definition
    - `run_in_background: true`
    - Prompt must include:
      - The user's verbatim thought
-     - The target file path
+     - The target file path (from step 3)
      - The workspace root path
-     - The Research Mode template (below)
-6. Confirm dispatch to the user: "Researching in the background. I'll let you know when it's done."
-7. When the agent completes, report: file path and a one-line summary of what was found
+     - The Research Mode body template (below)
+   - Tell the agent to write the body via `capture-context.mjs --update` so the same path is reused, and to pipe the rendered body on stdin.
+5. Confirm dispatch to the user: "Researching in the background. I'll let you know when it's done."
+6. When the agent completes, report: file path and a one-line summary of what was found.
 
-### Research Mode Template
+### Research Mode Body Template
 
 Include this template in the agent's prompt so it writes the correct format:
 
-```yaml
----
-state: ephemeral
-lifecycle: active
-type: braindump
-variant: aside
-author: {user}
-updated: {YYYY-MM-DD}
----
-
+```markdown
 ## User's Original Thought
 {Verbatim text from the user — copy exactly as provided, never paraphrase}
 
@@ -98,15 +102,16 @@ Topics that would benefit from deeper exploration or user input.}
 
 ## File Naming
 
-- **Location:** `shared-context/{user}/local-only-{slug}.md`
-- **Slug:** Generated from the thought content. Kebab-case, 3-5 words. E.g., `refresh-token-caching`, `deploy-pipeline-idea`
-- **Collision handling:** If the file exists, append `-2`, `-3`, etc.
-- **Always `local-only-`** — gitignored, never auto-committed
+- **Quick mode:** `workspace-context/team-member/{user}/local-only-braindump_{slug}.md`
+- **Research mode:** `workspace-context/team-member/{user}/local-only-research_{slug}.md`
+- **Slug:** Kebab-case, 3-5 words. E.g., `refresh-token-caching`, `deploy-pipeline-idea`.
+- **Collision handling:** Helper auto-appends `-2`, `-3`, …
+- **Always `local-only-`** — gitignored, never auto-committed.
 
 ## Session Behavior
 
 Asides are session-agnostic. Regardless of whether a work session is active:
-- Files always go to `shared-context/{user}/`
+- Files always go to `workspace-context/team-member/{user}/`
 - No interaction with the session tracker
 - No interaction with `/complete-work` synthesis
 

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

@@ -1,11 +1,11 @@
 ---
 name: braindump
-description: Capture discussion-heavy topics into shared context. Use when reasoning, exploration, or design rationale should be preserved. Accepts optional name parameter.
+description: Capture discussion-heavy topics into workspace-context. Use when reasoning, exploration, or design rationale should be preserved. Accepts optional name parameter.
 ---
 
 # Braindump
 
-Capture discussion reasoning, exploration results, and design rationale into shared context. More freeform than /handoff — designed for "why we chose X" content. User-scoped by default.
+Capture discussion reasoning, exploration results, and design rationale into workspace-context. More freeform than /handoff — designed for "why we chose X" content. Per-user (`team-member/{user}/`) is the default scope.
 
 ## Parameters
 - `/braindump {name}` — create or update a named braindump
@@ -27,25 +27,29 @@ When called within an active work session (the active-session pointer at `.claud
   ```
 
 When called from the workspace root (no active session):
-- Create a `local-only-{name}.md` file (root only allows local-only writes)
+- Use `--local-only` so the captured file is gitignored (the root only allows local-only writes)
 - Suggest starting a work session if the braindump is about actionable work
 
 The flows below apply when NOT in an active work session, or when the user explicitly asks for a standalone braindump file.
 
 ## Flow: Named
 
-Follows the same naming, scoping (user/team/local-only), and commit flow as `/handoff` but with a different file format:
+Use the centralized `capture-context.mjs` helper — it computes the path, applies the `braindump_` prefix, and writes the frontmatter so this skill doesn't have to:
 
-```yaml
----
-state: ephemeral
-lifecycle: active
-type: braindump
-topic: {name}
-author: {user}
-updated: {YYYY-MM-DD}
----
+```bash
+echo "$BODY" | node .claude/scripts/capture-context.mjs \
+  --type braindump \
+  --topic {kebab-case-name} \
+  --scope team-member \
+  --user {workspace.user} \
+  --description "{one-line summary}"
+```
 
+Add `--scope shared` (and drop `--user`) to put the file in `workspace-context/shared/` for team visibility. Add `--local-only` to keep it gitignored. Add `--update` to overwrite an existing file with the same name; without it, the helper appends `-2`, `-3`, etc. on collision.
+
+The body content sent on stdin should follow this template:
+
+```markdown
 ## Context
 {What prompted this discussion}
 
@@ -59,6 +63,8 @@ updated: {YYYY-MM-DD}
 {What this decision means for future work}
 ```
 
+The helper writes the frontmatter (`state: ephemeral`, `lifecycle: active`, `type: braindump`, `topic`, `author`, `updated`) and prints the absolute path on stdout so the skill can `git add` and commit it.
+
 ## Flow: Side Braindump (deprecated)
 
 `/braindump side` has been replaced by the `/aside` skill. If invoked:
@@ -74,7 +80,7 @@ updated: {YYYY-MM-DD}
 
 ## Include task snapshot
 
-If an active session exists (detected via `.claude/.active-session.json`), include a `## Tasks at capture time` section in the braindump artifact with a snapshot of the current `TodoWrite` state:
+If an active session exists (detected via `.claude/.active-session.json`), include a `## Tasks at capture time` section in the braindump body before piping it to `capture-context.mjs`:
 
 ```markdown
 ## Tasks at capture time
@@ -85,11 +91,11 @@ If an active session exists (detected via `.claude/.active-session.json`), inclu
 - [ ] Complete work
 ```
 
-Use the same GFM checkbox format as `session.md`'s `## Tasks` section (just `content` and `status` per task — no `activeForm` field, no blockquote line) and render it inline in the braindump. Do NOT call `sync-tasks.mjs --write` — braindumps are snapshots, not the canonical store.
+Use the same GFM checkbox format as `session.md`'s `## Tasks` section (just `content` and `status` per task — no `activeForm` field, no blockquote line). Do NOT call `sync-tasks.mjs --write` — braindumps are snapshots, not the canonical store.
 
 ## Updating Existing Braindumps
 
-When updating, rewrite as a fresh snapshot (coherent-revisions rule). The updated braindump should read as if written in one pass.
+When updating, rewrite as a fresh snapshot (coherent-revisions rule) and pass `--update` to `capture-context.mjs`. The updated braindump should read as if written in one pass.
 
 ## Key Differences from /handoff
 - `/handoff` is structured around work state (branch, status, next steps)
@@ -98,14 +104,14 @@ When updating, rewrite as a fresh snapshot (coherent-revisions rule). The update
 - Use `/braindump` when you're capturing a discussion or decision
 
 ## Auto-commit
-Same as `/handoff` — commit the file alone:
+Use the path that `capture-context.mjs` printed:
 ```bash
-git add shared-context/{path-to-file}
+git add {printed-path}
 git commit -m "braindump: {name}"
 ```
 
 ## Notes
-- User-scoped is the default
+- Per-user (`team-member/{user}/`) is the default scope
 - One topic, one file — don't mix unrelated ideas in one braindump
 - Drive-by ideas now use `/aside` instead of `/braindump side`
 - Auto-committing context files without user request is a workflow artifact — this intentionally bypasses the "do not commit unless asked" convention

package/template/.claude/skills/build-docs-site/SKILL.md

@@ -96,7 +96,7 @@ For the codebase:
 - Read actual implementations, not just existing docs about them
 
 For shared context:
-- Walk `shared-context/` for handoffs, braindumps, locked team knowledge, release notes
+- Walk `workspace-context/` for handoffs, braindumps, locked team knowledge, release notes
 
 For work-session history:
 - Walk `work-sessions/*/workspace/session.md` for any currently-active session trackers — their bodies may contain decisions not yet consumed into release notes

package/template/.claude/skills/build-docs-site/checklists/framing.md

@@ -52,7 +52,7 @@ For each selected option, **ask for specific paths**.
 
 > What other sources should I pull from?
 >
-> - Shared context files in the workspace
+> - Workspace-context files in the workspace
 > - Claude chat history from prior sessions on this project
 > - Notion export (zip)
 > - Confluence / wiki export

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

@@ -60,9 +60,9 @@ Formally read ALL sources before synthesizing — do not write release notes fro
    - `work-sessions/{session-name}/workspace/plan-*.md` files
    - Read each one fully
 
-3. **Handoffs** — any shared-context entries referencing this branch:
+3. **Handoffs** — any workspace-context entries referencing this branch:
    ```bash
-   grep -rl "branch: {branch}" shared-context/
+   grep -rl "branch: {branch}" workspace-context/
    ```
    Read each matching file.
 
@@ -249,6 +249,94 @@ cd repos/{repo} && git pull origin {repo-branch}
 cd {main-workspace-root} && git pull origin main
 ```
 
+**Step 10a.1: Tag the merge commit (release sessions only, project repos with `package.json`)**
+
+The next three sub-substeps run only when the session branch starts with `release/` — the convention for release sessions (e.g., `release/v0.15.0-beta.0`). For feature, bugfix, and chore sessions, skip 10a.1, 10a.2, and 10a.3 entirely; non-release sessions don't trigger publishes. Detection is purely by branch prefix.
+
+Derive the version tag from the branch name by stripping the `release/` prefix (so `release/v0.15.0-beta.0` yields `v0.15.0-beta.0`). For each project repo whose `package.json` declares a `version` field, verify that version matches the derived tag. The workspace repo is **never** tagged — only project repos with publishable `package.json` files get tagged, since the tag triggers `.github/workflows/publish.yml` in that project repo. If a project repo's `package.json` version doesn't match the release tag, skip that repo with a warning rather than failing the whole completion flow — the mismatch usually means `/release` was run against a different version than the branch name suggests, and the user needs to investigate before publishing.
+
+Before tagging, preflight against origin: if `v{version}` already exists remotely, surface the conflict to the user with three explicit recovery options — **Reuse** (skip to 10a.2 if the existing tag points at the right commit), **Replace** (`git push origin --delete v{version}` then re-run 10a.1), or **Investigate** (`gh release view v{version}` to see what shipped). Do **not** silently force-push the tag; an existing tag means a published artifact, and overwriting it without confirmation can corrupt the npm registry's view of the release history.
+
+If the tag is absent on origin, tag the merge commit (HEAD on `{default-branch}` after the prior `git pull origin {default-branch}`) and push the tag. The tag push triggers `.github/workflows/publish.yml`.
+
+```bash
+# Detect: only run for release sessions.
+if [[ ! "$branch" =~ ^release/ ]]; then
+  # Not a release session — skip 10a.1, 10a.2, 10a.3.
+  return
+fi
+
+# Extract the version from the branch name (release/v{X} → v{X}).
+version_tag="${branch#release/}"   # e.g. "v0.15.0-beta.0"
+
+# For each project repo with a package.json containing a version field:
+for repo in {project-repos-with-package-json}; do
+  cd repos/{repo}
+
+  # Verify package.json version matches the tag.
+  pkg_version=$(node -p "require('./package.json').version")
+  expected_version="${version_tag#v}"
+  if [ "$pkg_version" != "$expected_version" ]; then
+    echo "Skipping {repo}: package.json version ($pkg_version) does not match release tag ($expected_version)."
+    continue
+  fi
+
+  # Preflight: does the tag already exist on origin?
+  if git ls-remote --exit-code origin "refs/tags/$version_tag" >/dev/null 2>&1; then
+    # Tag exists. Surface to user with three options:
+    # 1. Reuse — skip to 10a.2 if the existing tag points at the right commit.
+    # 2. Replace — `git push origin --delete $version_tag` then re-run 10a.1.
+    # 3. Investigate — `gh release view $version_tag` to see what shipped.
+    # Do NOT silently force-push.
+    echo "Tag $version_tag already exists on origin. Aborting with recovery options."
+    return 1
+  fi
+
+  # Tag the merge commit (HEAD on default branch after the prior `git pull`).
+  git tag "$version_tag"
+  git push origin "$version_tag"   # Triggers .github/workflows/publish.yml
+done
+```
+
+**Step 10a.2: Watch the publish workflow (release sessions only)**
+
+For each project repo tagged in 10a.1, find and follow the `publish.yml` workflow run on GitHub. The workflow takes a moment to register against the new tag — poll `gh run list` up to 5 times with a 3-second backoff before giving up. Once the run is found, attach with `gh run watch` so the maintainer sees progress live alongside the unified summary. Append `|| true` to the watch command so a workflow failure does **not** abort the rest of `/complete-work`: the maintainer still needs to see the unified summary, including the failure URL, to decide whether to rerun, redo the release, or roll the tag back. If no run registers within the retry window, log a warning with the manual investigation command and continue.
+
+```bash
+# Retry up to 5 times with 3-second backoff — the run takes a moment to register.
+for i in 1 2 3 4 5; do
+  run_id=$(gh run list \
+    --repo {org}/{repo} \
+    --workflow publish.yml \
+    --branch "$version_tag" \
+    --limit 1 \
+    --json databaseId \
+    --jq '.[0].databaseId')
+  if [ -n "$run_id" ]; then break; fi
+  sleep 3
+done
+
+if [ -z "$run_id" ]; then
+  echo "Warning: no publish workflow run found for $version_tag after 15s. Investigate via 'gh run list'."
+else
+  gh run watch "$run_id" --exit-status --repo {org}/{repo} || true
+fi
+```
+
+**Step 10a.3: Update the unified summary (release sessions only)**
+
+The unified summary block presented earlier in Step 10a already has a section per project repo. For release sessions, append a `PUBLISH` section per tagged project repo to the same summary — this goes inside the existing summary, not in a new location, so the maintainer sees one consolidated report covering merges, tags, and npm publishes:
+
+```
+PUBLISH ({repo}):
+  Tag: v{version}
+  Workflow: {run-url}
+  Status: success | failure
+  Published: {dist-tag}@{version} on npm
+```
+
+Pull `Status` from the `gh run watch` exit code (success when the watch returned 0, failure otherwise). Pull `Published: {dist-tag}@{version}` from the workflow's published-package output if available; if the workflow failed before publishing, omit the `Published:` line and rely on `Status: failure` plus the workflow URL to point the maintainer at the failure.
+
 #### Step 10b: 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:
@@ -349,7 +437,7 @@ If /complete-work is called but changes were made without a formal work session
 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
+- **Hand off to someone** — create a team-visible handoff at root workspace-context/ for another member to pick up
 - **Revert** — undo the changes (with confirmation)
 
 ## Notes

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

@@ -1,11 +1,11 @@
 ---
 name: handoff
-description: Save workstream state as shared context. Use anytime during work to capture progress, decisions, and next steps. Accepts optional name parameter.
+description: Save workstream state as workspace-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.
+Save structured workstream state to workspace-context. Usable anytime, any number of times. Per-user (`team-member/{user}/`) is the default scope.
 
 ## Parameters
 - `/handoff {name}` — create or update a named handoff
@@ -28,34 +28,33 @@ When called within an active work session (the active-session pointer at `.claud
 
 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
+- Suggest starting a work session first, or use the helper with `--local-only`
 
 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}
----
+2. Ask: "Should this be user-scoped (default), team-visible, or local-only?"
+   - User-scoped (default): `--scope team-member --user {user}`
+   - Team-visible: `--scope shared`
+   - Local-only: add `--local-only` to either scope
+3. Use the centralized helper to compute the path, apply the `handoff_` prefix, and write the file with full frontmatter:
+
+```bash
+echo "$BODY" | node .claude/scripts/capture-context.mjs \
+  --type handoff \
+  --topic {kebab-case-name} \
+  --scope team-member \
+  --user {workspace.user} \
+  --description "{one-line summary}"
+```
+
+Pass `--update` to overwrite an existing handoff with the same name (otherwise the helper appends `-2`, `-3`, … to avoid clobbering). The helper prints the absolute path of the written file on stdout — use that path for the commit step.
 
+The body content sent on stdin should follow this template:
+
+```markdown
 ## Status
 {What was accomplished in this session}
 
@@ -69,9 +68,11 @@ updated: {YYYY-MM-DD}
 {Unresolved questions, if any}
 ```
 
-7. Auto-commit the handoff file alone:
+The helper writes the frontmatter (`state: ephemeral`, `lifecycle: active`, `type: handoff`, `topic`, `author`, `updated`). If you need extra fields like `branch:` or `repo:`, append them to the frontmatter after the helper writes (or include them inline in the body).
+
+4. Auto-commit the handoff file alone:
    ```bash
-   git add shared-context/{path-to-file}
+   git add {printed-path}
    git commit -m "handoff: {name}"
    ```
 
@@ -86,7 +87,7 @@ updated: {YYYY-MM-DD}
 
 ## Include task snapshot
 
-If an active session exists (detected via `.claude/.active-session.json`), include a `## Tasks at capture time` section in the handoff artifact with a snapshot of the current `TodoWrite` state:
+If an active session exists (detected via `.claude/.active-session.json`), include a `## Tasks at capture time` section in the handoff body before piping it to `capture-context.mjs`:
 
 ```markdown
 ## Tasks at capture time
@@ -97,16 +98,16 @@ If an active session exists (detected via `.claude/.active-session.json`), inclu
 - [ ] Complete work
 ```
 
-Use the same GFM checkbox format as `session.md`'s `## Tasks` section (just `content` and `status` per task — no `activeForm` field, no blockquote line) and render it inline in the handoff. Do NOT call `sync-tasks.mjs --write` — handoffs are snapshots, not the canonical store.
+Use the same GFM checkbox format as `session.md`'s `## Tasks` section (just `content` and `status` per task — no `activeForm` field, no blockquote line). Do NOT call `sync-tasks.mjs --write` — handoffs are snapshots, not the canonical store.
 
 ## 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.
+When updating an existing handoff, rewrite it as a fresh snapshot of current understanding (coherent-revisions rule) and pass `--update` to `capture-context.mjs`. 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.
+The helper updates the `updated` date in frontmatter automatically.
 
 ## Notes
-- User-scoped is the default — root is only for content deliberately made team-visible
+- Per-user is the default — `--scope shared` is 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