# 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

All AI-authored commits MUST use:
```
Co-Authored-By: Svrnty Inc. <eng@svrnty.com>
```

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

## 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

When changes span multiple repos:
1. Commit to each repo separately
2. Reference related repo in commit message
3. Run tests in each affected repo before commit