Hermes Wiki
AIDigest/AGENTS

AGENTS.md — AIDigest/

Operating manual for any agent (Claude or otherwise) working in AIDigest/. Read ../README.md first for vault-wide rules (frontmatter, wikilinks, _index.md conventions) — this file only adds what's specific to this folder. If a chat instruction conflicts with this file, the chat instruction wins for that session only.

Project Overview

AIDigest/ is a rolling collection of AI-innovation articles, one Markdown file per finding, fed by two independent paths:

  1. Scheduled scrape — the AI Digest Scraper cloud routine, cron 0 0,4,9,14,19 * * * (5 fixed EDT clock times a day), its own isolated sandbox with its own prompt. Full config: ai-digest-scheduler. This file does not govern the routine — its prompt is self-contained and out of scope here. Don't infer routine changes from anything below.
  2. Interactive sessions — Mihir chatting with an agent (this file's actual scope) to research something on demand, ask a counter-question on an existing article, or relate a finding to his own work. A per-article "Copy prompt for Claude" button on wiki.fullstackfusions.com (viewer/components/CopyClaudePrompt.tsx) makes this frictionless from mobile: it copies a ready-made instruction naming the exact file, meant to be pasted into a fresh claude.ai/Claude Code chat — deliberately not a custom in-app chat UI, since that would need its own Anthropic API key and billing separate from Mihir's claude.ai subscription. See ai-digest-scheduler § Asking from mobile.

Output lives directly in the vault, under date-sharded subfolders (AIDigest/YYYY/MM/DD/*.md) — unlike a staging-and-promotion pipeline, there's no separate output location and no promotion step.

Trigger Commands

Recognize these and switch mode accordingly — don't ask which mode, infer from the phrasing. This replaces the old blanket "always research immediately" rule with something closer to how the sibling TechResearch project's agents work.

Trigger Mode What happens
A topic, question, or link given directly in chat, no queue/schedule keyword Immediate Research (default) Research now, in this session. Write AIDigest/YYYY/MM/DD/YYYY-MM-DD-HHMM-slug.md per the structure below. Log it (see Logging).
queue [topic] / add to queue / schedule this for later Queue Append to _queue.md's ## Pending. No research now — the next scheduled run picks it up.
A question that references an existing AIDigest/*.md article (by name or clear context) Discussion Answer now, append the exchange under that article's ## Discussion section, push. Never defer this.
relate this to my work / how does this connect to Localz/my courses/my blog / asked after any research Relevance Mapping See below — cross-reference LocalzDocs/, CoursesDocs/, BlogPosts/, append findings to the article's ## Relevance to My Work section (create it if missing).
go deeper on [X] (said after an article already exists on X) Follow-up Expand in the same file — append to ## Discussion or extend ## Key Takeaways, don't spin up a duplicate article for the same finding.

If a request is genuinely ambiguous between Immediate Research and Queue (e.g. it's unclear whether Mihir wants it now or just wants it noted for later), ask — don't guess silently on this one, the cost of guessing wrong is a missed real-time answer or an unwanted research tangent.

Disambiguating which article for Discussion/Follow-up/Relevance Mapping: a message that opens with "Open AIDigest/<file>.md..." (the shape the "Copy prompt for Claude" button produces) already names the exact file — just use it, no disambiguation needed. Otherwise, if Mihir doesn't give an exact filename, grep/glob AIDigest/**/*.md frontmatter (title, source) for candidates before writing anything. If there's exactly one clear match, proceed. If there's more than one plausible match (or none), list the candidates — filename + title — and ask him to confirm which one, rather than guessing. A Discussion/Relevance write lands permanently in a specific file and gets pushed; a wrong guess means real content in the wrong article's history, not something to silently self-correct later.

Article Structure Conventions

Every interactively-written article follows the same shape the scheduler already uses, plus one addition:

---
title: "<article title>"
tags: [ai-digest, <1-3 domain tags>]
source: <exact URL>
created: YYYY-MM-DD
---

# <Title>

**Source**: [<publication/author>](<URL>) — <publish date>

## Summary

<2-4 sentences: what this is and why it's notable>

## Key Takeaways

- <specific, substantive point, not filler>

## Relevance to My Work

<Only include this section if Relevance Mapping (below) found a genuine connection. Cite specific note paths, e.g. "relates to the RAG chunking approach in [[BlogPosts/2026-03-27-rag-travel-tourism-systems]]" or "Localz's Observability-Stack note ([[LocalzDocs/Observability-Stack]]) touches the same tradeoff." Omit the section entirely if nothing genuinely connects — don't force one.>

## Discussion

_(No questions yet — ask follow-ups via a Claude Code chat session on this repo; answers get appended here.)_

Scheduler-written articles won't have ## Relevance to My Work unless you add it interactively afterward (via the Relevance Mapping trigger) — that's expected, not a bug to fix.

## Reel Script (opt-in for interactive, compulsory for AIDigest/ scheduler articles): since 2026-07-13, every AIDigest/ scheduler article carries a ## Reel Script section — Mihir records these as 2-5 minute Instagram Reels. This does NOT apply to TechEnglishVocab/ or any other scheduler output. For interactive articles, only add this section if he explicitly asks for it in-session (e.g. "make this reel-ready") — don't add it by default just because it exists on scheduler articles.

Eligibility check (run before writing): not every digest item has a genuine hands-on artifact. If the item has real code, a verified metric, or a diagrammable flow — proceed. If it doesn't, do not force one — set reel_eligible: false in frontmatter and skip the ## Reel Script section entirely (no separate log entry needed; AgentStack/Hermes/dispatcher.py's nightly structural lint already flags any AIDigest/*.md article missing the reel_eligible field, same mechanism as its missing-frontmatter/missing-Related checks — see check_missing_reel_eligible()). If eligible, set reel_eligible: true and proceed to the 4 beats below.

When eligible, write it as an actual spoken script (sentences meant to be read aloud, not bullet fragments), exactly 4 labeled beats, each with a word budget (~140 wpm spoken pace):

  • Hook (~15-20s, 35-45 words): stakes or a concrete consequence first, never a self-intro ("Hi, I'm a dev..."). Write in FullStackFusions voice — direct and specific, not stock reel-hook phrasing ("You won't believe...", "This changes everything").
  • Core Concept (~45-90s, 105-200 words): the "why" and the actual mechanism; define any jargon immediately with a plain analogy.
  • Hands-On (~45-150s, 105-350 words): the single most concrete, screen-worthy artifact the topic genuinely offers — a few lines of real code, a system-design flow, or a verified before/after metric. Never invent one. If pulling from a scraped source article, reword/re-derive the artifact — never lift code or figures verbatim.
  • Takeaway (~20-30s, 45-70 words): the practical/business ROI plus a one-line call to action. Committed opinion, not a hedge — state the verdict the way you would in a blog post, not a balanced summary.

Let total length flow from content depth — word budgets above sum to ~290 words (~2 min) at the low end and ~665 words (~4.75 min, i.e. "up to 5 min") at the high end. Default to the tight end; only stretch toward the long end when the Hands-On beat has real substance. Don't pad a thin topic to hit a longer runtime. Full rationale and the routine-side config: ai-digest-scheduler.

Relevance Mapping

When asked to relate a finding to Mihir's own work, or when writing an article interactively, check for genuine overlap against:

  • LocalzDocs/ — Localz product/tech docs (Canada-first marketplace: stack decisions, monetization, MVP roadmap, observability)
  • CoursesDocs/ — course-platform research and content-delivery patterns
  • BlogPosts/ — his own published/drafted technical writing (RAG, tokens/context engineering, AI concepts)

How: search those folders for real topical overlap (grep for shared concepts/tools/patterns, not just keyword coincidence), and cite the specific note by path/wikilink. Only include a connection if it's real — a coincidental shared word (e.g. both mention "database") isn't a connection. If nothing genuinely connects, say so plainly rather than fabricating a link. This mirrors the sibling TechResearch project's rule: a list of unconnected facts is a failed report, but a forced connection is worse than none.

File Ownership

  • writelist.md — user-owned. The routine reads it, never writes it. Edit it directly anytime to change sources/topics/verticals.
  • _queue.md — routine-managed split: ## Pending (topics waiting to be researched) / ## Done (moved there by the routine after it writes an article). Add to Pending yourself; don't hand-edit Done.
  • _sources.md — append-only log of source URLs already covered, one line per article. Both the scheduler and interactive sessions check it before researching a topic (to avoid a duplicate article) and append to it after writing one — this includes Immediate Research articles written in an interactive chat, not just scheduled runs, so the two paths stay in sync.
  • YYYY/MM/DD/YYYY-MM-DD-HH-slug.md (routine) or YYYY/MM/DD/YYYY-MM-DD-HHMM-slug.md (interactive session) — one per article, sharded into a subfolder by its UTC calendar date. The routine only ever fires on the hour, so its filenames drop the minute; an interactive session can happen at any minute, so it keeps one. See Article Structure Conventions above.
  • AGENTS_OTHER.md — a reference dropped in from a different project (TechResearch's own AGENTS.md), kept here only as the source pattern this file was adapted from. Not itself an AIDigest convention document — flag to Mihir if it should be moved out or deleted once it's no longer needed for reference.

Logging

Every AI Digest Scraper cron run prepends a [AIDIGEST] entry to Logs/2026.md (see ai-digest-scheduler), even on quiet runs with nothing new. If you write an article interactively, log it the same way: prepend ## [YYYY-MM-DD HH:MM UTC] AI Digest Scraper (interactive) with an [AIDIGEST] bullet noting what you wrote, so Logs/2026.md and the Dashboard "Scheduler Activity" count stay a complete picture regardless of source. Discussion-only or Relevance-Mapping-only edits to an existing file don't need a new log entry — logging is for new articles.

Definition of Done (before delivering any interactive research/discussion)

  • Correct trigger mode used (Immediate Research / Queue / Discussion / Relevance Mapping / Follow-up)
  • Article structure matches the convention above; ## Relevance to My Work included only if a genuine connection was found
  • Source verified and dated in frontmatter, not just search-ranking-assumed
  • writelist.md untouched; _queue.md only edited via its Pending→Done convention
  • Checked _sources.md before researching (no duplicate of an already-covered source); appended a line to it after writing a new article
  • New articles logged per Logging above
  • No fabricated cross-links to LocalzDocs//CoursesDocs//BlogPosts/
Hermes Wiki