modes

modes

Manage persistent response modes. Modes are binding contracts that override defaults; multiple may be active at once (with the documented exceptions); each persists across turns until explicitly exited.

Authority and ownership

Modes are user-settable only. Never enter, exit, or toggle a mode on Claude's own initiative. Only act when the user explicitly issues an /enterMode …, /exitMode …, /listModes, or /clearModes directive — or asks in natural language to enter, exit, list, clear, or check a mode. Do not echo directive syntax in responses except when quoting the user.

The single exception to "Claude doesn't toggle modes" is the plan ↔ agent mutex: entering one when the other is active exits the other automatically. This is still user-initiated — the user typed the directive — and matches Cursor's behavior.

State file

Active modes live in active_modes.md inside Claude's auto-memory directory (the path is in the system prompt's auto-memory section — use that absolute path; never hard-code a UUID). The file is the single source of truth.

Format:

# Active modes

- plan: ./
- exclude: *.t.ts, *.log

An absent or empty file means no modes are active.

A pointer line must exist in MEMORY.md so the file is loaded every turn:

- [Active modes](active_modes.md) — currently active mode directives; honor these every turn

If the pointer is missing when handling any directive, add it.

Recognized directives

Directive	Effect
/enterMode plan [dir]	Enter plan mode (exits agent if active); plan files go in [dir], default ./
/exitMode plan	Exit plan mode
/enterMode agent	Enter agent mode (exits plan if active)
/exitMode agent	Exit agent mode
/enterMode one-word	Enter one-word mode
/exitMode one-word	Exit one-word mode
/enterMode sbs	Enter step-by-step mode
/exitMode sbs	Exit step-by-step mode
/enterMode exclude <patterns>	Add comma-separated patterns to the "exclude" set (block-list for writes)
/exitMode exclude	Clear the "exclude" set entirely
/enterMode include <patterns>	Add comma-separated patterns to the "include" set (allow-list for writes)
/exitMode include	Clear the "include" set entirely
/listModes	Echo the currently active modes (no state change)
/clearModes	Exit every active mode

The directive verbs are case-insensitive — /entermode, /EnterMode, and /enter-mode are all recognized as equivalent to /enterMode. Mode names are lowercase (with kebab for multi-word). Treat natural-language phrasings as equivalent to the matching directive:

• "enter plan mode in src/", "turn on plan mode" → /enterMode plan src/
• "turn off agent", "exit agent mode", "drop agent" → /exitMode agent
• "what modes are on?", "show active modes" → /listModes
• "clear all modes", "reset modes" → /clearModes
• "show me the modes", "modes cheat sheet", "what modes are available?" → print the Help output (no state change; see below)

/listModes echoes what's active. The cheat sheet (natural-language only) lists what's available. Don't conflate them.

Echo contract

Every directive that mutates state — /enterMode, /exitMode, /clearModes — emits a structured echo so the user always sees the post-change state. /listModes emits the active-modes echo only. The echo is the entire response to a mode directive — no preamble, no commentary, no postscript.

/enterMode <name> [param]

If the mode is not currently active:

mode <name> is now active.
mode <displaced> is now inactive.
mode <name> : <one-line blurb>
active modes :
 • <mode>
 • <mode>

The "is now inactive" line appears only when a mutex sibling was displaced (currently: plan ↔ agent). Omit the line entirely when there's no displacement.

If the mode is already active:

mode <name> is already active.
mode <name> : <one-line blurb>
active modes :
 • <mode>
 • <mode>

/exitMode <name>

If the mode is currently active:

mode <name> is now inactive.
active modes :
 • <mode>
 • <mode>

Or active modes : none if no modes remain.

If the mode is not currently active:

mode <name> is not active.
active modes :
 • <mode>
 • <mode>

Or active modes : none if no modes remain.

/listModes

active modes :
 • <mode>
 • <mode>

Or active modes : none.

/clearModes

all modes cleared.
active modes : none

Echo formatting rules

• The active-modes list is always alphabetized by mode name.
• One bullet per line: a single leading space, then •, then a space, then the mode.
• Compound modes (exclude, include, plan) render with their param: exclude: *.log, *.tmp or plan: ./src.
• none is rendered inline on the same line as active modes : — no bullet list when empty.
• No preamble, no commentary, no postscript around the echo. The echo is the response.

Mode blurbs

The one-line blurb emitted with each /enterMode echo:

Mode	Blurb
plan	"plan-only writes (default ./); produce a *.plan.md then exit to execute"
agent	"full agency; the default working stance"
one-word	"responses are a single word"
sbs	"step-by-step; one step then wait for 'done'"
exclude	"block writes matching listed patterns"
include	"only allow writes matching listed patterns"

Handling a directive

Cheat-sheet queries are special — skip the numbered steps below entirely. Don't read or write active_modes.md. Instead, reply with the verbatim text from the Help output section. Treat natural-language equivalents ("show me the modes", "what modes are available?", "modes cheat sheet") the same way. Distinguish from /listModes, which echoes the active modes, not the available ones.

If no auto-memory directory is available in the current surface (the system prompt's auto-memory section is missing — the case in Chat, and likely in Claude Code), treat step 1 as "no active modes" and skip steps 3 and 4. The directive still takes effect for the remainder of the conversation via conversation context; cross-session persistence is simply unavailable. Acknowledge plainly via the standard echo — don't surface the missing-persistence detail to the user.

1. Read active_modes.md if it exists; otherwise treat as empty.
2. Parse the directive:
   • /enterMode <name> [param] → add the mode. If the mode is already in the set, emit the "already active" echo.
   • /exitMode <name> → remove the mode. If the mode is not in the set, emit the "not active" echo.
   • /listModes → no state change; emit the active-modes echo only.
   • /clearModes → empty the set; emit the "all modes cleared" echo.
   • For plan: store/replace the directory param; if no param given, default ./.
   • For exclude / include: append the comma-separated patterns to the existing set (idempotent — duplicate patterns deduped).
   • plan and agent are mutually exclusive — entering one exits the other and the displacement is named in the echo.
3. Write the updated active_modes.md.
4. If MEMORY.md lacks the pointer line, add it.
5. If the directive entered plan and the chosen directory isn't currently accessible, request access (Cowork: call the directory-request tool with that path; Claude Code: tell the user to run /add-dir <path>).
6. Emit the structured echo (see Echo contract). No other text in the response.

When tools are denied

This skill declares allowed-tools: Read, Write, Edit in its frontmatter. In Claude Code those are pre-approved while the skill is active; in Cowork the declaration is effectively documentation (the host inherits broader permissions). If a Write or Edit against active_modes.md or MEMORY.md is denied anyway by the user's settings.json, don't retry silently. Instead:

1. Honor the directive in conversation context for the remainder of the session (no persistence).
2. Emit the structured echo as usual — the user still gets the active-modes view.
3. Append one line after the echo: "persistence blocked: Write on active_modes.md denied — mode is active for this conversation only."
4. Suggest the minimum settings change (e.g. add Write for the memory directory) so future sessions persist.

Do not surface this branch unless a tool actually got denied — the happy path stays quiet.

Help output

When the user asks for the cheat sheet (any natural-language phrasing — "show me the modes", "what modes are available?", "modes cheat sheet"), reply with this exact text — preserve the structure, bullets, and order. No paraphrasing, no preamble, no closing remarks:

Modes:
• plan [dir] — plan-only writes in [dir] (default ./); mutex with agent
• agent — full agency; mutex with plan
• one-word — single-word responses
• sbs — step-by-step; one step then wait
• exclude <globs> — block writes matching globs
• include <globs> — only allow writes matching globs

Enter:      /enterMode <name> [param]
Exit:       /exitMode <name>
List:       /listModes
Clear all:  /clearModes

Mode behaviors

These are the effects Claude must enforce while the corresponding mode is active. Multiple modes compose; all active modes apply simultaneously (with the plan ↔ agent mutex noted above).

plan

Plan mode is a working stance: the goal is to produce a precise, well-scoped spec — a .plan.md file — that another agent (Cursor, Claude Code, Claude Desktop) can later execute. Implementation happens after the plan is approved, by exiting plan mode (/exitMode plan or /enterMode agent).

File-write behavior while in plan mode:

• Allowed writes: any file matching **/*.plan.md within the plan directory (the [dir] argument; default ./).
• Blocked writes: everything else. Decline with a plain note ("can't — plan mode; only *.plan.md writes in <dir>").
• Read, Glob, Grep, read-only Bash are unaffected.
• include / exclude still apply on top of plan-mode write rules.

Conversational behavior while in plan mode:

• Ask clarifying questions before drafting. Don't guess at scope.
• Research the codebase (Read, Grep, Glob) to ground the plan in real file paths and code.
• Surface alternatives and trade-offs the user should weigh.
• Don't implement. If asked to implement, remind the user they're in plan mode and ask whether to exit (/enterMode agent or /exitMode plan) before proceeding.

Plan file naming:

Filename: <descriptive-snake-case>.plan.md — no suffix.

If the same name already exists in the plan directory, the user has presumably revised the plan; either overwrite (if continuing the same plan) or pick a more specific name. Don't auto-suffix in plan-mode authoring; suffix-on-collision is plan2cursor's job at import time.

Plan file format (Cursor-compatible):

---
name: <human-readable title>
overview: <1–3 sentence summary of the work>
todos:
  - id: <slug>
    content: "<single-line description of the step>"
    status: pending
  - id: <slug>
    content: "..."
    status: pending
isProject: false
---

# <human-readable title>

## Background

<why this work; what motivates it>

## Approach

<the chosen design in 1–3 paragraphs; reference real files with [name](relative/path) links>

## Files to modify

- [path/to/file.swift](path/to/file.swift) — what changes here
- [path/to/other.ts](path/to/other.ts) — what changes here

## Implementation details

<concrete enough that an executing agent doesn't have to re-derive intent; pseudocode or actual snippets are welcome>

## Edge cases

- <case>: <how to handle>

## What we are NOT doing

- <out-of-scope item>: <why deferred>

## Open questions

- <question> (if any remain)

Status vocabulary: pending, in_progress, completed, cancelled. isProject: false for normal plans. Body sections beyond the frontmatter are author's choice — propose structure that fits the work; the above is a strong default.

Directory handling:

The chosen [dir] is stored in active_modes.md as plan: <dir>. If the directory isn't currently accessible:

• Cowork: call the directory-request tool with the path.
• Claude Code: tell the user to run /add-dir <path>.
• Don't silently fall back to ./ — the user picked a directory deliberately.

agent

Full agency. No plan-mode write filter. Entering agent exits plan if active. Other modes (include, exclude, one-word, sbs) continue to apply.

This is the default working stance, but having it as a named mode lets the user explicitly switch out of plan mode in one step (/enterMode agent) instead of /exitMode plan + adjusting expectations.

one-word

Responses are a single word. Apply literally — no punctuation flourishes or trailing clauses.

sbs (step-by-step)

Perform exactly one step, then stop and wait for the user to say "done" (or equivalent). Do not chain steps. After "done", proceed to the next step. The skill itself is exempt — handling a mode directive is not a step.

exclude

exclude holds a list of gitignore-style glob patterns. Any Write or Edit whose target file matches any pattern is refused. Read, Glob, Grep are unaffected. Decline blocked writes with a plain note naming the matched pattern.

Param format: comma-separated patterns. /enterMode exclude *.log, *.tmp, build/** appends those three to the existing set (duplicates deduped). /exitMode exclude clears the entire set.

include

include holds a list of gitignore-style glob patterns. Any Write or Edit whose target file does not match any pattern is refused. Read, Glob, Grep are unaffected. Decline blocked writes with a plain note that the file isn't in the include set.

Param format: comma-separated patterns. /enterMode include src/**/*.ts, tests/**/*.ts appends those to the existing set. /exitMode include clears the entire set.

Interaction summary

• plan and agent are mutually exclusive.
• include and exclude compose: writable iff (matches include) AND (does not match exclude).
• plan mode's allow-list (**/*.plan.md in plan dir) layers on top of include / exclude.
• Output-style modes (one-word, sbs) compose freely with everything else.

Edge cases

• Re-entering an active mode — emit the "already active" echo (which still includes the blurb and active-modes list). Don't error.
• Exiting an inactive mode — emit the "not active" echo. Don't error.
• Empty pattern args (/enterMode exclude with nothing after) — treat as no-op and ask the user for the intended patterns. Do not write to state.
• Pattern parsing — split on commas, trim whitespace. Patterns themselves may not contain commas.
• MEMORY.md truncation — keep the pointer line short so it survives the index's 200-line cap.
• Cross-session start — when a new conversation begins, read active_modes.md (loaded via MEMORY.md) and honor whatever's there. Do not announce active modes unprompted; the user can issue /listModes if they want to see.
• Plan dir collision with a same-named plan file — ask the user before overwriting.
• Pre-2.0.0 state files — if active_modes.md contains entries like - one word (with space) or - SBS (uppercase), normalize on first read to - one-word and - sbs and rewrite the file. No user-facing notice required.