Two skills with overlapping content but different conventions.
Unified location (work/), universal DAG placement with megamerge.

Assisted-by: Claude Opus 4.5 via Claude Code

diff --git a/ai/claude/skills/coordinating-subagents-with-jj-workspaces/SKILL.md b/ai/claude/skills/coordinating-subagents-with-jj-workspaces/SKILL.md
deleted file mode 100644
index d90bfb27..00000000
--- a/ai/claude/skills/coordinating-subagents-with-jj-workspaces/SKILL.md
+++ /dev/null
@@ -1,240 +0,0 @@
----
-name: coordinating-subagents-with-jj-workspaces
-description: Use when dispatching subagents to implement features on a jj repository (on request) - provides explicit setup, isolation enforcement, conflict resolution, and mandatory verification to eliminate ambiguity and enable safe parallel development
----
-
-# Coordinating Subagents with jj Workspaces
-
-## Overview
-
-Enable safe parallel feature development by dispatching independent subagents to isolated jj workspaces, with explicit isolation enforcement, conflict detection, and mandatory verification gates.
-
-**Core principle:** Isolation by design. Each agent works independently in an isolated workspace, creating revisions on a clean slate, with zero risk of interfering with other agents. Verification and conflict resolution happen centrally after all agents complete.
-
-## When to Use
-
-**Triggers:**
-- You explicitly request this workflow for subagent coordination
-- Single-agent task needing isolated development (simplest case)
-- Multiple independent features ready for parallel development
-- Need to coordinate work across several subagents simultaneously
-- Want unified conflict detection and resolution
-
-**When NOT to use:**
-- Tasks have dependencies (use sequential development)
-- Features require constant coordination (use pair programming)
-
-## The Workflow Checklist
-
-**CRITICAL: Create TodoWrite todos for EACH step below. This workflow has sequential gates.**
-
-### Phase 1: Setup (Coordinator)
-
-- [ ] Create workspace: `jj workspace add ~/src/workspaces/<name>`
-- [ ] Place in DAG: `jj rebase -r <name>@ -A 'trunk()' -B mm`
-- [ ] Sync main workspace: `jj workspace update-stale`
-- [ ] **BLOCKER:** Phase 1 MUST complete before dispatch.
-
-### Phase 2: Dispatch (Coordinator)
-
-- [ ] Dispatch subagent with: task spec + workspace path + verification commands
-- [ ] For multiple agents: dispatch in parallel with Task tool
-
-### Phase 3: Execution (Agent)
-
-- [ ] Agent makes file edits in workspace
-- [ ] Agent runs verification (tests, type checks)
-- [ ] Agent commits change: `jj commit -m "..."`
-- [ ] Agent reports completion with results and change ID
-
-### Phase 4: Review (Coordinator)
-
-- [ ] Sync: `jj workspace update-stale`
-- [ ] Review: `jj diff -r <workspace>@`
-- [ ] Check conflicts: `jj status`
-- [ ] Resolve conflicts if needed
-
-### Phase 5: Cleanup (Coordinator)
-
-- [ ] Delete workspace: `jj workspace forget <name>`
-- [ ] Remove directory: `rm -rf ~/src/workspaces/<name>`
-- [ ] Work remains in jj repository history
-
-## Setup: Creating Workspaces and DAG Placement
-
-**Before dispatching ANY agents, execute this setup:**
-
-### Step 1: Create the Workspace
-
-**MANDATORY location:** `~/src/workspaces/` - Fixed, standard location across all projects.
-
-**Workspace naming:** `{jira-id-if-present}-{feature-name}` - Include JIRA ID as prefix ONLY if work is tracked in JIRA. Use LOWERCASE only.
-
-```bash
-# Create workspace (all lowercase)
-jj workspace add ~/src/workspaces/proj-123-feature-name
-```
-
-### Step 2: Place Workspace in DAG (Critical)
-
-**The workspace change MUST be inserted between trunk() and the megamerge (mm).** This ensures the work integrates cleanly into your development stack.
-
-```bash
-# Insert workspace change between trunk and megamerge
-jj rebase -r <workspace-name>@ -A 'trunk()' -B mm
-```
-
-Example:
-```bash
-jj rebase -r proj-123-feature-name@ -A 'trunk()' -B mm
-```
-
-**Result:** `trunk() → workspace change → mm`
-
-### Step 3: Sync Main Workspace
-
-After setup in the workspace, sync the main workspace to see the new changes:
-
-```bash
-# In main workspace
-jj workspace update-stale
-```
-
-This updates the main workspace's view of the DAG after changes made in other workspaces.
-
-### Key Points
-
-- Workspaces created BEFORE agents start (not during)
-- DAG placement happens BEFORE dispatch
-- Run `jj workspace update-stale` in main workspace after workspace operations
-
-## Dispatching Agents
-
-**Use the Task tool to dispatch in parallel. Example:**
-
-```
-Task 1: Dispatch auth agent to auth workspace
-- Task: auth-feature
-- Workspace path: ~/src/workspaces/proj-123-auth
-- Requirements: Implement OAuth, create auth middleware, add login endpoints
-- Verification: Run tests, confirm all pass
-- Success criteria: OAuth flow works end-to-end
-
-Task 2: Dispatch API agent to api workspace
-- Task: api-endpoint
-- Workspace path: ~/src/workspaces/api-endpoint
-- [... similar structure ...]
-
-Task 3: Dispatch DB agent to db workspace
-- Task: db-migration
-- Workspace path: ~/src/workspaces/db-migration
-- [... similar structure ...]
-```
-
-**Critical enforcement:**
-- Each agent gets EXACTLY ONE workspace path
-- No agent can see other workspaces (isolation guarantee)
-- Agents work in parallel (no waiting)
-- Each agent must report verification status
-
-## Agent Contract (What Agents Must Do)
-
-**Each agent MUST:**
-1. Work ONLY in their assigned workspace path
-2. Make file edits to implement the task
-3. Run verification steps (tests, type checks, etc.)
-4. Commit the change: `jj commit -m "feat: ..."` (use describing-changes skill)
-5. Report results: what changed, verification output, final change ID
-7. Make NO changes outside their workspace
-
-**Agent workflow:**
-1. Make file edits in workspace
-2. Run verification commands
-3. Commit changes with `jj commit -m "..."`
-4. Report completion with results and change ID
-
-**FORBIDDEN for agents:**
-- `jj workspace` commands - breaks isolation
-- `jj git push` - coordinator handles
-- `jj rebase` - coordinator handles DAG operations
-- Any work outside assigned workspace path
-
-**If verification fails:**
-- Agent reports what failed and why
-- Agent attempts one retry OR hands off to coordinator
-
-**Coordinator handles:**
-- DAG operations (rebase, etc.)
-- Code review of agent's changes via `jj diff`
-- Conflict resolution after `jj workspace update-stale`
-- Decision about failed verification
-- Pushing to remote
-
-## After Agent Completes
-
-After each agent reports completion:
-
-```bash
-# In main workspace: sync to see agent's changes
-jj workspace update-stale
-
-# Review agent's work
-jj diff -r <workspace-name>@
-
-# Check for conflicts
-jj status
-# If conflicts shown, resolve them with jj resolve
-```
-
-**Key flow:**
-1. Agent makes edits and reports completion
-2. Coordinator reviews changes via `jj diff`
-3. Coordinator runs `jj workspace update-stale` in main workspace
-4. Conflicts surface and are resolved
-5. Repeat for each agent (if multiple)
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Skipping DAG placement | Must run `jj rebase -r <ws>@ -A 'trunk()' -B mm` after creating workspace |
-| Agent skipping `jj commit` | Agent must commit their changes with `jj commit -m "..."` |
-| Skipping `jj workspace update-stale` | Run in main workspace after agent completes to sync and detect conflicts |
-| Creating workspaces during dispatch | Create all workspaces and place in DAG BEFORE dispatch |
-| Agent touching other workspaces | Agents work ONLY in their assigned workspace path |
-| Deleting workspaces before review | Keep workspaces until all work complete and reviewed |
-
-## Red Flags - STOP
-
-If you catch yourself thinking ANY of these, you're about to violate the workflow. **RESTART and follow the workflow exactly.**
-
-| Red Flag | Reality |
-|----------|---------|
-| "I'll skip DAG placement" | NO. Must insert workspace between trunk and mm for clean integration. |
-| "Agent doesn't need to commit" | NO. Agent must run `jj commit` to finalize the change. |
-| "I'll create workspaces during dispatch" | Create ALL workspaces and place in DAG first. |
-| "I'll skip `jj workspace update-stale`" | Run after agent completes. This syncs main workspace. |
-| "I'll create a custom directory" | NO. Always use `~/src/workspaces/`. No exceptions. |
-| "This is overkill for one agent" | Single-agent workflow is valid and maintains consistency. |
-
-## Failure Recovery
-
-**Agent times out or disappears:**
-- Main session can retry that agent with fresh context
-- Work in that workspace is preserved (nothing is lost)
-- Other agents continue unaffected
-- Retry as many times as needed
-
-**Verification fails:**
-- Agent reports what failed
-- Main session can: retry agent, manually fix revisions in workspace, or revert
-- Other agents' work remains clean
-- No cascading failures
-
-**Conflicts surface after `jj workspace update-stale`:**
-- Expected and normal
-- Main session resolves explicitly
-- No emergency needed - this is why `jj workspace update-stale` exists
-- Revert conflicting agent work if necessary, retry agent
-
-**Conclusion:** All failures are contained, transparent, and recoverable.
diff --git a/ai/claude/skills/jj-workspace-experiments/SKILL.md b/ai/claude/skills/jj-workspace-experiments/SKILL.md
deleted file mode 100644
index 503c667d..00000000
--- a/ai/claude/skills/jj-workspace-experiments/SKILL.md
+++ /dev/null
@@ -1,302 +0,0 @@
----
-name: jj-workspace-experiments
-description: Create isolated jj workspaces for testing changes, running experiments in parallel, and exploring alternative implementations. Use when testing breaking changes, comparing different approaches, or running long-running operations without blocking other work. (project)
-source: https://github.com/thoughtpolice/a/blob/canon/.claude/skills/jj-workspace-experiments/SKILL.md
----
-
-# Jj Workspace Experiments
-
-## Overview
-
-Create isolated jj workspaces in the `work/` directory to test changes, run experiments concurrently, and explore alternative implementations without affecting the main workspace. All workspaces share the same repository history, enabling seamless switching and comparison between approaches.
-
-## When to Use
-
-Use this skill when:
-- Testing breaking changes or refactors that might not work
-- Comparing multiple implementation approaches side-by-side
-- Running long-running tests or builds without blocking other work
-- Exploring alternative solutions to a problem concurrently
-- Testing changes that require extensive experimentation
-- Working on multiple independent features simultaneously
-
-## Core Workflows
-
-### Single Experiment Workspace
-
-Create a workspace to test changes in isolation.
-
-#### 1. Create the Workspace
-
-```bash
-jj workspace add --name=<experiment-name> work/<directory-name>
-```
-
-**Examples:**
-```bash
-# Test a refactoring
-jj workspace add --name=async-refactor work/async-refactor
-
-# Try a different architecture
-jj workspace add --name=new-db-layer work/new-db-layer
-
-# Experiment with a breaking change
-jj workspace add --name=api-v2 work/api-v2
-```
-
-The workspace starts from the current commit (`@`) by default. To start from a different commit:
-
-```bash
-jj workspace add --name=<name> -r <revision> work/<directory>
-```
-
-#### 2. Work in the Workspace
-
-Navigate to the workspace and make changes:
-
-```bash
-cd work/<directory-name>
-
-# Make changes, run tests, build
-# Commits created here are isolated to this workspace
-```
-
-Changes are visible from the main workspace via `jj log` - all workspaces share the repository history.
-
-#### 3. Evaluate and Decide
-
-After testing:
-
-**If successful:** Merge the changes back to the main branch:
-```bash
-# From main workspace
-jj rebase -s <experiment-name>@ -d @
-```
-
-**If unsuccessful:** Simply forget the workspace:
-```bash
-jj workspace forget <experiment-name>
-rm -rf work/<directory-name>
-```
-
-The commits remain in the repository history but can be abandoned if needed.
-
-### Parallel Experiments
-
-Test multiple approaches simultaneously by creating multiple workspaces.
-
-#### 1. Create Multiple Workspaces
-
-```bash
-# Create first approach workspace
-jj workspace add --name=approach-a work/approach-a
-
-# Create second approach workspace
-jj workspace add --name=approach-b work/approach-b
-
-# Create third approach workspace (optional)
-jj workspace add --name=approach-c work/approach-c
-```
-
-Each workspace starts from the same commit, creating parallel branches of development.
-
-#### 2. Implement Different Approaches
-
-Work in each workspace independently:
-
-```bash
-# Terminal 1: Implement approach A
-cd work/approach-a
-# Make changes...
-
-# Terminal 2: Implement approach B
-cd work/approach-b
-# Make changes...
-
-# Terminal 3: Implement approach C
-cd work/approach-c
-# Make changes...
-```
-
-#### 3. Compare Results
-
-From the main workspace, compare implementations:
-
-```bash
-# View all workspace changes
-jj log -r 'working_copies()'
-
-# Compare approach A to approach B
-jj diff -r approach-a@ -r approach-b@
-
-# View specific workspace state
-jj show approach-a@
-```
-
-#### 4. Choose Winner and Clean Up
-
-Select the best approach and merge it:
-
-```bash
-# Merge winning approach
-jj rebase -s approach-b@ -d @
-
-# Forget the other workspaces
-jj workspace forget approach-a
-jj workspace forget approach-c
-
-# Clean up directories
-rm -rf work/approach-a work/approach-c
-```
-
-### Long-Running Operations
-
-Use a workspace to run long builds/tests without blocking other work.
-
-#### 1. Create Workspace for Long Operation
-
-```bash
-jj workspace add --name=test-run work/test-run
-```
-
-#### 2. Start Long Operation
-
-```bash
-cd work/test-run
-
-# Start long-running operation
-buck2 test //... &
-```
-
-#### 3. Continue Work Elsewhere
-
-While the operation runs, work normally in the main workspace:
-
-```bash
-cd $REPO_ROOT  # Back to main workspace
-# Continue development normally
-```
-
-#### 4. Check Results When Ready
-
-Return to the test workspace to check results:
-
-```bash
-cd work/test-run
-# Check test results, build artifacts, etc.
-```
-
-## Advanced Patterns
-
-### Testing Changes on Different Base Commits
-
-Create workspaces from different commits to test compatibility:
-
-```bash
-# Test on current commit
-jj workspace add --name=current-test work/current-test
-
-# Test on older commit
-jj workspace add --name=backport-test -r @-- work/backport-test
-
-# Test on main branch
-jj workspace add --name=main-test -r main work/main-test
-```
-
-### Darcs-Style Multiple Workspaces
-
-Create a sparse main workspace with all real work in sub-workspaces:
-
-```bash
-# Make main workspace sparse (only work/ directory)
-jj sparse set --clear --add work
-
-# Create multiple workspaces for different tasks
-jj workspace add work/feature-a
-jj workspace add work/feature-b
-jj workspace add work/bugfix-123
-```
-
-Now the main workspace is empty, but `work/` contains multiple full checkouts that all share the repository history.
-
-### Workspace as Scratch Space
-
-Create temporary workspaces for quick experiments:
-
-```bash
-# Create scratch workspace
-jj workspace add --name=scratch work/scratch
-
-cd work/scratch
-# Experiment freely without concern
-
-# When done, forget it
-jj workspace forget scratch
-rm -rf work/scratch
-```
-
-## Best Practices
-
-### Naming Conventions
-
-Use descriptive names that indicate purpose:
-- **Experiments:** `sqlite-vs-postgres`, `algorithm-a`, `refactor-v2`
-- **Features:** `feature-auth`, `feature-search`
-- **Tests:** `test-integration`, `perf-benchmark`
-- **Scratch:** `scratch`, `temp-experiment`
-
-### Workspace Lifecycle
-
-1. **Create** workspace with clear purpose
-2. **Work** in isolation until complete or failed
-3. **Evaluate** results and make decision
-4. **Merge** successful work or **forget** failed attempts
-5. **Clean up** directories after forgetting
-
-### Managing Multiple Workspaces
-
-List active workspaces regularly:
-
-```bash
-jj workspace list
-```
-
-Keep track of workspace purposes in notes or commit messages.
-
-### Resource Considerations
-
-Each workspace is a full working copy, consuming disk space. Clean up unused workspaces promptly.
-
-## Workspace Commands Reference
-
-```bash
-# Create workspace from current commit
-jj workspace add --name=<name> work/<dir>
-
-# Create workspace from specific revision
-jj workspace add --name=<name> -r <rev> work/<dir>
-
-# List all workspaces
-jj workspace list
-
-# Forget workspace (keeps commits, removes workspace reference)
-jj workspace forget <name>
-
-# View all workspace commits
-jj log -r 'working_copies()'
-
-# Reference a workspace's current commit
-<workspace-name>@
-```
-
-## Limitations
-
-- **Disk space:** Each workspace is a full working copy
-- **Manual cleanup:** Must remember to forget and remove old workspaces
-- **Coordination:** When working in multiple workspaces, ensure you're in the correct directory
-- **Build artifacts:** Each workspace has its own build outputs, which can consume significant space
-
-## Related Skills
-
-- `jj-clone-third-party` - For examining external repositories
-- `jj-graft-third-party` - For integrating third-party repository history
diff --git a/ai/claude/skills/jj-workspaces/SKILL.md b/ai/claude/skills/jj-workspaces/SKILL.md
new file mode 100644
index 00000000..ba96e636
--- /dev/null
+++ b/ai/claude/skills/jj-workspaces/SKILL.md
@@ -0,0 +1,189 @@
+---
+name: jj-workspaces
+description: Use when needing isolated workspace for experiments, parallel development, or subagent coordination - covers solo experimentation and multi-agent workflows with jj workspaces
+---
+
+# jj Workspaces
+
+## Overview
+
+Create isolated jj workspaces for experimentation, parallel development, and subagent coordination. All workspaces share repository history, enabling seamless switching and comparison.
+
+**Core principle:** Isolation by design. Each workspace operates independently with zero risk of interference.
+
+## When to Use
+
+**Triggers:**
+- Testing breaking changes or refactors that might not work
+- Comparing multiple implementation approaches
+- Running long-running operations without blocking other work
+- Dispatching subagents to implement features in parallel
+- Need isolated development for any reason
+
+## Workspace Location
+
+**Always use `work/` directory** (relative to repo root).
+
+**Naming:** Use lowercase, descriptive names. Include story/ticket ID as prefix if work is tracked (e.g., `abc-123-auth-feature`, `async-refactor`, `api-v2`).
+
+## Creating a Workspace
+
+```bash
+# 1. Create workspace
+jj workspace add --name=<name> work/<name>
+
+# Or from specific revision
+jj workspace add --name=<name> -r <rev> work/<name>
+
+# 2. Place in DAG - if megamerge (mm) exists, insert between trunk and mm
+jj rebase -r <name>@ -A 'trunk()' -B mm
+
+# If no megamerge, just rebase onto trunk:
+# jj rebase -r <name>@ -d 'trunk()'
+
+# 3. Sync main workspace
+jj workspace update-stale
+```
+
+**Result (with mm):** `trunk() → workspace change → mm`
+
+## Solo Experiments
+
+### Work and Evaluate
+
+```bash
+cd work/<name>
+# Make changes, run tests, build
+# Commits are isolated to this workspace
+```
+
+**If successful:** Merge back:
+```bash
+jj rebase -s <name>@ -d @
+```
+
+**If unsuccessful:** Forget and clean up:
+```bash
+jj workspace forget <name>
+rm -rf work/<name>
+```
+
+### Parallel Experiments
+
+Create multiple workspaces to compare approaches:
+
+```bash
+jj workspace add --name=approach-a work/approach-a
+jj workspace add --name=approach-b work/approach-b
+# Don't forget to place each in DAG if mm exists
+```
+
+Compare from main workspace:
+```bash
+jj log -r 'working_copies()'
+jj diff -r approach-a@ -r approach-b@
+```
+
+## Subagent Coordination
+
+For dispatching agents to work in parallel. **Execute setup BEFORE dispatching ANY agents.**
+
+### Phase 1: Setup (Coordinator)
+
+Create workspace(s) using the standard process above.
+
+### Phase 2: Dispatch (Coordinator)
+
+Use Task tool to dispatch in parallel. Each agent gets:
+- Task specification
+- Workspace path (exactly one)
+- Verification commands
+- Success criteria
+
+### Phase 3: Execution (Agent)
+
+**Agent MUST:**
+1. Work ONLY in assigned workspace path
+2. Make file edits to implement task
+3. Run verification (tests, type checks)
+4. Commit: `jj commit -m "feat: ..."`
+5. Report: what changed, verification output, change ID
+
+**FORBIDDEN for agents:**
+- `jj workspace` commands
+- `jj git push`
+- `jj rebase`
+- Any work outside assigned workspace
+
+### Phase 4: Review (Coordinator)
+
+```bash
+jj workspace update-stale  # Sync to see agent's changes
+jj diff -r <name>@         # Review work
+jj status                  # Check conflicts, resolve if needed
+```
+
+### Phase 5: Cleanup
+
+```bash
+jj workspace forget <name>
+rm -rf work/<name>
+```
+
+## Commands Reference
+
+```bash
+# Create workspace
+jj workspace add --name=<name> work/<name>
+jj workspace add --name=<name> -r <rev> work/<name>
+
+# List workspaces
+jj workspace list
+
+# Forget workspace (keeps commits)
+jj workspace forget <name>
+
+# View workspace commits
+jj log -r 'working_copies()'
+
+# Reference workspace's current commit
+<name>@
+
+# Sync after external workspace changes
+jj workspace update-stale
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Skipping DAG placement | Must run `jj rebase` to place in DAG (with `-B mm` if megamerge exists) |
+| Agent skipping commit | Agent must run `jj commit -m "..."` |
+| Skipping `jj workspace update-stale` | Run in main workspace after workspace operations |
+| Creating workspaces during dispatch | Create ALL workspaces BEFORE dispatch |
+| Agent touching other workspaces | Agents work ONLY in assigned path |
+| Forgetting cleanup | Remove directories after forgetting workspace |
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "I'll skip DAG placement" | Must place in DAG for clean integration |
+| "Agent doesn't need to commit" | Agent must run `jj commit` to finalize change |
+| "I'll create workspaces during dispatch" | Create ALL workspaces first |
+| "Custom directory is fine" | Always use `work/` directory |
+| "This is overkill for one agent" | Single-agent workflow maintains consistency |
+
+## Failure Recovery
+
+**Agent timeout:** Retry with fresh context. Work in workspace is preserved.
+
+**Verification fails:** Agent reports failure. Coordinator decides: retry, fix, or revert.
+
+**Conflicts after sync:** Expected. Coordinator resolves via `jj resolve`.
+
+All failures are contained and recoverable.
+
+## References
+
+- [jj-workspace-experiments](https://github.com/thoughtpolice/a/blob/canon/.claude/skills/jj-workspace-experiments/SKILL.md) - Original source for workspace patterns