The Catalogue of Façades

What a catalogue of façades is for

The Synedre's agentic harness is not a monolith: it is a constellation of small executable entry points — Python scripts under synedre/ and binaries under bin/. Each carries a single role. The catalogue of façades maps these entry points with, for each, its family, its one-line role and its typical invocation mode. The goal: that an engineer picking up the repository can quickly find which script does what, without rereading hundreds of files.

The guiding principle is simple — one module, one façade. When a domain of the system (client email, antivirus scanning, deployment) must be touched, there is a single, mandatory entry point. A façade is never bypassed: it is the façade that carries the safeguards.

Extraction method and coverage

The catalogue's descriptions are not invented: they are extracted programmatically from the first docstring or header comment of each file. For Python, a loop reads the module docstring; for bin/* binaries, the first non-banner description line. When a file carries only a boilerplate header (@author / @copyright), the real docstring is fished out a few lines below. This recovery is not systematic, and the reliability of each entry is annotated rather than oversold.

Coverage is tracked explicitly: the catalogue distinguishes the real total of files on disk from the number actually detailed.

Category	Real total on disk	Covered
synedre/*.py	~180	all listed or attached to a family
bin/* (executable entries)	~80 entries	executable scripts detailed; data files and caches not detailed one by one

Drift detected. A cross-check between the crontab and the actual contents of synedre/ reveals several dozen dead cron entries: they point to Python files that have been deleted or renamed. The catalogue documents this gap rather than hiding it — an honest catalogue also maps its own holes. These entries are to be cleaned up.

The legend of invocations

Each façade carries a typical invocation mode. Understanding this vocabulary is enough to know how a script is meant to be triggered.

Code	Meaning
cron	Launched by the scheduler, often through a shared watchdog wrapper
CLI	Called by hand from the command line
skill	Façade behind a Claude Code skill (.claude/skills/<name>/)
hook	Claude Code hook (SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop)
lib	Imported module, not a standalone entry point
worker	Daemon or loop draining a database queue

The common base and the data layer

Every family converges on a single database, accessed exclusively through a Python PostgreSQL façade. No script talks to the database directly: it goes through this façade, which centralises the connection, and through an environment façade that loads configuration variables. Secrets live in out-of-repository environment files (gitignored) — never in plaintext in the code or the documentation.

Above this layer sits a base of cross-cutting façades, shared by every other family.

Façade	Role	Invocation
PostgreSQL façade	Python access to the single database for all automates	lib
Sandbox connection helper	Database connection for sandboxed agents	lib
Environment façade	Centralised loading of configuration variables	lib
Structured logger	Mandatory logging for all automates	lib
Cron wrapper	Autonomous watchdog for scheduled automates	cron
AI façade	Provider-agnostic layer (embed / complete)	lib
Agent invocation	Call a Synedre agent from any automate	CLI / lib
PII filter	Strips personal data before any send to the LLM pipeline	lib

Atlas and orchestration

The atlas family carries the orchestrating core: receive an incoming email, classify its intent (run, chantier, question, noise), then act. A doctrinal rule frames agent invocation: an agent is always called through a pseudo-tty terminal (node-pty) that captures its stream of thought for audit, never in an opaque mode.

Façade	Role	Invocation
Inbox poll	Polls the orchestration mailbox at regular intervals	cron
Intent classifier	Classifies a message's intent via LLM	lib / CLI
Spawn	Launches a headless intelligence to act on classified messages	worker
Ship-via-email	Triggers a production release by email, with triple anti-spoof verification	CLI
Post-ship monitoring	Monitors after release, with a single automatic rollback	cron
Per-task ReAct cycle	Runs a task's reason-act cycle	worker
Runaway detector	Auto-pauses tasks blocked too long or too costly in tokens	cron
Post-deploy QA	Two-tier quality control after deployment	cron / CLI

Chantiers

The chantiers family embodies the multi-step creation workflow: read the request, audit available agents, draft a mission letter, explicitly recruit the team, create the atomic skeleton (chantier + travaux + tasks). The official "chantier from email" façade runs these steps under constraint.

Façade	Role	Invocation
Chantier from email	Creates a client chantier from an incoming email	CLI / skill
Live chantier	Live tail of agent events on a chantier	CLI
Mission letter	Generates a draft mission letter	lib
Auto-explode discovery	LLM pipeline turning a discovery into implementation tasks	worker
Token estimator	Estimates token cost and recommends a model per task	lib
Pattern detector	Spots recurring patterns across task iterations	cron
Validation QA	Quality validation of a travail by its team	worker
Lead scanner	Detects incoming leads from appointment bookings	cron / skill

Audits, quality and security

A whole family watches over the system's health: nightly audits of automates, of the database schema, of dependencies, of backups; automated pentest; accessibility audit; HTTP monitoring of production sites. The principle: observe continuously, alert, and apply an automatic fix only under a strict safeguard.

Façade	Role	Invocation
Automates audit	Nightly audit of all automates	cron
Schema audit	Daily audit of the database schema vs naming convention	cron
Backups surveillance	Daily check of database backups	cron
Restore test	Monthly restorability test of a database dump	cron
Pentest	Automated pentest	CLI / skill
Accessibility audit	WCAG 2.2 AA audit	CLI
Uptime monitoring	HTTP monitoring of production sites	cron
QA gate (review)	Heuristic quality-review verdict (go / with reservations / no-go)	CLI
Infra audit	Unified infra audit of mothership and tenants	CLI / skill
OSS-safety audit	Scans the OSS core against any leak of tenant-specific lexicon	CLI
Multi-tenant smoke test	Smoke test of sites, failing on a server-error HTTP response	CLI

Memory, scars and learning

This family carries the system's learning loop: harvesting scars from the git history, LLM re-qualification, injecting active scars at session start through hooks, nightly memory consolidation, and semantic recall via vector search. Memory lives on three levels — working memory, a Zettelkasten second brain, vector semantic memory — but the database remains the only source of truth.

Façade	Role	Invocation
Scar harvest	Automatic harvest of scars from the git history	cron
Scar re-qualification	Batch LLM reclassification of scars	cron
Session-start injection	Hook reconnecting active memory at session start	hook
Pre-tool injection	Hook injecting scars before a tool runs	hook
Post-chantier lesson	Drafts a pedagogical retrospective after a chantier	CLI / skill
Nightly consolidation	Consolidates memory overnight	cron
Semantic recall	Vector search retrieving the relevant note	CLI / skill
Second-brain indexing	Indexes the Zettelkasten into the semantic store	cron
Context tracking	Estimates the context budget consumed in a session	lib / skill
Immutable hard-floor	Loads and validates the manifest of immutable P0 blocks	lib / skill

Inbox and client email

A hard rule governs this family: the intelligence never sends an email to a client directly. Everything goes through a single email façade, in two beats — a draft, then an explicit send after human validation. A hook blocks any attempt to use a direct SMTP client. The mailbox credentials live in an out-of-repository environment file; their values appear nowhere in the code or the documentation.

Façade	Role	Invocation
Client email	Send workflow: draft, review, send, archive	CLI (single façade)
Email façade guard	Hook enforcing the mandatory email façade	hook
Inbox sync	Polls the inbox into the database	cron
Direct inbox	Direct connection to the mail server, as an emergency fallback	CLI / skill
Attachment AV scan	Façade scanning attachments before opening	CLI / skill
Tone of voice	Resolves the writing register per lead or client	lib
Appointment sync	Syncs bookings into the CRM pipeline	cron
Cost alert	Checks the monthly LLM API total against the budget	cron

Blog, SEO and content

The content family carries DB-first publishing: a publishing engine, article cleanup, cover and carousel generation, SEO duplicate watching, product description generation, and a translation sub-family covering FR → EN (and DE) across the interface, base content and product sheets.

Façade	Role	Invocation
Publishing engine	DB-first article publishing	CLI / skill
Blog hygiene	Automatic article cleanup	cron
Cover generator	Generates article cover images	cron / CLI
Carousel generator	Produces square-format social carousels	CLI
Cannibalisation radar	Detects SEO duplicates and near-duplicates	cron
Product sheet generator	Writes product descriptions	CLI
Content translation	Completes FR-only fields into EN in the database	CLI

Browser agents

One family drives Playwright for web automation. Its protection doctrine is instructive: a SOCKS proxy handles address reputation but not the browser's behavioural detection; some actions therefore require a visible browser on a residential machine. Classifying the protection always precedes coding the flow.

Façade	Role	Invocation
Browser agent	Playwright automate with residential egress via proxy	lib
Browser worker	Visible-browser worker on a residential machine	worker
Browser job queue	Interface to the browser job queue	CLI
Screenshot	Captures pages via headless Chromium	CLI / lib
Fleet scan	Scans the site fleet	cron / CLI

Banking, invoicing and finance

The finance family covers bank synchronisation, statement import with deduplication, recurring invoicing and reminders, and the tracking of production fixes. Write operations on a production database go through a dedicated secure wrapper.

Façade	Role	Invocation
Bank sync	Cron entry point for the banking domain	cron / skill
Statement import	Parses a bank export with deduplication	CLI / skill
Recurring invoicing	Daily recurring-invoicing cron	cron
Reminders	Daily reminders and reconciliation cron	cron

Deployment, ship and infra

This family embodies the hard asymmetry rule between deploying and going to production. ./deploy is always the intelligence's job: it deploys to preprod without asking. ./ship is the production release, a manual gesture exclusive to the Founder — the intelligence never touches it. On the mothership itself, deploying means a live rebuild, with no preprod. And before any deployment, you commit: uncommitted changes are lost in the rebuild.

Façade	Role	Invocation
Deployment helpers	Functions shared across deployment scripts	lib
deploy.yaml validation	Parses and validates the deployment config	lib
Git-clean check	Verifies the git tree is clean before deployment	CLI
Safe production SQL write	Secure wrapper for any SQL write in production	CLI
Tenant bootstrap	Initialises a new tenant from the template	CLI
Provisioning	Automatically provisions a machine for a client	CLI
Post-ship health check	Health check and automatic rollback after release	CLI
Encrypted backup	Encrypted backup of critical files to object storage	cron / CLI
Restore from storage	Restores a database from an object-storage backup	CLI

The Claude Code hooks

Beyond the families above, an entire subsystem lives in hook configuration files. Hooks wire the façades to the key moments of a session's lifecycle: start, before and after each tool, prompt submission, and session end.

Moment	Hook role
SessionStart	Resets context tracking, loads the session brief, injects active memory
PreToolUse:Bash	Production-write safeguard, mandatory email façade, scar injection
PreToolUse:Edit|Write	Scar injection before a file edit
PreToolUse:Agent	Scar injection before an agent invocation
PostToolUse	Automatic context tracking, ReAct cycle logging, agent telemetry
Stop	Releases chantier locks, git-clean safeguard (blocks if the git tree is not clean), chantier synchronisation cascade

The "uncommitted git at Stop" safeguard is what embodies the commit-in-flow doctrine: no finished work stays uncommitted. The hook blocks session end as long as the tree is not clean.

Reliability notes

A good catalogue is honest about its limits. Three caveats accompany this one:

• Scripts whose only header was boilerplate had their real role fished out further down the file — no role was invented, and uncertain cases are annotated.
• The "invocation" column mixes the certain (verified presence in the crontab) with the inferred (a "daily cron" mention read in a docstring). For scheduling truth, only direct inspection of the scheduler is authoritative.
• The skill ↔ façade mapping is sourced from skill sheets, which were not all opened one by one: to be confirmed case by case.

This is the spirit of the catalogue: map faithfully, flag the drift, and never oversell certainty.