Previous version buried DAG placement in prose and duplicated instructions
throughout. Adding workspace between trunk and megamerge is critical for
clean integration—now it's a top-level phase step instead of buried detail.
Simplified agent contract by removing synchronous approval loop.

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
index 16afefc7..bfe50df8 100644
--- a/ai/claude/skills/coordinating-subagents-with-jj-workspaces/SKILL.md
+++ b/ai/claude/skills/coordinating-subagents-with-jj-workspaces/SKILL.md
@@ -15,11 +15,10 @@ Enable safe parallel feature development by dispatching independent subagents to
 
 **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
-- Must ensure isolation between parallel tasks
-- Single-agent tasks where you want structured isolated development
 
 **When NOT to use:**
 - Tasks have dependencies (use sequential development)
@@ -29,78 +28,86 @@ Enable safe parallel feature development by dispatching independent subagents to
 
 **CRITICAL: Create TodoWrite todos for EACH step below. This workflow has sequential gates.**
 
-### Phase 1: Define and Setup (Main Session)
+### Phase 1: Setup (Coordinator)
 
-- [ ] 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.
+- [ ] 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 Agents (Main Session)
+### Phase 2: Dispatch (Coordinator)
 
-- [ ] 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
+- [ ] Dispatch subagent with: task spec + workspace path + verification commands
+- [ ] For multiple agents: dispatch in parallel with Task tool
 
-### Phase 3: Execution and Incremental Validation (Agents + Main Session in Parallel)
+### Phase 3: Execution (Agent)
 
-**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
+- [ ] Agent makes file edits in workspace
+- [ ] Agent runs verification (tests, type checks)
+- [ ] Agent describes change: `jj describe -m "..."`
+- [ ] Agent creates new change: `jj new -A @ -B mm`
+- [ ] Agent reports completion with results and change ID
 
-**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
+### Phase 4: Review (Coordinator)
 
-### Phase 4: Cleanup (Main Session)
+- [ ] Sync: `jj workspace update-stale`
+- [ ] Review: `jj diff -r <workspace>@`
+- [ ] Check conflicts: `jj status`
+- [ ] Resolve conflicts if needed
 
-- [ ] Delete workspaces: `jj workspace forget <name>`
-- [ ] Remove isolated workspace directories
-- [ ] All agent work remains in the jj repository history
+### Phase 5: Cleanup (Coordinator)
 
-## Setup: Creating or Reusing Workspaces
+- [ ] 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:**
 
-**MANDATORY location:** `~/src/workspaces/` - This is the fixed, standard location across all projects.
+### 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.
 
-**DO NOT deviate from this structure.** Do not create custom directories like `-workspaces`, `parallel-work`, `subagent-work`, etc.
+```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
-# 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
+# Insert workspace change between trunk and megamerge
+jj rebase -r <workspace-name>@ -A 'trunk()' -B mm
 ```
 
-**NO custom paths. NO alternative directories. ALWAYS use `~/src/workspaces/`**
+Example:
+```bash
+jj rebase -r proj-123-feature-name@ -A 'trunk()' -B mm
+```
 
-**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
+**Result:** `trunk() → workspace change → mm`
 
-**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
+### 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
 
@@ -134,91 +141,88 @@ Task 3: Dispatch DB agent to db workspace
 ## Agent Contract (What Agents Must Do)
 
 **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
+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. Describe the change: `jj describe -m "feat: ..."` (use describing-changes skill)
+5. Create new change: `jj new -A @ -B mm`
+6. Report results: what changed, verification output, final change ID
+7. Make NO changes outside their workspace
 
 **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
+1. Make file edits in workspace
+2. Run verification commands
+3. Describe changes with `jj describe -m "..."`
+4. Create new change with `jj new -A @ -B mm`
+5. Report completion with results and change ID
+
+This inserts a new empty change between the completed work and the workspace's stable parent, ready for the next task.
+
+**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 main session
-- Agent does NOT commit failed work
+- Agent attempts one retry OR hands off to coordinator
 
-**Main session handles:**
-- Review agent changes before describe
-- Approve or request changes
+**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 (retry, fix, or revert)
+- Decision about failed verification
+- Pushing to remote
 
-## After Each Agent Describes Changes
+## After Agent Completes
 
-After each agent reports they've described changes and created new change:
+After each agent reports completion:
 
 ```bash
-# Update workspace to see other agents' changes
+# In main workspace: sync to see agent's changes
 jj workspace update-stale
 
-# Check for conflicts - if conflicts appear, resolve them
+# 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 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
+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 |
 |---------|-----|
-| 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` |
+| Skipping DAG placement | Must run `jj rebase -r <ws>@ -A 'trunk()' -B mm` after creating workspace |
+| Agent skipping `jj describe` | Agent must describe their changes before creating new change |
+| Agent skipping `jj new` | Agent must run `jj new -A @ -B mm` after describing |
+| 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. **All of these mean: RESTART and follow the workflow exactly.**
+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 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. |
+| "I'll skip DAG placement" | NO. Must insert workspace between trunk and mm for clean integration. |
+| "Agent doesn't need to describe" | NO. Agent must run `jj describe` to document the change. |
+| "Agent doesn't need jj new" | NO. Agent must run `jj new -A @ -B mm` after describing. |
+| "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