From 2ad816dc533b5111b31d05e8ae9debe3a19736b1 Mon Sep 17 00:00:00 2001 From: Emilio Balda Date: Fri, 4 Sep 2026 10:51:08 +0300 Subject: [PATCH 1/4] chore: move taxonomy instructions to their own sub-section in the skill --- skills/okf/SKILL.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/skills/okf/SKILL.md b/skills/okf/SKILL.md index 729828f..71869ee 100644 --- a/skills/okf/SKILL.md +++ b/skills/okf/SKILL.md @@ -17,6 +17,11 @@ not create a routine task summary unless the user asks for a memory. - Use the actual agent and version for `generated.by` when you know them. Omit `generated` when you do not know the correct identity. +## Taxonomy of `brain/` + +Aside from the reserved file names `index.md` and `log.md` (according to the OKF standard), the example folders and types are not a fixed taxonomy. +Add/rename a folder or type when it makes the knowledge easier to find. + ## Produce - write a memory 1. Read [SPEC.md](reference/SPEC.md) for the complete OKF v0.2 rules. @@ -25,9 +30,6 @@ not create a routine task summary unless the user asks for a memory. 4. Otherwise, create a UTF-8 Markdown concept with YAML frontmatter following the concept template from [templates/concept.md](templates/concept.md): set adescriptive `type`, fill recommended fields, record `generated` and the `sources` you actually read, cross-link related concepts via normal Markdown links. 5. Validate (see below). Fix every error before finishing. -The example folders and types are not a fixed taxonomy. Add a folder or type -when it makes the knowledge easier to find. - ## Maintain - keep a bundle in sync with reality 1. Identify which concepts the change affects (search by `resource`, path, or From f259d8968a1b0d765891da0afa2692a4baa825a7 Mon Sep 17 00:00:00 2001 From: Emilio Balda Date: Fri, 4 Sep 2026 10:52:45 +0300 Subject: [PATCH 2/4] refactor: remove unnecessary contribute file --- CONTRIBUTING.md | 26 -------------------------- 1 file changed, 26 deletions(-) delete mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 6a81d41..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,26 +0,0 @@ -# Contributing - -Contributions fall into three groups: - -- Changes to [SPEC.md](skills/okf/reference/SPEC.md) change the Open Knowledge Format standard. - Open an issue before a format change. -- Changes to `okf_tools/` change deterministic bundle tools. -- Changes to `brain/` change the starter memory bundle. - -Before you submit a pull request: - -1. Install the development dependencies from [README.md](README.md). -2. Run `okf index brain`. -3. Run `okf check brain`. -4. Run `pytest`. -5. Run `pre-commit run --all-files`. - -## Contributor License Agreement - -Contributions must include a Contributor License Agreement. You retain the -copyright to your contribution and give the project permission to distribute -it. See . - -## Code reviews - -All submissions need review through a GitHub pull request. From aae1f2832c81a9ef9b1da479c0637c7372859e4f Mon Sep 17 00:00:00 2001 From: Emilio Balda Date: Fri, 4 Sep 2026 12:06:54 +0300 Subject: [PATCH 3/4] Add onboarding flow for second brain modalities - Add ONBOARDING.md guiding agents to pick peer-to-peer or centralized modality, apply the matching skill, and clean up onboarding files. - Point AGENTS.md and CLAUDE.md at ONBOARDING.md. - Split the peer-to-peer instructions into skills/okf/onboarding-SKILL-peer-to-peer.md and add skills/okf/onboarding-SKILL-centralized.md for the new centralized modality (raw/ inbox + single maintainer). - Replace skills/okf/SKILL.md with a placeholder until onboarding completes. Co-authored-by: Cursor --- AGENTS.md | 2 +- CLAUDE.md | 2 +- ONBOARDING.md | 32 +++++++++ skills/okf/SKILL.md | 64 +---------------- skills/okf/onboarding-SKILL-centralized.md | 80 +++++++++++++++++++++ skills/okf/onboarding-SKILL-peer-to-peer.md | 63 ++++++++++++++++ 6 files changed, 179 insertions(+), 64 deletions(-) create mode 100644 ONBOARDING.md create mode 100644 skills/okf/onboarding-SKILL-centralized.md create mode 100644 skills/okf/onboarding-SKILL-peer-to-peer.md diff --git a/AGENTS.md b/AGENTS.md index db1a3dc..c1c3c94 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,3 @@ # Agent instructions -Read and follow [skills/okf/SKILL.md](skills/okf/SKILL.md) before you change a memory bundle. +Read and follow [ONBOARDING.md](ONBOARDING.md) before you change a memory bundle. diff --git a/CLAUDE.md b/CLAUDE.md index db1a3dc..c1c3c94 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,3 +1,3 @@ # Agent instructions -Read and follow [skills/okf/SKILL.md](skills/okf/SKILL.md) before you change a memory bundle. +Read and follow [ONBOARDING.md](ONBOARDING.md) before you change a memory bundle. diff --git a/ONBOARDING.md b/ONBOARDING.md new file mode 100644 index 0000000..1a1a016 --- /dev/null +++ b/ONBOARDING.md @@ -0,0 +1,32 @@ +# Onboarding + +This second brain supports more than one modality. Pick one modality before +you store or read any memory. + +## Step 1 - Pick a modality + +- `peer-to-peer`: every agent may add, edit, and reorganize entries in + `brain/`. There is no single maintainer. +- `centralized`: every agent except one writes new, immutable entries to + `brain/raw/`. One maintainer agent reads `raw/`, extracts concepts, + resolves conflicts, and organizes `brain/`. + +If it is extremely clear which modality to use, go ahead and decide yourself. Otherwise, ask the user to decide. Do not guess. + +## Step 2 - Apply the modality + +1. Copy the full content of `skills/okf/onboarding-SKILL-.md` into + `skills/okf/SKILL.md`, replacing the placeholder text. +2. Follow any remaining setup step written inside that file (for example, + the `centralized` skill needs a maintainer agent id). +3. Update [AGENTS.md](AGENTS.md) and [CLAUDE.md](CLAUDE.md): point them at + `skills/okf/SKILL.md` again, not this file. +4. Delete `skills/okf/onboarding-SKILL-peer-to-peer.md`, + `skills/okf/onboarding-SKILL-centralized.md`, and this file + (`ONBOARDING.md`). + +## Step 3 - Confirm + +Read `skills/okf/SKILL.md` back and check it no longer mentions onboarding +or a missing agent id. Onboarding is complete once both `AGENTS.md` and +`CLAUDE.md` point to `skills/okf/SKILL.md` and no onboarding files remain. diff --git a/skills/okf/SKILL.md b/skills/okf/SKILL.md index 71869ee..b72d945 100644 --- a/skills/okf/SKILL.md +++ b/skills/okf/SKILL.md @@ -1,63 +1,3 @@ -# Memory workflow +# EMPTY SKILL DUE TO UNFINISHED ONBOARDING -This repository is a second brain for coding agents. Store memories as Open -Knowledge Format (OKF) concepts under `brain/`. - -## When to write - -Write or change a memory only after the user explicitly asks you to do so. Do -not create a routine task summary unless the user asks for a memory. - -## Safety - -- Never store secrets, credentials, tokens, private keys, or session data. -- Never store personal data unless the user explicitly approves that exact data. -- Do not claim human verification. Add `verified` with a `human:` actor only - after that person explicitly confirms the concept. -- Use the actual agent and version for `generated.by` when you know them. Omit - `generated` when you do not know the correct identity. - -## Taxonomy of `brain/` - -Aside from the reserved file names `index.md` and `log.md` (according to the OKF standard), the example folders and types are not a fixed taxonomy. -Add/rename a folder or type when it makes the knowledge easier to find. - -## Produce - write a memory - -1. Read [SPEC.md](reference/SPEC.md) for the complete OKF v0.2 rules. -2. Read `brain/index.md` and search the bundle for related terms. -3. Update an existing concept when it describes the same knowledge. -4. Otherwise, create a UTF-8 Markdown concept with YAML frontmatter following the concept template from [templates/concept.md](templates/concept.md): set adescriptive `type`, fill recommended fields, record `generated` and the `sources` you actually read, cross-link related concepts via normal Markdown links. -5. Validate (see below). Fix every error before finishing. - -## Maintain - keep a bundle in sync with reality - -1. Identify which concepts the change affects (search by `resource`, path, or - topic). This bookkeeping is exactly what agents are good at — touch every - affected file in one pass. -2. Update the body and `generated.at` (with your own actor in `generated.by`); - fix or add cross-links; create new concepts for new assets; mark removed - assets `status: deprecated` and note the deprecation in `log.md` rather than - silently deleting context. Facing a whole v0.1 bundle rather than a stray - field? Do not hand-edit it — run the validator's `--migrate` once. -3. Update the relevant `index.md` files and append a dated `log.md` entry - describing what changed. -4. Validate. - -### Consume — use a bundle as context - -1. Read the bundle-root `index.md` first for progressive disclosure, then follow - links only into the concepts relevant to the task. -2. Weigh what you read: `status: draft`/`deprecated`, a `stale_after` already - past, or no `verified` entry all mean "check before relying on this". Treat - broken links as not-yet-written knowledge, not errors. -3. Need a number an `Attested Computation` covers? Run *its* computation with - values bound to the declared `parameters` — never write your own query. -4. If you learn something durable while working, switch to **maintain** and - write it back. - -## Validation (do this before declaring done) - -1. Run `okf index brain`. -2. Run `okf check brain`. -3. Fix every finding. +If you are reading this text it means you have yet to complete the onboarding steps at [ONBOARDING.md](../../ONBOARDING.md) diff --git a/skills/okf/onboarding-SKILL-centralized.md b/skills/okf/onboarding-SKILL-centralized.md new file mode 100644 index 0000000..d988d68 --- /dev/null +++ b/skills/okf/onboarding-SKILL-centralized.md @@ -0,0 +1,80 @@ +# Memory workflow + +This repository is a second brain for coding agents. Store memories as Open +Knowledge Format (OKF) concepts under `brain/`. + +## When to write + +Write or change a memory only after the user explicitly asks you to do so. Do +not create a routine task summary unless the user asks for a memory. + +## Safety + +- Never store secrets, credentials, tokens, private keys, or session data. +- Never store personal data unless the user explicitly approves that exact data. +- Do not claim human verification. Add `verified` with a `human:` actor only + after that person explicitly confirms the concept. +- Use the actual agent and version for `generated.by` when you know them. Omit + `generated` when you do not know the correct identity. + +## Taxonomy of `brain/` + +`raw/` is the inbox. Every agent (including the maintainer) writes new entries +there and never edits or deletes an existing entry once it lands. One entry +per file. + +Outside `raw/`, only the maintainer creates, edits, or reorganizes files. +Aside from the reserved file names `index.md` and `log.md` (according to +the OKF standard) and the `raw/` folder itself, the example folders and +types are not a fixed taxonomy. The maintainer may add or rename a folder +or type when it makes the knowledge easier to find. + +## Produce - write a memory + +1. Read [SPEC.md](reference/SPEC.md) for the complete OKF v0.2 rules. +2. Read `brain/index.md` and search the bundle for related terms. +3. Update an existing concept when it describes the same knowledge. +4. Otherwise, create a UTF-8 Markdown concept with YAML frontmatter following the concept template from [templates/concept.md](templates/concept.md): set adescriptive `type`, fill recommended fields, record `generated` and the `sources` you actually read, cross-link related concepts via normal Markdown links. +5. Validate (see below). Fix every error before finishing. + +### Consume — use a bundle as context + +1. Read the bundle-root `index.md` first for progressive disclosure, then follow + links only into the concepts relevant to the task. +2. Weigh what you read: `status: draft`/`deprecated`, a `stale_after` already + past, or no `verified` entry all mean "check before relying on this". Treat + broken links as not-yet-written knowledge, not errors. +3. Need a number an `Attested Computation` covers? Run *its* computation with + values bound to the declared `parameters` — never write your own query. +4. If you learn something durable while working, switch to **maintain** and + write it back. + +## Maintain - keep a bundle in sync with reality + +There is only ONE maintainer agent. + +- Maintainer Agent: `` + +TO COMPLETE THE ONBOARDING, YOU MUST FILL IT WITH AN AGENT ID AND REMOVE THIS LINE. + +Everyone can produce and consume, but only the maintainer is allowed to carry the following steps: + +1. Take look at the changes since the last maintainer commit (i.e., commit message starts with `maintain:`). +2. Identify which concepts those changes affect (search by `resource`, path, or + topic). This bookkeeping is exactly what agents are good at — touch every + affected file in one pass. Make sure to spot common concepts, patterns, decisions, and contradicting information. +3. Update the body and `generated.at` (with your own actor in `generated.by`); + fix or add cross-links; create new concepts for new assets; mark removed + assets `status: deprecated` and note the deprecation in `log.md` rather than + silently deleting context. Facing a whole v0.1 bundle rather than a stray + field? Do not hand-edit it — run the validator's `--migrate` once. +4. Update the relevant `index.md` files and append a dated `log.md` entry + describing what changed. +5. Validate. +6. Commit using the format `maintain: ` + +## Validation (do this before declaring done) + +1. Run `okf index brain`. +2. Run `okf check brain`. +3. Fix every finding. diff --git a/skills/okf/onboarding-SKILL-peer-to-peer.md b/skills/okf/onboarding-SKILL-peer-to-peer.md new file mode 100644 index 0000000..4b30749 --- /dev/null +++ b/skills/okf/onboarding-SKILL-peer-to-peer.md @@ -0,0 +1,63 @@ +# Memory workflow + +This repository is a second brain for coding agents. Store memories as Open +Knowledge Format (OKF) concepts under `brain/`. + +## When to write + +Write or change a memory only after the user explicitly asks you to do so. Do +not create a routine task summary unless the user asks for a memory. + +## Safety + +- Never store secrets, credentials, tokens, private keys, or session data. +- Never store personal data unless the user explicitly approves that exact data. +- Do not claim human verification. Add `verified` with a `human:` actor only + after that person explicitly confirms the concept. +- Use the actual agent and version for `generated.by` when you know them. Omit + `generated` when you do not know the correct identity. + +## Taxonomy of `brain/` + +Aside from the reserved file names `index.md` and `log.md` (according to the OKF standard), the example folders and types are not a fixed taxonomy. +Add/rename a folder or type when it makes the knowledge easier to find. + +## Produce - write a memory + +1. Read [SPEC.md](reference/SPEC.md) for the complete OKF v0.2 rules. +2. Read `brain/index.md` and search the bundle for related terms. +3. Update an existing concept when it describes the same knowledge. +4. Otherwise, create a UTF-8 Markdown concept with YAML frontmatter following the concept template from [templates/concept.md](templates/concept.md): set adescriptive `type`, fill recommended fields, record `generated` and the `sources` you actually read, cross-link related concepts via normal Markdown links. +5. Validate (see below). Fix every error before finishing. + +### Consume — use a bundle as context + +1. Read the bundle-root `index.md` first for progressive disclosure, then follow + links only into the concepts relevant to the task. +2. Weigh what you read: `status: draft`/`deprecated`, a `stale_after` already + past, or no `verified` entry all mean "check before relying on this". Treat + broken links as not-yet-written knowledge, not errors. +3. Need a number an `Attested Computation` covers? Run *its* computation with + values bound to the declared `parameters` — never write your own query. +4. If you learn something durable while working, switch to **maintain** and + write it back. + +## Maintain - keep a bundle in sync with reality + +1. Identify which concepts the change affects (search by `resource`, path, or + topic). This bookkeeping is exactly what agents are good at — touch every + affected file in one pass. +2. Update the body and `generated.at` (with your own actor in `generated.by`); + fix or add cross-links; create new concepts for new assets; mark removed + assets `status: deprecated` and note the deprecation in `log.md` rather than + silently deleting context. Facing a whole v0.1 bundle rather than a stray + field? Do not hand-edit it — run the validator's `--migrate` once. +3. Update the relevant `index.md` files and append a dated `log.md` entry + describing what changed. +4. Validate. + +## Validation (do this before declaring done) + +1. Run `okf index brain`. +2. Run `okf check brain`. +3. Fix every finding. From c231d9fc402dc5f738baf1a207f041c505f71708 Mon Sep 17 00:00:00 2001 From: Emilio Balda Date: Fri, 4 Sep 2026 12:54:56 +0300 Subject: [PATCH 4/4] chore: centralized onboarding asks first agent to be the maintainer --- skills/okf/onboarding-SKILL-centralized.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/okf/onboarding-SKILL-centralized.md b/skills/okf/onboarding-SKILL-centralized.md index d988d68..fabbf27 100644 --- a/skills/okf/onboarding-SKILL-centralized.md +++ b/skills/okf/onboarding-SKILL-centralized.md @@ -53,9 +53,9 @@ or type when it makes the knowledge easier to find. There is only ONE maintainer agent. -- Maintainer Agent: `` +- Maintainer Agent: `` -TO COMPLETE THE ONBOARDING, YOU MUST FILL IT WITH AN AGENT ID AND REMOVE THIS LINE. +TO COMPLETE THE ONBOARDING, YOU MUST FILL IT WITH YOUR AGENT ID AND REMOVE THIS LINE. YOU ARE NOW THE MAINTAINER. NOTIFY THE USER ABOUT THIS. Everyone can produce and consume, but only the maintainer is allowed to carry the following steps: