Update to okrdev

{
  "description": "Install, upgrade, or level-up okrdev in the current repo. Walks the adoption ladder — Level 0 parking lot, Level 1 method, Level 2 collaboration rails, optional stack module — creating okrdev/ files from templates, appending the marked coach block to the host agent's instructions file (CLAUDE.md or AGENTS.md), and merging (never overwriting) anything that already exists. Use when someone says \"install okrdev\", \"set up okrdev\", \"add okrdev to this repo\", \"upgrade okrdev\", \"move us to Level 1/2\", or asks how to get started with okrdev.",
  "included_files": [],
  "name": "install",
  "skill_md_contents": "---\nname: install\ndescription: Install, upgrade, or level-up okrdev in the current repo. Walks the adoption ladder — Level 0 parking lot, Level 1 method, Level 2 collaboration rails, optional stack module — creating okrdev/ files from templates, appending the marked coach block to the host agent's instructions file (CLAUDE.md or AGENTS.md), and merging (never overwriting) anything that already exists. Use when someone says \"install okrdev\", \"set up okrdev\", \"add okrdev to this repo\", \"upgrade okrdev\", \"move us to Level 1/2\", or asks how to get started with okrdev.\n---\n\n# Install okrdev\n\nYou are installing okrdev into the repo the user is working in (the \"target repo\"). Paths\nstarting with `templates/` refer to files shipped with this plugin; every other path is\nrelative to the target repo root. If you can't locate the plugin's templates directory (skills\ncopied without templates, or a surface that can't reach plugin files), don't stop: recreate the\nfiles from the canonical formats embedded in the skills and docs — the parking-lot format in\n`/okrdev:park`, the check-in skeleton in `/okrdev:checkin`, the config frontmatter in step 4\nbelow, and the coach blocks quoted in this file.\n\nTwo rules govern everything below:\n\n- **Start at the lowest level that delivers value.** Level 0 works standalone and takes ten\n  minutes. Never install a level the user didn't ask for — unused ceremony is how frameworks\n  get deleted by week three.\n- **Never overwrite an existing file.** Every collision gets a proposed merge and a question,\n  not a silent clobber.\n\n## Procedure\n\n1. **Detect state.** In the target repo, check:\n   - Is this a git repo? (`git rev-parse --is-inside-work-tree`)\n   - Does `okrdev/` exist? Does `okrdev/config.md` carry `okrdev_version` in its frontmatter?\n   - **Which file does the host agent read?** `CLAUDE.md` on Claude Code, `AGENTS.md` on\n     Codex. This is the *only* platform-specific thing about an okrdev install — the coach\n     block itself carries no platform tokens, so nothing else forks. Resolve it in this order,\n     and stop at the first hit:\n     1. **Existing markers win.** If either file already contains `<!-- okrdev:start -->`,\n        that file is the destination, whatever the host. A repo that was installed from one\n        agent and is now being upgraded from another must not sprout a second block.\n     2. Otherwise, the host you are running in.\n     3. If you genuinely cannot tell, ask — one question, with the default named.\n   - Does that file contain `<!-- okrdev:start -->`?\n   - **Do *both* `CLAUDE.md` and `AGENTS.md` carry the markers?** They should never. If they\n     do, say so and stop: two coach blocks drift, and the repo needs a human to say which one\n     is real. Offer to delete the other after they choose.\n   - Do `.github/pull_request_template.md`, `.github/CODEOWNERS`, or\n     `.github/workflows/okr-gate.yml` already exist?\n\n   Classify the state:\n   - **Fresh** — no okrdev traces. Continue at step 2.\n   - **Partial** — some okrdev files but no version marker (hand-rolled or interrupted\n     install). Fill the gaps using the steps below, skip anything that exists, and add the\n     version marker and any missing frontmatter keys to `okrdev/config.md`.\n   - **Existing** — version marker present. If the user wants a *higher level*, run only the\n     steps for the new level and update `level:` in `okrdev/config.md`. Otherwise treat it as\n     an upgrade — see \"Upgrading\" below.\n\n2. **Not a git repo?** Offer to `git init`. okrdev's storage is git-native — versioned,\n   reviewable by PR, greppable by agents — so a repo is required. If this is not a software\n   business, say plainly: the repo can contain nothing but `okrdev/`; it's just the ledger.\n   Details in `docs/adoption.md`.\n\n3. **Walk the ladder.** Present it and ask where to start. Default to Level 0 unless the user\n   clearly wants more. Each level assumes the ones below it.\n\n   | Level | What it adds | Time |\n   |-------|--------------|------|\n   | 0 — Parking lot | Idea capture + weekly triage. Nothing else. | 10 minutes |\n   | 1 — The method | Mission, cycle OKRs, check-ins, retros. | One planning session |\n   | 2 — Collaboration rails | `KR:` tags on PRs, okr-gate, CODEOWNERS, branch protection. | An afternoon |\n   | Stack module | Vercel + Neon AI-first environment. | A day. Greenfield only |\n\n   If the user is unsure, recommend Level 0 or 1: Level 0 to feel the capture habit first,\n   Level 1 if they already want objectives this week. Do not pitch Level 2 or the stack —\n   answer if asked.\n\n   One piece of advice applies at every level: protect the default branch — PR required\n   before merge, squash-only, no force pushes. That's repo best practice, not a Level 2\n   commitment, and okrdev runs happily behind it: captures become issues (no commits at\n   all), and batched state writes become roughly one small state PR a week instead of a\n   direct commit. Be honest about the plan wall: on private repos, branch protection needs\n   a paid GitHub plan; public repos get it free.\n\n4. **Level 0 — parking lot.**\n   - Create `okrdev/config.md` from `templates/okrdev/config.md`. Set `level: 0`. Ask one\n     question: who is the backstop — the human to call when the DRI and the coach are both\n     stuck? Leave the other frontmatter defaults (`cycle_length: quarterly`,\n     `checkin_cadence: weekly`, `side_quest_box_hours_per_week: 4`, `strict_gate: false`)\n     in place. They're inert at Level 0, but keeping them means moving up later is a flip of\n     `level:`, not a re-interview.\n   - Create `okrdev/PARKING_LOT.md` from `templates/okrdev/PARKING_LOT.md`.\n   - When `gh` is authed and the repo's remote is GitHub, fold one opt-out into the backstop\n     question — \"I'll also add the `okrdev:parked` label so ideas can be parked as issues,\n     unless you'd rather not\" — then create it:\n     `gh label create okrdev:parked --color F9D71C --description \"okrdev parking-lot inbox — triaged weekly, then closed\"`.\n     That gives `/okrdev:park` its primary path: zero commits, and capture from a phone or by\n     a collaborator straight from the GitHub UI, no Claude session needed. No `gh`, no\n     remote, or the remote isn't GitHub? Skip silently — the Captured section works\n     everywhere. This applies at every level; don't make it a ceremony of its own.\n   - Add the **minimal Level 0 coach block** to the instructions file resolved in step 1,\n     following the collision rules in step 8. Use exactly this text:\n\n     ```markdown\n     <!-- okrdev:start -->\n     ## okrdev coach\n\n     This repo runs okrdev at Level 0 — parking lot only (see `okrdev/config.md`). No active\n     cycle yet.\n\n     Rules for every session:\n\n     1. **Park new ideas by default.** A mid-session idea gets captured in ten seconds as an\n        `okrdev:parked` issue — or one line in the Captured section of\n        `okrdev/PARKING_LOT.md` (date, idea, who, energy high/med/low, effort S/M/L) when\n        offline or the remote isn't GitHub. Then back to what you were doing.\n     2. **Nothing parked — issue or Captured line — gets worked on.** Ever. Triage first\n        (`/okrdev:triage`): promote, archive, or time-box it as a side-quest.\n     3. **Side-quests get a time-box before they start**, logged in the Side quests section\n        of the parking lot.\n     4. When the team is ready to set objectives, suggest `/okrdev:install` to move to\n        Level 1, then `/okrdev:plan`. Installing Level 1 replaces this block.\n     <!-- okrdev:end -->\n     ```\n\n5. **Level 1 — the method.** Everything from Level 0 (create whatever is missing), plus:\n   - `okrdev/MISSION.md` from `templates/okrdev/MISSION.md` — and don't leave it as\n     placeholder text. Draft it with the human now, in three questions: what does this\n     business or project exist to do? What's the current strategy, in a paragraph?\n     Optionally, what are the 2–3 strategic bets this year? Keep it short. Planning reads\n     this file first, and the coach can't answer \"aligned to what?\" without it.\n   - `okrdev/LESSONS.md` from `templates/okrdev/LESSONS.md`. It starts empty; retros append.\n   - Replace the coach block content between the markers with the full canonical block from\n     `templates/CLAUDE-okrdev.md`, verbatim.\n   - In `okrdev/config.md`: set `level: 1`; ask about `cycle_length` — quarterly is the\n     default and fits most businesses; six-week suits AI-speed projects that would go stale\n     waiting a quarter.\n   - Do **not** create a cycle file. That's `/okrdev:plan`'s job, and it deserves a real\n     planning session, not the tail end of an install.\n\n6. **Brownfield scan (offer it whenever the target repo has an existing codebase).** Offer to\n   scan the repo so planning starts from a straw man instead of a blank page:\n   - Read the README and any docs or roadmap files.\n   - `git log --oneline --since=\"90 days ago\"` for the actual workstreams.\n   - `gh issue list --state open` when `gh` is available.\n\n   Summarize in chat: what the product appears to do, where recent effort went, recurring\n   pain. Offer to park any concrete ideas the scan surfaced (one `okrdev:parked` issue each,\n   or one line each into the Captured section of `okrdev/PARKING_LOT.md` when there's no\n   GitHub remote). Then suggest running `/okrdev:plan` while the\n   findings are fresh. Planning goes faster as an argument with a draft than as a staring\n   contest with an empty page.\n\n7. **Level 2 — collaboration rails.** Requires Level 1: the rails tag work against KRs, so\n   the KRs have to exist first. Each item is a **separate, explicit opt-in question** — never\n   bundle them, never install one uninvited:\n\n   a. **PR template** → copy `templates/github/pull_request_template.md` to\n      `.github/pull_request_template.md`. If one already exists, show a proposed merge —\n      their sections plus the `KR:` line, the how-to-verify section, and the risk\n      checklist — and ask before writing.\n   b. **okr-gate** → copy `templates/github/workflows/okr-gate.yml` to\n      `.github/workflows/okr-gate.yml`. Explain what they're opting into: warn-by-default —\n      a comment and a `needs-kr` label on PRs missing a `KR:` line, never a blocked merge.\n      Strict mode is a separate later opt-in (a repo variable), and even then a\n      human-applied `okr-override` label passes the gate; the coach logs its use. Nothing\n      in okrdev is human-unoverridable.\n   c. **CODEOWNERS** → copy `templates/github/CODEOWNERS` to `.github/CODEOWNERS`, then\n      replace the placeholder reviewers with real usernames for the risky paths this repo\n      actually has (migrations, auth config, payment code). If a CODEOWNERS exists, propose\n      a merge and ask.\n   d. **Branch protection** → offer to run `templates/stack/branch-protection.sh` (requires\n      an authed `gh`). If asked how okrdev's own writes survive a protected main: state PRs\n      are the standard path — the coach batches ledger writes by ritual and opens one small\n      PR per triage or check-in, merged immediately. The script keeps an actor-bypass as an\n      opt-in convenience, commented out by default; it is not the assumed setup. Be honest\n      about plan requirements: on private repos, branch protection and CODEOWNERS\n      enforcement need a paid GitHub plan; public repos get them free. If the plan can't\n      support it, install CODEOWNERS anyway — it still routes review requests — and state\n      exactly what's missing teeth.\n\n   Set `level: 2` in `okrdev/config.md`. Ask about `strict_gate` but recommend leaving it\n   `false` until the team has lived with warn mode for a full cycle. If they ever flip it to\n   `true`, set both halves together: the config key (the recorded decision) and the repo\n   variable that actually controls the gate — `gh variable set OKRDEV_STRICT_GATE --body true`.\n   One without the other is a gate that says one thing and does another.\n\n8. **Instructions-file collision rules** (apply at every level). \"The instructions file\" is\n   the one resolved in step 1 — `CLAUDE.md` or `AGENTS.md`, never both:\n   - File doesn't exist → create one containing just the coach block.\n   - File exists without the markers → append the block at the end, between\n     `<!-- okrdev:start -->` and `<!-- okrdev:end -->`. Touch nothing else — the rest of the\n     file is the user's.\n   - Markers already present → replace only the content between them. This is how level\n     changes and upgrades apply cleanly, and how uninstall stays a deletion instead of an\n     archaeology project.\n   - **Never write both files.** One install, one instructions file. Writing both doubles the\n     footprint and creates two copies of the block free to drift apart — which is exactly how\n     this repo's own coach block sat a revision behind its template for a month. If the host\n     changed since the last install, *move* the block: write the new file, delete the markers\n     and the block from the old one, and say what you did.\n   - **Never write the other agent's file to be helpful.** A Codex user does not want a\n     `CLAUDE.md` appearing in their repo, and the reverse is equally true. If they want both,\n     the bridge is theirs to make — Claude Code documents an `@AGENTS.md` import line for\n     exactly this, and it belongs in their file, not in okrdev's write.\n\n9. **Stack module.** Offer it **only** if the repo is greenfield (empty or brand-new) or the\n   user explicitly asks. It is never a prerequisite for anything else — if asked, say so\n   directly: the method runs on any stack. When wanted, point at `templates/stack/README.md`\n   for the step-by-step and `docs/stack.md` for what each piece is and why. It's a day of\n   setup; don't start it inside the install conversation unless the user wants to keep going.\n\n10. **Commit.**\n    - Levels 0–1 on an unprotected default branch: one direct commit, e.g.\n      `chore: install okrdev (level 1)`. The install is additive and the ten-minute promise\n      dies waiting on review. On a protected default branch: a short-lived branch and a\n      small PR titled `okrdev: install (level <n>)`, merged immediately\n      (`gh pr merge --squash`) — about a minute, and the standard path for okrdev writes on\n      protected repos anyway.\n    - Level 2 files under `.github/` change everyone's workflow: open a PR unless the user\n      says commit direct. Narrate for non-technical users: \"I'm opening a pull request —\n      that's a proposal page with a link you can click.\"\n\n11. **Close.** Confirm in a few lines what was installed and at what level. Then propose the\n    next step:\n    - Level 0 → try it immediately: \"`/okrdev:park` your next idea.\"\n    - Level 1 → schedule `/okrdev:plan` (about 90 minutes) to draft the first cycle. There\n      is no active cycle until plan runs — that's expected, not a gap.\n    - Any level → mention `/okrdev:coach` as the anytime entry point for status and\n      \"is this aligned?\" questions.\n\n## Upgrading an existing install\n\n1. Read `okrdev_version` from `okrdev/config.md` frontmatter and compare it with this\n   plugin's version in `.claude-plugin/plugin.json`.\n2. **If nothing template-derived changed between those two versions, say so and stop.** Since\n   2026-08-08 every shipped change bumps the version, including docs-only ones — so a release\n   with no scaffolding in it is now normal, not a mistake. Report it in one line (\"0.7.0 is\n   out; it changed docs only, nothing to apply here\") and offer to move the marker. Do **not**\n   present an empty diff and do not walk the file list to prove there was nothing: an upgrade\n   prompt that is usually empty is a prompt people stop reading, which is precisely why the\n   old rule exempted docs and why dropping that exemption had to come with this behaviour.\n3. Diff **only template-derived content**: the coach block between the markers in the\n   instructions file, any `.github/` files okrdev installed, and `okrdev/config.md` frontmatter\n   keys (new keys get proposed with their defaults). New capabilities get offered the same\n   folded-in way — e.g. the `okrdev:parked` capture label (step 4) when the repo is on GitHub\n   and the label doesn't exist yet.\n4. Never touch user data: `MISSION.md` content, cycle files in `okrdev/okrs/`, check-ins,\n   `PARKING_LOT.md` entries, `LESSONS.md`. Those are the team's records, not okrdev's.\n5. Show the proposed diffs, apply what's approved, bump `okrdev_version`.\n\n## Uninstall (if asked)\n\nDelete `okrdev/`, remove the coach block including its markers — check **both** `CLAUDE.md`\nand `AGENTS.md` regardless of the host you are running in, because the install may have been\ndone from the other one — delete the\n`okrdev:parked` label (closing any still-open parked issues with a note), and optionally\ndelete `.github/pull_request_template.md`, `.github/workflows/okr-gate.yml`, and\n`.github/CODEOWNERS` if okrdev installed them. That's the entire footprint — \"removable\" is\na procedure here, not an adjective. Full procedure in `docs/adoption.md`.\n"
}