oh-my-opencode 4.13.0 → 4.14.0

package/packages/omo-codex/plugin/skills/frontend/references/designpowers/vendor/skills/voice-and-tone/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: voice-and-tone
+description: "Use when establishing or applying brand voice — defining voice attributes, tone adaptation across contexts, vocabulary lists, writing examples, and ensuring consistent personality across the interface"
+---
+
+# Voice and Tone
+
+Voice is who you are. Tone is how you say it right now. Voice stays constant. Tone adapts to context. This skill defines both so every word sounds like the same person wrote it.
+
+## When to Use
+
+- At the start of a project, during or after `design-strategy`
+- When the content-writer agent needs voice guardrails
+- When interface copy sounds inconsistent across screens
+
+## Step 1: Define Voice Attributes
+
+Choose 3-5. For each, define "this, not that":
+
+| Attribute | This | Not that |
+|-----------|------|----------|
+| Warm | Friendly, approachable | Sycophantic, emoji-heavy |
+| Knowledgeable | Confident, precise | Academic, condescending |
+| Direct | Clear, action-oriented | Blunt, cold, robotic |
+| Encouraging | Celebrates effort | Patronising, fake-cheerful |
+
+The "not that" column prevents drift.
+
+## Step 2: Define Tone by Context
+
+| Context | Feel | Example |
+|---------|------|---------|
+| Success | Celebration, warmth | "Your monstera is happy. Next water Thursday." |
+| Error | Calm, helpful, no blame | "We couldn't save that. Check your connection and try again." |
+| Onboarding | Welcoming, confidence-building | "Let's get to know your plants. About 30 seconds." |
+| Empty state | Inviting, action-oriented | "Your windowsill is empty. Add your first plant." |
+| Loading | Reassuring, brief | "Checking your plants..." |
+| Destructive | Clear, calm, reversible | "Remove this plant? You can undo this." |
+
+## Step 3: Build the Vocabulary
+
+| Always use | Never use |
+|-----------|----------|
+| water | irrigate |
+| happy | optimal |
+| check it out | investigate |
+| you | the user |
+
+The content-writer agent uses this as a constraint.
+
+## Step 4: Set Reading Level
+
+| Audience | Target |
+|----------|--------|
+| General consumer | Grade 6-8 |
+| Professional tool | Grade 8-10 |
+| Technical docs | Grade 10-12 |
+
+## Voice Audit Checklist
+
+- [ ] Every screen sounds like the same person wrote it
+- [ ] Voice attributes are present in the copy
+- [ ] Tone matches the context
+- [ ] Vocabulary list words used consistently
+- [ ] Reading level at or below target
+- [ ] Copy works read aloud by a screen reader
+
+## What You Deliver
+
+- Voice attributes table (3-5, with "this not that")
+- Tone guide by context with examples
+- Vocabulary list
+- Reading level target
+- 3-5 before/after examples
+
+## Integration
+
+- **Informed by:** `design-strategy`, `design-discovery`
+- **Feeds into:** `content-writer` agent, `accessible-content`, `design-critic`

package/packages/omo-codex/plugin/skills/frontend/references/designpowers/vendor/skills/writing-design-plans/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: writing-design-plans
+description: "Use when you have a design brief or strategy and need to break implementation into reviewable chunks — creates step-by-step plans with verification criteria for each task"
+---
+
+# Writing Design Plans
+
+A design plan breaks an approved design direction into discrete, reviewable tasks. Each task is small enough to evaluate clearly and specific enough that the result is predictable.
+
+## When to Use
+
+- After design-discovery and/or design-strategy have produced an approved direction
+- Before any implementation work begins
+- When a design task is too large to complete and review in one step
+
+## Process
+
+### Step 1: Review Inputs
+
+Gather:
+- Design brief (from design-discovery)
+- Strategy document (from design-strategy, if applicable)
+- Personas (from inclusive-personas)
+- Existing design system inventory
+
+### Step 2: Identify Design Tasks
+
+Break the work into categories:
+
+1. **Structure tasks** — information architecture, page hierarchy, navigation
+2. **Component tasks** — individual UI components that need designing
+3. **Layout tasks** — how components compose into screens
+4. **Interaction tasks** — states, transitions, feedback patterns
+5. **Content tasks** — copy, labels, error messages, help text
+6. **Accessibility tasks** — specific inclusive design requirements per component
+
+### Step 3: Order the Work
+
+Design work has natural dependencies:
+
+```
+Structure → Layout → Components → Interactions → Content → Review
+     ↑ accessibility woven through each step, not a final phase ↑
+```
+
+Order tasks so that:
+- Foundation work (structure, layout) comes before detail work (interactions, content)
+- Each task can be reviewed independently
+- Accessibility is addressed within each task, not deferred
+
+### Step 4: Write the Plan
+
+```markdown
+# Design Plan: [Feature/Project Name]
+
+> **For agentic workers:** REQUIRED: Use designpowers:designpowers-critique to review completed work against this plan.
+
+**Goal:** [One sentence — what this plan delivers]
+
+**Design Direction:** [Reference to the design brief or strategy]
+
+**Personas:** [Reference to personas this plan serves]
+
+---
+
+## Task 1: [Task Name]
+
+**Files:** [Which files will be created or modified]
+
+- [ ] Step 1: [Specific action]
+- [ ] Step 2: [Specific action]
+- [ ] Step 3: [Specific action]
+
+**Accessibility check:** [What inclusive design criteria this task must meet]
+
+**Verification:** [How to confirm this task is complete and correct]
+
+---
+
+## Task 2: [Task Name]
+...
+```
+
+### Step 5: Task Sizing
+
+Each task should be:
+- **2-5 minutes of focused work** — small enough to hold in your head
+- **Independently reviewable** — someone can evaluate it without seeing everything else
+- **Specifically described** — exact files, exact components, exact acceptance criteria
+- **Accessibility-inclusive** — each task addresses its own inclusive design requirements
+
+If a task takes longer than 5 minutes, break it down further.
+
+### Step 6: Save and Review
+
+Save to: `docs/designpowers/plans/YYYY-MM-DD-<feature>-plan.md`
+
+Present the plan to the user. Walk through:
+- Does the task order make sense?
+- Are any tasks missing?
+- Are the accessibility checks appropriate for each task?
+- Is the scope right, or should anything be deferred?
+
+User must approve the plan before execution begins.
+
+## Integration
+
+- **Called by:** `design-discovery`, `design-strategy`
+- **Calls:** Implementation begins via the relevant design skills (`ui-composition`, `interaction-design`, etc.)
+- **Pairs with:** `designpowers-critique` (reviews work against the plan)
+
+## Anti-Patterns
+
+| Pattern | Problem |
+|---------|---------|
+| Tasks without accessibility checks | Every task affects the user experience. Every task has accessibility implications |
+| Tasks that say "make it look good" | Vague tasks produce vague results. Be specific about what "good" means |
+| Accessibility as the final task | By then it is too late. Accessibility is in every task |
+| Plan without persona references | If you do not know who you are designing for, you cannot verify the design works |

package/packages/omo-codex/plugin/skills/git-master/SKILL.md

@@ -36,6 +36,10 @@ git merge-base HEAD origin/master
 
 Missing upstream or missing `main`/`master` is normal. Fall back to the best available branch or report the missing fact. Never treat a failed lookup as proof.
 
+## PR Body Evidence Attachments
+
+When a PR body needs screenshots or terminal PNGs, use the repo reference at `docs/reference/github-attachment-upload.md`. The allowed hosting path is GitHub user attachments from the authenticated web attachment flow; never commit temporary images, never use GitHub Releases for PR evidence, and never use external image hosts. Do not log browser cookies, CSRF tokens, S3 form fields, or upload headers.
+
 ## Commit Mode
 
 Commit only the user's requested changes. Preserve unrelated dirty work.

package/packages/omo-codex/plugin/skills/init-deep/SKILL.md

@@ -18,6 +18,10 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
+On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If a code block below conflicts with this section, this section wins.
+
+When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+
 For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 # /init-deep

package/packages/omo-codex/plugin/skills/refactor/SKILL.md

@@ -19,6 +19,10 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
+On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If a code block below conflicts with this section, this section wins.
+
+When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+
 For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 export const REFACTOR_TEMPLATE = `# Intelligent Refactor Command

package/packages/omo-codex/plugin/skills/remove-ai-slops/SKILL.md

@@ -19,6 +19,10 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
+On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If a code block below conflicts with this section, this section wins.
+
+When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+
 For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 # Remove AI Slops Skill

package/packages/omo-codex/plugin/skills/review-work/SKILL.md

@@ -18,6 +18,10 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
+On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If a code block below conflicts with this section, this section wins.
+
+When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+
 For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 ## Codex Subagent Reliability
@@ -58,7 +62,11 @@ gate, it is blocking. A timeout, missing deliverable, ack-only response,
 explicit `BLOCKED:`, or inconclusive lane is not a pass. Treat that lane as
 failed, investigate the underlying uncertainty with the `debugging` skill when
 runtime behavior may be wrong, fix with evidence, and rerun the affected lane
-before claiming completion or handing off a PR.
+before claiming completion, creating or handing off a PR, or merging.
+
+When reviewing a PR or branch, collect diff, file contents, and verification
+results from a dedicated review worktree attached to that branch. Never
+checkout, test, or edit the review branch in the main worktree.
 
 Review evidence must be safe to share. Redact or mask secrets and sensitive
 user data before including evidence in logs, PR bodies, or handoffs. Never
@@ -95,7 +103,7 @@ Before launching agents, collect these inputs. Extract from conversation history
 </required_inputs>
 
 
-**NEVER CHECKOUT A PR BRANCH IN THE MAIN WORKTREE. ALWAYS CREATE A NEW GIT WORKTREE (`git worktree add`) AND WORK THERE. THIS PREVENTS CONTAMINATING THE USER'S WORKING DIRECTORY WITH UNRELATED BRANCH STATE.**
+Review PRs and branches from a dedicated review worktree only: create or attach one with `git worktree add <path> <branch>` before collecting changed files, diff, file contents, or running checks. The main worktree is read-only context; never checkout, test, or edit the review branch there.
 
 **Auto-collection sequence:**
 
@@ -213,7 +221,7 @@ The QA agent follows a structured process: brainstorm scenarios exhaustively fir
 task(
   category="unspecified-high",
   run_in_background=true,
-  load_skills=["playwright", "dev-browser"],
+  load_skills=["browser:control-in-app-browser", "playwright", "dev-browser"],
   description="QA by actually running and using the application",
   prompt="""
 <review_type>QA - HANDS-ON APP EXECUTION</review_type>
@@ -281,7 +289,7 @@ Work through the task list in priority order (P0 first). For each test:
 6. Mark the task complete
 
 **Execution guidance by app type:**
-- **Web app**: Use playwright/dev-browser to navigate, click, fill forms, verify visual output.
+- **Web app**: In Codex, use `browser:control-in-app-browser` first for browser work that does not need an authenticated user session. Fall back to playwright/dev-browser when the Browser plugin is unavailable, lacks the needed action, or the test specifically needs a persistent/authenticated browser profile. Navigate, click, fill forms, and verify visual output through the chosen browser surface.
 - **CLI tool**: Run commands with various arguments, pipe inputs, check exit codes and output.
 - **Library/SDK**: Write and execute a test script that imports and exercises the public API.
 - **Backend API**: Use curl/httpie to hit endpoints with various payloads, verify response codes and bodies.

package/packages/omo-codex/plugin/skills/start-work/SKILL.md

@@ -19,6 +19,10 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
+On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If a code block below conflicts with this section, this section wins.
+
+When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+
 For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 ## ABSOLUTE RULE: YOU ARE AN ORCHESTRATOR — NEVER THE IMPLEMENTER
@@ -42,7 +46,7 @@ $start-work [plan-name] [--worktree <absolute-path>]
 ```
 
 - `plan-name` (optional): a full or partial file stem under `.omo/plans/`.
-- `--worktree` (optional): only when the user explicitly asks for a separate git worktree.
+- `--worktree` (required for PR/branch work; otherwise optional): the task-owned git worktree path.
 
 ## Phase 1: Select the plan
 
@@ -85,7 +89,7 @@ Write `.omo/boulder.json` before implementation starts. Prefix session ids with
 }
 ```
 
-If `--worktree` is set, verify the path with `git worktree list --porcelain` or create it with `git worktree add <path> <branch-or-HEAD>`, then store the absolute path as `worktree_path`. All edits, commands, tests, and evidence capture must run inside that worktree.
+For PR/branch work, `--worktree` is mandatory before implementation starts. Verify the path with `git worktree list --porcelain` or create it with `git worktree add <path> <branch-or-HEAD>`, then store the absolute path as `worktree_path`. All edits, commands, tests, and evidence capture must run inside that worktree.
 
 ## Phase 3: Execute the next checkbox
 
@@ -102,11 +106,12 @@ Each sub-task message must include:
 2. When the task touches existing behavior: a baseline characterization test, written first, that pins current observable behavior and passes on the unchanged code (exact inputs, exact observable, exact assertion). Then the failing-first proof for the new behavior before production changes — a unit test where a seam exists, otherwise the sub-task's Manual-QA scenario captured failing. A test that mirrors its implementation (mock-call assertions, pinned constants) is not evidence.
 3. Implementation constraints from the plan and project rules.
 4. Automated verification commands to run.
-5. One Manual-QA channel, named with the exact tool and exact invocation (the literal `curl`, `send-keys`, `page.click`, payload, selectors, and the binary observable that decides PASS/FAIL), not "verify it works". A LIGHT checkbox needs one real-surface proof of its deliverable, and auxiliary surfaces (CLI stdout, DB state diff, parsed config dump) are first-class when the surface is CLI- or data-shaped:
+5. One Manual-QA channel, named with the exact tool and exact invocation (the literal `curl`, `send-keys`, `browser:control-in-app-browser` action, `page.click`, payload, selectors, and the binary observable that decides PASS/FAIL), not "verify it works". A LIGHT checkbox needs one real-surface proof of its deliverable, and auxiliary surfaces (CLI stdout, DB state diff, parsed config dump) are first-class when the surface is CLI- or data-shaped:
    - HTTP call: `curl -i` against the live endpoint.
    - tmux: a `tmux` session driven with `send-keys`, dumped via `capture-pane`.
-   - Browser use: drive the real page with Chrome, or agent-browser (https://github.com/vercel-labs/agent-browser) when Chrome is unavailable.
+   - Browser use: in Codex, use `browser:control-in-app-browser` first when available and the scenario does not need an authenticated or persistent user browser profile; otherwise drive the real page with Chrome, or agent-browser (https://github.com/vercel-labs/agent-browser) when Chrome is unavailable.
    - Computer use: OS-level GUI automation against the running desktop app when the surface is not a page.
+   - TUI visual evidence: when a tmux/TUI claim needs visual QA or PR proof, run `node script/qa/web-terminal-visual-qa.mjs --from-file <capture.txt> --evidence-dir <dir>` and attach `terminal.png` plus `metadata.json`.
 6. The adversarial classes that apply to this sub-task (from the 9 ultraqa classes) and how each is probed.
 7. Required artifact path and cleanup receipt.
 
@@ -168,13 +173,13 @@ Only after verification passes:
 When all top-level checkboxes in `## TODOs` and `## Final Verification Wave` are complete:
 
 1. Run the plan's final verification commands.
-2. Complete the **Global Review and Debugging Gate** before any completion claim, PR handoff, or branch handoff:
+2. Complete the **Global Review and Debugging Gate** before any completion claim, PR creation, PR handoff, branch handoff, or merge:
    - Invoke the `review-work` skill with the final diff, changed files, user goal, constraints, run command, and verification evidence. All five review lanes must return PASS. A timeout, missing deliverable, ack-only child, `BLOCKED:`, or inconclusive lane is a gate failure, not approval.
    - Run a debugging-oriented runtime audit even when the review passes: name at least three plausible failure hypotheses for the changed surface, run the distinguishing checks against the actual artifact, and append the ruled-out or confirmed result to `.omo/start-work/ledger.jsonl`.
    - If any review lane or debugging hypothesis fails, invoke the `debugging` skill, confirm root cause with runtime evidence, add the minimal failing test or reproduction, fix it, rerun the affected verification, then rerun the Global Review and Debugging Gate.
    - Evidence hygiene is mandatory: redact or mask secrets and sensitive user data before writing `.omo/start-work/ledger.jsonl`, a PR body, or a handoff. Never include raw tokens, credentials, auth headers, cookies, API keys, env dumps, private logs, or PII; use concise summaries, lengths, hashes, or short non-sensitive prefixes instead.
-   - If the work includes creating, updating, or handing off a PR, refresh `git status` and the PR/branch state after the gate, and include only redacted review/debugging evidence in the PR body or handoff.
-3. If worktree mode was used, sync `.omo/` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff.
+   - If the work includes creating, updating, or handing off a PR, refresh `git status` and the PR/branch state from the task-owned worktree after the gate, and include only redacted review/debugging evidence in the PR body or handoff.
+3. Finish the PR/branch lifecycle from its task-owned worktree: sync `.omo/` state back to the main repo, create or update the PR when requested, wait for CI/review/Cubic gates, merge by default unless explicitly opted out, and remove the worktree only after successful merge or explicit handoff.
 4. Remove or mark the Boulder work as completed.
 5. Print an `ORCHESTRATION COMPLETE` block with the plan path, verification commands, Global Review and Debugging Gate verdict, artifacts, and cleanup receipts.
 
@@ -185,6 +190,7 @@ When all top-level checkboxes in `## TODOs` and `## Final Verification Wave` are
 - No tests-only completion claim. A Manual-QA artifact is required.
 - **NO DIRECT IMPLEMENTATION BY THE ORCHESTRATOR.** Root NEVER edits product files, writes tests, or runs QA itself — a spawned worker does.
 - No completion claim while an applicable ultraqa adversarial class was never probed. Each applicable class needs a captured observable result; each skipped class needs a one-line not-applicable reason in the ledger.
-- No `ORCHESTRATION COMPLETE`, final response, PR creation, or PR handoff before the Global Review and Debugging Gate passes with recorded evidence.
+- No `ORCHESTRATION COMPLETE`, final response, PR creation, PR handoff, or merge before the Global Review and Debugging Gate passes with recorded evidence.
+- No PR/branch implementation or review in the main worktree; create or use a task-owned git worktree first.
 - No unprefixed session ids in Boulder state. Codex sessions are always `codex:<session_id>`.
 - No stale-memory execution. The plan and ledger are the durable source of truth.

package/packages/omo-codex/plugin/skills/teammode/SKILL.md

@@ -89,10 +89,18 @@ subcommand rewrites `guide.md`, so the manual always matches the current team.
    exact title to use. If `codex_app.create_thread` accepts a working directory / cwd argument,
    set it to that member's worktree; otherwise the member's manual tells it to `cd` there first.
    Use `codex_app.set_thread_title` if the title did not land at creation.
+   If Codex returns only `pendingWorktreeId`, the worktree-backed thread is not ready yet: do not
+   `bind-thread` and do not send the member bootstrap. Wait until Codex surfaces a real `threadId`
+   or the thread appears in the thread list, then set the title, bind that real id with the cwd,
+   and only then send the bootstrap.
 3. `bind-thread` to record each thread id (and `--cwd`), then send that member's bootstrap
    trigger (printed by `add-member` / `member-prompt`) as the thread's first message. The trigger
    is short on purpose: it tells the new thread to READ its `guide.md` and `team.json` rather than
    carrying the whole protocol inline.
+4. Whenever you report, audit, reopen, or hand off a member thread, include the app deep link
+   `codex://threads/<thread_id>` next to the raw id. For example:
+   `codex://threads/019ef350-ee78-72a3-bd5e-e40cebc3d814`. Worktree-backed threads are easy to
+   lose in the sidebar without this link.
 
 Every team member is a real Codex thread created with `codex_app.create_thread` - this is strict,
 not a preference. NEVER substitute `multi_agent_v1.spawn_agent`, or any other in-process subagent,
@@ -113,8 +121,28 @@ members to the hard rules, so you mainly keep the channel open: expect frequent
 from each member - findings, `WORKING:`/`BLOCKED:` markers, peer digests - rather than one final
 dump, and act on them as they arrive. All member-to-member and member-to-leader traffic is in English;
 when the END user addresses a member, that member replies in the user's own language. Members hand off
-files and memos through the team `artifacts/` directory and reference them by path. Wait for every
-required member's final report before you declare the team done.
+files and memos through the team `artifacts/` directory and reference them by path.
+
+## Let members work - do not rush them
+
+Members heartbeat every few tool calls and message you on every finding, blocker, and finished
+slice (their manual binds them to this). So a member that is quiet between heartbeats is **working,
+not stalled** - a stretch of silence is the normal sound of focused work, not a problem to chase.
+Re-reading `codex_app.read_thread` to check on a calm member, or sending "any update?" / "are you
+done?" / "hurry up" pings, interrupts that member and slows the whole team. Trust the heartbeat and
+let them cook.
+
+Message a member only when one of these is true:
+- you have new information, context, or a correction it needs to do its slice right;
+- you are reassigning, narrowing, or unblocking its scope;
+- a peer's result changes what it should do; or
+- it has gone fully silent well past its heartbeat cadence AND that stall is blocking the team -
+  then send one specific question, not a barrage.
+
+Otherwise stay calm and keep the channel open: read inbound updates as they arrive and act on them.
+A long-running member is alive; a heartbeat you have not received yet is not a failure. Wait for
+every required member's final report before you declare the team done - rushing toward "done" while
+members are still mid-slice just produces half-built work you will have to redo.
 
 ## Worktrees - isolate members who would touch the same files
 
@@ -127,6 +155,16 @@ its own worktree. To land the work, `integrate --team <id>` merges every member
 current branch with a merge commit (never a squash or rebase); resolve any conflict it reports, then
 `worktree-remove` each worktree at cleanup.
 
+After `worktree-add`, immediately send the member a follow-up that includes both its assigned
+worktree path and its `codex://threads/<thread_id>` link. Use `bind-thread --cwd <worktree>` or
+`--worktree-path <worktree>` after the thread exists so `team.json`, `guide.md`, `status`, and
+`member-prompt` all point at the same worktree-backed thread.
+
+When the member starts inside a worktree, it must verify the assigned cwd exists and contains the
+repository checkout before editing. If the directory is missing, empty, or does not look like a git
+worktree/repository yet, the member reports `BLOCKED: worktree not ready` to the leader and waits
+instead of editing a parent checkout or an empty directory.
+
 ## Run a ulw-plan in parallel
 
 When a decision-complete plan already exists at `.omo/plans/<slug>.md` (from ulw-plan), execute its

package/packages/omo-codex/plugin/skills/teammode/scripts/team-guide.mjs

@@ -5,8 +5,12 @@
 // writes it once at team creation, and every member thread is told to READ it instead of
 // receiving the rules inline each turn.
 
+export function codexThreadLink(threadId) {
+	return `codex://threads/${threadId}`;
+}
+
 function memberLine(member) {
-	const thread = member.threadId ? ` | thread ${member.threadId}` : " | thread not created yet";
+	const thread = member.threadId ? ` | thread ${member.threadId} (${codexThreadLink(member.threadId)})` : " | thread not created yet";
 	const wt = member.worktree?.path ? ` | worktree ${member.worktree.path}` : "";
 	const name = member.name ? ` "${member.name}"` : "";
 	const title = member.threadTitle ? ` | thread title \`${member.threadTitle}\`` : "";
@@ -23,13 +27,23 @@ that is a coordination signal: mark yourself \`blocked\` and tell the leader at
 	}
 	const lines = team.members
 		.filter((m) => m.worktree?.path || m.worktree?.branch)
-		.map((m) => `- **${m.id}**: worktree \`${m.worktree.path ?? "(assign with bind-thread --cwd)"}\` on branch \`${m.worktree.branch ?? team.worktree.baseBranch}\``);
+		.map((m) => {
+			const thread = m.threadId ? `; thread ${codexThreadLink(m.threadId)}` : "";
+			return `- **${m.id}**: worktree \`${m.worktree.path ?? "(assign with bind-thread --cwd)"}\` on branch \`${m.worktree.branch ?? team.worktree.baseBranch}\`${thread}`;
+		});
 	return `## Worktrees (ISOLATION IS ON - this is not optional for you)
 
 This team runs each member in its own git worktree branched off \`${team.worktree.baseBranch}\`.
 **You MUST work only inside your own worktree.** The very first thing you do is \`cd\` into it;
 every edit, command, and commit happens there. Never touch another member's worktree, and
 never edit files outside your assigned scope. Commit your work so the leader can integrate it.
+Before editing, verify that your assigned worktree exists and contains repo files. If the path is
+missing, empty, or does not look like a git worktree/repository yet, send \`BLOCKED: worktree not ready\`
+to the leader and wait instead of editing any parent checkout or empty directory.
+
+If Codex returns only \`pendingWorktreeId\` while the leader is creating a worktree-backed member
+thread, the thread is not ready yet. The leader must wait until Codex surfaces a real thread id,
+then bind that real id and send the bootstrap.
 
 ${lines.length ? lines.join("\n") : "- (worktree paths are assigned as threads are bound; read team.json for yours)"}`;
 }
@@ -71,6 +85,8 @@ coordinate with each other, but the leader owns the final decision and integrati
 - **Reach the leader and your peers with \`codex_app.send_message_to_thread\` - not by narrating in
   your own thread, where no one reads it.** The address book is in team.json: the leader thread id
   is \`leader.sessionId\`, and each peer thread id is its \`members[].threadId\`.
+- **When you mention a Codex thread, include its app link too:** \`codex://threads/<threadId>\`.
+  These links are the fastest way for the leader to reopen worktree-backed member threads.
 - **Push a short message at each of these moments - never batch them into one report at the end:**
   - to the **leader**: every finding or decision, every file or sub-task you finish, a
     \`WORKING: <focus> - <phase>\` heartbeat every few tool calls so you never look stale, a
@@ -78,7 +94,9 @@ coordinate with each other, but the leader owns the final decision and integrati
   - to a **peer**: the instant you learn anything that touches their slice - a shared finding, a
     changed assumption, an interface they depend on. When unsure who owns it, send it to the leader.
 - **Going quiet is the only failure.** Many small lean messages beat one end-of-work dump; keep
-  every message short.
+  every message short. Your heartbeats are what let the leader relax and leave you to work: a leader
+  who can see your progress has no reason to interrupt you, while silence forces it to break in and
+  ask where things stand. Frequent lean updates buy you uninterrupted focus.
 
 ## Artifacts (how you hand work off)
 
@@ -103,10 +121,19 @@ export function buildMemberPrompt(team, id) {
 	if (!member) throw new Error(`no member with id "${id}"`);
 	const guide = team.paths?.guide ?? ".omo/teams/<session_id>/guide.md";
 	const teamJson = team.paths?.team ?? ".omo/teams/<session_id>/team.json";
-	const where = member.cwd ? `Work inside \`${member.cwd}\`.` : "Work from the repository root unless your manual assigns a worktree.";
+	const where = member.cwd
+		? `Work inside \`${member.cwd}\`.`
+		: team.worktree?.enabled
+			? "Wait for the leader to bind your worktree cwd before editing."
+			: "Work from the repository root unless your manual assigns a worktree.";
+	const threadLink = member.threadId ? `\nYour Codex thread link is ${codexThreadLink(member.threadId)}. Include it when reporting handoffs or worktree status.` : "";
+	const readiness =
+		team.worktree?.enabled
+			? "\nBefore editing, verify that your assigned worktree exists and contains repo files. If this prompt arrived before your Codex worktree checkout is ready, or the path is missing, empty, or not a git worktree/repository yet, report `BLOCKED: worktree not ready` to the leader and wait."
+			: "";
 	return `You are member ${member.id}${member.name ? ` (${member.name})` : ""} of team ${team.teamName} - owner of: ${member.focus}. Your thread title is \`${member.threadTitle}\`.
 FIRST read your field manual at \`${guide}\`, then the team state at \`${teamJson}\`; they define your scope, deliverable, the leader, the artifacts directory, and the communication rules.
-${where}
+${where}${threadLink}${readiness}
 Communicate with the team and leader in English; reply to the end user in the user's own language.
 Start now. Push updates to the leader and relevant peers with \`codex_app.send_message_to_thread\` as you work - findings, \`WORKING:\` heartbeats, and \`BLOCKED:\` the instant you stall - never just one report at the end.`;
 }

package/packages/omo-codex/plugin/skills/teammode/scripts/team.mjs

@@ -20,7 +20,7 @@ import { randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { buildGuide, buildMemberPrompt } from "./team-guide.mjs";
+import { buildGuide, buildMemberPrompt, codexThreadLink } from "./team-guide.mjs";
 import {
 	addMember,
 	archive,
@@ -164,8 +164,11 @@ const handlers = {
 		setMemberWorktree(team, { id: member.id, path: result.path, branch: result.branch });
 		await persist(team, dir);
 		const note = result.created ? "" : " (already exists)";
+		const thread = member.threadId
+			? `\nMember thread: ${codexThreadLink(member.threadId)}\nTell that member to: cd "${result.path}"`
+			: "\nMember thread is not bound yet; wait for the real Codex thread id, then bind-thread before sending bootstrap. After binding, send the member this worktree path.";
 		process.stdout.write(
-			`worktree for member ${member.id}${note}: ${result.path} on branch ${result.branch} (off ${result.base}).\nTell that member to: cd "${result.path}"\n`,
+			`worktree for member ${member.id}${note}: ${result.path} on branch ${result.branch} (off ${result.base}).${thread}\n`,
 		);
 	},
 
@@ -232,7 +235,8 @@ const handlers = {
 		const { team } = await loadTeam(cwd, sessionId);
 		process.stdout.write(`Team ${team.teamName} [${team.status}] - leader: main session - ${team.members.length} member(s)\n`);
 		for (const m of team.members) {
-			process.stdout.write(`  ${m.id} (${m.lens}) ${m.focus} -> ${m.deliverable || "(no deliverable)"} [${m.status}]${m.threadId ? ` thread=${m.threadId}` : ""}${m.cwd ? ` cwd=${m.cwd}` : ""}\n`);
+			const thread = m.threadId ? ` thread=${m.threadId} link=${codexThreadLink(m.threadId)}` : "";
+			process.stdout.write(`  ${m.id} (${m.lens}) ${m.focus} -> ${m.deliverable || "(no deliverable)"} [${m.status}]${thread}${m.cwd ? ` cwd=${m.cwd}` : ""}\n`);
 		}
 		if (isUnderstaffed(team)) {
 			process.stdout.write(