Add onboarding flow for second brain modalities - #8
Merged
Merged
Conversation
- 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 <cursoragent@cursor.com>
There was a problem hiding this comment.
🟡 Changes recommended
The centralized modality instructions contain a contradiction about whether non-maintainer agents may edit existing concepts, and there’s an undocumented removal of CONTRIBUTING.md.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR introduces an onboarding flow to choose a single “second brain modality” (peer-to-peer vs centralized) and restructures agent instruction files so the repository can be configured once and then keep only the chosen modality’s guidance.
Changes:
- Add
ONBOARDING.mdand repointAGENTS.md/CLAUDE.mdto it during the onboarding phase. - Split the prior OKF skill content into modality-specific onboarding skill templates and make
skills/okf/SKILL.mda temporary placeholder until onboarding completes. - Remove
CONTRIBUTING.md(not mentioned in the PR description).
File summaries
| File | Description |
|---|---|
| skills/okf/SKILL.md | Replaces the prior skill content with an onboarding placeholder redirect. |
| skills/okf/onboarding-SKILL-peer-to-peer.md | Adds peer-to-peer modality instructions (template to be copied into SKILL.md). |
| skills/okf/onboarding-SKILL-centralized.md | Adds centralized modality instructions (template to be copied into SKILL.md). |
| ONBOARDING.md | Adds the modality selection + application steps. |
| AGENTS.md | Temporarily repoints agents to onboarding instructions. |
| CLAUDE.md | Temporarily repoints Claude to onboarding instructions. |
| CONTRIBUTING.md | Deleted contributor guidance file. |
Review details
Suppressed comments (3)
skills/okf/onboarding-SKILL-centralized.md:37
- Typo: "set adescriptive
type" is missing a space; it should read "set a descriptivetype".
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.
skills/okf/onboarding-SKILL-centralized.md:62
- Minor grammar: "Take look" should be "Take a look".
1. Take look at the changes since the last maintainer commit (i.e., commit message starts with `maintain:`).
skills/okf/onboarding-SKILL-centralized.md:65
- Minor wording: "contradicting information" should be "contradictory information".
affected file in one pass. Make sure to spot common concepts, patterns, decisions, and contradicting information.
- Files reviewed: 7/7 changed files
- Comments generated: 5
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+22
to
+23
| 3. Update [AGENTS.md](AGENTS.md) and [CLAUDE.md](CLAUDE.md): point them at | ||
| `skills/okf/SKILL.md` again, not this file. |
Comment on lines
+34
to
+38
| 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. |
Comment on lines
+1
to
+4
| # Onboarding | ||
|
|
||
| This second brain supports more than one modality. Pick one modality before | ||
| you store or read any memory. |
Comment on lines
+1
to
+3
| # 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. | ||
|
|
||
| ## 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. | ||
|
|
||
| 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 | ||
| 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) |
| 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. |
There was a problem hiding this comment.
🔵 Needs a closer look
The new onboarding templates contain several concrete instruction/clarity issues (including workflow contradictions and typos) that could mislead agents during onboarding.
Review details
Suppressed comments (8)
Previously missed (2) — in code that hasn't changed since the last review.
skills/okf/onboarding-SKILL-centralized.md:24
- The centralized modality relies on
brain/raw/as an inbox, but the repo currently has nobrain/raw/directory committed. Adding an explicit instruction to createbrain/raw/(and anindex.mdfor it) will prevent onboarding confusion and avoid agents writing files into a path that doesn't exist yet.
This issue also appears on line 54 of the same file.
skills/okf/onboarding-SKILL-centralized.md:37
- Typo in the instructions: "adescriptive" should be "a descriptive".
This issue also appears on line 62 of the same file.
skills/okf/onboarding-SKILL-peer-to-peer.md:30
- Typo in the instructions: "adescriptive" should be "a descriptive".
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.
skills/okf/onboarding-SKILL-centralized.md:38
- In the centralized modality you state that entries in
brain/raw/are immutable (never edited/deleted), but the Produce steps still instruct agents to "Update an existing concept". This conflicts with the centralized workflow and could lead to agents editing existing files inraw/.
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.
skills/okf/onboarding-SKILL-centralized.md:58
- This onboarding placeholder is written in all-caps and asserts "YOU ARE NOW THE MAINTAINER", which is easy for agents to misinterpret as an instruction to claim authority. It would be safer and clearer to keep this as a neutral placeholder note to be removed during onboarding.
There is only ONE maintainer agent.
- Maintainer Agent: `<your-agent-id>`
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.
skills/okf/onboarding-SKILL-centralized.md:65
- Grammar issues in the maintainer workflow steps ("Take look" / "contradicting information") reduce clarity.
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.
skills/okf/SKILL.md:3
- The placeholder skill header/body is written in a way that looks like an error message (all-caps) and is missing basic punctuation, which makes it harder to understand what action the reader should take.
# EMPTY SKILL DUE TO UNFINISHED ONBOARDING
If you are reading this text it means you have yet to complete the onboarding steps at [ONBOARDING.md](../../ONBOARDING.md)
ONBOARDING.md:4
CONTRIBUTING.mdis removed in this PR but that change is not called out in the PR description; if intentional, it would help to either mention it explicitly (or move any remaining guidance into README/ONBOARDING) so contributors know where to find the workflow steps.
# Onboarding
This second brain supports more than one modality. Pick one modality before
you store or read any memory.
- Files reviewed: 7/7 changed files
- Comments generated: 0 new
- Review effort level: Lite
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduces a second brain modality system, starting with two modalities:
brain/.brain/raw/; one maintainer agent processesraw/, extracts concepts, resolves conflicts, and organizesbrain/.Since only one modality applies per repo, an onboarding flow lets an agent pick a modality once, then removes the instructions for the modality it didn't choose so future agents can't accidentally read or follow them.
Changes
ONBOARDING.md: guides an agent to pick a modality, copy the matching skill intoskills/okf/SKILL.md, repointAGENTS.md/CLAUDE.md, and delete the onboarding files once done.AGENTS.mdandCLAUDE.mdatONBOARDING.mdinstead ofskills/okf/SKILL.md.skills/okf/onboarding-SKILL-peer-to-peer.md.skills/okf/onboarding-SKILL-centralized.mdfor the new centralized modality, with araw/inbox taxonomy and a maintainer-only workflow.skills/okf/SKILL.mdwith a placeholder pointing back toONBOARDING.mduntil onboarding completes.Testing
Not applicable — documentation/instruction changes only.
Made with Cursor