desk

Add a new MCP to the operator's workspace runtime config so it auto-loads on every agent session via the workspace-config link. Use when the operator asks to "add an MCP", "configure an MCP", "I want to use the X tool" (where X is an MCP server), or otherwise needs a tool that isn't currently loaded. Covers both runtime-native builtin MCPs (under `[mcps.builtins.<alias>]`) and external npm-distributed stdio MCPs (under `[mcps.servers.<alias>]`). Handles the TOML schema choice, the comment convention, the verification step, and the commit-push-relaunch flow.

Six-step flow for bringing existing in-flight work (planning bundles, doing docs, prior-agent output, migrated project state) under worker's management. Use when the operator says "adopt this", "this is now yours", or picks Option 3 in the first-run bootstrap.

Move terminal-state tasks (and fully-terminal tracks) into _archive/ directories to keep the active workspace readable while preserving history. Use when a task transitions to `done` or `cancelled`, or when checking whether a track's tasks are all terminal so the track itself can be archived.

Invoke when the agent needs Playwright to drive a web UI behind an interactive authentication flow that a throwaway isolated browser cannot complete, when several agents need one persistent authenticated context without sharing tabs, or when the operator's existing Playwright MCP cannot reuse the required browser state. Covers claims-based context acquisition, lease-isolated CDP proxying, background-safe target creation, exact lease release, and broker status and recovery. Do NOT invoke for browser tasks where an isolated browser works, for unauthenticated scraping, or when the current Playwright MCP is already healthy.

Verify and repair Codex host-native Desk activation, including plugin source/marketplace exposure, Desk + Work Suite enablement, the activation-owned Desk MCP bridge, runtime dependency pack health, `$DESK` binding, and owned worker-default activation blocks.

Decide where a durable rule, lesson, fact, or preference belongs — the operator's workspace vs a plugin, which plugin (generic vs overlay), and within a plugin an always-on body/principles vs a triggered skill. Invoke whenever the agent is about to encode something durable and must choose its home: a friction disposition (curator), a captured lesson (lesson-capture), a new operator preference or rule, a repo-specific gotcha, a new skill's plugin layer (which layer it belongs in, and whether to split a generic engine from a context skin). Do NOT invoke for where files go *inside* a workspace (that's `directory-structure`), or for what to say to a human (that's a voice/comms concern).

Invoke ONLY when the operator explicitly asks to process the open friction backlog — walk each open `_friction/*.md` entry and decide encode / no-op dispositions. Triggered by phrases like "let's go through friction", "process the backlog", "curate the friction", "let's curate". Do NOT invoke for appending a new friction entry (that's `friction-management`), answering questions about what's in the backlog, or discussing friction abstractly.

Canonical layout of `$DESK/` — tracks, tasks, repo workspaces, reserved `_` directories, naming conventions, and rules for where planning/doing docs go. Use when creating a new track or task directory, placing a planning/doing doc, or auditing a track that looks disorganized.

A shared, surface-agnostic method for evaluating a document's substance: test the claims it rests on, ground them in the team's reference material, separate verified facts from author inferences and decisions, and produce findings the operator drives. Use from the review step of the surface skill you arrived from, or when the operator asks for substance: what jumps out, review the claims, is this grounded, poke holes in this. Evaluation only; it does not find, open, or deliver feedback to a surface, and is not for code PRs.

Invoke ONLY when worker is about to act on assumed-but-unverified evidence in concrete high-risk scenarios: supervised wrappers, explicit tool warnings, outcome claims, numeric estimates, orchestration wrappers, auth transfer, durability claims, process cleanup, or precedent claims. Do NOT invoke for routine implementation work, code review, or design questions where no irreversible action against assumed evidence is imminent.

Bootstrap the agent's `$DESK/` workspace repo on a machine where it doesn't exist yet. FIRST checks whether the operator already has a remote workspace repo on GitHub and offers to clone it. Only falls through to the fresh-create / operator-provides-path / skip menu if no remote is found. Hard-gates on `gh auth status` — if gh auth is broken, STOPS and waits — does NOT fall through to local-only init, because that forks operator state silently. Use when `session-start` discovers that `$DESK/` is missing.

How worker maintains the operator's friction log — appending new entries during real use, updating `Status:` lines when fixes land, and archiving landed/partial entries so the live log stays signal-dense. Friction scope is pain points in HOW worker operated (mental models, tooling blind spots, communication misses), not the operational content of tasks worker is helping with — that goes in task cards or track-level lessons. Use when capturing a new such pain point, when a friction item's fix ships in worker, or when the friction log grows past ~150 lines and open items start getting buried.

Keep the code repos the agent touches synced and never leave state behind. Use at session start, before starting work in a code repo, after every ref change, when a required check fails or previous validation proof may be reused, before every push, and at session end.

Use whenever the user asks to "humanize", "make this sound more human", "rewrite to avoid AI detection", "make this less AI-sounding", "add a human voice", or "write like a person". Also use when the user pastes text and asks why it reads as robotic, generic, flat, or AI-like, or when generating new text in a register where AI tells (em dashes, semicolons, hedges, banned vocabulary like "delve", "leverage", "robust") would damage credibility.

Hard rules about how worker talks to the operator: one decision group per message; slug permanence before creating directories; when to use TaskCreate or TodoWrite versus markdown task cards; act on confident decisions rather than narrate options; worker-tasks anchored in path prose; time-to-first-action discipline (authorization as scope, ask only when blocked, constrained questions); brevity in response prose (lead with action, no trailing offers, ban known tic-phrases, strip fabricated estimates, with a carve-out for artifact prose); the remote substrate boundary (worker's job ends at launch substrate-worker, not driving operator-as-keyboard sequences); and invocation guidance, naming the right surface. Always-on for response composition; explicitly invoked when presenting multiple decisions at once, creating a new track or task directory, or responding to a harness nudge about TaskCreate.

Agent-driven post-task lesson mining. Triggered when a task transitions to `done` (or after a non-trivial iteration). Reads the iteration's `planning.md`, `doing.md`, `feedback.md`, and artifacts; mines for patterns / mistakes / anti-patterns that surfaced during the work; proposes targeted updates to relevant skill bodies. Sister to `friction-management` — friction-management is operator-driven encoding from explicit friction entries; lesson-capture is agent-driven encoding from the work's own evidence. Use when an agent wants to self-learn from its own completed work without the operator having to surface friction explicitly.

Invoke ONLY when worker is drafting content for posting in the operator's voice — PR comments (top-level or thread reply), PR description prose, work-item comments, chat messages worker drafts for the operator to send. Triggered by other skills (pr-feedback-on-own-pr, pr-surface-hygiene, pr-self-review, peer-pr-review) at their drafting steps. Do NOT invoke for skill-internal docs, doing-doc / planning-doc prose, commit messages, or worker's own chat replies to the operator (different surfaces with different conventions).

Invoke ONLY when the operator hands worker a PR URL or ID and asks to review it — phrases like "review this", "let's review", "review Doris's PR", "review PR <id>". The PR is authored by someone else (not the operator). Do NOT invoke for the operator's own PRs (those use pr-self-review or pr-feedback-on-own-pr), for hypothetical PRs, or for general code-review questions divorced from a specific PR.

Invoke ONLY when the operator explicitly asks to iterate on a PR's reviewer feedback — addressing reviewer comments on an open PR. Triggered by phrases like "comments", "iterate", "address feedback", "review pass", "reviewer comments". Do NOT invoke for opening a new PR, authoring a PR description (that's `pr-surface-hygiene` + work-merger), discussing a PR abstractly, reviewing another author's PR, or pre-merge checks without explicit reviewer input.

Invoke ONLY when reviewing a PR (self or external) that adds a new abstraction / helper / pattern, OR when answering a provenance question about code in a diff ("where did X come from", "is X new", "what does this PR change about Y"). Triggered by phrases like "why did we add this helper", "is this new in the PR", "where did this field come from", "why does this PR need this". Also auto-invoked by `pr-self-review` Phase 2 / Phase 4 when a finding concerns a new abstraction or a provenance claim. Do NOT invoke for generic code review that does not involve challenging a design premise or tracing where something came from, for routine nit / style findings, or for architectural conversations that have no PR in scope.

Audit which reviewers are required on a PR (by files touched) and which are active approvers in the current PR's vote state. Produces a file→required-groups map + approver ranking. Use when operator asks "who needs to approve this PR," "what's the reviewer situation," or when drafting a who-to-ping message for a long-sitting PR.

Final pre-open fresh-eyes pass on a PR after operator-worker collab review cycles. Invoke only when the operator explicitly signals ready for a self-review convergence pass, phrased as run self-review, polish this PR, ready to share, final gate, or pr-self-review. Worker runs a thorough evaluation against the diff, fact-checks findings, classifies each as auto (the agent can fix it mechanically) or human (requires operator judgment), and enters a convergence loop that auto-addresses the auto findings via pr-feedback-on-own-pr, re-reviewing after each pass until no auto-addressable findings remain. Do NOT invoke during initial implementation (work-doer's job), during manual human-agent review cycles, or as a substitute for real reviewer sign-off; this is a final polish pass, not a replacement for humans.

Authoring rules for long-lived PR surfaces — the PR description body, top-level PR comments, and reply comments that aren't bound to a reviewer thread. Use before drafting any such content, and when auditing a draft handed off from an upstream tool (typically work-doer's `artifacts/pr-description.md`) before work-merger opens the PR. Keeps content from rotting against the pipeline it claims to describe.

Invoke ONLY when worker is about to take a live/shared-state action (send / schedule / post / publish / file / apply / deploy / change shared config) AND one condition holds — (a) more than one judgment substitution from the literal ask; (b) tooling cannot deliver the named shape and worker would substitute; (c) the action comes from research rather than an action mandate; OR (d) it would unilaterally mutate a partner-operated live surface without an established delegation/SOP/contribution path. Triggered by asks like "schedule", "post", "apply", "stage", or "deploy". Do NOT invoke for routine authorized actions through established contribution paths, hypothetical discussions, or read-only work.

Find or set up local clones for code repos referenced by a task card. Handles the multi-computer workflow where operators create task cards on one machine and resume on another with different directory layouts. Probes the current working directory, its parent, and common conventions before falling back to a two-option clone/provide flow. Also manages machine-local overrides, large-repo fallbacks, and a repo-knowledge auto-loader.

Invoke ONLY when the operator describes a runtime symptom that seems wrong — error responses, things that worked before now don't, unexpected outputs, performance changes — and worker would otherwise default to depth-first source-code reading. Triggered by phrases like "X is returning Y but shouldn't", "this used to work", "do not return until you understand exactly why X". Do NOT invoke for implementation tasks, design questions, or generic code-walking questions where no runtime behavior is in question.

Resume a specific non-terminal task the operator selected from the session-start status block. Reads the task card, checks the repo workspaces' git state, and re-enters the right workflow phase based on the task's current `status`. Use when the operator picks one of the listed active tasks.

Session-start checklist. Invoke as the FIRST thing in every agent session — probes prerequisites (gh binary + version floor + auth state, jq, Windows PATH gotchas), syncs the workspace repo, scans for active tasks, and emits a one-screen status block. Hard-stops on prereq failures; does NOT silently fall through to local-only operation. If `$DESK/` doesn't exist, hands off to `first-run-bootstrap`. If the operator picks a task to resume, hands off to `session-resumption`.

Auto-heal a machine's local state when it's stale relative to canonical names (workspace dir renamed, plugin moved, symlink target changed, etc.). Walks every enabled plugin's `migrations/` dir at session start; for each migration whose Detect block fires, runs Safety check + Migrate + Announce, then halts the session for restart. Self-evidencing predicates (no marker file). Used by `desk:session-start` early in its flow, before any path-dependent work.

Start a new task in the workspace from either an operator description or an agent-initiated proposal. Produces a task card in the appropriate track directory. Use when the operator says "start a new task: <description>", "work on X", "I need to do Y", "track this", "this is worth tracking", or when an agent recognizes mid-conversation that it's working on something task-worthy ("I'm investigating Z; let me track this") and proposes creating a task.

Emit a one-screen resume-friendly dashboard of all active worker state — tracks, tasks, uncommitted code changes, blockers, recent friction. Use when the operator says "status", "/status", "where are we", "summary", or asks any variant of the resume question.

Schema for `task.md` — the per-task card inside a task directory. Covers required fields, adoption signals (`planning_complete`, `adopted_at`), local-path portability via tilde paths, and adopted doc filename conventions. Use when creating, reading, or updating a task card.

The 8-state task lifecycle machine — states, valid transitions, the state-change protocol, and handling of adopted tasks with pre-completed planning. Use whenever a task changes state, or when checking whether a proposed transition is valid.

Schema + body template for `track.md` — the per-track dashboard at the root of each track directory. Use when creating a new track, reading an existing track, or updating a track card's frontmatter or tasks table.

Route authorized work through only the phases it needs, validate cross-repo dependencies, isolate parallel worktrees, and leave lifecycle state to Desk.