From d6f316008d49f2286f170c391158a725d8fed119 Mon Sep 17 00:00:00 2001 From: jared Date: Sun, 12 Jul 2026 18:53:07 -0400 Subject: [PATCH] os-shortcuts: new plugin + /wrap session-close skill (ADR-028) User-invoked QOL commands plugin; domain boundary vs hook-injection plugins recorded in ADR-028. First resident /os-shortcuts:wrap encodes the session-close ritual (commit per repo conventions, doc sweep, handoff) from the 2026-07-09 workflow audit. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01QBAYNm4AmczQaEHfXwai5a --- ...-bounded-against-hook-injection-plugins.md | 27 +++++++++ docs/adr/README.md | 1 + docs/implementation-status.md | 23 +++++++- .../os-shortcuts/.claude-plugin/plugin.json | 5 ++ plugins/os-shortcuts/skills/wrap/SKILL.md | 58 +++++++++++++++++++ 5 files changed, 113 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0028-os-shortcuts-plugin-for-user-invoked-qol-commands-bounded-against-hook-injection-plugins.md create mode 100644 plugins/os-shortcuts/.claude-plugin/plugin.json create mode 100644 plugins/os-shortcuts/skills/wrap/SKILL.md diff --git a/docs/adr/0028-os-shortcuts-plugin-for-user-invoked-qol-commands-bounded-against-hook-injection-plugins.md b/docs/adr/0028-os-shortcuts-plugin-for-user-invoked-qol-commands-bounded-against-hook-injection-plugins.md new file mode 100644 index 0000000..04b3f89 --- /dev/null +++ b/docs/adr/0028-os-shortcuts-plugin-for-user-invoked-qol-commands-bounded-against-hook-injection-plugins.md @@ -0,0 +1,27 @@ +--- +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. diff --git a/docs/adr/README.md b/docs/adr/README.md index afeb1f4..ce5ed02 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -34,4 +34,5 @@ One file per decision, `NNNN-kebab-title.md`, created via `/os-adr:create`. | 0025 | [Standard Ruby structure for cc-os plugins (lib/ + single-dispatcher bin/, fail-soft, installed-gem-only dependencies)](0025-standard-ruby-structure-for-cc-os-plugins-lib-single-dispatcher-bin-fail-soft-installed-gem-only-dependencies.md) | Accepted | 2026-07-10 | | 0026 | [Unified project setup/update command: `/os-status:fix` remediates what the os-status checks flag](0026-unified-project-setup-update-command-os-status-fix-remediates-what-the-os-status-checks-flag.md) | Accepted | 2026-07-12 | | 0027 | [All cc-os per-project state lives under `.cc-os//`](0027-all-cc-os-per-project-state-lives-under-cc-os-plugin.md) | Accepted | 2026-07-12 | +| 0028 | [os-shortcuts plugin for user-invoked QOL commands, bounded against hook-injection plugins](0028-os-shortcuts-plugin-for-user-invoked-qol-commands-bounded-against-hook-injection-plugins.md) | Accepted | 2026-07-12 | diff --git a/docs/implementation-status.md b/docs/implementation-status.md index a50881a..93c51d8 100644 --- a/docs/implementation-status.md +++ b/docs/implementation-status.md @@ -1,6 +1,6 @@ # cc-os implementation status & changelog -_Last updated: 2026-07-10. This is the append-only implementation-status record moved out of +_Last updated: 2026-07-12. This is the append-only implementation-status record moved out of `CLAUDE.md` (2026-07-08, task B1 of [system-prompt-profiles-tasks.md](plans/system-prompt-profiles-tasks.md)). CLAUDE.md keeps orientation only; when a build step completes, record it HERE (plus @@ -219,6 +219,16 @@ decisions go through `/os-adr:create`. CLAUDE.md updated (docs/adr/ layout entry trigger-phrased decisions convention, os-adr rollout line). Remaining os-adr rollout: pilot projects one at a time, then wider. +**os-shortcuts plugin + `/wrap` shipped (2026-07-12, ADR-028, Planka card):** new plugin +`plugins/os-shortcuts/` for user-invoked QOL commands — the "keybindings" of cc-os; domain +boundary vs automatic hook injection (os-orchestration / future os-context) recorded in +ADR-028; skills only, no hooks. First resident `/os-shortcuts:wrap` encodes the session-close +ritual from the 2026-07-09 workflow audit (typed 20+ times): git review → commits per repo +conventions → doc/todo sweep deferring to project CLAUDE.md → Done/In-flight/Next handoff. +Registered in the local-plugins marketplace, enabled in settings.json, installed via +`claude plugin install os-shortcuts@local-plugins`. Sonnet-delegated build. `/readonly` +remains a separate open card (decide vs plan mode first). + **Remaining optional items:** additional project onboarding (one at a time, per ADR-013); bulk vault migration. All required build steps complete as of 2026-06-15. @@ -619,6 +629,17 @@ symlinked into `~/.claude/plugins/os-backlog`; PRD Forgejo issue #9, slices #10 installed 0.2.0 gem post-migration — see "os-backlog migrated to planka-api 0.2.0" and "os-backlog live verification (0.2.0)" timeline entries above. +### os-shortcuts (plugin) + +Global plugin: user-invoked QOL shortcut commands (ADR-028). Skills only — never hooks; +automatic injection belongs to os-orchestration / the planned os-context. + +- Skills: `/os-shortcuts:wrap` — session-close ritual (git review, commits per repo + conventions, doc/todo sweep deferring to project CLAUDE.md, handoff summary). Shipped + 2026-07-12. +- Expected future residents: additional shortcuts as audit findings warrant (`/readonly` + card is open — decide vs plan mode before implementing). + ## Operational procedures ### Renaming or moving a local plugin diff --git a/plugins/os-shortcuts/.claude-plugin/plugin.json b/plugins/os-shortcuts/.claude-plugin/plugin.json new file mode 100644 index 0000000..8ac37bf --- /dev/null +++ b/plugins/os-shortcuts/.claude-plugin/plugin.json @@ -0,0 +1,5 @@ +{ + "name": "os-shortcuts", + "version": "0.1.0", + "description": "User-invoked QOL shortcut commands for the cc-os plugin family — the 'keybindings' of cc-os, ritual multi-step sequences invoked on demand (not automatic hook injection). Starts with /os-shortcuts:wrap (session-close ritual); expect more shortcuts to accumulate here." +} diff --git a/plugins/os-shortcuts/skills/wrap/SKILL.md b/plugins/os-shortcuts/skills/wrap/SKILL.md new file mode 100644 index 0000000..1c58c0b --- /dev/null +++ b/plugins/os-shortcuts/skills/wrap/SKILL.md @@ -0,0 +1,58 @@ +--- +description: Session-close ritual — review changes, commit, sweep affected docs/todos, and produce a handoff summary. Trigger on "wrap up", "close out this session", "wrap", end-of-session. Invoked by /os-shortcuts:wrap. +--- + +# wrap + +The session-close ritual: review, commit, sweep docs, hand off. Run this near the end +of a working session so nothing from the session is lost — uncommitted work, stale +docs, or context the next session (or the user) needs. + +## Flow + +1. **Check the session's work.** Run `git status` and `git diff` (staged and + unstaged) to see everything touched this session. If nothing changed, skip to + step 4 and say so. + +2. **Propose and make commit(s).** + - Read the project's `CLAUDE.md` (if present) for commit conventions, and run + `git log --oneline -10` to match the repo's actual message style. + - Group changes into logically separate commits rather than one giant commit, + unless the work is genuinely a single unit. + - Follow this repo's own git-safety rules (never `--no-verify`, never force-push, + new commits rather than amends, etc.) — these are standing rules, not + session-specific. + - Commit directly unless the project's own conventions require confirmation + first (e.g. a CLAUDE.md instruction to ask before committing, or a commit that + touches something sensitive/destructive). Default is to just commit. + +3. **Sweep docs/todos affected by the session's work.** Look for anything the + session's changes should have updated but may not have: + - Build-plan checkmarks / step status (e.g. `docs/*/*-build-plan.md` style files). + - Status/timeline docs (e.g. `docs/implementation-status.md`-style files) — + add a timeline entry if the project keeps one. + - `_Last updated:_` / status lines on any design doc actually touched this + session. + - Any TODO list or issue tracker the project uses, per its own conventions. + Defer entirely to the project's `CLAUDE.md` for *which* files are the source of + truth and *how* they should be updated — don't invent a doc-update convention a + project doesn't already have. If the project has no such conventions, skip this + step rather than fabricating structure. + - If doc updates are substantive, fold them into a commit (step 2 pattern + applies) rather than leaving them uncommitted. + +4. **Produce a handoff summary as your final message.** Concise, three parts: + - **Done** — what was completed and committed this session. + - **In flight** — anything left uncommitted, half-finished, or deliberately + deferred, and why. + - **Next steps** — the concrete next action(s), especially anything that needs + the user's decision. + +## Notes + +- This skill has no hooks — it only runs when explicitly invoked. +- Don't silently skip step 2 or step 3 because it feels like extra work: the whole + point of `wrap` is to replace a manual ritual the user was doing by hand every + session. +- If a repo has no discernible commit or doc-update conventions, use judgment and + say so in the handoff rather than guessing silently.