Co-VibeDocs

Engineering

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.
View as .md