Skip to content

Implementation notes.

A small set of defaults, patterns and constraints that have proved useful in practice. Not rules, and not a methodology. Just the parts that kept working.

Consistent choices, deliberate reasons

The same stack appears in every project. That is a decision made once, written down, and defended each time it is questioned.

Presentation HTML · CSS · JS
No framework. No build step. No npm. Zero dependency debt. Also considerably faster.
Edge + Static CloudFront · S3
ACM certificate in us-east-1 — required for CloudFront regardless of primary region. Free tier CDN.
Compute API Gateway · Lambda · Python
Serverless scales to zero. Python for consistency across every project, not because it is the only option.
Data + Secrets DynamoDB · SSM
Single-table design, on-demand billing. SSM Parameter Store for secrets — Secrets Manager costs $0.40/secret/month. SSM is free.
Infrastructure Terraform
Never CloudFormation, never CDK. State always remote in S3. Every resource tagged.

Things that survived contact with reality

Not ideals. What is left after enough failed repos to understand what these were protecting against.

01

Spec first

Requirements before design. Design before tasks. Tasks before code. The spec is written before the code exists — as the design surface, not as documentation after the fact.

03

Cost as a constraint

Free tier budget tracked per service. Known cost traps explicitly banned before a decision gets made. LLM costs tracked per project. The discipline that makes running many parallel experiments sustainable.

04

Multi-IDE, multi-agent

Two agents working the same codebase, explicit ownership boundaries, shared context store for sync. The protocol matters more than the tools. Prevent split-brain by searching shared context before touching anything the other agent might own.

05

Build in the open

This site runs under its own governance constraints. The scanner scans real repos. Gatekeep runs on this codebase. Everything is in version control — including the deviations from standard, and the written rationale for each one.

Ten constraints from the repos

Not inherited from a framework. Things that appear in every project's constraints file because they were the answer to a problem that was encountered.

  • 01 Everything in Git. Configs, governance rules, infrastructure, agent definitions. If it is not in version control it does not reliably exist.
  • 02 No mock data. Real data or a clear error state. Mock data creates false confidence in things that do not work like the real thing.
  • 03 No framework for frontend. Plain HTML, CSS, JavaScript. No npm, no bundler, no upgrade debt. Faster to load. Faster to understand.
  • 04 Python for backends. Not because it is the only option. Because consistency across every project means every project is navigable by the same people and tools.
  • 05 Terraform only. Never CloudFormation, never CDK. State always remote. All resources tagged. Predictable, reviewable, diffs that mean something.
  • 06 Spec before code. Requirements, then design, then tasks. The order matters. You ship better things when you understand what you are building before the first line is written.
  • 07 Type hints on all function signatures. No exceptions. If the signature is ambiguous, the code is ambiguous. Agents and humans both read signatures before reading bodies.
  • 08 Credentials never in code. Always in a secrets store, read at runtime. This bites everyone at least once. Rotate first, investigate second.
  • 09 Governance before shipping. The checks run before the deploy, not after the incident. The gates are not a ceremony — they are the reason the deploys are uneventful.
  • 10 Document the deviation. When you break a standard, write down why. The standard exists for a reason; so does the exception. Future teams — and future agents — need to know both.

This site runs under these constraints

The scanner runs against real repos. Gatekeep runs on this codebase — including the deviations from standard (SSM over Secrets Manager; Lambda self-invoke over SQS; dataclasses over Pydantic), each documented with the constraint that justified it.