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

package/template/.claude/scripts/trackers/github-issues.test.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+// Tests for the GitHub Issues adapter. Uses an injected spawnFn to mock gh calls.
+// Run: node .claude/scripts/trackers/github-issues.test.mjs
+import { createTracker, AlreadyAssignedError } from './interface.mjs';
+
+let failed = 0, passed = 0;
+const ok = () => { passed++; };
+const fail = (msg) => { failed++; console.error(`  FAIL: ${msg}`); };
+
+// Build a spawnFn that returns canned responses keyed by argv.
+function buildSpawn(responses) {
+  const calls = [];
+  const fn = (cmd, args, options) => {
+    calls.push({ cmd, args, input: options?.input });
+    const key = args.join(' ');
+    const resp = responses[key];
+    if (!resp) {
+      return { status: 1, stdout: '', stderr: `no mock for: ${cmd} ${key}` };
+    }
+    return { status: 0, stdout: resp, stderr: '' };
+  };
+  fn.calls = calls;
+  return fn;
+}
+
+// listAssignedToMe normalizes JSON into Issue[].
+{
+  const spawnFn = buildSpawn({
+    'api user --jq .login': 'alice\n',
+    'issue list --repo foo/bar --assignee alice --state open --json number,title,body,state,assignees,labels,milestone,url,createdAt,updatedAt':
+      JSON.stringify([{ number: 1, title: 'Fix bug', body: 'details', state: 'OPEN', assignees: [{ login: 'alice' }], labels: [{ name: 'bug' }], milestone: { title: 'v0.1' }, url: 'https://github.com/foo/bar/issues/1', createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-01-02T00:00:00Z' }]),
+  });
+  const t = createTracker({ type: 'github-issues', repo: 'foo/bar' }, { spawnFn });
+  const issues = await t.listAssignedToMe();
+  if (issues.length === 1 && issues[0].id === 'gh:1' && issues[0].assignees[0] === 'alice'
+      && issues[0].labels[0] === 'bug' && issues[0].milestone === 'v0.1') ok();
+  else fail(`listAssignedToMe normalization wrong: ${JSON.stringify(issues)}`);
+}
+
+// listUnassigned uses no:assignee search.
+{
+  const spawnFn = buildSpawn({
+    'api user --jq .login': 'alice\n',
+    'issue list --repo foo/bar --search no:assignee --state open --json number,title,body,state,assignees,labels,milestone,url,createdAt,updatedAt':
+      JSON.stringify([{ number: 2, title: 'Open work', body: '', state: 'OPEN', assignees: [], labels: [], milestone: null, url: 'https://github.com/foo/bar/issues/2', createdAt: '2026-01-03T00:00:00Z', updatedAt: '2026-01-03T00:00:00Z' }]),
+  });
+  const t = createTracker({ type: 'github-issues', repo: 'foo/bar' }, { spawnFn });
+  const issues = await t.listUnassigned();
+  if (issues.length === 1 && issues[0].id === 'gh:2' && issues[0].assignees.length === 0) ok();
+  else fail(`listUnassigned wrong: ${JSON.stringify(issues)}`);
+}
+
+// claim throws AlreadyAssignedError when a different user is assigned.
+{
+  const spawnFn = buildSpawn({
+    'api user --jq .login': 'alice\n',
+    'issue view 3 --repo foo/bar --json number,title,body,state,assignees,labels,milestone,url,createdAt,updatedAt':
+      JSON.stringify({ number: 3, title: 't', body: '', state: 'OPEN', assignees: [{ login: 'bob' }], labels: [], milestone: null, url: 'u', createdAt: 'd', updatedAt: 'd' }),
+  });
+  const t = createTracker({ type: 'github-issues', repo: 'foo/bar' }, { spawnFn });
+  try { await t.claim('gh:3'); fail('claim should have thrown'); }
+  catch (e) { if (e instanceof AlreadyAssignedError && e.assignees[0] === 'bob') ok(); else fail(`wrong error: ${e}`); }
+}
+
+// claim is idempotent when already assigned to me.
+{
+  const spawnFn = buildSpawn({
+    'api user --jq .login': 'alice\n',
+    'issue view 4 --repo foo/bar --json number,title,body,state,assignees,labels,milestone,url,createdAt,updatedAt':
+      JSON.stringify({ number: 4, title: 't', body: '', state: 'OPEN', assignees: [{ login: 'alice' }], labels: [], milestone: null, url: 'u', createdAt: 'd', updatedAt: 'd' }),
+  });
+  const t = createTracker({ type: 'github-issues', repo: 'foo/bar' }, { spawnFn });
+  const issue = await t.claim('gh:4');
+  const edited = spawnFn.calls.some(c => c.args.includes('edit') && c.args.includes('--add-assignee'));
+  if (issue.id === 'gh:4' && !edited) ok();
+  else fail(`claim should be no-op when already assigned: edited=${edited}`);
+}
+
+// claim assigns when unassigned.
+{
+  const viewResponse = JSON.stringify({ number: 5, title: 't', body: '', state: 'OPEN', assignees: [], labels: [], milestone: null, url: 'u', createdAt: 'd', updatedAt: 'd' });
+  const viewAssigned = JSON.stringify({ number: 5, title: 't', body: '', state: 'OPEN', assignees: [{ login: 'alice' }], labels: [], milestone: null, url: 'u', createdAt: 'd', updatedAt: 'd' });
+  let viewCallCount = 0;
+  const spawnFn = (cmd, args, options) => {
+    const key = args.join(' ');
+    if (key === 'api user --jq .login') return { status: 0, stdout: 'alice\n', stderr: '' };
+    if (key === 'issue view 5 --repo foo/bar --json number,title,body,state,assignees,labels,milestone,url,createdAt,updatedAt') {
+      viewCallCount++;
+      return { status: 0, stdout: viewCallCount === 1 ? viewResponse : viewAssigned, stderr: '' };
+    }
+    if (key === 'issue edit 5 --repo foo/bar --add-assignee alice') return { status: 0, stdout: '', stderr: '' };
+    return { status: 1, stdout: '', stderr: `no mock: ${key}` };
+  };
+  const t = createTracker({ type: 'github-issues', repo: 'foo/bar' }, { spawnFn });
+  const issue = await t.claim('gh:5');
+  if (issue.assignees[0] === 'alice') ok();
+  else fail(`claim should assign: ${JSON.stringify(issue)}`);
+}
+
+// createIssue parses issue number from URL.
+{
+  const spawnFn = (cmd, args, options) => {
+    const key = args.join(' ');
+    if (key.startsWith('issue create --repo foo/bar')) {
+      return { status: 0, stdout: 'https://github.com/foo/bar/issues/99\n', stderr: '' };
+    }
+    if (key === 'issue view 99 --repo foo/bar --json number,title,body,state,assignees,labels,milestone,url,createdAt,updatedAt') {
+      return { status: 0, stdout: JSON.stringify({ number: 99, title: 'New', body: 'b', state: 'OPEN', assignees: [], labels: [{ name: 'chore' }], milestone: null, url: 'https://github.com/foo/bar/issues/99', createdAt: 'd', updatedAt: 'd' }), stderr: '' };
+    }
+    return { status: 1, stdout: '', stderr: `no mock: ${key}` };
+  };
+  const t = createTracker({ type: 'github-issues', repo: 'foo/bar' }, { spawnFn });
+  const issue = await t.createIssue({ title: 'New', body: 'b', labels: ['chore'] });
+  if (issue.id === 'gh:99') ok();
+  else fail(`createIssue wrong: ${JSON.stringify(issue)}`);
+}
+
+// ensureLabels calls gh label create --force for each of the six standard labels.
+{
+  const created = [];
+  const spawnFn = (cmd, args) => {
+    if (args[0] === 'label' && args[1] === 'create') {
+      created.push(args[2]);
+      return { status: 0, stdout: '', stderr: '' };
+    }
+    return { status: 1, stdout: '', stderr: 'no mock' };
+  };
+  const t = createTracker({ type: 'github-issues', repo: 'foo/bar' }, { spawnFn });
+  await t.ensureLabels();
+  const expected = ['bug', 'feat', 'chore', 'P1', 'P2', 'P3'];
+  if (JSON.stringify(created.sort()) === JSON.stringify(expected.sort())) ok();
+  else fail(`ensureLabels wrong: ${JSON.stringify(created)}`);
+}
+
+// gh failure surfaces stderr.
+{
+  const spawnFn = () => ({ status: 1, stdout: '', stderr: 'gh is on fire' });
+  const t = createTracker({ type: 'github-issues', repo: 'foo/bar' }, { spawnFn });
+  try { await t.listUnassigned(); fail('should have thrown'); }
+  catch (e) { if (/gh is on fire/.test(e.message)) ok(); else fail(`wrong error: ${e.message}`); }
+}
+
+// ensureMilestone returns existing milestone without POST when title matches.
+{
+  const calls = [];
+  const spawnFn = (cmd, args) => {
+    calls.push(args.join(' '));
+    const key = args.join(' ');
+    if (key === 'api repos/foo/bar/milestones?state=all&per_page=100') {
+      return { status: 0, stdout: JSON.stringify([
+        { number: 1, title: 'Backlog', description: 'Triage later', state: 'open', due_on: null, html_url: 'https://github.com/foo/bar/milestone/1' },
+      ]), stderr: '' };
+    }
+    return { status: 1, stdout: '', stderr: `no mock: ${key}` };
+  };
+  const t = createTracker({ type: 'github-issues', repo: 'foo/bar' }, { spawnFn });
+  const ms = await t.ensureMilestone({ title: 'Backlog' });
+  const posted = calls.some(c => c.includes('-X POST'));
+  if (ms.title === 'Backlog' && ms.number === 1 && !posted) ok();
+  else fail(`ensureMilestone should return existing without POST: posted=${posted}, ms=${JSON.stringify(ms)}`);
+}
+
+// ensureMilestone creates when title does not exist.
+{
+  const spawnFn = (cmd, args) => {
+    const key = args.join(' ');
+    if (key === 'api repos/foo/bar/milestones?state=all&per_page=100') {
+      return { status: 0, stdout: JSON.stringify([]), stderr: '' };
+    }
+    if (key.startsWith('api repos/foo/bar/milestones -X POST')) {
+      return { status: 0, stdout: JSON.stringify({ number: 2, title: 'v0.1', description: 'alpha', state: 'open', due_on: null, html_url: 'https://github.com/foo/bar/milestone/2' }), stderr: '' };
+    }
+    return { status: 1, stdout: '', stderr: `no mock: ${key}` };
+  };
+  const t = createTracker({ type: 'github-issues', repo: 'foo/bar' }, { spawnFn });
+  const ms = await t.ensureMilestone({ title: 'v0.1', description: 'alpha' });
+  if (ms.title === 'v0.1' && ms.number === 2 && ms.description === 'alpha') ok();
+  else fail(`ensureMilestone should create when absent: ${JSON.stringify(ms)}`);
+}
+
+// ensureMilestone rejects missing title.
+{
+  const spawnFn = () => ({ status: 0, stdout: '[]', stderr: '' });
+  const t = createTracker({ type: 'github-issues', repo: 'foo/bar' }, { spawnFn });
+  try { await t.ensureMilestone({}); fail('should have thrown'); }
+  catch (e) { if (/title is required/.test(e.message)) ok(); else fail(`wrong error: ${e.message}`); }
+}
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/template/.claude/scripts/trackers/interface.mjs

@@ -0,0 +1,25 @@
+// Tracker adapter interface. Skills import only from this module.
+// See design-tracker-abstraction.md for the full Issue shape and method contracts.
+
+import { createGithubAdapter } from './github-issues.mjs';
+
+export class AlreadyAssignedError extends Error {
+  constructor(issueId, assignees) {
+    super(`${issueId} is already assigned to ${assignees.join(', ')}`);
+    this.name = 'AlreadyAssignedError';
+    this.code = 'ALREADY_ASSIGNED';
+    this.assignees = assignees;
+  }
+}
+
+export function createTracker(config, options = {}) {
+  if (!config || typeof config !== 'object') {
+    throw new Error('No tracker configured — pass workspace.json\'s workspace.tracker block.');
+  }
+  switch (config.type) {
+    case 'github-issues':
+      return createGithubAdapter(config, options);
+    default:
+      throw new Error(`Unknown tracker type: ${config.type}`);
+  }
+}

package/template/.claude/scripts/trackers/interface.test.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// Tests for the tracker factory and AlreadyAssignedError.
+// Run: node .claude/scripts/trackers/interface.test.mjs
+import { createTracker, AlreadyAssignedError } from './interface.mjs';
+
+let failed = 0, passed = 0;
+const ok = (msg) => { passed++; };
+const fail = (msg) => { failed++; console.error(`  FAIL: ${msg}`); };
+
+// AlreadyAssignedError carries assignees and a code.
+{
+  const err = new AlreadyAssignedError('gh:42', ['alice', 'bob']);
+  if (err.code === 'ALREADY_ASSIGNED' && JSON.stringify(err.assignees) === '["alice","bob"]'
+      && err.message.includes('gh:42') && err.message.includes('alice')) ok();
+  else fail('AlreadyAssignedError should carry code and assignees');
+}
+
+// createTracker rejects missing config.
+{
+  try { createTracker(); fail('should throw on missing config'); }
+  catch (e) { if (/No tracker configured/.test(e.message)) ok(); else fail(`wrong error: ${e.message}`); }
+}
+
+// createTracker rejects unknown type.
+{
+  try { createTracker({ type: 'nope' }); fail('should throw on unknown type'); }
+  catch (e) { if (/Unknown tracker type/.test(e.message)) ok(); else fail(`wrong error: ${e.message}`); }
+}
+
+// createTracker builds a github-issues adapter without calling gh at construction (lazy).
+{
+  const fakeSpawn = () => { throw new Error('spawn should not run at construction'); };
+  // With repo: 'foo/bar' literal, the adapter should NOT shell out to resolve the remote.
+  const adapter = createTracker({ type: 'github-issues', repo: 'foo/bar' }, { spawnFn: fakeSpawn });
+  if (adapter.identity === 'github-issues:foo/bar') ok();
+  else fail(`unexpected identity: ${adapter.identity}`);
+}
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/template/.claude/settings.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/workspace-update-check.mjs",
+            "timeout": 5000,
+            "statusMessage": "Checking for workspace updates..."
+          },
+          {
+            "type": "command",
+            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/session-start.mjs",
+            "timeout": 30000,
+            "statusMessage": "Syncing workspace..."
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/subagent-start.mjs",
+            "timeout": 5000,
+            "statusMessage": "Loading shared context..."
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/pre-compact.mjs",
+            "timeout": 5000,
+            "statusMessage": "Checking for uncaptured context..."
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/post-compact.mjs",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/workspace-update-check.mjs",
+            "timeout": 5000
+          },
+          {
+            "type": "command",
+            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/repo-write-detection.mjs",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/session-end.mjs",
+            "timeout": 15000,
+            "statusMessage": "Saving session state..."
+          }
+        ]
+      }
+    ],
+    "WorktreeCreate": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(if command -v cygpath >/dev/null 2>&1; then cygpath -u \"$CLAUDE_PROJECT_DIR\"; else echo \"$CLAUDE_PROJECT_DIR\"; fi)\"/.claude/hooks/worktree-create.mjs",
+            "timeout": 5000,
+            "statusMessage": "Checking for stale worktrees..."
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Bash(git:*)",
+      "Bash(ls:*)"
+    ]
+  },
+  "enabledPlugins": {
+    "playwright@claude-plugins-official": false
+  }
+}

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

@@ -0,0 +1,125 @@
+---
+name: aside
+description: Capture a drive-by idea without interrupting your current work. Dispatches a background researcher by default, or use --quick for a simple note. Usage: /aside [--quick] <your thought>
+---
+
+# Aside
+
+Capture a drive-by idea without interrupting the current conversation. By default, dispatches a background subagent to research and expand the idea. Use `--quick` for a simple note with no research.
+
+## Parameters
+
+- `/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.
+
+## 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`"
+
+### Quick Mode Template
+
+```yaml
+---
+state: ephemeral
+lifecycle: active
+type: braindump
+variant: aside
+author: {user}
+updated: {YYYY-MM-DD}
+---
+
+## User's Original Thought
+{Verbatim text from the user — copy exactly as provided}
+
+## Further Investigation
+{2-3 bullet points: threads worth pulling on, questions to explore,
+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:
+   - `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 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
+
+### Research Mode 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}
+---
+
+## User's Original Thought
+{Verbatim text from the user — copy exactly as provided, never paraphrase}
+
+## Agent Research
+{Findings from the workspace, project repos, and web.
+References specific file paths and prior art.
+Structured as prose or sub-headings as the content demands.}
+
+## Synthesis
+{How the user's thought connects to what was found.
+Proposed next steps, design considerations.
+Clearly framed as agent analysis, not user intent.}
+
+## Further Investigation
+{Threads worth pulling on. What the agent couldn't answer.
+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
+
+## Session Behavior
+
+Asides are session-agnostic. Regardless of whether a work session is active:
+- Files always go to `shared-context/{user}/`
+- No interaction with the session tracker
+- No interaction with `/complete-work` synthesis
+
+## Lifecycle
+
+Asides stay as `local-only-*` files until deliberately promoted:
+- `/promote` discovers them during its `local-only-*` scan
+- `/maintenance` can flag stale asides
+- `variant: aside` frontmatter distinguishes them from other local-only files
+
+## Notes
+
+- The subagent receives locked context automatically via the SubagentStart hook
+- The subagent does NOT receive conversation history — the user provides context inline as part of their thought
+- Asides never modify existing files
+- One aside = one file, always

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

@@ -0,0 +1,96 @@
+---
+name: braindump
+description: Capture discussion-heavy topics into shared 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.
+
+## Parameters
+- `/braindump {name}` — create or update a named braindump
+- `/braindump` (no param) — analyze session and suggest name(s)
+
+> **Note:** `/braindump side` has moved to `/aside`. If the user invokes `/braindump side`, redirect them: "The side braindump is now `/aside`. Running it for you." Then invoke the `/aside` skill with their text.
+
+## Session-Aware Behavior
+
+When called within an active work session (the active-session pointer at `.claude/.active-session.json` exists inside the current worktree):
+
+- Default behavior: append reasoning and decisions to the session tracker body at `work-sessions/{session-name}/workspace/session.md`
+- Add a new section to the tracker body (Context, Exploration, Decisions, Implications) — do NOT touch the frontmatter
+- Auto-commit from inside the worktree so the update lands on the session branch:
+  ```bash
+  cd work-sessions/{session-name}/workspace
+  git add session.md
+  git commit -m "braindump: update {session-name} tracker"
+  ```
+
+When called from the workspace root (no active session):
+- Create a `local-only-{name}.md` file (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:
+
+```yaml
+---
+state: ephemeral
+lifecycle: active
+type: braindump
+topic: {name}
+author: {user}
+updated: {YYYY-MM-DD}
+---
+
+## Context
+{What prompted this discussion}
+
+## Exploration
+{What options were considered, what was researched}
+
+## Decisions
+{What was decided and why — include tradeoffs that were weighed}
+
+## Implications
+{What this decision means for future work}
+```
+
+## Flow: Side Braindump (deprecated)
+
+`/braindump side` has been replaced by the `/aside` skill. If invoked:
+1. Inform the user: "The side braindump is now `/aside`. Running it for you."
+2. Invoke the `/aside` skill with the user's text
+
+## Flow: No Parameter
+
+1. Analyze the current session: what discussion topics are in play?
+2. If one clear topic: suggest a name, ask to confirm
+3. If multiple topics: "I see discussion about {topic-1} and {topic-2}. Split into separate braindumps?"
+4. Proceed with named flow for each
+
+## Updating Existing Braindumps
+
+When updating, rewrite as a fresh snapshot (coherent-revisions rule). 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)
+- `/braindump` is structured around reasoning (context, exploration, decisions, implications)
+- Use `/handoff` when you're tracking a workstream
+- Use `/braindump` when you're capturing a discussion or decision
+
+## Auto-commit
+Same as `/handoff` — commit the file alone:
+```bash
+git add shared-context/{path-to-file}
+git commit -m "braindump: {name}"
+```
+
+## Notes
+- User-scoped is the default
+- 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