# Development Guidelines

Universal development practices for all Svrnty/a-gent repositories.

## Engineering Principles

### KISS (Keep It Simple)
- Prefer straightforward control flow over clever meta-programming
- Keep error paths obvious and localized

### YAGNI (You Aren't Gonna Need It)
- Do not add features without concrete accepted use case
- Do not introduce speculative abstractions

### DRY + Rule of Three
- Duplicate small logic when it preserves clarity
- Extract shared utilities only after 3+ repeated patterns

### SRP + ISP (Single Responsibility + Interface Segregation)
- Keep each module focused on one concern
- Avoid "god modules" mixing multiple responsibilities

### Fail Fast + Explicit Errors
- Prefer explicit errors for unsupported states
- Document fallback behavior when intentional

### Secure by Default
- Deny-by-default for access boundaries
- Never log secrets or sensitive payloads

## Agent Workflow

1. **Read before write** - Inspect existing code before editing
2. **Define scope** - One concern per PR
3. **Implement minimal patch** - Apply KISS/YAGNI explicitly
4. **Validate** - Run lint, format, test before commit
5. **Document impact** - Note behavior changes and risks

## Branch Strategy

- All repos use `JP` branch for active development
- Always verify current branch before committing

## Commit Rules

### Allowed Authors
Only these emails are permitted for commits:
- `jp@svrnty.io` (Jean-Philippe Brule)
- `mathias@svrnty.io` (Mathias Beaulieu-Duncan)

Configure with: `git config user.email jp@svrnty.io`

### AI-Assisted Commits
All AI-authored commits MUST include:
```
Co-Authored-By: Svrnty Inc. <jp@svrnty.io>
```

NEVER use third-party AI tool/company names in commits.

### Git Hooks Setup
Install lefthook to enforce commit standards:
```bash
brew install lefthook
lefthook install
```

The hooks automatically:
- Validate author email is in allowed list
- Append Co-Authored-By footer
- Warn on conventional commit format violations

## PR Discipline

- Clear, scoped commit messages
- Small PRs preferred
- Never commit personal/sensitive data
- Reference related repos for cross-repo changes

## Validation

Run before every commit:
- Format check (language-specific)
- Lint check (language-specific)
- Test suite

## Anti-Patterns

- Do NOT add heavy dependencies for minor convenience
- Do NOT mix formatting-only with functional changes
- Do NOT modify unrelated modules "while here"
- Do NOT bypass failing checks without explanation

## Cross-Repo Changes

- Each repo is standalone with its own build configuration
- Reference related repos in commit messages for cross-repo changes
- Coordinate multi-repo changes via matching branch names
- Test each repo independently before pushing