feat(human-friendly-style): v1.1.0 — always show irreversible actions verbatim + discoverability docs
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
parent
b6bb61246b
commit
66709b0867
6 changed files with 38 additions and 8 deletions
|
|
@ -1,7 +1,7 @@
|
|||
{
|
||||
"name": "human-friendly-style",
|
||||
"version": "1.0.0",
|
||||
"description": "Shared output style for ktg-plugin-marketplace plugins. Activates a clear, plain-language tone that hides paths, raw commands, JSON, and stack traces by default.",
|
||||
"version": "1.1.0",
|
||||
"description": "Shared output style for ktg-plugin-marketplace plugins. Activates a clear, plain-language tone that hides paths, raw commands, JSON, and stack traces by default — while always showing irreversible actions (deploys, deletes, force-push, migrations) verbatim before and after.",
|
||||
"author": {
|
||||
"name": "Kjell Tore Guttormsen"
|
||||
},
|
||||
|
|
|
|||
|
|
@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
|
|||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [1.1.0] - 2026-05-29
|
||||
|
||||
### Added
|
||||
- **Irreversible-action carve-out** in `output-styles/human-friendly.md` — a new directive (9th) that overrides the hide-by-default noise reduction for state-changing, unrecoverable operations: production deploys, deletes, force-push / git-history rewrites, database migrations and destructive queries, and bulk file edits. For these, Claude shows the exact command and target verbatim before running and reports the same verbatim after, even unprompted, so the user can approve and audit. When reversibility is uncertain, the action is treated as irreversible. Documented as best-effort model guidance, not an enforced guard — a hard guarantee would require a hook, which is deliberately out of scope for this zero-runtime plugin.
|
||||
- **"Getting more detail" section** in the README surfacing the escape hatch that already lived in the style: ask once for the raw form, set a standing preference for the session, or turn the style off via `/config` / `/output-style`. Also notes the irreversible-action exception.
|
||||
|
||||
### Changed
|
||||
- README directive table grows from eight rows to nine; prose "eight directives" reference updated to "nine"; version badge `1.0.0` → `1.1.0`.
|
||||
- `.claude-plugin/plugin.json` description extended to mention irreversible actions are always shown verbatim.
|
||||
|
||||
## [1.0.0] - 2026-05-04
|
||||
|
||||
### Added
|
||||
|
|
|
|||
|
|
@ -1,7 +1,9 @@
|
|||
# Human-Friendly Style v1.0.0
|
||||
# Human-Friendly Style v1.1.0
|
||||
|
||||
Shared output style for ktg-plugin-marketplace. Single deliverable: `output-styles/human-friendly.md`.
|
||||
|
||||
v1.1.0 added an **irreversible-action carve-out**: the hide-by-default noise reduction has one exception — destructive or unrecoverable operations (prod deploy, delete, force-push, git-history rewrite, DB migration, bulk file edits) are shown verbatim (command + target) before and after, even unprompted, so the user can approve and audit. Style stays nine directives, still zero commands/agents/hooks; the carve-out is best-effort model guidance, not an enforced guard (a hook would be a separate plugin).
|
||||
|
||||
## Purpose
|
||||
|
||||
Give every plugin in the marketplace a consistent, plain-language tone. Users install this once, activate via `/config`, and get the same conversational style regardless of which plugin they invoke.
|
||||
|
|
@ -42,6 +44,6 @@ If `keep-coding-instructions` is removed or set to `false`, Claude Code will str
|
|||
|
||||
## Out of scope
|
||||
|
||||
- Per-plugin variants (code-focused, deep-technical, etc.) — would belong in a future v1.1 if there's real demand
|
||||
- Per-plugin variants (code-focused, deep-technical, etc.) — would belong in a future v1.x if there's real demand
|
||||
- Forcing the style on other plugins — it remains opt-in. Other plugins may reference it in their READMEs.
|
||||
- Translation of the style file itself into Norwegian — defeats the purpose of language-agnostic instruction
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
|
||||
*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -24,7 +24,7 @@ Default Claude Code output is engineering output. Long absolute paths. Raw `git`
|
|||
- A non-engineer is reading along over your shoulder
|
||||
- You are documenting a session for someone who needs to understand what happened, not how it happened
|
||||
- You are using Claude Code for non-code work (writing, research, planning) and the surrounding noise gets in the way
|
||||
- You want each plugin in your toolkit to feel like part of one assistant, not eight different consoles
|
||||
- You want each plugin in your toolkit to feel like part of one assistant, not a handful of different consoles
|
||||
|
||||
The other plugins in this marketplace cover specific domains (security, configuration, OKRs, Microsoft architecture, LinkedIn content, planning). Each has its own slash commands, agents, and hooks. What they did not have until now was a shared **conversational tone** — so installing two plugins meant getting two slightly different experiences glued together.
|
||||
|
||||
|
|
@ -34,7 +34,7 @@ This plugin solves that with one short Markdown file and the official Claude Cod
|
|||
|
||||
## What it does
|
||||
|
||||
The style file at `output-styles/human-friendly.md` declares eight directives that ride on top of Claude Code's normal system prompt:
|
||||
The style file at `output-styles/human-friendly.md` declares nine directives that ride on top of Claude Code's normal system prompt:
|
||||
|
||||
| # | Directive | What it changes |
|
||||
|---|-----------|-----------------|
|
||||
|
|
@ -46,6 +46,7 @@ The style file at `output-styles/human-friendly.md` declares eight directives th
|
|||
| 6 | Honest about uncertainty | "I think this should work, but I haven't tested it yet" beats fabricated confidence |
|
||||
| 7 | Minimal formatting | Prose first; lists, tables, and headers only when structure genuinely helps comprehension |
|
||||
| 8 | Failure framed plainly | Errors are described in human terms, with what is being done about them — no drama, no jargon walls |
|
||||
| 9 | Always show irreversible actions | The hide-by-default in directive 3 has one exception: destructive or unrecoverable operations (prod deploy, delete, force-push, history rewrite, DB migration, bulk file edits) are shown verbatim — exact command and target — before and after, even unprompted, so you can approve and audit |
|
||||
|
||||
`keep-coding-instructions: true` in the frontmatter means Claude Code's built-in software-engineering instructions (test-first, secure code, careful edits, verification) stay active. The style only changes how Claude *communicates* about the work — not how the work itself is done.
|
||||
|
||||
|
|
@ -92,6 +93,18 @@ Same operation, same correctness, different relationship to the reader. The info
|
|||
|
||||
---
|
||||
|
||||
## Getting more detail
|
||||
|
||||
Hiding noise is the default, not a wall. Anything the style folds away is one ask from being shown in full:
|
||||
|
||||
- **Ask once.** "Show me the exact command", "paste the JSON", "what's the full path" — Claude shows the raw form for that answer.
|
||||
- **Set a standing preference.** "Always show the commands and paths when you change something" — Claude holds it for the rest of the conversation, so you only say it once.
|
||||
- **Turn the style off entirely.** `/config` → **Output style** → **(default)**, or `/output-style`. The next session goes back to vanilla Claude Code output.
|
||||
|
||||
One thing the style does *not* hide, even unprompted: **irreversible actions**. Deploying to production, deleting data, force-pushing or rewriting git history, database migrations, and bulk file edits are always shown verbatim — the exact command and its target, before and after — so you can approve before and audit after. This is best-effort guidance to the model, not an enforced guard; a hard guarantee would need a hook, which is deliberately out of scope for this zero-runtime plugin.
|
||||
|
||||
---
|
||||
|
||||
## Quick start
|
||||
|
||||
### Install
|
||||
|
|
|
|||
|
|
@ -28,6 +28,10 @@ By default, do not show:
|
|||
|
||||
When the user asks for any of these explicitly ("show me the path", "what was the actual command", "paste the JSON"), provide them in full. The defaults exist to reduce noise, not to withhold information.
|
||||
|
||||
## Always show, even unprompted: irreversible actions
|
||||
|
||||
The noise-hiding above applies to read-only and idempotent work. It does NOT apply to actions that change state irreversibly — deploying to production, deleting data or files, force-pushing or rewriting git history, database migrations and destructive queries, mass or bulk file edits, and anything you cannot cleanly undo. For these, show the exact command (or API call) and its target verbatim before you run it, and report the same verbatim after. The user must be able to audit precisely what changed. When unsure whether an action is reversible, treat it as irreversible and show it.
|
||||
|
||||
## Progress and findings
|
||||
|
||||
Summarize progress in short, natural sentences. "I have read the configuration and found two settings that look outdated" is better than a bullet list of every file inspected.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue