diff --git a/chezmoi/.chezmoitemplates/AGENTS.md b/chezmoi/.chezmoitemplates/AGENTS.md index 6d43ca38..fa0e0d56 100644 --- a/chezmoi/.chezmoitemplates/AGENTS.md +++ b/chezmoi/.chezmoitemplates/AGENTS.md @@ -36,24 +36,34 @@ - Do not duplicate information between the two files. Reference `README.md` for project context. -## Global Knowledge +## Knowledge Wiki -Durable knowledge lives under `~/.okf/`, as an Open Knowledge Format +Durable knowledge lives under `~/wiki/`, as an Open Knowledge Format (OKF) bundle. Use the `okf` skill for the format and bundle- maintenance conventions. -Rules: - -- At session start, read `~/.okf/index.md`; load topic files - only when relevant. -- Organize by topic freely, no fixed taxonomy. Split files that +- **Read**: at session start, read `~/wiki/index.md`; load topic + files only when relevant. +- **Write**: when a task surfaces a durable fact, decision, or + gotcha — a library quirk, a config value and why it's set that + way, an architectural tradeoff, a fix for a problem likely to + recur — write it to the matching concept file immediately, before + moving on. Don't wait to be asked, and don't batch it for session + end. Example: fixing a flaky test because a library needs + `retry=true` is wiki-worthy; a one-off typo fix is not. +- **Search before writing**: check whether an existing concept + already covers the topic; amend it in place rather than creating + a near-duplicate. Only create a new concept file for a genuinely + new topic. +- **Organize** by topic freely, no fixed taxonomy. Split files that grow unwieldy or unfocused. -- Maintain as you go: when editing a topic file, fix or remove +- **Maintain as you go**: when editing a topic file, fix or remove entries you find stale, wrong, or superseded. Keep `index.md` in - sync with what actually exists on disk. + sync with what actually exists on disk, and add a `log.md` entry + at that directory level if one exists. - `~/.memsearch/USER.md` is a related, read-only reference maintained by memsearch — don't edit it or merge it into - `~/.okf/`. + `~/wiki/`. ## Code Quality diff --git a/chezmoi/.chezmoitemplates/opencode.json b/chezmoi/.chezmoitemplates/opencode.json index e228afde..62fe41f8 100644 --- a/chezmoi/.chezmoitemplates/opencode.json +++ b/chezmoi/.chezmoitemplates/opencode.json @@ -7,6 +7,14 @@ "compaction": { "prune": true }, + "permission": { + "edit": { + "~/wiki/**": "allow" + }, + "external_directory": { + "~/wiki/**": "allow" + } + }, "plugin": [ "@tarquinen/opencode-dcp", "openslimedit", diff --git a/chezmoi/private_dot_agents/skills/okf/TEMPLATE/index.md b/chezmoi/private_dot_agents/skills/okf/SAMPLE/index.md similarity index 100% rename from chezmoi/private_dot_agents/skills/okf/TEMPLATE/index.md rename to chezmoi/private_dot_agents/skills/okf/SAMPLE/index.md diff --git a/chezmoi/private_dot_agents/skills/okf/SAMPLE/log.md b/chezmoi/private_dot_agents/skills/okf/SAMPLE/log.md new file mode 100644 index 00000000..d17a0547 --- /dev/null +++ b/chezmoi/private_dot_agents/skills/okf/SAMPLE/log.md @@ -0,0 +1,11 @@ +# Bundle Update Log + +## 2026-05-28 + +* **Creation**: Established the [orders](./tables/orders.md) and + [customers](./tables/customers.md) tables. + +## 2026-04-12 + +* **Creation**: Added the [freshness alert + playbook](./playbooks/data-freshness-alert.md). diff --git a/chezmoi/private_dot_agents/skills/okf/TEMPLATE/playbooks/data-freshness-alert.md b/chezmoi/private_dot_agents/skills/okf/SAMPLE/playbooks/data-freshness-alert.md similarity index 69% rename from chezmoi/private_dot_agents/skills/okf/TEMPLATE/playbooks/data-freshness-alert.md rename to chezmoi/private_dot_agents/skills/okf/SAMPLE/playbooks/data-freshness-alert.md index 58087160..9a618526 100644 --- a/chezmoi/private_dot_agents/skills/okf/TEMPLATE/playbooks/data-freshness-alert.md +++ b/chezmoi/private_dot_agents/skills/okf/SAMPLE/playbooks/data-freshness-alert.md @@ -9,9 +9,9 @@ timestamp: 2026-04-12T09:00:00Z ## Trigger A freshness alert fires when `orders` lags more than 30 minutes behind -its expected SLA. See the [orders table](/tables/orders.md). +its expected SLA. See the [orders table](../tables/orders.md). ## Steps 1. Check the ingestion job dashboard. -2. Confirm whether upstream [customers](/tables/customers.md) is also lagging. +2. Confirm whether upstream [customers](../tables/customers.md) is also lagging. diff --git a/chezmoi/private_dot_agents/skills/okf/TEMPLATE/playbooks/index.md b/chezmoi/private_dot_agents/skills/okf/SAMPLE/playbooks/index.md similarity index 100% rename from chezmoi/private_dot_agents/skills/okf/TEMPLATE/playbooks/index.md rename to chezmoi/private_dot_agents/skills/okf/SAMPLE/playbooks/index.md diff --git a/chezmoi/private_dot_agents/skills/okf/TEMPLATE/tables/customers.md b/chezmoi/private_dot_agents/skills/okf/SAMPLE/tables/customers.md similarity index 88% rename from chezmoi/private_dot_agents/skills/okf/TEMPLATE/tables/customers.md rename to chezmoi/private_dot_agents/skills/okf/SAMPLE/tables/customers.md index 60e05fe4..af8db5d4 100644 --- a/chezmoi/private_dot_agents/skills/okf/TEMPLATE/tables/customers.md +++ b/chezmoi/private_dot_agents/skills/okf/SAMPLE/tables/customers.md @@ -14,4 +14,4 @@ timestamp: 2026-05-28T00:00:00Z | `customer_id` | STRING | Globally unique customer id. | | `signed_up_at` | TIMESTAMP | When the account was created. | -Referenced by [orders](/tables/orders.md) via `customer_id`. +Referenced by [orders](./orders.md) via `customer_id`. diff --git a/chezmoi/private_dot_agents/skills/okf/TEMPLATE/tables/index.md b/chezmoi/private_dot_agents/skills/okf/SAMPLE/tables/index.md similarity index 100% rename from chezmoi/private_dot_agents/skills/okf/TEMPLATE/tables/index.md rename to chezmoi/private_dot_agents/skills/okf/SAMPLE/tables/index.md diff --git a/chezmoi/private_dot_agents/skills/okf/TEMPLATE/tables/orders.md b/chezmoi/private_dot_agents/skills/okf/SAMPLE/tables/orders.md similarity index 51% rename from chezmoi/private_dot_agents/skills/okf/TEMPLATE/tables/orders.md rename to chezmoi/private_dot_agents/skills/okf/SAMPLE/tables/orders.md index 1be4cb6c..e7605a62 100644 --- a/chezmoi/private_dot_agents/skills/okf/TEMPLATE/tables/orders.md +++ b/chezmoi/private_dot_agents/skills/okf/SAMPLE/tables/orders.md @@ -9,11 +9,11 @@ timestamp: 2026-05-28T14:30:00Z ## Schema -| Column | Type | Description | -|---------------|---------|------------------------------------------| -| `order_id` | STRING | Globally unique order identifier. | -| `customer_id` | STRING | FK to [customers](/tables/customers.md). | -| `total_usd` | NUMERIC | Order total in US dollars. | +| Column | Type | Description | +|---------------|---------|------------------------------------| +| `order_id` | STRING | Globally unique order identifier. | +| `customer_id` | STRING | FK to [customers](./customers.md). | +| `total_usd` | NUMERIC | Order total in US dollars. | ## Citations diff --git a/chezmoi/private_dot_agents/skills/okf/SKILL.md b/chezmoi/private_dot_agents/skills/okf/SKILL.md index 82c7bbf8..770a14ff 100644 --- a/chezmoi/private_dot_agents/skills/okf/SKILL.md +++ b/chezmoi/private_dot_agents/skills/okf/SKILL.md @@ -10,13 +10,15 @@ description: >- # Open Knowledge Format (OKF) -OKF v0.1 (Draft, GoogleCloudPlatform/knowledge-catalog) is a spec for -knowledge as a directory of markdown files with YAML frontmatter — readable -by humans, parseable by agents, diffable in git. No SDK, schema registry, or -central authority required. This file contains the full spec; no need to -re-fetch it. [TEMPLATE/](TEMPLATE/) is a small worked bundle — every file -kind below in one directory tree — copy from it when actually writing a -bundle, not just reading about one. +OKF is a spec for knowledge as a directory of markdown files with YAML +frontmatter — readable by humans, parseable by agents, diffable in git. No +SDK, schema registry, or central authority required. + +[SAMPLE/](SAMPLE/) is a small worked bundle — every file kind in one +directory tree — copy from it when actually writing a bundle, not just +reading about one. [SPEC.md](SPEC.md) holds the full field-level spec +(frontmatter fields, citations, versioning); load it only when a rule below +doesn't answer the question in front of you. ## Terminology @@ -39,109 +41,47 @@ bundle/ ``` `index.md` and `log.md` are **reserved filenames** — never use them for a -concept document. Every other `.md` file is a concept. File encoding UTF-8, -extension `.md` only. - -## Concept frontmatter - -Every concept MUST open with a frontmatter block carrying a non-empty -`type`. Recommended fields, in priority order when trimming: `title`, -`description`, `resource`, `tags`, `timestamp`. - -| Field | Required | Meaning | -|---------------|----------|-------------------------------------------------| -| `type` | **yes** | Free-text kind. Not centrally registered. | -| `title` | no | Display name; derives from filename if omitted. | -| `description` | no | One sentence; feeds index entries and search. | -| `resource` | no | Canonical URI of the underlying asset. | -| `tags` | no | List for cross-cutting categorization. | -| `timestamp` | no | ISO 8601 datetime of last meaningful change. | - -`type` examples: `Playbook`, `API Endpoint`, `Metric`. Pick a -self-explanatory value; tolerate unknown ones you encounter. `resource` is -omitted for abstract concepts (playbooks, decisions, notes). - -Extra producer-defined keys are always allowed — preserve them, never strip -an unrecognized key. - -Body has no required sections. Prefer structural markdown (tables, lists, -fenced code) over prose. Conventional headings: `# Schema` (columns/fields -of a data asset), `# Examples` (usage), `# Citations` (see below). - -## Cross-linking concepts - -Standard markdown links, two forms: - -- **Bundle-absolute (recommended)** — starts with `/`, relative to bundle - root: `[customers table](/tables/customers.md)`. Survives the file being - moved within its subdirectory. -- **Relative** — `[neighboring concept](./other.md)`. - -A link only asserts "these are related" — the relationship kind -(parent/child, joins-with, depends-on) belongs in surrounding prose, never -in link syntax. A broken link is tolerated, not an error: it may name -knowledge not yet written. Never "fix" a dangling link by deleting it +concept document. Every other `.md` file is a concept. + +Every concept opens with a frontmatter block carrying a non-empty `type` +(free-text, not centrally registered — e.g. `Playbook`, `API Endpoint`, +`Metric`). Body has no required sections; prefer structural markdown +(tables, lists, fenced code) over prose. See [SPEC.md](SPEC.md) for the +full recommended-field list and citation conventions. + +Cross-link concepts with standard markdown links, relative to the linking +file, e.g. `[customers table](../tables/customers.md)`. A link only asserts +"these are related"; the relationship kind belongs in surrounding prose, +never in link syntax. A broken link is tolerated, not an error — it may +name knowledge not yet written. Never "fix" a dangling link by deleting it without first checking whether the target should simply be created. -## `index.md` - -Progressive disclosure for a directory: a flat, headed list of links to -its concepts and subdirectories, each with a short description pulled from -the linked concept's frontmatter. May exist at any directory level, -including bundle root. - -No frontmatter — **except** the bundle-root `index.md`, which may carry a -frontmatter block containing only `okf_version` (see Versioning). That is -the one place frontmatter is permitted in an `index.md`. - -## `log.md` - -Optional at any directory level; records that scope's change history as a -flat, date-grouped list, **newest date first**, headings in `## YYYY-MM-DD` -form. The leading bold word per entry (`**Update**`, `**Creation**`, -`**Deprecation**`) is convention, not required structure. - -## Citations - -When a concept's body makes claims sourced from external material, list -them under a trailing `# Citations` heading, numbered. Targets may be -external URLs, bundle-relative paths, or paths into a `references/` -subdirectory that mirrors external material as first-class concepts. - ## Conformance — the only hard rules A bundle is OKF-conformant iff: 1. Every non-reserved `.md` file has parseable YAML frontmatter. 2. Every frontmatter block has a non-empty `type`. -3. `index.md`/`log.md`, where present, follow the structures above. +3. `index.md`/`log.md`, where present, follow the structures in [SPEC.md](SPEC.md). Everything else is soft guidance. Never reject or "fix" a bundle for: missing optional fields, unknown `type` values, unknown extra frontmatter keys, broken links, or a missing `index.md`. This permissiveness is -intentional — it supports partial, incremental, agent-driven growth. - -## Versioning - -Format `.`; this spec is `0.1`. Minor bump = backward-compatible -addition (new optional field, new conventional heading). Major bump = -breaking (renamed required field, changed reserved filename). Declare a -bundle's target version only via `okf_version` in the bundle-root -`index.md` frontmatter — see [TEMPLATE/index.md](TEMPLATE/index.md). +intentional — it supports partial, incremental, agent-driven growth. Before +treating a bundle as broken, check it against these three rules only — +never invent stricter ones. ## Maintaining a bundle 1. **New concept** — pick the right subdirectory (create one if the topic - is new), model the file on the closest match in - [TEMPLATE/](TEMPLATE/) with `type` + recommended fields, link it from - related concepts and from the nearest `index.md`. + is new), model the file on the closest match in [SAMPLE/](SAMPLE/) + with `type` + recommended fields (see [SPEC.md](SPEC.md)), link it from + related concepts and from the nearest `index.md`. 2. **Update a concept** — edit body/frontmatter in place, bump `timestamp`, - add a `log.md` entry at the relevant directory level if the bundle - maintains one. -3. **Reorganize** — moving a file only breaks *relative* (`./`) links, not - bundle-absolute (`/`) ones; prefer bundle-absolute links to make this - safe. Update the old and new directories' `index.md` entries. + add a `log.md` entry at the relevant directory level if the bundle + maintains one. +3. **Reorganize** — moving a file breaks relative links pointing to or from + it; update those links and the old and new directories' `index.md` + entries. 4. **New subdirectory** — add its `index.md`, and add one line linking to - `subdir/` from the parent `index.md`. -5. Before treating a bundle as broken, check it against the three - conformance rules above only — never invent stricter rules. + `subdir/` from the parent `index.md`. diff --git a/chezmoi/private_dot_agents/skills/okf/SPEC.md b/chezmoi/private_dot_agents/skills/okf/SPEC.md new file mode 100644 index 00000000..b7a14a05 --- /dev/null +++ b/chezmoi/private_dot_agents/skills/okf/SPEC.md @@ -0,0 +1,60 @@ +# OKF Spec Reference + +Field-level detail for [SKILL.md](SKILL.md). Source: OKF v0.1 (Draft, +[GoogleCloudPlatform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)). + +## Concept frontmatter fields + +Recommended fields, in priority order when trimming: + +| Field | Required | Meaning | +|---------------|----------|-------------------------------------------------| +| `type` | **yes** | Free-text kind. Not centrally registered. | +| `title` | no | Display name; derives from filename if omitted. | +| `description` | no | One sentence; feeds index entries and search. | +| `resource` | no | Canonical URI of the underlying asset. | +| `tags` | no | List for cross-cutting categorization. | +| `timestamp` | no | ISO 8601 datetime of last meaningful change. | + +`resource` is omitted for abstract concepts (playbooks, decisions, notes) — +it exists for concepts describing a concrete addressable asset (a table, an +endpoint). + +Extra producer-defined keys are always allowed — preserve them, never strip +an unrecognized key. + +Conventional body headings: `# Schema` (columns/fields of a data asset), +`# Examples` (usage), `# Citations` (see below). + +## `index.md` + +Progressive disclosure for a directory: a flat, headed list of links to its +concepts and subdirectories, each with a short description pulled from the +linked concept's frontmatter. May exist at any directory level, including +bundle root. + +No frontmatter — **except** the bundle-root `index.md`, which may carry a +frontmatter block containing only `okf_version` (see Versioning below). +That is the one place frontmatter is permitted in an `index.md`. + +## `log.md` + +Optional at any directory level; records that scope's change history as a +flat, date-grouped list, **newest date first**, headings in `## YYYY-MM-DD` +form. The leading bold word per entry (`**Update**`, `**Creation**`, +`**Deprecation**`) is convention, not required structure. + +## Citations + +When a concept's body makes claims sourced from external material, list +them under a trailing `# Citations` heading, numbered. Targets may be +external URLs, bundle-relative paths, or paths into a `references/` +subdirectory that mirrors external material as first-class concepts. + +## Versioning + +Format `.`; this spec is `0.1`. Minor bump = +backward-compatible addition (new optional field, new conventional +heading). Major bump = breaking (renamed required field, changed reserved +filename). Declare a bundle's target version only via `okf_version` in the +bundle-root `index.md` frontmatter — see [SAMPLE/index.md](SAMPLE/index.md). diff --git a/chezmoi/private_dot_agents/skills/okf/TEMPLATE/log.md b/chezmoi/private_dot_agents/skills/okf/TEMPLATE/log.md deleted file mode 100644 index 6a7a7137..00000000 --- a/chezmoi/private_dot_agents/skills/okf/TEMPLATE/log.md +++ /dev/null @@ -1,11 +0,0 @@ -# Bundle Update Log - -## 2026-05-28 - -* **Creation**: Established the [orders](/tables/orders.md) and - [customers](/tables/customers.md) tables. - -## 2026-04-12 - -* **Creation**: Added the [freshness alert - playbook](/playbooks/data-freshness-alert.md).