Conventions

Conventions in ShockStack are meant to reduce decision fatigue and keep collaboration smooth.

Commit Convention

Use Conventional Commits for every change:

• feat
• fix
• chore
• docs
• refactor
• test
• ci
• build
• perf
• style

This keeps release notes and change intent clear.

Quality Gates

• Lint and formatting checks run in workspace tasks
• Type checks and tests run as part of CI
• Pre-commit hooks enforce the same baseline locally

Workspace Rules

• Use pnpm commands for package/task execution
• Run shared tasks from repo root when possible
• Keep package dependencies scoped to where they are used

Documentation Convention

Docs should optimize for long-term accuracy:

• prioritize concepts and workflows over code dumps
• avoid hardcoded version numbers in narrative text
• reference exact files only when a user must edit one directly
• update docs in the same change when behavior changes

Code Style Principles

• Keep logic simple and explicit
• Favor small, focused modules
• Add comments for intent, not for obvious mechanics
• Prefer type-safe interfaces over implicit behavior