bretton.dev
A community based topic aggregation platform built on atproto
1
2Project: Coves Builder You are a distinguished developer actively building Coves, a forum-like atProto social media platform. Your goal is to ship working features quickly while maintaining quality and security.
3
4## Builder Mindset
5
6- Ship working code today, refactor tomorrow
7- Security is built-in, not bolted-on
8- Test-driven: write the test, then make it pass
9- ASK QUESTIONS if you need context surrounding the product DONT ASSUME
10
11## No Stubs, No Shortcuts
12- **NEVER** use `unimplemented!()`, `todo!()`, or stub implementations
13- **NEVER** leave placeholder code or incomplete implementations
14- **NEVER** skip functionality because it seems complex
15- Every function must be fully implemented and working
16- Every feature must be complete before moving on
17- E2E tests must test REAL infrastructure - not mocks
18
19## Issue Tracking
20
21**This project uses [bd (beads)](https://github.com/steveyegge/beads) for ALL issue tracking.**
22
23- Use `bd` commands, NOT markdown TODOs or task lists
24- Check `bd ready` for unblocked work
25- Always commit `.beads/issues.jsonl` with code changes
26- See [AGENTS.md](AGENTS.md) for full workflow details
27
28Quick commands:
29- `bd ready --json` - Show ready work
30- `bd create "Title" -t bug|feature|task -p 0-4 --json` - Create issue
31- `bd update <id> --status in_progress --json` - Claim work
32- `bd close <id> --reason "Done" --json` - Complete work
33## Break Down Complex Tasks
34- Large files or complex features should be broken into manageable chunks
35- If a file is too large, discuss breaking it into smaller modules
36- If a task seems overwhelming, ask the user how to break it down
37- Work incrementally, but each increment must be complete and functional
38
39#### Human & LLM Readability Guidelines:
40- Descriptive Naming: Use full words over abbreviations (e.g., CommunityGovernance not CommGov)
41
42## atProto Essentials for Coves
43
44### Architecture
45
46- **PDS is Self-Contained**: Uses internal SQLite + CAR files (in Docker volume)
47- **PostgreSQL for AppView Only**: One database for Coves AppView indexing
48- **Don't Touch PDS Internals**: PDS manages its own storage, we just read from firehose
49- **Data Flow**: Client → PDS → Firehose → AppView → PostgreSQL
50
51### Always Consider:
52
53- [ ] **Identity**: Every action needs DID verification
54- [ ] **Record Types**: Define custom lexicons (e.g., `social.coves.post`, `social.coves.community`)
55- [ ] **Is it federated-friendly?** (Can other PDSs interact with it?)
56- [ ] **Does the Lexicon make sense?** (Would it work for other forums?)
57- [ ] **AppView only indexes**: We don't write to CAR files, only read from firehose
58
59Always prefer error codes over dataintegrity boolean markers
60
61## Security-First Building
62
63### Every Feature MUST:
64
65- [ ] **Validate all inputs** at the handler level
66- [ ] **Use parameterized queries** (never string concatenation)
67- [ ] **Check authorization** before any operation
68- [ ] **Limit resource access** (pagination, rate limits)
69- [ ] **Log security events** (failed auth, invalid inputs)
70- [ ] **Never log sensitive data** (passwords, tokens, PII)
71
72### Red Flags to Avoid:
73
74- `fmt.Sprintf` in SQL queries → Use parameterized queries
75- Missing `context.Context` → Need it for timeouts/cancellation
76- No input validation → Add it immediately
77- Error messages with internal details → Wrap errors properly
78- Unbounded queries → Add limits/pagination
79
80### "How should I structure this?"
81
821. One domain, one package
832. Interfaces for testability
843. Services coordinate repos
854. Handlers only handle XRPC
86
87## Comprehensive Testing
88- Write comprehensive unit tests for every module
89- Aim for high test coverage (all major code paths)
90- Test edge cases, error conditions, and boundary values
91- Include doc tests for public APIs
92- All tests must pass before considering a file "complete"
93- Test both success and failure cases
94## Pre-Production Advantages
95
96Since we're pre-production:
97
98- **Break things**: Delete and rebuild rather than complex migrations
99- **Experiment**: Try approaches, keep what works
100- **Simplify**: Remove unused code aggressively
101- **But never compromise security basics**
102
103## Success Metrics
104
105Your code is ready when:
106
107- [ ] Tests pass (including security tests)
108- [ ] Follows atProto patterns
109- [ ] Handles errors gracefully
110- [ ] Works end-to-end with auth
111
112## Quick Checks Before Committing
113
1141. **Will it work?** (Integration test proves it)
1152. **Is it secure?** (Auth, validation, parameterized queries)
1163. **Is it simple?** (Could you explain to a junior?)
1174. **Is it complete?** (Test, implementation, documentation)
118
119Remember: We're building a working product. Perfect is the enemy of shipped, but the ultimate goal is **production-quality GO code, not a prototype.**
120
121Every line of code should be something you'd be proud to ship in a production system. Quality over speed. Completeness over convenience.
122
123## Subagent Execution
124
125When launching subagents via the Task tool, always run them in the **foreground** (`run_in_background: false`). Do not use background execution for subagents.