Communitygithub.com

lguidolin/engineering-constitution

Use when starting work in a project that follows the engineering constitution, orienting to its rules, or deciding which engineering practice applies to a task — spec writing, commits, testing, security, deploys, database, or UI work.

What is engineering-constitution?

engineering-constitution is a Claude Code agent skill that use when starting work in a project that follows the engineering constitution, orienting to its rules, or deciding which engineering practice applies to a task — spec writing, commits, testing, security, deploys, database, or UI work.

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lguidolin/agent-skills/tree/main/skills/engineering-constitution
View original→Browse all skills

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentation

Engineering Constitution

Overview

A portable charter of engineering practice, decomposed into focused skills. This skill is the index: it states the inviolable principles and routes you to the specific skill for your task. The full reasoning lives in references/engineering-constitution.md, bundled alongside this SKILL.md so it travels with the skill wherever it is installed.

Core idea: Software engineering is programming integrated over time. Optimize for the long-lived system — operating it, changing it safely, recovering when it breaks — not the first deploy.

The Eight Inviolable Principles

  1. Understand before building. No code before an approved design.
  2. Record every decision with its rationale — and what you rejected.
  3. Tests are a control, not a formality — and behavioral change is test-first. A failing test is information, never edited away. Structural change is gated instead by the existing suite passing unedited.
  4. YAGNI, ruthlessly.
  5. Automate the repeatable.
  6. Software engineering is programming integrated over time.
  7. A rule not enforced is a suggestion. Bind rules to tooling or label them reviewer-judgment.
  8. The user's explicit instructions outrank this document. Precedence: User → Constitution → tool defaults.

Which Skill Do I Need?

Tier 1 — universal (applies to every project):

Your taskSkill
Starting a feature, turning an idea into a spec/plandesigning-before-building
A decision was made; writing it down (ADR, index, deferred ideas)recording-decisions
Committing, writing messages, automated releasesconventional-commits-and-releases
Writing/changing tests; permission/role rules; a test broke in a refactortests-as-a-control
Writing or refactoring code; structuring a change; DRY decisionschange-hygiene-and-code-craft
Building UI, components, styling, accessibilityinterface-craft-and-accessibility
CI, pre-push hooks, task runners, merge gatesmerge-gates-and-automation
Logging, metrics, tracing, health checks, SLOs, alertsobservability-and-slos
Untrusted input, secrets, auth, dependencies, threat modelingdefense-in-depth-security
Hot paths, pagination, N+1, list endpoints, public interfacesperformance-and-scale
Planning a deploy, rollback, or incident/postmortemresilience-and-deploy-safety

Tier 2 — stack-specific (load only when the tooling/topic is present):

Your taskSkill
PostgreSQL, PostGraphile, RLS, SQL files, the app→GraphQL→DB pathpostgres-postgraphile-rls-and-sql
GraphQL queries shared between UI and tests; route/schema contract testsgraphql-contract-testing
Schema change with data that must survive — migrations, backfillszero-downtime-migrations
Deploying to Kubernetes/AKS, cloud secrets, progressive rollout, per-PR envscloud-delivery-aks

How These Skills Apply to a New Project

  • Tier 1 travels unchanged. Every skill above the line applies to any project — web app, pipeline, CLI, library.
  • Tier 2 is swappable. When the stack differs, the Tier-2 skills won't trigger (their descriptions are stack-specific) and you substitute equivalents. The principles they implement (one data path, final enforcement low, contract seams, reversible deploys) still hold.
  • Scale to lifecycle. A pre-launch or local-only project applies zero-downtime migrations, canary, and formal incident process as write-the-rule-now, activate-on-trigger. State the project's mode in its first decision record.

Red Flag

If you're about to write code, commit, deploy, or change a test and you have not consulted the relevant skill above — stop and load it first. The constitution overrides default habit (Principle 7); habit is what it's correcting for.

Individual skills in this repo

This repo contains 18 individual skills — each has its own dedicated page.

lguidolin/change-hygiene-and-code-craft

Use when writing or refactoring code, structuring a commit or PR, or deciding whether to abstract duplication. Symptoms — mixing reorg with logic changes, a PR doing several things at once, a file growing large, the second copy of similar code, or unsure whether to DRY something up.

lguidolin/cloud-delivery-aks

Use when deploying to Kubernetes or Azure Kubernetes Service (AKS), configuring cloud secrets, setting up progressive rollout/canary, per-PR ephemeral environments, or k8s health probes. Keywords — Kubernetes, AKS, Key Vault, Argo Rollouts, Flagger, canary, blue-green, liveness, readiness, PodDisruptionBudget, HPA, rollback, GHCR.

lguidolin/commit-history-rewrite

Use when an existing repository has messy commit history that needs to conform to conventional commits before adopting release-please, or when intermediate WIP/fixup/merge commits need to be cleaned up.

lguidolin/conventional-commits-and-releases

Use when committing, writing a commit message, opening a PR that will be squash-merged, or configuring automated versioning/changelogs. Keywords — conventional commits, release-please, semver, feat/fix/chore, breaking change, changelog.

lguidolin/defense-in-depth-security

Use when handling untrusted input, secrets, authentication/authorization, or dependencies — or threat-modeling a new surface. Keywords — STRIDE, threat model, least privilege, secrets management, supply chain, dependency scanning, input validation, audit log, defense in depth.

lguidolin/designing-before-building

Use when starting a feature, fixing a non-trivial bug, or about to write implementation code — before any code exists. Symptoms you need this: "this is simple, I'll just code it", reaching for the editor before a design is approved, or an idea that hasn't been turned into a spec and plan.

lguidolin/graphql-contract-testing

Use when writing a GraphQL query/mutation that the UI and a test will share, or building route/schema contract or smoke tests. Symptoms — copying a query into a test, a test asserting on query text, schema change that didn't break the UI build, or RLS/permission drift. Keywords — graphql-codegen, typed document, contract test, route smoke test.

lguidolin/init-repo-CI

Use when setting up a new repository with conventional commits, release-please, and CI automation, or when retrofitting an existing repository that lacks automated versioning and PR validation workflows.

lguidolin/interface-craft-and-accessibility

Use when building or styling UI — components, layouts, forms, design tokens — or making accessibility decisions. Keywords — a11y, WCAG, keyboard navigation, focus state, contrast, design system, minimalist UI, component reuse, ARIA, semantic HTML.

lguidolin/merge-gates-and-automation

Use when setting up or changing CI, pre-push hooks, or a task runner, or deciding what must pass before merge. Symptoms — tempted to put authoritative checks only in a local hook, skip CI, bypass with --no-verify, or unsure what gates a merge vs. runs locally.

lguidolin/observability-and-slos

Use when adding logging, metrics, tracing, health checks, SLOs, or alerting — or when building a service surface that needs to be operable and debuggable. Keywords — structured logs, OpenTelemetry, correlation id, RED metrics, liveness, readiness, SLI, SLO, error budget, alerting.

lguidolin/performance-and-scale

Use when working on hot paths, list endpoints, pagination, data-access in loops, or public interfaces/schemas. Symptoms — unbounded queries, N+1 access, no latency budget, optimizing without measuring, or changing an interface many consumers depend on. Keywords — pagination, N+1, Hyrum's Law, performance budget, bundle size.

lguidolin/postgres-postgraphile-rls-and-sql

Use when writing PostgreSQL, PostGraphile config, Row-Level Security policies, SQL schema files, or working on the Browser→App→PostGraphile→Postgres data path. Keywords — RLS, SECURITY DEFINER, search_path, pgSettings, grants, roles, GraphQL depth limit, query cost, statement_timeout, SQL file organization.

lguidolin/recording-decisions

Use when a design or architecture decision has been made and needs to be captured — writing a decision record or ADR, updating a decision index, noting a deferred idea, or superseding a past decision. Keywords — ADR, decision record, rationale, rejected alternatives, dependency index.

lguidolin/resilience-and-deploy-safety

Use when planning a deploy, designing a rollback, or responding to an incident or writing a postmortem. Keywords — deploy safety, rollback, immutable artifact, progressive delivery, canary, blast radius, incident response, blameless postmortem, error budget.

lguidolin/ship-it

Use when the user wants to ship work — push, PR, archive decision records, merge, and clean up. Handles the full lifecycle from committing final changes through post-merge cleanup including converting specs/plans to compact decision records.

lguidolin/tests-as-a-control

Use when writing or modifying tests, when a test breaks during a refactor, or when testing permission/role rules. Symptoms — tempted to edit a test to make it pass, testing only the happy path, a deny-test that started passing, flaky tests, or unsure what to assert.

lguidolin/zero-downtime-migrations

Use when changing a database schema where data must survive the change — adding/removing/renaming columns, constraints, indexes, or backfilling. Symptoms — a destructive migration bundled with a code deploy, a NOT NULL column with a backfill, a table-locking UPDATE, or a rename. Keywords — expand/contract, parallel change, backfill, NOT VALID, CREATE INDEX CONCURRENTLY, graphile-migrate.

Related Skills

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

affaan-m/prisma-patterns

Prisma ORM patterns for TypeScript backends — schema design, query optimization, transactions, pagination, and critical traps like updateMany returning count not records, $transaction timeouts, migrate dev resetting the DB, @updatedAt skipped on bulk writes, and serverless connection exhaustion.

community

affaan-m/django-celery

Django + Celery async task patterns — configuration, task design, beat scheduling, retries, canvas workflows, monitoring, and testing. Use when adding background jobs, scheduled tasks, or async processing to a Django app.

community

affaan-m/quarkus-patterns

Quarkus 3.x LTS architecture patterns with Camel for messaging, RESTful API design, CDI services, data access with Panache, and async processing. Use for Java Quarkus backend work with event-driven architectures.

community