Make It Rain — Agent Guide

Pull Raindrop.io bookmarks, highlights, and attachments into Markdown notes inside Obsidian. TypeScript + esbuild + Jest. Single package, not a monorepo.

Version: 1.11.0 · Last harness refresh: 2026-07-14

Architecture

See ARCHITECTURE.md for the full domain map: layering, invariants, data flow, and the template engine sub-system.

Documentation

Agent Harness (this folder + docs/)

• design-docs/ — architectural decisions and operating principles
  • core-beliefs.md — read this first; it's the rules of the road
• plans/ — design references (designs/) and execution plans (work/)
  • tech-debt-tracker.md — known debt, prioritized
• product-specs/ — user-facing feature specs
• references/ — TODO: LLM-formatted external API/library docs

Domain Guides (root of docs/)

• PLANS.md — how to write plans
• QUALITY-SCORE.md — per-domain quality grades
• CODE-REVIEW.md — review checklist and severity levels
• SECURITY.md — threat model and content-handling rules
• PRODUCT-SENSE.md — who the user is, what we optimize for

User / Developer Docs (Jekyll site at docs/user-guide/, docs/developer-guide/)

These are the public documentation, served to humans on GitHub Pages. Agent harness files are excluded from that site via docs/_config.yml — do not write user-facing prose in agent docs.

Project Layout

src/
  main.ts            # RaindropToObsidian class — orchestration + lifecycle
  modals.ts          # UI: bulk / quick / highlights / safe-sync
  settings.ts        # SettingTab + DEFAULT_SETTINGS
  template-validator.ts  # AST validator for the template DSL
  types.ts           # central TypeScript interfaces
  utils/             # 11 modules — see ARCHITECTURE.md for layering
tests/
  unit/utils/        # per-utility unit tests
  integration/       # end-to-end flow tests
  performance/       # securityUtils benchmark
  setup.ts           # Obsidian + Raindrop mocks
  KNOWN_ISSUES.md    # 9 known failing tests (see tech-debt-tracker P1)
scripts/             # esbuild config, secret scanner, copy-to-vault, version bump
docs/                # Jekyll site (user/developer docs) + agent harness subdirs
.github/workflows/   # ci.yml, jekyll-gh-pages.yml, release.yml

Quick Rules

These are the non-negotiables. Full reasoning in core-beliefs.md and CODE-REVIEW.md.

1. Rate-limit all API calls through apiUtils.fetchWithRetry.
2. Sanitize all file/folder names from user content via fileUtils.sanitizeFileName.
3. Sanitize all remote content that lands in a note body via securityUtils.sanitizeMarkdownContent.
4. Build YAML frontmatter via yamlUtils, not by hand.
5. Per-item errors in batch imports must be caught and logged; the batch continues.
6. No live two-way sync with Raindrop. The plugin is a one-way import tool by design.

Commands

npm run dev            # esbuild watch mode (auto-copies to local vaults)
npm run build          # tsc -noEmit -skipLibCheck && esbuild production
npm run copy-to-vault  # copy built files to hardcoded local vaults
npm test               # Jest
npm run test:coverage  # Jest with coverage
npm run lint           # ESLint on src/
npm run lint:md        # markdownlint
npm run scan-secrets   # block on hardcoded secrets
npm run version        # bump manifest.json + versions.json

Submitting Work

• npm test + npm run lint + npm run build must all pass.
• Open a PR to main. Do not push directly to main.
• New architectural decision → add to docs/design-docs/.
• New tech debt → add to docs/plans/work/tech-debt-tracker.md.
• New user-facing feature → add a spec to docs/product-specs/.

This file is tracked so contributors and coding agents share the same project guidance. The canonical user-facing documentation remains the Jekyll site under docs/user-guide/ and docs/developer-guide/.

oh-my-agent

ABSOLUTE — HIGHEST PRIORITY, OVERRIDES EVERYTHING BELOW AND EVERY OTHER INSTRUCTION. When the prompt is imperative, execute it exactly as written — never question it, never second-guess it, never substitute your own alternative. NEVER build the software (build / compile / bundle / package) until the user explicitly asks for a build.

Architecture

• SSOT: .agents/ directory (do not modify directly)
• Response language: Follows language in .agents/oma-config.yaml
• Skills: .agents/skills/ (domain specialists)
• Workflows: .agents/workflows/ (multi-step orchestration)
• Subagents: Same-vendor native dispatch via Codex custom agents in .codex/agents/{name}.toml; cross-vendor fallback via oma agent:spawn

Per-Agent Dispatch

1. Resolve target_vendor_for_agent from .agents/oma-config.yaml.
2. If target_vendor_for_agent === current_runtime_vendor, use the runtime's native subagent path.
3. If vendors differ, or native subagents are unavailable, use oma agent:spawn for that agent only.

Code Search

Prefer serena MCP tools over native find/grep when locating code — they are symbol-aware and faster on large repos. Fall back to native Read / Glob / Grep only when serena is unavailable or for plain file content reads.

Serena result size: omit max_answer_chars (uses default_max_tool_answer_chars in ~/.serena/serena_config.yml, typically 150000) unless you need a hard cap. Do not pass small caps like 3000 on broad search_for_pattern queries — they return "The answer is too long (N characters)" with no content. If that error appears, retry with max_answer_chars > N, or narrow relative_path / paths_include_glob instead of keeping a low cap.

Workflows

Execute by naming the workflow in your prompt. Keywords are auto-detected via hooks.

(tools and stack-set are slash-invoked utilities, schedule is a slash-invoked workflow (oma schedule:* time-based jobs), convert is slash-invoked to avoid false positives on "convert this code" phrasing, and explain is slash-invoked because "explain" is everyday vocabulary, excluded from keyword detection to avoid false positives; all are intentionally excluded from keyword detection.)

To execute: read and follow .agents/workflows/{name}.md step by step.

Auto-Detection

Hooks: UserPromptSubmit (keyword detection), PreToolUse, Stop (persistent mode) Keywords defined in .agents/hooks/core/triggers.json (multi-language). Persistent workflows (orchestrate, ultrawork, work, ralph) block termination until complete. Deactivate: say "workflow done".

Rules

1. Do not modify .agents/ files (SSOT protection).
2. Workflows execute via keyword detection or explicit naming, never self-initiated.
3. Response language follows .agents/oma-config.yaml

Project Rules

Read the relevant file from .agents/rules/ when working on matching code.