Overview
The jre-notion-workers system supports an 11-agent architecture where each agent produces digests (reports) that are written to Notion databases. The system provides strict validation, standardized naming patterns, and automated routing.The 11 Agents
Each agent has a specific role and produces one or more digest types:Inbox Manager
Digest: Email Triage
Target: Docs database
Purpose: Processes and triages incoming emails
Target: Docs database
Purpose: Processes and triages incoming emails
Personal Ops Manager
Digest: Personal Triage
Target: Home Docs database
Purpose: Manages personal tasks and operations
Target: Home Docs database
Purpose: Manages personal tasks and operations
GitHub Insyncerator
Digest: GitHub Sync
Target: Docs database
Purpose: Synchronizes GitHub activity and issues
Target: Docs database
Purpose: Synchronizes GitHub activity and issues
Client Repo Auditor
Digest: Client Repo Audit
Target: Docs database
Purpose: Audits client repositories for issues
Target: Docs database
Purpose: Audits client repositories for issues
Docs Librarian
Digests:
- Docs Quick Scan
- Docs Cleanup Report
Target: Docs database
Purpose: Maintains documentation quality
VEP Weekly Reporter
Digest: VEP Weekly Activity Report
Target: Docs database
Purpose: Generates weekly VEP activity summaries
Target: Docs database
Purpose: Generates weekly VEP activity summaries
Home & Life Watcher
Digest: Home & Life Weekly Digest
Target: Home Docs database
Purpose: Tracks personal and life events
Target: Home Docs database
Purpose: Tracks personal and life events
Template Freshness Watcher
Digest: Setup Template Freshness Report
Target: Docs database
Purpose: Monitors template staleness
Target: Docs database
Purpose: Monitors template staleness
Time Log Auditor
Digest: Time Log Audit
Target: Docs database
Purpose: Audits time tracking entries
Target: Docs database
Purpose: Audits time tracking entries
Client Health Scorecard
Digest: Client Health Scorecard
Target: Docs database
Purpose: Monitors client account health
Target: Docs database
Purpose: Monitors client account health
Morning Briefing
Digest: Morning Briefing
Target: Docs database
Purpose: Daily summary and priorities
Target: Docs database
Purpose: Daily summary and priorities
Agent Configuration
The system maintains agent configuration insrc/shared/agent-config.ts:
All agent names are validated against
VALID_AGENT_NAMES. Invalid agent names are rejected at the validation stage.Digest Patterns
Each agent produces one or more standardized digest types. The first digest pattern for each agent is used as the default digest type in page titles.Multi-Pattern Agents
Some agents produce multiple digest types:Docs Librarian
Docs Librarian
The Docs Librarian produces two types of digests:
- Docs Quick Scan - Fast scan of documentation
- Docs Cleanup Report - Detailed cleanup recommendations
Default Digest Type
The system provides a helper function to get the default digest type:Target Database Routing
Agents write to one of two Notion databases:Docs Database
Agent Count: 9 agents
Environment Variable:
Purpose: Work-related documentation and reportsAgents:
Environment Variable:
DOCS_DATABASE_IDPurpose: Work-related documentation and reportsAgents:
- Inbox Manager
- GitHub Insyncerator
- Client Repo Auditor
- Docs Librarian
- VEP Weekly Reporter
- Template Freshness Watcher
- Time Log Auditor
- Client Health Scorecard
- Morning Briefing
Home Docs Database
Agent Count: 2 agents
Environment Variable:
Purpose: Personal and life managementAgents:
Environment Variable:
HOME_DOCS_DATABASE_IDPurpose: Personal and life managementAgents:
- Personal Ops Manager
- Home & Life Watcher
Automatic Routing
Thewrite-agent-digest worker automatically routes digests to the correct database:
The
target_database field in WriteAgentDigestInput must be either "docs" or "home_docs". This is enforced by TypeScript types and JSON schema validation.Agent Validation
All workers validate agent names before processing:Validation Helper
The system provides a validation helper:Digest Page Titles
Digest pages follow standardized title formats:Normal Runs
📧 Email Triage — 2026-03-04🐙 GitHub Sync — 2026-03-04📊 Client Health Scorecard — 2026-03-04
Degraded Runs
Whenstatus_value is "partial" or "failed":
Email Triage ERROR — 2026-03-04GitHub Sync ERROR — 2026-03-04
Error-titled pages omit the emoji to make them visually distinct and easier to spot in the database.
Title Construction
Thewrite-agent-digest worker constructs titles using this logic:
Status Types
Agents report one of four status types:sync - Synchronization Operations
sync - Synchronization Operations
Used for agents that synchronize data between systems.Status values:
complete→ ✅ Completepartial→ ⚠️ Partialfailed→ ❌ Failed
snapshot - Point-in-time Captures
snapshot - Point-in-time Captures
Used for agents that capture a snapshot of current state.Status values:
complete→ ✅ Completepartial→ ⚠️ Partial
report - Analysis Reports
report - Analysis Reports
Used for agents that generate analytical reports.Status values:
full_report→ ✅ Full reportstub→ ⚠️ Stubfailed→ ❌ Failed
heartbeat - No Actionable Items
heartbeat - No Actionable Items
Special status indicating successful run with no actionable items.Always displays as:
Sync Status: ✅ CompleteExample: Email Triage finding no new emailsHeartbeat Detection
The system automatically detects heartbeat runs:status_typeis explicitly"heartbeat", OR- No flagged items AND no tasks created or updated
Heartbeat pages include the line:
Heartbeat: no actionable items in their content.Agent Dependencies
Some agents depend on upstream agents. Thecheck-upstream-status worker enables dependency checking:
Agent Escalations
Agents can escalate issues to other agents using thecreate-handoff-marker worker:
Scope and Boundaries
Reads From
- Docs database
- Home Docs database
Writes To
- Docs database
- Home Docs database
- Tasks database (for handoffs)
Runtime and Deployment
Local Development
Local Development
Runtime: Bun ≥ 1.1
Commands:
Native TypeScript: No transpilation step needed
Commands:
bun run, bun testNative TypeScript: No transpilation step needed
Production Deployment
Production Deployment
Runtime: Node.js ≥ 22
Deployment:
Platform: Notion Workers
Deployment:
ntn workers deployPlatform: Notion Workers
Next Steps
Governance
Learn about the rules that protect the system
Architecture
Understand the system design and data flow
Write Agent Digest
API reference for creating digest pages
Check Upstream Status
API reference for checking agent dependencies