Automated Code Quality Enforcement: Git Hooks and Kiro Agent Hooks#

This project enforces code quality through a combination of git hooks (formerly managed by Husky, now by pre-commit) and Kiro agent hooks. These mechanisms ensure that code meets formatting, linting, type safety, and testing standards before it is committed or pushed, and that documentation and code analysis remain up to date.

Pre-commit and Pre-push Hooks#

Pre-commit Hook#

The pre-commit hook runs automatically on git commit. It performs the following checks and fixes:

• Formats staged files using Prettier (JavaScript, TypeScript, JSON, YAML)
• Runs TypeScript type checking
• Runs ESLint for linting and code style enforcement
• Performs general file quality checks (trailing whitespace, end-of-file fixes, YAML/JSON validation, large files, merge conflicts, private keys)

These checks are configured in .pre-commit-config.yaml and are executed via the pre-commit Python package. To install and activate these hooks:

pip install pre-commit
pre-commit install

Alternatively, use the project’s setup script or justfile:

just install-hooks
# or
./scripts/setup.sh

Pre-push Hook#

The pre-push hook runs automatically on git push. It ensures that:

• TypeScript type checking passes across all workspaces
• All test suites (backend, frontend, integration, E2E) pass

This prevents broken or untested code from being pushed to the repository. The pre-push logic is typically wired through npm scripts:

"pre-push": "npm run type-check && npm run test -- --silent"

Lint-staged Usage#

The project previously used lint-staged with Husky to run linters and formatters only on staged files. This has been replaced by pre-commit hooks, which provide similar staged-file checks and more extensibility. There is currently no lint-staged configuration; all staged checks are handled by pre-commit and npm scripts.

Kiro Agent Hooks#

Kiro agent hooks provide continuous, automated enforcement and analysis beyond git hooks. These are defined in .kiro/hooks/ and include:

• CI Check Validator: Runs just ci-check to validate code quality, including linting, formatting, type checking, and all tests. If any check fails, the agent analyzes and fixes issues, then re-runs the checks until all pass. This is triggered manually or by CI pipelines [source].
• Code Quality Analyzer: Monitors changes to TypeScript source files and triggers automated analysis for code smells, design patterns, best practices, readability, maintainability, performance, type safety, and error handling [source].
• Documentation Sync on Source Changes: Watches for changes in source, config, and API spec files. When changes are detected, the agent prompts for documentation updates in README.md or /docs to keep documentation in sync with code [source].
• Format Code on Save: Automatically runs just format on save for code and documentation files to maintain consistent styling [source].
• Update LLMs.txt File: Updates llms.txt when documentation files are edited, following the llmstxt.org specification [source].

Type Checking, Linting, Formatting, and Test Suite Execution#

• Type Checking: Uses TypeScript across all workspaces. Run manually with just type-check or npm run type-check.
• Linting: Uses ESLint with TypeScript and React plugins. Run with just lint or npm run lint.
• Formatting: Uses Prettier. Run with just format or npm run format.
• Testing: Includes backend, frontend, integration, and E2E tests. Run with just test, just test-backend, just test-frontend, just test-integration, or just test-e2e.

CI Validation#

CI validation is enforced both locally and in CI pipelines:

• Local CI Check: Run just ci-check to execute linting, formatting, type checking, all tests, and coverage. This is also the command used by the CI Check Validator Kiro hook.
• CI Pipelines: The .github/workflows/ci.yml workflow runs the same suite of checks on every pull request and push to main branches.

Troubleshooting#

If hooks fail, check the following:

• Port Conflicts: Stop existing services with docker compose down or change ports in docker-compose.yml and update .env files.
• Database Issues: Reset MongoDB with docker compose down -v and docker compose up -d mongodb. View logs with docker compose logs mongodb.
• Dependency Issues: Clean install with:
  Copy

  rm -rf node_modules package-lock.json
  rm -rf backend/node_modules frontend/node_modules shared/node_modules
  npm install
  

• Manual Quality Checks: Run just lint, just format, just type-check, and just test to identify and fix issues.

Skipping Hooks#

To skip hooks in emergencies (not recommended), use the --no-verify flag:

git commit --no-verify
git push --no-verify

Use this only when absolutely necessary, as it bypasses all automated quality checks and may allow broken or non-compliant code into the repository [source].

Summary of Enforcement Workflow#

This workflow ensures that code quality, consistency, and documentation are maintained at every stage of development and collaboration.