Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 21 additions & 11 deletions chezmoi/.chezmoitemplates/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
(OKF) bundle. Use the `okf` skill for the format and bundle-
Durable knowledge lives under `~/wiki/`, as an Open Knowledge Format
(OKF) bundle. Use the `\okf` skill for the format and bundle-
Comment thread
yxtay marked this conversation as resolved.
Resolved
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

Expand Down
8 changes: 8 additions & 0 deletions chezmoi/.chezmoitemplates/opencode.json
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,14 @@
"compaction": {
"prune": true
},
"permission": {
"edit": {
"~/wiki/**": "allow"
},
"external_directory": {
"~/wiki/**": "allow"
}
},
"plugin": [
"@tarquinen/opencode-dcp",
"openslimedit",
Expand Down
11 changes: 11 additions & 0 deletions chezmoi/private_dot_agents/skills/okf/SAMPLE/log.md
Original file line number Diff line number Diff line change
@@ -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).
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
130 changes: 35 additions & 95 deletions chezmoi/private_dot_agents/skills/okf/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 `<major>.<minor>`; 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`.
60 changes: 60 additions & 0 deletions chezmoi/private_dot_agents/skills/okf/SPEC.md
Original file line number Diff line number Diff line change
@@ -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 `<major>.<minor>`; 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).
11 changes: 0 additions & 11 deletions chezmoi/private_dot_agents/skills/okf/TEMPLATE/log.md

This file was deleted.

Loading