From 0cdf55d52b3745fd0ef2aa0b6c91a09e6d8b2420 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Sun, 3 May 2026 14:57:00 +0200 Subject: [PATCH] docs: introduce GOVERNANCE.md and unify fork-and-own blurb Establish a single governance document at marketplace root and copy it into each of the 9 plugins so every plugin folder remains 100% self-contained. Replace the inconsistent provocative blurb across all READMEs with a uniform fork-and-own paragraph that links to the local GOVERNANCE.md. [skip-docs] Co-Authored-By: Claude Opus 4.7 --- GOVERNANCE.md | 131 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 +- 2 files changed, 132 insertions(+), 1 deletion(-) create mode 100644 GOVERNANCE.md diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..a1e9b52 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,131 @@ +# 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, cycle lengths, regulatory framing, 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. + +This isn't a workaround for not accepting PRs. It's the actual recommended adoption pattern, especially for plugins like `okr` and `ms-ai-architect` where every Norwegian public sector organization will need its own tildelingsbrev mappings, terminology, and integrations. A central "one true plugin" would be wrong for everyone. + +### What to change first when you fork + +Each plugin differs, but the common edits are: + +- **Identity** — rename the plugin, replace authorship, update README. +- **External integrations** — issue trackers, knowledge bases, dashboards, observability backends. The plugins ship as starting points, not pre-wired. Every organization must configure its own integrations. +- **Norwegian-specific framing** — relevant for `okr` and `ms-ai-architect`. Other plugins are jurisdiction-neutral. Rewrite for your jurisdiction if you're outside Norway. +- **Reference docs** — the knowledge base in each plugin reflects my reading. Replace with your organization's authoritative sources. +- **Hooks and policies** — security thresholds, blocked commands, and audit gates are tuned to my taste. Tune them to yours. + +### Staying current with upstream + +If you want to pull in upstream changes later: + +- **Cherry-pick, don't merge.** Each plugin moves independently and breaking changes land without ceremony. +- **Read the CHANGELOG first.** Every plugin has one. +- **Keep your customizations in clearly-named files.** The harder upstream is to merge cleanly, the more painful staying current becomes. A `local/` directory or `*.local.md` convention helps. + +--- + +## 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 | +| **Norwegian public sector context** | Kept current as long as the project lives | If I lose interest or change jobs, the framing freezes | +| **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. +- **Pointers to better sources.** If you know a DFØ veileder, an NSM guideline, or an academic paper that contradicts what's in a knowledge base, tell me. +- **Security findings.** See each plugin's `SECURITY.md` for disclosure preference where one exists; otherwise email rather than open a public issue. + +### 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 one of these plugins 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) but no runtime dependencies. + +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. + +--- + +## Public sector adoption notes + +For Norwegian etater specifically: + +- **DPIA-relevant data flows are documented in the relevant plugin README where applicable.** Read them before installation. +- **No data leaves your machine** beyond what Claude Code itself sends to Anthropic. The plugins themselves do not call external services unless you configure an integration. +- **Drøftingsplikt and ledelsesansvar** are not replaced by these tools. The `okr` plugin coaches; it does not decide. The `ms-ai-architect` plugin advises; it does not approve. +- **Choose your Claude deployment carefully.** claude.ai vs. API direct vs. Bedrock in EU region have different data residency profiles. The plugins don't choose for you. + +--- + +## License + +MIT for all plugins in this marketplace. See each plugin's `LICENSE` file. diff --git a/README.md b/README.md index 15d2a3c..3c9370a 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ # Interaction Awareness -*Built for my own Claude Code workflow and shared openly for anyone who finds it useful. This is a solo project — bug reports and feature requests are welcome, but pull requests are not accepted.* +> **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)*