The gap between writing code and engineering production systems is enormous. It is the difference between solving a problem in isolation and operating inside a system that other people depend on, that runs at scale, that must be deployed without downtime, monitored in production, debugged at 2 AM, and evolved over years by teams of people who were not there when the original decisions were made. Most CS programs do not teach this. Most graduates discover it on the job, through expensive mistakes and patient mentors — if they are lucky enough to have mentors at all.

This is the gap that Professional Software Engineering for AI and Distributed Systems is designed to close. It is a graduate-level course I am developing at Georgia Tech that treats software engineering as a discipline distinct from computer science — one that requires its own vocabulary, its own practices, and its own modes of thinking.

The Philosophy Link to heading

The course is built on a single principle:

You play like you practice.

If you practice with toy projects, unrealistic environments, and no consequences for bad decisions, you will play that way in production. If you practice with production-parity development environments, real CI/CD pipelines, and architecture decisions that must be defended in front of peers, you will carry those habits into your career.

This means Docker and devcontainers from day one — not as a topic in week twelve, but as the environment in which all coursework happens. It means dev/prod parity as a foundational constraint, not an aspiration. It means secrets management and configuration discipline before students write their first feature, because in production, misconfigured environments cause more outages than buggy code.

The course is organized around six pillars: engineering foundations, codebase and architecture mastery, distributed systems and production realism, operational excellence, AI-augmented engineering, and leadership and organizational impact. Each pillar spans multiple weeks, and each week builds on what came before.

Orion: A Deliberately Broken System Link to heading

Students do not start from scratch. They inherit a system called Orion — a Python-based distributed AI platform with a FastAPI service layer, an async worker service, PostgreSQL, Redis, a message queue, an AI integration layer, and a Docker-based development environment. It functions. It also has problems.

The CI pipeline is broken. The codebase contains intentional technical debt — tightly coupled components, missing type annotations, inconsistent error handling, implicit dependencies between services, and no observability. There are no Architecture Decision Records. There is no documentation explaining why things are the way they are.

This is deliberate. Starting with a clean codebase teaches students how to build. Starting with a messy one teaches them how to engineer — how to navigate unfamiliar systems, diagnose structural problems, introduce discipline incrementally, and make things better without breaking what already works. Every professional engineer inherits more code than they write. Orion reflects that reality.

Over the semester, students collaboratively evolve Orion into a production-ready platform. They refactor the architecture, introduce ADRs, add static typing, implement trunk-based development, build CI/CD pipelines, add observability, design safe database migrations, optimize performance and cost, secure the system against real threats, and ultimately defend their architectural decisions in a formal review.

Engineering Foundations Link to heading

The first three weeks establish the mindset and the mechanics.

Week 1 draws the line between a programmer and an engineer. A programmer writes code that works. An engineer owns a system — understands its failure modes, considers its operational characteristics, makes decisions under constraint, and accepts responsibility for the consequences. This distinction is not philosophical. It determines whether you ship a feature and walk away, or ship a feature and monitor its impact on latency, error rates, and downstream services. The week covers ownership, systems thinking, and the ethics of AI in engineering — because students will increasingly work alongside AI systems, and they need a framework for when to trust the output and when to question it.

Week 2 builds the development environment. Students configure Docker-based environments with development containers, enforce environment parity between development and production, and learn secrets management. The goal is that by the end of week two, every student can run the entire Orion stack locally with a single command, and the environment they run locally is structurally identical to the one that runs in CI. I have written previously about the importance of investing in your development environment — this week puts that philosophy into practice.

Week 3 introduces trunk-based development. Students learn to work with short-lived branches, use CI as an enforcement mechanism, implement feature flags for incomplete work, and practice rigorous code review. The emphasis is on small, frequent merges rather than long-lived feature branches — because in production, integration risk grows with branch age, and merge conflicts are a symptom of process failure, not code complexity.

Codebase and Architecture Mastery Link to heading

Weeks four and five teach students how to read and restructure large codebases.

Week 4 focuses on navigation. Static typing becomes the primary tool — not as an academic exercise, but as a means of understanding code you did not write. When a function signature tells you it accepts a TranscriptQueryParams and returns a list[Transcript], you know what it does without reading the implementation. Students learn to identify modular boundaries, detect code smells, and use type annotations as both documentation and a safety net for refactoring.

Week 5 introduces dependency inversion and composition over inheritance — the principles that separate maintainable architectures from brittle ones. Students refactor legacy code in Orion to follow clean layered architecture: interfaces defined before implementations, dependency direction enforced through physical directory boundaries, cross-cutting concerns handled through decorator composition. I have written about this architecture in detail in my post on the ideal repository structure and in the companion post on the decorator pattern for observability and resilience.

Testing and Delivery Link to heading

Weeks six and seven address how code gets validated and shipped.

Week 6 covers testing in distributed systems — a fundamentally different challenge from testing a monolithic application. Unit tests verify individual components. Integration tests verify interactions between services. Contract tests verify that service boundaries honor their agreements. Students learn to design for idempotency — ensuring that retried operations produce the same result — and to simulate failure conditions: network partitions, slow databases, unavailable downstream services. The question is not “does this work when everything is healthy?” but “does this degrade gracefully when something fails?”

Week 7 introduces CI/CD and release engineering. Students build multi-stage pipelines that enforce quality gates — formatting, linting, type checking, tests — on every commit. They learn to produce reproducible builds, design rollback strategies, and treat the deployment pipeline as code that is versioned, tested, and reviewed with the same rigor as application code.

Distributed Systems and Data Safety Link to heading

Weeks eight and nine introduce the theory and practice of building systems that span multiple processes, machines, and failure domains.

Week 8 covers distributed systems fundamentals: consistency models, the trade-offs between availability and partition tolerance, retry strategies with exponential backoff and jitter, and event-driven architecture. The emphasis is practical — students implement these patterns in Orion, not in a textbook. They experience what happens when a message is delivered twice, when a consumer crashes mid-processing, when a network timeout causes a cascade of retries that overwhelms a downstream service.

Week 9 addresses schema evolution and data safety. Databases change. APIs change. The challenge is making those changes without downtime and without breaking existing clients. Students learn zero-downtime migration patterns — expand and contract, parallel writes, backfill strategies — and implement versioned APIs that allow old clients to coexist with new ones. In production, the most dangerous deploys are not code changes. They are data changes.

Operational Excellence Link to heading

Weeks ten and eleven shift focus from building systems to running them.

Week 10 introduces observability and SRE thinking. Students instrument Orion with structured logging, metrics, and distributed tracing. They define service level objectives — not as abstract percentages, but as concrete commitments about latency, error rates, and availability that drive engineering decisions. They practice incident retrospectives: blameless postmortems that focus on systemic causes rather than individual mistakes. The goal is to shift from reactive firefighting to proactive reliability engineering.

Week 11 covers performance and cost engineering. Students learn to profile applications systematically — CPU profiling, memory profiling, query analysis — rather than guessing at bottlenecks. They run load tests against Orion and discover where the system breaks under pressure. And because Orion integrates AI services, they learn about token economics: the cost of LLM inference at scale, strategies for reducing token consumption without degrading quality, and the trade-offs between model capability and operational cost. In production, performance is not just about speed. It is about sustainability.

Security and AI Link to heading

Weeks twelve and thirteen address the two domains where the stakes are highest.

Week 12 covers security through the lens of production systems. Students perform threat modeling against Orion — identifying attack surfaces, classifying threats, and prioritizing mitigations. They learn supply chain security: dependency auditing, SBOM generation, pinned dependencies, and the risks of transitive trust. And because Orion includes an AI integration layer, they study prompt injection — how adversarial inputs can manipulate LLM behavior, and what defenses look like in practice.

Week 13 focuses on AI-augmented engineering. Not AI as a toy, and not AI as a replacement for engineering judgment — AI as a professional tool that requires the same discipline as any other tool in the stack. Students use LLMs for large-scale refactors, AI-assisted test generation, and code review augmentation. They learn to evaluate hallucinations systematically: how to detect when a model’s output is confidently wrong, how to design workflows that catch errors before they ship, and how to build the kind of engineering system I described in a previous post — where AI operates within explicit constraints rather than unconstrained improvisation. The line between leverage and liability is drawn by the discipline of the person holding the tool.

Organization and Defense Link to heading

The final two weeks connect engineering to organizational reality.

Week 14 covers the human side of software engineering: writing stories that developers can actually implement, estimating work without false precision, managing technical debt as a portfolio rather than a backlog item, and navigating the tension between shipping fast and shipping well. These are the skills that determine whether an engineer leads or follows — and they are almost never taught in CS programs.

Week 15 is the architecture defense. Each team presents the evolution of their Orion system — the decisions they made, the alternatives they considered, the trade-offs they accepted, and the evidence that supports their choices. ADRs, architecture diagrams, observability dashboards, test coverage reports, CI/CD pipeline runs, and live demonstrations. This is not a final exam. It is a simulation of the architectural review process that exists at every serious engineering organization — the moment where you must explain not just what you built, but why.

What Students Leave With Link to heading

By the end of this course, students will be able to operate inside distributed AI systems, architect responsibly, refactor safely at scale, ship production-ready software, lead technical discussions, and use AI as a force multiplier — not a crutch.

More importantly, they will have practiced these skills under conditions that mirror the real world. Not in isolation. Not with toy data. Not with unlimited time and no constraints. They will have inherited a broken system, fixed it collaboratively, defended their decisions publicly, and shipped something that works. That experience is transferable to the first day of a professional engineering role in a way that a passing grade on a data structures final is not.

Course Reading Link to heading

The following books, articles, and resources form the reading list for the course, organized by module.

Engineering Foundations (Weeks 1–3) Link to heading

• Software Engineering at Google by Titus Winters, Tom Manshreck, and Hyrum Wright — Chapters 1–3 on what distinguishes software engineering from programming, and how Google thinks about code over time. Free to read online.
• The Pragmatic Programmer by David Thomas and Andrew Hunt — Chapters 1–2 on pragmatic philosophy: ownership, responsibility, and the “broken windows” theory of software decay.
• A Philosophy of Software Design by John Ousterhout — Chapters 1–4 on complexity as the central problem, and the distinction between tactical and strategic programming.
• The Twelve-Factor App by Adam Wiggins — all twelve factors, with emphasis on Factor X: Dev/Prod Parity and Factor III: Config.
• Trunk Based Development by Paul Hammant — the complete site, covering short-lived branches, branch by abstraction, and feature flags.
• Feature Toggles by Pete Hodgson (Martin Fowler’s site) — taxonomy of toggle types, lifecycle management, and the operational burden of flags.
• Documenting Architecture Decisions by Michael Nygard — the original blog post that introduced lightweight ADRs.

Codebase and Architecture Mastery (Weeks 4–5) Link to heading

• Refactoring: Improving the Design of Existing Code by Martin Fowler — the catalog of refactorings and the chapter on code smells. The companion site Refactoring Guru provides visual explanations of each smell.
• Clean Architecture by Robert C. Martin — Part V on architecture, with emphasis on the dependency rule, the stable abstractions principle, and the separation of policy from detail.
• The Pragmatic Programmer — Chapter 5 on decoupling: the Law of Demeter, metaprogramming, and reducing coupling between components.
• The Ideal Repository Structure — how strict layer boundaries prevent architectural decay, with Go and Python examples of interface-first, layered monorepo design.
• The Decorator Pattern for Observability and Resilience — composing cross-cutting concerns through decorator stacks rather than scattering them through business logic.

Testing and Delivery (Weeks 6–7) Link to heading

• Working Effectively with Legacy Code by Michael Feathers — the definitive guide to introducing tests into codebases that were not designed for testability. Chapters on seam identification and breaking dependencies.
• The Practical Test Pyramid by Ham Vocke (Martin Fowler’s site) — a modern restatement of the test pyramid with concrete examples of unit, integration, and end-to-end tests.
• Pact Documentation — consumer-driven contract testing for microservices. How to verify that service boundaries honor their agreements without running full integration environments.
• Continuous Delivery by Jez Humble and David Farley — the foundational text on deployment pipelines, reproducible builds, and the practice of keeping software in a releasable state at all times.
• Continuous Integration by Martin Fowler — the principles behind CI as a practice, not just a tool.

Distributed Systems and Data Safety (Weeks 8–9) Link to heading

• Designing Data-Intensive Applications by Martin Kleppmann — Part II on distributed data: replication, partitioning, consistency, and consensus. The single most important textbook for understanding distributed systems in practice.
• What do you mean by “Event-Driven”? by Martin Fowler — disambiguating event notification, event-carried state transfer, event sourcing, and CQRS.
• Jepsen: Consistency Models by Kyle Kingsbury — a visual guide to the hierarchy of consistency models, from linearizability to eventual consistency.
• Life beyond Distributed Transactions by Pat Helland — how to build correct applications without relying on distributed transactions, using idempotency and natural keys.
• Release It! by Michael Nygard — stability patterns (circuit breakers, bulkheads, timeouts) and anti-patterns (cascading failures, blocked threads, self-denial attacks). Essential reading for building systems that survive production.

Operational Excellence (Weeks 10–11) Link to heading

• Site Reliability Engineering edited by Betsy Beyer, Chris Jones, Jennifer Petoff, and Niall Richard Murphy — Chapters on service level objectives, monitoring distributed systems, and postmortem culture. Free to read online.
• The Site Reliability Workbook — the practical companion to the SRE book, with worked examples of SLO implementation, alerting strategies, and incident response. Free to read online.
• Observability Engineering by Charity Majors, Liz Fong-Jones, and George Miranda — the distinction between monitoring and observability, structured events over metrics, and high-cardinality debugging in distributed systems.
• How Complex Systems Fail by Richard I. Cook — a short, essential paper on why complex systems fail, how failure is evaluated after the fact, and why hindsight bias distorts incident analysis. Required reading before the first retrospective exercise.

Security and AI (Weeks 12–13) Link to heading

• OWASP Top 10 — the standard reference for web application security risks: injection, broken authentication, sensitive data exposure, and the rest. Students should be able to identify each risk category in Orion’s codebase.
• OWASP Top 10 for Large Language Model Applications — prompt injection, insecure output handling, training data poisoning, and other LLM-specific attack vectors. The AI-era companion to the classic Top 10.
• SLSA Framework (Supply-chain Levels for Software Artifacts) — a security framework for achieving increasing levels of supply chain integrity, from basic provenance to hermetic builds.
• Threat Modeling: Designing for Security by Adam Shostack — the STRIDE methodology, attack trees, and practical approaches to identifying threats before they become vulnerabilities.
• Anatomy of an AI Engineering System — how composable skills, quality gates, and model tiers turn AI tools into a disciplined engineering workflow rather than unconstrained generation.
• How I Learned to Love the Bomb — the shift from AI skepticism to building an engineering system around it, and why the leverage is real only if you bring the discipline with you.

Organization and Leadership (Weeks 14–15) Link to heading

• Accelerate by Nicole Forsgren, Jez Humble, and Gene Kim — the research behind the four key metrics (deployment frequency, lead time, change failure rate, mean time to recovery) and how they predict organizational performance.
• Team Topologies by Matthew Skelton and Manuel Pais — how team structure shapes software architecture (and vice versa), the four fundamental team types, and the three interaction modes.
• The Mythical Man-Month by Frederick P. Brooks Jr. — essays on why adding people to a late project makes it later, the distinction between essential and accidental complexity, and the surgical team model. Published in 1975, still correct.
• Software Engineering at Google — Chapters 9–10 on code review culture and documentation, and Chapter 22 on large-scale changes.

The Guiding Principle Link to heading

Professional software engineering is not about writing code.

It is about owning systems, making decisions under constraint, and shipping reliable software in real organizations.

Everything in this course — the production-parity environments, the deliberately broken codebase, the architecture defenses, the AI integration — serves that principle. The tools and technologies will change. The languages will evolve. The AI capabilities will grow. But the discipline of engineering — the habit of making explicit decisions, enforcing quality, and accepting responsibility for what you ship — that endures.

This post opens it up. Seventeen slash commands. Seven templates. Three model tiers. Each skill is short, composable, and single-purpose. Together they form a pipeline that mirrors how software has always been built — just faster.

The Lifecycle as a Directed Graph Link to heading

Traditional software development follows a predictable arc: understand the problem, make architectural decisions, break the work into deliverable pieces, plan each piece, implement with tests, verify, commit, review, ship. Every methodology from waterfall to agile to shape-up is a variation on this sequence. The differences are in the feedback loops and the batch sizes, not in the fundamental ordering.

My skills encode this arc as a directed graph of slash commands:

/adr → /arch → /rfp → /spec → /spec-plan → /spec-implement → /spec-verify → /github

Each node in the graph is a standalone skill that reads the outputs of its predecessors and produces artifacts for its successors. /adr writes an Architecture Decision Record. /arch generates Mermaid diagrams from codebase analysis. /rfp decomposes an epic into independently testable stories. /spec dispatches to planning, implementation, or verification based on where the plan currently sits. /github handles branching, committing, PRs, and merges.

The key property is that every skill terminates by offering to route you to the next one. Here’s how /adr does it — the entire routing logic at the end of the skill:

Use AskUserQuestion:

  question: "What's the next step for this decision?"
  header: "Pipeline"
  options:
    - "/arch — Diagram affected architecture"
    - "/rfp — Decompose into stories"
    - "/spec — Implement directly"
    - "Done — Record only"

Based on the user's choice, invoke the corresponding skill:
- /arch: Skill(skill='arch', args='<scope derived from ADR context>')
- /rfp: Skill(skill='rfp', args='<epic description from ADR>')
- /spec: Skill(skill='spec', args='<task description from ADR>')
- Done: End the workflow

The developer chooses the next step. The system suggests; it doesn’t dictate. You can enter the graph at any point — jump straight to /spec for a small feature, start at /adr for a structural change — and the downstream skills will work regardless of how you arrived.

Each Skill is Short Link to heading

The longest skill in the system is /spec-plan at roughly 120 lines of markdown. Most are under 60. /preflight — which runs formatting, linting, type checking, and tests across three languages — is about 40 lines. /tdd — which implements the full red-green-refactor cycle with property-based testing — is around 50.

This is deliberate. A skill isn’t a manual. It’s a set of constraints, a sequence of steps, and a definition of done. The model already knows how to write Go or run pytest. What it doesn’t know is your conventions: which linter, which formatter, which test markers, which directory structure, what constitutes “done” in your specific codebase. That’s what the skill provides — the delta between general capability and your particular expectations.

Here’s the entire rules section of /debug — four lines that define its behavioral contract:

## Rules
- NEVER change code before understanding the root cause
- NEVER fix a bug without a test that reproduces it
- NEVER apply a fix that you can't explain
- If the fix is complex, consider whether the underlying design needs an ADR

And here are the rules from /tdd:

## Rules
- NEVER write implementation before a failing test
- NEVER write more test than needed for the current step
- NEVER skip the refactor step (even if the code "looks fine")
- If a test passes on first run, the test is probably wrong — investigate

That’s the whole enforcement mechanism. No lengthy prose about why TDD matters. No motivational preamble. The model already knows what TDD is. The skill tells it your non-negotiable constraints and nothing more.

Short skills are also debuggable skills. When something goes wrong — and it will — you want to be able to read the entire skill in thirty seconds, identify which step produced the bad output, and adjust. A 500-line prompt is an untestable monolith. A 50-line prompt is a function.

Templates as Shared Memory Link to heading

Skills don’t work in isolation. They share structure through a set of seven templates that live in ~/.claude/templates/:

• adr.md — Architecture Decision Record with alternatives table, consequences, and quality checklist
• epic.md — Epic specification with stories table and risk matrix
• story.md — User story with acceptance criteria and coding patterns checklist
• plan.md — Implementation plan with task breakdown, feature inventory, and progress tracking
• commit.md — Conventional commit format with scope and type conventions
• pr.md — Pull request with summary, changes by area, and test plan
• repo.md — Monorepo scaffold with layered architecture and directory conventions

When /adr creates an ADR, it stamps out the adr.md template and fills in the blanks. When /rfp decomposes an epic into stories, each story uses the story.md template. When /spec-plan produces an implementation plan, it follows plan.md — complete with a status header (PENDING, COMPLETE, VERIFIED), an approved flag, and an iteration counter that increments when verification fails and the plan loops back to implementation.

The templates serve as shared memory across sessions. A plan file written by /spec-plan on Monday is picked up by /spec-implement on Tuesday and /spec-verify on Wednesday. The status header is the handoff mechanism. /spec reads it and dispatches to the right phase automatically. No human has to remember where they left off. The artifact carries the state.

This also means skills don’t need to be long, because the structural decisions live in templates. The skill says what to do. The template says what the output looks like. Separation of concerns, applied to prompts.

The Spec Pipeline as a Filesystem Link to heading

Every skill reads from and writes to a specific path. The directory structure is the workflow engine:

docs/
├── adr/                    # Architecture Decision Records
└── spec/
    ├── arch/               # Mermaid architecture diagrams
    ├── epics/              # Epic specifications
    ├── stories/            # Implementation stories
    └── plans/              # Implementation plans

/repo scaffolds this structure on day one — it’s part of the standard monorepo template. From that point forward, every skill in the pipeline knows exactly where to find its inputs and where to deposit its outputs. /adr writes numbered files to docs/adr/. /arch writes diagrams to docs/spec/arch/. /rfp reads an epic from docs/spec/epics/ and creates stories in docs/spec/stories/. /spec-plan creates plans in docs/spec/plans/. No configuration. No database. Just files in agreed-upon locations.

The naming conventions are part of the contract. Epics are epic-NN-<slug>.md. Stories use <epic>.<story>-<slug>.md — so story 5.3 of epic 5 lands at docs/spec/stories/5.3-repository-layer.md. Plans are YYYY-MM-DD-<slug>.md. The skills use these conventions to discover related artifacts automatically. When /rfp decomposes epic 5, it creates stories 5.1 through 5.N and updates the epic’s stories table with relative links:

## Stories

| #   | Story            | Status | File                                   |
| --- | ---------------- | ------ | -------------------------------------- |
| 5.1 | Core interfaces  | Todo   | [5.1-core-interfaces.md](../stories/5.1-core-interfaces.md) |
| 5.2 | Repository layer | Todo   | [5.2-repository-layer.md](../stories/5.2-repository-layer.md) |
| 5.3 | Service layer    | Todo   | [5.3-service-layer.md](../stories/5.3-service-layer.md) |

Status tracking happens in-file, not by moving files between directories. Each story has a Status field that progresses from Todo to In Progress to Complete. When /spec-verify finishes verifying a story’s plan, it updates the story’s status field and the epic’s table in one pass. /rfp status scans the entire tree to generate a progress report:

| # | Epic                       | Total | Done | Remaining | Progress         |
|---|----------------------------|-------|------|-----------|------------------|
| 1 | Repository Restructure     | 9     | 9    | 0         | ████████░░ 100%  |
| 2 | Foundation Fault Tolerance | 8     | 5    | 3         | █████░░░░░  63%  |

The filesystem approach has a practical advantage over any database or project management tool: it’s version-controlled. Every status change, every story creation, every plan iteration is a git commit. You can git log docs/spec/stories/5.3-service-layer.md and see the full history of a story from creation through implementation to completion. You can git diff a plan between iteration 1 and iteration 3 to see exactly what the verification phase changed.

Every template includes a section for references — links to ADRs, architecture diagrams, epic specs, and story files. When /spec-plan creates a plan, it cross-references the ADR that motivated the work and the story that scoped it. When /github generates a PR description, it links back to the plan, the story, and the ADR. This creates a traceable chain from decision to implementation to commit. Six months later, when someone asks “why did we restructure the event pipeline?”, the PR links to the plan, the plan links to the story, the story links to the epic, and the epic links to the ADR that documents the decision, the alternatives considered, and the trade-offs accepted.

The AI doesn’t maintain this chain because it has good memory. It maintains it because the templates have a References section and the skills say fill it in. Structure beats intelligence.

Model Tiers Link to heading

Not every skill needs the same model. Reviewing an architecture decision requires different capability than running a linter. The skills encode this by specifying which model tier to use:

The encoding is a single YAML frontmatter line at the top of each skill file. /adr opens with:

---
model: opus
---

And /preflight opens with:

---
model: sonnet
---

That’s the entire model selection mechanism. Opus handles the work that requires judgment: /adr, /arch, /spec-plan, /spec-verify, /review, /repo, and /debug. These skills involve reading large codebases, making design decisions, evaluating trade-offs, and catching subtle errors. They benefit from deeper reasoning and broader context comprehension.

Sonnet handles the work that requires execution: /spec (dispatcher), /spec-implement, /tdd, /github, /preflight, /learn, /patterns, /sync, and /vault. These skills follow well-defined steps — run the tests, format the code, create the branch, commit with conventional format. The instructions are precise enough that a faster, cheaper model executes them reliably.

The division mirrors how engineering teams work. Senior architects make the structural decisions. Everyone follows the same process for committing code and running CI. You don’t need your most expensive resource reviewing whether ruff format passed.

In practice, this means a typical /spec session starts with Opus for planning — exploring the codebase, designing the approach, breaking work into tasks — then drops to Sonnet for implementation, where it runs TDD cycles on each task, and finally escalates back to Opus for verification, where it launches review agents and checks for regressions. The model tier follows the cognitive demand of each phase.

The Spec Workflow Link to heading

The centerpiece is /spec, a three-phase workflow that manages the full implementation cycle:

Phase 1 — Plan (/spec-plan, Opus): Explores the codebase. Identifies affected files, similar features, existing patterns. Designs 3–12 implementation tasks, each independently testable. Launches two verification agents in parallel — one checks alignment with requirements, one challenges assumptions and finds failure modes. The plan doesn’t proceed until the developer approves it.

Phase 2 — Implement (/spec-implement, Sonnet): Takes the approved plan and executes each task sequentially using /tdd for the red-green-refactor cycle. Updates the plan’s checkboxes after every completed task. Commits per-task when working in a git worktree. No sub-agents — everything runs in the main context to preserve continuity.

Phase 3 — Verify (/spec-verify, Opus): Launches two review agents — one for process compliance, one for code quality. Runs the full test suite, checks coverage, validates file lengths, traces call chains upstream and downstream. Then builds, deploys to a test environment, executes the actual program, and runs end-to-end tests. If anything fails, it adds fix tasks to the plan, resets the status, and loops back to Phase 2.

The loop is the important part. The /spec skill encodes it as a status machine:

PENDING (Not Approved) → spec-plan    → User approves
PENDING (Approved)     → spec-implement → All tasks done → COMPLETE
COMPLETE               → spec-verify   → All checks pass → VERIFIED

And the feedback path:

spec-verify finds issues → Status: PENDING → spec-implement fixes →
  COMPLETE → spec-verify → ... → VERIFIED

Verification doesn’t just report problems — it feeds them back into implementation as new tasks. The plan file’s iteration counter tracks how many times this has happened. Most features verify on the first pass. Complex migrations sometimes take two or three iterations. The system handles both without human intervention beyond the initial approval.

Quality Gates are Non-Negotiable Link to heading

/preflight runs before every commit. Four gates, in order:

1. Format — ruff format for Python, gofumpt for Go, prettier for TypeScript. Auto-fixes in place.
2. Lint — ruff check --fix, golangci-lint run, eslint --fix. Reports remaining errors.
3. Type check — basedpyright, go vet, tsc --noEmit. No auto-fix available. You fix it or you don’t commit.
4. Tests — pytest, go test, vitest. Changed modules must have passing tests.

This isn’t a suggestion. /github commit delegates to /preflight before staging anything. If gate 3 or 4 fails, the commit doesn’t happen. The AI fixes the issue and tries again. The same bar applies whether the code was written by hand, by Sonnet, or by Opus.

The Feedback Loop Link to heading

The pipeline skills handle the forward path — from decision to shipped code. A second set of skills handles the feedback path: learning from what happened and improving the system itself.

/debug applies the scientific method to bugs. Reproduce with a failing test, isolate the root cause through bisection, diagnose, fix via /tdd, verify no regressions. It prevents the most common AI failure mode: randomly changing code until the symptom disappears without understanding the cause.

/learn watches for non-obvious discoveries during a session and extracts them into reusable skill files. The skill defines its own trigger conditions:

| Trigger                      | Example                                              |
| ---------------------------- | ---------------------------------------------------- |
| **Non-obvious debugging**    | Spent 10+ minutes investigating; solution wasn't in docs |
| **Misleading errors**        | Error message pointed wrong direction                |
| **Workarounds**              | Found limitation and creative solution               |
| **Tool integration**         | Figured out how to use tool/API in undocumented way  |
| **Trial-and-error**          | Tried multiple approaches before finding what worked |
| **Repeatable workflow**      | Multi-step task that will recur; worth standardizing |

Each extracted skill lands at .claude/skills/. The next session benefits from what this session learned. Over weeks, the system accumulates institutional knowledge that would otherwise evaporate when the context window resets.

/patterns audits the codebase for DRY violations, anti-patterns, coupling problems, and complexity hotspots. It’s the skill I run when something feels wrong but I can’t point to a specific bug. It produces a severity-ranked report and offers to fix what it finds.

/sync keeps the documentation layer current. It reads the codebase, compares what it finds against existing rules and skills, updates what’s stale, and creates new rules for patterns it discovers but can’t find documented anywhere. The system doesn’t just execute — it maintains itself.

These aren’t part of the main pipeline. They’re the maintenance loop that keeps the pipeline honest. Without them, the skills would calcify — correct when written, increasingly irrelevant as the codebase evolves.

Why This Works Link to heading

The system works for the same reason any good engineering process works: it separates decisions from execution, makes the decisions explicit, and automates the execution.

The developer decides the architecture (via /adr), approves the plan (via /spec-plan), and reviews the output (via /spec-verify). The model executes the mechanical translation — the 400 lines of well-structured, well-tested implementation that used to take an afternoon. The templates ensure structural consistency. The model tiers allocate capability where it matters. The quality gates prevent regression.

None of this requires the model to be brilliant. It requires the model to follow instructions reliably, and it requires the instructions to be precise. Seventeen short skills, each doing one thing, chained together through file-based artifacts and status headers. That’s the whole system.

The source of leverage isn’t the AI. It’s the constraints you put around it.

Flat structures invite disorder. When everything lives in a single directory, or when layering exists only as a naming convention without enforcement, developers default to expedient choices rather than architecturally sound ones. A service needs database access, so it imports the repository directly. The repository needs to emit an event, so it imports the event bus. The event bus needs to log, so it imports the logger. Three months later, every component depends on every other component, and the dependency graph is cyclic. Refactoring becomes impossible because changes ripple unpredictably across the codebase.

Layers are the antidote. Physical directory boundaries enforce dependency direction — code can depend downward on lower layers, never upward or sideways. A strict layer model transforms implicit architectural conventions into explicit compilation failures. When a repository attempts to import from a service, the compiler rejects it. When a workflow tries to access a controller, the import path does not resolve. The structure becomes self-enforcing, and architectural decay stops being a gradual slide toward chaos.

The Inspiration: Ardanlabs Service Link to heading

The foundation for this structure came from Bill Kennedy’s ardanlabs/service template. Kennedy’s approach introduced a three-layer model for Go services that made dependency direction visible through directory structure:

service/
├── foundation/    # Utilities, logging, metrics, database drivers
├── business/      # Domain logic, business rules, data access
└── app/           # HTTP handlers, service composition, main()

The breakthrough insight was physical enforcement. The foundation/ layer contains infrastructure primitives — loggers, metric emitters, database clients, cache adapters — with zero dependencies on anything above it. The business/ layer implements domain logic and data models, depending only on foundation/. The app/ layer wires everything together and exposes HTTP endpoints, depending on both foundation/ and business/ but owned by neither.

This structure prevents common pathologies. A database repository cannot import an HTTP handler because handler code lives in app/, and business/ is forbidden from importing app/. A logger cannot depend on business logic because foundation/ has no upward dependencies. Every import violation is a compile-time error, not a runtime surprise discovered during a production incident.

Kennedy’s model established two principles that remain central: dependency direction flows downward, and layers are directories, not comments. The first principle ensures that lower layers are reusable and testable in isolation — the logger does not need a database to function, and the business logic does not need an HTTP server to execute. The second principle makes architecture visible and enforceable — static analysis tools can verify that no business/ file imports from app/, and code review can catch violations before they merge.

The ardanlabs model was designed for small to medium Go services. As the pattern scaled to larger polyglot monorepos with dozens of microservices and shared libraries, the three-layer division became insufficient. Business logic stratified into distinct responsibilities — data access, domain services, sequential pipelines, multi-step workflows — each deserving a separate layer. Infrastructure expanded beyond foundation utilities to include decorator-wrapped external clients and repository abstractions. Interface contracts needed a dedicated location to prevent circular dependencies between layers.

The evolution produced a nine-layer model that preserves Kennedy’s core insight — dependency flows downward through physical boundaries — while providing finer granularity for complex systems.

The Layer Model Link to heading

The ideal structure separates concerns into nine layers, each with a single responsibility and clear dependency constraints. Lower layers provide primitives and infrastructure. Middle layers implement domain logic. Upper layers coordinate and expose functionality. Dependency arrows point strictly downward.

Core Interfaces — Contracts Before Implementations Link to heading

Interface definitions live in a dedicated package, isolated from all implementations. Every layer imports from core/interfaces/, but core/interfaces/ imports from nothing. This breaks circular dependencies and establishes a single source of truth for contracts.

In Go, this means a pkg/go/core/interfaces/ directory containing only interface definitions and their documentation:

// pkg/go/core/interfaces/repository.go
package interfaces

// Repository provides generic CRUD operations for any entity type T,
// filtered by parameters P, and identified by ID.
type Repository[T any, P any, ID comparable] interface {
    Create(ctx context.Context, entity T) (T, error)
    GetByID(ctx context.Context, id ID) (T, error)
    GetAll(ctx context.Context, params P) ([]T, error)
    Update(ctx context.Context, id ID, entity T) (T, error)
    DeleteByID(ctx context.Context, id ID) error
    Count(ctx context.Context, params P) (int64, error)
}

In Python, the equivalent is an src/interfaces/ package with abstract base classes:

# src/interfaces/repository.py
from abc import ABC, abstractmethod
from typing import Generic, TypeVar

T = TypeVar('T')  # Entity type
P = TypeVar('P')  # Query parameters
ID = TypeVar('ID')  # Identifier type

class Repository(ABC, Generic[T, P, ID]):
    """Generic repository interface for CRUD operations."""

    @abstractmethod
    def create(self, entity: T, *, ctx: Ctx = None) -> T:
        """Create a new entity."""
        ...

    @abstractmethod
    def get_by_id(self, entity_id: ID, *, ctx: Ctx = None) -> T | None:
        """Retrieve an entity by its unique identifier."""
        ...

    @abstractmethod
    def get_all(self, params: P, *, ctx: Ctx = None) -> list[T]:
        """Retrieve all entities matching the given parameters."""
        ...

The interface layer defines contracts for repositories, services, pipelines, workflows, controllers, clients, loggers, metrics emitters, cache adapters, and all other abstractions. Implementations live elsewhere. This separation enables testability through mocking — a service test can inject a fake repository that implements the Repository[T, P, ID] interface without requiring a real database — and pluggability — swapping PostgreSQL for MongoDB requires only a different repository implementation, with zero changes to service logic.

Foundation — Cross-Cutting Infrastructure Link to heading

The foundation layer provides utilities and adapters for logging, metrics collection, distributed tracing, caching, retry logic, circuit breaking, rate limiting, timeout enforcement, and other infrastructure concerns. Each component is independently versioned and publishable, depends only on core interfaces, and has zero dependencies on domain logic.

A logger in the foundation layer implements the Logger interface from core:

// pkg/go/foundation/logger/logger.go
package logger

import "github.com/org/mothership/pkg/go/core/interfaces"

type Config struct {
    Kind        Kind   // stdlib, zap, zerolog
    Level       string
    JSON        bool
    Development bool
}

func New(kind Kind, opts ...Option) interfaces.Logger {
    cfg := DefaultConfig()
    for _, opt := range opts {
        opt(&cfg)
    }
    return newFromConfig(cfg)
}

The foundation logger has three implementations: stdlib (Go’s log/slog), zap (Uber’s structured logger), and zerolog (zero-allocation logger). Each implementation satisfies the interfaces.Logger contract. Application code depends on the interface, not the implementation, so switching from zap to zerolog requires changing only the DI wiring, not every log call site.

Foundation components are independently versioned Go modules. Each has its own go.mod, VERSION file, and CHANGELOG.md. The logger is publishable as github.com/org/mothership/foundation/logger@v1.2.0, the metrics emitter as github.com/org/mothership/foundation/metrics@v1.1.0. Teams can upgrade the logger without touching the circuit breaker, and external projects can depend on individual foundation modules without pulling the entire monorepo.

Clients — External System Integration Link to heading

The client layer wraps all interactions with external systems — databases, message brokers, object storage, third-party APIs. Clients implement interfaces from the core layer and are wrapped with decorator stacks for observability and resilience.

A MongoDB client in Python demonstrates the pattern:

# src/clients/domain/mongodb/client.py
from motor.motor_asyncio import AsyncIOMotorClient
from src.interfaces.client import DatabaseClient

class MongoDBClient(DatabaseClient):
    """Async MongoDB client implementation."""

    def __init__(self, uri: str, database: str) -> None:
        self._client = AsyncIOMotorClient(uri)
        self._db = self._client[database]

    async def connect(self) -> None:
        await self._client.admin.command('ping')

    async def disconnect(self) -> None:
        self._client.close()

    def collection(self, name: str):
        return self._db[name]

The raw client provides minimal functionality. Production use requires retry logic for transient failures, circuit breaking to prevent cascading failures, structured logging for observability, and metrics for monitoring. Decorators compose these concerns:

# src/clients/sdk/decorators.py
from src.clients.sdk.base import ClientDecorator

class RetryDecorator(ClientDecorator[T]):
    """Wraps a client with retry logic."""

    def __init__(self, inner: T, retrier: Retrier) -> None:
        super().__init__(inner)
        self._retrier = retrier

    async def execute(self, operation, *args, **kwargs):
        return await self._retrier.execute(
            lambda: getattr(self._inner, operation)(*args, **kwargs)
        )

class CircuitBreakerDecorator(ClientDecorator[T]):
    """Wraps a client with circuit breaking."""

    def __init__(self, inner: T, circuit_breaker: CircuitBreaker) -> None:
        super().__init__(inner)
        self._cb = circuit_breaker

    async def execute(self, operation, *args, **kwargs):
        return await self._cb.call(
            lambda: getattr(self._inner, operation)(*args, **kwargs)
        )

A factory function composes the stack:

def create_mongo_client(settings: Settings) -> DatabaseClient:
    """Factory that wraps raw client with resilience and observability."""
    raw = MongoDBClient(settings.mongo_uri, settings.database)

    # Inner: circuit breaker → retry
    with_retry = RetryDecorator(raw, create_retrier())
    with_cb = CircuitBreakerDecorator(with_retry, create_circuit_breaker())

    # Outer: logging → metrics
    with_logging = LoggingDecorator(with_cb, logger)
    with_metrics = MetricsDecorator(with_logging, metrics)

    return with_metrics

The resulting client satisfies the DatabaseClient interface while transparently adding retry, circuit breaking, logging, and metrics. Service code calls client.collection('users').find({}) without awareness of the decorator stack. For the full decorator pattern details, see my earlier post on the decorator pattern for observability and resilience.

Repositories — Data Access Abstraction Link to heading

Repositories provide a domain-oriented interface to persistent storage. A repository accepts domain entities (not database-specific persistence models), translates them to the appropriate storage format, and abstracts query construction.

Go repositories are generic over entity type, query parameters, and identifier:

// pkg/go/platform/repository/repository.go
package repository

type BaseRepository[T any, P any, ID comparable] struct {
    tableName string
    db        interfaces.DatabaseClient
}

func (r *BaseRepository[T, P, ID]) GetByID(
    ctx context.Context,
    id ID,
) (T, error) {
    var zero T
    query := fmt.Sprintf("SELECT * FROM %s WHERE id = $1", r.tableName)
    // Execute query, scan into entity, return
    // ...
}

Concrete repositories embed BaseRepository and add domain-specific queries:

// apps/go/server/internal/repositories/user_repository.go
package repositories

type UserRepository struct {
    *repository.BaseRepository[User, UserParams, uuid.UUID]
}

func NewUserRepository(db interfaces.DatabaseClient) *UserRepository {
    return &UserRepository{
        BaseRepository: repository.NewBase[User, UserParams, uuid.UUID](
            "users",
            db,
        ),
    }
}

func (r *UserRepository) GetByEmail(
    ctx context.Context,
    email string,
) (User, error) {
    // Custom query beyond base CRUD
}

Python repositories follow the same pattern with ABCs:

# src/repository/mongo/transcript.py
from src.interfaces.repository import Repository
from src.repository.mongo.models import TranscriptMongoModel

class TranscriptRepository(Repository[Transcript, TranscriptQueryParams, str]):
    """MongoDB repository for transcripts."""

    def __init__(self, client: DatabaseClient) -> None:
        self._collection = client.collection('transcripts')

    async def get_by_id(
        self,
        entity_id: str,
        *,
        ctx: Ctx = None
    ) -> Transcript | None:
        doc = await self._collection.find_one({'_id': entity_id})
        if not doc:
            return None
        return self._translator.to_domain(doc)

Repositories depend on clients (the layer below) and implement the Repository[T, P, ID] interface from core. They are database-agnostic from the service layer’s perspective — swapping MongoDB for PostgreSQL requires only injecting a different repository implementation at the composition root, with zero service code changes.

Services — Business Logic Link to heading

Services implement domain logic and business rules. They are stateless, depend on repositories and clients through interfaces, and expose methods that operate on domain entities.

A service in Go:

// pkg/go/services/corpus/service.go
package corpus

type Service struct {
    transcriptRepo interfaces.Repository[Transcript, TranscriptParams, string]
    speakerRepo    interfaces.Repository[Speaker, SpeakerParams, string]
    logger         interfaces.Logger
}

func (s *Service) GetTranscriptWithSpeakers(
    ctx context.Context,
    transcriptID string,
) (TranscriptWithSpeakers, error) {
    // Business logic: fetch transcript, fetch related speakers, assemble
    transcript, err := s.transcriptRepo.GetByID(ctx, transcriptID)
    if err != nil {
        return TranscriptWithSpeakers{}, fmt.Errorf("fetch transcript: %w", err)
    }

    speakerIDs := transcript.SpeakerIDs()
    speakers, err := s.speakerRepo.GetAll(ctx, SpeakerParams{IDs: speakerIDs})
    if err != nil {
        return TranscriptWithSpeakers{}, fmt.Errorf("fetch speakers: %w", err)
    }

    return s.assembleTranscriptWithSpeakers(transcript, speakers), nil
}

Services are wrapped with the same decorator stack as clients — logging, metrics, retry, circuit breaking. A ServiceBuilder composes decorators:

# src/service/sdk/builder.py
from src.interfaces.builder import Builder

class ServiceBuilder(Builder[T, C], Generic[T, C]):
    """Builds services with decorator composition."""

    def build(self) -> T:
        instance = self._create_instance()

        # Apply fault tolerance decorators (innermost)
        if self._fault_tolerance:
            instance = RetryDecorator(instance, self._retrier)
            instance = CircuitBreakerDecorator(instance, self._cb)

        # Apply observability decorators (outermost)
        if self._observability:
            instance = LoggingDecorator(instance, self._logger)
            instance = MetricsDecorator(instance, self._metrics)

        return instance

Services depend on repositories and clients (layers below) and implement service interfaces from core. They do not depend on workflows, controllers, or entrypoints (layers above).

Pipelines — Sequential Transformations Link to heading

Pipelines model sequential data transformations where each stage consumes the output of the prior stage. A pipeline implements Pipeline[In, Out]:

// pkg/go/core/interfaces/pipeline.go
package interfaces

type Pipeline[In any, Out any] interface {
    Execute(ctx context.Context, input In) (Out, error)
}

An NLP pipeline in Python demonstrates composition:

# src/pipeline/domain/nlp/spacy_pipeline.py
from src.interfaces.pipeline import Pipeline

class SpacyPipeline(Pipeline[str, ProcessedDocument]):
    """NLP processing pipeline using spaCy."""

    def __init__(self, model: str = "en_core_web_sm") -> None:
        self._nlp = spacy.load(model)

    def execute(self, input: str, *, ctx: Ctx = None) -> ProcessedDocument:
        """Process text through: tokenization → POS → NER → dep parse."""
        doc = self._nlp(input)

        return ProcessedDocument(
            text=input,
            tokens=[token.text for token in doc],
            pos_tags=[token.pos_ for token in doc],
            entities=[(ent.text, ent.label_) for ent in doc.ents],
            dependencies=[(token.text, token.dep_, token.head.text) for token in doc],
        )

Pipelines are stateless transformations. They depend on services or clients for data fetching but do not coordinate multi-step workflows. That responsibility belongs to the next layer.

Workflows — Multi-Step Orchestration Link to heading

Workflows coordinate multiple operations — fetch data, validate, transform, publish events, handle errors. A workflow implements Workflow[In, Out]:

// pkg/go/core/interfaces/workflow.go
package interfaces

type Workflow[In any, Out any] interface {
    Execute(ctx context.Context, input In) (Out, error)
}

A search workflow demonstrates cache-aside pattern:

# src/workflow/domain/search/workflow.py
from src.interfaces.workflow import AsyncWorkflow

class SearchWorkflow(AsyncWorkflow[SearchRequest, SearchResponse]):
    """Implements cache-aside search: check cache, else pipeline."""

    def __init__(
        self,
        cache: Cache,
        pipeline: AsyncPipeline[SearchRequest, SearchResponse],
    ) -> None:
        self._cache = cache
        self._pipeline = pipeline

    async def execute(
        self,
        input: SearchRequest,
        *,
        ctx: Ctx = None
    ) -> SearchResponse:
        cache_key = self._build_cache_key(input)

        # Cache hit?
        cached = await self._cache.get(cache_key)
        if cached:
            return SearchResponse.from_json(cached)

        # Cache miss — execute pipeline
        result = await self._pipeline.execute(input, ctx=ctx)

        # Cache result
        await self._cache.set(cache_key, result.to_json(), ttl=300)

        return result

Workflows depend on services, pipelines, repositories, and clients. They do not depend on controllers or entrypoints.

Controllers — HTTP/gRPC Handlers Link to heading

Controllers are thin adapters between transport protocols (HTTP, gRPC, GraphQL) and workflows. They deserialize requests into DTOs, invoke workflows, and serialize responses.

A FastAPI controller in Python:

# src/controller/domain/search/controller.py
from fastapi import APIRouter
from src.interfaces.workflow import AsyncWorkflow

class SearchController:
    """HTTP controller for search endpoints."""

    def __init__(
        self,
        workflow: AsyncWorkflow[SearchRequest, SearchResponse],
    ) -> None:
        self._workflow = workflow
        self.router = APIRouter()
        self.router.add_api_route("/search", self.search, methods=["GET"])

    async def search(
        self,
        query: str,
        filters: str = None,
        limit: int = 10,
    ) -> SearchResponse:
        """GET /search endpoint."""
        request = SearchRequest(query=query, filters=filters, limit=limit)
        return await self._workflow.execute(request)

Controllers depend on workflows (the layer below). They do not contain business logic. Validation, transformation, and orchestration belong in lower layers.

Entrypoints — DI Wiring and Bootstrap Link to heading

Entrypoints are composition roots. They load configuration, instantiate dependencies, wire the DI container, and start the server. Each microservice has an entrypoint:

# entrypoints/server/search/container.py
from dependency_injector import containers, providers
from src.foundation.config import CoreContainer

class SearchContainer(containers.DeclarativeContainer):
    """DI container for search server."""

    # Inherit core infrastructure
    core = providers.DependenciesContainer()

    # Repository
    es_repo = providers.Singleton(
        AsyncElasticTranscriptRepository,
        client=core.es_client,
    )

    # Pipeline
    search_pipeline = providers.Singleton(
        SearchPipeline,
        repository=es_repo,
    )

    # Workflow
    search_workflow = providers.Singleton(
        SearchWorkflow,
        cache=core.redis_client,
        pipeline=search_pipeline,
    )

    # Controller
    search_controller = providers.Singleton(
        SearchController,
        workflow=search_workflow,
    )

Entrypoints depend on every other layer. No other layer depends on entrypoints. This is the dependency inversion principle in physical form — high-level policy (entrypoints) depends on low-level details (services, repositories), but low-level details do not depend back.

The Dependency Rule Link to heading

Dependency direction is the single most important structural constraint. Code in layer N can depend on layers N-1, N-2, … all the way down to core interfaces. Code in layer N cannot depend on layers N+1, N+2, or any layer above.

Enforcement in Go Link to heading

Go enforces the dependency rule through import paths. A service in pkg/go/services/corpus/ can import from pkg/go/repos/ and pkg/go/foundation/, but attempting to import pkg/go/workflow/ or pkg/go/controllers/ produces a compilation error if those packages do not exist at lower layers.

Compile-time checks make violations impossible. A repository that tries to emit domain events by importing the event bus triggers:

pkg/go/repos/postgres/user_repository.go:5:2:
    cannot import "github.com/org/mothership/pkg/go/workflow/events"
    (import cycle or dependency rule violation)

Static analysis tools like go mod graph | grep can detect cross-layer violations:

go mod graph | grep "repos.*->.*services"
# Output: (empty if no violations)

Enforcement in Python Link to heading

Python does not prevent circular imports at compile time. Import linting tools like import-linter enforce the dependency rule:

# pyproject.toml
[tool.importlinter]
root_package = "src"

[[tool.importlinter.contracts]]
name = "Layered architecture"
type = "layers"
layers = [
    "entrypoints",
    "controller",
    "workflow",
    "pipeline",
    "service",
    "repository | clients",
    "foundation",
    "interfaces",
]

Running lint-imports fails the build if a service imports from workflow:

Layer violation: src.service.corpus imported src.workflow.search
  Layers: service -> workflow (forbidden upward dependency)

Directory structure reinforces the rule. A developer attempting to import from workflow.search import SearchWorkflow into a service file sees the import path and realizes the violation before running linters.

Interface-First Design Link to heading

Defining all interfaces in a dedicated package prevents circular dependencies and establishes a contract-first development model. Implementation layers import interface definitions, but the interface package imports nothing.

Go: Compile-Time Verification Link to heading

Go repositories provide interface implementations:

// pkg/go/repos/postgres/user_repository.go
package postgres

import "github.com/org/mothership/pkg/go/core/interfaces"

type UserRepository struct {
    db interfaces.DatabaseClient
}

// Compile-time assertion: UserRepository implements Repository[User, UserParams, uuid.UUID]
var _ interfaces.Repository[User, UserParams, uuid.UUID] = (*UserRepository)(nil)

func (r *UserRepository) GetByID(
    ctx context.Context,
    id uuid.UUID,
) (User, error) {
    // Implementation
}

The assertion var _ interfaces.Repository[...] = (*UserRepository)(nil) is checked at compile time. If UserRepository fails to implement any method from Repository[T, P, ID], compilation fails. Interfaces are self-documenting contracts with compiler enforcement.

Python: Runtime Protocol Checks Link to heading

Python repositories use ABCs for interface definitions:

# src/interfaces/repository.py
from abc import ABC, abstractmethod
from typing import Generic, TypeVar, runtime_checkable, Protocol

T = TypeVar('T')
P = TypeVar('P')
ID = TypeVar('ID')

@runtime_checkable
class Repository(Protocol, Generic[T, P, ID]):
    """Repository protocol for CRUD operations."""

    def get_by_id(self, entity_id: ID, *, ctx: Ctx = None) -> T | None:
        ...

Concrete implementations inherit and override:

# src/repository/mongo/transcript.py
from src.interfaces.repository import Repository

class TranscriptRepository(Repository[Transcript, TranscriptQueryParams, str]):
    """MongoDB transcript repository."""

    def get_by_id(
        self,
        entity_id: str,
        *,
        ctx: Ctx = None
    ) -> Transcript | None:
        # Implementation

Type checkers like Mypy verify protocol adherence at static analysis time. The @runtime_checkable decorator enables isinstance() checks:

repo = TranscriptRepository(client)
assert isinstance(repo, Repository)  # True

Why Dedicated Interface Packages Matter Link to heading

Without a separate interface package, repositories and services create circular dependencies. A service needs RepositoryInterface, so it imports from the repository package. The repository needs ServiceInterface for callbacks, so it imports from the service package. The import cycle breaks the build.

A dedicated core/interfaces/ package (Go) or interfaces/ package (Python) solves this:

• Services import interfaces.Repository
• Repositories import interfaces.Repository and implement it
• No service-to-repository or repository-to-service import required

Interfaces become the shared contract. Changes to repository implementations do not require service code changes if the interface remains stable.

The Monorepo Layout Link to heading

The layer model maps to directory structure. Go and Python monorepos follow parallel organization with language-appropriate conventions.

Go: mothership Link to heading

mothership/
├── pkg/
│   └── go/
│       ├── core/
│       │   ├── interfaces/      # 60+ interface definitions
│       │   ├── types/           # Option, Either, Result, Page, ID
│       │   └── errors/          # Core error types
│       │
│       ├── foundation/          # ~20 independent modules
│       │   ├── logger/          # stdlib, zap, zerolog
│       │   │   ├── go.mod       # Independent versioning
│       │   │   ├── VERSION
│       │   │   ├── base/
│       │   │   ├── noop/
│       │   │   ├── stdlib/
│       │   │   ├── zap/
│       │   │   └── zerolog/
│       │   ├── metrics/         # Prometheus, OTEL
│       │   ├── cache/           # Redis, Ristretto
│       │   ├── circuitbreaker/
│       │   ├── retrier/
│       │   └── ...
│       │
│       ├── repos/               # Data access implementations
│       │   ├── databases/
│       │   │   ├── relational/  # PostgreSQL, SQLite
│       │   │   ├── time-series/ # InfluxDB, TimescaleDB
│       │   │   └── document/    # MongoDB
│       │   └── caches/          # Redis, Ristretto
│       │
│       ├── services/            # Domain services
│       │   ├── git/
│       │   └── version/
│       │
│       ├── platform/            # Request processing layers
│       │   ├── pipeline/
│       │   ├── decorators/
│       │   └── workflow/
│       │
│       └── config/              # Config providers
│
└── apps/
    └── go/
        ├── server/              # Main API server
        │   ├── cmd/main.go      # Bootstrap
        │   ├── internal/
        │   │   ├── handlers/
        │   │   ├── services/
        │   │   ├── repositories/
        │   │   └── wire/        # Google Wire DI
        │   └── configs/
        ├── worker/              # Background worker
        └── job/                 # Batch job

Python: hpc Link to heading

hpc/
├── src/
│   ├── interfaces/          # ABCs for all contracts
│   │   ├── repository.py
│   │   ├── service.py
│   │   ├── pipeline.py
│   │   ├── workflow.py
│   │   └── ...
│   │
│   ├── foundation/          # Infrastructure
│   │   ├── logger/
│   │   ├── metrics/
│   │   ├── cache/
│   │   ├── resilience/      # Retry, circuit breaker
│   │   └── ...
│   │
│   ├── clients/             # External systems
│   │   ├── sdk/             # Decorator framework
│   │   │   ├── base.py
│   │   │   ├── retry.py
│   │   │   ├── circuit_breaker.py
│   │   │   └── logging.py
│   │   └── domain/          # Concrete clients
│   │       ├── mongodb/
│   │       ├── redis/
│   │       ├── elasticsearch/
│   │       └── kafka/
│   │
│   ├── repository/          # Data access
│   │   ├── sdk/             # Base repository
│   │   └── mongo/           # MongoDB repositories
│   │
│   ├── service/             # Business logic
│   │   ├── sdk/
│   │   └── domain/
│   │
│   ├── pipeline/            # Sequential transformations
│   │   ├── sdk/
│   │   └── domain/
│   │
│   ├── workflow/            # Multi-step orchestration
│   │   ├── sdk/
│   │   └── domain/
│   │
│   └── controller/          # HTTP handlers
│       ├── sdk/
│       └── domain/
│
└── entrypoints/             # Service wiring
    ├── server/
    │   ├── search/          # Search API
    │   │   ├── container.py # DI wiring
    │   │   ├── app.py       # FastAPI factory
    │   │   └── routes/
    │   ├── admin/           # Admin API
    │   └── auth/            # Auth API
    ├── stream/              # Kafka consumers
    │   ├── processor/
    │   └── indexer/
    └── cli/                 # Typer CLI

Parallel Structure Link to heading

Both repositories follow the same conceptual layers with language-appropriate naming:

The directory structure makes dependency flow visible. Reading from top to bottom shows increasing abstraction. Reading imports shows dependency direction.

Decorator Composition Across Layers Link to heading

Each layer boundary is wrapped with decorators for logging, metrics, tracing, retry, and circuit breaking. A service calling a repository triggers the decorator stack at both boundaries:

Controller → [Logging → Metrics] → Workflow
                 ↓
Workflow → [Logging → Metrics] → Service
                 ↓
Service → [Logging → Metrics → Retry → CB] → Repository
                 ↓
Repository → [Logging → Metrics → Retry → CB] → Client

The decorator pattern separates cross-cutting concerns from business logic. For a detailed explanation of how decorators stack, see the decorator pattern for observability and resilience.

Builders compose the decorator stack at each layer:

service = (
    CorpusServiceBuilder(config)
    .with_repository(repo)
    .with_observability(enabled=True)
    .with_fault_tolerance(enabled=True)
    .build()
)
# Returns: LoggingDecorator(MetricsDecorator(RetryDecorator(CircuitBreakerDecorator(raw_service))))

Decorators apply uniformly across all services, repositories, and clients. Operational changes — adjusting retry backoff, switching metric backends, changing log formats — require modifications to decorator implementations, not to every service call site.

What the Structure Prevents Link to heading

Layers eliminate pathologies that plague unstructured codebases.

Circular Imports Link to heading

Flat structures produce import cycles. A service imports a repository. The repository emits domain events, so it imports the event publisher. The event publisher logs, so it imports the logger. The logger needs configuration, so it imports the config loader. The config loader validates schemas, so it imports domain models from the service. The circle closes, and the build breaks.

Layers break cycles through unidirectional dependency flow. Services depend on repositories, but repositories do not depend on services. If a repository needs to publish an event, it accepts an EventPublisher interface via dependency injection, and the entrypoint wires a concrete publisher from the foundation layer. The repository imports interfaces.EventPublisher, not a service package.

God Services Link to heading

Without clear boundaries, services accumulate responsibilities. A UserService starts with authentication. Then it handles email notifications. Then it manages file uploads. Then it orchestrates payment processing. The service becomes a thousand-line monolith that depends on every repository and client in the system.

Layers enforce the single responsibility principle through separation. Authentication belongs in an AuthService. Notifications belong in a NotificationService. File uploads belong in a StorageService. Each service depends on a narrow subset of repositories and clients. Workflows coordinate multi-service operations.

Infrastructure Leaking into Business Logic Link to heading

Services that directly import database drivers, HTTP clients, or message brokers tie business logic to infrastructure choices. Switching from PostgreSQL to DynamoDB requires changing every service method that constructs SQL queries. Replacing Kafka with RabbitMQ requires modifying every event publisher call site.

Repository and client abstractions isolate infrastructure. Services depend on interfaces.Repository[User, UserParams, uuid.UUID], not *sql.DB. Swapping persistence backends requires only a different repository implementation at the DI layer. Service code remains unchanged.

Untestable Code Link to heading

Services that instantiate dependencies internally are hard to test. A service that creates its own database connection requires a real database for tests. A service that calls external APIs directly requires network access or elaborate mocking.

Dependency injection through interfaces makes testing trivial. A service test injects a fake repository:

func TestService_GetUser(t *testing.T) {
    fakeRepo := &FakeUserRepository{
        Users: map[uuid.UUID]User{
            testUserID: {ID: testUserID, Email: "test@example.com"},
        },
    }
    service := NewUserService(fakeRepo, fakeLogger)

    user, err := service.GetUser(context.Background(), testUserID)
    require.NoError(t, err)
    assert.Equal(t, "test@example.com", user.Email)
}

No database, no network, no external dependencies. Tests run in milliseconds.

Deployment Coupling Link to heading

Microservices that share code through direct imports couple deployment. Service A imports a utility function from Service B’s internal package. Deploying Service B requires coordinating with Service A to ensure compatibility. The services are no longer independently deployable.

Layers eliminate coupling through shared libraries in foundation. Utilities live in pkg/go/foundation/, not in application packages. Services import foundation modules, not each other. Foundation modules are independently versioned, and services declare version constraints in their go.mod files. Upgrading a foundation module in Service A does not affect Service B until Service B updates its own dependency declaration.

Summary Link to heading

The ideal repository structure is not about naming conventions or directory aesthetics. It is about enforcing dependency direction through physical boundaries. Layers prevent circular dependencies by making upward imports impossible. Layers prevent God components by separating responsibilities. Layers prevent infrastructure leakage by isolating abstractions from implementations. Layers prevent deployment coupling by limiting shared code to independently versioned foundation modules.

Layers are directories. Interfaces are files in a dedicated package. Dependencies flow downward. Violations fail at compile time or in CI. The structure becomes self-enforcing, and architectural decay stops being inevitable.

The nine-layer model scales from small services to large polyglot monorepos. The Go structure in mothership and the Python structure in hpc demonstrate the same principles with language-appropriate implementations. Both enforce the dependency rule. Both define interfaces before implementations. Both use decorator composition for cross-cutting concerns. Both rely on physical directory structure to make architecture visible and violations obvious.

Structure is not overhead. Structure is the mechanism that prevents complexity from compounding into chaos.

I wasn’t alone. The developers I respected most were skeptical. The arguments wrote themselves: it hallucinates, it produces subtly wrong code, it doesn’t understand architecture, it makes junior developers worse by letting them skip the part where they actually learn. I repeated these arguments often, and I believed them. Some of them are still true.

But here’s what happened: I was wrong about the conclusion.

The Resistance Link to heading

My skepticism wasn’t uninformed. I’d spent years building natural language systems — first at ClearGraph, then at Tableau, then at Salesforce. I understood language models. I knew what they were good at (pattern matching, surface fluency) and what they were bad at (reasoning, consistency, knowing when they don’t know something). When people told me GPT-3 was going to replace software engineers, I had the technical background to explain exactly why that was wrong.

And it was wrong — in 2022. The problem is that I let being right about the timeline make me complacent about the trajectory.

While I was explaining why AI-generated code was unreliable, the tools got better. While I was pointing out hallucination rates, context windows grew from 4K to 128K to effectively unlimited. While I was insisting that real engineering required human judgment, a generation of developers started shipping production code with AI assistance and — here’s the part that stung — some of them were moving faster than I was.

Bill Kennedy Link to heading

The person who changed my mind was Bill Kennedy.

Bill runs Ardan Labs and has spent years teaching Go to engineers who care about doing it right. He’s not a hype guy. He’s the opposite — rigorous, opinionated about engineering discipline, allergic to shortcuts. So when Bill started talking seriously about AI-assisted development, I couldn’t dismiss it the way I’d dismissed the Twitter evangelists. This wasn’t someone chasing a trend. This was someone who had looked at the tools, measured the output, and concluded that the leverage was real — if you brought the same discipline to AI-assisted code that you’d bring to any other code.

Bill’s argument wasn’t “AI writes code for you.” It was closer to: “AI is a force multiplier for engineers who already know what good looks like.” The standards don’t relax. The quality bar doesn’t drop. You just move faster at the parts that were never the hard parts to begin with.

That distinction mattered to me. It was the difference between “replace your judgment” and “free up your judgment for the work that actually needs it.”

Georgia Tech Link to heading

I didn’t start using AI tools seriously until I joined Georgia Tech as Research Faculty. Through ClearGraph, Tableau, Salesforce, co-founding PerceptivePanda, the Zapier acquisition — all of that was done the old way. Every line written by hand.

At Georgia Tech, the context shifted. I was working across multiple codebases, multiple languages, moving between research and engineering. The surface area was broader than anything I’d dealt with at a single company. Bill’s words kept echoing: force multiplier for engineers who already know what good looks like.

So I started small. First it was autocomplete. Fine, let Copilot finish the obvious boilerplate. I’m not going to type if err != nil { return fmt.Errorf("failed to parse config: %w", err) } for the ten thousandth time if a machine will do it for me. That’s not intelligence, that’s typing.

Then it was exploration. I started asking Claude questions about codebases I was unfamiliar with. Not to write code — just to orient. What does this module do? Where are the entry points? What’s the error handling strategy? It turned out that having a conversation with something that had read every Go package on GitHub was genuinely useful for navigating unfamiliar territory.

Then it was drafting. I’d describe a function signature, the expected behavior, the edge cases. The model would produce a first draft. I’d rewrite 60% of it. Then 40%. Then 20%. The drafts kept getting better, and I kept getting faster.

Within months, AI tools were load-bearing infrastructure in my workflow. The question had shifted from should I use these tools to how do I use them without losing the things that matter.

The Problem with “Vibe Coding” Link to heading

Here’s what I didn’t want to become: a prompt jockey. Someone who types “build me an app” into a chat window and ships whatever comes back. The industry has a word for this now — vibe coding — and I find it genuinely dangerous.

Not because the output is always bad. Sometimes it’s remarkably good. The danger is that it divorces the developer from the decisions. When you let a model choose your architecture, your error handling strategy, your test coverage, your dependency graph — you haven’t saved time. You’ve accumulated technical debt at machine speed. You just don’t know it yet, because the code runs and the tests (if there are any) pass.

The developers who are going to thrive with AI are not the ones who prompt the hardest. They’re the ones who know what good engineering looks like and refuse to accept anything less, regardless of who — or what — wrote the code.

The System Link to heading

So I built a system. Not a product, not a framework — a set of engineering standards that I enforce across every AI tool I use. The same rules, the same quality gates, the same architectural patterns, whether the code is coming from Claude Code, Cursor, or Kilo Code.

The core of it is a document I call my global standards. It lives in my dotfiles and gets symlinked into every tool’s configuration directory. It specifies:

Process — every structural change follows a pipeline: ADR first, then architecture diagrams, then decompose into stories, then plan, then implement, then verify. AI doesn’t get to skip steps.

Quality gates — before every commit, four things must pass: formatting, linting, type checking, and unit tests. No exceptions. No “I’ll fix it later.” The AI writes the code, and the code meets the same bar as anything I’d write by hand.

Architecture patterns — clean layered architecture with dependency injection, repository pattern for data access, early returns over nested conditionals. Separate your persistence models from your domain entities from your DTOs. These aren’t suggestions. They’re constraints.

Anti-patterns — files over 800 lines, functions over 50 lines, nesting deeper than 4 levels, hardcoded secrets, mutable shared state, any types without narrowing, import cycles. If the AI produces any of these, it gets rejected. Every time.

Each language gets its own standards file. Python means uv for package management, ruff for linting, basedpyright for type checking, pytest with markers per layer, attrs classes for models, Google-style docstrings, and property-based testing with hypothesis. Go means gofumpt for formatting, golangci-lint for linting, table-driven tests with t.Run() subtests, small consumer-defined interfaces, and structured logging with zap. TypeScript means pnpm, strict tsc, vitest, functional React components, and Tailwind utilities — never @apply.

These aren’t aspirational documents. They’re enforced. When I open Claude Code, it reads my CLAUDE.md and knows the rules before I type a single prompt. When I open Cursor, the .cursorrules file tells it how this specific project works — down to the import paths for the error hierarchy and the structured logging package. When I open Kilo Code, the same standards are waiting in ~/.kilocode/rules/.

The result is that I get three different AI tools, built by three different companies, all producing code that looks like my code. Same patterns. Same conventions. Same quality bar.

What It Actually Looks Like Link to heading

Here’s a typical session. I’m adding a new domain entity to a Go service. I open Claude Code and describe what I need:

Add a workspace domain entity with CRUD operations, Ent repository, and HTTP controller. Follow the existing user domain as the reference implementation.

Claude Code reads my standards, examines the existing user domain for patterns, and produces a plan. Not code — a plan. It identifies the files it needs to create, the interfaces it needs to implement, the tests it needs to write. I review the plan. I adjust it. Then it executes.

The code that comes out has structured logging with zap, errors wrapped with cockroachdb/errors, context as the first parameter, table-driven tests, the full layered architecture from cmd to controller to core to foundation. Not because the model is brilliant, but because I told it exactly what good looks like and gave it a reference implementation to follow.

When something doesn’t meet the bar, I reject it. The model learns from the correction within the session. Over time, my standards files get more precise based on the patterns of mistakes I see. It’s a feedback loop: the AI makes me more explicit about what I want, and that explicitness makes the AI more reliable.

TDD Still Matters Link to heading

One of the standards I enforce hardest is TDD. Write the failing test first. Red, green, refactor. Every AI tool I use knows this rule.

This matters more with AI-generated code, not less. When a human writes code, they have a mental model of the invariants. When a model writes code, it has a statistical approximation of what code in this context usually looks like. Tests are the mechanism that bridges that gap. If the model’s implementation satisfies the tests I wrote — tests that encode my understanding of the requirements — then I have confidence in the output regardless of whether a human or a machine produced it.

The developers who skip tests because “the AI wrote it and it looks right” are going to learn expensive lessons.

The Uncomfortable Truth Link to heading

Here’s the part that’s hard to say: I’m faster now. Meaningfully faster. Not at the parts of programming that matter most — design, architecture, understanding the problem — but at the mechanical translation of decisions into working code. The part where you know exactly what you want and you need to produce 400 lines of well-structured, well-tested, well-documented implementation. That part used to take an afternoon. Now it takes twenty minutes.

This means one of two things. Either the mechanical translation was never where my value as an engineer lived, or I was spending a lot of my career on work that didn’t require my full attention. Probably both.

The developers who are threatened by this are the ones whose primary skill is typing speed and syntax recall. The developers who are amplified by it are the ones whose primary skill is judgment: knowing what to build, how to structure it, what trade-offs to accept, and — critically — knowing when the AI’s output is wrong.

What I Got Wrong Link to heading

I got two things wrong about AI and software engineering.

First, I thought the quality floor was fixed. I assumed that AI-generated code would always be mediocre and that serious engineers would always need to rewrite it. What I didn’t anticipate was that the quality floor is a function of the constraints you impose. Unconstrained, yes, AI writes mediocre code. But with 70 pages of standards, enforced quality gates, reference implementations, and a human who knows what good looks like? The floor rises dramatically.

Second, I thought adoption was binary. Either you’re a “real” developer who writes everything by hand, or you’re a prompt engineer who ships slop. The reality is a spectrum, and the interesting part of that spectrum is where human judgment and AI capability overlap. That’s where the leverage is.

Adapt or Die Link to heading

The tools exist. They’re getting better. The developers who refuse to engage with them aren’t preserving craftsmanship — they’re ceding ground to developers who use AI and have good judgment.

The answer isn’t to abandon your standards. It’s to encode them. Write them down. Make them machine-readable. Enforce them automatically. Then use every tool available to you — AI included — to ship better software faster, without compromising on the things that actually matter.

Bill was right. The leverage is real. But only if you bring the discipline with you.

I still have opinions about whitespace. I still believe in TDD. I still think architecture matters more than velocity. I just let a machine handle the typing.

The decorator pattern provides a principled alternative. Each cross-cutting concern is extracted into a standalone wrapper that implements the same interface as the component it decorates. Each wrapper adds exactly one behavior — logging, metrics, retry, or circuit breaking — then delegates to the inner implementation. The business logic remains unaware that it is being observed or protected, and each concern can be developed, tested, and modified independently.

Motivation: Failure in Distributed Systems Link to heading

In a monolithic system, a failed function call raises an exception that the caller handles directly. Distributed systems present a fundamentally different failure model. Network partitions, request timeouts, overloaded upstreams, and cold starts are not edge cases; they are routine operational conditions. Every service-to-service call requires a defensive layer: retries with exponential backoff to allow transient failures to resolve, circuit breakers to prevent a degraded upstream from cascading into the caller, timeouts to bound resource consumption on hung connections, and structured logging to enable distributed tracing across service boundaries.

The decorator pattern enables uniform application of these concerns across every client and service boundary without duplicating the implementation. A single RetryDecorator wraps any client interface. A single CircuitBreakerDecorator protects any upstream dependency. When the operational team determines that a backoff strategy should change from exponential to jittered, the modification is confined to one file. When a new database client is introduced, the same decorator stack is composed with a domain-specific error classifier, and the full set of protections — logging, metrics, retry, circuit breaking — is applied automatically.

The Pattern in Go Link to heading

Go’s implicit interface satisfaction makes the decorator pattern particularly natural. A logging decorator for an event producer is a struct that holds the inner producer and a logger. It satisfies the same EventProducer interface, so callers cannot distinguish it from the underlying implementation:

// loggingProducer wraps an EventProducer with structured logging.
// It records publish duration, event name, and any errors without
// modifying the underlying producer's behavior.
type loggingProducer struct {
    inner  EventProducer
    logger Logger
}

// WithLogging decorates a producer with entry/exit logging.
// Returns the same EventProducer interface — callers cannot tell
// they are talking to a decorator.
func WithLogging(p EventProducer, logger Logger) EventProducer {
    return &loggingProducer{inner: p, logger: logger}
}

func (p *loggingProducer) Publish(ctx context.Context, event Event) error {
    start := time.Now()
    err := p.inner.Publish(ctx, event)
    p.logger.Info("publish",
        "event", event.Name(),
        "duration", time.Since(start),
        "error", err,
    )
    return err
}

A circuit breaker decorator follows the same structural pattern. It checks the circuit state before each call and records the outcome afterward. If the upstream has exceeded the failure threshold, the decorator short-circuits immediately without attempting the call:

// circuitBreakerProducer fails fast when the upstream is degraded.
// BeforeCall checks the circuit state; AfterCall records the outcome
// so the breaker can track the failure rate over time.
type circuitBreakerProducer struct {
    inner EventProducer
    cb    CircuitBreaker
}

func (p *circuitBreakerProducer) Publish(ctx context.Context, event Event) error {
    if err := p.cb.BeforeCall(ctx); err != nil {
        return err // circuit is open — fail fast
    }
    err := p.inner.Publish(ctx, event)
    p.cb.AfterCall(ctx, err)
    return err
}

The essential property is that every decorator accepts and returns the same interface. This makes decorators composable — an arbitrary number can be stacked without altering any type signatures.

The Pattern in Python Link to heading

Python’s __getattr__ proxy mechanism extends the pattern further. Rather than wrapping each method individually, the decorator intercepts attribute access at the class level, determines whether the attribute is callable, and wraps it transparently. This approach yields a single decorator class that operates on any interface without per-method boilerplate:

class LoggingDecorator:
    """Transparent proxy that logs entry, exit, and errors for every call.

    Uses __getattr__ so it works with any interface — no per-method
    boilerplate. Adding logging to a new client is a single line:
        client = LoggingDecorator(raw_client, service="neo4j", logger=logger)
    """

    def __init__(self, inner, *, service: str, logger):
        self._inner = inner
        self._logger = logger
        self._service = service

    def __getattr__(self, name):
        # Delegate non-callable attributes unchanged
        attr = getattr(self._inner, name)
        if not callable(attr):
            return attr

        @wraps(attr)
        async def wrapper(*args, **kwargs):
            start = time.monotonic()
            try:
                result = await attr(*args, **kwargs)
                self._logger.debug(
                    "%s.%s ok",
                    self._service, name,
                    extra={"duration_ms": (time.monotonic() - start) * 1000},
                )
                return result
            except Exception as exc:
                self._logger.warning(
                    "%s.%s failed",
                    self._service, name,
                    extra={"error": str(exc)},
                )
                raise

        return wrapper

The same __getattr__ approach generalizes to metrics, retry, timeout, and circuit breaker decorators. Each is a standalone class capable of wrapping any object that exposes callable attributes.

Composition: Stacking Decorators Link to heading

The power of the pattern lies in composition. Each decorator is independent — it is aware only of the interface it wraps and the single concern it introduces. Decorators are composed into a stack where each layer contributes exactly one behavior. A fluent builder makes the ordering explicit and the composition readable:

// Fluent builder — reads top-to-bottom as outermost to innermost.
// A call enters at Recovery, flows through Auth → Transaction →
// Observability, reaches the concrete service, then unwinds back out.
svc := decorators.NewBuilder(NewUserService(repo), "users").
    WithRecovery().
    WithAuthorization(authorizer).
    WithTransaction(txManager).
    WithObservability(logger, metrics, tracer).
    Build()

Without a builder, the manual composition is equally explicit. Each variable name documents the layer being applied:

# Stack order: Logging → Metrics → Retry → CircuitBreaker → Timeout → Raw
# Each decorator wraps the previous, adding one concern.
raw = Neo4JClient(uri=uri, user=user, password=password)
with_timeout = TimeoutDecorator(raw, timeout_seconds=30.0, service="neo4j")
with_cb = CircuitBreakerDecorator(with_timeout, name="neo4j", threshold=5)
with_retry = RetryDecorator(with_cb, max_attempts=3, classifier=Neo4JErrorClassifier())
with_metrics = MetricsDecorator(with_retry, service="neo4j")
client = LoggingDecorator(with_metrics, service_name="neo4j", logger=logger)

When a new database client is introduced — Redis, Elasticsearch, Kafka — the same decorator stack is composed with a domain-specific error classifier, and the full complement of observability and resilience behaviors is inherited without additional implementation effort.

Summary Link to heading

The decorator pattern confines each cross-cutting concern to a single file with a single responsibility. Business logic remains clean: a repository implementation is concerned with data access, not with Prometheus histograms or retry scheduling. Decorators are individually testable — the inner interface is mocked, and the wrapper’s behavior is verified in isolation. The composition is explicit and inspectable: the builder chain or factory function specifies exactly which protections are in place and in what order. There is no annotation indirection, no framework-level interception, and no implicit behavior — only functions wrapping functions, each with a well-defined contract.

Architecture Link to heading

A natural way to organize these components is as a multi-stage pipeline. A Stanford CoreNLP dependency parser (Chen & Manning, 2014) produces token-level annotations — lemma, POS tag, dependency relation, and head position — which feed into two parallel tracks. The Stanford parser generates Universal Dependencies (UD) trees (de Marneffe et al., 2014) via its neural network dependency parser, providing typed dependency relations (e.g., nsubj, obj, det, amod) that serve as the syntactic backbone for semantic translation.

The first track embeds tokens via sentence transformers and clusters the resulting vectors into canonical concepts using deterministic k-means. The second track extracts Dowty (1991) proto-role features from dependency arcs and classifies verbs according to Beth Levin’s (1993) taxonomy. Both tracks converge in a semantic graph builder, which constructs a typed predicate-argument structure. A final generation stage produces a lambda-calculus term from the graph, applies beta-reduction and simplification, validates types, and emits a canonical string representation. None of these components are individually novel — the contribution is in tracing how they compose.

As a running illustration, the sentence “Every tall senator approved the new bill” enters the pipeline as raw text and exits as a fully typed, quantifier-scoped lambda term — with each lexical constant grounded to a canonical concept ID derived from its embedding cluster. The remainder of this post traces that sentence through each stage.

The Type System Link to heading

The standard representation language for this kind of pipeline is a higher-order typed lambda calculus in the Montague (1973) tradition. The type system comprises two primitive types — $e$ (entity) and $t$ (truth value) — and a recursive function type constructor. Common derived types include properties ($e \to t$), binary relations ($e \to (e \to t)$), generalized quantifiers ($(e \to t) \to ((e \to t) \to t)$), and connectives ($t \to (t \to t)$).

The primitive and derived types are defined as follows:

Primitive types:
    e                                       // individuals
    t                                       // propositions

Derived types:
    Property    = e → t
    BinaryRel   = e → (e → t)
    TernaryRel  = e → (e → (e → t))
    Determiner  = (e → t) → ((e → t) → t)
    Connective  = t → (t → t)
    Modifier    = (e → t) → (e → t)

The type system constrains well-formedness: a function of type $e \to t$ can only be applied to a term of type $e$, and the result has type $t$. Attempting to apply a property to another property — for example, $(\textsf{Tall}\;\textsf{Senator})$ where both are $e \to t$ — raises a type error at construction time. This enables type-driven composition and catches arity mismatches before evaluation.

For example, the determiner every has type $(e \to t) \to ((e \to t) \to t)$. It consumes a restrictor property (the noun) and a scope property (the verb phrase), yielding a truth value. The adjective tall has the modifier type $(e \to t) \to (e \to t)$: it takes a property and returns a refined property. These types determine how constituents compose — tall senator is $(\textsf{Tall}\;\textsf{Senator})$ where $\textsf{Tall} : (e \to t) \to (e \to t)$ applied to $\textsf{Senator} : e \to t$ yields a new property of type $e \to t$.

The AST Link to heading

In Montague’s framework, the abstract syntax tree requires exactly four node types. Predicates, quantifiers, and connectives are not distinct AST categories — they are typed constants composed via curried application. The four node types are:

Variable(x, τ)         // bound or free variable of type τ
Constant(c, τ)         // typed constant (predicate, quantifier, connective)
Application(f, a)      // function application: f(a)
Abstraction(x, φ)      // lambda abstraction: λx. φ

Curried application is defined recursively: $\textsf{Apply}(f, a, b) = \textsf{Application}(\textsf{Application}(f, a), b)$.

To illustrate the uniformity of this representation, consider how the words in “Every tall senator approved the new bill” reduce to the same AST primitives:

Senator : e → t                             // common noun
Approve : e → (e → t)                       // transitive verb
Bill    : e → t                             // common noun
Every   : (e → t) → ((e → t) → t)          // determiner
The     : (e → t) → ((e → t) → t)          // determiner
Tall    : (e → t) → (e → t)                // modifier
New     : (e → t) → (e → t)                // modifier

The phrase “senator approved” is simply $\textsf{Application}(\textsf{Application}(\textsf{Approve}, \textsf{Senator}), \ldots)$ — no special syntax is required for any linguistic category. Every word in the sentence is a typed constant; composition is handled entirely by $\textsf{Application}$ and $\textsf{Abstraction}$.

Translation: Dependency Arcs to Lambda Terms Link to heading

The central question is how dependency relations map to semantic argument positions. The natural approach, following Reddy et al. (2016), is a recursive transpiler that walks the dependency tree bottom-up, building typed lambda terms at each node. The recursive structure of the algorithm mirrors the recursive structure of the dependency tree itself: each subtree is translated independently, and the results are composed according to the dependency relation that connects them.

Recursive Definition Link to heading

The translation function $\mathcal{T}$ is defined over dependency tree nodes. Given a node $n$ with head word $w$, POS tag $p$, and a set of dependents $\{d_1, d_2, \ldots\}$ each bearing a dependency relation $\text{rel}(d_i)$, the function proceeds as follows:

function T(node) → LambdaTerm

    // Base case: look up the canonical concept and assign a type from POS tag
    term ← Constant(name: concept(node), type: type_for(node.pos))

    // Recursive case: process each dependent by relation type
    for each dep in node.dependents do
        case dep.relation of

            "amod", "advmod":
                // Modifiers have type (e→t) → (e→t)
                modifier ← T(dep)
                term ← Application(modifier, term)

            "det":
                // Determiners have type (e→t) → ((e→t) → t)
                quantifier ← T(dep)
                term ← QuantifierTerm(quantifier, restrictor: term)

            "nsubj", "csubj":
                // Subject: recurse into subject subtree, bind as ARG0
                subject ← T(dep)
                term ← bind_argument(term, arg: subject, position: ARG0)

            "obj", "dobj":
                // Object: recurse into object subtree, bind as ARG1
                object ← T(dep)
                term ← bind_argument(term, arg: object, position: ARG1)

    return term

The $\text{bind\_argument}$ function handles the interaction between quantified noun phrases and the verb. When the argument is a quantifier term (produced by a det dependent), the verb’s lambda term is threaded into the quantifier’s scope position. When the argument is a bare entity constant (a proper noun), it is applied directly via curried application.

Worked Example Link to heading

Consider the sentence “Every tall senator approved the new bill.” The Stanford CoreNLP dependency parse (Chen & Manning, 2014) produces the following tree:

approved(ROOT)
├── senator(nsubj)
│   ├── every(det)
│   └── tall(amod)
└── bill(obj)
    ├── the(det)
    └── new(amod)

The transpiler processes this tree bottom-up, starting from the leaves and composing terms at each level.

Step 1: Translate the subject subtree senator(nsubj).

The transpiler recurses into the senator node, which has two dependents: tall(amod) and every(det).

First, the leaf tall is translated to a modifier constant $\textsf{Tall} : (e \to t) \to (e \to t)$. The base noun senator becomes $\textsf{Senator} : e \to t$. The modifier is applied to produce a refined property:

(Tall Senator) : e → t

Next, the determiner every is translated to $\textsf{Every} : (e \to t) \to ((e \to t) \to t)$. The modified noun is wrapped as the restrictor, producing a quantifier term that awaits a scope:

Every (λx. (Tall Senator) x)  [scope: _]

Step 2: Translate the object subtree bill(obj).

The same recursive procedure applies. The leaf new becomes $\textsf{New} : (e \to t) \to (e \to t)$, and bill becomes $\textsf{Bill} : e \to t$. The modifier applies:

(New Bill) : e → t

The determiner the becomes $\textsf{The} : (e \to t) \to ((e \to t) \to t)$, and the modified noun is wrapped:

The (λy. (New Bill) y)  [scope: _]

Step 3: Compose at the root approved(ROOT).

The verb approved is assigned the binary relation type $\textsf{Approve} : e \to (e \to t)$. The transpiler now binds the subject and object arguments. The object quantifier’s scope is filled first — it receives the verb applied to the subject variable and the object variable:

Every (λx. (Tall Senator) x)
      (λx. The (λy. (New Bill) y)
               (λy. Approve x y))

The outermost quantifier $\textsf{Every}$ takes two arguments: the restrictor $\lambda x.\;(\textsf{Tall}\;\textsf{Senator})\;x$ and the scope $\lambda x.\;\ldots$. Within the scope, the inner quantifier $\textsf{The}$ takes its own restrictor $\lambda y.\;(\textsf{New}\;\textsf{Bill})\;y$ and scope $\lambda y.\;\textsf{Approve}\;x\;y$, where $x$ is bound by the outer abstraction and $y$ by the inner one.

Step 4: The final AST.

Apply(
    Every,
    Abstraction(x,
        Apply(Application(Tall, Senator), x)),
    Abstraction(x,
        Apply(
            The,
            Abstraction(y,
                Apply(Application(New, Bill), y)),
            Abstraction(y,
                Apply(Approve, x, y)))))

Each recursive call to $\mathcal{T}$ produces a self-contained typed term. The composition at each level is determined entirely by the dependency relation — amod triggers modifier application, det triggers quantifier wrapping, nsubj and obj trigger argument binding — which is why the algorithm generalizes across arbitrary dependency trees without sentence-specific rules.

Vector-Grounded Concept Base Link to heading

Lexical grounding is the bridge between surface forms and the formal representation. Each token is embedded via a sentence transformer, and the resulting vectors are clustered using seeded k-means into canonical concepts. The seed ensures determinism: identical inputs always produce identical concept assignments. Each cluster centroid defines a canonical concept with a stable SHA-256-derived identifier.

mapper ← CanonicalConceptMapper(n_clusters: 256, seed: 42)
mapper.fit(feature_vectors)

mapping ← mapper.map(feature, text: "senator", lemma: "senator")
// → ConceptMapping(concept_id: "a3f2c8", label: "Senator", confidence: 0.87)

The concept mapper assigns each token a canonical concept ID and a confidence score derived from the distance to the cluster centroid. These concept IDs are threaded into the lambda-calculus constants via the concept_id field, linking the formal representation to the distributional semantics.

Sample Lexicon Link to heading

After fitting the concept mapper to a corpus, each cluster centroid defines a canonical concept. The resulting lexicon annotates each concept with its semantic type, cluster ID, representative surface forms, and the proto-role frame assigned by the verb classifier. A fragment of such a lexicon:

Each entry records the mapping from distributional cluster to formal type. The surface form sets show which tokens ground to the same concept — senator, legislator, lawmaker, and congressperson all resolve to concept a3f2c8 with type $e \to t$. Verbs carry proto-role annotations that inform argument binding during transpilation. The two $\textsf{Bank}$ entries illustrate polysemy resolution: the surface form bank appears in both concepts, but the sentence transformer’s contextual embedding disambiguates the intended sense at runtime.

When the transpiler encounters the token ratify in a dependency tree, it queries the lexicon and retrieves concept b71e04 ($\textsf{Approve}$), producing the constant $\textsf{Constant}(\text{Approve},\; e \to (e \to t),\; \texttt{b71e04})$. This means the sentences “The senator approved the bill” and “The legislator ratified the measure” produce structurally identical lambda terms — both ground to the same concept constants — despite sharing no surface forms.

This grounding enables the recognition that two different surface forms may map to the same canonical concept if their embeddings cluster together. The confidence scores assigned by the mapper decrease with distance from the cluster centroid, reflecting decreasing typicality:

map("senator",    lemma: "senator")    → (concept_id: "a3f2c8", label: "Senator", confidence: 0.87)
map("legislator", lemma: "legislator") → (concept_id: "a3f2c8", label: "Senator", confidence: 0.81)
map("lawmaker",   lemma: "lawmaker")   → (concept_id: "a3f2c8", label: "Senator", confidence: 0.74)

Conversely, polysemous forms are distinguished by context. The word bank in “the river bank” and “the investment bank” receives different embeddings from the sentence transformer (which encodes the full sentential context), and these embeddings cluster into distinct canonical concepts — f44c12 (financial) vs. f44c13 (geographical) — with the contextual embedding resolving the ambiguity before the token reaches the transpiler.

Semantic Role Assignment Link to heading

A further refinement involves extracting Dowty (1991) proto-role features from dependency arcs to inform argument labeling. Agent-like properties (volitionality, sentience, causation) are associated with ARG0 positions, while patient-like properties (change of state, affectedness) are associated with ARG1.

Verb classification follows Levin’s (1993) taxonomy, which groups verbs by shared syntactic behavior and assigns thematic role frames accordingly. Returning to the running example, the verb approved belongs to a Levin class that shares the frame ARG0:Agent, ARG1:Theme with verbs like endorse, ratify, and sanction — the same synonyms that cluster together in the concept base.

The Stanford parser (Chen & Manning, 2014) produces $\text{nsubj}(\textit{approved},\;\textit{senator})$ and $\text{obj}(\textit{approved},\;\textit{bill})$. The Dowty classifier examines the proto-role features of each argument: senator is volitional and sentient (proto-agent), and bill undergoes a change of state — it becomes approved (proto-patient). These features confirm the ARG0/ARG1 assignment derived from the dependency relations, providing a redundant check that strengthens confidence in the resulting predicate-argument structure. The final lambda term thus carries both its formal type structure and its grounded proto-role annotations: $\textsf{Approve}$ is labeled with ARG0:Agent, ARG1:Theme, matching the lexicon entry for concept b71e04.

Summary Link to heading

The ideas presented here connect three traditions: dependency grammar for syntactic analysis, Montague semantics for compositional meaning representation, and distributional semantics for lexical grounding. The Stanford CoreNLP dependency parser (de Marneffe et al., 2014) provides the syntactic backbone — typed dependency relations that a transpiler can map systematically to predicate-argument structures. The typed lambda calculus provides a representation language that supports beta-reduction, type checking, and logical inference. And vector-grounded concept bases bridge surface variation with semantic identity. The synthesis yields a pipeline that takes raw text and produces typed, normalized, concept-grounded logical forms suitable for downstream reasoning tasks. Related approaches include incremental dependency-to-semantics translation for embodied agents (Brick & Scheutz, 2007), CCG-based Montague parsing (upshot-montague), Minimal Recursion Semantics as an alternative compositional formalism (Copestake et al., 2005), and monotonicity-driven inference from Universal Dependency trees (Chen & Gao, 2021).

References Link to heading

• Montague, R. "The proper treatment of quantification in ordinary English." In J. Hintikka, J. Moravcsik, & P. Suppes (Eds.), Approaches to Natural Language, pp. 221–242. Dordrecht: Reidel. 1973.
• Reddy, S., Oscar Täckström, Michael Collins, Tom Kwiatkowski, Dipanjan Das, Mark Steedman, and Mirella Lapata. "Transforming dependency structures to logical forms for semantic parsing." Transactions of the Association for Computational Linguistics, 4, 127–140. 2016.
• Bai, J. and Hai Zhao. "Dep2Sem: Learning the correspondence between dependency trees and formal meaning representations via syntax-guided attention." Findings of the Association for Computational Linguistics: ACL-IJCNLP 2021, pp. 2395–2405. 2021.
• de Marneffe, M.-C., Timothy Dozat, Natalia Silveira, Katri Haverinen, Filip Ginter, Yoav Goldberg, and Christopher D. Manning. "Universal Stanford Dependencies: A cross-linguistic typology." Proceedings of the 9th International Conference on Language Resources and Evaluation (LREC), pp. 4585–4592. 2014.
• Chen, D. and Christopher D. Manning. "A fast and accurate dependency parser using neural networks." Proceedings of the 2014 Conference on Empirical Methods in Natural Language Processing (EMNLP), pp. 740–750. 2014.
• Brick, T. and Matthias Scheutz. "Incremental natural language processing for HRI." Proceedings of the ACM/IEEE International Conference on Human-Robot Interaction, pp. 263–270. 2007.
• Kim, Y. and Raymond Mooney. upshot-montague: A CCG-based semantic parsing library implementing Montague semantics in Scala. 2013.
• Copestake, A., Dan Flickinger, Carl Pollard, and Ivan A. Sag. "Minimal recursion semantics: An introduction." Research on Language and Computation, 3(2–3), 281–332. 2005.
• Chen, Z. and Qiyue Gao. "Monotonicity marking from Universal Dependency trees." Proceedings of the 14th International Conference on Computational Semantics (IWCS 2021), pp. 31–41. 2021.
• Dowty, D. "Thematic proto-roles and argument selection." Language, 67(3), 547–619. 1991.
• Levin, B. English Verb Classes and Alternations: A Preliminary Investigation. Chicago: University of Chicago Press. 1993.

Mine lives at github.com/alexdjalali/dotfiles. It provisions a full macOS development environment from a blank machine in a single command. This post walks through what’s in it and why.

The Philosophy Link to heading

Three principles:

One theme everywhere. Catppuccin Mocha in the terminal, in the editor, in tmux, in git diffs, in bat output. Visual consistency across tools isn’t vanity — it reduces context-switching friction. When everything looks like it belongs together, your brain stops noticing the seams between tools and starts focusing on the work.

Modern replacements for legacy tools. ls becomes eza. cat becomes bat. grep becomes ripgrep. find becomes fd. sed becomes sd. du becomes dust. top becomes btop. diff becomes delta. These aren’t gimmicks. They’re faster, they have better defaults, and they produce output that’s actually readable.

One command, full setup. A fresh Mac should go from “nothing installed” to “fully productive” with ./install.sh. No manual steps. No “oh, I also need to install X.” The install script is idempotent — safe to run again whenever I add something new.

The Shell Link to heading

Zsh with Oh My Zsh, Powerlevel10k for the prompt, and a modular config that keeps .zshrc clean:

# .zshrc is a thin bootstrap that sources conf.d/ modules in order
export DOTFILES="${DOTFILES:-$HOME/dotfiles}"
for conf in "$DOTFILES/zsh/conf.d/"*.zsh(N); do
  source "$conf"
done

Each numbered file in conf.d/ handles one concern — environment variables, path setup, aliases, completions, fzf config, tool initialization. When I want to change how aliases work, I open 04-aliases.zsh. When I want to tweak fzf, I open 06-fzf.zsh. No scrolling through a 500-line .zshrc looking for the right section.

The plugins are minimal and deliberate:

• fzf-tab — replaces zsh’s default completion menu with fzf, so tab completion gets fuzzy matching and preview windows
• zsh-autosuggestions — ghost text from history
• zsh-syntax-highlighting — real-time command highlighting
• zoxide — frecency-based cd replacement (learns which directories you visit most)
• atuin — shell history with full-text search and optional sync across machines

I intentionally removed the default git plugin from Oh My Zsh. It defines 176 aliases, most of which I’ll never use, and some of which shadow commands I actually want. My own git aliases live in conf.d/04-aliases.zsh where I control exactly what exists.

tmux Link to heading

I spend most of my day inside tmux. The config is hand-rolled with Catppuccin Mocha colors — no plugin themes, just raw color codes mapped to the palette:

# Status bar
set -g status-style "bg=#181825,fg=#cdd6f4"
setw -g window-status-current-style "bg=#313244,fg=#cba6f7,bold"

# Panes
set -g pane-border-style "fg=#313244"
set -g pane-active-border-style "fg=#cba6f7"

Vim-style keybindings for everything: h/j/k/l for pane navigation, | and - for splits (instead of the unintuitive " and % defaults), v and y in copy mode. True color and undercurl support are configured so Neovim’s LSP diagnostic squiggly lines render correctly inside tmux — a detail that took an embarrassing amount of time to get right:

set -g default-terminal "tmux-256color"
set -ga terminal-overrides ",*-256color:Tc"
set -as terminal-overrides ',*:Smulx=\E[4::%p1%dm'
set -as terminal-overrides ',*:Setulc=\E[58::2::%p1%{65536}%/%d::%p1%{256}%/%{255}%&%d::%p1%{255}%&%d%;m'

tmux-resurrect and tmux-continuum handle session persistence. I can reboot and come back to exactly where I left off — same windows, same panes, same working directories.

Neovim Link to heading

AstroNvim-based config, fully Lua, with 30+ plugin configurations. The key pieces:

• LSP for every language I work in (Go via gopls, Python via basedpyright, TypeScript via ts_ls, Lua via lua_ls, LaTeX via texlab)
• DAP (Debug Adapter Protocol) for stepping through Go and Python without leaving the editor
• Treesitter for syntax highlighting, text objects, and structural navigation
• 59 custom LuaSnip snippets for LaTeX — 20 for TikZ/pgfplots, 17 for Beamer presentations, 22 for common packages and document structures

The LaTeX setup deserves a mention. I do academic writing in Neovim with VimTeX, latexmk for continuous compilation, and Skim for PDF preview with SyncTeX forward/inverse search. Click a line in the PDF, and Neovim jumps to that line in the source. Click a line in Neovim, and Skim jumps to the corresponding position in the PDF. Once you’ve experienced this workflow, writing LaTeX in anything else feels broken.

Git Link to heading

The .gitconfig is opinionated:

[core]
	editor = nvim
	pager = delta
	fsmonitor = true
	untrackedCache = true

[commit]
	gpgsign = true

[delta]
	navigate = true
	side-by-side = true
	syntax-theme = "Catppuccin Mocha"

[diff]
	algorithm = histogram

[merge]
	conflictstyle = diff3

[rerere]
	enabled = true

[pull]
	rebase = true

[rebase]
	autoStash = true
	autoSquash = true

A few choices worth explaining:

GPG signing on every commit. Non-negotiable. If your commits aren’t signed, anyone can impersonate you with git config user.email.

Delta as the pager. Side-by-side diffs with syntax highlighting and line numbers, themed to match everything else. git diff output becomes something you actually want to read.

Histogram diff algorithm. Produces better diffs than the default Myers algorithm, especially for moved blocks of code. Once you switch, you notice the difference immediately and never go back.

rerere enabled. “Reuse recorded resolution” — git remembers how you resolved a conflict and applies the same resolution automatically if it encounters the same conflict again. Essential for long-running feature branches that rebase often.

Pull with rebase, rebase with autoStash. No merge commits from git pull. If I have local changes when pulling, git stashes them automatically, rebases, and pops the stash. Clean linear history with zero effort.

The Brewfile Link to heading

Everything I install lives in one file. Running brew bundle on a fresh machine installs the entire stack — CLI tools, languages, casks, fonts:

# Modern CLI Replacements
brew "eza"         # ls
brew "bat"         # cat
brew "ripgrep"     # grep
brew "fd"          # find
brew "sd"          # sed
brew "dust"        # du
brew "btop"        # top
brew "delta"       # diff
brew "xh"          # curl
brew "doggo"       # dig

# Languages
brew "go"
brew "python@3"
brew "uv"
brew "node"
brew "pnpm"
brew "oven-sh/bun/bun"

# Kubernetes
brew "kubectl"
brew "k9s"
brew "helm"
brew "kind"
brew "stern"
brew "lazydocker"
brew "dive"
brew "trivy"

# Infrastructure
brew "terraform"
brew "pgcli"
brew "mongosh"
brew "grpcurl"

The full Brewfile has 80+ entries. The point isn’t that I use all of them every day — the point is that when I need k9s or grpcurl or hyperfine, it’s already there. The cost of installing something unused is a few hundred megabytes of disk. The cost of needing something that isn’t installed is a context switch away from the problem I’m solving.

Raycast Scripts Link to heading

Raycast replaced Spotlight on my machine. Beyond its built-in features, I have 29 custom script commands in ~/dotfiles/raycast/ that automate common workflows:

• focus-mode.sh / end-focus-mode.sh — toggle Do Not Disturb, close distracting apps, set Slack status
• meeting-mode.sh — same as focus mode but opens Zoom and positions windows
• open-project.sh — fuzzy-find a project directory and open it in Cursor
• lazygit-here.sh — open lazygit in the current Finder directory
• git-status-all.sh — check git status across all project directories at once
• dev-stack.sh — start/stop the local dev stack (Docker containers, databases)
• k8s-context.sh — switch kubectl context without remembering cluster names
• window-layout-coding.sh — arrange windows into my preferred coding layout

Each script is a plain bash file with Raycast metadata in the header. No plugins, no dependencies, no framework. When something annoys me more than twice, it becomes a Raycast script.

The Install Script Link to heading

The whole thing bootstraps from a blank Mac:

git clone https://github.com/alexdjalali/dotfiles.git ~/dotfiles
cd ~/dotfiles
./install.sh

The script runs 15 steps: Xcode CLT, Homebrew, brew bundle, shell setup, Oh My Zsh with plugins, symlinks (with automatic backup of existing files), fzf integration, bat/delta Catppuccin theme, iTerm2 shell integration, directory scaffolding, TPM and tmux plugins, git-lfs, LaTeX environment, and a headless Neovim bootstrap that syncs all plugins and installs Treesitter parsers.

It’s idempotent. Every step checks whether it’s already been done before doing it. Symlinks check whether they already point to the right place. Homebrew checks whether it’s already installed. The script produces a clean log of what it did and what it skipped:

[ok]    Homebrew already installed
[ok]    ~/.gitconfig -> ~/dotfiles/git/.gitconfig (already linked)
[info]  Installing Oh My Zsh plugins...
[ok]    fzf-tab already installed
[warn]  Backed up ~/.tmux.conf -> ~/.dotfiles-backup/20260115_143022/
[ok]    ~/.tmux.conf -> ~/dotfiles/tmux/.tmux.conf

AI Tool Integration Link to heading

The dotfiles also manage my AI coding tool configurations. The same engineering standards get symlinked into three different tools:

~/.claude/CLAUDE.md        -> ~/dotfiles/.claude/CLAUDE.md
~/.claude/settings.json    -> ~/dotfiles/.claude/settings.json
~/.claude/commands         -> ~/dotfiles/.claude/commands
~/.cursor/rules            -> ~/dotfiles/cursor/rules
~/.kilocode/rules          -> ~/dotfiles/kilocode/rules

This means my Claude Code, Cursor, and Kilo Code configurations are version-controlled alongside everything else. When I update a standard — say, adding a new quality gate or refining an architecture pattern — the change propagates to every tool the next time I open it. I wrote more about this workflow in How I Learned to Love the Bomb.

The Point Link to heading

None of this is about having the fanciest terminal or the most plugins. It’s about removing friction. Every tool configured here solves a specific problem I hit repeatedly: navigating code, reviewing diffs, managing containers, switching contexts, staying in flow.

The dotfiles repo is the mechanism that makes this sustainable. Without it, I’d spend my first day on any new machine reinstalling things from memory, getting half the configs wrong, and losing a day of productivity. With it, I clone one repo, run one script, and I’m working.

The whole thing is MIT-licensed and on GitHub if any of it is useful to you.