open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

docs(human-friendly-style): polish README to marketplace standard + add GOVERNANCE [skip-docs]

Browse source 
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:
Kjell Tore Guttormsen 2026-05-04 21:08:06 +02:00
commit 4e78dc77d7
3 changed files with 296 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

3
plugins/human-friendly-style/CHANGELOG.md
View file

@ -11,5 +11,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Initial release of `human-friendly-style` as a shared output style for ktg-plugin-marketplace - Initial release of `human-friendly-style` as a shared output style for ktg-plugin-marketplace
- `output-styles/human-friendly.md` — the style file with frontmatter (`name`, `description`, `keep-coding-instructions: true`) and full instruction set covering tone, language matching, hidden-by-default noise, prose-first formatting, and honest uncertainty handling - `output-styles/human-friendly.md` — the style file with frontmatter (`name`, `description`, `keep-coding-instructions: true`) and full instruction set covering tone, language matching, hidden-by-default noise, prose-first formatting, and honest uncertainty handling
- `.claude-plugin/plugin.json` manifest (v1.0.0, MIT, marketplace metadata) - `.claude-plugin/plugin.json` manifest (v1.0.0, MIT, marketplace metadata)
- README explaining install + activation + cross-plugin use - Professional README with badges, problem/solution narrative, eight-directive table, before/after example, architecture diagram, install + activation steps, cross-plugin use guidance, compatibility matrix, and versioning policy
- CLAUDE.md describing component layout, activation flow, and frontmatter contract - CLAUDE.md describing component layout, activation flow, and frontmatter contract
- GOVERNANCE.md establishing fork-and-own adoption model, contribution policy (issues yes, PRs no), and version stability guarantees — aligned with marketplace-wide governance pattern

118
plugins/human-friendly-style/GOVERNANCE.md Normal file
View file

@ -0,0 +1,118 @@
# Governance
How this marketplace is maintained, what you can expect from upstream, and how it's meant to be used.
## TL;DR
- Solo-maintained, AI-assisted development, MIT licensed.
- **Fork-and-own is the default model.** Upstream is a starting point, not a vendor.
- Issues welcome as signals. Pull requests are not accepted — see [Why no PRs](#pull-requests--no).
- No SLA. Best-effort bug fixes and security advisories. Breaking changes happen and are noted in each plugin's CHANGELOG.
---
## Can I trust this?
Be honest with yourself about what you're adopting:
- **One maintainer.** If I get hit by a bus, the bus wins. The repos stay up under MIT, but no one owes you a fix.
- **AI-generated code with human review.** Every plugin is built through dialog-driven development with Claude Code. I read, test, and judge the output before it ships, but I'm not auditing every line the way a security firm would. Treat it accordingly.
- **No commercial interests.** I'm not selling a SaaS, not steering you toward a paid tier, not collecting telemetry. The plugins run locally in your Claude Code installation.
- **MIT licensed.** Fork it, modify it, ship it under your own name.
If you work somewhere that needs vendor accountability, support contracts, or signed assurances — **this isn't that.** Use it as a reference implementation, fork it into your own organization, and own the result.
---
## How this is meant to be used
### Fork-and-own
The intended workflow:
1. **Fork** the marketplace (or a single plugin) into your own organization or namespace.
2. **Tailor** it to your context — terminology, integrations, whatever doesn't fit out of the box.
3. **Maintain it yourself.** Treat your fork as the canonical version for your team.
4. **Watch upstream selectively.** Cherry-pick changes that help, ignore changes that don't. There's no obligation to stay in sync.
For `human-friendly-style` specifically, the most likely fork is a tone variant — a more terse style for terminal-only users, a more verbose style for non-technical readers, a different language match policy, or directives tuned to a specific organization's communication norms. The plugin is one short Markdown file plus a manifest. Forking it is trivial.
### What to change first when you fork
- **Identity** — rename the plugin, replace authorship, update README.
- **Style content** — the directives in `output-styles/human-friendly.md` reflect my taste. Adjust them to your team's voice.
- **Frontmatter** — `name` and `description` show up in `/config`. Pick names that won't collide with other forks installed on the same machine.
### Staying current with upstream
If you want to pull in upstream changes later:
- **Cherry-pick, don't merge.** Each plugin moves independently.
- **Read the CHANGELOG first.**
- **Keep your customizations distinct.** A renamed style file (`my-org-style.md`) merges more cleanly than edits to `human-friendly.md`.
---
## What upstream provides
| | What I do | What I don't |
|---|---|---|
| **Bug fixes** | Best-effort when I notice or get a clear report | No SLA, no triage commitment |
| **Security issues** | Investigate within reasonable time, document in CHANGELOG | No CVE process, no embargo coordination |
| **New features** | When they fit my own usage | Not on request |
| **Breaking changes** | Documented in CHANGELOG | They happen — version pin if you need stability |
| **Compatibility** | Tracked against current Claude Code releases | No long-term support branches |
If any of this is a dealbreaker — fork now, version-pin, and stop reading upstream.
---
## How to contribute
### Issues — yes, please
Issues are the most valuable thing you can send me:
- **Bug reports** with reproduction steps. Even a screenshot helps.
- **Use-case feedback.** "I tried to use this in my organization and X didn't fit" is genuinely useful, even if I can't fix it for you.
- **Style suggestions.** If a directive in `human-friendly.md` produces output that doesn't feel human-friendly in your context, tell me what you saw. Concrete examples beat abstract complaints.
### Pull requests — no
This is deliberate, not laziness:
- **Solo review is a bottleneck.** Honest PR review takes me longer than rewriting from scratch. The math doesn't work.
- **Forks are where the value is.** The fork-and-own model means upstream consolidation isn't the point. Your organization's adaptations belong in your fork, not mine.
- **AI-generated code complicates provenance.** Every line here is produced through dialog with Claude Code, with me as the judge. Mixing in PRs from contributors with different processes and licensing assumptions creates a mess I'd rather not untangle.
If you've built something useful on top of a fork, **publish it under your own name and link back.** I'll happily list notable forks here once they exist.
### Notable forks
*(To be populated as forks emerge. If you've forked this plugin for production use, open an issue and I'll add a link.)*
---
## Relationship between plugins
These plugins are **independent**. Install one without the others, fork one without the others. They share conventions (slash command naming, hook patterns, AI-generated disclosure, and now this shared output style) but no runtime dependencies.
`human-friendly-style` is a shared convenience — every other plugin works without it, and it works without any other plugin installed.
The marketplace is a **catalog**, not a suite. Don't fork the whole repo unless you actually want to maintain everything.
---
## Versioning and stability
- **Semantic versioning per plugin.** Each plugin has its own `CHANGELOG.md` and version number.
- **Breaking changes happen.** I bump the major version when they do, but I don't run an LTS branch.
- **Pin your version.** If stability matters more than features, install a specific version and stay there until you choose to upgrade.
For `human-friendly-style` specifically: changes that alter Claude's output behavior are minor or major bumps. Pure README/docs changes are patch. The style file itself is meant to be stable.
---
## License
MIT for all plugins in this marketplace. See [LICENSE](LICENSE) in this plugin and each other plugin's `LICENSE` file.

199
plugins/human-friendly-style/README.md
View file

@ -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)*
![Version](https://img.shields.io/badge/version-1.0.0-blue)
![Platform](https://img.shields.io/badge/platform-Claude_Code_Plugin-purple)
![Output style](https://img.shields.io/badge/output_style-1-green)
![Commands](https://img.shields.io/badge/commands-0-lightgrey)
![Hooks](https://img.shields.io/badge/hooks-0-lightgrey)
![License](https://img.shields.io/badge/license-MIT-lightgrey)
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 ## 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 | # | Directive | What it changes |
- **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 | 1 | Explain *what* and *why*, not *how* | Claude describes the outcome and the reason; the technical mechanics stay reserved for when you ask |
- **Honest about uncertainty** — say "I think this should work" instead of pretending to be sure | 2 | Use everyday language | Jargon gets translated; technical terms get one short clarification on first use |
- **Minimal formatting** — prose in conversation, lists and tables only when they genuinely help | 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: Add the marketplace once, then install the plugin:
@ -28,7 +108,17 @@ In Claude Code:
/plugin install human-friendly-style@ktg-plugin-marketplace /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 /config
@ -36,22 +126,87 @@ In Claude Code:
Choose **Output style** → **Human-Friendly**. 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 ## License
MIT. See [LICENSE](LICENSE). [MIT](LICENSE). Fork it, modify it, ship your own version under your own name.
## 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.