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

package/template/.claude/lib/session-frontmatter.test.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+// Unit tests for session-frontmatter.mjs
+// Run: node template/.claude/lib/session-frontmatter.test.mjs
+import {
+  parseSessionContent,
+  updateSessionContent,
+} from './session-frontmatter.mjs';
+
+let failed = 0;
+let passed = 0;
+
+function assert(cond, msg) {
+  if (cond) {
+    passed++;
+  } else {
+    failed++;
+    console.error(`  FAIL: ${msg}`);
+  }
+}
+
+function assertEq(actual, expected, msg) {
+  const a = JSON.stringify(actual);
+  const e = JSON.stringify(expected);
+  if (a === e) {
+    passed++;
+  } else {
+    failed++;
+    console.error(`  FAIL: ${msg}\n    expected: ${e}\n    actual:   ${a}`);
+  }
+}
+
+const SAMPLE = `---
+type: session-tracker
+name: fix-auth
+description: Fix the auth timeout on mobile
+status: active
+branch: bugfix/fix-auth
+created: 2026-04-13T05:33:50.000Z
+user: alice
+repos:
+  - my-app
+  - my-api
+workItem: 3
+chatSessions:
+  - id: aa3c952e-dbff-4055-8bcc-e5f217618d57
+    names: [pickup-from-braindump]
+    started: 2026-04-13T05:33:50.000Z
+    ended: 2026-04-13T07:12:00.000Z
+  - id: bb4d063e-ec00-4166-cc71-cd3d3d4628a1
+    names: []
+    started: 2026-04-13T08:00:00.000Z
+    ended: null
+author: alice
+updated: 2026-04-13
+---
+
+# Work Session: fix-auth
+
+Brief one-liner.
+
+## Progress
+
+Some prose.
+`;
+
+// === Test 1: parse all field types ===
+console.log('Test 1: parse all field types');
+{
+  const parsed = parseSessionContent(SAMPLE);
+  assertEq(parsed.fields.type, 'session-tracker', 'type');
+  assertEq(parsed.fields.name, 'fix-auth', 'name');
+  assertEq(parsed.fields.description, 'Fix the auth timeout on mobile', 'description');
+  assertEq(parsed.fields.status, 'active', 'status');
+  assertEq(parsed.fields.branch, 'bugfix/fix-auth', 'branch');
+  assertEq(parsed.fields.created, '2026-04-13T05:33:50.000Z', 'created (ISO timestamp unquoted)');
+  assertEq(parsed.fields.workItem, 3, 'workItem (integer)');
+  assertEq(parsed.fields.repos, ['my-app', 'my-api'], 'repos (flat list)');
+  assertEq(parsed.fields.chatSessions.length, 2, 'chatSessions length');
+  assertEq(parsed.fields.chatSessions[0].id, 'aa3c952e-dbff-4055-8bcc-e5f217618d57', 'chat 0 id');
+  assertEq(parsed.fields.chatSessions[0].names, ['pickup-from-braindump'], 'chat 0 names');
+  assertEq(parsed.fields.chatSessions[0].started, '2026-04-13T05:33:50.000Z', 'chat 0 started');
+  assertEq(parsed.fields.chatSessions[0].ended, '2026-04-13T07:12:00.000Z', 'chat 0 ended');
+  assertEq(parsed.fields.chatSessions[1].id, 'bb4d063e-ec00-4166-cc71-cd3d3d4628a1', 'chat 1 id');
+  assertEq(parsed.fields.chatSessions[1].names, [], 'chat 1 names (empty inline list)');
+  assertEq(parsed.fields.chatSessions[1].ended, null, 'chat 1 ended (null)');
+  assert(parsed.body.startsWith('\n# Work Session'), 'body starts with blank line + H1');
+  assert(parsed.body.endsWith('Some prose.\n'), 'body ends with trailing newline');
+}
+
+// === Test 2: lossless byte-identity on no-op update ===
+console.log('Test 2: lossless byte-identity on no-op update');
+{
+  const unchanged = updateSessionContent(SAMPLE, {});
+  assertEq(unchanged, SAMPLE, 'no-op update preserves content byte-identical');
+}
+
+// === Test 3: update single scalar field ===
+console.log('Test 3: update single scalar field');
+{
+  const updated = updateSessionContent(SAMPLE, { status: 'paused' });
+  const parsed = parseSessionContent(updated);
+  assertEq(parsed.fields.status, 'paused', 'status changed');
+  assertEq(parsed.fields.name, 'fix-auth', 'name preserved');
+  assertEq(parsed.fields.repos, ['my-app', 'my-api'], 'repos preserved');
+  assertEq(parsed.fields.chatSessions.length, 2, 'chatSessions preserved');
+  // Verify every other line is byte-identical
+  const origLines = SAMPLE.split('\n');
+  const newLines = updated.split('\n');
+  assertEq(newLines.length, origLines.length, 'same number of lines');
+  for (let i = 0; i < origLines.length; i++) {
+    if (origLines[i].startsWith('status:')) {
+      assertEq(newLines[i], 'status: paused', `line ${i} is new status`);
+    } else {
+      assertEq(newLines[i], origLines[i], `line ${i} preserved`);
+    }
+  }
+}
+
+// === Test 4: update chatSessions array (append a chat) ===
+console.log('Test 4: update chatSessions array');
+{
+  const parsed = parseSessionContent(SAMPLE);
+  const newChats = [...parsed.fields.chatSessions, {
+    id: 'cc5e174f-fd11-5277-dd82-de4e4e5739b2',
+    names: [],
+    started: '2026-04-13T09:00:00.000Z',
+    ended: null,
+  }];
+  const updated = updateSessionContent(SAMPLE, { chatSessions: newChats });
+  const reparsed = parseSessionContent(updated);
+  assertEq(reparsed.fields.chatSessions.length, 3, 'chatSessions now has 3 entries');
+  assertEq(reparsed.fields.chatSessions[2].id, 'cc5e174f-fd11-5277-dd82-de4e4e5739b2', 'new chat id');
+  assertEq(reparsed.fields.name, 'fix-auth', 'other fields preserved');
+  assertEq(reparsed.body, parsed.body, 'body preserved byte-identical');
+}
+
+// === Test 5: append a new field ===
+console.log('Test 5: append a new field');
+{
+  const updated = updateSessionContent(SAMPLE, { newField: 'hello' });
+  const parsed = parseSessionContent(updated);
+  assertEq(parsed.fields.newField, 'hello', 'newField present');
+  assertEq(parsed.fields.name, 'fix-auth', 'existing field preserved');
+}
+
+// === Test 6: remove a field ===
+console.log('Test 6: remove a field');
+{
+  const updated = updateSessionContent(SAMPLE, { workItem: undefined });
+  const parsed = parseSessionContent(updated);
+  assertEq(parsed.fields.workItem, undefined, 'workItem removed');
+  assertEq(parsed.fields.user, 'alice', 'user preserved');
+}
+
+// === Test 7: update repos (flat list) ===
+console.log('Test 7: update repos flat list');
+{
+  const updated = updateSessionContent(SAMPLE, { repos: ['my-app', 'my-api', 'my-web'] });
+  const parsed = parseSessionContent(updated);
+  assertEq(parsed.fields.repos, ['my-app', 'my-api', 'my-web'], 'repos has 3 items');
+  assertEq(parsed.fields.chatSessions.length, 2, 'chatSessions preserved after repos update');
+}
+
+// === Test 8: empty repos ===
+console.log('Test 8: empty repos');
+{
+  const updated = updateSessionContent(SAMPLE, { repos: [] });
+  const parsed = parseSessionContent(updated);
+  assertEq(parsed.fields.repos, [], 'repos is empty');
+}
+
+// === Test 9: scalar with special chars (colon in branch name) ===
+console.log('Test 9: scalar with special chars');
+{
+  // Branch names with slashes should NOT be quoted
+  const sample = `---
+branch: feature/worksessions-refactor
+---
+body
+`;
+  const parsed = parseSessionContent(sample);
+  assertEq(parsed.fields.branch, 'feature/worksessions-refactor', 'branch unquoted');
+  const noop = updateSessionContent(sample, {});
+  assertEq(noop, sample, 'no-op preserves unquoted slash');
+}
+
+// === Test 10: ISO timestamp round-trip ===
+console.log('Test 10: ISO timestamp round-trip');
+{
+  const sample = `---
+created: 2026-04-13T05:33:50.000Z
+---
+body
+`;
+  const parsed = parseSessionContent(sample);
+  assertEq(parsed.fields.created, '2026-04-13T05:33:50.000Z', 'ISO timestamp parsed');
+  const updated = updateSessionContent(sample, { created: '2026-05-01T12:00:00.000Z' });
+  const reparsed = parseSessionContent(updated);
+  assertEq(reparsed.fields.created, '2026-05-01T12:00:00.000Z', 'ISO timestamp round-trip');
+  // Must not be quoted
+  assert(!updated.includes('"2026-05-01'), 'ISO timestamp not quoted on write');
+}
+
+// === Test 11: string that truly needs quoting ===
+console.log('Test 11: string that truly needs quoting');
+{
+  const sample = `---
+title: hello
+---
+body
+`;
+  const updated = updateSessionContent(sample, { title: 'hello: world' });
+  assert(updated.includes('title: "hello: world"'), 'colon-space triggers quoting');
+  const reparsed = parseSessionContent(updated);
+  assertEq(reparsed.fields.title, 'hello: world', 'quoted value round-trips');
+}
+
+// === Test 12: body preservation with multiline content ===
+console.log('Test 12: body preservation with multiline content');
+{
+  const sample = `---
+name: test
+---
+
+# Heading
+
+Paragraph with multiple lines.
+And more lines.
+
+- bullet 1
+- bullet 2
+`;
+  const noop = updateSessionContent(sample, {});
+  assertEq(noop, sample, 'multiline body preserved byte-identical');
+  const updated = updateSessionContent(sample, { name: 'changed' });
+  const parsed = parseSessionContent(updated);
+  assertEq(parsed.body.trim(), '# Heading\n\nParagraph with multiple lines.\nAnd more lines.\n\n- bullet 1\n- bullet 2', 'body intact after update');
+}
+
+// === Summary ===
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/template/.claude/recipes/migrate-from-notion.md

@@ -0,0 +1,120 @@
+# Recipe: Migrate from Notion
+
+Migrate rules, memory, and handoffs from Notion pages into the claude-workspace template structure.
+
+## Prerequisites
+
+- The workspace must have a working Notion MCP server configured in `.mcp.json`
+- Run this recipe BEFORE removing the MCP server
+- The scaffolder (`npx @ulysses-ai/create-workspace --init`) should have already been run to install the template structure
+
+## Detection
+
+This recipe applies when:
+- `.mcp.json` contains a Notion MCP server configuration
+- `CLAUDE.md` (or `.bak`) references Notion page IDs for rules, memory, or handoffs
+
+## Steps
+
+### 1. Identify Notion pages
+
+Read `CLAUDE.md.bak` (the pre-migration backup) to find Notion page references:
+- Look for page IDs (32-character hex strings)
+- Note the purpose of each page (rules, memory/context, handoffs)
+
+### 2. Extract rules
+
+For each Notion page that contains rules/conventions:
+
+```
+Fetch the page content using the Notion MCP server.
+For each rule or convention section:
+  - Create a .claude/rules/{rule-name}.md file
+  - Use the section heading as the filename (kebab-case)
+  - If the rule is project-specific, make it mandatory (.md)
+  - If the rule is optional, use .md.skip
+  - Write the content as a coherent rule following the template format:
+    # Rule Name
+    {What the rule says}
+    ## Why
+    {Rationale if provided}
+```
+
+### 3. Extract memory and context
+
+For each Notion page that contains project memory, context, or key decisions:
+
+```
+Fetch the page content using the Notion MCP server.
+Determine scope:
+  - Architecture decisions, tech stack, stable conventions → shared-context/locked/
+  - Active project state, current priorities → shared-context/{user}/
+  - Historical context no longer relevant → skip
+
+For each section:
+  - Create a shared-context file with proper frontmatter:
+    ---
+    state: locked (or ephemeral)
+    lifecycle: active
+    type: promoted
+    topic: {section-topic}
+    author: {user}
+    updated: {today}
+    ---
+  - Write content adapted for the template format
+  - One topic per file — split large Notion pages into multiple files
+```
+
+### 4. Extract handoffs
+
+For each Notion page that contains session handoffs or context transfers:
+
+```
+Fetch the page content using the Notion MCP server.
+For recent/active handoffs only (skip stale ones):
+  - Create shared-context/{user}/{handoff-name}.md
+  - Use handoff frontmatter format with type: handoff
+  - Extract: status, key decisions, next steps, open questions
+  - Set lifecycle: active (or paused if the work is suspended)
+```
+
+### 5. Preserve local preferences
+
+Check `CLAUDE.md.bak` for local preferences that aren't Notion-dependent:
+- Repo paths, coding conventions, project-specific notes
+- Add these to appropriate places:
+  - Coding conventions → `.claude/rules/` (new rule file)
+  - Project notes → `shared-context/locked/` or `shared-context/{user}/`
+  - Repo paths → already in `workspace.json`
+
+### 6. Remove Notion dependency
+
+After all content is extracted and verified:
+
+```bash
+# Back up and remove MCP config
+mv .mcp.json .mcp.json.bak
+
+# Remove CLAUDE.md backup (original Notion-fetching version)
+rm CLAUDE.md.bak
+```
+
+Verify the workspace works without Notion:
+- Start a new Claude Code session
+- Confirm SessionStart hook surfaces the migrated context
+- Confirm rules are loaded (check /context)
+- Confirm skills work
+
+### 7. Commit
+
+```bash
+git add .claude/rules/ shared-context/
+git commit -m "chore: migrate Notion content to local files"
+```
+
+## Notes
+
+- Don't try to migrate everything — only active, relevant content
+- Stale Notion handoffs can be skipped. If it's more than a few weeks old and not referenced, it's dead.
+- Large Notion pages should be split into multiple focused files (one topic per file)
+- The migration is one-way — once verified, the Notion pages become the archive, not the source of truth

package/template/.claude/rules/agent-rules.md.skip

@@ -0,0 +1,32 @@
+# Agent Rules
+
+Activate this rule to enforce conventions specifically for subagent behavior.
+
+## All Agents
+
+- Follow the coherent-revisions rule — rewrite sections from scratch, never inject
+- Report status using the standard protocol: DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT
+- If anything is ambiguous, ask before proceeding — don't guess
+- Stay within the scope of the task description — don't explore beyond what was asked
+
+## Implementer Agents
+
+- Receive full task text in the prompt — never read plan files directly
+- Keep changes minimal and focused on the assigned task
+- Don't restructure code outside the task scope
+- Commit frequently with conventional commit messages
+- It is always OK to say "this is too complex for a single task"
+
+## Reviewer Agents
+
+- Review only what changed — don't comment on pre-existing code
+- Don't suggest improvements outside the diff scope
+- Be specific: file, line, what's wrong, what to do instead
+- Style preferences defer to linters/formatters — don't enforce personal taste
+
+## Researcher Agents
+
+- Never modify files — read-only operations only
+- Search thoroughly before reporting "not found"
+- Report with exact file paths and line numbers
+- Flag contradictions between code and documentation

package/template/.claude/rules/cloud-infrastructure.md.skip

@@ -0,0 +1,15 @@
+# Cloud Infrastructure
+
+Activate this rule if the project uses cloud resources (AWS, GCP, Azure, etc.).
+
+## Code-First Rule
+
+- All changes to cloud resources go through code and CI/CD
+- Never recommend or execute direct cloud provider changes — no console edits, no CLI commands against live resources
+- If the user asks to do something directly in the cloud provider, warn about drift and recommend the code-first path
+
+## Environment Portability
+
+- Never hardcode account IDs, resource ARNs/URIs, bucket names, distribution IDs, or environment-specific values
+- All environment-specific values come from environment config files or runtime CI/CD variables
+- This applies to infrastructure code, configuration files, workflow files, and function code

package/template/.claude/rules/coherent-revisions.md

@@ -0,0 +1,24 @@
+# Coherent Revisions
+
+When revising any document or code, rewrite the affected section from start to finish so the result reads as a single coherent piece. Never patch, inject, or insert new content between existing paragraphs/blocks in a way that creates a stitched-together feel.
+
+This applies to all written output:
+- Project documentation
+- Specs and design docs
+- Code and logic changes including comments
+- Shared context documents (handoffs, braindumps, locked context)
+- Release notes
+- Open questions
+- Commit messages
+
+## Why
+
+Injected revisions create fragmented, hard-to-follow output where the seams between old and new content are visible. Rewriting from start to finish produces output that flows naturally and reads as if written in one pass.
+
+## In Practice
+
+- When updating a section of a document, rewrite the entire section — not just the changed sentences
+- When updating a shared-context file, rewrite it as a fresh snapshot of current understanding
+- When synthesizing multiple sources into release notes, write the narrative from scratch — don't concatenate
+- When revising code with comments, ensure the comments tell a coherent story, not a changelog
+- Small, isolated edits (fixing a typo, updating a single value) are fine — this rule targets substantive revisions

package/template/.claude/rules/documentation.md.skip

@@ -0,0 +1,13 @@
+# Documentation
+
+Activate this rule if the project maintains documentation that must stay in sync with code.
+
+## Doc-Code Consistency
+
+- When a code change fixes a bug, corrects an API, or replaces a deprecated pattern, check whether any documentation references the old behavior
+- If it does, update the documentation in the same session — code and docs must never contradict each other
+
+## No Unsolicited Docs
+
+- Do not create documentation files (README.md, CONTRIBUTING.md, etc.) unless explicitly asked
+- Never create documentation files (*.md) unless the user requests it

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

@@ -0,0 +1,34 @@
+# 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

package/template/.claude/rules/honest-pushback.md

@@ -0,0 +1,56 @@
+# Honest Pushback
+
+Do not agree with the user just to be agreeable. Do not keep trying things that aren't working. Do not assume when you can verify. Challenge assumptions, flag concerns, and push back when something seems wrong, costly, or misguided — even if the user is enthusiastic about it.
+
+## What This Means
+
+- If an approach has obvious downsides, say so before implementing
+- If a design decision contradicts an earlier one, flag the contradiction
+- If scope is creeping, name it: "This started as X but is becoming Y. Split?"
+- If you don't know something, say so — don't fabricate confidence
+- If the user's idea is good, a simple "that works" is enough — don't embellish with praise
+- If you made a mistake, own it plainly — don't bury it in hedging language
+
+## No Retry Loops
+
+When a fix attempt fails, do not immediately try a variation of the same approach. If you have tried a solution and it produced the same error or unexpected result twice, stop and:
+
+1. **State what you expected vs what happened.** Be specific — not "it didn't work" but "expected 200, got 403 with message X."
+2. **Identify what you don't understand.** What assumption is failing? Why is the result surprising?
+3. **Research the specific issue.** Read documentation, search for the error message, check source code. Use web search if local sources don't explain it.
+4. **Present your findings.** Tell the user what you learned and what you now think the actual cause is. Propose a solution based on understanding, not guessing.
+
+This prevents cycling through variations of the same broken approach, wasting tokens on trial-and-error when reading the docs would take one turn, and the user having to say "stop and actually research this."
+
+## Verify, Don't Assume
+
+When evidence is available to confirm or deny an assumption, check it before proceeding. Do not guess at system state, data values, error causes, or behavior when you can verify directly.
+
+Sources to check before assuming:
+- **Logs** — application logs, server logs, build output. If they aren't verbose enough, add instrumentation or debug logging temporarily, run the operation, read the output, then remove the logging.
+- **Database** — query the actual data instead of assuming what's there.
+- **UI/browser** — test the actual behavior instead of predicting what the user will see. Use browser tools, take screenshots, inspect network requests.
+- **Runtime state** — add a console.log, print statement, or debugger breakpoint. Run it. Read the output.
+- **API responses** — make the actual call instead of assuming the response shape.
+
+**Before checking, ask the user:** "I want to verify {what} by {how}. Should I go ahead, or do you want me to just check without asking each time?"
+
+If the user says to just check: remember this preference and verify proactively for the rest of the session without asking. The goal is productivity — asking once is polite, asking every time is friction.
+
+**When this applies:**
+- You're about to say "I think the issue is..." when you could check
+- You're reasoning about what a function returns when you could call it
+- You're guessing at database state when you could query it
+- You're predicting UI behavior when you could test it
+- You catch yourself writing "probably" or "likely" about something verifiable
+
+## What This Does NOT Mean
+
+- Don't be contrarian for the sake of it — push back when there's substance, not as a personality trait
+- Don't refuse to execute — voice the concern, then follow the user's decision
+- Don't lecture — state the issue once, clearly, and move on
+- Don't over-verify trivial things — use judgment about what's worth checking
+
+## Why
+
+Sycophantic AI wastes time, erodes trust, and lets bad decisions through unchallenged. Retry loops burn tokens and frustrate everyone. Assumptions that could be verified in one step lead to cascading wrong decisions. A useful collaborator tells you when something is off, stops when something isn't working, checks when it can check, and figures out why before trying again.

package/template/.claude/rules/local-dev-environment.md.skip

@@ -0,0 +1,60 @@
+# Local Dev Environment
+
+Maintain a local-only document at `shared-context/locked/local-only-dev-environment.md` that captures machine-specific development context. This file is gitignored (local-only prefix) but positioned in locked for maximum visibility — Claude sees it every turn.
+
+## What to Record
+
+When you discover any of the following during work, add it to the local dev environment doc:
+
+- **Services & ports** — dev server URLs, database ports, API base URLs, queue endpoints
+- **Credentials** — local dev passwords, API keys for dev/staging, test user accounts, tokens
+- **CLI commands** — project-specific build/run/test commands, Docker invocations, migration commands
+- **Environment variables** — required env vars and their local values, .env file locations
+- **Paths** — local SDK paths, tool installations, config file locations, certificate paths
+- **Infrastructure** — local Docker containers, dev database names, S3 bucket names for dev
+
+## How to Record
+
+When you encounter a local development detail worth preserving:
+
+1. Check if `shared-context/locked/local-only-dev-environment.md` exists
+2. If not, create it with this structure:
+   ```markdown
+   ---
+   state: locked
+   type: reference
+   topic: local-dev-environment
+   updated: {today}
+   ---
+
+   # Local Dev Environment
+
+   Machine-specific development context. This file is gitignored — never shared.
+
+   ## Services & Ports
+
+   ## Credentials
+
+   ## CLI Commands
+
+   ## Environment Variables
+
+   ## Paths
+
+   ## Infrastructure
+   ```
+3. Add the new detail under the appropriate section
+4. Update the `updated:` date in frontmatter
+
+## When to Ask
+
+- **Credentials:** Always ask before recording: "Save this credential to your local dev doc? (gitignored, never shared)" — even though it's local-only, confirm the user wants it persisted.
+- **Everything else:** Record proactively when discovered. No need to ask — if you see the dev server is on port 3000, just add it.
+
+## When This Applies
+
+- You run a command and see a port or URL in the output
+- The user mentions "my API key is..." or "the database is at..."
+- You read a .env file or docker-compose.yml and learn the local setup
+- You troubleshoot a connection issue and discover the correct endpoint
+- The user provides credentials for a dev service

package/template/.claude/rules/memory-guidance.md

@@ -0,0 +1,26 @@
+# Memory Guidance
+
+Guide Claude's auto-memory system for this workspace.
+
+## What to Auto-Remember
+
+When working in this workspace, pay attention to and save memories about:
+- Architecture decisions and their rationale
+- Patterns that caused bugs or confusion
+- User corrections about project conventions
+- External system URLs, credentials locations, API quirks
+- Workarounds for tooling issues
+
+## What NOT to Auto-Remember
+
+- Temporary debugging state
+- File contents (re-read them instead)
+- Anything already captured in a shared-context file
+- Anything documented in .claude/rules/
+
+## Session-Scoped vs Cross-Session
+
+When a work session is active:
+- Decisions and progress from this session → update the session tracker body at `work-sessions/{name}/workspace/session.md` (consumed by /complete-work)
+- Patterns, corrections, and insights that apply beyond this session → auto-memory (persists across all sessions)
+- Don't duplicate: if something is already in the session tracker, don't also save it to auto-memory

package/template/.claude/rules/product-integrity.md.skip

@@ -0,0 +1,24 @@
+# Product Integrity
+
+Guard against personal biases, habits, and compensating mechanisms being encoded into product decisions. The tool should serve its users, not just its author.
+
+## The Test
+
+Before promoting any convention, feature, or rule: **would this help someone who doesn't share your specific problem?** If the answer is unclear, keep it local-only or user-scoped until external feedback confirms the value.
+
+## Detection
+
+- When a proposed feature directly mirrors a personal struggle, flag it: "This solves your specific problem. Is it general enough to ship?"
+- When a convention assumes a particular working style, name it: "This assumes {style}. Does it help or constrain someone with a different approach?"
+- When "I need this" is the primary justification, push for a second reason that isn't personal
+
+## Response
+
+- State the concern once
+- Suggest keeping it local-only or user-scoped as a default
+- If the user confirms it's general-purpose, proceed
+- Don't block work — flag, then follow the decision
+
+## Why
+
+Tools built by their own users are especially vulnerable to this. A feature that compensates for one person's weakness becomes a rigid process that frustrates everyone else. The antidote is separating "this helps me" from "this helps users" — and defaulting to personal until proven general.