JobApply: A Spec-Driven, Skill-Based CV Pipeline

A privacy-first, human-in-the-loop pipeline that automates the job application process from inbox discovery to defensible CV drafting. Built for the Google Agent Development Hackathon.

⚠️ The Problem

1. The Time Sink: Tailoring a resume to bypass Applicant Tracking Systems (ATS) takes hours per job. This turns applying into a rare, high-friction event.
2. The Hallucination Danger: Using standard LLM wrappers often results in "hallucinated" skills or inflated claims that immediately collapse during technical interviews.
3. The Privacy Risk: Uploading your actual career history, contact information, and target compensation to random SaaS platforms is a severe privacy leak.

💡 The Solution

JobApply is a local-first pipeline that lives on your machine, packaged with a clean React dashboard and an Express backend. It reads job alerts directly from your inbox using a read-only IMAP script, scrapes the full job descriptions, triages them against your target profile, and drafts highly tailored resumes.

Crucially, it is tightly constrained to draw only from your prose Master CV. To ensure accuracy, the tool enforces strict rules against inventing skills or facts, and runs a dedicated defensibility audit step to catch hallucination or overclaim. This produces a defensible, tailored resume in minutes instead of hours. This is achieved through a strict, spec-driven architecture where each "skill" is tightly constrained by specific markdown instructions and invariant rules.

🏗️ Architecture: The Three Human Gates

This tool prioritizes accuracy and safety. The automated scripts do the heavy lifting, but the human retains absolute veto power at three critical gates:

sequenceDiagram
    actor Human
    participant UI Dashboard
    participant Discover/Triage
    participant Tailor
    participant Audit
    
    %% Phase 1: Discovery
    Human->>UI Dashboard: Click "Scan Inbox"
    UI Dashboard->>Discover/Triage: Read IMAP & Scrape JDs
    Discover/Triage-->>UI Dashboard: Ranked Job List (Apply/Consider/Skip)
    
    note over Human,UI Dashboard: GATE 1: Human reviews and selects a job to pursue
    
    %% Phase 2: Tailoring
    Human->>UI Dashboard: Click "Tailor Resume"
    UI Dashboard->>Tailor: Load Master CV & Formatting Guide
    Tailor-->>UI Dashboard: Drafted Resume displayed in UI
    
    note over Human,UI Dashboard: GATE 2: Human triggers the Defensibility Audit
    
    %% Phase 3: Audit
    Human->>UI Dashboard: Click "Run Audit"
    UI Dashboard->>Audit: Compare Draft vs. Master CV
    Audit-->>UI Dashboard: Defensibility Note (Flags Overclaims)
    
    note over Human,UI Dashboard: GATE 3: Human reviews audit, finalizes, and submits manually.

Loading

The Core Skills

• Discovery (scan): A robust tool that uses safe IMAP EXAMINE mode to pull job alerts, bypasses anti-scraping walls using a headless Playwright browser, and uses Gemini to score the role against your targeting criteria.
• Tailor (tailor): Merges the specific Job Description, your Master CV, and a strict Formatting Guide to draft the customized markdown CV using gemini-2.5-pro.
• Audit (audit): Acts as a red-team reviewer. It compares the tailored draft against the Master CV and enforces "Locked Traps" (e.g., preventing the AI from attaching 15 years of experience to a technology that only existed for 3 years).

🤖 The Differentiator: Spec-Driven Autonomous Metaloop

JobApply isn't just an application; it is an architectural proof of concept for Spec-Driven Agentic Coding.

While the bulk of the interface was hand-plumbed, the project includes an autonomous "metaloop" to prove that an agent can autonomously converge code against human-authored contracts. The absolute source of truth for the system is a suite of strict behavioral contracts defined in a validation script (src/verify.ts). When an End-to-End Playwright test fails (e.g., failing to handle API rate limits correctly), the metaloop reads the trace, navigates the codebase, autonomously writes the patch in React, and verifies the fix until the test suite is green.

For the full philosophical writeup on why "automated checking lies to you," see our WRITEUP.md.

Note to Judges: You can check out the agent-loop-workspace branch in this repository to see the raw, indelibly recorded commit history of the loop proposing contracts and autonomously patching the React UI in real-time.

🚀 Setup & Installation

Because privacy is the default, all local data is gitignored. We have provided fictional sample data so you can test the pipeline safely.

1. Clone the repository:

   git clone https://github.com/ratiarsone/jobapply-hackathon.git
   cd jobapply-hackathon

2. Install dependencies:

   npm install
   cd ui && npm install && cd ..

3. Configure Environment: Copy the example environment file and fill in your Gemini API key.

   cp .env.example .env

   Note: Ensure MASTER_PATH in your .env points to ./master/sample/master-repo.sample.txt to use the fictional candidate profile.

💻 Usage

Run the dashboard workflow:

1. Start the Backend Server:

   npx tsx src/server.ts

2. Start the React UI: In a new terminal window:

   cd ui
   npm run dev

3. Open the Dashboard: Navigate to http://localhost:5173 in your browser. From there, you can scan your inbox, select a job, tailor a resume, and run the defensibility audit entirely through the UI.

🔒 Security & Privacy

• No SaaS Uploads: The LLM calls are routed directly to Gemini API. Your data is not stored in a centralized database.
• Read-Only Inbox: The discovery tool forces IMAP EXAMINE mode, ensuring emails cannot be deleted or marked as read.
• .gitignore Enforcement: The repository structure structurally prevents the accidental commit of any file within the /local/ or secrets/ directories.