From 46ebfb1b2f9a77d4feea040377c7d832272a3552 Mon Sep 17 00:00:00 2001 From: jared Date: Mon, 13 Jul 2026 08:06:48 -0400 Subject: [PATCH] ADR-030: read-only work uses plan mode; no /readonly shortcut Closes the /readonly backlog card as convention-only: plan mode enforces read-only at the permission layer; a skill cannot activate plan mode and would imply enforcement it doesn't have. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01CLeMz48rvG3s9XpAsDxeho --- ...-plan-mode-no-readonly-shortcut-command.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 docs/adr/0030-read-only-work-uses-claude-code-plan-mode-no-readonly-shortcut-command.md diff --git a/docs/adr/0030-read-only-work-uses-claude-code-plan-mode-no-readonly-shortcut-command.md b/docs/adr/0030-read-only-work-uses-claude-code-plan-mode-no-readonly-shortcut-command.md new file mode 100644 index 0000000..b651cd6 --- /dev/null +++ b/docs/adr/0030-read-only-work-uses-claude-code-plan-mode-no-readonly-shortcut-command.md @@ -0,0 +1,27 @@ +--- +id: "0030" +date: 2026-07-13 +status: Accepted +supersedes: +superseded-by: +affected-paths: [plugins/os-shortcuts/] +affected-components: [os-shortcuts, plan-mode] +--- + +# 0030 — Read-only work uses Claude Code plan mode; no /readonly shortcut command + +## Context + +The 2026-07-09 AI-workflow audit (finding #2) showed the user typed 'read-only, do NOT change anything' near-verbatim 15+ times. A backlog card proposed either documenting a convention or building a /readonly skill in os-shortcuts. Claude Code plan mode already enforces read-only at the permission layer, while a prompt or skill saying 'don't change anything' is only advisory; os-shortcuts has no mechanism to switch the client into plan mode or enforce filesystem permissions, so a /readonly slash command would imply stronger enforcement than it actually has. + +## Decision + +The convention for read-only tasks is to start them in Claude Code plan mode (shift+tab / --permission-mode plan). No /readonly skill is built in os-shortcuts. Per-task read-only expectations are expressed by entering plan mode, not by injected or skill-carried phrasing. + +## Consequences + +Easier: read-only is enforced at the permission layer rather than trusted to prompt compliance; no new skill to maintain or cache-refresh; the os-shortcuts surface stays small. Harder: the user must remember the plan-mode keybinding instead of a memorable slash command; any standing read-only phrasing beyond 'no changes' (reporting expectations, output format) still has to be typed per task or captured elsewhere. + +## Alternatives rejected + +1) Build /os-shortcuts:readonly as a thin skill that instructs the model to behave read-only and states the user's expectations - rejected: skills cannot activate plan mode, so the command would be advisory-only while its name implies enforcement; a false sense of safety is worse than the keybinding. 2) Inject standing read-only rules via os-context session-start prompts - rejected: read-only is a per-task property, not an always-true rule; injecting it globally would contradict sessions that are supposed to write.