Skills, agents and hooks of the Synedre OS harness

Skills, agents & hooks — the agentic harness

This section describes how the Synedre OS agentic harness is wired: the skills (invocable capabilities), the delegatable sub-agents, and the event hooks that enforce doctrine (streaming commits, production guardrails, memory injection). It is aimed at the engineer taking over the harness who needs to understand what triggers when, and what the source of truth is.

1. Overview

The harness is organized around a central configuration folder. Two settings files coexist:

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

Both sets of hooks are cumulative: for a given event (e.g. PreToolUse on the Bash tool), the commands from both files are executed. This is why Python-driven guardrails live in the local file, and shell nudges in the versioned file.

The general flow is as follows:

• The user or the Atlas orchestrator submits a request.
• The configuration hooks intercept each tool call before and after execution.
• The skills are named capabilities, each described by a definition file; they are invoked via the Skill tool.
• The sub-agents are specialized agents (Mitnick, Turing, Brunel, etc.) delegated via the Agent tool.
• The hook scripts enforce guardrails and nudges; the application facades handle memory injection and business calls.

2. Available skills

Each skill is defined by a description file (markdown, with or without frontmatter). A subdirectory groups internal engine skills not intended for manual invocation.

2.1 Catalogue by category

Category	Skill	Role
Audit / health	Immutable floor guardrail	Verifies that every path and section of the immutable P0 whitelist still exists. Anti-rot.
	i18n & slugs audit	SEO i18n audit and localized slugs for synedre.com — EN↔FR key parity, English URL slugs, localized map consistency. To be run before any deployment touching pages, i18n, or routing.
	Canonical lexicon audit	Anti-drift audit of the lexical register: detects missing or misaligned entries, divergent enums in code, forbidden synonyms in schemas. Strict dry-run; exit 0 = healthy, exit 1 = drift.
	Persona drift	Detects agent persona drift relative to the current stack. Correction mode refreshes via the AI provider and produces a three-way diff.
	System status	Full system health check. The site mode performs a comprehensive audit of a public site (pages, SEO, performance, security, database) and produces a score out of 100.
	Context status	Returns the context state of the current session.
Infra / hosts	Host audit	Single entry point for host audits, four facets: availability / load / services / SSL; security hardening; backup freshness and integrity; system updates. Without a specified facet, the three main audits run.
	Bot analysis	Analyzes the automated request log to identify bots and their behavior.
	GSC opportunities	Queries the Google Search Console API to extract SEO opportunities.
Project / steering	Project steering	Steering of projects according to the "1 project = N tasks" doctrine. Supports project skeleton creation via the dedicated facade.
	Scoped run	Opens a scoped run — a lightweight unit symmetric to the project. Loads the scope (mother-ship / tenant / negotiation) from the database and returns the current line. Distinct from the native application launcher.
	Commercial negotiation	Loads the full context of a negotiation — file, qualification, team, journal, deliverables. Symmetric to the project for the lead → deal pipeline.
	Brainstorm idea	Creates an idea in the brainstorm register.
Review / training	Place des Armes review	Each agent presents itself and reports its status.
	Post-project lesson	Generates a structured lesson at the end of a project and deposits it as a draft in the Obsidian Vault.
Email / inbox	Inbox read via facade	Reads and searches emails in the inbox register via the Nuxt facade.
	Direct inbox read	Direct read-only IMAP fallback. Does not write to the database.
	Ergonomic inbox search	Ergonomic IMAP wrapper — retrieves emails and their attachments, lists attachments without extracting them (scan-first approach).
	Attachment antivirus scan	Antivirus scan of an attachment before opening, via the dedicated facade (Mitnick agent).
Email QA	Commercial proposal verification	Quality control of a commercial email proposal before sending, orchestrated across a pool of four agents.
Memory / knowledge	Semantic recall	RAG recall by vector similarity over memory, the Vault, and the scar, doctrine, and project registers. Cosine embeddings, 1024 dimensions.
	Zettelkasten atomization	Splits a monolithic document into atomic notes for the Obsidian Vault.
	Technical dictionary	Adds terms to the technical dictionary.
	Victory engraving	Engraves a victory in the scar register.
Finance / business	Bank consultation	Consults accounts and transactions via the banking facade.
	Transaction import	Manual import of N26 transactions into the banking register.
	Invoicing	Creates, lists, generates PDFs, and sends invoices and quotes via the invoicing facade, including recurring subscriptions. The canonical issuer is the configured legal entity; a different entity requires an explicit instruction.
Prospecting	Malt conversations	Retrieves prospect conversations from the Malt platform.
Publishing / SEO	Article publishing	Publishes a blog article to the configured public site.
	Scar publishing	Full pipeline: curation → sanitization → adversarial review (Mitnick agent) → publication of public scars on synedre.com. Selection from the register, database write, deployment, and live leak scan. Publishes the trophy scar (lesson) — never the tutorial scar (exploitable reproduction).
	Tenant SEO audit	SEO audit of a client: i18n coverage by language and technical sentinel (HTTP error sweep, GSC health over 28 days, alert / warning / ok verdict). Early detection of a ranking bleed.
Doc / QA	Technical documentation generation	Generates or refreshes technical documentation via multi-agent orchestration (writing → verification → correction). Refresh mode: regenerates only stale pages. Never commits without explicit validation.
	Visual QA	Captures a screenshot via Chromium / Playwright and submits the image to a multimodal sub-agent to verify that the visual intent is actually rendered — not merely that the code ran.
	Client site cloning	Generates the "server access and info" intake protocol to clone a client's existing site onto a VPS, and drafts the access request email via the email facade.

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

2.2 Database-side sources of truth

Skills do not store business data: they query the operational database via the appropriate facades. The main registers involved are:

• Projects and tasks: the project register and the associated task register.
• Semantic recall: the scar, doctrine, and project registers.
• Victories: the scar register, entries of type victory.
• Ideas: the brainstorm register.
• Agent personas: the persona drift history register (audit) and the agent register (correction).
• Inbox: the inbound email register.
• Banking transactions: the banking transaction register.

A pre-invocation hook reads the declared size of each skill in the database to decide whether to suggest deferred loading (three-level lazy-load strategy).

Delegable Sub-Agents

The system includes around thirty specialized sub-agents, each defined by a dedicated configuration file. These files are partially generated from the database: a regeneration script reads the published agent view and rewrites only the automatically managed zone, delimited by start and end markers. The editorial zone (doctrine, operating mode) written manually is preserved between each regeneration. The automatically managed zone must not be modified by hand.

Read/write architecture: the view exposed to the regeneration scripts is read-only; it relies on a base table that constitutes the physical source of truth. The persona audit tool writes to the base table, while the regeneration script reads the view — both components are consistent and there is no risk of divergence between two tables.

Each sub-agent declares in its header: a public name, a description serving as a delegation criterion, the list of authorized tools, and the language model used.

Execution Agents

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

Public Codename	Role	Authorized Tools
Brunel	DevOps / Infrastructure — container management, reverse proxy, SSL certificates, DNS, VPS	Read, write, edit, execute, search
Turing	Backend SRE — application server, database integrity, server-side business modules	Read, write, edit, execute, search
Eames	Frontend — user interface, Vue 3 components, design system, dashboard pages	Read, write, edit, execute, search
Otlet	Technical SEO — structured data, sitemap, Core Web Vitals, redirects, indexability	Read, write, edit, execute, search
Lovelace	QA — last line of defense before production, automated acceptance testing, regression detection	Read and search only (no write access)
Mitnick	Offensive and defensive security — attachment analysis, exposed secret detection, OWASP	Read and search only (no write access)

Important observations:

• Lovelace and Mitnick have no write or edit access: their roles are control and observation, never mutation.
• Mitnick in attachment analysis mode constitutes a preliminary tooling step, not a team recruitment in the sense of the project doctrine.

Advisory and Knowledge Agents

These agents have read-only access. They produce analyses, drafts, and recommendations, without ever executing commands or modifying files. All use the same language model.

Public Codename	Role
Atlas	Architect & Project Manager — orchestrates projects, partitions work, and dispatches to specialized agents
Audiard	Audio author — rewriting for the ear (rhythm, orality, breath)
Bernays	Commercial growth — lead pipeline, conversion funnels, offer positioning
Bernhardt	Audio quality control — scoring with blocking threshold, diction, fidelity to source text
Braille	Accessibility — WCAG 2.2 AA compliance (keyboard navigation, contrast ratios, ARIA attributes)
Clausewitz	Strategy — consistency of product decisions against positioning
Coco	Brand Guardian — tonal refinement, cross-channel visual consistency
Colbert	General management — project 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 manga/manhwa illustration via AI
Itten	Art direction — color palette, typography, design tokens
Marco Polo	Monitoring — technological, 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 — learning modules, glossary, learner pathways
Nightingale	Customer Success — drafting client communications, never direct sending
Ogilvy	Copywriting — persuasive tone, message clarity, cross-channel consistency, CTAs
Pacioli	FinOps — tracking AI, infrastructure, and service costs, reconciliation
Pulitzer	Content Manager — blog articles, covers, SEO internal linking
Renoir	Automation supervision — scheduling, idle windows, execution schedule management
Socrate	Dialogue & Community — maieutics, FAQ, clarification of assumptions
Winnicott	Operational balance — overload detection, work pace adjustments

Absolute rule: Nightingale has no command execution access — it is strictly limited to read access, which is consistent with the principle that the system never addresses clients directly without human validation. Likewise, all advisory agents have exclusively read access: none execute commands, none write files.

Delegation Doctrine

The Atlas agent applies the project doctrine to itself: for any scope involving a client, at least two distinct agents must be engaged. Atlas orchestrates and dispatches via the agent delegation mechanism; it does not carry out execution tasks itself.

A known point of vigilance: the automatically managed zone in configuration files may, for certain agents, exhibit a slight drift relative to the manually written zone. The source of truth always remains the base table — consulted via the persona audit tool, which also allows these drifts to be corrected.

4. Hooks

4.1 Event Map

The hook system intercepts every step of the agent's work cycle. The table below summarises the anchor points, their execution mode and their role:

Event	Mode	Primary role
SessionStart	local	Context reset, session brief injection and scar injection
UserPromptSubmit	json + local	Database schema synchronisation and mailbox check (messaging agent)
PreToolUse Read	json	Antivirus scan on attachments before opening
PreToolUse Bash	json + local	8 shell nudges and guards + 3 Python guardrails
PreToolUse Agent	json + local	Agent reactor + scar injection
PreToolUse Skill	json	Pre-invocation: suggests compact view if the skill is large
PreToolUse Edit|Write	json + local	Decentralised reflex engine + scar injection
PostToolUse Bash	json	Reaction log + pre-prod deployment after commit
PostToolUse Agent	json	Reactor + log + agent telemetry
PostToolUse Edit|Write|…	json	Tracking of files edited during the session
PostToolUse *	json	CLI cockpit event (best-effort)
PostToolUse ""	local	Token / context counting
Stop	json	Cockpit stop → lock release → scar → uncommitted-work warning → worksite sync

4.2 SessionStart

Three commands run at the start of each session, each with a maximum timeout of 5 seconds:

1. Context counter reset — resets the token counter for the current session to zero.
2. Session brief — reads the pre-computed report produced every night at 05:00 UTC (type daily_meet) and enriches it in real time: git status, crontab, received client emails, backlog, scars. No npm dependency; database reads go through the mothership's internal database engine.
3. Scar injection — pushes the scars relevant to the session into the startup context.

⚠️ The SessionStart hook does not appear in the shared versioned configuration — it lives exclusively in the uncommitted local configuration of the host machine.

4.3 UserPromptSubmit

• Versioned configuration: database schema dump synchronisation on every user prompt submission.
• Local configuration: mailbox check (15 s timeout, status message visible in the interface) — synchronises the IMAP inbox into the incoming-mail table on every UserPromptSubmit.

ℹ️ Fix 2026-06-06: the hook previously pointed to an IMAP synchronisation script that had never been migrated — a ghost that failed silently. The inbox is now exposed as a dedicated skill via the web facade; the actual synchronisation is performed by the correct synchronisation script. The same dead reference had been copied into the email guardrail's allowlist — it has been corrected there as well.

4.4 PreToolUse

Antivirus check on file reads (blocking)

A guardrail applies to every read tool (Read): any attempt to open a file from the attachment temporary folder is blocked (exit 2) if the file does not yet carry a valid antivirus scan marker. This survival reflex operates in fail-closed mode, with no database dependency whatsoever.

Shell guards on Bash commands (versioned configuration)

Guardrail	Effect
Antivirus check (Bash)	Same blocking behaviour as for Read: prevents shell commands that would open an unscanned attachment.
Targeted deployment block	Blocking (exit 2) — queries the database to determine whether the target allows direct deployment (./ship). Explicitly authorised targets pass through; unauthorised or unknown targets are blocked (fail-closed).
Misaligned DB mutation detector	Blocks any database mutation (structural or sensitive-data change) without a corresponding code commit in the last 5 minutes — enforces the "code before DB" rule.
Auto-commit before deployment	Performs an automatic commit before ./deploy is executed.
Worksite skeleton nudge	Warns when a worksite is inserted via raw SQL instead of using the skeleton-creation command (create_with_skeleton).
Pre-commit leak scan	Analyses staged content before each commit to detect potential sensitive-data leaks (10 s timeout).
Similar worksite reminder	Non-blocking (30 s timeout): at worksite creation time, runs a hybrid search (lexical + semantic) on the title and injects the 4 closest worksites or doctrines — prevents reinventing existing work.
Documentation link nudge	Warning only (exit 0 guaranteed): at commit time, cross-references staged files against the contracts declared in documentation chapters. If a contracted file is modified, reminds the operator to verify that the chapter remains accurate.

ℹ️ Recovery note: a ninth guardrail script exists on disk but is not referenced in any active configuration — it is dormant. The eight hooks listed above are effectively wired into PreToolUse Bash.

Python guardrails on Bash commands (local configuration, blocking)

Guardrail	Effect
Production database protection	Blocks any shell command targeting a client's production database with a destructive write pattern (TRUNCATE, DROP, DELETE, ALTER, UPDATE, direct import). Requires going through the secure production-promotion script. Three-layer false-positive mitigation: (1) commands targeting the mothership's own internal databases are short-circuited before the client test; (2) commands targeting the client's pre-prod pass without check; (3) non-destructive queries (SELECT, SHOW, standard INSERT…) pass implicitly — only nine destructive expressions are blocking.
Email facade protection	Blocks any bypass of the official sending facade: prevents direct calls to raw SMTP/IMAP libraries and to unofficial send functions. An allowlist of authorised scripts is maintained (sending, IMAP synchronisation, direct read). Fix 2026-06-06: the never-migrated ghost script has been removed from the allowlist.
Scar injection (Bash)	Injects scars related to the current command (3 s timeout).

ℹ️ Email facade evolution — 2026-06-08: in draft mode (--draft), the facade automatically sends a validation copy to the responsible operator before any actual sending — the show-before-send doctrine is enforced in practice. In send mode (--send), the canonical HTML signature is appended automatically. A --markdown mode converts the body to email-compatible HTML. At draft time, the expected tone of writing 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 recreating it.

Reflex engine on file edits (versioned configuration)

For Edit and Write tools, a decentralised reflex engine reads the hook event, loads active rules from the mothership database, makes a decision (deny / warn / allow) and writes the audit trace. Fault handling is targeted fail-closed: if the primary database is unreachable, only sensitive areas (product core) are blocked; outside those areas, the tool is allowed. A bug in the engine itself never blocks work (exit 0 + error message on stderr).

Scar injection on edits (local configuration)

For the same Edit|Write event, both hooks run cumulatively: the reflex engine (versioned configuration) followed by scar injection (local configuration).

Agent and Skills

• Agent: an agent reactor (versioned configuration) runs in parallel with a scar injection specific to sub-agents (local configuration).
• Skill: a non-blocking pre-invocation hook (exit 0 guaranteed, 5 s timeout) suggests the compact view of a skill if its size exceeds a configured threshold.

4.5 PostToolUse

• Bash: post-execution reaction log + automatic pre-prod deployment after a commit (10 s timeout). The hook identifies the impacted site based on the paths touched. Important nuance: for client tenants this is a pre-prod deployment; for the mothership site itself there is no pre-prod — ./deploy rebuilds the site directly in production. The term "pre-prod" in the hook name is therefore misleading for that case. Skip conditions: the hook does not trigger a deployment if the commit message contains [skip-deploy] or [no-deploy], if the commit starts with wip:, if only documentation files were modified, or if the repository is in a modified state after the commit.
• Agent: reactor + reaction log + agent telemetry (5 s timeout).
• Edit / Write / MultiEdit / NotebookEdit: tracking of files edited during the current session (3 s timeout) — feeds the session file consumed by the Stop hook.
• All tools: CLI cockpit event (10 s timeout) — reflects session activity to the active worksite dashboard. Conditional short-circuit: if the disable environment variable is set or if no active worksite is registered, the hook exits immediately at no cost. Non-blocking: exit 0 guaranteed even on database failure.
• All tools (local configuration): token counting and context tracking (5 s timeout).

4.6 Stop — execution order

At the end of each session, five hooks run in the following order:

1. End-of-turn event to the cockpit (9 s timeout) — emits an end-of-turn fragment into the worksite timeline only if the activation variable is set and an active binding exists.
2. Worksite lock release (3 s timeout) — releases the exclusive lock acquired by the session on the current worksite.
3. Scar reminder — triggered only if the user's last message contains a closing keyword ("closing", "end of session", "wrapping up"…). Lists fix-type commits since the last synchronisation.
4. Uncommitted-work warning (5 s timeout, blocking) — refuses to close the session if files edited during this session are still uncommitted, forcing an in-stream commit.
5. Worksite sync (8 s timeout) — prompts synchronisation between the local worksite and the hub database.

Key mechanics of the uncommitted-work guardrail

• Session awareness: filters the git status to only the files edited during the current session — multiple parallel Claude sessions do not block one another.
• Anti-loop: if the Stop hook is already active (second pass), switches to a non-blocking warning instead of blocking the shutdown.
• Early exit for sub-agents: if the session is a sub-agent spawned by the automated task engine, the hook exits silently — the sub-agent manages its own commit cycle.
• Session configuration file exclusion: local configuration files potentially modified by the hook itself are excluded from the check.

4.7 Worker context convention

A single shared library, sourced by all four Stop hooks, provides a worker context detection function. When a sub-agent is spawned by the automated task engine (the corresponding environment variable is set by the spawn script), all interactive-session hooks terminate immediately with no effect: in-stream commit, closing scar reminder, lock release and worksite sync are all disabled.

General rule: a sub-agent spawned by the task engine does not trigger interactive-session hooks.

Permissions & environment

Default permissions configuration

The main configuration file defines two key aspects of the runtime environment:

"env":         { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0", "CLAUDE_CODE_NO_FLICKER": "0" }
"permissions": { "defaultMode": "auto" }

The auto mode means agents run without requesting confirmation at each action. This behaviour is consistent with the autonomous execution doctrine enforced by ./deploy: the AI acts, then reports.

Local permissions configuration

A second local configuration file extends and refines these rules:

• Allowlist: several hundred tools and commands are pre-approved, with no explicit denylist.
• Local environment variables: empty — no local overrides.
• Data access policy: a declarative natural-language block defines the following rules:
  • Authorisation: read-only access to a client's staging environment.
  • Soft restriction: any write to the same client's production environment requires explicit confirmation at each attempt.
  • Contextual reminder: both environments (production and staging) are clearly distinguished to avoid any confusion during interventions.

This declarative policy is backed at the executable level by a dedicated guardrail (described in the section on protection hooks): the rule is both declared and technically enforced.

Secret leak protection

No secret appears in plain text in hooks, skills, or agents. Credentials (messaging access, database passwords, API keys) are referenced solely by their variable name in an environment file excluded from version control. The actual value is never written into versioned code.

Two complementary safety nets enforce this discipline:

• A pre-commit hook that analyses transcripts before any commit, in order to detect any secret leak.
• An attachment-analysis skill that filters potentially malicious content entering the system.

Data model — tables involved

The central hub relies on several tables and views organised by functional domain. The following table summarises the persistence components, their producers, and their consumers.

Functional domain	Producer	Consumer
Agent registry (base table + read view)	Manual editing or persona recalibration command	Agent file regeneration script reading from the read view
Projects and tasks	Project management skill, Project entity	Project synchronisation and locking hooks
Scars	Victory closure skill, end-of-session hook	Recall skill, injection at session start and before each tool
Daily audit reports	Scheduled daily audit task	Session brief script (injected at startup)
Skill index (size)	Skill indexing	Skill pre-invocation hook
Persona drift history	Persona command	Drift review
Ideas / brainstorm	Ideation skill	Hub brainstorm panel
Incoming emails	Email reception facade	Inbox management skill
Bank transactions	Bank statement importer	Financial tracking skill

Architecture note: The agent registry relies on a two-tier architecture — a writable base table and a read-only read view, both containing the same number of entries. The persona recalibration script writes to the base table; the agent file regeneration script reads from the view. These two components remain consistent and do not diverge: there is no risk of uncontrolled duplication or refactoring.