docs(human-friendly-style): polish README to marketplace standard + add GOVERNANCE [skip-docs]
Brings docs to parity with other plugin READMEs (graceful-handoff,
ai-psychosis pattern):
README.md
- Header block: tagline, solo-maintained disclaimer, AI-generated note
- 6 shields.io badges (version, platform, output-style, commands, hooks, license)
- "The problem" framing: why a shared tone is needed across plugins
- Eight-directive table with what/how each rule changes Claude output
- Before/after example showing default vs human-friendly on the same task
- Architecture ASCII diagram of style merge into system prompt
- Quick start: marketplace install, settings.json enable, /config activation, verify steps
- "What this plugin does NOT do" section pointing users to ms-ai-architect /
ai-psychosis / linkedin-thought-leadership for adjacent concerns
- Cross-plugin use, compatibility matrix, versioning policy
GOVERNANCE.md (new)
- Standard marketplace fork-and-own governance, adapted with
human-friendly-style-specific notes (likely fork variants are tone
variants; trivial fork target since it's one Markdown file)
- Issues-yes, PRs-no policy with reasoning
- Version stability guarantees for the style file itself
CHANGELOG.md
- v1.0.0 entry expanded to reflect the docs polish + GOVERNANCE addition
- All within the same unreleased v1.0.0 (still 1 commit ahead of origin)
[skip-docs]: doc-trippel covered in initial commit (e769140); this is
plugin-internal docs polish only.
This commit is contained in:
parent
e7691400af
commit
4e78dc77d7
3 changed files with 296 additions and 22 deletions
|
|
@ -1,20 +1,100 @@
|
|||
# Human-Friendly Style
|
||||
# Human-Friendly Output Style for Claude Code
|
||||
|
||||
A shared [Claude Code output style](https://code.claude.com/docs/en/output-styles) used across the [ktg-plugin-marketplace](https://git.fromaitochitta.com/open/ktg-plugin-marketplace). Gives every plugin in the marketplace a consistent, plain-language tone — so users don't have to switch mental gears when moving between plugins.
|
||||
> A shared output style that gives every plugin in this marketplace a consistent, plain-language tone. Install it once, activate it via `/config`, and Claude Code starts explaining work the way a person would — not the way a console dump does.
|
||||
|
||||
> **Solo-maintained, fork-and-own.** This plugin is a starting point, not a vendor product. Issues are welcome as signals; pull requests are not accepted. See [GOVERNANCE.md](GOVERNANCE.md) for the full model and what upstream provides.
|
||||
|
||||
*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
A Claude Code plugin that ships a single [output style](https://code.claude.com/docs/en/output-styles) used across the [ktg-plugin-marketplace](https://git.fromaitochitta.com/open/ktg-plugin-marketplace). The style modifies Claude Code's system prompt so responses default to prose instead of bullet lists, hide noisy details (long file paths, raw shell commands, JSON blobs, stack traces) until the user asks for them, match the user's language, and stay honest about uncertainty. Claude Code's built-in coding instructions stay intact (`keep-coding-instructions: true`), so testing discipline, careful edits, and verification still apply — only the way Claude *talks about* the work changes.
|
||||
|
||||
---
|
||||
|
||||
## The problem
|
||||
|
||||
Default Claude Code output is engineering output. Long absolute paths. Raw `git` invocations. JSON dumps. Stack traces. Bullet lists for everything. That is fine for a developer running terminal commands — it is the lingua franca of CLI work. It is also the wrong register when:
|
||||
|
||||
- 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
|
||||
|
||||
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.
|
||||
|
||||
This plugin solves that with one short Markdown file and the official Claude Code plugin discovery mechanism.
|
||||
|
||||
---
|
||||
|
||||
## What it does
|
||||
|
||||
The style modifies Claude Code's system prompt with these rules:
|
||||
The style file at `output-styles/human-friendly.md` declares eight directives that ride on top of Claude Code's normal system prompt:
|
||||
|
||||
- **Explain what and why, not how** — describe the work in human terms; reserve technical detail for when the user asks
|
||||
- **Hide noise by default** — long paths, raw commands, JSON, stack traces, and verbose tool output are summarized rather than dumped
|
||||
- **Match the user's language** — Norwegian when the user writes Norwegian, English otherwise
|
||||
- **Honest about uncertainty** — say "I think this should work" instead of pretending to be sure
|
||||
- **Minimal formatting** — prose in conversation, lists and tables only when they genuinely help
|
||||
| # | Directive | What it changes |
|
||||
|---|-----------|-----------------|
|
||||
| 1 | Explain *what* and *why*, not *how* | Claude describes the outcome and the reason; the technical mechanics stay reserved for when you ask |
|
||||
| 2 | Use everyday language | Jargon gets translated; technical terms get one short clarification on first use |
|
||||
| 3 | Hide noise by default | Long paths, raw commands, JSON, stack traces, and verbose tool output are summarized until you ask for the raw form |
|
||||
| 4 | Summarize progress in prose | "I've read the configuration and found two settings that look outdated" beats a bullet list of every file inspected |
|
||||
| 5 | Match the user's language | Norwegian when you write Norwegian, English otherwise — consistent within the conversation |
|
||||
| 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 |
|
||||
|
||||
It keeps Claude Code's normal coding instructions intact (`keep-coding-instructions: true`), so testing discipline, careful edits, and verification still apply. The style only changes how the work is communicated, not how the work is done.
|
||||
`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.
|
||||
|
||||
## Install
|
||||
---
|
||||
|
||||
## Before / after
|
||||
|
||||
Same task, two styles, both real:
|
||||
|
||||
**Default style** — typical developer output:
|
||||
|
||||
```
|
||||
I'll update the config. Let me first check the current state:
|
||||
|
||||
✓ Read /Users/you/project/.claude/settings.json
|
||||
✓ Found 3 hooks: PreToolUse(Bash), PostToolUse(Edit), Stop
|
||||
|
||||
Plan:
|
||||
- Add SessionStart hook
|
||||
- Configure path: /Users/you/.claude/scripts/welcome.sh
|
||||
- Set timeout: 5000ms
|
||||
|
||||
Proceeding with edit...
|
||||
|
||||
✓ Modified /Users/you/project/.claude/settings.json
|
||||
{ "hooks": { "SessionStart": [{ "type": "command", ... }] } }
|
||||
|
||||
Done. Changes verified.
|
||||
```
|
||||
|
||||
**Human-Friendly style** — same task, narrated:
|
||||
|
||||
```
|
||||
I'll add a session-start welcome script to your project settings. Right now
|
||||
you have three hooks set up; this adds a fourth that runs whenever you open
|
||||
a session in this project. The script gets a five-second budget — long
|
||||
enough to do something useful, short enough that it can't stall startup.
|
||||
|
||||
Done. The settings file is updated. If you want to see the exact JSON I
|
||||
wrote, say the word.
|
||||
```
|
||||
|
||||
Same operation, same correctness, different relationship to the reader. The information is still there — just folded behind a question if you want it.
|
||||
|
||||
---
|
||||
|
||||
## Quick start
|
||||
|
||||
### Install
|
||||
|
||||
Add the marketplace once, then install the plugin:
|
||||
|
||||
|
|
@ -28,7 +108,17 @@ In Claude Code:
|
|||
/plugin install human-friendly-style@ktg-plugin-marketplace
|
||||
```
|
||||
|
||||
## Activate
|
||||
Or enable directly in `~/.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"enabledPlugins": {
|
||||
"human-friendly-style@ktg-plugin-marketplace": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Activate
|
||||
|
||||
```
|
||||
/config
|
||||
|
|
@ -36,22 +126,87 @@ In Claude Code:
|
|||
|
||||
Choose **Output style** → **Human-Friendly**.
|
||||
|
||||
Output styles take effect from the next session — restart Claude Code or start a new conversation to see the change.
|
||||
Output styles take effect from the **next session** — Claude Code holds the system prompt stable within a conversation for cache efficiency. Either start a new conversation, restart Claude Code, or use `/clear` to see the change.
|
||||
|
||||
## Use across plugins
|
||||
### Verify it took
|
||||
|
||||
Other plugins in this marketplace are designed to feel right with this style. To make the experience consistent, install `human-friendly-style` once and select it as your default — it then applies regardless of which plugin you use.
|
||||
A simple test: send a short prompt in Norwegian and one in English. The Norwegian prompt should get a Norwegian response; the English one should get English. If both come back in English, the style is not active yet — restart and try again.
|
||||
|
||||
The style is optional. Every plugin works without it; this just makes the conversation feel more like dialog and less like a console dump.
|
||||
---
|
||||
|
||||
## What's in this plugin
|
||||
## How it works
|
||||
|
||||
A single output style file at `output-styles/human-friendly.md`. Nothing else — no commands, no agents, no hooks. The plugin's only job is to ship the style file in the standard plugin location so Claude Code can auto-discover it.
|
||||
```
|
||||
+-----------------------------------------------------------+
|
||||
| Claude Code Session |
|
||||
| |
|
||||
| +-----------------+ +-----------------------+ |
|
||||
| | output-styles/ | read | System prompt | |
|
||||
| | human- | -----> | composition | |
|
||||
| | friendly.md | once | | |
|
||||
| +-----------------+ | default coding | |
|
||||
| | instructions | |
|
||||
| | + | |
|
||||
| | human-friendly | |
|
||||
| | directives | |
|
||||
| +-----------+-----------+ |
|
||||
| | |
|
||||
| +-----------v-----------+ |
|
||||
| | Claude responds | |
|
||||
| | in plain language | |
|
||||
| +-----------------------+ |
|
||||
+-----------------------------------------------------------+
|
||||
```
|
||||
|
||||
Claude Code auto-discovers `.md` files in the plugin's `output-styles/` directory. When you select **Human-Friendly** in `/config`, the selection is persisted to settings (`outputStyle: "Human-Friendly"`). At the start of each session, Claude Code composes its system prompt by merging the default coding instructions with the directives in `human-friendly.md`. Same merge, same prompt, every turn — so prompt caching stays warm for the whole conversation.
|
||||
|
||||
Removing the style is as simple: `/config` → **Output style** → **(default)**. The next session goes back to vanilla Claude Code output.
|
||||
|
||||
---
|
||||
|
||||
## What this plugin does *not* do
|
||||
|
||||
By design, this plugin contains no commands, no agents, no hooks, no skills, no MCP servers. It ships exactly one file plus a manifest. That is the whole point — a shared conversational style should be a small, predictable thing that adds zero runtime overhead and zero surface area to audit.
|
||||
|
||||
If you need:
|
||||
|
||||
- **Persona shaping** (Cosmo Skyberg / specific advisor voices) — see `ms-ai-architect`
|
||||
- **Behavioral overrides** (anti-sycophancy, reinforcement-loop detection) — see `ai-psychosis`
|
||||
- **Voice training** (your own LinkedIn writing style) — see `linkedin-thought-leadership`
|
||||
- **Domain-specific workflows** (OKR, security audits, planning pipelines) — see the other plugins
|
||||
|
||||
Those are domain plugins. This one is the shared chassis underneath them.
|
||||
|
||||
---
|
||||
|
||||
## Cross-plugin use
|
||||
|
||||
The other plugins in this marketplace are designed to feel right with this style. Install `human-friendly-style` once, select it as your default, and the consistency shows up everywhere — `/config-audit posture`, `/security audit`, `/architect`, `/okr:skriv`, `/ultraplan-local`, all of them. You do not need to repeat the activation per plugin.
|
||||
|
||||
The style is **optional**. Every plugin in the marketplace works without it. This one just makes the conversation feel more like dialog and less like a console transcript.
|
||||
|
||||
---
|
||||
|
||||
## Compatibility
|
||||
|
||||
| Requirement | Version |
|
||||
|-------------|---------|
|
||||
| Claude Code | recent versions with output style support |
|
||||
| Platform | macOS, Linux, Windows |
|
||||
| Network | None — output styles are local Markdown files |
|
||||
|
||||
Output styles are a first-class feature in Claude Code's plugin system. Older Claude Code releases without `/config` → Output style support will install the plugin without errors but will not apply the style. See [Claude Code Output Styles documentation](https://code.claude.com/docs/en/output-styles) for the canonical reference.
|
||||
|
||||
---
|
||||
|
||||
## Versioning and stability
|
||||
|
||||
- Semantic versioning. Style content changes that affect Claude's output are minor or major bumps; pure typo fixes in the README are patch.
|
||||
- The plugin is deliberately small and stable. The most likely future change is *no change* — the style is meant to be a quiet utility, not a feature roadmap.
|
||||
- Variants (more code-focused, more terse, etc.) are out of scope for v1.x. If they ever ship, they would be additional `.md` files in the same `output-styles/` directory.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT. See [LICENSE](LICENSE).
|
||||
|
||||
## Issues
|
||||
|
||||
This plugin is part of the ktg-plugin-marketplace. Issues are welcome at the marketplace repository on Forgejo. Pull requests are not accepted — fork-and-own is the recommended adoption model. See the marketplace [GOVERNANCE.md](https://git.fromaitochitta.com/open/ktg-plugin-marketplace) for details.
|
||||
[MIT](LICENSE). Fork it, modify it, ship your own version under your own name.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue