Cursor CLI Orchestrator - Cross-AI Task Delegation
CRITICAL — SELF-INVOCATION PROHIBITED
This skill dispatches to the Cursor CLI binary (cursor-agent). If the agent currently reading this skill is itself running inside cursor-agent (detection signals listed in ROUTER.md), the skill MUST refuse to load and return the documented error message instead of generating any cursor-agent invocation.
A running CLI skill never dispatches itself. The cli-X skills are for cross-AI delegation only — never self-invocation.
Orchestrate Cursor's terminal coding agent (cursor-agent) for tasks that benefit from a second AI perspective, Cursor's native model (Composer), read-only plan/ask exploration, or its unique worktree/cloud-worker/plugin surfaces.
Core Principle: Use Cursor for what it does best. Delegate, validate, integrate. The calling AI stays the conductor.
1. WHEN TO USE
Activation Triggers
- Cross-AI Validation — code review second perspective, bug detection, an independent implementation attempt.
- Composer Dispatch — tasks that specifically want Cursor's own native model (
composer-2.5/composer-2.5-fast), or the Grok (4.5/4.6/4.7) / GLM 5.2 tiers already on the enforced allowlist (see §3 Model Selection).
- Read-Only Exploration —
--mode plan (read-only planning) or --mode ask (read-only Q&A) when a task wants Cursor's analysis without any file writes.
- Isolated Experimentation — Cursor's native git worktree isolation (
-w/--worktree) for a change the operator wants tried in a disposable checkout, documented in references/cursor-tools.md as an opt-in escape hatch, not this packet's default dispatch shape.
- Specialized Generation — explicit Cursor requests naming Grok (4.5, 4.6 or 4.7) or GLM 5.2 specifically (the only non-Composer models on the enforced allowlist).
When NOT to Use
- You ARE Cursor already. If your runtime is
cursor-agent (detection signal: CURSOR_AGENT=1 set, CURSOR_CONVERSATION_ID set, cursor-agent in process ancestry, or an active-session probe under ~/.cursor/), this skill refuses to load. Self-invocation creates a circular dispatch loop and burns tokens for no value.
- Simple, quick tasks where CLI overhead is not worth it, or tasks needing an immediate response (auth/network round-trips may delay).
- Context already loaded and understood by the current agent.
- Interactive refinement requiring the full-screen TUI (use
cursor-agent directly instead).
- Tasks where Cursor CLI is not installed, or the account is not authenticated (
cursor-agent about reports "Not logged in").
2. SMART ROUTING
The hub's cli-cursor mode signal routes a Cursor CLI dispatch here when a request names cursor-agent, Composer, a Cursor plan or ask exploration, or Cursor's worktree and cloud-worker surfaces.
references/cli-reference.md and assets/prompt-quality-card.md load on every invocation; the hub ROUTER.md names the mode's first leaves.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. HOW IT WORKS
Prerequisites
- Install with
curl https://cursor.com/install -fsS | bash (Windows: irm 'https://cursor.com/install?win32=true' | iex).
- Authenticate
cli-cursor through Cursor account OAuth. Run cursor-agent login and complete the browser flow.
NO_OPEN_BROWSER disables browser opening for headless hosts.
- Use
CURSOR_API_KEY or --api-key for headless/CI auth.
- Full install, auth, flag, hook, and unique-surface tables are in the ALWAYS-loaded cli-reference.md.
This section keeps only the routing decisions and dispatch-critical gotchas.
Execution Ownership
This packet owns:
- user-facing routing,
- the
command -v cursor-agent availability probe,
- prompt construction, and
- the self-invocation guard.
Research and review lineages delegate process construction and execution to the already-shipped deep-loop runtime at ../../system-deep-loop/runtime/scripts/fanout-run.cjs, using executor kind cli-cursor.
That runner accepts only the research and review loop types.
For a single build or doc dispatch, use the child dispatch envelope in providers-and-models.md §5.
The runtime is the single Cursor execution adapter. Do not add a packet-local wrapper, command builder, or spawn path. Direct cursor-agent -p snippets below are operator reference and manual-testing examples; research and review lineages use the shared runtime, and a one-shot dispatch uses the child envelope.
Provider Auth Pre-Flight
MANDATORY before any first dispatch in a session. cursor-agent -p without a valid session exits 0 even on an auth failure — the exit code is never a reliable availability signal. Run this check once per session, cache the result, and re-run it only if a dispatch's output text (not its exit code) shows an authentication error.
# One-shot pre-flight: capture account auth status for routing
CURSOR_ABOUT=$(cursor-agent about 2>&1)
echo "$CURSOR_ABOUT" | grep -qi "not logged in" && CURSOR_AUTH_OK=0 || CURSOR_AUTH_OK=1
Decision tree (apply in order — first match wins):
| State |
CURSOR_AUTH_OK |
Action |
| Authenticated |
1 |
Proceed with cursor-agent -p "<prompt>" --output-format text --model composer-2.5 --auto-review --sandbox enabled |
| Not logged in |
0 |
ASK user to run cursor-agent login — surface the command, do NOT dispatch. Never substitute an unrelated CLI. |
User prompt template — not logged in:
Cursor CLI is not authenticated on this machine. cli-cursor uses Cursor account OAuth
(or CURSOR_API_KEY for headless auth). Run `cursor-agent login`
(browser flow), then confirm when login finishes — the skill will retry the original dispatch.
Error-recovery contract. If a dispatch's output text shows an auth error after pre-flight passed (session expired or revoked), invalidate the cache, re-run the pre-flight, and re-check before retrying. Never substitute a model the user didn't approve.
Model Selection — Enforced Allowlist
The cli-cursor dispatch is scoped to exactly 29 ids.
Never dispatch a model outside the allowlist, including auto.
Never substitute the closest-sounding allowed model without telling the user.
Default to composer-2.5.
Choose a Gemini 3.8 Flash High / GLM 5.2 / GPT-5.6 Luna Max / Grok (4.5, 4.6 or 4.7) tier only when the task or user explicitly names that family.
Cursor has no --reasoning-effort flag and rejects parameterized model brackets outright.
Select effort tiers through exact enumerated ids.
The enforced allowlist (29 ids) and per-task rationale table are inline in references/cli-reference.md §5 and references/providers-and-models.md §2.
The runtime layer enforces it through CURSOR_SUPPORTED_MODELS in executor-config.ts.
fanout-run.cjs and dispatch-model.cjs check it before constructing any command. This skill enforces it too.
If a task needs a model outside the allowlist, escalate to the user rather than fabricating a substitute or falling back to auto.
Default Invocation (Skill Default)
Default model + approval: composer-2.5 (Cursor's own native model) · auto-review approval (Smart Auto). auto (Cursor's own router) is NOT used — it can silently resolve to a model outside the enforced allowlist above, which defeats the point of enforcing one.
Fan-out fallback: a deep-loop lineage that pins no model runs Composer. The family is named here on purpose, without a version or an effort tier, so this line does not go stale when the family ships a point release; the runner resolves the current id. A drift test keeps the two in the same family.
cursor-agent -p "<prompt>" \
--output-format text \
--model composer-2.5 \
--auto-review \
--sandbox enabled
User override (honor explicit user phrasing verbatim, but ONLY within the enforced allowlist — see Model Selection above):
| User says |
Resolve to |
| (nothing specified) |
--model composer-2.5 --auto-review --sandbox enabled |
| "Use Composer" |
--model composer-2.5 --auto-review --sandbox enabled |
| "Use Composer fast" |
--model composer-2.5-fast --auto-review --sandbox enabled |
| "Use Composer max" / "Composer Max Mode" |
Composer has no -max (1M "Max Mode") tier — only composer-2.5/composer-2.5-fast. Tell the user; do not substitute another model's -max. |
| "Use Grok" / "Grok high" |
--model cursor-grok-4.6-high --auto-review --sandbox enabled |
| "Use Grok 4.7" / "Grok 4.7 high" |
--model grok-4.7-high --auto-review --sandbox enabled |
| "Use GLM" / "GLM max" |
--model glm-5.2-max --auto-review --sandbox enabled |
| "Just plan it, don't write anything" |
--model composer-2.5 --mode plan (read-only; approval flags do not apply in plan mode) |
| "Full auto, run everything" |
--model composer-2.5 --force --sandbox disabled |
| Any model NOT in the allowlist (e.g. "GPT-5.2 high", "use auto") |
Refuse the model, do not substitute silently. Tell the user this dispatch is scoped to the allowlist above and ask which allowed model to use instead. |
Honor whichever dimensions the user names (approval level, mode). Model stays on composer-2.5 unless the user explicitly names a different ALLOWED model.
Cursor Agent Delegation
The calling AI is the conductor.
Cursor's own skill system at ~/.cursor/skills-cursor/ confirms live that Cursor supports subagents natively.
Its skills include:
automate, babysit, canvas, create-hook, create-rule, create-skill, create-subagent, loop, migrate-to-skills, sdk, shell, split-to-prs, statusline, update-cli-config, and update-cursor-settings.
These are Cursor-editor-side conventions, not a -p <profile> flag like Codex's.
Find the full delegation contract and the --mode plan/--mode ask/default-agent execution-mode roster in agent-delegation.md.
| Task Type |
Execution mode |
| Code review / bug detection |
default agent, --sandbox enabled |
| Read-only exploration / architecture questions |
--mode ask |
| Multi-step planning without writes |
--mode plan |
| Code generation / file edits |
default agent, --auto-review or --force |
Custom Subagents (CORRECTION -- earlier claim was wrong)
An earlier pass recorded that "cursor-agent --help has no custom-agent-loading concept." That was wrong, and the error is instructive: agent profiles are discovered by file convention, never by a CLI flag, so grepping --help for a flag proves nothing about whether the concept exists.
Cursor CLI loads custom subagents from two places, confirmed live:
| Source |
Scope |
Status here |
.cursor/agents/*.md |
project |
This repo mirrors all 11 roster agents here |
.claude/agents/*.md |
project (Claude-format auto-import) |
Already worked before any mirror existed |
Cursor's own bundled create-subagent skill documents the format:
- Both
name and description frontmatter fields are required.
- The Markdown body is the system prompt.
A live cursor-agent --force -p roster probe lists all 11 repo agents alongside Cursor's own built-ins:
ai-council, code, context, debug, deep-research, deep-review, design, markdown, orchestrate, prompt-improver, and review.
The probe found no duplicate entries when both sources define the same name.
Each .cursor/agents/<name>.md is a symlink to the canonical .claude/agents/<name>.md.
This matches the discovery-mirror precedent already used for .claude/hooks/ and .codex/hooks/.
There is one source of truth, so a mirror can never drift from the agent it mirrors.
Note: ~/.cursor/agents/ (user-level) is documented by Cursor but a live probe found the CLI did not load a profile placed there; only the project-level paths above are verified working. Dispatch remains subject to this repo's own preToolUse spec-gate, which is correct behavior.
Repository Rules, Hook Delivery, and Parity Boundaries
Cursor CLI reads project .cursor/rules/*.md, root AGENTS.md, root CLAUDE.md, and legacy .cursorrules automatically. This repo now uses .cursor/rules/skill-routing.md as a compact, always-on pointer to the relevant top-level .skilled/skills/*/SKILL.md packets. It is static session context, not a replacement for dynamic per-turn classification.
The beforeSubmitPrompt adapter is designed to deliver a dynamic skill-advisor-equivalent brief.
Delivery is confirmed dormant under the installed Cursor CLI build.
Its source marks the status as registered but unconfirmed and records the shared-advisor delegation in user-prompt-submit.ts and user-prompt-submit.ts.
A live marker re-probe against cursor-agent 2026.07.23-e383d2b confirmed that beforeSubmitPrompt did not fire.
The static rules file therefore complements a missing dynamic brief.
It does not claim to provide per-turn advisor output.
The hook registration and adapter remain unchanged.
cursor-agent --help has no native command-roster listing subcommand. This repository still exposes a .cursor/commands/ parity surface: the synchronizer derives it from eligible .skilled/commands/ files, excludes goal-opencode.md, and adds the runtime-native goal-cursor.md; validate membership with command-scope.cjs and validate behavior with a real slash-command invocation.
Dispatch-Critical Gotchas
The full flag glossary, hook contract, shared-config surface, and troubleshooting table are in the ALWAYS-loaded cli-reference.md. Gotchas that silently break a dispatch and must be honored at routing time:
- The exit code is never an availability signal.
cursor-agent -p without auth exits 0 and prints an error to stdout/stderr instead. Every guard and pre-flight in this packet checks output text, never exit code.
- The canonical binary is
cursor-agent, never the bare agent alias. agent is a symlink to the same binary; using it in a process-ancestry match risks colliding with an unrelated agent command.
- Cursor shares its entire config surface with the Cursor editor (
.cursor//~/.cursor/: mcp.json, hooks.json, rules/, cli-config.json). A dispatched cursor-agent silently inherits the operator's shared hooks/MCP/rules unless a workspace/config-isolation flag is used — see shared-editor-config.md.
- No
model[effort=...] bracket support. Unlike some sibling CLIs' parameterized model syntax, cursor-agent --model 'cursor-grok-4.6[effort=high]' is rejected outright ("Cannot use this model") — effort tiers must be selected via an exact enumerated id (cursor-grok-4.6-high), never a bracket.
--auto-review/--force are the write-capable escalation, not --sandbox. --sandbox enabled|disabled toggles the OS-level sandbox; the approval decision (whether unattended actions run without a human) is --auto-review (Smart Auto) or --force/--yolo (Run Everything) — omitting both leaves Cursor's own prompt-and-block default in place, which cannot proceed unattended.
- Project-scoped MCP servers show
not loaded (needs approval) until trusted. For a non-interactive dispatch that needs MCP tools, add --approve-mcps to the cursor-agent -p command (auto-approves configured MCP servers for that run); for a persistent operator grant use cursor-agent mcp enable <server> (a trust mutation the automation itself must never run).
4. RULES
✅ ALWAYS
Verify Cursor CLI is installed before first invocation (command -v cursor-agent).
Delegate research and review lineages to ../../system-deep-loop/runtime/scripts/fanout-run.cjs with executor kind cli-cursor. It rejects every other loop type, so a single build or doc dispatch uses the child dispatch envelope in providers-and-models.md §5. Never build a second adapter in this packet.
Use --mode plan or --mode ask for read-only exploration/analysis/research; use the default agent mode with --auto-review or --force for code generation/file modification.
Validate Cursor-generated code (XSS, injection, eval, syntax checks via node --check, tsc --noEmit, etc.) before applying.
Capture stderr (2>&1) so errors surface; check output TEXT for auth/availability failures, never the exit code (always 0).
Redirect cursor-agent stdin from /dev/null on EVERY non-interactive dispatch — not only inside a while read loop, which is the condition this rule used to name and the reason it was skipped, mirroring the family-wide convention: cursor-agent -p "$PROMPT" > "$LOG" 2>&1 </dev/null &. Live-verified: a real cursor-agent -p ... </dev/null dispatch completes normally with no hang.
Specify model and approval mode explicitly — never rely on caller environment. Default: --model composer-2.5 --auto-review --sandbox enabled. Honor user overrides verbatim, but ONLY within the enforced allowlist (§3 Model Selection) — never auto, never a model outside the 29 allowed ids.
Route to --mode plan/--mode ask/default agent per the task type (see Section 3 routing table).
Pass the spec folder to the delegated agent in the prompt: if the calling AI has an active Gate-3 spec folder, include Spec folder: <path> (pre-approved, skip Gate 3). If none, ASK the user before delegating — the delegated agent cannot answer Gate 3 in --force/non-interactive mode.
Prompt construction & model-craft (cli- family precedence).* Compose every dispatch prompt via the 2-tier rule canonical in ../../sk-prompt/assets/cli-prompt-quality-card.md:
Fast path (default). Build from the local assets/prompt-quality-card.md, which delegates the framework table + CLEAR check to the canonical card.
Deep path (escalation). Dispatch @prompt-improver via the Task tool (never load full sk-prompt inline) when any canonical Tier 2 trigger applies — the trigger list lives in ../../sk-prompt/assets/cli-prompt-quality-card.md under "Tier 2 — Deep path"; do not re-enumerate it here.
Never inject user-level voice/personalization content into AI-orchestrated Cursor delegations. Cursor CLI reads rules from .cursor/rules, AGENTS.md, CLAUDE.md, and legacy .cursorrules automatically. When an AI delegates via cursor-agent -p, the calling AI's own voice rules govern the response — keep delegations focused on task/model/approval/(spec-folder pre-approval).
Code Standards Loading (surface-aware contract) — When dispatching for code review or code generation, instruct the dispatched session to:
- Load
sk-code.
- Let
sk-code emit a surface tag matching the detected stack from markers and target files.
- Load the selected surface resources and run its verification commands.
- Add
code-review only for formal findings-first review output.
Fallback: if the surface cannot be determined confidently, ask for the runtime surface and verification command set.
NEVER hardcode obsolete sibling code skills in dispatch prompts.
Design Standards Loading (measured-reference contract) — When dispatching for design or UI work, instruct the dispatched session to:
- Load
sk-design-md-generator.
- Extract a measured Style Reference DESIGN.md from the live source before building UI. Include named color tokens, type scale, components, and Quick-Start CSS/Tailwind.
- Build against those measured tokens and run the extraction's validate step to confirm hex/section fidelity.
Fallback: if there is no live source to measure, ask for the reference URL or the exact tokens to build against.
NEVER treat mcp-figma or sk-design-md-generator as a taste, visual-direction, or critique authority.
The extraction measures real CSS; it does not judge design.
Pass the design reference manifest to the dispatched session — when dispatching design or UI work, inline a DESIGN_DISPATCH_MANIFEST v1 block in the prompt.
The child cannot resolve skill paths, so the manifest travels in the payload, not by reference.
Include styleReferenceExtracted true, the live source that was measured, the measured design tokens / type scale / components the child must build against, loadedFiles, and proofDemandBack.
If the manifest cannot be assembled because no Style Reference was extracted or no live source can be measured, ASK before launching the child rather than starting a silent design dispatch.
The child returns the demanded proof, and the parent reconciles it on the return path.
Single-dispatch discipline (operator-gated, session-scoped).
- By default, launch ONE cli-* dispatch at a time across the cli-* family.
- Wait for the dispatched agent's work to return and verify that outputs exist.
Then SIGKILL only the dispatch THIS skill started. Capture its PID at launch with
cursor-agent -p ... & CURSOR_PID=$!.
Kill that PID directly and its own orphan children with kill -9 "$CURSOR_PID" 2>/dev/null; pkill -9 -P "$CURSOR_PID" 2>/dev/null.
- Never use a blanket
pkill -9 -f "cursor-agent" pattern. It matches and kills EVERY running cursor-agent process on the machine, including the operator's unrelated Cursor sessions and the operator's own Cursor editor, since the CLI shares the binary family.
- Launch the next dispatch, this skill or a sibling, only after the prior one is dead and RSS has dropped.
- Within a deep-flow session (deep-review / deep-research), the operator authorizes the whole multi-iteration session at the start.
Iterations chain back-to-back with kill-between as the safety mechanism, NOT a per-iteration confirmation prompt.
- Exception (cross-skill parallel): when the operator explicitly authorizes N parallel dispatches, run N concurrently.
Still SIGKILL each by its own captured PID as its work returns.
Set AI_SESSION_CHILD=1 in the dispatched child's env and state the exemption in the prompt.
The variable makes the waiver true, but it does not make it observable.
The reader being waived is a model, and a model cannot see an environment variable.
A child given only the variable still stops to ask the documentation-scope question and writes nothing, at exit code zero.
Copy the preamble from shared/references/child-dispatch-preamble.md to the top of every non-interactive prompt.
A session may be launched through the per-session worktree wrapper (.skilled/bin/worktree-session.sh).
A dispatched cursor-agent -p is an orchestrated sub-session, not a new top-level session.
It must SHARE the parent's worktree rather than allocate its own.
This is distinct from Cursor's own native -w worktree flag, which this packet's default dispatch never passes.
Pattern: AI_SESSION_CHILD=1 cursor-agent -p ... </dev/null.
This is harmless when the wrapper is not in use.
See .skilled/bin/README.md → "Worktree session isolation".
Agent-persona injection (attach identity, not just the task).
Every dispatch composes {resolved agent persona + task prompt}, never a bare task.
Resolve the persona from the ACTIVE runtime's agent directory per AGENTS.md §9:
.cursor/agents/<name>.md, .claude/agents/<name>.md, .skilled/agents/<name>.md, and other runtime paths.
Never hardcode one runtime.
Map each subtask to the RIGHT agent, not one default:
code→code, review→review, design→design, research→deep-research, and docs→markdown.
Cursor has a native file-convention subagent surface.
.cursor/agents/*.md and .claude/agents/*.md mirror all 11 canonical agents.
Dispatch by naming the resolved subagent to satisfy the rule.
On a bare cursor-agent -p that names no subagent, INLINE the persona block into the payload.
Use the same in-payload pattern as the DESIGN_DISPATCH_MANIFEST (Rule 14), because the child cannot resolve agent paths by reference.
A persona-less dispatch runs the leaf as a generic assistant and silently drops the agent's tool-scope, verification gates, and output contract.
The canonical contract is ../../sk-prompt/assets/cli-prompt-quality-card.md "Persona Injection".
The native precedent is orchestrate.md "Agent Loading Protocol".
Declare rare exceptions at the dispatch site: a native surface used, a focused summary for a small-context model, or a pure-mechanical command.
⛔ NEVER
- Pass
-w/--worktree or dispatch cursor-agent worker from orchestrated fan-out without explicit user approval — these are opt-in escape hatches documented in references/cursor-tools.md, not this packet's default dispatch behavior.
- Trust Cursor output blindly for security-sensitive code, send sensitive data (API keys, passwords, credentials) in prompts, or hammer the CLI with rapid sequential calls.
- Use Cursor for tasks where context is already loaded — direct action by the calling AI is faster.
- Assume Cursor output is correct without verification — cross-reference codebase and project standards.
- Build or maintain a packet-local Cursor execution adapter; the deep-loop runtime is the execution authority.
- Treat a
0 exit code as proof of a successful, authenticated dispatch — always inspect output text.
- Do not dispatch a
--model value outside the enforced 29-id allowlist (§3 Model Selection), including auto.
Do not silently substitute the closest-sounding allowed model instead of asking the user.
The runtime layer enforces this through CURSOR_SUPPORTED_MODELS/isCursorModelAllowed in executor-config.ts.
A hard-rejecting check also runs in fanout-run.cjs's buildCursorLineageCommand and dispatch-model.cjs's cli-cursor case.
This rule states the same constraint for advisory/manual dispatches the runtime layer cannot see.
⚠️ ESCALATE IF
- Cursor CLI is not installed and user has not acknowledged (provide
curl https://cursor.com/install -fsS | bash).
cursor-agent about reports "Not logged in" and the user has not acknowledged running cursor-agent login.
- Cursor output conflicts with existing code patterns (present both perspectives; user decides).
- Task requests
cursor-agent worker (cloud execution) or native worktree isolation (-w) as part of an orchestrated fan-out (describe the scope-creep risk; get explicit user approval).
Memory Handback Protocol
When you need to preserve session context from a Cursor CLI delegation, run the canonical procedure:
- Extract the
MEMORY_HANDBACK section.
- Build structured JSON and scrub secrets.
- Invoke
generate-context.js via --stdin/--json/temp-file.
The continuity writer is the last step. Nothing is handed to an index.
Find the full procedure and caveats in system-spec-kit/references/cli/memory-handback.md.
Use the Cursor-specific Memory Epilogue template in assets/prompt-templates.md.
printf '%s' "$JSON_PAYLOAD" | node .skilled/skills/system-spec-kit/runtime/cli/dist/continuity/generate-context.js --stdin [spec-folder]
5. REFERENCES
Core References
Templates and Assets
Manual Testing
- manual-testing-playbook.md - 19 CU-NNN scenarios across 9 categories; the canonical no-mocking PASS/FAIL/SKIP validation gate for this skill
Shared (cli-* family)
External
Reference Loading Notes
- Load only references needed for current intent;
ROUTER.md is the single routing authority.
cli-reference.md is ALWAYS loaded as baseline.
6. SUCCESS CRITERIA
Task Completion
- Cursor CLI invoked with correct subcommand, flags, model, and approval mode.
- Output captured, validated, and integrated appropriately; no security vulnerabilities introduced.
- Auth failures handled gracefully (text-based detection, never exit-code-based).
- Appropriate execution mode matched to task type (
--mode ask/--mode plan for read-only, default agent for generation).
- Orchestrated execution delegated to the shared deep-loop runtime without a packet-local adapter.
Skill Quality
- All 8 sections present in the template order.
- ROUTER.md section 3 covers all intent signals with UNKNOWN_FALLBACK.
- Reference files provide deep-dive content without duplication.
7. INTEGRATION POINTS
Framework Integration
This skill operates within the behavioral framework defined in AGENTS.md.
Key integrations:
- Gate 2: Skill routing via
skill_advisor.py
- Tool Routing: Per AGENTS.md Section 5 decision tree
- Continuity: Context preserved by
/speckit:save, which writes through generate-context.js
- Execution: Shared deep-loop runtime (
../../system-deep-loop/runtime/scripts/fanout-run.cjs)
Tool roles: Bash dispatches the CLI; Read/Glob/Grep validate output.
8. REFERENCES AND RELATED RESOURCES
The router discovers reference, asset, and script docs dynamically (Section 5 is the authored index). Start with the ALWAYS-loaded references/cli-reference.md and assets/prompt-quality-card.md, then load task-specific resources per Smart Routing.
Related skills: cli-codex for OpenAI-backed delegation, cli-claude-code for extended reasoning, cli-opencode for full OpenCode runtime dispatch, sk-code for code-quality contracts, mcp-code-mode for external MCP work, and system-spec-kit for packet handback.
1---2name: cli-cursor3description: "Cursor CLI executor for cursor-agent coding, plan/ask read-only modes and worktree-isolated cloud worker dispatch."4allowed-tools: [Bash, Read, Glob, Grep]5version: 1.5.10.06metadata:7 source: https://skillmd.com/skills/michelkerkmeester/cli-cursor8---910# Cursor CLI Orchestrator - Cross-AI Task Delegation1112> **CRITICAL — SELF-INVOCATION PROHIBITED**13>14> This skill dispatches to the Cursor CLI binary (`cursor-agent`). If the agent currently reading this skill is itself running inside `cursor-agent` (detection signals listed in [`ROUTER.md`](./ROUTER.md)), the skill MUST refuse to load and return the documented error message instead of generating any `cursor-agent` invocation.15>16> A running CLI skill never dispatches itself. The cli-X skills are for **cross-AI delegation only** — never self-invocation.1718Orchestrate Cursor's terminal coding agent (`cursor-agent`) for tasks that benefit from a second AI perspective, Cursor's native model (Composer), read-only plan/ask exploration, or its unique worktree/cloud-worker/plugin surfaces.1920**Core Principle**: Use Cursor for what it does best. Delegate, validate, integrate. The calling AI stays the conductor.2122---2324## 1. WHEN TO USE2526### Activation Triggers2728- **Cross-AI Validation** — code review second perspective, bug detection, an independent implementation attempt.29- **Composer Dispatch** — tasks that specifically want Cursor's own native model (`composer-2.5`/`composer-2.5-fast`), or the Grok (4.5/4.6/4.7) / GLM 5.2 tiers already on the enforced allowlist (see §3 Model Selection).30- **Read-Only Exploration** — `--mode plan` (read-only planning) or `--mode ask` (read-only Q&A) when a task wants Cursor's analysis without any file writes.31- **Isolated Experimentation** — Cursor's native git worktree isolation (`-w`/`--worktree`) for a change the operator wants tried in a disposable checkout, documented in `references/cursor-tools.md` as an opt-in escape hatch, not this packet's default dispatch shape.32- **Specialized Generation** — explicit Cursor requests naming Grok (4.5, 4.6 or 4.7) or GLM 5.2 specifically (the only non-Composer models on the enforced allowlist).3334### When NOT to Use3536- **You ARE Cursor already.** If your runtime is `cursor-agent` (detection signal: `CURSOR_AGENT=1` set, `CURSOR_CONVERSATION_ID` set, `cursor-agent` in process ancestry, or an active-session probe under `~/.cursor/`), this skill refuses to load. Self-invocation creates a circular dispatch loop and burns tokens for no value.37- Simple, quick tasks where CLI overhead is not worth it, or tasks needing an immediate response (auth/network round-trips may delay).38- Context already loaded and understood by the current agent.39- Interactive refinement requiring the full-screen TUI (use `cursor-agent` directly instead).40- Tasks where Cursor CLI is not installed, or the account is not authenticated (`cursor-agent about` reports "Not logged in").4142---4344## 2. SMART ROUTING4546The hub's `cli-cursor` mode signal routes a Cursor CLI dispatch here when a request names `cursor-agent`, Composer, a Cursor plan or ask exploration, or Cursor's worktree and cloud-worker surfaces.4748`references/cli-reference.md` and `assets/prompt-quality-card.md` load on every invocation; the hub `ROUTER.md` names the mode's first leaves.4950Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.5152---5354## 3. HOW IT WORKS5556### Prerequisites5758- Install with `curl https://cursor.com/install -fsS | bash` (Windows: `irm 'https://cursor.com/install?win32=true' | iex`).59- Authenticate `cli-cursor` through **Cursor account OAuth**. Run `cursor-agent login` and complete the browser flow.60- `NO_OPEN_BROWSER` disables browser opening for headless hosts.61- Use `CURSOR_API_KEY` or `--api-key` for headless/CI auth.62- Full install, auth, flag, hook, and unique-surface tables are in the ALWAYS-loaded [cli-reference.md](./references/cli-reference.md).63 This section keeps only the routing decisions and dispatch-critical gotchas.6465### Execution Ownership6667This packet owns:68- user-facing routing,69- the `command -v cursor-agent` availability probe,70- prompt construction, and71- the self-invocation guard.7273Research and review lineages delegate process construction and execution to the already-shipped deep-loop runtime at `../../system-deep-loop/runtime/scripts/fanout-run.cjs`, using executor kind `cli-cursor`.74That runner accepts only the `research` and `review` loop types.75For a single build or doc dispatch, use the child dispatch envelope in [providers-and-models.md](./references/providers-and-models.md) §5.7677The runtime is the single Cursor execution adapter. Do not add a packet-local wrapper, command builder, or spawn path. Direct `cursor-agent -p` snippets below are operator reference and manual-testing examples; research and review lineages use the shared runtime, and a one-shot dispatch uses the child envelope.7879### Provider Auth Pre-Flight8081**MANDATORY before any first dispatch in a session.** `cursor-agent -p` without a valid session exits `0` even on an auth failure — the exit code is never a reliable availability signal. Run this check once per session, cache the result, and re-run it only if a dispatch's output text (not its exit code) shows an authentication error.8283```bash84# One-shot pre-flight: capture account auth status for routing85CURSOR_ABOUT=$(cursor-agent about 2>&1)86echo "$CURSOR_ABOUT" | grep -qi "not logged in" && CURSOR_AUTH_OK=0 || CURSOR_AUTH_OK=187```8889**Decision tree** (apply in order — first match wins):9091| State | CURSOR_AUTH_OK | Action |92|-------|-----------------|--------|93| Authenticated | 1 | Proceed with `cursor-agent -p "<prompt>" --output-format text --model composer-2.5 --auto-review --sandbox enabled` |94| Not logged in | 0 | **ASK user** to run `cursor-agent login` — surface the command, do NOT dispatch. Never substitute an unrelated CLI. |9596**User prompt template — not logged in:**9798```99Cursor CLI is not authenticated on this machine. cli-cursor uses Cursor account OAuth100(or CURSOR_API_KEY for headless auth). Run `cursor-agent login`101(browser flow), then confirm when login finishes — the skill will retry the original dispatch.102```103104**Error-recovery contract.** If a dispatch's output text shows an auth error after pre-flight passed (session expired or revoked), invalidate the cache, re-run the pre-flight, and re-check before retrying. Never substitute a model the user didn't approve.105106### Model Selection — Enforced Allowlist107108The cli-cursor dispatch is scoped to exactly 29 ids.109Never dispatch a model outside the allowlist, including `auto`.110Never substitute the closest-sounding allowed model without telling the user.111Default to `composer-2.5`.112Choose a Gemini 3.8 Flash High / GLM 5.2 / GPT-5.6 Luna Max / Grok (4.5, 4.6 or 4.7) tier only when the task or user explicitly names that family.113Cursor has no `--reasoning-effort` flag and rejects parameterized model brackets outright.114Select effort tiers through exact enumerated ids.115116The enforced allowlist (29 ids) and per-task rationale table are inline in [references/cli-reference.md](./references/cli-reference.md) §5 and [references/providers-and-models.md](./references/providers-and-models.md) §2.117The runtime layer enforces it through `CURSOR_SUPPORTED_MODELS` in `executor-config.ts`.118`fanout-run.cjs` and `dispatch-model.cjs` check it before constructing any command. This skill enforces it too.119If a task needs a model outside the allowlist, escalate to the user rather than fabricating a substitute or falling back to `auto`.120121### Default Invocation (Skill Default)122123**Default model + approval**: `composer-2.5` (Cursor's own native model) · `auto-review` approval (Smart Auto). `auto` (Cursor's own router) is NOT used — it can silently resolve to a model outside the enforced allowlist above, which defeats the point of enforcing one.124125> **Fan-out fallback:** a deep-loop lineage that pins no model runs **Composer**. The family is named here on purpose, without a version or an effort tier, so this line does not go stale when the family ships a point release; the runner resolves the current id. A drift test keeps the two in the same family.126127```bash128cursor-agent -p "<prompt>" \129 --output-format text \130 --model composer-2.5 \131 --auto-review \132 --sandbox enabled133```134135**User override** (honor explicit user phrasing verbatim, but ONLY within the enforced allowlist — see Model Selection above):136137| User says | Resolve to |138|-----------|------------|139| (nothing specified) | `--model composer-2.5 --auto-review --sandbox enabled` |140| "Use Composer" | `--model composer-2.5 --auto-review --sandbox enabled` |141| "Use Composer fast" | `--model composer-2.5-fast --auto-review --sandbox enabled` |142| "Use Composer max" / "Composer Max Mode" | Composer has no `-max` (1M "Max Mode") tier — only `composer-2.5`/`composer-2.5-fast`. Tell the user; do not substitute another model's `-max`. |143| "Use Grok" / "Grok high" | `--model cursor-grok-4.6-high --auto-review --sandbox enabled` |144| "Use Grok 4.7" / "Grok 4.7 high" | `--model grok-4.7-high --auto-review --sandbox enabled` |145| "Use GLM" / "GLM max" | `--model glm-5.2-max --auto-review --sandbox enabled` |146| "Just plan it, don't write anything" | `--model composer-2.5 --mode plan` (read-only; approval flags do not apply in plan mode) |147| "Full auto, run everything" | `--model composer-2.5 --force --sandbox disabled` |148| Any model NOT in the allowlist (e.g. "GPT-5.2 high", "use auto") | **Refuse the model, do not substitute silently.** Tell the user this dispatch is scoped to the allowlist above and ask which allowed model to use instead. |149150Honor whichever dimensions the user names (approval level, mode). Model stays on `composer-2.5` unless the user explicitly names a different ALLOWED model.151152### Cursor Agent Delegation153154The calling AI is the conductor.155Cursor's own skill system at `~/.cursor/skills-cursor/` confirms live that Cursor supports subagents natively.156Its skills include:157- `automate`, `babysit`, `canvas`, `create-hook`, `create-rule`, `create-skill`, `create-subagent`, `loop`, `migrate-to-skills`, `sdk`, `shell`, `split-to-prs`, `statusline`, `update-cli-config`, and `update-cursor-settings`.158159These are Cursor-editor-side conventions, not a `-p <profile>` flag like Codex's.160Find the full delegation contract and the `--mode plan`/`--mode ask`/default-agent execution-mode roster in [agent-delegation.md](./references/agent-delegation.md).161162| Task Type | Execution mode |163|-----------|-----------------|164| Code review / bug detection | default agent, `--sandbox enabled` |165| Read-only exploration / architecture questions | `--mode ask` |166| Multi-step planning without writes | `--mode plan` |167| Code generation / file edits | default agent, `--auto-review` or `--force` |168169#### Custom Subagents (CORRECTION -- earlier claim was wrong)170171An earlier pass recorded that "`cursor-agent --help` has no custom-agent-loading concept." **That was wrong**, and the error is instructive: agent profiles are discovered by *file convention*, never by a CLI flag, so grepping `--help` for a flag proves nothing about whether the concept exists.172173Cursor CLI loads custom subagents from two places, confirmed live:174175| Source | Scope | Status here |176|--------|-------|-------------|177| `.cursor/agents/*.md` | project | This repo mirrors all 11 roster agents here |178| `.claude/agents/*.md` | project (Claude-format auto-import) | Already worked before any mirror existed |179180Cursor's own bundled `create-subagent` skill documents the format:181- Both `name` and `description` frontmatter fields are required.182- The Markdown body is the system prompt.183184A live `cursor-agent --force -p` roster probe lists all 11 repo agents alongside Cursor's own built-ins:185`ai-council`, `code`, `context`, `debug`, `deep-research`, `deep-review`, `design`, `markdown`, `orchestrate`, `prompt-improver`, and `review`.186The probe found no duplicate entries when both sources define the same name.187188Each `.cursor/agents/<name>.md` is a **symlink** to the canonical `.claude/agents/<name>.md`.189This matches the discovery-mirror precedent already used for `.claude/hooks/` and `.codex/hooks/`.190There is one source of truth, so a mirror can never drift from the agent it mirrors.191192Note: `~/.cursor/agents/` (user-level) is documented by Cursor but a live probe found the CLI did **not** load a profile placed there; only the project-level paths above are verified working. Dispatch remains subject to this repo's own `preToolUse` spec-gate, which is correct behavior.193194### Repository Rules, Hook Delivery, and Parity Boundaries195196Cursor CLI reads project `.cursor/rules/*.md`, root `AGENTS.md`, root `CLAUDE.md`, and legacy `.cursorrules` automatically. This repo now uses `.cursor/rules/skill-routing.md` as a compact, always-on pointer to the relevant top-level `.skilled/skills/*/SKILL.md` packets. It is static session context, not a replacement for dynamic per-turn classification.197198The `beforeSubmitPrompt` adapter is designed to deliver a dynamic skill-advisor-equivalent brief.199Delivery is confirmed dormant under the installed Cursor CLI build.200Its source marks the status as registered but unconfirmed and records the shared-advisor delegation in [`user-prompt-submit.ts`](../../system-spec-kit/runtime/hooks/cursor/user-prompt-submit.ts#L5-L14) and [`user-prompt-submit.ts`](../../system-spec-kit/runtime/hooks/cursor/user-prompt-submit.ts#L45-L51).201A live marker re-probe against `cursor-agent 2026.07.23-e383d2b` confirmed that `beforeSubmitPrompt` did not fire.202The static rules file therefore complements a missing dynamic brief.203It does not claim to provide per-turn advisor output.204The hook registration and adapter remain unchanged.205206`cursor-agent --help` has no native command-roster listing subcommand. This repository still exposes a `.cursor/commands/` parity surface: the synchronizer derives it from eligible `.skilled/commands/` files, excludes `goal-opencode.md`, and adds the runtime-native `goal-cursor.md`; validate membership with `command-scope.cjs` and validate behavior with a real slash-command invocation.207208### Dispatch-Critical Gotchas209210The full flag glossary, hook contract, shared-config surface, and troubleshooting table are in the ALWAYS-loaded [cli-reference.md](./references/cli-reference.md). Gotchas that silently break a dispatch and must be honored at routing time:211212- **The exit code is never an availability signal.** `cursor-agent -p` without auth exits `0` and prints an error to stdout/stderr instead. Every guard and pre-flight in this packet checks output text, never exit code.213- **The canonical binary is `cursor-agent`, never the bare `agent` alias.** `agent` is a symlink to the same binary; using it in a process-ancestry match risks colliding with an unrelated `agent` command.214- **Cursor shares its entire config surface with the Cursor editor** (`.cursor/`/`~/.cursor/`: `mcp.json`, `hooks.json`, `rules/`, `cli-config.json`). A dispatched `cursor-agent` silently inherits the operator's shared hooks/MCP/rules unless a workspace/config-isolation flag is used — see [shared-editor-config.md](./references/shared-editor-config.md).215- **No `model[effort=...]` bracket support.** Unlike some sibling CLIs' parameterized model syntax, `cursor-agent --model 'cursor-grok-4.6[effort=high]'` is rejected outright ("Cannot use this model") — effort tiers must be selected via an exact enumerated id (`cursor-grok-4.6-high`), never a bracket.216- **`--auto-review`/`--force` are the write-capable escalation, not `--sandbox`.** `--sandbox enabled|disabled` toggles the OS-level sandbox; the approval decision (whether unattended actions run without a human) is `--auto-review` (Smart Auto) or `--force`/`--yolo` (Run Everything) — omitting both leaves Cursor's own prompt-and-block default in place, which cannot proceed unattended.217- **Project-scoped MCP servers show `not loaded (needs approval)`** until trusted. For a non-interactive dispatch that needs MCP tools, add `--approve-mcps` to the `cursor-agent -p` command (auto-approves configured MCP servers for that run); for a persistent operator grant use `cursor-agent mcp enable <server>` (a trust mutation the automation itself must never run).218219---220221## 4. RULES222223### ✅ ALWAYS2242251. Verify Cursor CLI is installed before first invocation (`command -v cursor-agent`).2262. Delegate research and review lineages to `../../system-deep-loop/runtime/scripts/fanout-run.cjs` with executor kind `cli-cursor`. It rejects every other loop type, so a single build or doc dispatch uses the child dispatch envelope in [providers-and-models.md](./references/providers-and-models.md) §5. Never build a second adapter in this packet.2273. Use `--mode plan` or `--mode ask` for read-only exploration/analysis/research; use the default agent mode with `--auto-review` or `--force` for code generation/file modification.2284. Validate Cursor-generated code (XSS, injection, eval, syntax checks via `node --check`, `tsc --noEmit`, etc.) before applying.2295. Capture stderr (`2>&1`) so errors surface; check output TEXT for auth/availability failures, never the exit code (always `0`).2306. **Redirect cursor-agent stdin from `/dev/null` on EVERY non-interactive dispatch** — not only inside a `while read` loop, which is the condition this rule used to name and the reason it was skipped, mirroring the family-wide convention: `cursor-agent -p "$PROMPT" > "$LOG" 2>&1 </dev/null &`. Live-verified: a real `cursor-agent -p ... </dev/null` dispatch completes normally with no hang.2317. **Specify model and approval mode explicitly** — never rely on caller environment. Default: `--model composer-2.5 --auto-review --sandbox enabled`. Honor user overrides verbatim, but ONLY within the enforced allowlist (§3 Model Selection) — never `auto`, never a model outside the 29 allowed ids.2328. Route to `--mode plan`/`--mode ask`/default agent per the task type (see Section 3 routing table).2339. **Pass the spec folder to the delegated agent** in the prompt: if the calling AI has an active Gate-3 spec folder, include `Spec folder: <path> (pre-approved, skip Gate 3)`. If none, ASK the user before delegating — the delegated agent cannot answer Gate 3 in `--force`/non-interactive mode.23410. **Prompt construction & model-craft (cli-* family precedence).** Compose every dispatch prompt via the 2-tier rule canonical in `../../sk-prompt/assets/cli-prompt-quality-card.md`:235 1. **Fast path (default).** Build from the local `assets/prompt-quality-card.md`, which delegates the framework table + CLEAR check to the canonical card.236 2. **Deep path (escalation).** Dispatch `@prompt-improver` via the Task tool (never load full `sk-prompt` inline) when any canonical **Tier 2** trigger applies — the trigger list lives in `../../sk-prompt/assets/cli-prompt-quality-card.md` under "Tier 2 — Deep path"; do not re-enumerate it here.23711. **Never inject user-level voice/personalization content into AI-orchestrated Cursor delegations.** Cursor CLI reads rules from `.cursor/rules`, `AGENTS.md`, `CLAUDE.md`, and legacy `.cursorrules` automatically. When an AI delegates via `cursor-agent -p`, the calling AI's own voice rules govern the response — keep delegations focused on task/model/approval/(spec-folder pre-approval).23812. **Code Standards Loading (surface-aware contract)** — When dispatching for code review or code generation, instruct the dispatched session to:239 1. Load `sk-code`.240 2. Let `sk-code` emit a surface tag matching the detected stack from markers and target files.241 3. Load the selected surface resources and run its verification commands.242 4. Add `code-review` only for formal findings-first review output.243244 Fallback: if the surface cannot be determined confidently, ask for the runtime surface and verification command set.245 NEVER hardcode obsolete sibling code skills in dispatch prompts.24613. **Design Standards Loading (measured-reference contract)** — When dispatching for design or UI work, instruct the dispatched session to:247 1. Load `sk-design-md-generator`.248 2. Extract a measured Style Reference DESIGN.md from the live source before building UI. Include named color tokens, type scale, components, and Quick-Start CSS/Tailwind.249 3. Build against those measured tokens and run the extraction's validate step to confirm hex/section fidelity.250251 Fallback: if there is no live source to measure, ask for the reference URL or the exact tokens to build against.252 NEVER treat `mcp-figma` or `sk-design-md-generator` as a taste, visual-direction, or critique authority.253 The extraction measures real CSS; it does not judge design.25414. **Pass the design reference manifest to the dispatched session** — when dispatching design or UI work, inline a `DESIGN_DISPATCH_MANIFEST v1` block in the prompt.255 The child cannot resolve skill paths, so the manifest travels in the payload, not by reference.256 Include `styleReferenceExtracted` true, the live `source` that was measured, the measured design tokens / type scale / components the child must build against, `loadedFiles`, and `proofDemandBack`.257 If the manifest cannot be assembled because no Style Reference was extracted or no live source can be measured, ASK before launching the child rather than starting a silent design dispatch.258 The child returns the demanded proof, and the parent reconciles it on the return path.25915. **Single-dispatch discipline (operator-gated, session-scoped).**260 - By default, launch ONE cli-* dispatch at a time across the cli-* family.261 - Wait for the dispatched agent's work to return and verify that outputs exist.262 Then SIGKILL only the dispatch THIS skill started. Capture its PID at launch with `cursor-agent -p ... & CURSOR_PID=$!`.263 Kill that PID directly and its own orphan children with `kill -9 "$CURSOR_PID" 2>/dev/null; pkill -9 -P "$CURSOR_PID" 2>/dev/null`.264 - **Never use a blanket `pkill -9 -f "cursor-agent"` pattern.** It matches and kills EVERY running `cursor-agent` process on the machine, including the operator's unrelated Cursor sessions and the operator's own Cursor editor, since the CLI shares the binary family.265 - Launch the next dispatch, this skill or a sibling, only after the prior one is dead and RSS has dropped.266 - **Within a deep-flow session** (deep-review / deep-research), the operator authorizes the whole multi-iteration session at the start.267 Iterations chain back-to-back with kill-between as the safety mechanism, NOT a per-iteration confirmation prompt.268 - **Exception (cross-skill parallel):** when the operator explicitly authorizes N parallel dispatches, run N concurrently.269 Still SIGKILL each by its own captured PID as its work returns.27016. **Set `AI_SESSION_CHILD=1` in the dispatched child's env and state the exemption in the prompt.**271 The variable makes the waiver true, but it does not make it observable.272 The reader being waived is a model, and a model cannot see an environment variable.273 A child given only the variable still stops to ask the documentation-scope question and writes nothing, at exit code zero.274 Copy the preamble from [`shared/references/child-dispatch-preamble.md`](../shared/references/child-dispatch-preamble.md) to the top of every non-interactive prompt.275 A session may be launched through the per-session worktree wrapper (`.skilled/bin/worktree-session.sh`).276 A dispatched `cursor-agent -p` is an orchestrated sub-session, not a new top-level session.277 It must SHARE the parent's worktree rather than allocate its own.278 This is distinct from Cursor's own native `-w` worktree flag, which this packet's default dispatch never passes.279 Pattern: `AI_SESSION_CHILD=1 cursor-agent -p ... </dev/null`.280 This is harmless when the wrapper is not in use.281 See `.skilled/bin/README.md` → "Worktree session isolation".28228317. **Agent-persona injection (attach identity, not just the task).**284 Every dispatch composes `{resolved agent persona + task prompt}`, never a bare task.285 Resolve the persona from the ACTIVE runtime's agent directory per AGENTS.md §9:286 `.cursor/agents/<name>.md`, `.claude/agents/<name>.md`, `.skilled/agents/<name>.md`, and other runtime paths.287 Never hardcode one runtime.288 Map each subtask to the RIGHT agent, not one default:289 `code`→code, `review`→review, `design`→design, research→`deep-research`, and docs→`markdown`.290 **Cursor has a native file-convention subagent surface.**291 `.cursor/agents/*.md` and `.claude/agents/*.md` mirror all 11 canonical agents.292 Dispatch by naming the resolved subagent to satisfy the rule.293 On a bare `cursor-agent -p` that names no subagent, **INLINE** the persona block into the payload.294 Use the same in-payload pattern as the `DESIGN_DISPATCH_MANIFEST` (Rule 14), because the child cannot resolve agent paths by reference.295 A persona-less dispatch runs the leaf as a generic assistant and silently drops the agent's tool-scope, verification gates, and output contract.296 The canonical contract is `../../sk-prompt/assets/cli-prompt-quality-card.md` "Persona Injection".297 The native precedent is `orchestrate.md` "Agent Loading Protocol".298 Declare rare exceptions at the dispatch site: a native surface used, a focused summary for a small-context model, or a pure-mechanical command.299300### ⛔ NEVER3013021. Pass `-w`/`--worktree` or dispatch `cursor-agent worker` from orchestrated fan-out without explicit user approval — these are opt-in escape hatches documented in `references/cursor-tools.md`, not this packet's default dispatch behavior.3032. Trust Cursor output blindly for security-sensitive code, send sensitive data (API keys, passwords, credentials) in prompts, or hammer the CLI with rapid sequential calls.3043. Use Cursor for tasks where context is already loaded — direct action by the calling AI is faster.3054. Assume Cursor output is correct without verification — cross-reference codebase and project standards.3065. Build or maintain a packet-local Cursor execution adapter; the deep-loop runtime is the execution authority.3076. Treat a `0` exit code as proof of a successful, authenticated dispatch — always inspect output text.3087. Do not dispatch a `--model` value outside the enforced 29-id allowlist (§3 Model Selection), including `auto`.309 Do not silently substitute the closest-sounding allowed model instead of asking the user.310 The runtime layer enforces this through `CURSOR_SUPPORTED_MODELS`/`isCursorModelAllowed` in `executor-config.ts`.311 A hard-rejecting check also runs in `fanout-run.cjs`'s `buildCursorLineageCommand` and `dispatch-model.cjs`'s cli-cursor case.312 This rule states the same constraint for advisory/manual dispatches the runtime layer cannot see.313314### ⚠️ ESCALATE IF3153161. Cursor CLI is not installed and user has not acknowledged (provide `curl https://cursor.com/install -fsS | bash`).3172. `cursor-agent about` reports "Not logged in" and the user has not acknowledged running `cursor-agent login`.3183. Cursor output conflicts with existing code patterns (present both perspectives; user decides).3194. Task requests `cursor-agent worker` (cloud execution) or native worktree isolation (`-w`) as part of an orchestrated fan-out (describe the scope-creep risk; get explicit user approval).320321### Memory Handback Protocol322323When you need to preserve session context from a Cursor CLI delegation, run the canonical procedure:324- Extract the `MEMORY_HANDBACK` section.325- Build structured JSON and scrub secrets.326- Invoke `generate-context.js` via `--stdin`/`--json`/temp-file.327328The continuity writer is the last step. Nothing is handed to an index.329Find the full procedure and caveats in [ `system-spec-kit/references/cli/memory-handback.md`](../../system-spec-kit/references/cli/memory-handback.md).330Use the Cursor-specific Memory Epilogue template in [assets/prompt-templates.md](./assets/prompt-templates.md).331332```bash333printf '%s' "$JSON_PAYLOAD" | node .skilled/skills/system-spec-kit/runtime/cli/dist/continuity/generate-context.js --stdin [spec-folder]334```335336---337338## 5. REFERENCES339340### Core References341342- [cli-reference.md](./references/cli-reference.md) - Complete CLI subcommands, flags, auth, and troubleshooting reference343- [integration-patterns.md](./references/integration-patterns.md) - Cross-AI orchestration patterns and workflows344- [cursor-tools.md](./references/cursor-tools.md) - Cursor-unique surfaces: native worktree (`-w`), cloud `worker`, plugin marketplace, MCP345- [hook-contract.md](./references/hook-contract.md) - Cursor's shared hooks.json contract (events, schema, discovery, envelope)346- [shared-editor-config.md](./references/shared-editor-config.md) - The shared `.cursor/`/`~/.cursor/` editor-config surface and dispatch-isolation implications347- [agent-delegation.md](./references/agent-delegation.md) - Cursor execution-mode roster (default/plan/ask) and delegation patterns348- [providers-and-models.md](./references/providers-and-models.md) - Single-source catalog of the Cursor provider and the enforced 29-id model allowlist349350### Templates and Assets351352- [prompt-templates.md](./assets/prompt-templates.md) - Copy-paste ready prompt templates for common tasks353- [prompt-quality-card.md](./assets/prompt-quality-card.md) - Fast-path prompt framework + CLEAR check (ALWAYS loaded)354355### Manual Testing356357- [manual-testing-playbook.md](./manual-testing-playbook/manual-testing-playbook.md) - 19 CU-NNN scenarios across 9 categories; the canonical no-mocking PASS/FAIL/SKIP validation gate for this skill358359### Shared (cli-* family)360361- [shared-smart-router.md](../../system-spec-kit/references/cli/shared-smart-router.md) - Helper-function bodies for the smart router.362- [memory-handback.md](../../system-spec-kit/references/cli/memory-handback.md) - Canonical 7-step Memory Handback procedure.363364### External365366- [Cursor CLI docs](https://cursor.com/docs/cli/overview) - Official documentation367- [Cursor account](https://cursor.com) - Cursor account (auth for cli-cursor)368369### Reference Loading Notes370371- Load only references needed for current intent; [`ROUTER.md`](./ROUTER.md) is the single routing authority.372- `cli-reference.md` is ALWAYS loaded as baseline.373374---375376## 6. SUCCESS CRITERIA377378### Task Completion379380- Cursor CLI invoked with correct subcommand, flags, model, and approval mode.381- Output captured, validated, and integrated appropriately; no security vulnerabilities introduced.382- Auth failures handled gracefully (text-based detection, never exit-code-based).383- Appropriate execution mode matched to task type (`--mode ask`/`--mode plan` for read-only, default agent for generation).384- Orchestrated execution delegated to the shared deep-loop runtime without a packet-local adapter.385386### Skill Quality387388- All 8 sections present in the template order.389- [ROUTER.md section 3](./ROUTER.md#3-machine-router) covers all intent signals with UNKNOWN_FALLBACK.390- Reference files provide deep-dive content without duplication.391392---393394## 7. INTEGRATION POINTS395396### Framework Integration397398This skill operates within the behavioral framework defined in [AGENTS.md](../../../../AGENTS.md).399400Key integrations:401- **Gate 2**: Skill routing via `skill_advisor.py`402- **Tool Routing**: Per AGENTS.md Section 5 decision tree403- **Continuity**: Context preserved by `/speckit:save`, which writes through `generate-context.js`404- **Execution**: Shared deep-loop runtime (`../../system-deep-loop/runtime/scripts/fanout-run.cjs`)405406**Tool roles**: Bash dispatches the CLI; Read/Glob/Grep validate output.407408---409410## 8. REFERENCES AND RELATED RESOURCES411412The router discovers reference, asset, and script docs dynamically (Section 5 is the authored index). Start with the ALWAYS-loaded `references/cli-reference.md` and `assets/prompt-quality-card.md`, then load task-specific resources per Smart Routing.413414Related skills: `cli-codex` for OpenAI-backed delegation, `cli-claude-code` for extended reasoning, `cli-opencode` for full OpenCode runtime dispatch, `sk-code` for code-quality contracts, `mcp-code-mode` for external MCP work, and `system-spec-kit` for packet handback.