solpbc.org
personal memory agent
1# Coding Standards
2
3## Language & Tools
4
5- **Ruff** (`make format`) - Formatting, linting, and import sorting
6- **mypy** (`make check`) - Type checking
7- Configuration in `pyproject.toml`
8
9## Naming Conventions
10
11- **Modules/Functions/Variables**: `snake_case`
12- **Classes**: `PascalCase`
13- **Constants**: `UPPER_SNAKE_CASE`
14- **Private Members**: `_leading_underscore`
15
16## Code Organization
17
18- **Imports**: Prefer absolute imports, grouped (stdlib, third-party, local), one per line
19- **Docstrings**: Google or NumPy style with parameter/return descriptions
20- **Type Hints**: Should be included on function signatures (legacy helpers may still need updates)
21- **File Structure**: Constants → helpers → classes → main/CLI
22
23## File Headers
24
25All source code files (but not text or markdown files or prompts) must begin with a license and copyright header:
26
27```
28# SPDX-License-Identifier: AGPL-3.0-only
29# Copyright (c) 2026 sol pbc
30```
31
32Use `//` comments for JavaScript files.
33
34## Development Principles
35
36- **DRY, KISS, YAGNI**: Extract common logic, prefer simple solutions, don't over-engineer
37- **Single Responsibility**: Functions/classes do one thing well
38- **Conciseness & Maintainability**: Clear code over clever code
39- **Robustness**: Minimize assumptions that must be kept in sync across the codebase, avoid fragility and increasing maintenance burden.
40- **Self-Contained Codebase**: All code that depends on this project lives within this repository—never add backwards-compatibility shims, fallback aliases, re-exports for moved symbols, deprecated parameter handling, or legacy support code. When renaming or removing something, update all usages directly. For journal data format changes, write a migration script (see [docs/APPS.md](docs/APPS.md) for `maint` commands) instead of adding compatibility layers.
41- **Trust system path resolution**: Never set `_SOLSTONE_JOURNAL_OVERRIDE` or bypass `get_journal()` from application code, agent prompts, subprocess environments, or service files. The env var exists only for tests and Makefile sandboxes. See `reference/environment.md`.
42- **Security**: Never expose secrets, validate/sanitize all inputs
43- **Performance**: Profile before optimizing
44- **Git**: Small focused commits, descriptive branch names. Run git commands directly (not `git -C`) since you're already in the repo.
45
46## Dependencies
47
48- **Minimize Dependencies**: Use standard library when possible
49- **All Dependencies**: Add to `dependencies` in `pyproject.toml`
50- **Package Manager**: [uv](https://docs.astral.sh/uv/) — lock file (`uv.lock`) is committed, `make install` syncs from it
51- **Installation**: `make install` (creates isolated `.venv/`, syncs deps from lock file, symlinks `sol` to `~/.local/bin`)
52- **Updating**: `make update` upgrades all deps to latest and regenerates the lock file