Skills, agents & hooks — Synedre OS agentic harness

Agentic Harness Overview

The Synedre OS agentic harness is organised around three complementary pillars: skills (invocable behaviour directories), sub-agents (delegating entities) and event hooks (guardrails and nudges triggered automatically). These three pillars are configured in a central settings directory, via two distinct files.

         ┌──────────────── Configuration Directory ────────────────┐
         │                                                          │
user     │  versioned settings (git)  +  local settings (uncommitted)│
/ Atlas  │    └── hooks PreToolUse / PostToolUse / Stop / UserPrompt│
         │                                                          │
         │  skills/       ──▶ invoked via the skills engine         │
         │  sub-agents/   ──▶ delegated via the agent engine        │
         └──────────────────────────────────────────────────────────┘
                        │                        │
                        ▼                        ▼
             guardrail scripts           business facades + memory injection
             (shell hooks)               (Python / JS modules)

Two settings files coexist and are cumulative: for a given event (for example PreToolUse on a Bash tool), commands from both files execute in order. This separation allows generic nudges to be versioned while keeping sensitive guardrails out of the repository.

File	Git-versioned	Contents
Versioned settings	Yes	Hooks PreToolUse / PostToolUse / Stop / UserPromptSubmit, environment variables, default permission mode
Local settings	No	Extended list of allowed permissions, hooks SessionStart / UserPromptSubmit / PreToolUse / PostToolUse, automatic mode

Skills Catalogue

Each skill is a self-contained directory holding a markdown description sheet — with or without frontmatter. A sub-directory groups skills internal to the engine, not intended for manual invocation. Skills are organised by functional domain.

Audit and System Health

Skill	Role
General audit	Full healthcheck of a public site: infrastructure, pages, SEO, performance, security, database — score out of 100.
Anti-rot whitelist	Verifies that every path and section of the immutable P0 whitelist still exists in the repository.
i18n & slugs audit	FR ↔ EN translation key parity, correct English URL slugs, consistency of the localised map. Must be run before any deployment touching pages or routing.
Lexical audit	Detects drift from the canonical lexical register: missing or misaligned entries in the database, divergent enums in the code, forbidden synonyms in schemas. Strict dry-run mode; returns 0 if healthy, 1 if drift detected.
Personas audit	Detects discrepancies between documented personas and the actual stack; records a historical snapshot.
System state	Full check of the current system state.
Context state	Report on the state of the current session context.

Infrastructure and Hosts

Skill	Role
Infra audit	Availability, load, services, SSL 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 for a host.
System update	Non-interactive APT upgrade of a host with containerisation daemon freeze.
Bot analysis	Analyses the application server's robot hit log.
Search Console	Queries the Google Search Console API via the dedicated facade.

Project Management

Skill	Role
Project	Manages projects according to the "1 project = N tasks" doctrine; reads and writes to the dedicated tables; supports creating a project skeleton from the command line.
Run	Opens a scoped run — a lightweight unit symmetrical to the project. Loads the scope (mothership / tenant / negotiation) from the database and returns the current line. Distinct from the native application launcher.
Negotiation	Loads the full context of a commercial negotiation: file, qualification, team, journal, deliverables. Symmetrical to the project for the lead → deal pipeline.
Idea	Creates a brainstorm entry in the dedicated table.
Review	Place des Armes review — each agent presents itself and reports in.
Post-project lesson	Generates a Montessori lesson after a project via the Academy agent; produces a draft in the Obsidian Vault.

Email and Inbox

Skill	Role
Inbox (facade)	Reads and searches emails in the reception table via the Nuxt facade.
Direct inbox	Direct IMAP fallback, read-only — does not write to the database.
Inbox search	Ergonomic IMAP wrapper: retrieves messages, exports to .eml, lists attachments without extracting them (scan-first approach).
Attachment scan	Antivirus analysis of an attachment before opening, via the dedicated facade (Mitnick agent).
Commercial proposal QA	Quality control of a commercial proposal before sending, via a pool of four agents.

Memory and Knowledge

Skill	Role
Semantic recall	RAG vector search over documentary memory and the scars, doctrine and projects tables (Mistral embeddings, 1024 dimensions, cosine similarity).
Zettel	Splits a monolithic document into atomic notes for the Obsidian Vault.
Dictionary	Adds terms to the canonical technical dictionary.
Victory	Records a victory in the scars table with type victory.
Persona refresh	Refreshes an agent's profile via Mistral, three-way diff and review, then updates the agents table.

Finance and Business

Skill	Role
Banking	Queries accounts and transactions via the banking facade.
Transaction import	Manual import of transactions from an external CSV export into the banking transactions table.
Invoicing	Creates, lists, generates as PDF and sends invoices and quotes via the invoicing facade; manages recurring subscriptions. The canonical issuing entity is defined by the tax doctrine — never another entity without an explicit order.
Platform prospects	Retrieves prospect conversations from the configured freelance platform.

Publishing and SEO

Skill	Role
Article publishing	Publishes a blog article to the configured public site.
Scars publishing	Full pipeline: curation → sanitisation → adversarial review (Mitnick agent) → publication of public scars on synedre.com. Selection from the scars table, database write, deployment and live leak scan. Publishes only the trophy scar (the lesson) — never the tutorial scar (exploitable reproduction).
SEO sentinel	Multi-tenant technical SEO monitoring: early detection of ranking losses, triggers the automaton and produces a reformulated report.

Documentation and QA

Skill	Role
Technical doc	Generates or refreshes technical documentation via multi-agent orchestration (writing → verification → correction). Supports a refresh mode (stale pages only) and a no-summary mode. Never commits without explicit validation.
Visual QA	Captures a screenshot via Playwright and submits it to a multimodal sub-agent to verify that the visual intent is actually rendered — beyond mere code execution success.
Site clone	Generates the "server access and information" intake protocol for reproducing a client's existing site on a VPS and drafts the client access request email.

The catalogue above reflects the forty active skills at the time of writing. The engine also exposes internal skills (automatic skill creation, automatic task reaction) not intended for manual invocation.

Database Sources of Truth

Skills do not store business data: they query and write to the relational database via dedicated facades. The main mappings are as follows:

• Projects and tasks → project and associated task tables
• Semantic recall → scars, doctrine, projects tables
• Victories → scars table (type victory)
• Brainstorm / ideas → brainstorm table
• Personas history → persona drift history table
• Agents → agents table
• Emails → email reception table
• Banking transactions → banking transactions table

A pre-invocation hook queries the database size of each skill to decide whether to propose lazy-loading (three-level lazy-load), in order to preserve the context window during long sessions.

Delegable Sub-Agents

The system relies on approximately thirty specialized agent profiles, each defined by a dedicated configuration file. These files are partially generated from the database: a regeneration script reads the agents view (itself built on the agents base table) and updates a zone delimited by markers in each file. The remaining editorial zone — doctrine, operating mode — is written manually and preserved between each regeneration. The automatically managed zone must therefore never be modified manually.

Architecture note: The agents view is read-only. The underlying base table is the physical source of truth: the persona update script writes directly to it, while the agent file regeneration script reads through the view. Both are consistent — there is no divergence or risk associated with a dual-table setup.

Each agent profile exposes three key metadata fields: a name, a description (selection criterion for automatic delegation), and the list of tools it has access to. All agents run on the same language model tier.

Executing Agents

These agents have both read and write access, as well as the ability to execute system commands. They are the operational arms of the system.

Public codename	Role	Tool scope
Brunel	DevOps / Infrastructure — containerization, reverse proxy, SSL, DNS, server management	Read, write, execute, search
Turing	Backend engineering — application server, business modules, database integrity	Read, write, execute, search
Eames	Frontend — Vue 3 interfaces, design system, control hub pages	Read, write, execute, search
Otlet	Technical SEO — structured markup, sitemap, Core Web Vitals, redirects, AI indexability	Read, write, execute, search
Lovelace	QA — last checkpoint before production, acceptance testing, regression detection	Read and search only — no write access
Mitnick	Offensive and defensive security — attachment analysis, secret detection, OWASP compliance	Read and search only — no write access

Note: Lovelace and Mitnick hold no modification rights. Their roles are control-oriented, not mutation-oriented — this is a deliberate constraint, not an omission.

Advisory and Knowledge Agents

These agents have access to read only. They produce analyses, drafts, and recommendations, but never execute any direct action on the system. None of them has Bash access or write access.

Public codename	Role
Atlas	Architect and project lead — partitions work, dispatches to specialized agents, orchestrates workstreams
Audiard	Audio author — rewriting for the ear (rhythm, orality, breath)
Bernays	Commercial growth — pipeline, leads, conversion funnels
Bernhardt	Audio quality control — scoring (blocking threshold 9.5/10), diction, fidelity to source text
Braille	Accessibility — WCAG 2.2 AA compliance (keyboard navigation, contrast ratios, ARIA)
Clausewitz	Strategy — consistency of product decisions with respect to positioning
Coco	Brand guardian — tonal refinement, cross-channel visual consistency
Colbert	General management — workstream prioritization, resource allocation, steering
Dumas	Narrative — 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 and AI-assisted manga/manhwa illustration
Itten	Art direction — color palette, typography, design tokens
Marco Polo	Monitoring — technology, competitive, and market intelligence
Méliès	AI visual production — portraits, scenes, covers, prompt engineering
Montesquieu	Legal counsel (EU law) — GDPR, terms of service, digital law
Montessori	Pedagogy — training modules, glossary, learner pathways
Nightingale	Customer success — drafting client communications, never direct sending
Ogilvy	Copywriting — persuasive tone, message clarity, CTAs, cross-channel consistency
Pacioli	FinOps — AI costs, infrastructure, services, budget reconciliation
Pulitzer	Content and SEO blog — articles, covers, internal linking
Renoir	Automata supervision — scheduled task orchestration, silence management, time-slot handling
Socrate	Dialogue and community — maieutics, assumption challenging, FAQ, clarity
Winnicott	Operational balance — overload detection, pace adjustments

Structural Guarantees and Delegation Doctrine

• Lovelace and Mitnick are control agents: they read, analyze, and raise alerts, but never modify anything. This constraint is encoded in their configuration.
• Nightingale has no system execution access — the rule that the system never addresses clients directly is thus enforced structurally, not merely doctrinally.
• All advisory agents (previous section) are strictly limited to read access: zero execution, zero write.
• In the event of drift between the automatically managed zone and the editorial zone of an agent file, the agents base table is authoritative. The persona update and audit tools allow the entire set to be resynchronized.

The delegation doctrine requires that Atlas mobilizes a minimum of two distinct agents for any workstream touching a client's scope, and delegates through the orchestration mechanism provided for this purpose. Mitnick's involvement in attachment analysis is treated as a preliminary tooling step — not as a full team recruitment.

4. Hooks

4.1 Event Map

The harness is structured around several anchor points that intercept the lifecycle of each interaction. The following table summarizes, for each event, the mechanism(s) activated:

Event	Scope	Triggered Mechanisms
SessionStart	local	Context reset, session brief, scar injection
UserPromptSubmit	versioned + local	DB schema sync, inbox sync (Nightingale agent)
PreToolUse Read	versioned	Antivirus guard on attachments pending scan
PreToolUse Bash	versioned + local	8 shell nudges and guards, 3 additional safeguards
PreToolUse Agent	versioned + local	Agent reactor, scar injection
PreToolUse Skill	versioned	Pre-invocation (suggests lightweight view if skill card is large)
PreToolUse Edit|Write	versioned + local	Decentralized reflex engine, scar injection
PostToolUse Bash	versioned	Reaction log, post-commit preprod deployment
PostToolUse Agent	versioned	Reactor, reaction log, agent telemetry
PostToolUse Edit|Write|…	versioned	Session edit tracking
PostToolUse (all tools)	versioned	CLI cockpit event (best-effort)
PostToolUse (all tools)	local	Token count / context tracking
Stop	versioned	Cockpit shutdown → lock release → scar → uncommitted warning → worksite sync

4.2 SessionStart (local configuration)

Three commands are executed at each session open, each with a maximum timeout of 5 seconds:

1. Context counter reset — reinitializes context window tracking for the new session.
2. Session brief — reads the pre-computed report produced nightly at 05:00 UTC (type daily_meet) and enriches it in real time: git status, crontab, pending client emails, backlog, recent scars. No npm dependencies.
3. Scar injection — pushes scars deemed relevant for the session into the startup context.

⚠️ The SessionStart hook does not appear in the shared versioned configuration — it lives exclusively in the host machine's local configuration, intentionally kept out of the repository.

4.3 UserPromptSubmit

• Versioned configuration: synchronization of the database schema dump to a reference file consulted by the agent.
• Local configuration: IMAP inbox synchronization (Nightingale agent, maximum timeout 15 s) — incoming emails are ingested into the messaging table on each new prompt.
  Maintenance note (corrected): a legacy ghost script — never migrated — was incorrectly referenced in this configuration; it was failing silently. The dead reference has been replaced with the correct synchronization script, and the same stale pointer had been copied into the email guard whitelist (also corrected).

4.4 PreToolUse

Matcher Read — antivirus guard (blocking)

Mechanism	Effect
Attachment read guard	BLOCKING (exit 2): prevents any read of an attachment pending scan until a clean antivirus verdict (validated SHA-256 fingerprint) exists. Fail-closed reflex, zero database dependencies.

Matcher Bash — nudges and guards (versioned configuration)

Mechanism	Effect
Antivirus guard (Bash commands)	Same logic as for Read: also blocks shell commands that attempt to open an unscanned attachment.
Deployment blocking to unauthorized targets	BLOCKING (exit 2): consults the client environment configuration table (auto_ship_allowed) and blocks the ./ship command for targets whose field is false or unknown (fail-closed). Authorized targets pass through freely. TRUNK reflex, zero runtime dependencies.
Database mutation guard	Blocks any configuration data mutation (UPDATE/INSERT/ALTER) without an aligned code commit within the last 5 minutes — enforces the "code before database" principle.
Auto-commit before deployment	Triggers an automatic commit before any ./deploy execution.
Worksite skeleton nudge	Warns if a worksite is created via a raw SQL INSERT instead of the create_with_skeleton command.
Pre-commit leak scan	Analyzes commit content (maximum timeout 10 s) to detect potential sensitive data leaks.
Existing worksite recall	Non-blocking (maximum timeout 30 s): at worksite creation time, performs a hybrid recall (lexical + semantic, RRF fusion) on the title and injects the 4 closest results via stderr — prevents recreating an already existing worksite or doctrine.
Documentation link nudge	Warning only (always exit 0): at git commit time, cross-references staged files against documentation chapter link contracts. If a file under contract is modified, reminds to verify that the corresponding chapter is still accurate.

ℹ️ An additional guard script exists in the repository but is not referenced in any active configuration — it is dormant. The 8 mechanisms above are the only ones actually wired into PreToolUse Bash.

Matcher Bash — additional safeguards (local configuration, blocking)

Mechanism	Effect
Production write guard	BLOCKING: detects shell commands targeting a client production environment with a destructive write pattern (TRUNCATE, DROP TABLE, DROP DATABASE, DELETE FROM, ALTER TABLE, RENAME TABLE, UPDATE … SET, and direct SQL client invocation forms) and requires routing through the dedicated secure deployment script. Anti-false-positive (3 layers): (1) commands targeting the mothership itself are short-circuited before the production test — avoids false positives if a client name appears in a text note; (2) commands targeting preprod pass without check; (3) non-destructive queries (SELECT, SHOW, standard INSERT) are not targeted — only the 9 destructive patterns are blocking.
Email facade guard	BLOCKING: prevents any direct use of low-level email sending or reading libraries (SMTP, IMAP, MIME composition) outside of officially whitelisted scripts. The whitelist covers the send script, the IMAP sync script, the direct read script, and the secondary mailbox script. The legacy ghost script (never migrated) has been removed from this whitelist.
Scar injection (local Bash)	Non-blocking (maximum timeout 3 s): injects scars associated with the command currently being executed.

ℹ️ Email facade update (2026-06-08): the official send script automatically sends a validation copy to the administrator on each draft (--draft), effectively enforcing the "show before send" policy. The --send mode automatically appends the canonical HTML signature before SMTP delivery. The --markdown mode converts the Markdown body to email-compatible HTML. At draft composition time, the expected tone for the recipient is displayed (best-effort, non-blocking). A new --validate --draft-id <N> mode allows resending the validation copy of an existing draft without creating a new one.

Matcher Edit|Write — reflex engine (versioned configuration)

Mechanism

Effect

Decentralized reflex engine

Reads the incoming hook event, loads active rules from the reflex table, makes a decision (deny / warn / allow), and writes the audit trace. Targeted fail-closed handling: if the primary database is unreachable, blocks only sensitive areas of the application core; outside sensitive areas, allows through. A bug in the engine itself produces an exit 0 with an error message — it never blocks work in the event of a facade failure.

Matcher Edit|Write — local configuration

Mechanism	Effect
Scar injection (local edit)	Same script as for local Bash: injects scars linked to the file currently being edited.

ℹ️ For a given Edit|Write event, both hooks run cumulatively: the reflex engine (versioned, decisions from the database) then scar injection (local).

Matcher Agent: agent reactor (versioned) + agent-specific scar injection (local).

Matcher Skill: non-blocking pre-invocation (maximum timeout 5 s, always exit 0) — suggests the lightweight view of the skill card if its size exceeds a configured threshold.

4.5 PostToolUse (versioned configuration unless noted)

• Bash: reaction log + post-commit preprod deployment (maximum timeout 10 s). The hook maps modified paths to the impacted site and triggers an automatic deployment after each commit. Important nuance: for tenants, this is a deployment to preprod; for the mothership itself, no preprod environment exists — ./deploy rebuilds the live site directly. The term "preprod" in the hook name is therefore misleading for this case. Skips: deployment is skipped if the commit message contains [skip-deploy] or [no-deploy], if it starts with wip:, if the commit touches only documentation (no runtime files), or if the working directory is dirty after the commit.
• Agent: agent reactor + reaction log + agent telemetry (maximum timeout 5 s).
• Edit|Write|MultiEdit|NotebookEdit: session edit tracking (maximum timeout 3 s) — writes the list of modified files, basis for the session-aware Stop hook.
• All tools (Bash, Read, Write, Edit, MultiEdit, NotebookEdit, Glob, Grep, Skill, Agent, Task): CLI cockpit event (maximum timeout 10 s) — reflects session activity to the active worksite dashboard. Conditional no-op: if the CLI cockpit is disabled or no active worksite is detected, exits immediately at no cost. Non-blocking: exit 0 guaranteed even on database failure — a missed event must never block a tool call.
• All tools (local configuration): token count and context window tracking (maximum timeout 5 s).

4.6 Stop (versioned configuration) — execution order

At the end of each session, five mechanisms execute in the following order:

1. Cockpit end signal (maximum timeout 9 s) — no-op by default; if beat mode is active and a worksite is linked, emits an end-of-turn fragment in the cockpit timeline.
2. Worksite lock release (maximum timeout 3 s) — releases the exclusive lock held by the session on the active worksite.
3. Scar reminder — triggered only if the last user message contains a closing keyword ("closing", "end of session", "wrapping up"…); lists fix commits since origin via stderr and exits with exit 2.
4. Uncommitted warning (maximum timeout 5 s) — BLOCKING: refuses session close if files modified during this session are not committed, forcing an inline commit.
5. Worksite sync (maximum timeout 8 s) — triggers synchronization between the local worksite state and the hub database.

Key mechanics of the uncommitted guard

• Session-aware: filters git status against the list of files modified by this session — multiple parallel Claude sessions do not block each other.
• Anti-loop: if the hook is already active (second pass), switches to a non-blocking warning instead of a hard block.
• Early exit for workers: if the session is a sub-agent spawned by the task engine, the hook exits silently without blocking — the worker manages its own commit cycle.
• Local configuration file exclusion — the hook may have modified it itself; it is not included in the check.

4.7 Worker Context Convention

A shared shell library, unique under the utility scripts directory, is sourced by all four Stop hooks. It implements a uniform rule: if the SY_WORKER_CONTEXT environment variable indicates that the session is a sub-agent spawned by the task engine, the user session hooks (inline commit, closing scars, worksite lock, synchronization) exit immediately without action.

General rule: a sub-claude spawned by the worker does not trigger user session hooks. The worker manages its own lifecycle autonomously.

Permissions & execution environment

Main configuration

The main configuration file defines two structural parameters:

• An env block that enables or disables experimental agent features (team mode, flicker-free rendering).
• A permissions block with defaultMode: auto: the agent runs without confirmation prompts by default, consistent with the autonomy doctrine of AI-driven deployments.

Local configuration and access policy

A second configuration file, local and unversioned, refines the authorization policy:

• Allow list: several hundred tools and commands are pre-approved, with no explicit deny list.
• Environment variables: no sensitive values are declared at this level; the block is empty.
• Declarative access policy: a structured natural-language block describes the rules applied to a reference client's environments:
  • Allowed: read-only access to the relevant client's staging database.
  • Soft deny: any write operation on the same client's production environment requires explicit confirmation for each operation.
  • Context reminder: the client's two VPS instances (production and staging) are clearly distinguished to prevent any confusion.

This declarative policy is backed by an executable safeguard (see the section on production write protection): the rule expressed in configuration and the blocking hook together form a defense-in-depth strategy.

Secret leak protection

No secret appears in plain text in hooks, skills, or agents. Messaging credentials (inbound and outbound access) are referenced solely by their variable name in a local environment file excluded from version control. Two complementary mechanisms ensure detection:

• A pre-commit hook that inspects transcripts before any recording.
• An attachment scanning skill that also filters incoming malicious content.

Data model — overview of persistent components

The table below summarizes the system's main storage components, indicating for each one which mechanism produces it and which mechanism consumes it.

The technical names of tables and schemas are internal identifiers. Only functional roles are described here.

Component (functional role)	Producer	Consumer
Agent registry — base table + read view	Manual editing or persona refresh skill	Agent card regeneration script → agent configuration files
Project and task registry	Project management skill, associated business entity	Project synchronization and locking hooks
Scar log	Victory skill, closure hook	Recall skill, injection at session start and before each tool
Daily audit reports	Scheduled audit task	Session briefing script (loaded at startup)
Skill index (size in bytes)	Skill indexing process	Skill pre-invocation hook
Persona drift history	Persona audit skill	Manual drift review
Brainstorming space	Ideation skill	Hub brainstorming panel
Inbound message queue	Email reception facade	Inbox management skill
Bank transaction log	Bank statement importer	Financial tracking skill

Architecture note: the agent registry relies on two distinct database objects — a base table (authoritative source, editable) and a read-only view built on that table. The regeneration script reads from the view; the refresh skill writes to the table. These two objects are fully consistent and carry no risk of divergence: there are no two competing tables.