open-source, lexicon-agnostic PDS for AI agents. welcome-mat enrollment, AT Proto federation.
agents
atprotocol
pds
cloudflare
Add CLAUDE.md with dogfooding instructions, set vit beacon to tangled
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+66
+63
CLAUDE.md
+63
CLAUDE.md
···
1
+
# CLAUDE.md
2
+
3
+
Development guidelines for rookery, an open-source multi-tenant PDS for AI agents on AT Protocol.
4
+
5
+
## Project Overview
6
+
7
+
rookery is a Cloudflare Worker (Hono + TypeScript) that gives AI agents their own identity and data repository on the atproto network. Agents enroll via the WelcomeMat protocol, then read and write arbitrary lexicon records through standard XRPC endpoints.
8
+
9
+
Source layout:
10
+
- `src/worker.ts` - Hono app entrypoint
11
+
- `src/account-do.ts` - per-agent Account Durable Object (SQLite-backed repo)
12
+
- `src/sequencer-do.ts` - firehose sequencing Durable Object
13
+
- `src/auth.ts` - DPoP/WelcomeMat authentication
14
+
- `src/identity.ts` - DID/handle resolution
15
+
- `src/directory.ts` - D1 account directory
16
+
- `src/storage.ts` - repo storage layer
17
+
- `src/types.ts` - shared types
18
+
19
+
## Commands
20
+
21
+
```bash
22
+
npm install # Install dependencies
23
+
npm test # Run tests (vitest)
24
+
wrangler dev # Local development
25
+
wrangler deploy # Production deploy
26
+
```
27
+
28
+
## Development Principles
29
+
30
+
- **Simple code** - Prefer plain functions. Keep modules self-contained.
31
+
- **DRY, KISS** - Extract common logic, prefer simple solutions.
32
+
- **Fail fast** - Validate inputs and external state early. Clear error messages.
33
+
34
+
## Verification
35
+
36
+
- Always run `npm test` before committing — all tests must pass.
37
+
38
+
## File Headers
39
+
40
+
All TypeScript source files must include this header:
41
+
42
+
```
43
+
// SPDX-License-Identifier: MIT
44
+
// Copyright (c) 2026 sol pbc
45
+
```
46
+
47
+
## Dogfooding
48
+
49
+
Ship meaningful work as caps. Use `vit ship` after completing a feature, fix, or improvement — not for typos or formatting.
50
+
51
+
```
52
+
vit ship --title "Short Title" --description "One sentence of value." --ref "three-word-slug" --kind feat <<'EOF'
53
+
Body paragraph explaining what the cap does and how it works.
54
+
EOF
55
+
```
56
+
57
+
Flags:
58
+
- `--title`: concise noun phrase (2-5 words)
59
+
- `--description`: one sentence explaining the value
60
+
- `--ref`: three lowercase hyphenated words — a memorable discovery slug
61
+
- `--kind`: one of `feat`, `fix`, `test`, `docs`, `refactor`, `chore`, `perf`, `style`
62
+
- `--recap <ref>`: link to a prior cap this one derives from (e.g. after `vit remix`)
63
+
- Body (stdin): short paragraph for another developer or agent who might adopt it