mirror of
https://github.com/runbear-io/beardrive.git
synced 2026-08-25 08:08:08 +02:00
docs(plugin): two-file AGENTS.md orientation for shared folders
Replace the old "append conventions to CLAUDE.md" step with a two-file pattern for teaching agents a newly mounted shared folder: - <shared>/AGENTS.md (synced): the team's single source of truth for the folder's structure and conventions — scaffolded once by the project creator, read (never rewritten) by joiners. - A repo-root AGENTS.md/CLAUDE.md pointer (per machine, not synced): the awareness/routing layer. Required because discovery differs by platform — Claude Code and Hermes load nested instruction files lazily (only after entering the folder), and Codex never discovers them at all (root→cwd path only). SKILL.md gains a "Teaching agents the folder" section with the platform discovery table and a first-contact orientation ritual; /beardrive:install step 4 and /beardrive:init step 6 now offer both files as separate consents; install.md step 3 gains the same never-sync-a-repo-root hard rule init.md already had; README/CLAUDE.md descriptions updated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P5cxPQdSGJnjXCYY9GeWXt
This commit is contained in:
Snow Lee
co-authored by
Claude Fable 5
Claude Fable 5
parent
fafa00b9a6
commit
8cd886174b
@@ -62,7 +62,7 @@ The real coverage is the integration tests in `internal/syncer/syncer_test.go`:
|
||||
|
||||
## Claude Code plugin
|
||||
|
||||
`plugin/` is a Claude Code plugin (skill + `/beardrive:install` + `/beardrive:init` + `/beardrive:status` commands + turn-boundary sync hooks). `/beardrive:install` (`plugin/commands/install.md`) is the team onboarding flow: binary, login, init, a consent-gated CLAUDE.md section about the shared folder, and project-level hooks in `.claude/settings.json` (blocking pull at UserPromptSubmit, async push on PostToolUse Write/Edit) so teammates without the plugin still sync, published via the marketplace manifest at `.claude-plugin/marketplace.json` (`/plugin marketplace add runbear-io/beardrive`). The canonical skill lives at `plugin/skills/beardrive/SKILL.md`; `.claude/skills/beardrive` is a symlink to it. The hook script `plugin/scripts/beardrive-sync.sh` (and the inline project-level hook commands) must stay a fast no-op for folders without a `.bdrive/` dir — it runs on every turn in every project.
|
||||
`plugin/` is a Claude Code plugin (skill + `/beardrive:install` + `/beardrive:init` + `/beardrive:status` commands + turn-boundary sync hooks). `/beardrive:install` (`plugin/commands/install.md`) is the team onboarding flow: binary, login, init, a consent-gated two-file agent orientation (synced `<shared>/AGENTS.md` map + repo-root `AGENTS.md`/`CLAUDE.md` pointer — see SKILL.md "Teaching agents the folder"), and project-level hooks in `.claude/settings.json` (blocking pull at UserPromptSubmit, async push on PostToolUse Write/Edit) so teammates without the plugin still sync, published via the marketplace manifest at `.claude-plugin/marketplace.json` (`/plugin marketplace add runbear-io/beardrive`). The canonical skill lives at `plugin/skills/beardrive/SKILL.md`; `.claude/skills/beardrive` is a symlink to it. The hook script `plugin/scripts/beardrive-sync.sh` (and the inline project-level hook commands) must stay a fast no-op for folders without a `.bdrive/` dir — it runs on every turn in every project.
|
||||
|
||||
## Docs to keep in sync
|
||||
|
||||
|
||||
@@ -440,7 +440,8 @@ The plugin sets up everything at once:
|
||||
|
||||
- **`/beardrive:install`** — the full team setup, conversationally: CLI,
|
||||
sign-in, project init (whole folder or a shared subfolder like `wiki/`),
|
||||
a consent-gated CLAUDE.md section for agents, and project-level sync
|
||||
a consent-gated agent orientation — a synced `AGENTS.md` mapping the
|
||||
shared folder plus a repo-root pointer to it — and project-level sync
|
||||
hooks in `.claude/settings.json`.
|
||||
- **`/beardrive:init [folder] [--name/--project/--shared]`** — just start
|
||||
syncing a project; `/beardrive:status` diagnoses problems.
|
||||
|
||||
+12
-6
@@ -66,10 +66,16 @@ Follow these steps:
|
||||
|
||||
6. **Verify**: run `bdrive status <folder>` and confirm the daemon is
|
||||
running and pending is 0. Summarize: project name/id, what syncs, and
|
||||
that edits propagate to every team member within seconds. Offer a
|
||||
consent-gated CLAUDE.md note and tell the user how teammates connect
|
||||
(invite link → `bdrive init` → same `--shared` scope, which is
|
||||
per-device).
|
||||
that edits propagate to every team member within seconds. Offer the
|
||||
two-file agent orientation, each part as its own consent (full flow:
|
||||
the skill's "Teaching agents the folder" section): a synced
|
||||
`<shared>/AGENTS.md` mapping the folder — draft it if this user is
|
||||
creating the project, read and follow it if joining — and, for
|
||||
`--shared` mounts inside a repo, a short pointer to it in the repo
|
||||
root's `AGENTS.md`/`CLAUDE.md` (the only file Codex loads, and what
|
||||
makes any agent aware the folder matters). Then tell the user how
|
||||
teammates connect (invite link → `bdrive init` → same `--shared`
|
||||
scope, which is per-device).
|
||||
|
||||
For the full team setup (CLAUDE.md guidance + per-project sync hooks in
|
||||
`.claude/settings.json`), suggest `/beardrive:install` instead.
|
||||
For the full team setup (the AGENTS.md orientation + per-project sync
|
||||
hooks in `.claude/settings.json`), suggest `/beardrive:install` instead.
|
||||
|
||||
+38
-18
@@ -29,38 +29,58 @@ Otherwise ask the user two questions (or infer from their request):
|
||||
isn't needed here — `bdrive init --name <name>` creates-or-joins by name;
|
||||
`bdrive init --project <p-id>` connects by id.)
|
||||
- **Sync the whole folder, or only a shared subfolder** (e.g. `./wiki` or
|
||||
`./shared`)? A shared subfolder is right when only part of the repo — a
|
||||
company wiki, a deliverables folder — should be shared across the team.
|
||||
`./shared`)? Hard rule: **never sync a repo root** — inside a repo,
|
||||
knowledge always syncs as a scoped subfolder via `--shared`. Whole-folder
|
||||
is only for a dedicated knowledge folder (an empty dir, a standalone
|
||||
vault) that is the mount itself.
|
||||
|
||||
Then run it non-interactively, e.g.:
|
||||
```sh
|
||||
bdrive init --name <project-name> --yes # whole folder
|
||||
bdrive init --name <project-name> --shared wiki # only ./wiki syncs
|
||||
bdrive init --name <project-name> --yes # dedicated knowledge folder
|
||||
bdrive init --name <project-name> --shared wiki # in a repo: only ./wiki syncs
|
||||
```
|
||||
Re-running `bdrive init --yes` later is always safe: it resumes syncing
|
||||
(including after the folder was renamed or moved).
|
||||
|
||||
## 4. Offer to update CLAUDE.md (ask first — never do this silently)
|
||||
## 4. Teach agents about the shared folder (ask first — never do this silently)
|
||||
|
||||
Ask: "Want me to add a section to CLAUDE.md so agents know about the shared
|
||||
folder?" If yes, append a section shaped like this (adapt folder name and
|
||||
wording to the project; create CLAUDE.md if missing):
|
||||
Two files with different jobs (full rationale: the beardrive skill's
|
||||
"Teaching agents the folder" section). Offer each as its own consent:
|
||||
|
||||
**a. The folder's own map — `<shared>/AGENTS.md` (synced, team-wide).**
|
||||
If the shared folder already has an `AGENTS.md`, read it and follow it —
|
||||
it is the team's source of truth; do not rewrite it while onboarding.
|
||||
If it has none and this user is creating the project, offer to draft one:
|
||||
explore the folder (top-level dirs, naming patterns, what's actually
|
||||
there) and write a short map — what each area is for, naming conventions,
|
||||
where agents should put their output, what not to touch. Keep it under a
|
||||
screen; it syncs to every member, so write it for the whole team, not
|
||||
this machine.
|
||||
|
||||
**b. A root pointer in this repo (per machine, never synced).** For a
|
||||
`--shared` mount inside a repo, append a short section to the repo root's
|
||||
`AGENTS.md` and/or `CLAUDE.md` — both if both exist; `AGENTS.md` is what
|
||||
Codex and Hermes read (Codex never discovers nested instruction files,
|
||||
and no platform knows the folder *matters* until told). Shape it like
|
||||
this (adapt the folder name; create the file if missing):
|
||||
|
||||
```markdown
|
||||
## Shared folder (BearDrive)
|
||||
|
||||
`wiki/` is the company wiki, synced across all team members and agents via
|
||||
BearDrive. Anything saved there propagates to everyone within seconds, and
|
||||
every change is tracked (who, when, from which device).
|
||||
|
||||
- Put shareable artifacts — generated HTML/PDF/markdown reports, notes,
|
||||
plans — in `wiki/` so the team can see them.
|
||||
- To hand someone a public link to a file: `bdrive share wiki/<file>` —
|
||||
prints a URL anyone can open (rendered, no account needed).
|
||||
- Do not put secrets in `wiki/`; share links are public to whoever has
|
||||
the URL.
|
||||
`wiki/` is the team's shared folder, synced via BearDrive — changes
|
||||
propagate to everyone within seconds and every change is tracked (who,
|
||||
when, which device). Read `wiki/AGENTS.md` before working there. Put
|
||||
shareable artifacts — reports, notes, plans — in `wiki/` so the team
|
||||
sees them; never secrets (`bdrive share wiki/<file>` mints public URLs).
|
||||
```
|
||||
|
||||
Point at the synced `AGENTS.md` rather than duplicating its conventions —
|
||||
the pointer is for awareness and routing; the conventions live in the
|
||||
folder, stay current for everyone, and are versioned by the hub. For a
|
||||
standalone knowledge mount (dedicated folder, no enclosing repo) skip the
|
||||
pointer: `AGENTS.md` at the mount root is loaded natively by every
|
||||
platform.
|
||||
|
||||
## 5. Register agent sync hooks
|
||||
|
||||
Run `bdrive hooks install` in the project. It detects the agent platforms
|
||||
|
||||
@@ -25,7 +25,7 @@ Use this skill whenever the user is working with the `bdrive` CLI: initializing
|
||||
| Sign this device in (once per device) | `bdrive login [url]` — bare form uses the remembered server or beardrive.ai. Opens the sign-in page in a browser (sign-up available there); the terminal completes on its own and stores a per-device token. `--device` prints a code to approve from any browser (SSH/headless); `--status` shows server + account. Password reset: "Forgot password?" on the sign-in page (emailed via the server's SMTP config, or the link appears in the server log). **Switch hubs** with `bdrive login <new-url>`, then re-run `bdrive init` in each folder. |
|
||||
| Sign this device out | `bdrive logout` — clears the saved token + account (folders untouched); `--forget` also drops the remembered server. The device token stays valid server-side until it expires — revoke it from the hub's device list to be sure. |
|
||||
| Share a synced file publicly by URL | `bdrive share <file>` — prints a link anyone can open (HTML renders as a page, markdown rendered, PDFs inline; sandboxed; always the latest content; no account needed). `--expires 24h` for self-destructing links; `--list` / `--revoke <token-or-url>` to manage. Put generated reports in the shared folder, sync, then share. |
|
||||
| Set up a project for a Claude Code team | `/beardrive:install` — installs the CLI, signs in, runs init (whole/shared folder), offers a CLAUDE.md section about the shared folder, and registers agent sync hooks via `bdrive hooks install` (pull at turn start, push after edits, session-note stamping — for every detected platform, not just Claude) |
|
||||
| Set up a project for a Claude Code team | `/beardrive:install` — installs the CLI, signs in, runs init (whole/shared folder), offers the two-file agent orientation (synced `<shared>/AGENTS.md` map + repo-root pointer), and registers agent sync hooks via `bdrive hooks install` (pull at turn start, push after edits, session-note stamping — for every detected platform, not just Claude) |
|
||||
| Per-file / folder change history in the web UI | History button (file versions or project feed) and per-folder ⌚ — each entry: account, time, device (name/OS/IP), view/download of that exact version. API: `GET /api/p/<id>/history?path=\|prefix=`, `GET /api/p/<id>/blob?sha=` |
|
||||
| Web server: viewer + multi-project sync hub (read-only unless `--upload`) | `bdrive web [<folder> \| <storage-root-url>]` (serves cwd by default, `--addr :4173`; `-c config.json` reads remote/addr/upload/projects_db/database/auth settings from a file, explicit flags win; a storage root URL makes it a hub hosting many projects at `<root>/<project-id>/`, registry in `--projects-db` file, default `$BDRIVE_HOME/projects.json`; `--upload` lets browsers add files, client devices push, and projects be created — direct to storage via expiring presigned URLs on S3/GCS, relayed through the server for `file://`; `--upload-ttl 15m`; clients never see the remote URL or credentials; hub projects are walled by org membership — invite teammates from the web UI; the viewer has a ⌘K palette for fuzzy file search, project switching, and quick actions) |
|
||||
|
||||
@@ -206,7 +206,26 @@ Detection ladder — first match wins; if two rungs match, ask which to connect:
|
||||
|
||||
Conflict copies are named `<file>.bdrive-conflict-<device>-<timestamp>` and sync like normal files. `openknowledge validate` does **not** flag them (they aren't `.md`) — pair validate with a `*.bdrive-conflict-*` glob check when offering a post-edit validation hook.
|
||||
|
||||
Every branch ends the same way: verify (`bdrive status`, pending 0), a consent-gated CLAUDE.md note describing what syncs and how teammates connect, and the teammate onboarding sentence (invite link → `bdrive init` → same `--shared` scope).
|
||||
Every branch ends the same way: verify (`bdrive status`, pending 0), the consent-gated two-file agent orientation (next section), and the teammate onboarding sentence (invite link → `bdrive init` → same `--shared` scope).
|
||||
|
||||
### Teaching agents the folder (AGENTS.md)
|
||||
|
||||
A newly mounted shared folder is hundreds of opaque files to an agent. Two files with different jobs fix that — offer each as its own consent, never write either silently:
|
||||
|
||||
1. **The folder's own map — `<shared>/AGENTS.md` (synced, team-wide).** The single source of truth for conventions: what each area is for, naming patterns, where agents should *write* (e.g. reports → `reports/`), what not to touch. Because the folder syncs, the map travels with it — every member on every platform gets it, and hub history tracks who changed the rules. It is scaffolded **once, by the project creator** (explore the folder, draft it, keep it under a screen); joiners read it and follow it — a new member's agent must not rewrite team conventions on day one.
|
||||
2. **A root pointer (per machine, never synced).** For `--shared` mounts inside a repo, append 2–3 lines to the repo root's `AGENTS.md` and/or `CLAUDE.md` (both if both exist): the folder is shared via BearDrive, read `<shared>/AGENTS.md` before working there, put shareable artifacts there, no secrets. Point at the synced map — don't duplicate its conventions, or the copy goes stale.
|
||||
|
||||
The pointer is not optional politeness — platform discovery differs:
|
||||
|
||||
| Platform | Finds `<shared>/AGENTS.md` on its own? |
|
||||
|---|---|
|
||||
| Claude Code / Cowork | Lazily — loaded when a file in that subtree is first read |
|
||||
| Hermes | Lazily — progressive discovery; walks up from files it touches |
|
||||
| Codex | **Never** — only loads `AGENTS.md` along the root→cwd path |
|
||||
|
||||
And even where lazy loading works, it fires only *after* the agent decides to enter the folder; only the root pointer gives it the awareness to go there ("save the report where the team sees it"). A standalone knowledge mount (a dedicated folder, no enclosing repo) needs only the synced `AGENTS.md`: at the mount root every platform loads it at session start.
|
||||
|
||||
**Orientation ritual** — your own behavior in any synced folder: on first contact, read its `AGENTS.md` before substantive work. If there is none, orient from the tree plus `bdrive log <folder>` (recent changes show which areas are alive), and — if this device created the project — offer to draft `AGENTS.md` for the team.
|
||||
|
||||
### What beardrive does not sync
|
||||
|
||||
|
||||
Reference in New Issue
Block a user