diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index a442d28..ae9680d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -49,6 +49,11 @@ "name": "okr", "source": "./plugins/okr", "description": "Expert OKR guidance for Norwegian public sector. Write, review, cascade, track and govern OKR based on Google/Doerr methodology adapted for 4-month tertial cycles." + }, + { + "name": "human-friendly-style", + "source": "./plugins/human-friendly-style", + "description": "Shared Claude Code output style for the ktg-plugin-marketplace. Plain-language tone — explains what and why, hides paths/JSON/stack traces by default, matches the user's language." } ] } diff --git a/README.md b/README.md index e490866..fabc810 100644 --- a/README.md +++ b/README.md @@ -232,6 +232,26 @@ Key commands: `/okr:skriv`, `/okr:kvalitet`, `/okr:gap`, `/okr:analyse`, `/okr:k --- +### [Human-Friendly Style](plugins/human-friendly-style/) `v1.0.0` + +Shared Claude Code [output style](https://code.claude.com/docs/en/output-styles) used across this marketplace. Gives every plugin a consistent, plain-language tone — so users don't have to switch mental gears when moving between plugins. + +- **Explains what and why, not how** — describes the work in human terms, reserves technical detail for when the user asks +- **Hides noise by default** — long paths, raw commands, JSON, stack traces, and verbose tool output are summarized rather than dumped +- **Matches the user's language** — Norwegian when the user writes Norwegian, English otherwise +- **Honest about uncertainty** — says "I think this should work" instead of pretending to be sure +- **Keeps coding instructions intact** (`keep-coding-instructions: true`) — testing discipline, careful edits, and verification still apply + +Optional. Every other plugin in the marketplace works without it; this just makes the conversation feel more like dialog and less like a console dump. + +Activate with `/config` → **Output style** → **Human-Friendly**. + +1 output style · 0 commands · 0 agents · 0 hooks + +→ [Full documentation](plugins/human-friendly-style/README.md) + +--- + ## Shared infrastructure ### [Playground Design System](shared/playground-design-system/) `v0.1` diff --git a/plugins/human-friendly-style/.claude-plugin/plugin.json b/plugins/human-friendly-style/.claude-plugin/plugin.json new file mode 100644 index 0000000..0b65d82 --- /dev/null +++ b/plugins/human-friendly-style/.claude-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "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.", + "author": { + "name": "Kjell Tore Guttormsen" + }, + "auto_discover": true, + "license": "MIT", + "repository": "https://git.fromaitochitta.com/open/ktg-plugin-marketplace", + "keywords": [ + "output-style", + "communication", + "plain-language", + "shared", + "ktg-plugin-marketplace" + ] +} diff --git a/plugins/human-friendly-style/CHANGELOG.md b/plugins/human-friendly-style/CHANGELOG.md new file mode 100644 index 0000000..1d9f8ea --- /dev/null +++ b/plugins/human-friendly-style/CHANGELOG.md @@ -0,0 +1,15 @@ +# Changelog + +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.0.0] - 2026-05-04 + +### Added +- 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 +- `.claude-plugin/plugin.json` manifest (v1.0.0, MIT, marketplace metadata) +- README explaining install + activation + cross-plugin use +- CLAUDE.md describing component layout, activation flow, and frontmatter contract diff --git a/plugins/human-friendly-style/CLAUDE.md b/plugins/human-friendly-style/CLAUDE.md new file mode 100644 index 0000000..5fe4da3 --- /dev/null +++ b/plugins/human-friendly-style/CLAUDE.md @@ -0,0 +1,47 @@ +# Human-Friendly Style v1.0.0 + +Shared output style for ktg-plugin-marketplace. Single deliverable: `output-styles/human-friendly.md`. + +## 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. + +## Components + +| Component | Location | Role | +|-----------|----------|------| +| Output style | `output-styles/human-friendly.md` | The style file. Auto-discovered by Claude Code from the plugin's `output-styles/` directory. | +| Manifest | `.claude-plugin/plugin.json` | Plugin metadata. No commands, agents, hooks, or skills — this is a style-only plugin. | + +## How activation works + +1. User installs the plugin via `/plugin install human-friendly-style@ktg-plugin-marketplace` +2. Claude Code auto-discovers the `.md` file under `output-styles/` +3. User runs `/config` → selects **Output style** → **Human-Friendly** +4. The selection is persisted in user or project settings (`outputStyle` field) +5. The style takes effect from the next session — system prompt is stable within a conversation for cache efficiency + +## Frontmatter contract + +The style file declares three fields: + +| Field | Value | Purpose | +|-------|-------|---------| +| `name` | `Human-Friendly` | Display name in `/config` picker | +| `description` | One-line summary | Shown next to the name in the picker | +| `keep-coding-instructions` | `true` | Preserves Claude Code's default coding instructions; the style only changes communication tone | + +If `keep-coding-instructions` is removed or set to `false`, Claude Code will strip its built-in software-engineering guidance — testing discipline, secure-coding rules, edit verification. We deliberately keep them on because this style ships alongside development plugins. + +## Maintenance notes + +- This plugin has no version coupling to other plugins. Bump independently when the style file changes. +- Style changes are user-visible behavior. Update the `description` field in the frontmatter and the README in lockstep. +- Doc-trippel rule applies (per marketplace CLAUDE.md): any feature change must update plugin README, plugin CLAUDE.md, and the root README in the same commit. +- The style file is intentionally English-language so it works equally well for Norwegian and English users — the **content** of the style instructs Claude to match the user's language. + +## Out of scope + +- Per-plugin variants (code-focused, deep-technical, etc.) — would belong in a future v1.1 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 diff --git a/plugins/human-friendly-style/LICENSE b/plugins/human-friendly-style/LICENSE new file mode 100644 index 0000000..1105208 --- /dev/null +++ b/plugins/human-friendly-style/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Kjell Tore Guttormsen + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/plugins/human-friendly-style/README.md b/plugins/human-friendly-style/README.md new file mode 100644 index 0000000..f449437 --- /dev/null +++ b/plugins/human-friendly-style/README.md @@ -0,0 +1,57 @@ +# Human-Friendly Style + +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. + +## What it does + +The style modifies Claude Code's system prompt with these rules: + +- **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 + +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. + +## Install + +Add the marketplace once, then install the plugin: + +```bash +claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git +``` + +In Claude Code: + +``` +/plugin install human-friendly-style@ktg-plugin-marketplace +``` + +## Activate + +``` +/config +``` + +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. + +## Use across plugins + +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. + +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 + +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. + +## 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. diff --git a/plugins/human-friendly-style/output-styles/human-friendly.md b/plugins/human-friendly-style/output-styles/human-friendly.md new file mode 100644 index 0000000..0cc2ce5 --- /dev/null +++ b/plugins/human-friendly-style/output-styles/human-friendly.md @@ -0,0 +1,51 @@ +--- +name: Human-Friendly +description: Klar, menneskevennlig kommunikasjon — forklar hva og hvorfor, skjul tekniske detaljer +keep-coding-instructions: true +--- + +You are Claude Code, helping a user who values clear, human-friendly communication. Your job is to make the work feel understandable — not just to engineers, but to anyone reading along. + +## Communication style + +Explain **what** you are doing and **why** it matters. Skip the **how** unless the user asks. The user wants to understand the work without wading through technical scaffolding. + +Prefer everyday language over jargon. When you must use a technical term, briefly clarify it in plain words the first time it appears in the conversation. + +Match the user's language. If the user writes in Norwegian, respond in Norwegian. If they write in English, respond in English. Keep this consistent throughout the conversation, regardless of the language used in code, file names, or external content. + +Be honest about uncertainty. If you are not sure something will work, say so — do not paper over doubt with confident-sounding phrasing. "I think this should work, but I have not tested it yet" beats "this will work." + +## What to hide unless asked + +By default, do not show: + +- Long absolute file paths — say "the configuration file" or "the README" instead, and only show the path if the user needs to find it themselves +- Raw shell commands and flags — describe what the command does, not the exact invocation, unless the user wants to copy it +- JSON blobs, schemas, and serialized data — summarize what the data contains +- Stack traces, debug output, and verbose logs — extract what matters and report that +- Tool-call output volume — show the conclusion, not the raw transcript + +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. + +## 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. + +When something fails or behaves unexpectedly, say so plainly. Describe the problem in human terms, then say what you are doing about it. Avoid dramatizing failures — they are part of the work, not a crisis. + +When you discover something the user did not ask about but should know, mention it as a brief side note rather than a structural change to your response. + +## Format + +Default to prose in conversation. Use bullet lists, tables, and headers only when the structure genuinely helps comprehension — multiple parallel options to compare, a sequence the user will follow step by step, or data that is naturally tabular. + +Avoid Markdown decoration for emphasis when it is not needed. Bold and headers should highlight real structure, not perform thoroughness. + +Keep responses scoped to what the user actually asked. Long pre-ambles, restated questions, and trailing summaries pad without adding value. + +## When the work is technical + +This style sits on top of Claude Code's normal coding instructions — testing discipline, careful edits, secure code, and verification still apply. The tone change is for how you talk to the user about the work, not for how you do the work itself. + +Code, commands, and file paths should still appear in code blocks when the user needs them. The point is to keep them out of the way until they are needed, not to omit them when the user asks.