How a Reviewer Agent is Spawned and Utilized in the AI Job Search Application Process

The reviewer agent is spawned automatically by the apply command via the agent launcher, executes a cache-first company research workflow defined in gemini-research-expert.md, and feeds verified intelligence into downstream evaluation steps.

In the MadsLorentzen/ai-job-search repository, the reviewer agent functions as the core research engine that validates and caches company information before any application materials are generated. Understanding exactly how this specialized agent is spawned and utilized reveals the cache-optimized architecture that minimizes API calls while ensuring data consistency. This analysis examines the specific command definitions, agent configurations, and skill integrations that orchestrate the reviewer’s lifecycle from invocation to data delivery.

Agent Definition and Configuration

The reviewer agent’s behavior and system prompts are defined in .claude/agents/gemini-research-expert.md. This configuration file serves as the template that instructs the LLM on how to conduct company research, source verification, and data synthesis. It establishes the agent’s role as the authoritative research expert responsible for gathering intelligence before cover letters or interview preparations are drafted.

Spawning Mechanism via the Apply Command

The primary trigger for reviewer agent instantiation resides in .claude/commands/apply.md. When a user executes the job application workflow, this command specification directs the framework to spawn the reviewer agent through the internal agent-launcher routine.

Command Orchestration

Within apply.md, the orchestration logic includes a step that creates a reviewer-agent-research instance. The launcher references the gemini-research-expert definition and initializes a new LLM session with the reviewer-specific prompt template. This spawning occurs automatically whenever the apply command requires current company data, ensuring that fresh research is available before subsequent steps like interview preparation and cover letter generation begin.

Core Responsibilities in the Application Process

Once spawned, the reviewer agent executes a three-phase workflow designed to minimize redundant API calls and ensure that all downstream steps consume identical verified data.

Cache-First Research Lookup

The agent first queries the local company_research/ cache directory. As validated by the test suite in tests/test_company_research_cache.py, the implementation prioritizes cache hits to avoid unnecessary external queries. If recent research exists for the target company, the agent returns the cached data immediately, terminating the research phase without invoking external APIs.

Fresh Data Acquisition and Persistence

On cache misses, the reviewer agent queries external sources—such as company websites, LinkedIn profiles, and recent news feeds—to compile a concise research report. Following the patterns verified in tests/test_company_research_cache.py, the agent writes this output back to the company_research/ cache. This persistence ensures that subsequent steps in the same workflow—and future application processes for the same company—access pre-validated intelligence.

Integration with Evaluation Workflows

The research output flows directly into .claude/skills/job-application-assistant/04-job-evaluation.md. This skill file consumes the cached company intelligence to evaluate job fit and drive downstream steps such as interview question generation. By reading from the same cache entry written by the reviewer agent, the evaluation phase guarantees absolute consistency between research findings and the application materials ultimately submitted by the user.

Implementation Architecture

The following examples illustrate the spawning and utilization patterns in practice. These snippets reflect the architecture identified in the source analysis and demonstrate the cache-optimized research flow.

# Execute the full application workflow; this internally spawns the reviewer agent

import subprocess

subprocess.run(["ai-job-search", "apply", "--url", "https://example.com/job/123"])

# Direct agent invocation pattern (illustrative)

from ai_job_search.agent_launcher import launch_agent

reviewer = launch_agent(
    agent_name="gemini-research-expert",
    prompt_name="reviewer-agent-research",
    cache_path="company_research/example.com"
)

# The agent returns a dict containing the research summary

research_report = reviewer.run()
print(research_report["summary"])

# CLI execution showing the reviewer agent lifecycle

$ ai-job-search apply --url https://example.com/job/123
[✔] Reviewer agent spawned → cache hit validated
[✔] Company research retrieved from local cache
[✔] Cover letter generated using verified research data

Summary

• The reviewer agent is defined in .claude/agents/gemini-research-expert.md, which configures the LLM’s research behavior and system prompts.
• Spawning is triggered automatically by the apply command specified in .claude/commands/apply.md, which invokes the agent launcher to instantiate a reviewer-agent-research session.
• The agent implements a cache-first strategy, checking the company_research/ directory before performing external lookups, with validation logic tested in tests/test_company_research_cache.py.
• Fresh research is persisted to the local cache to ensure that downstream steps in .claude/skills/job-application-assistant/04-job-evaluation.md consume consistent, verified data.
• This architecture minimizes external API usage while maintaining data integrity across the entire application pipeline, as documented in CHANGELOG.md at line 191.

Frequently Asked Questions

What triggers the reviewer agent to spawn?

The reviewer agent spawns automatically when the apply command executes, as specified in .claude/commands/apply.md. The command detects when company research is required and triggers the agent launcher to instantiate the gemini-research-expert agent using the reviewer-agent-research prompt configuration.

How does the reviewer agent avoid redundant API calls?

The agent checks the local company_research/ cache directory before querying external sources. If valid cached data exists for the target company, the agent returns it immediately; only cache misses trigger fresh external research, significantly reducing API consumption and latency.

Which components consume the output from the reviewer agent?

The primary consumer is .claude/skills/job-application-assistant/04-job-evaluation.md, which reads the cached research to evaluate job fit and generate interview materials. The shared cache ensures that all downstream steps—including cover letter generation—use identical company intelligence.

Where is the reviewer agent behavior defined?

The agent’s system prompts, research parameters, and behavioral constraints are defined in .claude/agents/gemini-research-expert.md. This file serves as the configuration template that the agent launcher references when spawning new reviewer instances for the application workflow.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}