# Repo Rules

These are hard rules for Co-Vibe.

## File Size

No source or documentation file may be over 300 lines.

Generated dependency lockfiles are exempt because reproducible installs matter.

If a file approaches 250 lines, split it.

Good splits:

- route by feature
- component by responsibility
- schema by domain
- tests by behavior
- docs by topic

## Folder Discipline

Every file belongs in the right folder.

Allowed root files:

- `README.md`
- `AGENTS.md`
- `CLAUDE.md`
- `DESIGN.md` (design directive; pairs with the vendored `design-system/`)
- `TODOS.md`
- package/config files required by tools
- license files

Product docs go in `docs/product/`.

Build-loop docs go in `docs/ops/`.

Engineering rules and architecture docs go in `docs/engineering/`.

Reports go in `reports/`.

Tests go next to the code they test or in a clear `tests/` folder.

## Documentation

Documentation must stay up to date.

If behavior changes, update docs in the same work unit.

Required docs:

- problem statement
- build-loop target
- repo rules
- architecture notes
- MCP setup
- auth setup
- testing instructions
- known limitations

## No Deferred Feature Code

Do not add code for future features.

Do not leave:

- unused components
- unused routes
- fake services
- placeholder files
- TODO-only modules
- "coming soon" code paths
- snippets that are not wired into the product

Docs may mention future ideas, but code should only contain working behavior.

`npm run check:files` enforces both the 300-line limit and deferred-code markers
in runtime/product paths (`src`, `scripts`, and `bin`). The deferred-code scan
checks tracked files plus unignored untracked files.

## Security

Security checks must pass before claiming work is done.

Minimum checks:

- dependency audit
- secret scan
- auth route review
- MCP token handling review
- permission check for protected routes
- no secrets in git

If a check fails, the morning report must list the severity and exact next step.

## Open Source Reuse

If a trusted open-source project solves a problem, use it or learn from it.

Trust starts at:

- at least 1,000 stars when a comparable project exists
- active maintenance
- compatible license
- no obvious security red flags
- fits our architecture

Do not copy code without checking the license.

Do not pull in a giant platform to solve a small problem.

## Quality Gates

Before "done":

- tests pass
- browser/user-flow QA runs
- security checks pass
- docs are current
- no file is over 300 lines
- no deferred feature code exists
- morning report is written

## Extra Rules Worth Keeping

- Prefer boring, maintained dependencies.
- Use Python where it clearly helps, but document and test scripts.
- Keep the database schema explicit.
- Keep MCP tool responses structured.
- Make errors useful to agents and humans.
- Treat auth as product surface, not plumbing.
- Keep logs inspectable and exportable.
- Never make the product feel like surveillance.