---
id: "0028"
date: 2026-07-12
status: Accepted
supersedes:
superseded-by:
affected-paths: [plugins/os-shortcuts/]
affected-components: [os-shortcuts, os-context, os-orchestration]
---

# 0028 — os-shortcuts plugin for user-invoked QOL commands, bounded against hook-injection plugins

## Context

The 2026-07-09 AI-workflow audit found ritual instructions the user re-types constantly — the session-close paragraph (commit per repo conventions, sweep affected docs, write a handoff) appeared 20+ times. These need a home in the cc-os plugin family. Injection-style plugins (os-orchestration, the planned os-context) are the wrong vehicle: SessionEnd hooks fire after the model's last turn and cannot inject actionable instructions, Stop hooks fire every turn and are noisy, and session-close is inherently user-timed. cc-os needed a decided boundary for where user-typed shortcut commands live versus automatic context injection.

## Decision

Create a new plugin `os-shortcuts` (plugins/os-shortcuts/) holding user-invoked QOL commands — the 'keybindings' of cc-os. Domain boundary: os-shortcuts = commands the user explicitly types (skills only, never hooks); os-context/os-orchestration = automatic hook-injected context. First resident is `/os-shortcuts:wrap`, encoding the session-close ritual (git review → conventional commits → doc/todo sweep deferring to project CLAUDE.md → Done/In-flight/Next handoff). Future shortcuts (e.g. a possible /readonly) accumulate here rather than spawning per-command plugins.

## Consequences

Easier: repeated ritual prompts collapse to one slash command; new shortcuts have an obvious home; the hooks-vs-commands boundary is explicit, keeping os-context's injection budget separate from on-demand behavior. Harder: one more globally installed plugin to cache-refresh and keep in sync; the wrap ritual's quality now depends on each project's CLAUDE.md documenting its own commit/doc conventions.

## Alternatives rejected

1) SessionEnd/Stop hook automation — rejected: SessionEnd cannot inject model-visible instructions (fires after the last turn) and Stop hooks fire every turn (noise); see vault note reference/claude-code-hook-lifecycle-injection-capability.md. 2) Put /wrap inside an existing plugin (os-status or os-context) — rejected: wrong domains; os-status is deterministic session checks, os-context is automatic injection, and mixing user-typed commands into either blurs the boundary this ADR fixes. 3) Keep re-typing the paragraph / rely on memory files — rejected: the audit shows it leaks (20+ repeats) and memory injection is not reliably surfaced at session close.
