agent-team/skills/conventions.md

name	description
conventions	Core coding conventions and quality priorities for all projects.

Quality priorities (in order)

1. Documentation — dual documentation strategy:
   • Inline: comments next to code explaining what it does
   • External: markdown files suitable for mdbook. Every module/component gets a corresponding .md doc covering purpose, usage, and design decisions.
   • READMEs: each major directory gets a README explaining why it exists and what it contains
   • Exception: helper/utility functions only need inline docs, not external docs
2. Maintainability — code is easy to read, modify, and debug. Favor clarity over cleverness.
3. Reusability — extract shared logic into well-defined interfaces. Don't duplicate. Helper functions specifically should be easy to cleanly isolate for reuse across the codebase.
4. Modularity — clean separation of duties and logic. Each file/module should have a cohesive purpose — not necessarily a single purpose, but a group of related responsibilities that belong together. Avoid both god files and excessive fragmentation.

Naming

• Default to snake_case unless the language has a stronger convention (e.g., camelCase in JavaScript, PascalCase for C++ classes)
• Language-specific formats take precedence over personal preference
• Names should be descriptive — no abbreviations unless universally understood
• No magic numbers — extract to named constants

Commits

• Use conventional commit format: type(scope): description
  • Types: feat, fix, refactor, docs, test, chore, style, perf
  • Scope is optional but recommended (e.g., feat(auth): add JWT middleware)
  • Description is imperative mood, lowercase, no period
• One logical change per commit — don't bundle unrelated changes
• Commit message body (optional) explains why, not what

Error handling

• Return codes: 0 for success, non-zero for error
• Error messaging uses three verbosity tiers:
  • Default: concise, user-facing message (what went wrong)
  • Verbose: adds context (where it went wrong, what was expected)
  • Debug: full diagnostic detail (stack traces, variable state, internal IDs)
• Propagate errors explicitly — don't silently swallow failures
• Match the project's existing error patterns before introducing new ones

Logging

• Follow the same verbosity tiers as error messaging (default/verbose/debug)
• Log at boundaries: entry/exit of major operations, external calls, state transitions
• Never log secrets, credentials, or sensitive user data

Testing

• New functionality gets tests. Bug fixes get regression tests.
• Tests should be independent — no shared mutable state between test cases
• Test the interface, not the implementation — tests shouldn't break on internal refactors
• Name tests to describe the behavior being verified, not the function being called

Interface design

• Public APIs should be stable — think before exposing. Easy to extend, hard to break.
• Internal interfaces can evolve freely — don't over-engineer internal boundaries
• Validate at system boundaries (user input, external APIs, IPC). Trust internal code.

Security

• Never trust external input — validate and sanitize at system boundaries
• No hardcoded secrets, credentials, or keys
• Prefer established libraries over hand-rolled crypto, auth, or parsing

File organization

• Directory hierarchy should make ownership and dependencies obvious
• Each major directory gets a README explaining its purpose
• If you can't tell what a directory contains from its path, reorganize
• Group related functionality cohesively — don't fragment for the sake of "single responsibility"

General

• Clean separation of duties — no god files, no mixed concerns
• Read existing code before writing new code — match the project's patterns
• Minimize external dependencies — vendor what you use, track versions