Git Structure Rules
Purpose: Standard git hygiene for the multi-tenant tree. Read BEFORE git init, gh repo create, or any commit decision.
1. Repo placement matrix
| Repo type | Canonical home | GitHub org/owner | Visibility default |
|---|
| ALAI product (Bilko, Drop, Tok) | ~/business/ALAI-Holding-AS/products/<product>/ | johnatbasicas/<product> | private until launch |
| ALAI internal CLI / SDK / library | ~/projects/<repo-name>/ | johnatbasicas/<repo> | public if open-source |
| ALAI infra workspace | ~/aisystem/ | n/a | n/a |
| ALAI Tech DOO (RS subsidiary) | ~/business/ALAI-Tech-DOO/ | alai-tech-doo/<repo> | private |
| Client-owned repo | ~/clients-external/<client>/ | client's GitHub org | client's choice |
| Personal scholarly project | ~/personal/scholarly/<topic>/ | johnatbasicas/<topic> | public (transparency) |
| System orchestration | ~/system/ | johnatbasicas/alai-system | private |
2. Required files per repo type
| File | When required |
|---|
README.md | Always |
CLAUDE.md | Every repo where agents will be dispatched |
BUILD-BLUEPRINT.md | Repos that build/deploy (per ZAKON PI2) |
DEPLOY-MAP.md | Repos with live deploys (CF Pages, Cloud Run, App Runner, etc.) |
.gitignore | Always — see Section 4 |
.github/workflows/deploy*.yml | Repos with CI/CD |
LICENSE | Public repos (default MIT for ALAI products) |
3. Commit conventions — Conventional Commits (mandatory)
<type>(<scope>): <subject> (MC #<id>)
<body — what changed and why>
Co-Authored-By: <persona-name> <noreply@alai.no>
type ∈ feat | fix | chore | docs | style | refactor | perf | test | ci | build
4. .gitignore standards
Universal (every repo)
# OS
.DS_Store
Thumbs.db
# Editor / IDE
.vscode/
.idea/
*.swp
.aider*
.claude-scratch/
# Secrets — NEVER COMMIT
.env
.env.*
!.env.example
*.pem
*.key
id_rsa*
*.p12
.bw-session
# Logs
*.log
logs/
# Build outputs
dist/
build/
out/
target/
.next/
.nuxt/
.output/
.turbo/
Node-specific
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
*.tfstate
*.tfstate.*
*.tfplan
.terraform/
.terraform.lock.hcl
crash.log
5. Anti-patterns — explicitly forbidden
| Anti-pattern | Why it's bad | Correct alternative |
|---|
git add . without reviewing diff | Commits unwanted files (.env, tfstate, secrets, IDE configs) | git add -p or explicit paths |
Committing .env "for now" | Secrets in git history forever | Bitwarden / .env.example pattern |
| Force-push to shared/master | Destroys teammates' work | PRs only; force-push only on private feat branches |
| Cross-tenant repos | Tenant contamination, IP confusion | Split into 2 repos, separate orgs ideally |
| Tags pushed before work is verified live | Tag points to broken state | Tag AFTER curl 200 + Playwright pass |
6. References
- ADR-023:
~/system/architecture/decisions/ADR-023-anvil-tenant-restructure-2026-05-07.md - Tree blueprint:
~/system/specs/anvil-tree-blueprint-2026-05-07.md - Canonical registry:
~/system/specs/canonical-registry.md - ZAKON PI2 (deploy verification):
~/system/rules/zakon-pi2-deploy-verification.md - Conventional Commits spec: https://www.conventionalcommits.org/en/v1.0.0/