feat(advisor): add Advisor plugin (Grok 4.6 consults at key checkpoints)

[ericzakariasson]

Summary

Adds an Advisor plugin: the main model consults a stronger model at key points — before major decisions, when stuck on an error, and before declaring a task done. The advisor gets a full briefing plus the conversation transcript path, returns a verdict with guidance, and the main model keeps doing the work. The default advisor is the latest Grok (Grok 4.6) at its highest reasoning effort; because the advisor is a subagent with its own model, it can also be a different model family from the one doing the work (the ask in this thread).

What's in the plugin

Component	Purpose
Skill advisor	/advisor [model|off|status|ask ...|nudge on|off]. Defines the checkpoint protocol (when to consult, how to write the briefing, how to act on and report the verdict), model resolution (default cursor-grok-4.6-xhigh; /advisor <model> resolves against the subagent model slugs the agent already has in context, so nothing is hardcoded beyond the default), and the .cursor/advisor/state.json state file. Has icon/color so it can be pinned as a Custom Mode for a whole session.
Agent advisor-subagent	Read-only subagent pinned to grok-4.6[effort=xhigh] by default; the skill overrides the model per session via the Task model parameter and resumes the same advisor across consults so it accumulates context. Verifies the briefing against the repo, reads the transcript when a path is available, and answers with Verdict / Why / Recommendations / Risks / Answers / Confidence.
Hooks	afterFileEdit marks edits since the last consult; subagentStop (matcher ^advisor-subagent$) counts consults and appends the advice to .cursor/advisor/log.md; afterAgentResponse + stop post a one-line [Advisor] follow-up when a turn ends with unreviewed edits, at most once per batch of edits, and stay quiet when the agent ended on a question for the user. State is bound to the conversation that enabled it, so other conversations on the same project are untouched.

Also registers the plugin in .cursor-plugin/marketplace.json and the root README table.

Verification

• node scripts/validate-plugins.mjs passes.
• Hooks exercised with 26 simulated Cursor hook payloads (no state, activation binding, conversation isolation, question suppression, aborted turns, nudge-once-then-clear, consult recording/logging, non-advisor and failed subagents ignored, nudge: false, enabled: false, corrupt state) — all pass and every failure path exits 0 silently so it can never break the agent loop.
• bash -n on all hook scripts; scripts are committed as executable.
• Not verified here (no interactive client in the cloud environment): a live end-to-end run. Recommended before merge: symlink into ~/.cursor/plugins/local/advisor, run /advisor, edit a file, end the turn, and confirm the nudge fires, the consult runs on Grok 4.6, and .cursor/advisor/log.md gets an entry.

Notes for reviewers

• The agent is named advisor-subagent rather than advisor because Cursor also resolves /name to subagents, which would collide with the /advisor skill.
• Model IDs follow Cursor's docs: grok-4.6 is the SDK/frontmatter ID for Cursor Grok 4.6 with effort levels low/medium/high/xhigh; the skill's default uses the Task-tool slug form (cursor-grok-4.6-xhigh). If a slug is rejected, the skill falls back to the closest valid one from the tool's error (same approach as pstack's interrogate).
• Squash-merge is preferable: the first commit's message describes the feature by reference to another product's command; the PR title and body above do not.

  

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Contradictory advisor rebind protocol
  • Bare /advisor no longer short-circuits to status when enabled is already true; it always overwrites state so the current conversation rebinds and the previous advisor_agent_id is dropped.

Or push these changes by commenting:

@cursor push bd9f18dc34

Preview (bd9f18dc34)

diff --git a/advisor/skills/advisor/SKILL.md b/advisor/skills/advisor/SKILL.md
--- a/advisor/skills/advisor/SKILL.md
+++ b/advisor/skills/advisor/SKILL.md
@@ -22,7 +22,7 @@
 
 | Input | Action |
 | --- | --- |
-| `/advisor` | Enable with the default advisor (`grok`: Grok 4.6 at xhigh effort). If already enabled, report status instead. |
+| `/advisor` | Enable with the default advisor (`grok`: Grok 4.6 at xhigh effort). Always overwrite state to bind this conversation, even if `enabled` is already true. Use `/advisor status` to inspect without rebinding. |
 | `/advisor <model>` | Enable, or switch models, using an alias or a full model slug: `/advisor opus`, `/advisor claude-opus-5-thinking-max`. |
 | `/advisor off` | Disable: delete `.cursor/advisor/`. |
 | `/advisor status` | Report model, consult count, and whether the end-of-turn nudge is on. |
@@ -51,7 +51,7 @@
 ## Enabling
 
 1. Resolve the model from the alias table.
-2. Write `.cursor/advisor/state.json` with the file-writing tool (not a shell redirect), creating the directory if needed. Overwrite any existing file; a fresh `/advisor` re-binds the mode to this conversation.
+2. Write `.cursor/advisor/state.json` with the file-writing tool (not a shell redirect), creating the directory if needed. Overwrite any existing file, even if `enabled` is already true; a fresh `/advisor` re-binds the mode to this conversation and drops the previous `conversation_id` and `advisor_agent_id`.
 
    ```json
    {

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Consult path silently re-binds advisor
  • Consults no longer re-run Enabling when leftover state.json belongs to another chat; they skip or do a one-off ask without rewriting the file.
• ✅ Fixed: Re-bind leaves stale pending marker
  • Enabling now deletes pending and last-response.txt on re-bind so the new conversation does not inherit the previous chat's end-of-turn nudge.

Or push these changes by commenting:

@cursor push 7cee36e202

Preview (7cee36e202)

diff --git a/advisor/skills/advisor/SKILL.md b/advisor/skills/advisor/SKILL.md
--- a/advisor/skills/advisor/SKILL.md
+++ b/advisor/skills/advisor/SKILL.md
@@ -46,7 +46,7 @@
 ## Enabling
 
 1. Resolve the model as described above.
-2. Write `.cursor/advisor/state.json` with the file-writing tool (not a shell redirect), creating the directory if needed. If a state file already exists, carry over its `model` (unless this command names one) and `nudge`, and reset every other field to the values below. You cannot see which conversation an existing file belongs to, so always rewrite it: that re-binds the mode to this conversation, the hooks re-fill `conversation_id` and `transcript_path`, and the next consult starts a fresh advisor instead of resuming another chat's.
+2. Write `.cursor/advisor/state.json` with the file-writing tool (not a shell redirect), creating the directory if needed. If a state file already exists, carry over its `model` (unless this command names one) and `nudge`, and reset every other field to the values below. You cannot see which conversation an existing file belongs to, so always rewrite it: that re-binds the mode to this conversation, the hooks re-fill `conversation_id` and `transcript_path`, and the next consult starts a fresh advisor instead of resuming another chat's. Delete `.cursor/advisor/pending` and `.cursor/advisor/last-response.txt` if they exist, so a leftover end-of-turn nudge from the previous conversation does not fire here.
 
    ```json
    {
@@ -80,7 +80,7 @@
 
 ## How to consult
 
-1. Read `.cursor/advisor/state.json`. If it is missing or `enabled` is false, advisor mode is off: do not consult. Exception: the user explicitly asks in this message, in which case run a one-off consult with the default model and do not create the state file. If the file exists but you did not run the Enabling steps in this conversation, it belongs to another chat: run them now (that is what a bare `/advisor` does), then continue. Never `resume` an `advisor_agent_id` you did not save yourself in this conversation.
+1. Read `.cursor/advisor/state.json`. If it is missing or `enabled` is false, advisor mode is off: do not consult. Exception: the user explicitly asks in this message, in which case run a one-off consult with the default model and do not create the state file. If the file exists but you did not run the Enabling steps in this conversation, it belongs to another chat: do not consult, do not rewrite the file, and do not `resume` its `advisor_agent_id`. Exception: the user explicitly asks in this message, in which case run a one-off consult with the default model and leave the file unchanged. Never `resume` an `advisor_agent_id` you did not save yourself in this conversation.
 2. Build the briefing from `references/briefing-template.md`. Give the advisor everything it needs to disagree with you:
    - The user's request verbatim, plus constraints or corrections they added later.
    - What has happened so far, in order: what you investigated, decided, changed, tried, and ruled out.

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: One-off consult exception is overbroad
  • Scoped the one-off exception to chats that never ran Enabling, so in-session /advisor ask still resumes and writes state, and one-offs no longer pass another conversation's transcript_path.

Or push these changes by commenting:

@cursor push 82dd8a12c9

Preview (82dd8a12c9)

diff --git a/advisor/skills/advisor/SKILL.md b/advisor/skills/advisor/SKILL.md
--- a/advisor/skills/advisor/SKILL.md
+++ b/advisor/skills/advisor/SKILL.md
@@ -80,14 +80,14 @@
 
 ## How to consult
 
-1. Read `.cursor/advisor/state.json`. Advisor mode is on for this conversation only if the file exists with `enabled: true` and you ran the Enabling steps in this conversation. Otherwise do not consult at checkpoints, and leave the file alone: a file you did not write belongs to another chat, and only `/advisor` re-binds it. Never `resume` an `advisor_agent_id` you did not save yourself in this conversation. Exception: the user explicitly asks for a consult in this message (`/advisor ask ...`, or a request for a second opinion). Run it as a one-off: a fresh spawn on the file's `model` if there is one, otherwise the default; no `resume`; no state writes. Mention that `/advisor` turns the mode on for this conversation.
+1. Read `.cursor/advisor/state.json`. Advisor mode is on for this conversation only if the file exists with `enabled: true` and you ran the Enabling steps in this conversation. Otherwise do not consult at checkpoints, and leave the file alone: a file you did not write belongs to another chat, and only `/advisor` re-binds it. Never `resume` an `advisor_agent_id` you did not save yourself in this conversation. Exception: if you did not run Enabling in this conversation and the user explicitly asks for a consult in this message (`/advisor ask ...`, or a request for a second opinion), run it as a one-off: a fresh spawn on the file's `model` if there is one, otherwise the default; no `resume`; no state writes; do not pass `transcript_path` from `state.json`. Mention that `/advisor` turns the mode on for this conversation.
 2. Build the briefing from `references/briefing-template.md`. Give the advisor everything it needs to disagree with you:
    - The user's request verbatim, plus constraints or corrections they added later.
    - What has happened so far, in order: what you investigated, decided, changed, tried, and ruled out.
    - Relevant tool results verbatim: error messages, stack traces, test output, diffs. Trim unrelated noise and mark trims with `[...]`, but never paraphrase evidence.
    - Current state: `git status --short`, `git diff --stat`, files you touched, anything half-done.
    - Your specific questions, the options you see, and your current leaning with reasons.
-   - The `transcript_path` from `state.json` when set, so the advisor can read the full conversation itself.
+   - The `transcript_path` from `state.json` when set and advisor mode is on for this conversation, so the advisor can read the full conversation itself.
    - No secrets. Redact tokens, keys, and `.env` values.
 3. Spawn the advisor in the foreground and wait for it:
    - `subagent_type: "advisor-subagent"`

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit ebffdf0. Configure here.}