Skills, agents & hooks — Synedre OS agentic harness

Agentic Harness Overview

The Synedre OS agentic harness rests on three complementary layers: skills (invocable capability modules), agents (delegatable sub-agents with their own identity) and event hooks (guardrails and nudges triggered automatically at each step of a session lifecycle). The whole system is driven by two configuration files that coexist.

Configuration file	Versioned	Contents
Versioned settings file	Yes	PreToolUse / PostToolUse / Stop / UserPromptSubmit hooks, environment variables, default permission mode
Local settings file	No	Permission allowlist (several hundred entries), SessionStart / UserPromptSubmit / PreToolUse / PostToolUse hooks, automatic mode

Both sets of hooks are cumulative: for the same event (for example PreToolUse on the Bash tool), the commands from both files are executed. This is why Python guardrails live in the local file while shell nudges appear in the versioned file.

Skills Catalogue

Each skill is an autonomous capability module, defined by a markdown description file. It can be invoked manually or triggered by the engine. Some internal skills are not intended for direct invocation.

Audit and System Health

• General audit — Full audit of a site or property: infrastructure healthcheck, public pages, SEO, performance, security, database. Produces a score out of 100.
• Allowlist anti-rot — Verifies that every path and named section in the immutable P0-level allowlist still exists. Guards against silent drift of critical references.
• SEO i18n audit — Checks translation key parity FR↔EN, consistency of localised URL slugs, and the routing map. Must be run before any deployment touching pages, internationalisation, or routing.
• Lexical registry audit — Detects drift between the canonical dictionary in the database and code schemas. Strict read-only mode; returns a healthy or drifted exit code.
• Personas audit — Compares agent personas against the current stack and records a drift snapshot in the dedicated history.
• System status — Checks the overall system status (services, connectivity, resources).
• Session context status — Returns the state of the current session context.

Infrastructure and Hosts

• Infra audit — Checks availability, load, services, SSL certificates and backups for a given host.
• Security audit — Security audit of a host (the mothership VPS or a client VPS).
• Backup verification — Checks the freshness and integrity of local backups on a host.
• System update — Runs a non-interactive APT update with Docker package pinning.
• Bot analysis — Analyses the robot hit log collected by the server.
• GSC query — Queries the Google Search Console API to surface SEO opportunities.

Project Steering

• Project — Drives the "1 project = N tasks" doctrine: skeleton creation, task tracking, database read of projects and their associated tasks.
• Run — Opens a scoped run (lightweight unit symmetric to the project). Loads the scope from the database (mothership, tenant, deal) and returns the current line. Distinct from the native application launcher.
• Deal — Loads the full context of a commercial deal: file, qualification, team, log, deliverables. Symmetric to the project for the prospect → contract pipeline.
• Idea — Creates a brainstorm note in the dedicated table.
• Review — Place des Armes review: each agent introduces itself and reports its status.
• Post-project lesson — Generates a pedagogical lesson after a project (Montessori method) and deposits it in the Obsidian Vault inbox.

Email and Inbox

• Inbox (façade) — Reads and searches emails via the application façade, in the database.
• Direct inbox — Fallback IMAP access, read-only, no database writes. Used when the façade is unavailable.
• Inbox search — Ergonomic wrapper for email retrieval and analysis: download in .eml format, attachment listing without prior extraction (scan-first approach).
• Attachment scan — Antivirus analysis of an attachment before opening, via the Mitnick agent.
• Commercial proposal check — QA of a commercial proposal before email dispatch, orchestrated across a pool of four agents.

Memory and Knowledge

• Semantic recall — RAG (retrieval-augmented generation) search by vector similarity over the documentary memory and the scars, doctrines, and projects in the database. Uses high-dimensional cosine embeddings.
• Zettelkasten — Decomposes a monolithic document into atomic notes for the Obsidian Vault.
• Technical dictionary — Adds terms to the shared technical dictionary.
• Victory — Records a victory as a victory-type scar in the database.
• Persona refresh — Updates an agent persona via an AI model, a three-way comparison and a review, then persists the update to the database.

Finance and Business

• Bank — Queries accounts and transactions via the banking façade.
• Bank import — Manual import of transactions from an N26 CSV export into the database transactions table.
• Invoicing — Creates, lists, generates PDFs and sends invoices and quotes via the invoicing façade. Manages recurring subscriptions. The canonical issuing entity is always the system owner's legal entity.
• Malt prospects — Retrieves prospect conversations from the Malt platform.

Publishing and SEO

• Article publishing — Publishes a blog article to the designated web property.
• Scar publishing — Full pipeline: curation → sanitisation → adversarial review by Mitnick → publication of Synedre's public scars. Publishes the trophy scar (extracted lesson); never publishes the tutorial scar (exploitable reproduction).
• SEO sentinel — Early detection of ranking haemorrhage across multiple properties. Launches the monitoring automation and reformulates the report.

Documentation and QA

• Technical documentation — Generates or refreshes technical documentation via multi-agent orchestration (authoring → verification → correction). Supports a selective refresh mode (stale pages only) and a no-synthesis mode. Never commits without explicit validation.
• Visual QA — Captures a screenshot via Playwright and submits the image to a multimodal sub-agent to verify that the visual intent is correctly rendered — beyond mere code execution success.
• Site clone — Generates the "server access and information" intake protocol for cloning a client's existing site onto a VPS, and drafts the access request email.

Database Sources of Truth

Skills do not store business data: they query the central database via dedicated tables. The following maps the main skills to their persisted entities:

Skill	Database entities
Project	Projects table, project tasks table
Semantic recall	Scars table, doctrines table, projects table
Victory	Scars table (kind = 'victory')
Idea	Brainstorm table
Personas audit	Persona drift history table
Persona refresh	Agents table
Inbox	Inbox emails table
Bank import	Bank transactions table

Architecture note: a pre-invocation hook queries the declared size of each skill in the database to decide whether a deferred load (three-level lazy-load) should be suggested, in order to preserve session context for large skills.

Sub-agents: delegable personality files

The system includes around thirty agent personality files, each delegable via the internal delegation mechanism. Each file describes a named agent: its role, delegation criteria, authorized tools, and target language model.

Part of each file is automatically generated from the database (persona data: canonical name, description, capabilities) and enclosed within managed-zone markers. The editorial zone — doctrine, operating mode, business instructions — is written by hand and preserved across each regeneration. The managed zone must never be edited manually: any modification would be overwritten at the next synchronization.

Source of truth: the physical agents table (accessible in read mode via a dedicated view) is the sole reference. The regeneration script reads the view; the persona refresh tool writes to the base table. Both operate on the same source: no risk of divergence between view and table.

Each personality file exposes three frontmatter metadata fields: a public name, a description serving as the automatic delegation criterion, and the list of authorized tools.

Execution agents

These agents have both read and write access, as well as the ability to execute system commands. They act directly on repository artifacts and infrastructure.

Public codename	Domain	Capabilities
Brunel	Infrastructure & DevOps — container orchestration, reverse proxy, SSL certificates, DNS, mothership VPS management	Read, write, execute, search
Turing	Backend & server reliability — Nuxt application layer, business modules, Python scripts, database integrity	Read, write, execute, search
Eames	Frontend — Nuxt 4 / Vue 3 / Tailwind interface, design system, hub pages	Read, write, execute, search
Otlet	Technical SEO — structured markup, sitemap, Core Web Vitals, redirects, AI indexability	Read, write, execute, search
Lovelace	Quality assurance — last gate before production, acceptance testing, regression detection	Read and search only (no write access)
Mitnick	Offensive & defensive security — attachment analysis, exposed secret detection, OWASP audit	Read and search only (no write access)

Lovelace and Mitnick deliberately hold no write or execution rights: their role is control, not mutation. Mitnick in attachment-analysis mode is a tooling instrument (a prerequisite step before any workstream), not a recruited team member.

Advisory and knowledge agents

These agents have read-only access to the repository and documentary sources. They produce analyses, recommendations, drafts, and reports — never direct execution or file modification.

Public codename	Role
Atlas	Architect & project lead — partitions work into workstreams, dispatches to specialized agents, orchestrates delegation doctrine
Audiard	Audio author — rewriting for the ear (rhythm, orality, breath)
Bernays	Business growth — lead pipeline, conversion funnels
Bernhardt	Audio quality control — scoring (9.5/10 blocking threshold), diction, fidelity to source text
Braille	Accessibility — WCAG 2.2 AA compliance (keyboard navigation, contrast ratios, ARIA)
Clausewitz	Strategy — consistency of product decisions against positioning
Coco	Brand guardian — tonal refinement, cross-channel visual consistency
Colbert	General management — workstream prioritization, resource allocation, steering
Dumas	Narrator — serialized storytelling, emotional arcs, episodes, characters
Gauss	Data analysis — metrics (traffic, conversion, costs), insight reporting
Hill	Long-term vision — strategic direction, North Star
Hokusai	Illustration — character design & manga/manhwa illustration via generative AI
Itten	Art direction — color palette, typography, design tokens
Marco Polo	Intelligence — technology, competitive, and market monitoring
Méliès	AI visual production — portraits, scenes, covers, prompt engineering
Montesquieu	Legal counsel (EU law) — GDPR, terms of service, digital law
Montessori	Pedagogy — learning modules, glossary, learner pathways
Nightingale	Customer success — drafting client communications, no direct sending
Ogilvy	Copywriting — persuasive tone, message clarity, CTAs, cross-channel consistency
Pacioli	FinOps — AI cost tracking, infrastructure, services, financial reconciliation
Pulitzer	Content & SEO blog — articles, covers, internal linking
Renoir	Scheduling supervision — automation orchestration, timetables, inter-task quiet periods
Socrate	Dialogue & community — maieutic questioning, FAQ, clarification of assumptions
Winnicott	Operational balance — overload detection, pace adjustments

Design invariants

• Nightingale holds no system execution capability: it operates in strict read-only mode, ensuring the system never communicates directly with a client without human validation.
• All advisory agents (previous section) operate in read-only mode: zero execution, zero write access.
• Atlas enforces the workstream doctrine: for any significant scope, at least two distinct agents are engaged, and delegation passes through the internal delegation mechanism — never via direct call.
• Residual drift may occur between the managed zone of an agent file and the actual data in the database if a manual synchronization has taken place. The source of truth remains the physical agents table at all times; the refresh-persona and audit-personas tools allow any discrepancy to be corrected.

4. Hooks

4.1 Event Map

The harness intercepts the agent lifecycle at six key points. Each interception can be blocking (the agent does not proceed) or non-blocking (warning only). The following table summarises the complete map:

Interception point	Targeted tool	Triggered mechanisms
Session start	(local)	Context reset, brief generation, scar injection
User prompt submission	versioned + local	DB schema synchronisation, mailbox synchronisation (Nightingale agent)
Pre-use — Read	versioned	Antivirus check on attachments (fail-closed)
Pre-use — Shell command	versioned + local	8 shell nudges and guards, 3 Python guardrails
Pre-use — Agent	versioned + local	Agent reactor, scar injection
Pre-use — Skill	versioned	Lightweight view suggestion when a skill card is large
Pre-use — Edit/Write	versioned	Decentralised reflex engine (deny/warn/allow decision, audit trail)
Pre-use — Edit/Write	local	Scar injection
Post-use — Shell command	versioned	Reaction log, post-commit preprod deployment
Post-use — Agent	versioned	Reactor, reaction log, telemetry
Post-use — Multiple edits	versioned	Tracking of files edited during the session
Post-use — All tools	versioned	CLI cockpit event (best-effort, non-blocking)
Post-use — All tools	local	Token / context counting
Session end (Stop)	versioned	Cockpit end-of-turn signal → worksite lock release → scar reminder → commit check → worksite synchronisation

4.2 Session Start

Three operations run at the opening of each session, each with a 5-second timeout:

1. Context counter reset — the context tracking module resets to zero for the current session.
2. Brief generation — the report generator reads a pre-computed report (produced each night around 05:00 UTC by a scheduled task of the daily audit type) and enriches it in real time: git status, crontab, pending client emails, backlog, scars. The result is injected into the startup context. No npm dependency is required; database reads are performed via the mother-ship's containerised database engine.
3. Scar injection — scars relevant to the session are injected into the initial context.

Configuration note: the session-start hook is not present in the shared versioned configuration file — it lives solely in the local (unversioned) configuration file. This separation is intentional: the startup operations access local resources (database, inbox) that are only available on the mother-ship.

4.3 User Prompt Submission

• Versioned file: database schema dump synchronisation on every prompt — the agent always has a fresh view of the table structure.
• Local file: mailbox synchronisation (Nightingale agent, 15 s timeout) — on every prompt, newly received emails are pulled into the inbox tracking table. This mechanism is implemented as a dedicated skill exposed via the application facade; the actual synchronisation script is distinct from the direct-read script.

Corrective history: until mid-2026, this hook pointed to a ghost script that had never been migrated, causing it to fail silently. The fix also updated the email guardrail whitelist, which was referencing the same obsolete script.

4.4 Pre-use (PreToolUse)

Antivirus guard — Read tool (blocking, versioned)

Any attempt to read an attachment from the temporary quarantine area is blocked if a clean antivirus verdict marker is not present for that file. This reflex is fail-closed: in the absence of the marker, access is denied. It has no dependency on the database — it evaluates solely on the presence or absence of the verdict file.

Shell guards — Command tool (versioned)

Eight scripts run in sequence before any shell command is executed:

Guard	Behaviour
Attachment antivirus check	Same fail-closed logic as for the Read tool: blocks shell commands that would open an unscanned attachment.
Production deployment command block (./ship)	Blocking — the agent can never trigger a public production deployment on its own. Trunk reflex, zero runtime dependency.
Database mutation check	Blocks any destructive mutation on internal system tables if no aligned code commit has occurred within the last five minutes. Embodies the "code before database" doctrine.
Pre-deployment auto-commit	Automatically performs a commit before a ./deploy execution.
Worksite skeleton nudge	Warns if a raw SQL insert on a worksite is attempted instead of using the dedicated skeleton-based creation command.
Pre-commit leak scan	Scans files about to be committed to detect potential leaks (secrets, sensitive data) before they enter the git history. Timeout: 10 s.
Existing worksites reminder	Non-blocking (30 s timeout) — when a new worksite is created, performs a hybrid recall (lexical + semantic search) and injects the four closest worksites or doctrines. Prevents reinventing existing work.
Documentation binding nudge	Warning only (never blocking) — at git commit time, cross-references modified files with the binding contracts of documentation chapters. If a file bound to a chapter is touched, reminds to verify that the chapter is still accurate.

Maintainer note: a back-office authentication control script exists in the repository but is not referenced in any active configuration file — it is dormant and has no effect.

Python guardrails — Command tool (local)

Three additional blocking guardrails run from the local configuration:

Guardrail	Behaviour
Client production environment protection	Blocks any shell command targeting a client production environment with a destructive write pattern (TRUNCATE, DROP, DELETE, ALTER, UPDATE, direct pipe import). Three layers of false-positive mitigation: (1) commands targeting the mother-ship itself are short-circuited before the client test; (2) commands targeting client preprod pass without check; (3) non-destructive queries (SELECT, SHOW, simple INSERT) are not targeted — only nine families of dangerous operations are actually blocked. Authorised write commands must go through the dedicated secured script.
Email facade protection	Blocks any bypass of the official email sending facade. Direct use of low-level SMTP/IMAP libraries or unofficial sending aliases is forbidden. Only the send, inbox sync, direct read, and specialised mailbox scripts listed in the whitelist are permitted — each accepted with or without a relative path. The ghost script that was never migrated was removed from the whitelist during the mid-2026 fix.
Contextual scar injection	Injects scars related to the command currently being evaluated. Timeout: 3 s.

Email facade evolution (mid-2026): the facade automatically sends a validation copy to the human operator for each draft created (show-before-send mechanism applied in practice, not merely declarative). The actual send automatically appends the canonical HTML signature. A Markdown-to-email-safe HTML conversion mode is available. At draft time, the writing tone appropriate for the recipient is displayed (best-effort, non-blocking). A mode to resend a validation copy on an existing draft is also available, without recreating the draft.

Reflex engine — Edit/Write tool (versioned)

Before any file edit, the decentralised reflex engine comes into play. It reads the incoming hook event, loads the active rules from the system reflex table, evaluates a decision (deny, warn, or allow), and traces the event to the reflex audit table. Targeted fail-closed handling:

• If the primary database is unreachable: blocking applies only to sensitive code areas (the core of the main product); outside the sensitive area, control is left to the agent.
• If a Python error occurs within the engine itself: switches to allow with a trace to standard error — a bug in the guard never blocks work.

In parallel, the scar injection script (local configuration) runs cumulatively for the same edit event.

Agent and Skills

• Agent tool: the agent reactor (versioned) and the agent scar injection script (local) run before any agent sub-call.
• Skill tool: a non-blocking hook (5 s timeout, guaranteed exit 0) suggests using the lightweight view of a skill card when it exceeds a configured size threshold.

4.5 Post-use (PostToolUse)

• Shell command: two hooks run in sequence.
  1. The reaction log records the command result.
  2. The automatic post-commit preprod deployment analyses the paths touched and determines the impacted site. Important nuance: for client sites, this is a preprod deployment; for the mother-ship itself, no preprod exists — ./deploy triggers a live rebuild. The hook skips deployment if the commit message contains an exclusion directive ([skip-deploy] / [no-deploy] / wip: prefix), if the commit touches only documentation with no runtime file, or if the working directory is dirty after the commit.
• Agent: reactor, reaction log, telemetry (5 s timeout).
• Multiple edits: the session-edited file tracker (3 s timeout) maintains the list of modified files, subsequently used by the session-end hook.
• All tools: the CLI cockpit activity mirror (10 s timeout) emits an event to the active worksite tracking dial. It activates only if an active worksite is registered; if the disable environment variable is set or no worksite is linked, it exits immediately at no cost. Non-blocking: a missed event never blocks the tool call.
• All tools (local): the context token counter (5 s timeout) updates the session consumption metrics.

4.6 Session End (Stop)

Five operations run sequentially at the close of each session:

1. End-of-turn cockpit signal (9 s timeout) — emits an end-of-turn fragment into the worksite tracking dial timeline, only if the feature is enabled and a worksite is linked.
2. Worksite lock release (3 s timeout) — releases the session lock on the current worksite.
3. Scar reminder — triggered only if the last user message contains a closing keyword ("closing", "end of session", "wrapping up"…). When triggered, lists corrective commits since the last preprod push via standard error, and returns a blocking exit code.
4. Commit check (5 s timeout, blocking) — refuses closure if files modified during this session are uncommitted. Forces a streaming commit. Key mechanics:
   • Session-aware: only files from the current session are checked — multiple parallel Claude sessions do not block each other.
   • Anti-loop: if the hook detects it is already on a second pass, it switches to a non-blocking warning instead of a hard block.
   • Worker short-circuit: if the session is a sub-agent spawned by the automated task engine, the hook exits silently — the worker manages its own commit cycle.
   • The session configuration file itself is excluded from the check.
5. Worksite synchronisation (8 s timeout) — synchronisation reminder between the local worksite state and the hub database.

4.7 Worker Context Convention

A shared utility module, sourced by the four session-end hooks, implements a systematic early exit when the session is a sub-agent spawned by the automated task engine. This convention guarantees that a sub-agent:

• does not trigger closing scar reminders,
• does not release locks that belong to the parent session,
• is not blocked by the commit check (it manages its own cycle),
• does not pollute the main user session's worksite synchronisation.

The worker context environment variable is injected by the task engine's spawn module at sub-agent creation time. This separation is a general rule: what belongs to the user session does not apply to automated agents, and vice versa.

Permissions and Execution Environment

Main Configuration

The agent's main configuration file defines two key parameters:

• An env block enabling experimental engine variables (agent teams, flicker-free rendering).
• A permissions block with defaultMode: auto — the agent runs without requesting confirmation at each step, which is consistent with the autonomy policy enforced by the ./deploy command.

Local Configuration and Data Access Policy

A second configuration file, specific to the host machine and excluded from the versioned repository, refines the authorization policy:

• The allowlist includes several hundred pre-approved tools and commands; no explicit denylist is defined at this level.
• Local environment variables are deliberately empty: no secrets are injected through this channel.
• A natural-language policy block specifies database access rules per environment:
  • Read-only access authorized on a given client's staging environment.
  • Production writes subject to explicit confirmation for each operation — the rule cannot be bypassed through context accumulation.
  • An explicit reminder distinguishes the two VPS instances involved (production and staging) to prevent any confusion during operations.

This declarative policy is backed by an executable safeguard (described in section 4): the rule is therefore enforced at two independent levels — the configuration and the verification hook — constituting a defense-in-depth approach.

Secret Leak Prevention

No secret appears in plaintext in hooks, skills, or agent definitions. Messaging credentials (inbound and outbound), database passwords, and API keys are referenced solely by their variable name in a local environment file excluded from version control. Their values are never written to any file tracked by the repository.

Two complementary monitoring mechanisms ensure leak detection:

• A pre-commit hook scans transcripts before any commit to detect any sensitive value that may have been captured in the session history.
• A dedicated attachment analysis skill detects potentially malicious content before processing.

Data Model — Flow Overview

The following table summarizes the main functional domains of the data model, indicating for each which component produces the data and which component consumes it.

Functional Domain	Producer	Consumer
Agent registry (base table + read view)	Manual editing or persona refresh skill	Agent definition file regeneration script (reads the read view)
Worksites and associated tasks	Worksite skill, worksite business entity	Worksite synchronization and locking hooks
Scars (memorized events)	Victory skill, stop hook	Recall skill, injection at session startup and before each tool
Daily audit reports	Scheduled audit task	Session briefing script (injected at startup)
Skill index (size in bytes)	Automatic skill indexing	Skill pre-invocation hook
Persona drift history	Persona audit	Manual drift review
Ideas / brainstorm	Idea submission skill	Hub brainstorm dashboard
Email inbox	Inbound mail facade	Inbox read skill
Bank transactions	Automated bank import	Banking consultation skill

Architectural note: the agent registry relies on a single base table exposed through a read view. The regeneration script reads the view; the persona refresh skill writes directly to the base table. There are no two diverging tables: consistency is guaranteed and no migration is required.