Architecture

Rolester is organized around two kinds of things: skills that make judgment calls and scripts that do deterministic work.

The flow

candidate profile
  → search setup (setup-searches)
  → sourced scan (search-jobs)
  → gated intake ← research loop (research-company / research-comp / research-boards)
  → body-read evaluation (evaluate-job)
  → tailoring (tailor-application)
  → communication tracking (email-comms / schedule-meeting)
  → application tracking (apply-job)
  → interview prep (interview-prep)
  → outcome tracking (track-outcomes) → reevaluation loop (reevaluate-strategy) ↑

The research loop feeds evaluation and interview prep with cited company intel and comp benchmarks. The reevaluation loop reads the full funnel and recommends targeting, fit-calibration, or channel-mix changes when outcome thresholds trip.

Layers

Skill layer

Skills are the 21 SKILL.md files under .agents/skills/. They make judgment calls:

• what to ask during onboarding
• whether a job passes the body-read gate
• how to rate fit
• which evidence supports an application
• how to draft recruiter communications
• what to include in an interview packet

Skills are field-neutral procedures. They produce different results for different candidates because they read different config files — not because they contain personal preferences.

Script layer

Scripts under src/ and exposed via npm run * should be deterministic:

• validate setup and environment (doctor)
• build source URLs from config (searches)
• parse saved job bodies
• dedupe sourced roles
• check link liveness
• render the dashboard (tracker)
• validate tracker state (verify:tracker)
• manage the gate files (gate), learning files (learnings), and activity feed (activity)

Communication layer

workspace/tracker.json stores concise communication metadata. Long message bodies and thread summaries live in workspace/comms/. email-comms reads both before drafting.

Source layer

Search-source adapters live under src/core/providers/. URL-query sources build stable URLs from config before the browser opens them. ATS sources use public endpoints where possible. Browser-rendered sources preserve the generated URL, raw capture, and recency cutoff.

User layer

Candidate facts, generated artifacts, and tracker state stay local:

• candidate/ — private config, gitignored
• workspace/ — runtime data, gitignored

System layer

Reusable skills, scripts, templates, and schemas are public-safe and shipped with the package.

Intent router

AGENTS.md in the repo root is the canonical intent router. It maps user intent to the 21 skills. The agent reads it first, then routes every paste or instruction through it. See Agent Contract for the full routing table.

CLAUDE.md points Claude Code at the same rules. Other AGENTS.md-aware runtimes (Codex, etc.) read AGENTS.md natively.