agentleFS
gilliancaigilliancai/career-explorer/AGENTS.md

career-explorer

AGENTS.md0 starsChanged 5 months agoMITView on GitHub

This system was built and used by santifer to evaluate 740+ job offers, generate 100+ tailored CVs, and land a Head of Applied AI role. The archetypes, scoring logic, negotiation scripts, and proof point structure all reflect his specific career search in AI/automation roles. The portfolio that goes with this system is also open source: cv-santiago. It will work out of the box, but it's designed to be made yours. If the archetypes don't match your career, the modes are…

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository3 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

26 rules. About 0 are common, 12 are distinctive, and 14 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 14

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If yes → run node update-system.mjs apply.

    line 36
  2. Distinctive:

    Before doing ANYTHING else, check if the system is set up: Run these checks silently every time a session starts:

    line 74
  3. Very specific:

    If modes/_profile.md is missing, copy from modes/_profile.template.md silently.

    line 81
  4. Distinctive:

    If ANY of these is missing, enter onboarding mode: Do NOT proceed with evaluations, scans, or any other mode until the basics are in place.

    line 83
  5. Very specific:

    If cv.md is missing, ask:

    line 86
  6. Very specific:

    Create cv.md from whatever they provide.

    line 94
  7. Very specific:

    If config/profile.yml is missing, copy from config/profile.example.yml and then ask:

    line 97
  8. Very specific:

    If portals.yml is missing:

    line 109
  9. Very specific:

    If data/applications.md doesn't exist, create it:

    line 115
  10. Distinctive:

    After the basics are set up, proactively ask for more context.

    line 125
  11. Very specific:

    If the user accepts, use the /loop or /schedule skill (if available) to set up a recurring /career-ops scan (or /career-ops-scan if using …

    line 154
  12. Very specific:

    Default modes are in modes/ (English).

    line 170
  13. Distinctive:

    When to use German modes: If the user is targeting German-language job postings, lives in DACH, or asks for German output.

    line 177
  14. Very specific:

    When to use French modes: If the user is targeting French-language job postings, lives in France/Belgium/Switzerland/Luxembourg/Quebec, or …

    line 182
  15. Distinctive:

    When to use Japanese modes: If the user is targeting Japanese-language job postings, lives in Japan, or asks for Japanese output.

    line 187
  16. Distinctive:

    When to use Turkish modes: If the user is targeting Turkish-language job postings, lives in Turkey, or asks for Turkish output.

    line 192
  17. Distinctive:

    Strongly discourage low-fit applications: If a score is below 4.0/5, explicitly recommend against applying.

    line 233
  18. Distinctive:

    Respect recruiters' time: Every application a human reads costs someone's attention.

    line 235
  19. Distinctive:

    Only footer/navbar without JD = closed.

    line 244
  20. Distinctive:

    When spawning headless workers for batch processing, use the appropriate command for your CLI:

    line 252
  21. Very specific:

    Write one TSV file per evaluation to batch/tracker-additions/{num}-{company-slug}.tsv.

    line 276
  22. Very specific:

    All reports MUST include URL: in the header (between Score and PDF).

    line 299
  23. Very specific:

    All statuses MUST be canonical (see templates/states.yml).

    line 300
  24. Very specific:

    No markdown bold (``) in status field

    line 321
  25. Distinctive:

    No dates in status field (use the date column)

    line 322
  26. Distinctive:

    No extra text (use the notes column)

    line 323

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Career-Ops -- AI Job Search Pipeline

Origin

This system was built and used by santifer to evaluate 740+ job offers, generate 100+ tailored CVs, and land a Head of Applied AI role. The archetypes, scoring logic, negotiation scripts, and proof point structure all reflect his specific career search in AI/automation roles.

The portfolio that goes with this system is also open source: cv-santiago.

It will work out of the box, but it's designed to be made yours. If the archetypes don't match your career, the modes are in the wrong language, or the scoring doesn't fit your priorities -- just ask. You (AI Agent) can edit the user's files. The user says "change the archetypes to data engineering roles" and you do it. That's the whole point.

Data Contract (CRITICAL)

There are two layers. Read DATA_CONTRACT.md for the full list.

User Layer (NEVER auto-updated, personalization goes HERE):

  • cv.md, config/profile.yml, modes/_profile.md, article-digest.md, portals.yml
  • data/*, reports/*, output/*, interview-prep/*

System Layer (auto-updatable, DON'T put user data here):

  • modes/_shared.md, modes/oferta.md, all other modes
  • AGENTS.md, CLAUDE.md, *.mjs scripts, dashboard/*, templates/*, batch/*

THE RULE: When the user asks to customize anything (archetypes, narrative, negotiation scripts, proof points, location policy, comp targets), ALWAYS write to modes/_profile.md or config/profile.yml. NEVER edit modes/_shared.md for user-specific content. This ensures system updates don't overwrite their customizations.

Update Check

On the first message of each session, run the update checker silently:

node update-system.mjs check

Parse the JSON output:

  • {"status": "update-available", "local": "1.0.0", "remote": "1.1.0", "changelog": "..."} → tell the user:

    "career-ops update available (v{local} → v{remote}). Your data (CV, profile, tracker, reports) will NOT be touched. Want me to update?" If yes → run node update-system.mjs apply. If no → run node update-system.mjs dismiss.

  • {"status": "up-to-date"} → say nothing
  • {"status": "dismissed"} → say nothing
  • {"status": "offline"} → say nothing
  • {"status": "no-remote-version"} → say nothing (checker reached GitHub but neither VERSION nor the latest release tag parsed as semver — treat as a silent non-failure, same as offline)

The user can also say "check for updates" or "update career-ops" at any time to force a check. To rollback: node update-system.mjs rollback

What is career-ops

AI-powered, CLI-agnostic job search automation: pipeline tracking, offer evaluation, CV generation, portal scanning, batch processing. Runs on any AI coding CLI that follows the open agent skill standard (Claude Code, Codex, Gemini, OpenCode, Qwen, Copilot, Kimi).

Main Files

FileFunction
data/applications.mdApplication tracker
data/pipeline.mdInbox of pending URLs
data/scan-history.tsvScanner dedup history
portals.ymlQuery and company config
templates/cv-template.htmlHTML template for CVs
templates/cv-template.texLaTeX/Overleaf template for CVs
generate-pdf.mjsPlaywright: HTML to PDF
generate-latex.mjsLaTeX CV validator + pdflatex compiler
article-digest.mdCompact proof points from portfolio (optional)
interview-prep/story-bank.mdAccumulated STAR+R stories across evaluations
interview-prep/{company}-{role}.mdCompany-specific interview intel reports
analyze-patterns.mjsPattern analysis script (JSON output)
followup-cadence.mjsFollow-up cadence calculator (JSON output)
data/follow-ups.mdFollow-up history tracker
scan.mjsZero-token portal scanner — hits Greenhouse/Ashby/Lever APIs directly, zero LLM cost
check-liveness.mjsJob posting liveness checker
liveness-core.mjsShared liveness logic (expired signals win over generic Apply text)
reports/Evaluation reports (format: {###}-{company-slug}-{YYYY-MM-DD}.md). Blocks A-F + G (Posting Legitimacy). Header includes **Legitimacy:** {tier}.

First Run — Onboarding (IMPORTANT)

Before doing ANYTHING else, check if the system is set up. Run these checks silently every time a session starts:

  1. Does cv.md exist?
  2. Does config/profile.yml exist (not just profile.example.yml)?
  3. Does modes/_profile.md exist (not just _profile.template.md)?
  4. Does portals.yml exist (not just templates/portals.example.yml)?

If modes/_profile.md is missing, copy from modes/_profile.template.md silently. This is the user's customization file — it will never be overwritten by updates.

If ANY of these is missing, enter onboarding mode. Do NOT proceed with evaluations, scans, or any other mode until the basics are in place. Guide the user step by step:

Step 1: CV (required)

If cv.md is missing, ask:

"I don't have your CV yet. You can either:

  1. Paste your CV here and I'll convert it to markdown
  2. Paste your LinkedIn URL and I'll extract the key info
  3. Tell me about your experience and I'll draft a CV for you

Which do you prefer?"

Create cv.md from whatever they provide. Make it clean markdown with standard sections (Summary, Experience, Projects, Education, Skills).

Step 2: Profile (required)

If config/profile.yml is missing, copy from config/profile.example.yml and then ask:

"I need a few details to personalize the system:

  • Your full name and email
  • Your location and timezone
  • What roles are you targeting? (e.g., 'Senior Backend Engineer', 'AI Product Manager')
  • Your salary target range

I'll set everything up for you."

Fill in config/profile.yml with their answers. For archetypes and targeting narrative, store the user-specific mapping in modes/_profile.md or config/profile.yml rather than editing modes/_shared.md.

Step 3: Portals (recommended)

If portals.yml is missing:

"I'll set up the job scanner with 45+ pre-configured companies. Want me to customize the search keywords for your target roles?"

Copy templates/portals.example.yml → portals.yml. If they gave target roles in Step 2, update title_filter.positive to match.

Step 4: Tracker

If data/applications.md doesn't exist, create it:

# Applications Tracker

| # | Date | Company | Role | Score | Status | PDF | Report | Notes |
|---|------|---------|------|-------|--------|-----|--------|-------|

Step 5: Get to know the user (important for quality)

After the basics are set up, proactively ask for more context. The more you know, the better your evaluations will be:

"The basics are ready. But the system works much better when it knows you well. Can you tell me more about:

  • What makes you unique? What's your 'superpower' that other candidates don't have?
  • What kind of work excites you? What drains you?
  • Any deal-breakers? (e.g., no on-site, no startups under 20 people, no Java shops)
  • Your best professional achievement — the one you'd lead with in an interview
  • Any projects, articles, or case studies you've published?

The more context you give me, the better I filter. Think of it as onboarding a recruiter — the first week I need to learn about you, then I become invaluable."

Store any insights the user shares in config/profile.yml (under narrative), modes/_profile.md, or in article-digest.md if they share proof points. Do not put user-specific archetypes or framing into modes/_shared.md.

After every evaluation, learn. If the user says "this score is too high, I wouldn't apply here" or "you missed that I have experience in X", update your understanding in modes/_profile.md, config/profile.yml, or article-digest.md. The system should get smarter with every interaction without putting personalization into system-layer files.

Step 6: Ready

Once all files exist, confirm:

"You're all set! You can now:

  • Paste a job URL to evaluate it
  • Run /career-ops scan (or /career-ops-scan if using OpenCode) to search portals
  • Run /career-ops to see all commands

Everything is customizable — just ask me to change anything.

Tip: Having a personal portfolio dramatically improves your job search. If you don't have one yet, the author's portfolio is also open source: github.com/santifer/cv-santiago — feel free to fork it and make it yours."

Then suggest automation:

"Want me to scan for new offers automatically? I can set up a recurring scan every few days so you don't miss anything. Just say 'scan every 3 days' and I'll configure it."

If the user accepts, use the /loop or /schedule skill (if available) to set up a recurring /career-ops scan (or /career-ops-scan if using OpenCode). If those aren't available, suggest adding a cron job or remind them to run /career-ops scan (or /career-ops-scan if using OpenCode) periodically.

Personalization

This system is designed to be customized by YOU (AI Agent). When the user asks you to change archetypes, translate modes, adjust scoring, add companies, or modify negotiation scripts -- do it directly. You read the same files you use, so you know exactly what to edit.

Common customization requests:

  • "Change the archetypes to [backend/frontend/data/devops] roles" → edit modes/_profile.md or config/profile.yml
  • "Translate the modes to English" → edit all files in modes/
  • "Add these companies to my portals" → edit portals.yml
  • "Update my profile" → edit config/profile.yml
  • "Change the CV template design" → edit templates/cv-template.html
  • "Adjust the scoring weights" → edit modes/_profile.md for user-specific weighting, or edit modes/_shared.md and batch/batch-prompt.md only when changing the shared system defaults for everyone

Language Modes

Default modes are in modes/ (English). Additional language-specific modes are available:

  • German (DACH market): modes/de/ — native German translations with DACH-specific vocabulary (13. Monatsgehalt, Probezeit, Kündigungsfrist, AGG, Tarifvertrag, etc.). Includes _shared.md, angebot.md (evaluation), bewerben.md (apply), pipeline.md.
  • French (Francophone market): modes/fr/ — native French translations with France/Belgium/Switzerland/Luxembourg-specific vocabulary (CDI/CDD, convention collective SYNTEC, RTT, mutuelle, prévoyance, 13e mois, intéressement/participation, titres-restaurant, CSE, portage salarial, etc.). Includes _shared.md, offre.md (evaluation), postuler.md (apply), pipeline.md.
  • Japanese (Japan market): modes/ja/ — native Japanese translations with Japan-specific vocabulary (正社員, 業務委託, 賞与, 退職金, みなし残業, 年俸制, 36協定, 通勤手当, 住宅手当, etc.). Includes _shared.md, kyujin.md (evaluation), oubo.md (apply), pipeline.md.
  • Turkish (Turkey market): modes/tr/ — native Turkish translations with Turkey-specific vocabulary (SGK, kıdem tazminatı, ihbar süresi, brüt/net maaş, AGİ, BES, yemek kartı, yol yardımı, TÜFE zammı, etc.). Includes _shared.md, is-ilani.md (evaluation), basvuru.md (apply), pipeline.md.

When to use German modes: If the user is targeting German-language job postings, lives in DACH, or asks for German output. Either:

  1. User says "use German modes" → read from modes/de/ instead of modes/
  2. User sets language.modes_dir: modes/de in config/profile.yml → always use German modes
  3. You detect a German JD → suggest switching to German modes

When to use French modes: If the user is targeting French-language job postings, lives in France/Belgium/Switzerland/Luxembourg/Quebec, or asks for French output. Either:

  1. User says "use French modes" → read from modes/fr/ instead of modes/
  2. User sets language.modes_dir: modes/fr in config/profile.yml → always use French modes
  3. You detect a French JD → suggest switching to French modes

When to use Japanese modes: If the user is targeting Japanese-language job postings, lives in Japan, or asks for Japanese output. Either:

  1. User says "use Japanese modes" → read from modes/ja/ instead of modes/
  2. User sets language.modes_dir: modes/ja in config/profile.yml → always use Japanese modes
  3. You detect a Japanese JD → suggest switching to Japanese modes

When to use Turkish modes: If the user is targeting Turkish-language job postings, lives in Turkey, or asks for Turkish output. Either:

  1. User says "use Turkish modes" → read from modes/tr/ instead of modes/
  2. User sets language.modes_dir: modes/tr in config/profile.yml → always use Turkish modes
  3. You detect a Turkish JD → suggest switching to Turkish modes

When NOT to: If the user applies to English-language roles, even at French, German, Japanese, or Turkish companies, use the default English modes — unless the user has explicitly requested another mode in this conversation, or language.modes_dir is set in config/profile.yml (the explicit user preference always wins over JD-language detection).

Skill Modes

If the user...Mode
Pastes JD or URLauto-pipeline (evaluate + report + PDF + tracker)
Asks to evaluate offeroferta
Asks to compare offersofertas
Wants LinkedIn outreachcontacto
Asks for company researchdeep
Preps for interview at specific companyinterview-prep
Wants to generate CV/PDFpdf
Evaluates a course/certtraining
Evaluates portfolio projectproject
Asks about application statustracker
Fills out application formapply
Searches for new offersscan
Processes pending URLspipeline
Batch processes offersbatch
Asks about rejection patterns or wants to improve targetingpatterns
Asks about follow-ups or application cadencefollowup

CV Source of Truth

  • cv.md in project root is the canonical CV
  • article-digest.md has detailed proof points (optional)
  • NEVER hardcode metrics -- read them from these files at evaluation time

Ethical Use -- CRITICAL

This system is designed for quality, not quantity. The goal is to help the user find and apply to roles where there is a genuine match -- not to spam companies with mass applications.

  • NEVER submit an application without the user reviewing it first. Fill forms, draft answers, generate PDFs -- but always STOP before clicking Submit/Send/Apply. The user makes the final call.
  • Strongly discourage low-fit applications. If a score is below 4.0/5, explicitly recommend against applying. The user's time and the recruiter's time are both valuable. Only proceed if the user has a specific reason to override the score.
  • Quality over speed. A well-targeted application to 5 companies beats a generic blast to 50. Guide the user toward fewer, better applications.
  • Respect recruiters' time. Every application a human reads costs someone's attention. Only send what's worth reading.

Offer Verification -- MANDATORY

NEVER trust WebSearch/WebFetch to verify if an offer is still active. ALWAYS use Playwright:

  1. browser_navigate to the URL
  2. browser_snapshot to read content
  3. Only footer/navbar without JD = closed. Title + description + Apply = active.

Exception for batch workers (headless mode): Playwright is not available in headless pipe mode. Use WebFetch as fallback and mark the report header with **Verification:** unconfirmed (batch mode). The user can verify manually later.


Headless / Batch Mode

When spawning headless workers for batch processing, use the appropriate command for your CLI:

CLICommand
Claude Codeclaude -p "prompt"
Gemini CLIgemini -p "prompt"
Copilot CLIcopilot -p "prompt"
Codexcodex exec "prompt"
OpenCodeopencode run "prompt"
Qwenqwen -p "prompt"

Stack and Conventions

  • Node.js (mjs modules), Playwright (PDF + scraping), YAML (config), HTML/CSS (template), Markdown (data), Canva MCP (optional visual CV)
  • Scripts in .mjs, configuration in YAML
  • Output in output/ (gitignored), Reports in reports/
  • JDs in jds/ (referenced as local:jds/{file} in pipeline.md)
  • Batch in batch/ (gitignored except scripts and prompt)
  • Report numbering: sequential 3-digit zero-padded, max existing + 1
  • RULE: After each batch of evaluations, run node merge-tracker.mjs to merge tracker additions and avoid duplications.
  • RULE: NEVER create new entries in applications.md if company+role already exists. Update the existing entry.

TSV Format for Tracker Additions

Write one TSV file per evaluation to batch/tracker-additions/{num}-{company-slug}.tsv. Single line, 9 tab-separated columns:

{num}\t{date}\t{company}\t{role}\t{status}\t{score}/5\t{pdf_emoji}\t[{num}](reports/{num}-{slug}-{date}.md)\t{note}

Column order (IMPORTANT -- status BEFORE score):

  1. num -- sequential number (integer)
  2. date -- YYYY-MM-DD
  3. company -- short company name
  4. role -- job title
  5. status -- canonical status (e.g., Evaluated)
  6. score -- format X.X/5 (e.g., 4.2/5)
  7. pdf -- ✅ or ❌
  8. report -- markdown link [num](reports/...)
  9. notes -- one-line summary

Note: In applications.md, score comes BEFORE status. The merge script handles this column swap automatically.

Pipeline Integrity

  1. NEVER edit applications.md to ADD new entries -- Write TSV in batch/tracker-additions/ and merge-tracker.mjs handles the merge.
  2. YES you can edit applications.md to UPDATE status/notes of existing entries.
  3. All reports MUST include **URL:** in the header (between Score and PDF). Include **Legitimacy:** {tier} (see Block G in modes/oferta.md).
  4. All statuses MUST be canonical (see templates/states.yml).
  5. Health check: node verify-pipeline.mjs
  6. Normalize statuses: node normalize-statuses.mjs
  7. Dedup: node dedup-tracker.mjs

Canonical States (applications.md)

Source of truth: templates/states.yml

StateWhen to use
EvaluatedReport completed, pending decision
AppliedApplication sent
RespondedCompany responded
InterviewIn interview process
OfferOffer received
RejectedRejected by company
DiscardedDiscarded by candidate or offer closed
SKIPDoesn't fit, don't apply

RULES:

  • No markdown bold (**) in status field
  • No dates in status field (use the date column)
  • No extra text (use the notes column)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.