AGENTS.md

Notes for AI agents (Claude Code, Codex, Hermes Agent, OpenClaw, Cursor and others) and people who change this repository. Read this before you change a skill, a template, a form or a doc.

[!NOTE] If you are an agent using Phygital Brain (building or running someone's brain, not editing this repository), follow skills/brain-setup/SKILL.md to build a brain, or skills/brain-keeper/SKILL.md for the Brain Keeper. Inside a brain, its own CLAUDE.md files are the rules.

What this is

Phygital Brain is an OS (operating system) for notes: a folder of Markdown notes in a cloud drive that works as the person's knowledge base and as the agent's operating system. It's two skills that any agent working in a folder can follow, packaged as a Claude plugin. There is no program: everything is instructions, templates and four HTML forms. Licence Apache-2.0. The name and logo are not covered (see TRADEMARKS.md).

Layout

.claude-plugin/plugin.json        the plugin: name, version, description
.claude-plugin/marketplace.json   lets people add this repo as a plugin marketplace
skills/brain-setup/SKILL.md       the setup: checks, language, four forms, build, finish, upgrade
skills/brain-setup/forms/         the four forms (HTML for the form window) and questions.md (the same in plain text)
skills/brain-setup/templates/     every file a new brain gets, with {placeholders}
skills/brain-setup/bundled/       third-party skills copied unchanged into every brain (no-ai-slop, MIT)
skills/brain-keeper/SKILL.md      installs and updates the Brain Keeper
skills/suggested-skills/          other people's skills that work with a brain: README.md (the list) and one page per skill, offered at the end of setup
skills/suggested-apps/            apps to connect (Google Workspace, Canva): README.md (the list) and one page per app, offered with the skills at the end of setup
skills/brain-keeper/templates/    daily.md, check-up.md, queue.md, the root CLAUDE.md section
skills/add-language/SKILL.md      makes a full set in a new language, or switches a brain's language
skills/brain-setup/i18n/{code}/   built language sets (don't edit: run scripts/i18n.py build)
languages/                        en.json source strings, {code}.json and {code}/ translations, TRANSLATING.md
scripts/i18n.py                   extract, build and check translations
docs/                             for people: getting started, use cases, FAQ, glossary, add more skills, importing, connect your apps, teams, limits, example brain, phone, how it works, other agents, fast search with Phygital Engram
docs/folders/                     one page per brain folder, and the main rules in plain words
docs/images/                      the README picture and the logo
languages/                        how other languages work
scripts/check.py                  the checks (no installs needed)
scripts/build_mcpb.py             builds dist/phygital-brain.mcpb, the Claude desktop extension, for the release
mcp/server.mjs                    the connector: an MCP server with no dependencies that serves skills/
package.json                      the npm package: npx -y phygital-brain runs the connector
.github/workflows/release.yml     on a push to main with a new version: checks, npm publish, the release with the .mcpb
.github/workflows/workflows.yml   on every push and pull request: zizmor checks the workflows for unsafe patterns
README.md, CHANGELOG.md, NOTICE, LICENSE, TRADEMARKS.md, CONTRIBUTING.md, SECURITY.md, CITATION.cff

How the pieces connect

1. A person says "Set up my second brain". The agent follows skills/brain-setup/SKILL.md.
2. It shows the four forms one at a time. Each answer comes back under its data-name. Step 2 of the skill sets the switches BUSINESS, BRIEF and WRITE.
3. Step 3 builds the brain from templates/, using the answers. Section 3.3 maps each answer to an About file.
4. Step 3.8 runs skills/brain-keeper/SKILL.md from its Step 2 to set up the daily tidy.
5. Inside the brain, the agent only follows the brain's own CLAUDE.md files. This repository is no longer read.

Rules that must never break

1. The templates are the source of truth. The docs explain the templates in plain words and link to them. When you change a rule in a template, change the matching doc page in the same pull request.
2. Answer names don't change. Every data-name and data-value in a form is read by SKILL.md. Rename one only together with every place that reads it. An answer nobody reads is a bug.
3. English stays English. Folder names, file names, [[links]] to files, and info block keys and values stay in English in every language. Only description: is translated.
4. "Your agent", never a product name, in anything a person sees. File names like CLAUDE.md are fine.
5. No em dashes, anywhere. Use periods, commas or colons.
6. Plain words. Short sentences, everyday words. The docs are written at about an 8th-grade reading level: plain and clear, never childish.
7. The agent asks before it creates, moves, renames or deletes a person's notes. Nothing in a skill or template may weaken that.
8. Private things stay private. .claudeignore keeps Memory/finances/. No template may copy private details (tax IDs, bank details, birth date) into other notes or replies.
9. Upgrades keep what's theirs. Their notes, their own rules (word for word), their routing rows and their folders survive every upgrade.
10. Version line. A brain's root CLAUDE.md starts with <!-- Phygital Brain, version X, language: xx -->. A new version updates it, the plugin files, package.json, the skills' "Version" lines and the CHANGELOG together, with a ## X.Y.Z (date) CHANGELOG entry. Pushing that to main runs .github/workflows/release.yml: it publishes to npm and creates the vX.Y.Z release with dist/phygital-brain.mcpb attached. Don't create releases by hand.
11. Keep the NOTICE credit: "Created by Phygital-Brain".
12. English templates are the source; translations follow. When you change a template, form or message, run python3 scripts/i18n.py extract if form text changed, update languages/en.json, and mark the change for every language (translate it, or open an issue). Never edit skills/brain-setup/i18n/ by hand.

Placeholders

Path patterns like Projects/{name}/, {title}, {topic}, {skill-name} and {client-name} stay in the brain as patterns. They are not filled in.

<!-- ADAPTING ... --> comments at the top of a template are instructions for the agent. They never reach the brain.

Checking a change

1. python3 scripts/check.py must pass.
2. For a change to a skill, a form or a template: build a test brain in an empty folder with your change, as two people (one who sells and wants a brief, one who doesn't), and read what was built. For an upgrade change, also upgrade a copy of an older brain.
3. Add a line to CHANGELOG.md.