From b8e362fe57cd09ecf5ffabe771d7f88354836d50 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Wed, 8 Apr 2026 15:22:45 +0200 Subject: [PATCH] =?UTF-8?q?docs(okr):=20rewrite=20README=20for=20engagemen?= =?UTF-8?q?t=20=E2=80=94=20problem-first=20landing=20page?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace dry documentation-style README with problem-first structure: lead with public sector pain points, show realistic interaction example, add "when not to use" section, move badges to bottom. 132 lines (down from 280). Hook within 10 seconds. Co-Authored-By: Claude Opus 4.6 --- plugins/okr/README.md | 299 +++++++++++------------------------------- 1 file changed, 76 insertions(+), 223 deletions(-) diff --git a/plugins/okr/README.md b/plugins/okr/README.md index 1370676..719e909 100644 --- a/plugins/okr/README.md +++ b/plugins/okr/README.md @@ -4,63 +4,62 @@ *Solo project — bug reports welcome, PRs not accepted.* -![Version](https://img.shields.io/badge/version-1.0.0-blue) -![Platform](https://img.shields.io/badge/platform-Claude_Code_Plugin-purple) -![Agents](https://img.shields.io/badge/agents-5-orange) -![Commands](https://img.shields.io/badge/commands-8-blue) -![Hooks](https://img.shields.io/badge/hooks-3-green) -![References](https://img.shields.io/badge/references-15-yellow) -![License](https://img.shields.io/badge/license-MIT-lightgrey) +## The Problem -A Claude Code plugin that provides structured OKR (Objectives and Key Results) guidance for Norwegian public sector organizations. Based on Google/Doerr methodology, adapted for 4-month tertial cycles, government accountability requirements, and public sector governance. +OKR sounds simple until you try it in public sector. Your organization gets a tildelingsbrev with 47 requirements, and someone asks you to turn it into "3-5 inspiring Objectives." Teams write KRs that are just task lists. Tertial cycles don't match the quarterly model from Google. And when Riksrevisjonen asks for documentation, nobody can trace which OKR delivered which mandate requirement. ---- +Most OKR tools assume you're a startup with quarterly goals and stock options. You're not. You have political steering, budget cycles tied to Stortinget, and mid-cycle priority changes from a minister who read something in Aftenposten. -## Table of Contents +This plugin understands that context. -- [What Is This?](#what-is-this) -- [Quick Start](#quick-start) -- [Commands](#commands) -- [Agents](#agents) -- [Hooks](#hooks) -- [Knowledge Base](#knowledge-base) -- [Workflow Examples](#workflow-examples) -- [Public Sector Features](#public-sector-features) -- [Configuration](#configuration) -- [Integrations](#integrations) -- [Limitations](#limitations) -- [Version History](#version-history) -- [License](#license) +## What You Get ---- +- **Guided OKR writing** that turns vague ambitions into outcome-focused Objectives with measurable Key Results — including baseline, target, and data source +- **Quality scoring** against a rubric that catches the 19 most common OKR mistakes (activity masquerading as outcome, sandbagging, missing baselines, too many KRs) +- **Tildelingsbrev translation** that separates what's actually an OKR candidate from what's a KPI, a compliance requirement, or a reporting routine +- **Cascade visualization** from organization strategy down to team OKR, with alignment gap detection +- **Meeting materials** for check-ins, reviews, workshops, and 1:1 conversations using the CFR framework -## What Is This? +## See It In Action -This plugin transforms Claude Code into a specialized OKR advisor that understands the unique constraints of Norwegian public sector organizations: +``` +> /okr:skriv We want to improve our digital services for driver's license renewals -- **8 commands** covering the complete OKR lifecycle -- **5 specialized agents** that activate automatically based on context -- **Government alignment** — translate tildelingsbrev into actionable OKR with audit-ready documentation -- **4-month tertial cycles** as the default cadence -- **CFR framework** (Conversations, Feedback, Recognition) for meaningful 1:1 conversations -- **Cascade visualization** showing alignment from organization level down to teams -- **Linear integration** for tracking OKR as issues with progress scoring +Which team is this for, and what cycle? +> Digital avdeling, T2-2026 -> [!TIP] -> Start with `/okr:oppsett` to configure your organization context, then use `/okr:skriv` to create your first OKR. +What's the current state — do you have baseline numbers? +> About 45% do it digitally. Average processing takes 14 business days. +> User satisfaction is 3.4 out of 5. ---- +─────────────────────────────────────────────────── + +OKR for Digital avdeling — T2-2026 + +Objective: Make driver's license renewal a frictionless experience + +Key Results: +1. Increase fully digital renewals from 45% to 75% + Measurement: Monthly report from case system + Type: Aspirational (target score: 0.7) + +2. Reduce average processing time from 14 to 5 business days + Measurement: Case management system + Type: Committed (target score: 1.0) + +3. Achieve user satisfaction of 4.2/5.0 (baseline: 3.4) + Measurement: Citizen survey, quarterly + Type: Aspirational (target score: 0.7) + +─────────────────────────────────────────────────── + +Shall I run a quality check on this? (/okr:kvalitet) +Or cascade it from an organization-level objective? (/okr:kaskade) +``` ## Quick Start -### Prerequisites - -- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed -- Optional: [Linear](https://linear.app) account for OKR tracking - -### Installation - -Add the marketplace and browse plugins with `/plugin`: +Add the marketplace: ```bash claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git @@ -76,204 +75,58 @@ Or enable directly in `~/.claude/settings.json`: } ``` -### First Conversation - -``` -> /okr:oppsett - -Welcome to the OKR plugin setup wizard. - -1. Which organization do you work for? -2. What cycle model do you use? (Tertial recommended) -3. Would you like to integrate with Linear? - -[Interactive configuration follows...] -``` - -After setup, try: - -``` -> /okr:skriv We want to improve digital services for citizens -``` - ---- +Then start with `/okr:oppsett` to configure your organization and cycle. ## Commands -### Writing & Quality - -| Command | Description | +| Command | What it does | |---------|-------------| -| `/okr:skriv` | Write new OKR with guided Objective and KR creation | -| `/okr:kvalitet` | Quality check OKR against rubric, detect antipatterns, suggest rewrites | +| `/okr:skriv` | Write new OKR — guided from vague idea to scored output | +| `/okr:kvalitet` | Score existing OKR against rubric, detect antipatterns, suggest rewrites | +| `/okr:kaskade` | Cascade from organization to team, visualize alignment | +| `/okr:sporing` | Track progress scores (0.0-1.0), generate check-in reports | +| `/okr:møter` | Generate agendas for workshops, check-ins, reviews, and 1:1s | +| `/okr:innføring` | Plan OKR rollout, handle resistance, assess maturity | +| `/okr:governance` | Translate tildelingsbrev to OKR, Riksrevisjon-ready documentation | +| `/okr:oppsett` | Configure organization, cycle, and Linear integration | -### Alignment & Tracking +## How It Works -| Command | Description | -|---------|-------------| -| `/okr:kaskade` | Cascade OKR from organization to team, visualize alignment | -| `/okr:sporing` | Track progress, calculate scores (0.0-1.0), generate check-in reports | +Under the hood, the plugin uses 5 specialized agents, 3 context-aware hooks, and a knowledge base of 15 reference documents covering methodology, governance, antipatterns, meeting formats, and sector-specific metrics. -### Meetings & Change Management +Configuration is stored in `.claude/okr.local.md` in your project directory (gitignored). A hook automatically injects your org context into every conversation, so the plugin remembers your organization, cycle, and team structure across sessions. -| Command | Description | -|---------|-------------| -| `/okr:møter` | Plan OKR workshops, check-ins, reviews, and 1:1 conversations | -| `/okr:innføring` | OKR rollout planning, resistance handling, maturity assessment | - -### Governance & Setup - -| Command | Description | -|---------|-------------| -| `/okr:governance` | Translate tildelingsbrev to OKR, Riksrevisjon compliance | -| `/okr:oppsett` | Interactive setup wizard for organization, cycle, integrations | - ---- - -## Agents - -5 specialized agents activate automatically based on user intent: - -| Agent | Model | Role | -|-------|-------|------| -| kvalitetssjekker | Sonnet | Score OKR quality (1-10), detect 19 antipatterns | -| kaskadebygger | Sonnet | Build cascades between org levels, find alignment gaps | -| fremdriftssporer | Sonnet | Calculate progress scores, forecast completion | -| møtefasilitator | Sonnet | Generate meeting agendas and facilitation materials | -| styringsrådgiver | Opus | Tildelingsbrev analysis, governance, audit compliance | - ---- - -## Hooks - -| Event | Type | Purpose | -|-------|------|---------| -| UserPromptSubmit | command | Auto-inject org/cycle context from `.claude/okr.local.md` | -| PreCompact | prompt | Preserve OKR draft state during context compaction | -| Stop | prompt | Remind user to save OKR work to tracking system | - ---- - -## Knowledge Base - -15 reference files organized in `skills/okr-offentlig-sektor/references/`: - -| File | Content | -|------|---------| -| `okr-framework.md` | Core methodology, scoring, cycle management | -| `okr-examples.md` | Good and bad examples from public sector | -| `okr-antipatterns.md` | 19 common OKR mistakes across 5 categories | -| `okr-offentlig-governance.md` | Tildelingsbrev, political steering, audit compliance | -| `okr-implementation.md` | Rollout methodology and change management | -| `okr-integrations.md` | OKR + Scrum/Kanban/SAFe integration | -| `cfr-framework.md` | CFR methodology and 1:1 templates | -| `meeting-guides.md` | Agendas for all OKR meeting types | -| `metrics-library.md` | Common KPIs for transport/roads/digital | -| `okr-calculator.md` | Progress calculation and confidence assessment | -| `okr-arshjul.md` | Annual cycle and budget synchronization | -| `okr-sources.md` | Bibliographic evidence base | -| `okr-cheatsheet.md` | One-page OKR best practices | -| `okr-oboard-guide.md` | Oboard tool guide | -| `individual-vs-team-okr.md` | Team vs individual OKR rationale | - ---- - -## Workflow Examples - -### New Team Starting OKR - -``` -/okr:oppsett # Configure organization and cycle -/okr:skriv # Write first OKR set -/okr:kvalitet # Quality check and improve -/okr:kaskade # Verify alignment with organization objectives -``` - -### Mid-Cycle Check-In - -``` -/okr:sporing # Update scores, get confidence assessment -/okr:møter # Generate check-in meeting agenda -``` - -### Government Mandate Translation - -``` -/okr:governance # Translate tildelingsbrev to OKR -/okr:kvalitet # Verify quality of generated OKR -/okr:kaskade # Cascade to team level -``` - ---- +Linear integration is optional — enable it through `/okr:oppsett` to track OKR progress as issues with score updates. ## Public Sector Features -### Governance Integration +| Framework | What the plugin does | +|-----------|---------------------| +| Tildelingsbrev | Parse requirements, separate OKR candidates from KPIs and compliance items | +| Riksrevisjonen | Generate documentation with baseline, target, data source, and audit trail | +| Political steering | Handle mid-cycle priority changes with documented rationale | +| NTP / Stortingsmelding | Cascade from national policy down to team-level OKR | -| Framework | Plugin Support | -|-----------|---------------| -| Tildelingsbrev | Translate requirements to OKR with audit trail | -| Riksrevisjonen | Documentation templates with baseline, target, data source | -| Political steering | Handle mid-cycle priority changes with rationale | -| NTP / Stortingsmelding | Cascade from national policy to team OKR | +## When Not to Use This -### CFR Framework - -Integrated Conversations, Feedback, Recognition methodology: -- **Conversations** — Structured 1:1 templates -- **Feedback** — Continuous two-way feedback -- **Recognition** — Techniques adapted for public sector (no bonus-linking) - ---- - -## Configuration - -Run `/okr:oppsett` for interactive setup. Configuration is saved to `.claude/okr.local.md` in your project directory (gitignored). - -The UserPromptSubmit hook automatically injects your org context into every session when configured. - -### Configuration Template - -See `templates/okr.local.md.template` for the full template. - ---- - -## Integrations - -### Linear - -OKR tracking via Linear MCP when configured through `/okr:oppsett`: -- Progress score updates via comments -- Status field tracking -- Team and project organization - -### Agile Frameworks - -Knowledge base includes integration patterns for Scrum, Kanban, SAFe, and project portfolio management. See `references/okr-integrations.md`. - ---- +- **Private sector** — the governance model, examples, and cycle structure are built for Norwegian public sector +- **Individual performance reviews** — OKR is a team tool; this plugin explicitly discourages individual OKR +- **Project management** — OKR sets direction, it doesn't replace your backlog or Gantt chart +- **First week of OKR** — start with a workshop and post-its, not a plugin; come back when you have your first draft ## Limitations -- Never tested in a real OKR cycle beyond the author's organization +- Not tested in a real OKR cycle beyond the author's organization - No automated tests -- Windows: not tested -- Norwegian public sector context only — may not fit private sector or other countries +- Norwegian public sector context only - Linear is the only supported tracking integration +- Windows: not tested --- -## Version History +![Version](https://img.shields.io/badge/version-1.0.0-blue) +![Commands](https://img.shields.io/badge/commands-8-blue) +![Agents](https://img.shields.io/badge/agents-5-orange) +![License](https://img.shields.io/badge/license-MIT-lightgrey) -See [CHANGELOG.md](CHANGELOG.md) for full details. - -| Version | Date | Highlights | -|---------|------|------------| -| **1.0.0** | 2026-04-08 | Architecture overhaul: self-contained commands, hooks, model optimization, marketplace-ready | -| 0.5.0 | 2026-02-07 | First formal version | - ---- - -## License - -[MIT](LICENSE) +See [CHANGELOG.md](CHANGELOG.md) for version history. [MIT License](LICENSE).