engineering-handbook/README.md

Engineering Handbook

Engineering conventions and best practices for Sea Haven Industries.

Contents

• Naming Conventions -- kebab-case everywhere, no exceptions
• Development Environment -- workstation directory layout, pyenv, Node, launchd/TCC
• Issue Tracking -- Jira projects, ticket description template, ticket hygiene
• Git Workflow -- feature branches, incremental commits, merge to main then release for prod
• Commit Messages -- Conventional Commits, type(scope) format, explain "why"
• Pull Requests -- scope, title, description format, merge strategy
• Code Review -- what to look for, giving feedback, turnaround expectations
• Code Review Rubric -- BLOCK/FIX/NIT/QUESTION finding categories and output format
• GitHub Standards -- branch defaults, repo hygiene, Environments
• AWS Infrastructure -- HCP Terraform default, remaining SAM/CDK, Lambda defaults
• HCP Terraform -- workspaces, seam, SSM deploy contract, exec roles
• Terraform Project Layout -- standard directory structure for HCP app repos
• SAM Project Layout -- remaining path for existing SAM stacks
• CDK Project Layout -- remaining path for CDK and Bedrock
• Lambda Starter Template -- remaining SAM scaffold for a Python Lambda
• Secrets and Configuration -- Secrets Manager vs SSM Parameter Store
• CI/CD Pipelines -- HCP lane default, remaining SAM/CDK reusables
• Bedrock -- cross-region inference profiles, alias pinning, KB Docker requirement
• Git Hooks -- shim for the global security pre-push hook
• Scripts -- repo provisioning, automation tooling
• CDK Constructs -- shared VPN EC2 instance construct and other reusable patterns

Contributing

See CONTRIBUTING.md.

License

This work is licensed under CC-BY-4.0. The commit messages section adapts content from commit-messages-guide by Romulo Oliveira, also licensed under CC-BY-4.0.