Documentation at OmniForge focuses on decisions, tradeoffs, and failures — not just outcomes. Each project maintains its own detailed docs, but common patterns and principles are documented here.
Contributing Guidelines
General Principles
- Read first, code second - Understand the problem and existing solutions before proposing changes
- Document decisions - Explain why, not just what
- Embrace constraints - Work within project limitations rather than expanding scope
- Ship incrementally - Small, working improvements over large, theoretical ones
Code Standards
- Code should be readable by someone unfamiliar with the project
- Comments explain business logic and tradeoffs, not syntax
- Tests focus on behavior, not implementation details
- Dependencies are justified and documented
Issue and PR Process
- Issues first - Discuss the problem before implementing solutions
- Small PRs - Easier to review, faster to merge
- Context in commits - Commit messages explain the reasoning
- Maintainer decisions - Discussion is open, but direction is not democratic
Project Documentation
Brody
Autonomous AI assistant for proactive day preparation.
Architecture Overview:
- Event-driven system built on calendar webhooks
- Local-first data storage with optional cloud sync
- Plugin architecture for different calendar/task providers
Key Decisions:
- Privacy-first: All processing happens locally or on user-controlled infrastructure
- No AI vendor lock-in: Supports multiple LLM providers through unified interface
- Incremental adoption: Works alongside existing tools, doesn't replace them
Current Limitations:
- Google Calendar only (Outlook and others planned)
- English language only
- Requires technical setup (no one-click install yet)
Design Philosophy
Problem-First Development
Every project starts with a clear problem statement. Solutions are evaluated against this problem, not against what's technically interesting or popular.
Constraint-Driven Design
Explicit constraints force better decisions. Common constraints at OmniForge:
- No vendor lock-in - Users can export their data and switch tools
- Privacy by design - Minimal data collection, local processing when possible
- Incremental adoption - Works with existing workflows, doesn't require wholesale changes
- Open source sustainability - Maintainable by small teams over long periods
Documentation Standards
Good documentation at OmniForge includes:
- Decision records - Why choices were made, what alternatives were considered
- Failure analysis - What didn't work and why
- Constraint documentation - What the project won't do and why
- Contribution paths - Clear entry points for new contributors
Resources
External Resources
- RFC Repository - Proposals and design discussions
- Organization Docs - Governance and community guidelines