GenericAgent's core is ~3K lines. Every file in this repo will be read by AI agents — potentially thousands of times. Extra words cost real tokens and push useful context out of the window, increasing hallucinations. This document practices what it preaches: say only what matters.
- Read the codebase first. It's small enough to read in one sitting. Understand the philosophy before proposing changes.
- Open an Issue first for anything non-trivial. Discuss before coding.
All PRs go through a strict automated code review skill. Key expectations:
- Self-documenting code, minimal comments. If code needs a paragraph to explain, rewrite it.
- Compact and visually uniform. Fewer lines, consistent line lengths, no fluff.
- Small change radius. Changing A shouldn't ripple through B, C, D.
- More features → less code. Good abstractions make the codebase shrink, not grow.
- Let it crash by failure radius. Critical errors fail loud; trivial ones pass silently. No blanket try-catch.
⚠️ This review is deliberately strict — most AI-generated code (e.g. Claude Code output) will not pass as-is. Read the full principles before submitting.
GenericAgent evolves through skills. Not all skills belong in the core repo:
| Type | Where it goes | Example |
|---|---|---|
| Fundamental / universal | Core repo (memory/) |
File search, clipboard, basic web ops |
| Domain-specific / niche | Skill Marketplace (coming soon) | Stock screening, food delivery, specific API integrations |
If your skill only makes sense for a specific workflow, it's a marketplace candidate, not a core PR.
- Issue linked or context explained in ≤3 sentences
- Code passes the [review principles] self-check:
- Can I safely modify this locally without reading the whole codebase?
- Is there a clear core abstraction — new features add implementations, not modify old logic?
- Are change points converging at boundaries, not scattered everywhere?
- On failure, can I quickly locate the responsible module?
- Net line count: ideally negative or zero for refactors
- No unnecessary dependencies added