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-part 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. Signed-in or authenticated browsing routes here. When no plugin declares a real browser profile, Desk's `desk-web` server is headless, isolated and signed out, and when one does, `desk-web` is already the operator's signed-in browser (see "The real browser profile"). Do NOT invoke for browser tasks where an isolated signed-out browser works, for unauthenticated scraping, or when the current Playwright MCP already has the signed-in state the task needs.

Verify Codex Desk alpha activation, including the selected Superpowers provider, owned MCP bridge and instruction block, runtime dependencies and Desk binding.

Decide where durable content belongs: the product repository, an operator's workspace, a generic plugin, or a context overlay. Invoke before encoding product behavior, interfaces, installation contracts, defaults, compatibility promises, release rules, a friction disposition, a captured lesson, an operator preference, a repo-specific gotcha, a reusable artifact just drafted, or a new skill's layer. Within a plugin, also decides the always-on foundation vs a triggered skill and whether to split a generic engine from a context skin. Do NOT invoke for file placement inside a workspace (that's `directory-structure`), beyond deciding that a just-drafted reusable artifact belongs in the desk at all, or for human-facing voice.

Work an improvement card by taking the oldest one with `improvement_next` and carry it to a shipped countermeasure, as standing, pre-authorized work the operator need not ask for; handle open andon issues first. Also invoke when the operator explicitly asks to process the open friction backlog (walk each open `_friction/*.md` entry and decide encode / no-op dispositions), with phrases like "let's go through friction", "process the backlog", "curate the friction", "work the improvement cards". 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.

Invoke when a Desk mechanism itself — a hook, a boot check, a migration, an MCP tool call, the sync step — fails to do its own designed job (a nonzero exit where zero was expected, an exception its own try/catch didn't already turn into a normal result, a budget timeout, or a result the mechanism itself flags as a failure state). This is about Desk breaking, not about the task the operator asked for. Do NOT invoke for an ordinary task failure (a failing test, a rejected PR review, a bug in the code being worked on) — that is the task's own problem, not Desk's.

Canonical layout of `$DESK/` — tracks, tasks, repo workspaces, reserved `_` directories, what may sit at the desk and track roots, naming conventions, renames, and rules for where planning/doing docs go. Use when creating a new track or task directory, placing a planning/doing doc or report, renaming or moving a task or track, or auditing or tidying a desk 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.

For `desk:observer` evaluating an Agentic Engineering V2 release alongside a human evaluator, or in an agent dry run of the same packet. Works through an evaluation packet from a cold start on the named host, records each step's outcome with evidence, times each scenario, classifies every problem as a defect, a confusion or a gap, and reports without fixing anything. Do NOT use for labeling a finished job's waste, for reviewing a pull request, or for any work observer did itself.

Invoke before giving a recommendation or claim that depends on external, mutable or unverified facts (a system's current behavior, a product, policy or market, an inherited handoff or another agent's claim), when curated records and current sources disagree, when the answer you have arrived at is complex or may answer an easier adjacent question, before quoting any duration, cost or scope estimate, and before acting on assumed-but-unverified evidence: supervised wrappers, explicit tool warnings, outcome messages, orchestration wrappers, auth transfer, durability claims, process cleanup, precedent claims, or test coverage. Also invoke when writing factual claims into a pull request, task card, handoff or subagent brief, for the citation procedure. Not needed for a routine status read directly from its source. Also invoke when a visual would help verify a state or a milestone claims a rendered, installed, merged or rollout state. Covers citation, primary sources, evidence precedence, fixtures and visual proof.

For `desk:observer` labeling the waste in a finished job's sessions from evaluator briefs that Desk prepared when the task reached `done`. Classifies each stretch of a session as value, support, muda or unknown with a confidence, names the waste, flags mura and muri, classifies why the agent stopped before each wait for the operator, cites evidence as exact fact intervals and writes labels with no free text. Do NOT use for evaluating a release, for reviewing a pull request, or for any job observer did or helped with.

Invoke before designing, planning, changing or reviewing the factory: derive, binding, reconcile, flush, the store pipeline and site, kaizen cards, andon, waste labels, or the factory docs. Carries the Lean reading and the terrarium checks every factory design, plan and review must pass.

Bootstrap a new Desk or upgrade an existing V1 Desk in place. Fresh bootstrap may discover, clone, create, bind, or skip a workspace; V1 upgrade preserves the existing workspace and durable state, records rollback evidence, replaces declarations with the reviewed V2 chain, verifies readiness, and resumes work.

How worker maintains the operator's friction log — appending new entries during real use, recording friction about the shared system (Desk, its skills and tools, the factory) as a kaizen candidate that opens an improvement card by itself, 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 when a task, iteration, delegated assignment or session ends.

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.

Coordinate an independent reviewer of the current candidate, finding disposition and re-review while leaving all implementation with the selected Superpowers owner.

Hard rules about how worker talks to the operator: one decision group per message; no question forms; few, long conversations; staying in a human-opened conversation; coaching; tidy and announce, never a naming proposal; frontloading what the human must supply; host task, memory, plan and autopilot commands versus the desk; act on confident decisions; respond in words before editing on new input; start announced parallel work in the same message; desk paths anchored in prose; time-to-first-action discipline (authorization as scope, ask only when blocked, no phantom limits); brevity; the remote substrate boundary; and invocation guidance. Always-on for response composition; invoke whenever new operator input arrives mid-work, before returning control or stopping short of agreed scope, when presenting several decisions, creating, moving or renaming a track or task, tidying the desk, aligning on new work or when the human is about to step away, or responding to a harness nudge about TaskCreate or its own memory.

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.

Evaluate a real Desk work item's outcome, flow, review burden and resource consumption at an agreed endpoint or observation horizon. Use for a work-item evaluation or retrospective, not for every tool call. Composes canonical Desk records, the factory's report for the finished job and existing independent outcome evidence. Does not own the lifecycle, start another implementation loop, run an offline benchmark, grant collection consent or rank people.

Invoke before anything is sent or scheduled in the operator's name — a chat message, an email, a calendar invitation, a PR comment or description, a work-item comment — and whenever worker drafts such content in the operator's voice. Owns the approval rule (the operator approves the exact audience and content before it goes; a go on the work is not approval to send) and the voice rules. 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.

Process explicitly requested feedback on the operator's PR, retain thread/state evidence and send remediation to the selected implementation owner. Not for another author's PR or unrequested feedback loops.

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.

Read-only PR evaluation when the operator requests a self-review or final polish pass. Fact-check and classify findings, then hand them to the selected Superpowers review cycle and existing implementation owner. Not a substitute for required reviewer approval.

Authoring and audit rules for PR descriptions and comments. Use before drafting or publishing a PR surface, including a draft from the selected Superpowers implementation owner.

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. Also invoke when the operator asks to widen the agent's permissions or to stop being prompted. Triggered by asks like "schedule", "post", "apply", "stage", "deploy", "allow this", or "stop asking me". Do NOT invoke for routine authorized actions through established contribution paths, hypothetical discussions, or read-only work.

Record and publish a participant's qualitative feedback about an installed engineering preview as attributed Markdown in their own desk. Use only for preview feedback a participant explicitly offers, not ordinary task discussion, code review, telemetry, or automatic friction logging. There is no feedback MCP tool; preserved private records are never migrated into Git.

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, a repo-knowledge auto-loader, and the rules for reading other people's repositories and clones (read-only, never rearranged).

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.

Checkpoint and resume an authorized non-terminal task, including a fresh-process handover after interruption, verified resource exhaustion or runtime pressure. Preserve actual source, unfinished work, work identity and authority; admit a replacement writer only after the prior owner is released. Also owns where private or sensitive operational evidence (raw transcripts, credentials, private measurement, customer data) is kept.

Session-start. Invoke as the FIRST thing in every agent session. Runs one script that does every mechanical startup step (migrations, host, prerequisites, sync, task index, card validation, push accounts, repo state, open PRs) and prints readable text that leads with the work, starting with one status line (status, desk path, host, sync), the active tasks grouped by state with each task's push route, open pull requests and repos, then only the numbered instructions that apply, and the desk's `AGENTS.md`. Hard-stops on a genuinely missing prerequisite. If no desk is bound, hands off to `first-run-bootstrap`. If the operator names a task, 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 when the migration needs one. 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 an operator description or from work the agent recognizes as task-shaped. Names the task from its outcome, routes it to the track whose scope line fits (or creates a new track with a scope line), and writes the task card, with no naming or filing question to the human. 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; this is a real 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.

Retired name for the Desk/Superpowers seam. Redirects to desk:using-superpowers-with-desk and retains the Work Suite capability mapping for unchanged standing instructions.

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 — one job as one task, states, valid transitions, the state-change protocol, and handling of adopted tasks with pre-completed planning. Use whenever a task changes state, when checking whether a proposed transition is valid, or when deciding whether new work is a new task or another iteration of an existing one.

Schema + body template for `track.md` — the per-track dashboard at the root of each track directory — including the one-line `scope:` that routes new work to a track. Use when creating a new track, reading an existing track, deciding whether work belongs in a track, or updating a track card's frontmatter, scope line or tasks table.

Desk's always-on foundation: how the human and the agent work together.

Map an existing Desk task, approval, plan and progress record onto one pristine Superpowers entry and an explicit artifact map. Invoke at the start of engineering work, at a reconciled resume, or at a material redesign.

Align new work before go by gathering every decision that needs the human's judgment into one batch with recommendations, then bind authorized engineering work to the selected Superpowers method and preserve Desk state and cross-repository dependency authority. Also invoke when a material new requirement arrives mid-task, for the rule on keeping it on the same durable task.