avizmarlon/engineering-standards

Engineering Standards and Project Governance

Every non-trivial project should have the artifacts and process gates listed below. This skill defines what to create, when, and why. Gates marked ★ block merge or release if they fail.

Core Artifacts

| Artifact | Purpose | When to Create | |---|---|---| | Charter | 1–2 page document answering: why does this project exist? Vision, scope, stakeholders (who is affected), constraints (what are the hard limits), non-goals (what this is NOT), success criteria. Think of it as the north star for all decisions that follow. | Before any implementation work — even before detailed specs. Required for any project with multiple stakeholders. | | One-pager / Executive Summary | Single page, no jargon. Problem → Solution → Expected impact → Cost → Timeline. Audience: CEO, investors, leadership without technical context. | Every business/product project. Update when direction changes. | | RFC (Request for Comments) | Structured proposal inviting review before implementing something that affects multiple components, public APIs, or process. Format: Context + Proposal + Alternatives Considered + Impact Assessment + Decision Status. | Breaking changes, major redesigns, integrations with wide impact, significant process changes. | | Specification / Design Document (SDD) | What to build, why, and the high-level approach. Distinct from architecture: this answers "what does the system do?" before detailing "how is it built?" | Every non-trivial feature. Can be a section in the RFC or a standalone document. | | Technical Design Document | Low-level implementation plan: components, interfaces, data flows, performance decisions, edge cases, pseudocode where needed. More granular than the specification. | Complex features, critical modules, performance-sensitive systems. | | Architecture.md | The system as actually built: components, communication patterns, security invariants, extension points. Must reflect real code, not the original plan. Keep it updated as the system evolves. | Every project with code. Part of the repository root. | | Architecture Decision Records (ADRs) | Immutable log of design decisions that were non-obvious or consequential. Format: Context + Decision + Rationale + Consequences + Status. Stored in docs/adr/ with timestamp in filename. | Every significant technology choice, architectural shift, or design tradeoff. | | Threat Model | Structured map of what can break or be attacked: valuable assets (data, tokens, credentials) + potential attackers + attack vectors + mitigations. Minimal format: STRIDE, or simple "What can go wrong + how we prevent it". | Any feature touching auth, user data, payments, external APIs, or permissions. Update when threat landscape changes. | | Post-mortem | Blameless analysis after an incident. Answers: what happened, timeline, root cause, impact, corrective actions (with owner and deadline). Stored in docs/post-mortems/YYYY-MM-DD-incident-title.md. Focus on systems, not people. | After any production incident or significant failure. Published internally. | | Software Bill of Materials (SBOM) | Complete, machine-readable inventory of all dependencies: name, version, license. Generated automatically via cyclonedx, syft, package-manager export, or equivalent. | Projects with compliance requirements, sensitive data, or third-party redistribution. Attach to releases. | | CONTRIBUTING.md | How to contribute: environment setup, PR workflow, code standards, review process, who to contact. Written for humans and AI agents alike. | Any open-source project or repo with multiple contributors (human or AI). | | Runbooks | Step-by-step operational procedures for routine tasks: deploy, rollback, scale infrastructure, restart service, restore backup. Stored in docs/runbooks/. Written to be executable under pressure, without requiring additional context. | Every operation that might need to happen in production. Include rollback steps. | | Playbooks | Response scripts for emergencies: "service is down at 3am — what do you do?" / "data breach detected — sequence of actions." Different from runbooks (which are routine); playbooks handle crisis scenarios. Stored in docs/playbooks/. | Projects in production serving real users. Publish in Slack, incident-response tool, or wiki. | | Build-in-Public Log / Devlog | Visible documentation of progress, milestones, and learnings for team, stakeholders, and community. Posts may live in blog, changelog, status page, or project wiki. | Projects with external visibility, community, or stakeholder reporting. Can be optional for internal-only projects. | | CHANGELOG.md | Chronological record of all releases: features, fixes, breaking changes. Follows semantic versioning. Machine-readable format (Conventional Commits) enables automated generation. | Every project with a public version or release cycle. | | PROGRESS.md or Dashboard | Executive summary of current phase, lane status, blockers, and key metrics. Updated continuously. | Business/product projects; multi-phase work. Keep it current so the next team/session knows where you are. | | SESSION-HANDOFF.md or Equivalent | Snapshot of project state for the next person/AI: what's done, what's in progress, what's blocked, next steps, any gotchas or context that won't be obvious from reading code. | Multi-session, multi-phase, or multi-person projects. Update at end of session before you leave. |

Process Gates

| Gate | Purpose | Mandatory When | |---|---|---| | Conventional Commits | Standardized commit message format: type(scope): description. Types: feat (new feature), fix (bug fix), docs, refactor, test, chore, ci, perf, build. Breaking changes: feat! or BREAKING CHANGE: footer. Enables automated CHANGELOG generation and git history parsing. | Every project with version control. Non-negotiable for generating reliable release notes. | | CI/CD Pipeline ★ | Automated build → lint → type-check → test → security scan → deploy, with failures blocking merge. Every step runs on every PR. | Every project with code. No exceptions. Failures are expected; they save time later. | | Branch Protection + PR Review Gate ★ | Main/trunk branch protected: push directly is forbidden, PR required, at least one approver, passing CI required before merge. Prevents hotfixes and bypasses that lose audit trail. | Production projects and any repo with multiple contributors. | | Security Review Gate ★ | Before merging features that expand attack surface (auth, permissions, new APIs, data handling): verify OWASP Top 10 checklist, threat model updated, no secrets exposed, inputs validated, dependencies audited. Can be manual or automated. | Features touching authentication, user data, payments, external APIs, or new permissions. | | Dependency Audit / Lockfiles ★ | Run npm audit, pip audit, or equivalent before releases. Always commit lockfiles (pnpm-lock.yaml, Pipfile.lock, Cargo.lock). Critical vulnerabilities block release. Patch or upgrade; suppressing is the last resort. | Every project with external dependencies. No exceptions. | | Secret Scanning ★ | Automated detection of secrets (API keys, tokens, passwords) in code, pre-commit and in CI. Tools: gitleaks, trufflehog, detect-secrets, or cloud provider native. Detected secrets = commit blocked. If already committed: revoke immediately, rotate credentials, assume all prior history is exposed. | Every repository, no exceptions. Set up on day 1. | | License Compliance | Verify compatibility of all dependencies' licenses with your project's license. GPL in proprietary code requires legal approval. MIT/Apache/BSD generally safe. Use license-checker or equivalent. | Proprietary projects or anything with third-party redistribution. | | Test-driven Development (TDD) | Red → Green → Refactor: write the test first (it fails), implement minimal code to pass, refactor. Guarantees code is testable and tests cover real behavior, not just happy paths. | Business logic, auth, scoring, validation, public APIs, critical modules. UI scaffolding and exploratory code can skip. | | Feature Flags / Gradual Rollout | Every new production feature launched behind a flag. Rollout: 1-5% of users → 25% → 100%. Allows reversal without redeployment. Remove flag once stable (target: 4 weeks max). Every flag has a planned removal date. | New features in production with real users. Essential for safety. | | Semantic Versioning (Semver) | Version numbering: MAJOR.MINOR.PATCH. MAJOR = breaking change, MINOR = backward-compatible feature, PATCH = bug fix. Communicate breaking changes loudly. | Every project with public releases or APIs. | | IaC / Scaffolding | All infrastructure, configuration, and environment setup as code. Repo should be rebuildable from zero with a single command (git clone + make bootstrap or equivalent). Eliminates "works on my machine" and enables disaster recovery. | Every new project. Day 1 requirement. |

Enforcement and Anti-patterns

Mandatory mindset:

• "We'll document this later" = documentation never happens when the next session starts from zero. Document now.
• Conventional commits skipped = you lose automatic CHANGELOG and commit history becomes untrackable.
• Push directly to main = bypasses review, hides decisions, makes auditing impossible.
• Secret committed "by accident" = not a typo; revoke and assume all prior history is exposed. Accidents happen; what matters is response speed.
• Feature flags that never get removed = permanent technical debt. Every flag must have a sunset date.
• No lockfile = builds are non-reproducible. "It works on my machine" is not acceptable.
• Threat model skipped because "project is small" = security breaches don't scale by project size. A small service exposed to the internet can be as broken as a large one.

Scaling the Checklist

A minimal project (experimental, internal-only) starts lean:

• Charter (one page)
• Spec (or RFC if there's debate)
• CI/CD (basic: lint + test)
• Branch protection (at least main)
• Secret scanning (day 1, non-negotiable)

Scale up as the project gains users, processes sensitive data, or becomes shared:

• Add threat modeling once auth or external APIs enter the system
• Add runbooks once ops involvement is likely
• Add playbooks once you have users to disappoint
• Add architecture documentation once there's code to understand
• Add compliance artifacts (SBOM, audit logs) if regulated

Summary: The Core Loop

1. Before code: Charter + Spec + ADRs for non-obvious choices
2. During code: TDD, secret scanning, linting, architecture design (not just implementation)
3. On merge: CI green, at least one review, threat model updated if surface changed
4. On release: CHANGELOG automated from commits, SBOM generated, feature flags staged
5. In production: Runbooks documented, monitoring active, playbooks ready for fire
6. After incident: Post-mortem captured, learnings shared, preventive ADR added if applicable

This approach trades upfront documentation time for massive gains in velocity, safety, and onboarding cost for the next person (or AI) who touches the project.

Applies to: all projects of non-trivial scope across any domain (product, infrastructure, research, internal tools, open-source).