Replaces bookmark-based subagent coordination with isolated jj workspaces
to guarantee structural separation and prevent interference. Integrates
skill usage (describing-changes, elements-of-style) into commit and PR
workflows to enforce reasoning and quality standards at decision points.

Assisted-by: Claude Haiku 4.5 via Claude Code

diff --git a/ai/claude/commands/commit.md b/ai/claude/commands/commit.md
index 9ca384cd..d0e1f5ac 100644
--- a/ai/claude/commands/commit.md
+++ b/ai/claude/commands/commit.md
@@ -8,15 +8,20 @@ Usage:
 - `/commit <fileset>` - Commit only files matching the fileset expression
 
 Before committing:
-1. Use the `describing-changes` skill to draft the commit message explaining reasoning
-   - The skill requires `elements-of-style:writing-clearly-and-concisely` for clarity
-2. Audit the message: is every sentence invisible in the diff?
+1. Check if a fileset was provided as arguments
+2. If a fileset is provided:
+   - Run `jj diff <fileset>` to view the specific changes being committed
+   - Use the `describing-changes` skill to draft the commit message based on these specific changes
+3. If no fileset is provided:
+   - Run `jj diff` to view all current changes
+   - Use the `describing-changes` skill to draft the commit message explaining reasoning
+4. The skill requires `elements-of-style:writing-clearly-and-concisely` for clarity
+5. Audit the message: is every sentence invisible in the diff?
    - For each sentence, ask: "Does this explain something not visible in the code change?"
    - If the answer is "no" (sentence just restates what the diff shows), delete it
    - If all sentences pass the audit, proceed. If any fail, rewrite until they do.
-3. Check if a fileset was provided as arguments
-4. If a fileset is provided, use `jj commit <fileset>` to commit only matching files
-5. If no fileset is provided, use `jj commit` to commit all changes
-6. Include the "Assisted-by" footer with the current model and tool being used
-7. Use a HEREDOC for the commit message to ensure proper formatting
-8. Verify the commit with `jj show` to confirm only intended changes were committed
+6. If a fileset is provided, use `jj commit <fileset>` to commit only matching files
+7. If no fileset is provided, use `jj commit` to commit all changes
+8. Include the "Assisted-by" footer with the current model and tool being used
+9. Use a HEREDOC for the commit message to ensure proper formatting
+10. Verify the commit with `jj show` to confirm only intended changes were committed
diff --git a/ai/claude/commands/pr.md b/ai/claude/commands/pr.md
index b1b42869..bccc3388 100644
--- a/ai/claude/commands/pr.md
+++ b/ai/claude/commands/pr.md
@@ -19,16 +19,20 @@ When creating a pull request:
 2. Run `jj log -r 'trunk()::<bookmark>'` to list all commits from trunk to the bookmark
 3. Run `jj diff -r 'trunk()::<bookmark>' --stat` to review all changes
 4. Check for .github PR templates and follow them
-5. Generate a PR title summarizing all commits in the changeset (not just the
-   most recent). The title reflects the overall change, not individual commits
-6. Draft a PR summary explaining why the changes were made and their impact.
-   Focus on context and motivation, not implementation details. Include only
-   "Assisted-by" footer for attribution—no "Generated with Claude Code"
+5. Use the writing skill to generate a PR title summarizing all commits in the
+   changeset (not just the most recent). The title reflects the overall change,
+   not individual commits. Apply Strunk's principles for clarity and concision.
+6. Use the writing skill to draft a PR summary explaining why the changes were
+   made and their impact. Focus on context and motivation, not implementation
+   details. Include only "Assisted-by" footer for attribution—no "Generated
+   with Claude Code"
    - Do not repeat information obvious from the diff
    - Omit details like "added function X" or "modified file Y" unless
      non-obvious reasoning justifies them
    - Explain user-facing impact, architectural decisions, and tradeoffs
    - Follow repository conventions
-7. Create the PR: `gh pr create --head <bookmark-name> --title "<title>"` using
+   - Apply elements-of-style rules: active voice, positive form, definite
+     language, omit needless words, keep related words together
+7. Create the PR as draft: `gh pr create --head <bookmark-name> --title "<title>" --draft` using
    a HEREDOC to pass the body
 8. Return the PR URL
diff --git a/ai/claude/skills/coordinating-subagents-with-jj-workspaces/SKILL.md b/ai/claude/skills/coordinating-subagents-with-jj-workspaces/SKILL.md
index a7cc3320..16afefc7 100644
--- a/ai/claude/skills/coordinating-subagents-with-jj-workspaces/SKILL.md
+++ b/ai/claude/skills/coordinating-subagents-with-jj-workspaces/SKILL.md
@@ -1,517 +1,243 @@
 ---
 name: coordinating-subagents-with-jj-workspaces
-description: Use when dispatching multiple subagents to implement independent features in parallel on a jj repository - provides explicit setup, isolation enforcement, conflict resolution, and mandatory verification to eliminate ambiguity and enable safe parallel development
+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
 
-Parallel independent feature development requires explicit coordination protocols. Without clarity, subagents break isolation (checking others' work) or lack critical information (which bookmark to use). This skill provides a rigid three-phase workflow: Setup (bookmarks + explicit instructions), Execution (enforce isolation strictly), Merge (megamerge + mandatory verification).
+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:** Parallelism breaks at every ambiguity point. Eliminate ambiguity entirely. No assumptions.
+**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.
 
-## Setup Phase (Main Agent)
+## When to Use
 
-### 1. Create Isolated Bookmarks
+**Triggers:**
+- You explicitly request this workflow for subagent coordination
+- Multiple independent features ready for parallel development
+- Need to coordinate work across several subagents simultaneously
+- Want unified conflict detection and resolution
+- Must ensure isolation between parallel tasks
+- Single-agent tasks where you want structured isolated development
 
-Create separate jj bookmarks for each subagent, all starting from the same base:
+**When NOT to use:**
+- Tasks have dependencies (use sequential development)
+- Features require constant coordination (use pair programming)
 
-```bash
-jj bookmark create feature-auth-subagent main
-jj bookmark create feature-payments-subagent main
-jj bookmark create feature-analytics-subagent main
-```
-
-**Why separate bookmarks:** If all subagents share a bookmark, their commits interleave. Later merging them separately becomes impossible. Each must have its own linear history.
+## The Workflow Checklist
 
-**Naming convention:** `feature-[descriptive-name]-subagent`. Examples:
-- ✅ `feature-auth-refactor-subagent`
-- ✅ `feature-stripe-integration-subagent`
-- ❌ `feature-a`, `branch-1` (ambiguous in commits)
+**CRITICAL: Create TodoWrite todos for EACH step below. This workflow has sequential gates.**
 
-### 2. Document Everything in Writing
+### Phase 1: Define and Setup (Main Session)
 
-For EACH subagent task, write a self-contained instruction document with:
+- [ ] Define task specifications for each agent (goal, requirements, success criteria, verification steps)
+- [ ] Create isolated workspaces: `jj workspace add <name> <path>` for each task (one per agent)
+- [ ] Verify EVERY workspace is isolated and ready (DO NOT proceed to Phase 2 until ALL workspaces verify successfully)
+- [ ] **BLOCKER:** Phase 1 MUST be 100% complete before ANY agent dispatch. Dispatching even one agent early breaks isolation guarantees.
 
-- **Bookmark name** (exact spelling, case-sensitive)
-- **Files allowed to modify** (explicit whitelist, no others)
-- **Files NOT to modify** (explicit blocklist)
-- **Commit message format** (e.g., "auth: [verb] [noun]")
-- **Tests to pass before returning** (exact commands)
-- **Completion criteria** (when is work "done"?)
+### Phase 2: Dispatch Agents (Main Session)
 
-**Minimal example for Subagent A:**
+- [ ] For each task, dispatch subagent with: task spec + workspace path + verification steps
+- [ ] All dispatches happen in parallel (use Task tool with multiple invocations)
+- [ ] Main session monitors for agent completion
 
-```
-FEATURE AUTH REFACTOR - Subagent A
-
-Bookmark: feature-auth-subactor
-Starting point: main
-Scope: ONLY modify these files:
-  - src/auth.ts
-  - src/middleware/auth.js
-  - tests/auth.test.ts
-
-Do NOT modify:
-  - src/payments.ts
-  - src/database.ts
-  - Any file outside src/
-
-Commit format: "auth: [description]"
-Examples: "auth: refactor middleware", "auth: add timeout handling"
-
-Verification:
-  npm test -- auth
-  npm run lint -- src/auth.ts src/middleware/auth.js
-  Both must pass before declaring complete
-
-Do NOT:
-  - Check other subagent bookmarks (they don't exist in your world)
-  - Ask "what is subagent B doing?"
-  - Look at other branches for context
-  - Modify shared utilities without asking main agent first
-
-Return to main agent when:
-  - All tests passing (output: npm test -- auth)
-  - All lint passing (output: npm run lint)
-  - Commit list (output: jj log -r feature-auth-subagent)
-```
+### Phase 3: Execution and Incremental Validation (Agents + Main Session in Parallel)
 
-**Why this level of detail:** Ambiguity is where parallelism breaks. Explicit > assumed.
+**Agents (in parallel):**
+- [ ] Agent works independently in their assigned isolated workspace
+- [ ] Agent runs verification steps (tests, checks) locally
+- [ ] Agent shows `jj diff` output to main session
+- [ ] Agent waits for main session code review and approval
+- [ ] Only after approval: Agent uses `jj describe -m "message"` to add message to current change
+- [ ] Agent uses `jj new --insert-after=@` to start a new change
+- [ ] Agent reports completion status
 
-### 3. Transmit Instructions to Each Subagent
+**Main session (as each agent reports ready):**
+- [ ] As each agent reports ready for review, immediately:
+  - [ ] Review their `jj diff` changes for code quality
+  - [ ] Verify their local verification results passed
+  - [ ] Approve or request changes
+  - [ ] Once approved: tell agent to describe and create new change
+  - [ ] After agent confirms workspace is updated: run `jj workspace update-stale`
+  - [ ] Check for conflicts and resolve if needed
+  - [ ] Workspace automatically stays in megamerge history
+  - [ ] Proceed to next agent
+- [ ] Repeat until ALL agents complete and all conflicts resolved
 
-Provide the exact instruction document above to EACH subagent in a separate dispatch. Do NOT ask one subagent to coordinate with another.
+### Phase 4: Cleanup (Main Session)
 
-**Correct dispatch:**
-- Task 1 (subagent A): [instruction 1 for A only]
-- Task 2 (subagent B): [instruction 2 for B only]
-- Task 3 (subagent C): [instruction 3 for C only]
+- [ ] Delete workspaces: `jj workspace forget <name>`
+- [ ] Remove isolated workspace directories
+- [ ] All agent work remains in the jj repository history
 
-**Incorrect dispatch:**
-- "Subagents A and B, coordinate on the auth system"
-- "Check if others are doing similar work"
-- "You can look at branches to avoid duplication"
+## Setup: Creating or Reusing Workspaces
 
-## Execution Phase (Subagent)
+**Before dispatching ANY agents, execute this setup:**
 
-### CRITICAL: Isolation is Structural, Not Optional
+**MANDATORY location:** `~/src/workspaces/` - This is the fixed, standard location across all projects.
 
-Other subagents and their bookmarks do NOT EXIST to you. This isn't about "not coordinating" - they literally don't exist as entities you interact with.
+**Workspace naming:** `{jira-id-if-present}-{feature-name}` - Include JIRA ID as prefix ONLY if work is tracked in JIRA. Use LOWERCASE only.
 
-### 1. Create Your Working Bookmark
-
-Checkout your assigned bookmark:
+**DO NOT deviate from this structure.** Do not create custom directories like `-workspaces`, `parallel-work`, `subagent-work`, etc.
 
 ```bash
-jj checkout feature-auth-subagent
+# EXACT pattern for workspaces (all lowercase)
+jj workspace add --revision "trunk()" ~/src/workspaces/proj-123-auth
+jj workspace add --revision "trunk()" ~/src/workspaces/api-feature
+jj workspace add --revision "trunk()" ~/src/workspaces/db-migration
 ```
 
-### 2. PROHIBITED COMMANDS
-
-**Do NOT run ANY of these:**
+**NO custom paths. NO alternative directories. ALWAYS use `~/src/workspaces/`**
 
-```bash
-jj log  # Do not see all branches
-jj bookmark list  # Do not see what others are doing
-jj diff -r <other-bookmark>  # Do not inspect other work
-jj status -A  # Do not see repository-wide state
-```
+**Key enforcement:**
+- Workspaces are created BEFORE agents start (not during)
+- Each workspace is completely isolated (cannot see other agent work)
+- Each workspace has its own independent jj state
+- Default location is `~/src/workspaces` for consistency across projects
+- JIRA IDs in workspace names provide automatic traceability
 
-**Why:** Even "just looking" creates implicit dependencies and influences your decisions.
+**Reusing existing workspaces:**
+- Verify workspace exists: `jj workspace list`
+- Check its current state: `jj -R /path/to/workspace status`
+- Workspaces may be reused for multiple agent cycles - they're just isolated directories
 
-### 3. RED FLAGS - STOP If You Think Any Of These
+## Dispatching Agents
 
-If this thought crosses your mind, STOP immediately and report to main agent:
+**Use the Task tool to dispatch in parallel. Example:**
 
-- "Let me just quickly check what subagent B is doing"
-- "I should see if they're touching files I need"
-- "I need to understand the repository state before starting"
-- "Maybe I can reuse something from their work"
-- "I should avoid conflicts by knowing what they're doing"
-- "I'm just orienting myself, not really coordinating"
-- "Due diligence means understanding the full picture"
-
-**If you think any of these, respond to main agent:**
-```
-I'm about to start but have a question: [specific question about dependencies]
-Should I proceed independently or does this indicate task decomposition was wrong?
 ```
+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
 
-Main agent decides if you have a legitimate dependency question or if you're rationalizing.
-
-### 4. Work ONLY On Your Scope
-
-Modify ONLY the files listed in your instruction document.
+Task 2: Dispatch API agent to api workspace
+- Task: api-endpoint
+- Workspace path: ~/src/workspaces/api-endpoint
+- [... similar structure ...]
 
-If you need to modify a file NOT on the list:
-- STOP
-- Report to main agent: "Feature X requires modifying [file], is this in scope?"
-- Wait for answer
-- Do NOT modify it without explicit approval
-
-### 5. Commit Regularly
-
-Small, meaningful commits following your format:
-
-```bash
-jj commit -m "auth: refactor middleware validation"
-jj commit -m "auth: add timeout handling"
+Task 3: Dispatch DB agent to db workspace
+- Task: db-migration
+- Workspace path: ~/src/workspaces/db-migration
+- [... similar structure ...]
 ```
 
-### 6. Run Your Verification BEFORE Declaring Done
-
-Run EXACTLY the commands from your instruction document:
-
-```bash
-npm test -- auth
-npm run lint -- src/auth.ts src/middleware/auth.js
-```
-
-**BOTH must pass.** If either fails, fix it. Do not declare complete if tests fail.
-
-### 7. Report Completion
-
-When your tests pass, report to main agent:
-
-```
-Subagent A: Feature Auth Refactor - COMPLETE
-
-Bookmark: feature-auth-subagent
-Files modified: src/auth.ts, src/middleware/auth.js, tests/auth.test.ts
-Commits:
-  - auth: refactor middleware validation
-  - auth: add timeout handling
-  - auth: update tests for new behavior
-
-Verification:
-  npm test -- auth: PASS (18/18 tests)
-  npm run lint: PASS (0 issues)
-
-Ready for integration.
-```
-
-**Do NOT add:** "I checked and subagent B isn't touching auth..." You have no knowledge of what others are doing.
-
-## Merge Phase (Main Agent)
-
-### Phase 1: Pre-Merge Verification
+**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
 
-Before invoking megamerge, verify setup:
+## Agent Contract (What Agents Must Do)
 
-```bash
-jj bookmark list | grep subagent
-# Should show all three: feature-auth-subagent, feature-payments-subagent, feature-analytics-subagent
+**Each agent MUST:**
+1. Work ONLY in their assigned workspace (cd to workspace path first)
+2. Run verification steps provided in task spec
+3. Report work status to main session with: changes made, test results, diff of changes
+4. **WAIT for main session approval** before describing changes
+5. Only after approval: Use `jj describe -m "message"` to add description to current change
+6. Then use `jj new --insert-after=@` to start a new change for the megamerge
+7. Report completion: "Described and new change created" or specific blockers
+8. Make NO changes outside their workspace
+9. Make NO attempt to check other agent workspaces
+10. Do NOT attempt to merge or integrate their work
 
-jj log -r 'feature-auth-subagent' --oneline
-jj log -r 'feature-payments-subagent' --oneline
-jj log -r 'feature-analytics-subagent' --oneline
-# Each should show commits from respective subagent
-```
+**Agent workflow:**
+- Make changes and verify locally
+- Show `jj diff` output to main session
+- Wait for code review approval
+- After approval: run `jj describe -m "message"` to describe current change
+- Then: run `jj new --insert-after=@` to create new change for next work
+- Report final status
 
-**If bookmark missing:** Subagent provided wrong name or didn't commit. Ask them to verify.
+**If verification fails:**
+- Agent reports what failed and why
+- Agent attempts one retry OR hands off to main session
+- Agent does NOT commit failed work
 
-**If commits absent:** Subagent committed to wrong bookmark or work is incomplete.
+**Main session handles:**
+- Review agent changes before describe
+- Approve or request changes
+- Conflict resolution after `jj workspace update-stale`
+- Decision about failed verification (retry, fix, or revert)
 
-### Phase 2: Invoke Megamerge
+## After Each Agent Describes Changes
 
-Create merge change explicitly:
+After each agent reports they've described changes and created new change:
 
 ```bash
-jj new main -m "Merge: auth refactor, payments integration, analytics tracking"
-jj merge feature-auth-subagent feature-payments-subagent feature-analytics-subagent
-```
-
-**CRITICAL:** Use exact bookmark names. jj will error if names are wrong.
-
-### Phase 3: Identify Conflicts
+# Update workspace to see other agents' changes
+jj workspace update-stale
 
-```bash
+# Check for conflicts - if conflicts appear, resolve them
 jj status
-```
-
-This shows files with conflicts.
-
-If conflicts exist, you'll see conflict markers:
-```
-<<<<<<< Change from feature-auth-subagent
-code version A
-||||||| original code base
-original code
-=======
-code version from feature-payments-subagent
->>>>>>> Change from feature-payments-subagent
-```
-
-### Phase 4: Resolve Each Conflict Manually
-
-For EACH conflicting file:
-
-1. **Read BOTH versions and their commits:**
-   ```bash
-   jj log -r feature-auth-subagent -p -- <filename>
-   jj log -r feature-payments-subagent -p -- <filename>
-   ```
-   Understand WHY each made their change.
-
-2. **Decide the correct resolution:**
-   - Can both versions coexist? (Yes → combine them)
-   - Does one take precedence? (Yes → use that version)
-   - Do they need different handling? (Yes → edit both in)
-
-3. **Edit the file to resolve:**
-   Remove conflict markers. Write final code incorporating necessary parts of both versions.
-
-4. **Verify resolution by checking for markers:**
-   ```bash
-   grep -r "<<<<<<" .  # Should return nothing
-   grep -r "=======" .  # Should return nothing
-   ```
-
-**Do NOT:**
-- Guess which version is "correct" without reading commits
-- Keep both versions (that's not resolving, that's leaving conflict)
-- Pick one version arbitrarily
-- Skip reading the commits explaining the changes
-
-### Phase 5: Confirm All Conflicts Resolved
-
-```bash
-jj status
-# Should show NO conflicted files
-# Should show modified files (your resolutions)
-```
-
-### Phase 6: Complete Merge Commit
-
-```bash
-jj describe -m "Merge: auth refactor, payments integration, analytics"
-```
-
-## Verification Phase (Main Agent) - MANDATORY
-
-**This phase is MANDATORY. Not optional. Not conditional. Not skippable.**
-
-Merge success (no conflicts reported) does NOT equal code validity. Semantic conflicts (logic breaks) are invisible to merge tools.
-
-**Examples of semantic conflicts:**
-- Subagent A changes function signature; Subagent B calls with old signature
-- Subagent A changes initialization order; Subagent B assumes old order
-- Two subagents add conflicting defaults to same config
-
-**Merge "succeeds" for all of these.** Only verification catches them.
-
-### You MUST Complete Every Step Below
-
-**Pre-commitment:** Before seeing merge results, commit to running ALL steps. Not selective. All.
-
-### Step 1: Build/Compile (MANDATORY)
-
-```bash
-npm run build
-# OR equivalent for your language: cargo build, go build, python -m py_compile, etc.
-```
-
-**If this fails:** You have a semantic conflict. Merge succeeded textually, but code won't compile.
-
-**Resolution:**
-- Identify which files failed compilation
-- Determine which features' changes caused it
-- Edit code to fix the conflict
-- Re-run build until it passes
-- Re-run verification after fix
-
-**Do NOT skip because:** "It probably compiles fine" - semantic conflicts are COMMON.
-
-### Step 2: Run Complete Test Suite (MANDATORY)
-
-```bash
-npm test
-# OR equivalent: pytest, cargo test, go test ./..., etc.
-```
-
-Run ALL tests. Not subset. All.
-
-**If tests fail:** You have a semantic conflict in behavior. Merge succeeded, but features break each other.
-
-**Resolution:**
-- Identify which test is failing
-- Find which features' changes caused the failure
-- Edit code to fix the semantic conflict
-- Re-run test that was failing until it passes
-- Re-run full suite to ensure no regressions
-- Re-run verification after fix
-
-**Do NOT skip because:** "Tests pass independently" - integration breaks are COMMON.
-
-### Step 3: Manual Smoke Test (MANDATORY For Features With User Workflows)
-
-If your features have user-visible workflows, test them:
-
-1. Start the application
-2. Test workflows that involve multiple merged features
-3. Verify features don't interfere (e.g., Feature A's side effect doesn't break Feature B's behavior)
-4. Document: "Verified: auth login → payments checkout → analytics tracking all work together"
-
-**If workflows fail:** You have a semantic conflict in integration. Fix, re-test, re-run step 1-2.
-
-### Step 4: Review the Diff (MANDATORY)
-
-```bash
-jj diff main
-# OR jj show (shows current change)
-```
-
-Spot-check the changes:
-
-1. **Unexpected file deletions?** (Should be intentional)
-2. **Files that shouldn't have been touched?** (Indicates over-aggressive conflict resolution)
-3. **Conflict markers somehow missed?** (Unlikely but check)
-4. **Massive changes to single file?** (Review for correctness)
-
-### Step 5: Declare Completion ONLY After ALL Above Pass
-
-Do NOT declare success until:
-- Build passes
-- All tests pass
-- Manual smoke test passes (if applicable)
-- Diff reviewed
-
-Report to user:
-
-```
-MERGE COMPLETE
-
-Merged bookmarks:
-  ✓ feature-auth-subagent
-  ✓ feature-payments-subagent
-  ✓ feature-analytics-subagent
-
-Verification:
-  ✓ Build: PASS
-  ✓ Tests: PASS (487/487)
-  ✓ Smoke test: PASS (auth → payments → analytics workflow)
-  ✓ Diff review: PASS (expected changes only)
-
-Ready for: [deployment/review/next step]
-```
-
-**Do NOT report:** "Merge succeeded" or "No conflicts" as completion. Completion is VERIFICATION.
-
-## Red Flags - STOP If Any Of These
-
-### For Main Agent (Setup/Merge/Verification)
-
-- "I'll just assume subagents know what to do" → Write explicit instructions
-- "This merge seems simple, skip verification" → Verify ALL merges
-- "Tests probably pass, I'll skip the full suite" → Run full suite
-- "I'll compile-check instead of test" → Do both
-- "Merge succeeded so we're done" → Verification hasn't started
-
-### For Subagent (Execution)
-
-- "Let me check what others are doing" → Ask main agent if you have a dependency
-- "I'll quickly look at other bookmarks" → They don't exist
-- "I should avoid conflicts by seeing their work" → Conflicts handled at merge time
-- "Maybe I should wait for subagent B to finish" → No. Work independently.
-- "I'll just modify one file outside scope since I'm here" → Ask main agent first
-
-## Anti-Patterns to Avoid
-
-❌ **Subagent checks other bookmarks** → Breaks parallelism
-❌ **Main agent unsure about bookmark names** → Write them down
-❌ **Skipping verification because "merge looked clean"** → Semantic conflicts are invisible
-❌ **Treating merge success as terminal** → Verification is separate mandatory step
-❌ **Assuming independent passing tests = integration works** → Test the integration too
-❌ **Subagent waits for others to finish** → Defeats parallelism
-
-## Example Walkthrough
-
-### Setup (Main Agent)
-
-```bash
-# Create bookmarks
-jj bookmark create feature-login-subagent main
-jj bookmark create feature-oauth-subagent main
-
-# Send explicit instructions to each subagent (separate documents)
-# Instruction for Subagent A:
-#   Bookmark: feature-login-subagent
-#   Scope: src/login.ts, src/login.test.ts ONLY
-#   Tests: npm test -- login
-
-# Instruction for Subagent B:
-#   Bookmark: feature-oauth-subagent
-#   Scope: src/oauth.ts, src/oauth.test.ts ONLY
-#   Tests: npm test -- oauth
-```
-
-### Execution (Subagent A)
-
-```bash
-jj checkout feature-login-subagent
-# Implement login feature
-jj commit -m "login: add session validation"
-npm test -- login  # PASS
-# Report: "Feature login complete, all tests pass"
-```
-
-### Execution (Subagent B)
-
-```bash
-jj checkout feature-oauth-subagent
-# Implement OAuth feature
-jj commit -m "oauth: integrate OAuth2 provider"
-npm test -- oauth  # PASS
-# Report: "Feature OAuth complete, all tests pass"
-```
-
-### Merge (Main Agent)
-
-```bash
-jj new main
-jj merge feature-login-subagent feature-oauth-subagent
-# Handle any conflicts by reading commits, understanding why, resolving
-jj describe -m "Merge: login session validation + OAuth2 integration"
-```
-
-### Verification (Main Agent) - MANDATORY
-
-```bash
-npm run build  # PASS
-npm test  # PASS (all 342 tests)
-# Manual test: login flow → OAuth flow → combined workflow → all work
-jj diff main  # Reviewed: expected changes only
-# Report success
-```
-
-## Summary Checklist - MAIN AGENT
-
-**Setup Phase:**
-- [ ] Created separate bookmark for each subagent
-- [ ] Wrote explicit written instructions for each
-- [ ] Instructions include: bookmark name, file scope, test commands, exact commit format
-- [ ] Transmitted separate instructions to each subagent (no inter-subagent communication)
-
-**Execution Phase:**
-- [ ] Subagents reported completion with bookmark name and verification output
-- [ ] Each subagent's tests pass on their scope
-
-**Merge Phase:**
-- [ ] Verified all bookmarks exist
-- [ ] Verified commits exist on each bookmark
-- [ ] Ran megamerge with exact bookmark names
-- [ ] Identified all conflicts
-- [ ] Resolved each conflict by reading commits, understanding rationale, making informed decision
-- [ ] Verified no conflict markers remain
-
-**Verification Phase (MANDATORY):**
-- [ ] Build passes
-- [ ] Full test suite passes
-- [ ] Manual smoke test passes (if applicable)
-- [ ] Diff reviewed for unexpected changes
-- [ ] ONLY AFTER ALL ABOVE: Reported completion to user
-
-**DO NOT skip any verification step.**
-**DO NOT declare completion without verification.**
+# If conflicts shown, resolve them with jj resolve
+```
+
+**Key flow:**
+1. Agent uses `jj describe -m "message"` to add description to their work
+2. Agent uses `jj new --insert-after=@` to create new change in megamerge
+3. Main session runs `jj workspace update-stale` to pull in all changes
+4. Workspace automatically stays in megamerge history
+5. Conflicts automatically surface and are resolved locally
+6. Repeat for each agent
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Agents working sequentially | Dispatch with Task tool in PARALLEL, not sequentially |
+| Manual coordination between agents | Agents work in isolated workspaces, zero communication |
+| Creating workspaces during dispatch | Create all workspaces in Phase 1 BEFORE any agent starts |
+| Dispatching agents before ALL workspaces ready | Phase 1 MUST complete 100% before ANY Phase 2 dispatch |
+| Agent describing without approval | Agents MUST wait for main session code review before describing |
+| Agent not using `jj describe` | Must describe changes with `jj describe -m "message"` |
+| Agent not creating new change | Must use `jj new --insert-after=@` to start new change for megamerge |
+| Skipping `jj workspace update-stale` | Run after each agent describes to detect conflicts |
+| Agent touching other workspaces | Agents work ONLY in their assigned workspace |
+| Deleting workspaces before review | Keep workspaces until all agents complete and conflicts resolved |
+| Not resolving conflicts as they appear | Resolve conflicts immediately after `jj workspace update-stale` |
+
+## Red Flags - STOP
+
+If you catch yourself thinking ANY of these, you're about to violate the workflow. **All of these mean: RESTART and follow the workflow exactly.**
+
+| Red Flag | Reality |
+|----------|---------|
+| "I'll dispatch agents one at a time" | Defeats parallelism. Dispatch ALL at once with Task tool parallel calls. |
+| "Agents should check each other's work" | Complete isolation guaranteed. Agents never see other workspaces. Period. |
+| "I'll create workspaces during dispatch" | Create ALL workspaces in Phase 1 first. Dispatching early breaks isolation. |
+| "Agent can describe without approval" | Agents MUST wait for main session review. Approval gate is mandatory. |
+| "Agent doesn't need to describe changes" | NO. Must use `jj describe -m "message"` to capture work description. |
+| "Agent doesn't need new change" | NO. Must use `jj new --insert-after=@` to keep workspace in megamerge. |
+| "Verification can happen later" | Agents must verify and report BEFORE handing off to main session. |
+| "I'll skip `jj workspace update-stale`" | Run after each agent describes. This is how conflicts surface and get resolved. |
+| "I'll resolve conflicts after all agents done" | Resolve conflicts immediately as each agent completes. Early detection = easier. |
+| "Just one workspace can be created during dispatch" | Phase 1 MUST complete 100% first. Partial setup breaks isolation guarantees. |
+| "I'll create a custom `-workspaces` directory" | NO. Always use `~/src/workspaces/`. No exceptions, no alternatives. |
+| "This is overkill for just 2 agents" | Isolation discipline scales. Cut corners now, deal with conflicts later. |
+
+## 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.