Skip to main content

​
Introduction to jre-notion-workers

jre-notion-workers is a set of Notion Workers built on the @notionhq/workers platform to support an 11-agent automation fleet. These workers enforce governance rules, reduce agent overhead, and make machine-to-machine coordination reliable across all agents.

​
What It Does

The package provides three specialized workers that handle critical coordination tasks so individual agents don’t have to remember or implement governance rules:

​
write-agent-digest

Accepts structured agent output and creates a schema-compliant digest page in the Docs or Home Docs database. This worker handles:
  • Status line formatting and emoji derivation (✅ / ⚠️ / ❌)
  • Section ordering according to governance standards
  • ERROR-title naming for degraded runs
  • Heartbeat formatting for healthy silence detection
  • Validation of flagged items (ensuring each has task_link or no_task_reason)

​
check-upstream-status

Finds the most recent digest for a given agent, parses its machine-readable status line and run timestamp, and returns a structured result. Use this at the start of any run that depends on upstream data to determine:
  • Whether upstream data is fresh or stale
  • The status of the last upstream run (complete/partial/failed)
  • Whether to include a data_completeness_notice in your digest

​
create-handoff-marker

Creates a handoff record when one agent escalates to another. This worker:
  • Returns a pre-formatted Escalations block ready to paste into your digest
  • Optionally creates a Notion Task for tracking
  • Enforces a circuit breaker: no duplicate handoff within 7 days for the same source→target pair
  • Enforces a re-escalation cap: maximum 2 escalations in the same direction within 7 days
  • Sets needs_manual_review flag when escalation cap is reached

​
Key Features

Governance Enforcement

Automatically enforces status line formats, page title patterns, and section ordering so agents don’t have to remember the rules

Circuit Breakers

Prevents duplicate handoffs and caps re-escalations to avoid runaway loops between agents

Schema Validation

Validates all input using JSON schemas before creating Notion pages, catching errors early

Machine-Readable Status

Parses and generates standardized status lines that agents can read programmatically

​
Governance Rules Enforced by Code

These workers automate the following governance standards:
  • Status lines: Sync / Snapshot / Report status and emoji (✅ / ⚠️ / ❌) derived from input; agents don’t format them
  • Page titles: Normal runs use {emoji} {Digest Type} — {date}. Degraded runs use {Digest Type} ERROR — {date} (no emoji)
  • Heartbeat: “Heartbeat: no actionable items” added automatically when appropriate so Morning Briefing can distinguish healthy silence from failure
  • Flagged items: Every flagged item must have task_link or no_task_reason; invalid input is rejected
  • Actions Taken: Always rendered (Created Tasks / Updated Tasks / No Tasks Created)
  • Handoff circuit breaker: No duplicate handoff task for the same source→target within 7 days
  • Escalation cap: At most 2 escalations in the same direction within 7 days; then needs_manual_review is set

​
Agent Workflow

Agents in the 11-agent system follow this pattern:
1

Check upstream status

At run start, call check-upstream-status for any upstream agents you depend on. Use data_completeness_notice and degraded in your digest when upstream is stale or failed.
2

Handle escalations

During the run, call create-handoff-marker when escalating to another agent (with or without creating a Task).
3

Write digest

At run end, call write-agent-digest with your structured output. It creates the page with the correct schema, status line, and sections.

​
Supported Agents

The workers support these agents with their corresponding digest title patterns:
AgentDigest Title PatternTarget DB
Inbox ManagerEmail Triagedocs
Personal Ops ManagerPersonal Triagehome_docs
GitHub InsynceratorGitHub Syncdocs
Client Repo AuditorClient Repo Auditdocs
Docs LibrarianDocs Quick Scan, Docs Cleanup Reportdocs
VEP Weekly ReporterVEP Weekly Activity Reportdocs
Home & Life WatcherHome & Life Weekly Digesthome_docs
Template Freshness WatcherSetup Template Freshness Reportdocs
Time Log AuditorTime Log Auditdocs
Client Health ScorecardClient Health Scorecarddocs
Morning BriefingMorning Briefingdocs

​
Alpha Status

@notionhq/workers is in alpha. APIs and deployment behavior may change. See makenotion/workers-template for the latest.

​
Next Steps

Installation

Install the package and set up credentials

Quickstart

Register your first worker and make test calls

Build docs developers (and LLMs) love

Get started for freeTalk to us