@olegkoval/agent-skills 1.33.0 → 1.35.0

package/{packages/wearables/garmin-watchface/adapters/grok → adapters/claude/olko-garmin-kit}/skills/garmin-watchface/scripts/ciq-mock

@@ -4,7 +4,7 @@ against what the watch can actually draw.
 
     ciq-mock out.html a.svg b.svg c.svg
     ciq-mock out.html *.svg --device fenix6pro
-    ciq-mock out.html a.svg --strict          # exit 1 on unsupported/bezel findings only
+    ciq-mock out.html a.svg --strict          # exit 1 on any infidelity
 
 Why this exists
 ---------------
@@ -99,10 +99,6 @@ BANNED_ATTRS = {
     "stroke-opacity": "alphaBlendingSupport is false -- renders fully opaque",
     "stroke-dasharray": "no dash support; draw the segments",
     "filter": "no filter primitives",
-}
-
-# Non-blocking attributes that need guidance but don't fail --strict.
-GUIDANCE_ATTRS = {
     "transform": "fine in the mock, but every rotation must be precomputed in "
                  "Monkey C -- one sin/cos pair per polygon, not per vertex",
 }
@@ -114,7 +110,7 @@ MIN_STROKE = 2
 # ---------------------------------------------------------------- colour ----
 
 def parse_colour(text):
-    """-> (r, g, b) or None when unparseable/none, or "alpha" when alpha-bearing."""
+    """-> (r, g, b) or None when unparseable/none."""
     if not text:
         return None
     t = text.strip().lower()
@@ -122,13 +118,6 @@ def parse_colour(text):
         return None
     if t in NAMED:
         return NAMED[t]
-    # 4-digit or 8-digit hex with alpha
-    m = re.fullmatch(r"#([0-9a-f]{4})", t)
-    if m:
-        return "alpha"
-    m = re.fullmatch(r"#([0-9a-f]{8})", t)
-    if m:
-        return "alpha"
     m = re.fullmatch(r"#([0-9a-f]{3})", t)
     if m:
         return tuple(int(c * 2, 16) for c in m.group(1))
@@ -139,9 +128,6 @@ def parse_colour(text):
     m = re.fullmatch(r"rgba?\(([^)]*)\)", t)
     if m:
         parts = [p.strip() for p in m.group(1).replace("/", ",").split(",")]
-        # If there's a 4th component (alpha), flag it
-        if len(parts) >= 4:
-            return "alpha"
         try:
             return tuple(int(round(float(p.rstrip("%")) * (2.55 if "%" in p else 1)))
                          for p in parts[:3])
@@ -200,8 +186,8 @@ def device_size(device):
     j = json.loads(path.read_text())
     res = j.get("resolution") or j.get("display") or {}
     w, h = res.get("width"), res.get("height")
-    if not w or not h:
-        sys.exit(f"{path} declares no resolution (width or height missing).")
+    if not w:
+        sys.exit(f"{path} declares no resolution.")
     return int(w), int(h)
 
 
@@ -289,19 +275,11 @@ def audit(root, size, round_screen):
             if attr in declared and declared[attr] not in ("1", "1.0", "none"):
                 findings.append(("unsupported", f"{tag} {attr}=\"{declared[attr]}\": {why}"))
 
-        for attr, why in GUIDANCE_ATTRS.items():
-            if attr in declared and declared[attr] not in ("1", "1.0", "none"):
-                findings.append(("limit", f"{tag} {attr}=\"{declared[attr]}\": {why}"))
-
         for attr in COLOUR_ATTRS:
             raw = declared.get(attr)
             if raw is None:
                 continue
             rgb = parse_colour(raw)
-            if rgb == "alpha":
-                findings.append(("unsupported", f"{tag} {attr}=\"{raw}\": alpha channel "
-                                               "not supported (alphaBlendingSupport is false)"))
-                continue
             if rgb is None:
                 if raw.strip().lower() not in ("none", "transparent", "inherit",
                                                "currentcolor"):
@@ -313,11 +291,7 @@ def audit(root, size, round_screen):
         sw = declared.get("stroke-width")
         if sw is not None and declared.get("stroke", "none") != "none":
             try:
-                # Strip "px" suffix if present
-                sw_str = str(sw).strip()
-                if sw_str.endswith("px"):
-                    sw_str = sw_str[:-2].strip()
-                if float(sw_str) < MIN_STROKE:
+                if float(sw) < MIN_STROKE:
                     findings.append(("stroke", f"{tag} stroke-width={sw}: below {MIN_STROKE}px "
                                                "breaks up with no anti-aliasing"))
             except ValueError:
@@ -400,13 +374,13 @@ document.querySelector('#dim').addEventListener('click', function () {
 """
 
 
-def card(name, markup, w, h, findings, colours, round_screen, card_index):
+def card(name, markup, w, h, findings, colours, round_screen):
     clip = ""
     if round_screen:
-        clip = (f'<defs><clipPath id="glass_{card_index}">'
+        clip = (f'<defs><clipPath id="glass_{abs(hash(name))}">'
                 f'<circle cx="{w/2}" cy="{h/2}" r="{min(w, h)/2}"/>'
                 f"</clipPath></defs>")
-        markup = f'<g clip-path="url(#glass_{card_index})">{markup}</g>'
+        markup = f'<g clip-path="url(#glass_{abs(hash(name))})">{markup}</g>'
 
     swatches = "".join(
         f'<div class="sw" style="background:{hexof(quantize(c))}" '
@@ -445,8 +419,7 @@ def main():
     ap.add_argument("--no-quantize", action="store_true",
                     help="render the colours as written (dishonest; for comparison only)")
     ap.add_argument("--strict", action="store_true",
-                    help="exit 1 if any variant has unsupported-feature or bezel findings "
-                         "(path/text limits are non-blocking)")
+                    help="exit 1 if any variant has an unsupported/bezel finding")
     args = ap.parse_args()
 
     if args.device:
@@ -456,7 +429,7 @@ def main():
     round_screen = (not args.rect) and w == h
 
     cards, blocking = [], 0
-    for idx, name in enumerate(args.svg):
+    for name in args.svg:
         path = Path(name)
         if not path.is_file():
             sys.exit(f"No such file: {path}")
@@ -466,7 +439,7 @@ def main():
             root = apply_quantize(root)
         blocking += sum(1 for kind, _ in findings if kind in ("unsupported", "bezel"))
         cards.append(card(path.stem, inner_markup(root), w, h,
-                          findings, colours, round_screen, idx))
+                          findings, colours, round_screen))
 
         print(f"{path.stem}: {len(findings)} finding(s)")
         for kind, msg in findings:

package/adapters/claude/olko-git-tools/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-git-tools",
+  "description": "Everyday git and GitHub CLI operations: conventional commits, branch hygiene.",
+  "skills": "./skills"
+}

package/adapters/claude/olko-github-pr/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-github-pr",
+  "description": "Drive GitHub pull requests to merge-ready: review-bot loops, CI fixes, descriptions, dependency triage.",
+  "skills": "./skills"
+}

package/adapters/claude/olko-obsidian/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-obsidian",
+  "description": "Keep an Obsidian vault in sync with work: PR sync, task rollover, morning routine.",
+  "skills": "./skills"
+}

package/adapters/claude/olko-product/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-product",
+  "description": "Take a product idea to a shippable build: MVP passes, full-stack scaffolds, launch plans.",
+  "skills": "./skills"
+}

package/adapters/claude/olko-reflection/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-reflection",
+  "description": "Look back and improve: self-critique, retrospectives, performance review, rapid learning.",
+  "skills": "./skills"
+}

package/adapters/claude/olko-reflection/skills/retro-analysis/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: retro-analysis
+description: Produce a recurring engineering retrospective from repository history, delivery evidence, work patterns, code-quality signals, and prior snapshots, with repository, comparison, and cross-project modes.
+license: MIT
+metadata:
+  author: Oleg Koval
+  tags:
+    - retrospective
+    - metrics
+    - git
+    - productivity
+    - code-quality
+    - trends
+    - planning
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Retro Analysis
+
+Run a factual engineering retrospective over a defined time window. The purpose is to explain what changed, how the work happened, what quality signals say, what was learned, and what should improve next. This is an analysis workflow, not a performance-ranking or blame exercise.
+
+Use it manually at the end of a day, week, sprint, or release; on a recurring schedule; or when asked what was shipped, where time went, or how delivery quality is trending. When a specific implementation has just reached its goal, run this analysis before or alongside `olko:wrap-up` so the delivery audit and the broader retrospective remain distinct.
+
+## Invocation
+
+Accept one of these arguments:
+
+- no argument or `7d`: the previous seven calendar days
+- `24h`: the previous 24 hours
+- `14d` or `30d`: the previous N calendar days
+- `compare` or `compare 14d`: compare the selected window with the immediately preceding window of equal length
+- `global`, `global 14d`: aggregate across discoverable repositories and agent sessions
+
+If the argument is invalid, print the accepted forms and stop. Do not silently choose a different window.
+
+Calendar windows are aligned to midnight in the operator's local timezone. A short hourly window may use a relative timestamp. State the resolved start, end, timezone, scope, and comparison window at the beginning of the report.
+
+## Safety and evidence rules
+
+- Be read-only by default. Do not push, merge, deploy, close issues, edit source, or rewrite history.
+- A local retro may write one task-owned snapshot under `.context/retros/` when that directory exists or when persistence is explicitly requested. Never overwrite an existing snapshot; use a date and window-specific filename.
+- Do not fetch or refresh remote refs unless the user or the surrounding workflow authorized that read-side state change. If refs may be stale, say so and use the available evidence.
+- Preserve dirty work, untracked files, existing snapshots, credentials, and unrelated temporary artifacts.
+- Never infer delivery from a local commit. Treat local Git, remote/PR state, CI, deployment, and device or human QA as separate evidence gates.
+- Do not expose secrets, tokens, private prompts, or raw session content. Use aggregate counts and redacted references only.
+- Missing data is `UNKNOWN`, not zero. Distinguish “none found” from “not available”.
+- Do not turn commit count, lines changed, hours, or AI-assisted activity into a simplistic productivity score. Use them as context for the narrative.
+
+## 1. Establish scope and baseline
+
+For repository mode:
+
+1. Identify the repository, current branch, `HEAD`, configured author, base branch, and working-tree state.
+2. Preserve and report pre-existing dirty paths; do not include their changes as delivered work unless the evidence links them to the window.
+3. Use the repository's local timezone for calendar boundaries. Use UTC timestamps in stored machine-readable data.
+4. Read only relevant project documentation and task artifacts needed to interpret the changes. Do not invent milestones, objectives, or acceptance criteria.
+5. Locate prior snapshots in `.context/retros/` and load the immediately preceding comparable snapshot when available.
+
+For global mode:
+
+1. Discover repositories from the configured workspace locations or an existing discovery tool. If discovery is unavailable, report that limitation and continue with explicitly supplied paths.
+2. For each repository, collect the same bounded evidence as repository mode and skip missing, inaccessible, or non-Git directories.
+3. Optionally include available agent/session summaries or tool telemetry, but only as aggregate, redacted evidence. Do not require a specific agent vendor, plugin, or telemetry format.
+4. Keep per-project results separate before producing cross-project totals. Never hide a repository-level failure in an aggregate.
+
+## 2. Collect raw evidence
+
+Capture enough raw data to reproduce the analysis. Prefer stable Git/provider CLIs already present in the environment. Save only the normalized snapshot unless raw artifacts were explicitly requested.
+
+### Repository history
+
+Collect, bounded to the resolved window and scope:
+
+- commit hash, author, timestamp, subject, body, and parent information
+- insertions, deletions, files changed, and test-file versus production-file changes
+- commit type signals from Conventional Commit prefixes, labels, or equivalent repository conventions
+- pull request or merge request references present in commits, and provider state when a provider CLI is available
+- changed-file frequency, churn, and hotspots; distinguish generated, vendored, lockfile, and source files when possible
+- per-author commit and file ownership signals, including co-authors and AI-assisted markers only when explicitly present
+
+Use `git log --shortstat` or equivalent for commit-level change counts and `git diff --numstat` or equivalent for test/source proportions. If a command cannot run, record the command and reason; do not substitute invented values.
+
+### Delivery and quality signals
+
+Inspect only signals that exist in the repository or authorized provider tooling:
+
+- branch and remote tracking state, current PR title/body, review state, and current-head checks
+- test files, test commands, recent test-related commits, and known failing or skipped checks
+- changelog, release notes, issue/task references, and plan artifacts when present
+- TODO/backlog markers when a project-maintained backlog exists
+- regression fixes, reverted changes, follow-up fixes, and repeated failure patterns
+- optional review or static-analysis summaries, clearly labeling unavailable or rate-limited providers
+
+Never call an absent test suite “healthy”; report `NOT_AVAILABLE`. Never call a skipped check green.
+
+### Work-pattern signals
+
+When timestamps are available:
+
+- build an hour-of-day histogram in local time
+- group commits or activity into sessions separated by at least 45 minutes of inactivity
+- classify sessions as deep (3+ hours), medium (1–3 hours), or micro (<1 hour)
+- count active days, longest streak, and context switches between repositories or work areas
+
+Treat commit timestamps as a proxy, not proof of keyboard time. If session telemetry exists, prefer it and name the source.
+
+## 3. Compute the analysis
+
+Use the evidence to calculate, or explicitly mark unavailable, the following dimensions:
+
+### Shipping and scope
+
+- features, fixes, refactors, docs, tests, chores, and releases shipped
+- commits, weighted commits, active days, contributors, and referenced PRs
+- version range or release identifiers when the repository exposes them
+- logical lines changed and raw lines changed, reported separately
+- plan or objective items completed, deferred, or still open when a plan is available
+
+### Quality and maintainability
+
+- test lines or test files changed relative to production changes
+- test commands run and their current result
+- regressions, reverts, repeated fixes, and hotspots with high churn
+- type, lint, build, security, review, and release signals when available
+- backlog/TODO health only when there is a maintained source to inspect
+
+Do not reward large diffs or penalize small ones without explaining their context. A small change that closes a high-value objective can be the most important shipment.
+
+### Focus and delivery flow
+
+- commit-type mix and fix ratio; flag a high fix ratio as a signal for investigation, not a diagnosis
+- PR/MR size buckets and time-to-merge when provider data is available
+- work sessions, time-of-day distribution, context switching, and focus patterns
+- planned versus unplanned work, if the plan and change evidence support the comparison
+- the single most consequential shipment or decision, with evidence and caveats
+
+### People and collaboration
+
+For multi-author work, provide a factual per-author view of commits, change volume, areas touched, review or PR participation, and notable contributions. Include a team view of ownership concentration, cross-review, handoffs, and shared hotspots. Avoid ranking people by raw LOC or commit count.
+
+Use the configured Git author as the personal focus only when it is unambiguous. Otherwise produce a team report and state that no personal identity was selected.
+
+## 4. Compare and track trends
+
+For `compare` or any window with a prior snapshot:
+
+- compare features/fixes, commits, active days, contributors, PRs, change volume, test signals, regressions, and backlog movement
+- identify meaningful directional changes and explain whether the evidence is strong, weak, or incomplete
+- preserve the same metric definitions between periods; do not compare a repository window to a global window as if they were equivalent
+- report streaks, recurring hotspots, repeated failure modes, and unresolved improvements only when snapshots support them
+
+Store a JSON snapshot with stable keys, UTC timestamps, resolved window, scope, repository identity, commit/PR identifiers, metric values, evidence limitations, and a short list of findings. Keep narrative prose out of fields intended for machine comparison. A snapshot is an aid to future analysis, not a source of truth that overrides current evidence.
+
+## 5. Optionally promote durable lessons
+
+This phase is opt-in. A retrospective remains read-only unless the user or the surrounding workflow explicitly requests promotion to the shared ledger. Do not silently turn analysis into a write operation.
+
+Before adding any finding:
+
+1. Locate and read the current shared ledger. When a Git-backed repository ledger exists, read that repository file directly and treat it as authoritative. If it is absent or inaccessible, report `NOT_AVAILABLE` and do not claim that the ledger was checked.
+2. Classify the finding as one of:
+   - `local action` — a project- or task-specific follow-up that belongs in the report or backlog, not the shared ledger.
+   - `lesson` — a durable practice that generalizes across projects.
+   - `trap` — a non-obvious failure mode that can silently produce incorrect work.
+   - `preference` — a stable way the operator wants agents to work.
+3. Promote only non-obvious, durable, cross-project lessons, traps, or preferences. Keep local actions in the retrospective or project task system.
+4. Attach evidence to every promoted finding: a source path, commit, check, or other redacted reference, or the concrete failure that caused the rule. Do not promote an unsupported impression.
+5. Do not duplicate existing project instructions, shared-ledger notes, or behavior already enforced by an automated check. A thin ledger is more useful than a repetitive one.
+
+When promotion is authorized, append new notes using the current ledger schema; never rewrite, reorder, or overwrite existing entries. If no note is justified, append nothing. Report each added note ID, or `NOT_WRITTEN` when no note was added, promotion was not requested, or the ledger could not be safely updated.
+
+## 6. Produce the report
+
+Lead with a concise, shareable summary of the period. Then use this order:
+
+1. **Scope and evidence** — window, timezone, repositories, branch/base, sources, and limitations.
+2. **Summary table** — shipping, activity, quality, and delivery metrics with `UNKNOWN` where needed.
+3. **What shipped** — the most important features, fixes, releases, or decisions, tied to commits/PRs.
+4. **Trends** — comparison with the previous period, if available.
+5. **Time and sessions** — active days, session shape, time distribution, and context switching.
+6. **Quality and test health** — checks, regressions, churn hotspots, review signals, and open risks.
+7. **Plan completion** — objective items completed, deferred, or missing evidence.
+8. **Focus and collaboration** — personal or team analysis with fair context.
+9. **Top wins** — three evidence-backed wins when enough evidence exists.
+10. **Improvements** — three concrete, small, actionable improvements; fewer is fine when evidence is limited.
+11. **Next-period habits** — explicit habits or experiments with an owner or trigger when known.
+12. **Limitations** — missing refs, unavailable provider data, stale telemetry, dirty work, or ambiguous attribution.
+
+Use compact tables for exact metrics and prose for interpretation. Label inference as inference. Link or name evidence paths/commit IDs where useful, but never paste private content.
+
+## 7. End-of-task handoff
+
+If this run is explicitly closing a completed implementation, continue with `olko:wrap-up`:
+
+- use the retro to check that the delivered work matches the original idea and to capture follow-up items
+- let `wrap-up` perform the separate local/remote/PR/CI/deployment/QA gates and task-owned cleanup
+- preserve the retro snapshot and report any limitation instead of deleting evidence
+
+For a periodic or global retrospective, do not clean worktrees, branches, logs, or temporary files unless the user explicitly asks for that separate cleanup. Analysis alone must not alter delivery state.
+
+## Minimal final status
+
+End every run with:
+
+```text
+RETRO_STATUS: DONE | DONE_WITH_LIMITATIONS | BLOCKED
+WINDOW: <resolved window and timezone>
+SCOPE: <repository or repositories>
+SNAPSHOT: <path, NOT_WRITTEN, or NOT_AVAILABLE>
+TOP_FINDINGS: <short summary>
+NEXT_ACTIONS: <short actionable list>
+```
+
+Use `BLOCKED` only when the requested scope cannot be analyzed safely or the required evidence is inaccessible. A partial but clearly labeled report is `DONE_WITH_LIMITATIONS`.

package/{packages/software-development/wrap-up/adapters/claude → adapters/claude/olko-reflection}/skills/wrap-up/SKILL.md

@@ -67,20 +67,40 @@ Clean only paths created by this task or explicitly named for cleanup.
 
 ## 6. Report the result
 
-Lead with the outcome. Include concise evidence, cleanup performed, items intentionally preserved, and the smallest next action for any blocker. Always finish with this receipt, using `NOT_APPLICABLE` for out-of-scope gates and `NOT_RUN` for applicable checks that were not executed:
+Lead with the outcome. Use a short `DELIVERY RECEIPT` heading and a one- or
+two-sentence summary before the fields. Add `STATUS`, `NEXT_PHASE`, and
+`NEXT_STEP` near the top when follow-up work remains. Keep the required fields
+flush-left and grouped with one blank line between logical groups, not between
+every field. Keep each value concise and avoid repeating the same prose. Do
+not use Markdown tables, decorative separators, bullets, emojis, or indented
+continuation lines inside the canonical field block. Put `FINAL_STATUS` last.
+Add `LOCAL_COMMIT` when a local commit exists. Always finish with this receipt,
+using `NOT_APPLICABLE` for out-of-scope gates and `NOT_RUN` for applicable
+checks that were not executed:
 
 ```text
+DELIVERY RECEIPT
+
+<short outcome summary>
+STATUS: <DELIVERED | BLOCKED | INTENTIONALLY_UNCHANGED>
+NEXT_PHASE: <next phase or NOT_APPLICABLE>
+NEXT_STEP: <single smallest next action or NOT_APPLICABLE>
+
 OBJECTIVE:
 CHANGED:
 NOT_CHANGED:
+
 TESTS:
 BUILD:
+
 REMOTE:
 PR:
 CI:
 DEPLOYMENT:
 DEVICE_OR_HUMAN_QA:
+
 KNOWN_LIMITATIONS:
+LOCAL_COMMIT: <hash and subject, or NOT_APPLICABLE>
 FINAL_STATUS:
 ```
 

package/adapters/claude/olko-release/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-release",
+  "description": "Ship a release: semantic-release setup, changelogs, store listing copy, release-day routine.",
+  "skills": "./skills"
+}

package/adapters/claude/olko-skill-meta/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-skill-meta",
+  "description": "Author and maintain agent skills and the AI toolchain itself.",
+  "skills": "./skills"
+}

package/{packages/software-development/shared-knowledge-artifact/adapters/claude → adapters/claude/olko-skill-meta}/skills/shared-knowledge-artifact/SKILL.md

@@ -19,7 +19,7 @@ metadata:
 
 # shared-knowledge-artifact
 
-Publish one private Artifact page that acts as an append-only knowledge ledger which multiple agents (and the user) read before starting work and write to when reality corrects them. The page **is** the record: it stores its own data and publishes new versions of itself, so nothing depends on a server or on local files.
+Use a private Artifact page as an optional rendered and editing surface for an append-only knowledge ledger. Multiple agents (and the user) can read the lessons before starting work and append corrections afterwards. The Artifact is not universally authoritative: when a repository contains a Git-backed ledger, that repository ledger is the canonical record; the Artifact mirrors it and provides a convenient view or edit surface. Without a Git ledger, the published Artifact state is the durable record for that Artifact.
 
 ## Trigger phrases
 
@@ -32,12 +32,20 @@ Publish one private Artifact page that acts as an append-only knowledge ledger w
 
 1. Invoke the `artifact-capabilities` skill — mandatory before declaring `capabilities` or writing any `window.claude.*` code.
 2. Invoke the `artifact-design` skill — calibrates the design treatment.
-3. Read the user's actual rules (`CLAUDE.md`, any verification/preferences doc, agent memory) and **seed the ledger with 6-10 real lessons already recorded there**. No lorem, no invented examples — a ledger that opens with fake entries never gets used.
+3. Read the user's actual rules (`CLAUDE.md`, any verification/preferences doc, agent memory), and read the current repository ledger directly when one exists. **Seed the ledger with real lessons already recorded there — use 6-10 when that many exist, or all available real lessons if fewer than six are found**. No lorem, no invented examples — a ledger that opens with fake entries never gets used.
+
+## Authority and reconciliation
+
+- If a Git-backed ledger exists, it is authoritative over the Artifact. Codex and other non-Claude agents must read and update that repository ledger directly; they must not require Artifact access.
+- Before writing either surface, read the current repository ledger and the current Artifact state when both exist. Do not write from a stale page or cached copy.
+- Notes added in the Artifact must be appended back to the Git ledger, using the repository's schema and append-only rules, before they are treated as shared guidance. Record the resulting note ID or the reason it was not written.
+- If the Artifact and Git ledger disagree, preserve both histories but resolve the usable guidance in favor of Git. Refresh or reconcile the Artifact from Git rather than overwriting the repository record.
+- If no Git ledger exists, the Artifact's published `#ledger-state` is authoritative for that Artifact. Do not imply that it is shared with non-Claude agents unless it has been exported to a repository ledger.
 
 ## Persistence mechanism
 
 - Declare `capabilities: {artifact: {}}` at publish time.
-- Store the data as a JSON object inside `<script type="application/json" id="ledger-state">`. That block is the authoritative record; the visible page is **rendered from it** at load. Never serialize the live DOM to save.
+- Store the Artifact surface's data as a JSON object inside `<script type="application/json" id="ledger-state">`. That block is authoritative for the published Artifact version; the visible page is **rendered from it** at load. When a Git ledger exists, this page state remains a mirror and Git remains authoritative overall. Never serialize the live DOM to save.
 - To persist: snapshot `document.documentElement.outerHTML` **once at script start** (pristine source, before any rendering), then on save splice the new JSON into that snapshot's `#ledger-state` block, prepend `<!doctype html>`, and call `artifact.publish(doc)`.
 - Get the namespace with `const artifact = await claude.use("artifact")`; branch on `null` (this view cannot write) and render a read-only state instead of a broken control.
 - Handle publish errors by code: `conflict` means someone published first and every view reloads to the winner — no retry, tell the person to re-add; `not_granted` / `not_writer` means read-only.
@@ -64,7 +72,7 @@ Kinds: **lesson** = a habit that holds; **trap** = something that silently produ
 - Note list, newest first: kind tag, scope tag, author, date, title, body, and a `Why:` line. Kind tags use semantic colour (trap = critical, pref = warning, lesson = accent), separate from the page accent.
 - Scope filter chips derived from the data, including an `all` chip, with `aria-pressed` state.
 - An "Add a note" form (kind, scope, author, title, body, why) that appends to the JSON and publishes, with an inline status line reporting published / conflict / read-only.
-- A "Protocol for agents" section **on the page itself**: read the page with the Artifact tool `action: "read"` before substantive work; parse the `#ledger-state` JSON, never scrape the DOM; **append, don't rewrite**; re-read before writing because another agent may have published since; one fact per note with the failure that caused it. Include the schema snippet.
+- A "Protocol for agents" section **on the page itself**: when a Git ledger exists, read that repository ledger directly before substantive work; Codex and other non-Claude agents must use it directly. Claude agents may read the Artifact with the Artifact tool `action: "read"` as a rendered surface, then parse the `#ledger-state` JSON rather than scraping the DOM. In either case, **append, don't rewrite**, re-read before writing because another agent may have updated the source, and include the failure that caused each note. Include the schema snippet and the Git reconciliation rule.
 - Gatekeeping copy: only non-obvious, durable, cross-cutting lessons. If a repo's `CLAUDE.md` already says it, or a review bot already catches it, leave it out — a littered ledger is worse than a thin one.
 
 ## Design constraints
@@ -78,11 +86,12 @@ Kinds: **lesson** = a habit that holds; **trap** = something that silently produ
 
 ## Deliverable
 
-Write the HTML to a file, publish it with the Artifact tool, then report:
+When an Artifact surface is requested, write the HTML to a file and publish it with the Artifact tool, then report:
 
 - the URL;
 - that it stays private until shared from the page's share menu;
-- the exact instructions another agent needs — read via Artifact `action: "read"` with that URL, and write by appending to `notes` and republishing **with `url` set to that URL** (a publish *without* `url` forks a separate artifact instead of updating this one).
+- the exact instructions another Claude agent needs — read via Artifact `action: "read"` with that URL, and write by appending to `notes` and republishing **with `url` set to that URL** (a publish *without* `url` forks a separate artifact instead of updating this one);
+- when a Git ledger exists, the repository path and the reconciliation result, making clear that other agents should read and write Git directly and that Git wins any disagreement.
 
 ## Notes
 

package/adapters/claude/olko-web-ops/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-web-ops",
+  "description": "Operate a website: WAF rules, search console audits, analytics bootstrap, docs indexes.",
+  "skills": "./skills"
+}

package/adapters/codex/olko-apple-kit/README.md

@@ -0,0 +1,8 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Codex adapter: olko-apple-kit
+
+Use the canonical skills directly:
+
+- `plugins/olko-apple-kit/skills/apple-store-submit/SKILL.md`
+- `plugins/olko-apple-kit/skills/macos-menubar-app/SKILL.md`

package/adapters/codex/olko-creative/README.md

@@ -0,0 +1,10 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Codex adapter: olko-creative
+
+Use the canonical skills directly:
+
+- `plugins/olko-creative/skills/gallery/SKILL.md`
+- `plugins/olko-creative/skills/fill-music-player/SKILL.md`
+- `plugins/olko-creative/skills/vinted-listing/SKILL.md`
+- `plugins/olko-creative/skills/wikipedia-uk-editor/SKILL.md`

package/adapters/codex/olko-garmin-kit/README.md

@@ -0,0 +1,7 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Codex adapter: olko-garmin-kit
+
+Use the canonical skills directly:
+
+- `plugins/olko-garmin-kit/skills/garmin-watchface/SKILL.md`

package/adapters/codex/olko-git-tools/README.md

@@ -0,0 +1,9 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Codex adapter: olko-git-tools
+
+Use the canonical skills directly:
+
+- `plugins/olko-git-tools/skills/git-commit/SKILL.md`
+- `plugins/olko-git-tools/skills/gh-cli/SKILL.md`
+- `plugins/olko-git-tools/skills/branch-cleanup/SKILL.md`

package/adapters/codex/olko-github-pr/README.md

@@ -0,0 +1,16 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Codex adapter: olko-github-pr
+
+Use the canonical skills directly:
+
+- `plugins/olko-github-pr/skills/pr-finalize/SKILL.md`
+- `plugins/olko-github-pr/skills/pr-finalize-complete/SKILL.md`
+- `plugins/olko-github-pr/skills/pr-to-green/SKILL.md`
+- `plugins/olko-github-pr/skills/pr-description-writer/SKILL.md`
+- `plugins/olko-github-pr/skills/qodoloop/SKILL.md`
+- `plugins/olko-github-pr/skills/coderabbitloop/SKILL.md`
+- `plugins/olko-github-pr/skills/codexloop/SKILL.md`
+- `plugins/olko-github-pr/skills/geminiloop/SKILL.md`
+- `plugins/olko-github-pr/skills/ci-fix-loop/SKILL.md`
+- `plugins/olko-github-pr/skills/dependabot-triage/SKILL.md`

package/adapters/codex/olko-obsidian/README.md

@@ -0,0 +1,7 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Codex adapter: olko-obsidian
+
+Use the canonical skills directly:
+
+- `plugins/olko-obsidian/skills/morning-routine/SKILL.md`

package/adapters/codex/olko-product/README.md

@@ -0,0 +1,10 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Codex adapter: olko-product
+
+Use the canonical skills directly:
+
+- `plugins/olko-product/skills/product-builder/SKILL.md`
+- `plugins/olko-product/skills/mvp-oneshot/SKILL.md`
+- `plugins/olko-product/skills/starter-rules/SKILL.md`
+- `plugins/olko-product/skills/viral-launch/SKILL.md`

package/adapters/codex/olko-reflection/README.md

@@ -0,0 +1,11 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Codex adapter: olko-reflection
+
+Use the canonical skills directly:
+
+- `plugins/olko-reflection/skills/self-critique/SKILL.md`
+- `plugins/olko-reflection/skills/review-past-performance/SKILL.md`
+- `plugins/olko-reflection/skills/retro-analysis/SKILL.md`
+- `plugins/olko-reflection/skills/crash-course/SKILL.md`
+- `plugins/olko-reflection/skills/wrap-up/SKILL.md`

package/adapters/codex/olko-release/README.md

@@ -0,0 +1,11 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Codex adapter: olko-release
+
+Use the canonical skills directly:
+
+- `plugins/olko-release/skills/semantic-release-beta/SKILL.md`
+- `plugins/olko-release/skills/open-source-publisher/SKILL.md`
+- `plugins/olko-release/skills/release-day/SKILL.md`
+- `plugins/olko-release/skills/changelog-generator/SKILL.md`
+- `plugins/olko-release/skills/store-listing-copy/SKILL.md`

package/adapters/codex/olko-skill-meta/README.md

@@ -0,0 +1,9 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Codex adapter: olko-skill-meta
+
+Use the canonical skills directly:
+
+- `plugins/olko-skill-meta/skills/add-to-my-skills/SKILL.md`
+- `plugins/olko-skill-meta/skills/promptctl/SKILL.md`
+- `plugins/olko-skill-meta/skills/ai-tools-setup/SKILL.md`

package/adapters/codex/olko-web-ops/README.md

@@ -0,0 +1,9 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# Codex adapter: olko-web-ops
+
+Use the canonical skills directly:
+
+- `plugins/olko-web-ops/skills/cloudflare-block-countries/SKILL.md`
+- `plugins/olko-web-ops/skills/search-console-indexing-audit/SKILL.md`
+- `plugins/olko-web-ops/skills/docs-index-keeper/SKILL.md`