claudecode-omc 5.6.8 → 5.9.1

package/bundled/upstream/oh-my-claudecode/skills/team/SKILL.md

@@ -78,6 +78,7 @@ User: "/team 3:executor fix all TypeScript errors"
 ```
 
 **Storage layout (managed by Claude Code):**
+
 ```
 ~/.claude/
   teams/fix-ts-errors/
@@ -90,6 +91,10 @@ User: "/team 3:executor fix all TypeScript errors"
     ...
 ```
 
+## Goal Workflow Relationship
+
+Team is the OMC authority for parallel, staged execution. Use the deterministic conflict policies `refuse`, `adopt_existing`, and `artifact_only` rather than non-deterministic warning handling. If a task mentions Claude Code `/goal`, Ralph, UltraQA, or artifact-only Ultragoal, keep Team as the primary loop authority unless the leader explicitly hands off. Use `/goal` only as a documented native Claude Code handoff target or as visible evidence from the lead session; do not claim the `/goal` evaluator independently runs commands, reads files, or replaces `team-verify` / `team-fix`. Artifact-only Ultragoal references should be treated as durable goal ledger/checkpoint/evidence artifacts, not as worker execution by themselves.
+
 ## Staged Pipeline (Canonical Team Runtime)
 
 Team execution follows a staged pipeline:
@@ -100,13 +105,13 @@ Team execution follows a staged pipeline:
 
 Each pipeline stage uses **specialized agents** -- not just executors. The lead selects agents based on the stage and task characteristics.
 
-| Stage | Required Agents | Optional Agents | Selection Criteria |
-|-------|----------------|-----------------|-------------------|
-| **team-plan** | `explore` (haiku), `planner` (opus) | `analyst` (opus), `architect` (opus) | Use `analyst` for unclear requirements. Use `architect` for systems with complex boundaries. |
-| **team-prd** | `analyst` (opus) | `critic` (opus) | Use `critic` to challenge scope. |
-| **team-exec** | `executor` (sonnet) | `executor` (opus), `debugger` (sonnet), `designer` (sonnet), `writer` (haiku), `test-engineer` (sonnet) | Match agent to subtask type. Use `executor` (model=opus) for complex autonomous work, `designer` for UI, `debugger` for compilation issues, `writer` for docs, `test-engineer` for test creation. |
-| **team-verify** | `verifier` (sonnet) | `test-engineer` (sonnet), `security-reviewer` (sonnet), `code-reviewer` (opus) | Always run `verifier`. Add `security-reviewer` for auth/crypto changes. Add `code-reviewer` for >20 files or architectural changes. `code-reviewer` also covers style/formatting checks. |
-| **team-fix** | `executor` (sonnet) | `debugger` (sonnet), `executor` (opus) | Use `debugger` for type/build errors and regression isolation. Use `executor` (model=opus) for complex multi-file fixes. |
+| Stage           | Required Agents                     | Optional Agents                                                                                         | Selection Criteria                                                                                                                                                                                |
+| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **team-plan**   | `explore` (haiku), `planner` (opus) | `analyst` (opus), `architect` (opus)                                                                    | Use `analyst` for unclear requirements. Use `architect` for systems with complex boundaries.                                                                                                      |
+| **team-prd**    | `analyst` (opus)                    | `critic` (opus)                                                                                         | Use `critic` to challenge scope.                                                                                                                                                                  |
+| **team-exec**   | `executor` (sonnet)                 | `executor` (opus), `debugger` (sonnet), `designer` (sonnet), `writer` (haiku), `test-engineer` (sonnet) | Match agent to subtask type. Use `executor` (model=opus) for complex autonomous work, `designer` for UI, `debugger` for compilation issues, `writer` for docs, `test-engineer` for test creation. |
+| **team-verify** | `verifier` (sonnet)                 | `test-engineer` (sonnet), `security-reviewer` (sonnet), `code-reviewer` (opus)                          | Always run `verifier`. Add `security-reviewer` for auth/crypto changes. Add `code-reviewer` for >20 files or architectural changes. `code-reviewer` also covers style/formatting checks.          |
+| **team-fix**    | `executor` (sonnet)                 | `debugger` (sonnet), `executor` (opus)                                                                  | Use `debugger` for type/build errors and regression isolation. Use `executor` (model=opus) for complex multi-file fixes.                                                                          |
 
 **Routing rules:**
 
@@ -142,6 +147,7 @@ Each pipeline stage uses **specialized agents** -- not just executors. The lead
 ### Verify/Fix Loop and Stop Conditions
 
 Continue `team-exec -> team-verify -> team-fix` until:
+
 1. verification passes and no required fix tasks remain, or
 2. work reaches an explicit terminal blocked/failed outcome with evidence.
 
@@ -159,6 +165,7 @@ The lead writes handoffs to `.omc/handoffs/<stage-name>.md`.
 
 ```markdown
 ## Handoff: <current-stage> → <next-stage>
+
 - **Decided**: [key decisions made in this stage]
 - **Rejected**: [alternatives considered and why they were rejected]
 - **Risks**: [identified risks for the next stage]
@@ -177,6 +184,7 @@ The lead writes handoffs to `.omc/handoffs/<stage-name>.md`.
 
 ```markdown
 ## Handoff: team-plan → team-exec
+
 - **Decided**: Microservice architecture with 3 services (auth, api, worker). PostgreSQL for persistence. JWT for auth tokens.
 - **Rejected**: Monolith (scaling concerns), MongoDB (team expertise is SQL), session cookies (API-first design).
 - **Risks**: Worker service needs Redis for job queue — not yet provisioned. Auth service has no rate limiting in initial design.
@@ -190,6 +198,17 @@ The lead writes handoffs to `.omc/handoffs/<stage-name>.md`.
 - **Cancel:** `/oh-my-claudecode:cancel` requests teammate shutdown, waits for responses (best effort), marks phase `cancelled` with `active=false`, captures cancellation metadata, then deletes team resources and clears/preserves Team state per policy. Handoff files in `.omc/handoffs/` are preserved for potential resume.
 - Terminal states are `complete`, `failed`, and `cancelled`.
 
+## Windows psmux tmux-compatible gate
+
+On native Windows, do **not** tell users that `/team` requires WSL or that tmux is unavailable until the actual tmux-compatible binary has been checked. Native [psmux](https://github.com/psmux/psmux) installs a `tmux`-compatible command (often `tmux` / `tmux.cmd`) and is a supported Team multiplexer.
+
+Before blocking or falling back on Windows:
+
+1. Check `tmux -V` (or the platform equivalent such as `where tmux` followed by `tmux -V`).
+2. Treat a successful psmux-backed `tmux -V` as tmux available.
+3. If psmux/tmux is available, continue the normal Team flow; do not emit WSL-required guidance.
+4. Only when no tmux-compatible binary is available, tell the user to install psmux for native Windows support or use WSL2 as an alternative.
+
 ## Workflow
 
 ### Phase 1: Parse Input
@@ -219,6 +238,7 @@ Call `TeamCreate` with a slug derived from the task:
 ```
 
 **Response:**
+
 ```json
 {
   "team_name": "fix-ts-errors",
@@ -248,18 +268,18 @@ state_write(mode="team", active=true, current_phase="team-plan", state={
 
 **State schema fields:**
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `active` | boolean | Whether team mode is active |
-| `current_phase` | string | Current pipeline stage: `team-plan`, `team-prd`, `team-exec`, `team-verify`, `team-fix` |
-| `team_name` | string | Slug name for the team |
-| `agent_count` | number | Number of worker agents |
-| `agent_types` | string | Comma-separated agent types used in team-exec |
-| `task` | string | Original task description |
-| `fix_loop_count` | number | Current fix iteration count |
-| `max_fix_loops` | number | Maximum fix iterations before failing (default: 3) |
-| `linked_ralph` | boolean | Whether team is linked to a ralph persistence loop |
-| `stage_history` | string | Comma-separated list of stage transitions with timestamps |
+| Field            | Type    | Description                                                                             |
+| ---------------- | ------- | --------------------------------------------------------------------------------------- |
+| `active`         | boolean | Whether team mode is active                                                             |
+| `current_phase`  | string  | Current pipeline stage: `team-plan`, `team-prd`, `team-exec`, `team-verify`, `team-fix` |
+| `team_name`      | string  | Slug name for the team                                                                  |
+| `agent_count`    | number  | Number of worker agents                                                                 |
+| `agent_types`    | string  | Comma-separated agent types used in team-exec                                           |
+| `task`           | string  | Original task description                                                               |
+| `fix_loop_count` | number  | Current fix iteration count                                                             |
+| `max_fix_loops`  | number  | Maximum fix iterations before failing (default: 3)                                      |
+| `linked_ralph`   | boolean | Whether team is linked to a ralph persistence loop                                      |
+| `stage_history`  | string  | Comma-separated list of stage transitions with timestamps                               |
 
 **Update state on every stage transition:**
 
@@ -291,6 +311,7 @@ Call `TaskCreate` for each subtask. Set dependencies with `TaskUpdate` using `ad
 ```
 
 **Response stores a task file (e.g. `1.json`):**
+
 ```json
 {
   "id": "1",
@@ -338,6 +359,7 @@ Spawn N teammates using `Task` with `team_name` and `name` parameters. Each team
 ```
 
 **Response:**
+
 ```json
 {
   "agent_id": "worker-1@fix-ts-errors",
@@ -347,6 +369,7 @@ Spawn N teammates using `Task` with `team_name` and `name` parameters. Each team
 ```
 
 **Side effects:**
+
 - Teammate added to `config.json` members array
 - An **internal task** is auto-created (with `metadata._internal: true`) tracking the agent lifecycle
 - Internal tasks appear in `TaskList` output -- filter them when counting real tasks
@@ -401,6 +424,7 @@ state_write(mode="team", current_phase="team-fix", state={
 ```
 
 This enables:
+
 - **Resume**: If the lead crashes, `state_read(mode="team")` reveals the last stage and team name for recovery
 - **Cancel**: The cancel skill reads `current_phase` to know what cleanup is needed
 - **Ralph integration**: Ralph can read team state to know if the pipeline completed or failed
@@ -533,6 +557,7 @@ This addendum must preserve the core rule: **worker = executor only, never leade
 **CRITICAL: Steps must execute in exact order. Never call TeamDelete before shutdown is confirmed.**
 
 **Step 1: Verify completion**
+
 ```
 Call TaskList — verify all real tasks (non-internal) are completed or failed.
 ```
@@ -540,6 +565,7 @@ Call TaskList — verify all real tasks (non-internal) are completed or failed.
 **Step 2: Request shutdown from each teammate**
 
 **Lead sends:**
+
 ```json
 {
   "type": "shutdown_request",
@@ -549,11 +575,13 @@ Call TaskList — verify all real tasks (non-internal) are completed or failed.
 ```
 
 **Step 3: Wait for responses (BLOCKING)**
+
 - Wait up to 30s per teammate for `shutdown_response`
 - Track which teammates confirmed vs timed out
 - If a teammate doesn't respond within 30s: log warning, mark as unresponsive
 
 **Teammate receives and responds:**
+
 ```json
 {
   "type": "shutdown_response",
@@ -563,11 +591,13 @@ Call TaskList — verify all real tasks (non-internal) are completed or failed.
 ```
 
 After approval:
+
 - Teammate process terminates
 - Teammate auto-removed from `config.json` members array
 - Internal task for that teammate completes
 
 **Step 4: TeamDelete — only after ALL teammates confirmed or timed out**
+
 ```json
 { "team_name": "fix-ts-errors" }
 ```
@@ -575,6 +605,7 @@ After approval:
 **Step 5: Orphan scan**
 
 Check for agent processes that survived TeamDelete:
+
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-orphans.mjs" --team-name fix-ts-errors
 ```
@@ -582,6 +613,7 @@ node "${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-orphans.mjs" --team-name fix-ts-erro
 This scans for processes matching the team name whose config no longer exists, and terminates them (SIGTERM → 5s wait → SIGKILL). Supports `--dry-run` for inspection.
 
 **Shutdown sequence is BLOCKING:** Do not proceed to TeamDelete until all teammates have either:
+
 - Confirmed shutdown (`shutdown_response` with `approve: true`), OR
 - Timed out (30s with no response)
 
@@ -595,11 +627,11 @@ The team skill supports **hybrid execution** combining Claude agent teammates wi
 
 Tasks are tagged with an execution mode during decomposition:
 
-| Execution Mode | Provider | Capabilities |
-|---------------|----------|-------------|
-| `claude_worker` | Claude agent | Full Claude Code tool access (Read/Write/Edit/Bash/Task). Best for tasks needing Claude's reasoning + iterative tool use. |
-| `codex_worker` | Codex CLI (tmux pane) | Full filesystem access in working_directory. Runs autonomously via tmux pane. Best for code review, security analysis, refactoring, architecture. Requires `npm install -g @openai/codex`. |
-| `gemini_worker` | Gemini CLI (tmux pane) | Full filesystem access in working_directory. Runs autonomously via tmux pane. Best for UI/design work, documentation, large-context tasks. Requires `npm install -g @google/gemini-cli`. |
+| Execution Mode  | Provider               | Capabilities                                                                                                                                                                               |
+| --------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `claude_worker` | Claude agent           | Full Claude Code tool access (Read/Write/Edit/Bash/Task). Best for tasks needing Claude's reasoning + iterative tool use.                                                                  |
+| `codex_worker`  | Codex CLI (tmux pane)  | Full filesystem access in working_directory. Runs autonomously via tmux pane. Best for code review, security analysis, refactoring, architecture. Requires `npm install -g @openai/codex`. |
+| `gemini_worker` | Gemini CLI (tmux pane) | Full filesystem access in working_directory. Runs autonomously via tmux pane. Best for UI/design work, documentation, large-context tasks. Requires `npm install -g @google/gemini-cli`.   |
 
 ### How CLI Workers Operate
 
@@ -612,6 +644,7 @@ Tmux CLI workers run in dedicated tmux panes with filesystem access. They are **
 5. Lead reads the output, marks the task complete, and feeds results to dependent tasks
 
 **Key difference from Claude teammates:**
+
 - CLI workers operate via tmux, not Claude Code's tool system
 - They cannot use TaskList/TaskUpdate/SendMessage (no team awareness)
 - They run as one-shot autonomous jobs, not persistent teammates
@@ -619,16 +652,16 @@ Tmux CLI workers run in dedicated tmux panes with filesystem access. They are **
 
 ### When to Route Where
 
-| Task Type | Best Route | Why |
-|-----------|-----------|-----|
-| Iterative multi-step work | Claude teammate | Needs tool-mediated iteration + team communication |
-| Code review / security audit | CLI worker or specialist agent | Autonomous execution, good at structured analysis |
-| Architecture analysis / planning | architect Claude agent | Strong analytical reasoning with codebase access |
-| Refactoring (well-scoped) | CLI worker or executor agent | Autonomous execution, good at structured transforms |
-| UI/frontend implementation | designer Claude agent | Design expertise, framework idioms |
-| Large-scale documentation | writer Claude agent | Writing expertise + large context for consistency |
-| Build/test iteration loops | Claude teammate | Needs Bash tool + iterative fix cycles |
-| Tasks needing team coordination | Claude teammate | Needs SendMessage for status updates |
+| Task Type                        | Best Route                     | Why                                                 |
+| -------------------------------- | ------------------------------ | --------------------------------------------------- |
+| Iterative multi-step work        | Claude teammate                | Needs tool-mediated iteration + team communication  |
+| Code review / security audit     | CLI worker or specialist agent | Autonomous execution, good at structured analysis   |
+| Architecture analysis / planning | architect Claude agent         | Strong analytical reasoning with codebase access    |
+| Refactoring (well-scoped)        | CLI worker or executor agent   | Autonomous execution, good at structured transforms |
+| UI/frontend implementation       | designer Claude agent          | Design expertise, framework idioms                  |
+| Large-scale documentation        | writer Claude agent            | Writing expertise + large context for consistency   |
+| Build/test iteration loops       | Claude teammate                | Needs Bash tool + iterative fix cycles              |
+| Tasks needing team coordination  | Claude teammate                | Needs SendMessage for status updates                |
 
 ### Example: Hybrid Team with CLI Workers
 
@@ -680,18 +713,18 @@ The `getTeamStatus(teamName, workingDirectory, heartbeatMaxAgeMs?)` function pro
 Example usage in the monitor loop:
 
 ```typescript
-const status = getTeamStatus('fix-ts-errors', workingDirectory);
+const status = getTeamStatus("fix-ts-errors", workingDirectory);
 
 for (const worker of status.workers) {
   if (!worker.isAlive) {
     // Worker is dead -- reassign its in-progress tasks
   }
   for (const msg of worker.recentMessages) {
-    if (msg.type === 'task_complete') {
+    if (msg.type === "task_complete") {
       // Mark task complete, unblock dependents
-    } else if (msg.type === 'task_failed') {
+    } else if (msg.type === "task_failed") {
       // Handle failure, possibly retry or reassign
-    } else if (msg.type === 'error') {
+    } else if (msg.type === "error") {
       // Log error, check if worker needs intervention
     }
   }
@@ -704,14 +737,14 @@ if (status.taskSummary.pending === 0 && status.taskSummary.inProgress === 0) {
 
 ### Event-Based Actions from Outbox Messages
 
-| Message Type | Action |
-|-------------|--------|
-| `task_complete` | Mark task completed, check if blocked tasks are now unblocked, notify dependent workers |
-| `task_failed` | Increment failure sidecar, decide retry vs reassign vs skip |
-| `idle` | Worker has no assigned tasks -- assign pending work or begin shutdown |
-| `error` | Log the error, check `consecutiveErrors` in heartbeat for quarantine threshold |
-| `shutdown_ack` | Worker acknowledged shutdown -- safe to remove from team |
-| `heartbeat` | Update liveness tracking (redundant with heartbeat files but useful for latency monitoring) |
+| Message Type    | Action                                                                                      |
+| --------------- | ------------------------------------------------------------------------------------------- |
+| `task_complete` | Mark task completed, check if blocked tasks are now unblocked, notify dependent workers     |
+| `task_failed`   | Increment failure sidecar, decide retry vs reassign vs skip                                 |
+| `idle`          | Worker has no assigned tasks -- assign pending work or begin shutdown                       |
+| `error`         | Log the error, check `consecutiveErrors` in heartbeat for quarantine threshold              |
+| `shutdown_ack`  | Worker acknowledged shutdown -- safe to remove from team                                    |
+| `heartbeat`     | Update liveness tracking (redundant with heartbeat files but useful for latency monitoring) |
 
 This approach complements the existing `SendMessage`-based communication by providing a pull-based mechanism for MCP workers that cannot use Claude Code's team messaging tools.
 
@@ -755,6 +788,7 @@ When the user invokes `/team ralph`, says "team ralph", or combines both keyword
 ### Activation
 
 Team+Ralph activates when:
+
 1. User invokes `/team ralph "task"` or `/oh-my-claudecode:team ralph "task"`
 2. Keyword detector finds both `team` and `ralph` in the prompt
 3. Hook detects `MAGIC KEYWORD: RALPH` alongside team context
@@ -791,6 +825,7 @@ state_write(mode="ralph", active=true, iteration=1, max_iterations=10, current_p
 ### Cancellation
 
 Cancel either mode cancels both:
+
 - **Cancel Ralph (linked):** Cancel Team first (graceful shutdown), then clear Ralph state
 - **Cancel Team (linked):** Clear Team, mark Ralph iteration cancelled, stop loop
 
@@ -810,21 +845,21 @@ This prevents duplicate teams and allows graceful recovery from lead failures.
 
 ## Comparison: Team vs Legacy Swarm
 
-| Aspect | Team (Native) | Swarm (Legacy SQLite) |
-|--------|--------------|----------------------|
-| **Storage** | JSON files in `~/.claude/teams/` and `~/.claude/tasks/` | SQLite in `.omc/state/swarm.db` |
-| **Dependencies** | `better-sqlite3` not needed | Requires `better-sqlite3` npm package |
-| **Task claiming** | `TaskUpdate(owner + in_progress)` -- lead pre-assigns | SQLite IMMEDIATE transaction -- atomic |
-| **Race conditions** | Possible if two agents claim same task (mitigate by pre-assigning) | None (SQLite transactions) |
-| **Communication** | `SendMessage` (DM, broadcast, shutdown) | None (fire-and-forget agents) |
-| **Task dependencies** | Built-in `blocks` / `blockedBy` arrays | Not supported |
-| **Heartbeat** | Automatic idle notifications from Claude Code | Manual heartbeat table + polling |
-| **Shutdown** | Graceful request/response protocol | Signal-based termination |
-| **Agent lifecycle** | Auto-tracked via internal tasks + config members | Manual tracking via heartbeat table |
-| **Progress visibility** | `TaskList` shows live status with owner | SQL queries on tasks table |
-| **Conflict prevention** | Owner field (lead-assigned) | Lease-based claiming with timeout |
-| **Crash recovery** | Lead detects via missing messages, reassigns | Auto-release after 5-min lease timeout |
-| **State cleanup** | `TeamDelete` removes everything | Manual `rm` of SQLite database |
+| Aspect                  | Team (Native)                                                      | Swarm (Legacy SQLite)                  |
+| ----------------------- | ------------------------------------------------------------------ | -------------------------------------- |
+| **Storage**             | JSON files in `~/.claude/teams/` and `~/.claude/tasks/`            | SQLite in `.omc/state/swarm.db`        |
+| **Dependencies**        | `better-sqlite3` not needed                                        | Requires `better-sqlite3` npm package  |
+| **Task claiming**       | `TaskUpdate(owner + in_progress)` -- lead pre-assigns              | SQLite IMMEDIATE transaction -- atomic |
+| **Race conditions**     | Possible if two agents claim same task (mitigate by pre-assigning) | None (SQLite transactions)             |
+| **Communication**       | `SendMessage` (DM, broadcast, shutdown)                            | None (fire-and-forget agents)          |
+| **Task dependencies**   | Built-in `blocks` / `blockedBy` arrays                             | Not supported                          |
+| **Heartbeat**           | Automatic idle notifications from Claude Code                      | Manual heartbeat table + polling       |
+| **Shutdown**            | Graceful request/response protocol                                 | Signal-based termination               |
+| **Agent lifecycle**     | Auto-tracked via internal tasks + config members                   | Manual tracking via heartbeat table    |
+| **Progress visibility** | `TaskList` shows live status with owner                            | SQL queries on tasks table             |
+| **Conflict prevention** | Owner field (lead-assigned)                                        | Lease-based claiming with timeout      |
+| **Crash recovery**      | Lead detects via missing messages, reassigns                       | Auto-release after 5-min lease timeout |
+| **State cleanup**       | `TeamDelete` removes everything                                    | Manual `rm` of SQLite database         |
 
 **When to use Team over Swarm:** Always prefer `/team` for new work. It uses Claude Code's built-in infrastructure, requires no external dependencies, supports inter-agent communication, and has task dependency management.
 
@@ -881,9 +916,9 @@ Optional settings live in `.claude/omc.jsonc` (project) or `~/.config/claude-omc
       "maxAgents": 20,
       "defaultAgentType": "claude",
       "monitorIntervalMs": 30000,
-      "shutdownTimeoutMs": 15000
-    }
-  }
+      "shutdownTimeoutMs": 15000,
+    },
+  },
 }
 ```
 
@@ -907,27 +942,27 @@ Declare which provider (`claude`, `codex`, `gemini`) and which model tier should
 {
   "team": {
     "roleRouting": {
-      "orchestrator":  { "model": "inherit" },
-      "planner":       { "provider": "claude", "model": "HIGH" },
-      "analyst":       { "provider": "claude", "model": "HIGH" },
-      "executor":      { "provider": "claude", "model": "MEDIUM" },
-      "critic":        { "provider": "codex" },
+      "orchestrator": { "model": "inherit" },
+      "planner": { "provider": "claude", "model": "HIGH" },
+      "analyst": { "provider": "claude", "model": "HIGH" },
+      "executor": { "provider": "claude", "model": "MEDIUM" },
+      "critic": { "provider": "codex" },
       "code-reviewer": { "provider": "gemini" },
-      "test-engineer": { "provider": "gemini", "model": "MEDIUM" }
-    }
-  }
+      "test-engineer": { "provider": "gemini", "model": "MEDIUM" },
+    },
+  },
 }
 ```
 
-| Role | Provider | Model |
-|---|---|---|
-| `orchestrator` | claude (pinned) | inherits invoking session |
-| `planner` | claude | `HIGH` (opus) |
-| `analyst` | claude | `HIGH` (opus) |
-| `executor` | claude | `MEDIUM` (sonnet) |
-| `critic` | codex | codex default |
-| `code-reviewer` | gemini | gemini default |
-| `test-engineer` | gemini | `MEDIUM` (sonnet) |
+| Role            | Provider        | Model                     |
+| --------------- | --------------- | ------------------------- |
+| `orchestrator`  | claude (pinned) | inherits invoking session |
+| `planner`       | claude          | `HIGH` (opus)             |
+| `analyst`       | claude          | `HIGH` (opus)             |
+| `executor`      | claude          | `MEDIUM` (sonnet)         |
+| `critic`        | codex           | codex default             |
+| `code-reviewer` | gemini          | gemini default            |
+| `test-engineer` | gemini          | `MEDIUM` (sonnet)         |
 
 ### Canonical roles
 
@@ -998,15 +1033,15 @@ MCP workers can operate in isolated git worktrees to prevent file conflicts betw
 
 ### API Reference
 
-| Function | Description |
-|----------|-------------|
-| `createWorkerWorktree(teamName, workerName, repoRoot, baseBranch?)` | Create isolated worktree |
-| `removeWorkerWorktree(teamName, workerName, repoRoot)` | Remove worktree and branch |
-| `listTeamWorktrees(teamName, repoRoot)` | List all team worktrees |
-| `cleanupTeamWorktrees(teamName, repoRoot)` | Remove all team worktrees |
-| `checkMergeConflicts(workerBranch, baseBranch, repoRoot)` | Non-destructive conflict check |
-| `mergeWorkerBranch(workerBranch, baseBranch, repoRoot)` | Merge worker branch (--no-ff) |
-| `mergeAllWorkerBranches(teamName, repoRoot, baseBranch?)` | Merge all completed workers |
+| Function                                                            | Description                    |
+| ------------------------------------------------------------------- | ------------------------------ |
+| `createWorkerWorktree(teamName, workerName, repoRoot, baseBranch?)` | Create isolated worktree       |
+| `removeWorkerWorktree(teamName, workerName, repoRoot)`              | Remove worktree and branch     |
+| `listTeamWorktrees(teamName, repoRoot)`                             | List all team worktrees        |
+| `cleanupTeamWorktrees(teamName, repoRoot)`                          | Remove all team worktrees      |
+| `checkMergeConflicts(workerBranch, baseBranch, repoRoot)`           | Non-destructive conflict check |
+| `mergeWorkerBranch(workerBranch, baseBranch, repoRoot)`             | Merge worker branch (--no-ff)  |
+| `mergeAllWorkerBranches(teamName, repoRoot, baseBranch?)`           | Merge all completed workers    |
 
 ### Important Notes
 
@@ -1038,3 +1073,10 @@ MCP workers can operate in isolated git worktrees to prevent file conflicts betw
 10. **Broadcast is expensive** -- Each broadcast sends a separate message to every teammate. Use `message` (DM) by default. Only broadcast for truly team-wide critical alerts.
 
 11. **CLI workers are one-shot, not persistent** -- Tmux CLI workers have full filesystem access and CAN make code changes. However, they run as autonomous one-shot jobs -- they cannot use TaskList/TaskUpdate/SendMessage. The lead must manage their lifecycle: write prompt_file, spawn CLI worker, read output_file, mark task complete. They don't participate in team communication like Claude teammates do.
+
+## Parallel session caveats
+
+- **Multi-repo workspace anchor:** drop a `.omc-workspace` marker at the parent directory so multiple sessions across sub-repos share one `.omc/`. Resolution order: `OMC_STATE_DIR > .omc-workspace > git > cwd`. See `docs/REFERENCE.md`.
+- **Session id source:** OMC_SESSION_ID env var wins in CLI contexts; hook payload data.session_id wins in hook contexts.
+- **Plan id (when applicable):** Team state is session-scoped. Team handoffs at `.omc/handoffs/` are shared by design (see Wave G in the workspace plan).
+- **Parallel verdict:** supported (session-scoped + shared handoffs by design)

package/bundled/upstream/oh-my-claudecode/skills/ultragoal/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: ultragoal
+description: Durable multi-goal workflow that persists plan/ledger artifacts under .omc/ultragoal and prints Claude /goal handoff text for the active session
+argument-hint: "<brief or subcommand>"
+level: 3
+---
+
+<Purpose>
+Ultragoal breaks a brief into an ordered set of goals, records start/checkpoint/blocker/failure events in a durable append-only ledger, and tells the active Claude agent how to drive the Claude Code `/goal` slash command alongside the plan. It does not — and cannot — mutate Claude `/goal` state from the shell; it persists durable repo state and prints a model-facing handoff that the active agent must act on in-session.
+</Purpose>
+
+<Use_When>
+- The user wants a durable, repo-native way to track an ultragoal across multiple Claude sessions or worktrees
+- The work is large enough to warrant multiple ordered "stories" with attempt counts and per-story evidence
+- The user wants the final completion gated behind ai-slop-cleaner + verification + $code-review
+- The user wants the active Claude `/goal` directive coordinated with the ledger so that a session restart does not lose progress
+</Use_When>
+
+<Do_Not_Use_When>
+- The task is a single small change — use direct delegation or `ralph` instead
+- The user wants the assistant to literally invoke `/goal` itself from the shell — that is not possible; `omc ultragoal` only writes artifacts and prints handoff text
+- The user wants a planning-only artifact with no execution loop — use `plan` instead
+</Do_Not_Use_When>
+
+<Why_This_Exists>
+Claude Code `/goal` is a session-scoped Stop hook: it blocks the session from stopping until a condition holds, and auto-clears on success. That is a great single-session execution primitive, but it loses state across sessions and does not by itself enforce a final review gate. `omc ultragoal` adds a durable plan, ledger, and gating layer so a long multi-step initiative can survive session restarts, fresh worktrees, and review iterations while still leveraging Claude `/goal` to keep the active agent focused.
+</Why_This_Exists>
+
+<How_To_Use>
+
+1. Create a plan from a brief:
+   ```
+   omc ultragoal create-goals --brief-file plan.md
+   ```
+   Or with explicit stories:
+   ```
+   omc ultragoal create-goals --brief "ship the migration" \
+     --goal "Schema::Add new columns" \
+     --goal "Backfill::Backfill rows in batches" \
+     --goal "Cutover::Drop old columns and switch reads"
+   ```
+   The default mode is `aggregate` (one Claude `/goal` covers the run).
+   Pass `--claude-goal-mode per-story` if you want each story to have its own `/goal`.
+
+   **Multi-repo workspaces / parallel sessions:** when several Claude sessions
+   in the same workspace need to run `/ultragoal` concurrently, pass either
+   `--plan-id <stable-id>` or `--auto-plan-id` so the plan is written to
+   `.omc/ultragoal/plans/{planId}/` instead of the shared single-plan path.
+   Without that flag, two sessions creating goals would clobber each other.
+   `--auto-plan-id` derives `{epochMs}-{slug}` from the brief title. Then thread
+   the same `--plan-id <id>` through every subsequent subcommand in that session.
+   Use `omc ultragoal list-plans` to enumerate available planIds when needed.
+
+2. Start (or resume) the next story:
+   ```
+   omc ultragoal complete-goals
+   ```
+   This prints a model-facing handoff. The active Claude agent must read it and:
+   - Confirm/Set the active `/goal` condition in this session.
+   - Work the story.
+   - When the story is complete (and for the final story, after the full quality gate), share back a snapshot of the active `/goal` state and call `checkpoint`.
+
+3. Checkpoint a story:
+   ```
+   omc ultragoal checkpoint --goal-id G001-... --status complete \
+     --evidence "tests/files/PR evidence" \
+     --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'
+   ```
+   For the final story, also pass `--quality-gate-json` containing
+   `aiSlopCleaner`, `verification`, and `codeReview` evidence (all clean).
+
+4. If the final review is not clean, do NOT mark complete. Record blockers:
+   ```
+   omc ultragoal record-review-blockers --goal-id G00X-... \
+     --title "Resolve final code-review blockers" \
+     --objective "Fix the listed review findings and rerun final gates" \
+     --evidence "<the review findings>" \
+     --claude-goal-json '{"goal":{"objective":"...","status":"active"}}'
+   ```
+   This appends a new blocker story and keeps the Claude `/goal` active.
+
+5. Inspect state at any time:
+   ```
+   omc ultragoal status
+   ```
+
+</How_To_Use>
+
+<Important_Limitations>
+- The shell cannot invoke or mutate Claude Code `/goal` state. `omc ultragoal` only persists durable artifacts and prints instructions that the active Claude agent reads and acts on in-session.
+- Snapshots passed via `--claude-goal-json` are model-supplied proof of the active `/goal` state; OMC validates them for textual consistency with the plan's expected objective and ledger event, but it cannot independently observe Claude `/goal` state.
+- If the Claude `/goal` slash command is renamed or restructured, only the handoff wording needs to change; the reconciliation logic is name-agnostic.
+</Important_Limitations>

package/bundled/upstream/oh-my-claudecode/skills/ultraqa/SKILL.md

@@ -15,17 +15,21 @@ You are now in **ULTRAQA** mode - an autonomous QA cycling workflow that runs un
 
 **Cycle**: qa-tester → architect verification → fix → repeat
 
+## Relationship to `/goal`, Ralph, Team, and Ultragoal
+
+UltraQA owns repeated quality-gate cycling only. Use the deterministic conflict policies `refuse`, `adopt_existing`, and `artifact_only` rather than non-deterministic warning handling. Use it after the target behavior is known and the remaining question is whether tests, build, lint, typecheck, or another explicit QA condition passes. If Claude Code `/goal` is active, UltraQA may produce visible command evidence for that goal, but must not describe the `/goal` evaluator as independently running commands or reading files. If Ralph or Team is active, UltraQA is a verification/fix sub-loop under that authority rather than a competing session loop. If no active loop is safe, record QA expectations and evidence in artifact-only Ultragoal notes instead of claiming automatic execution.
+
 ## Goal Parsing
 
 Parse the goal from arguments. Supported formats:
 
-| Invocation | Goal Type | What to Check |
-|------------|-----------|---------------|
-| `/oh-my-claudecode:ultraqa --tests` | tests | All test suites pass |
-| `/oh-my-claudecode:ultraqa --build` | build | Build succeeds with exit 0 |
-| `/oh-my-claudecode:ultraqa --lint` | lint | No lint errors |
-| `/oh-my-claudecode:ultraqa --typecheck` | typecheck | No TypeScript errors |
-| `/oh-my-claudecode:ultraqa --custom "pattern"` | custom | Custom success pattern in output |
+| Invocation                                     | Goal Type | What to Check                    |
+| ---------------------------------------------- | --------- | -------------------------------- |
+| `/oh-my-claudecode:ultraqa --tests`            | tests     | All test suites pass             |
+| `/oh-my-claudecode:ultraqa --build`            | build     | Build succeeds with exit 0       |
+| `/oh-my-claudecode:ultraqa --lint`             | lint      | No lint errors                   |
+| `/oh-my-claudecode:ultraqa --typecheck`        | typecheck | No TypeScript errors             |
+| `/oh-my-claudecode:ultraqa --custom "pattern"` | custom    | Custom success pattern in output |
 
 If no structured goal provided, interpret the argument as a custom goal.
 
@@ -52,6 +56,7 @@ If no structured goal provided, interpret the argument as a custom goal.
    - **NO** → Continue to step 3
 
 3. **ARCHITECT DIAGNOSIS**: Spawn architect to analyze failure
+
    ```
    Task(subagent_type="oh-my-claudecode:architect", model="opus", prompt="DIAGNOSE FAILURE:
    Goal: [goal type]
@@ -60,6 +65,7 @@ If no structured goal provided, interpret the argument as a custom goal.
    ```
 
 4. **FIX ISSUES**: Apply architect's recommendations
+
    ```
    Task(subagent_type="oh-my-claudecode:executor", model="sonnet", prompt="FIX:
    Issue: [architect diagnosis]
@@ -71,16 +77,17 @@ If no structured goal provided, interpret the argument as a custom goal.
 
 ## Exit Conditions
 
-| Condition | Action |
-|-----------|--------|
-| **Goal Met** | Exit with success: "ULTRAQA COMPLETE: Goal met after N cycles" |
-| **Cycle 5 Reached** | Exit with diagnosis: "ULTRAQA STOPPED: Max cycles. Diagnosis: ..." |
-| **Same Failure 3x** | Exit early: "ULTRAQA STOPPED: Same failure detected 3 times. Root cause: ..." |
-| **Environment Error** | Exit: "ULTRAQA ERROR: [tmux/port/dependency issue]" |
+| Condition             | Action                                                                        |
+| --------------------- | ----------------------------------------------------------------------------- |
+| **Goal Met**          | Exit with success: "ULTRAQA COMPLETE: Goal met after N cycles"                |
+| **Cycle 5 Reached**   | Exit with diagnosis: "ULTRAQA STOPPED: Max cycles. Diagnosis: ..."            |
+| **Same Failure 3x**   | Exit early: "ULTRAQA STOPPED: Same failure detected 3 times. Root cause: ..." |
+| **Environment Error** | Exit: "ULTRAQA ERROR: [tmux/port/dependency issue]"                           |
 
 ## Observability
 
 Output progress each cycle:
+
 ```
 [ULTRAQA Cycle 1/5] Running tests...
 [ULTRAQA Cycle 1/5] FAILED - 3 tests failing
@@ -94,6 +101,7 @@ Output progress each cycle:
 ## State Tracking
 
 Track state in `.omc/ultraqa-state.json`:
+
 ```json
 {
   "active": true,
@@ -132,6 +140,13 @@ rm -f .omc/state/ultraqa-state.json
 
 This ensures clean state for future sessions. Stale state files with `active: false` should not be left behind.
 
+## Parallel session caveats
+
+- **Multi-repo workspace anchor:** drop a `.omc-workspace` marker at the parent directory so multiple sessions across sub-repos share one `.omc/`. Resolution order: `OMC_STATE_DIR > .omc-workspace > git > cwd`. See `docs/REFERENCE.md`.
+- **Session id source:** OMC_SESSION_ID env var wins in CLI contexts; hook payload data.session_id wins in hook contexts.
+- **Plan id (when applicable):** UltraQA state is session-scoped. Mutual-exclusion with ralph applies only within the same session.
+- **Parallel verdict:** supported (session-scoped state)
+
 ---
 
 Begin ULTRAQA cycling now. Parse the goal and start cycle 1.