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.
- CLAUDE.mdCLAUDE.md
- career-opsSkill
- career-opsSkill
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
- Very specific: line 36
If yes → run node update-system.mjs apply.
- Distinctive: line 74
Before doing ANYTHING else, check if the system is set up: Run these checks silently every time a session starts:
- Very specific: line 81
If modes/_profile.md is missing, copy from modes/_profile.template.md silently.
- Distinctive: line 83
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.
- Very specific: line 86
If cv.md is missing, ask:
- Very specific: line 94
Create cv.md from whatever they provide.
- Very specific: line 97
If config/profile.yml is missing, copy from config/profile.example.yml and then ask:
- Very specific: line 109
If portals.yml is missing:
- Very specific: line 115
If data/applications.md doesn't exist, create it:
- Distinctive: line 125
After the basics are set up, proactively ask for more context.
- Very specific: line 154
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 …
- Very specific: line 170
Default modes are in modes/ (English).
- Distinctive: line 177
When to use German modes: If the user is targeting German-language job postings, lives in DACH, or asks for German output.
- Very specific: line 182
When to use French modes: If the user is targeting French-language job postings, lives in France/Belgium/Switzerland/Luxembourg/Quebec, or …
- Distinctive: line 187
When to use Japanese modes: If the user is targeting Japanese-language job postings, lives in Japan, or asks for Japanese output.
- Distinctive: line 192
When to use Turkish modes: If the user is targeting Turkish-language job postings, lives in Turkey, or asks for Turkish output.
- Distinctive: line 233
Strongly discourage low-fit applications: If a score is below 4.0/5, explicitly recommend against applying.
- Distinctive: line 235
Respect recruiters' time: Every application a human reads costs someone's attention.
- Distinctive: line 244
Only footer/navbar without JD = closed.
- Distinctive: line 252
When spawning headless workers for batch processing, use the appropriate command for your CLI:
- Very specific: line 276
Write one TSV file per evaluation to batch/tracker-additions/{num}-{company-slug}.tsv.
- Very specific: line 299
All reports MUST include URL: in the header (between Score and PDF).
- Very specific: line 300
All statuses MUST be canonical (see templates/states.yml).
- Very specific: line 321
No markdown bold (``) in status field
- Distinctive: line 322
No dates in status field (use the date column)
- Distinctive: line 323
No extra text (use the notes column)
≈ “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.
Files
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.ymldata/*,reports/*,output/*,interview-prep/*
System Layer (auto-updatable, DON'T put user data here):
modes/_shared.md,modes/oferta.md, all other modesAGENTS.md,CLAUDE.md,*.mjsscripts,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 checkParse 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 → runnode 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
| File | Function |
data/applications.md | Application tracker |
data/pipeline.md | Inbox of pending URLs |
data/scan-history.tsv | Scanner dedup history |
portals.yml | Query and company config |
templates/cv-template.html | HTML template for CVs |
templates/cv-template.tex | LaTeX/Overleaf template for CVs |
generate-pdf.mjs | Playwright: HTML to PDF |
generate-latex.mjs | LaTeX CV validator + pdflatex compiler |
article-digest.md | Compact proof points from portfolio (optional) |
interview-prep/story-bank.md | Accumulated STAR+R stories across evaluations |
interview-prep/{company}-{role}.md | Company-specific interview intel reports |
analyze-patterns.mjs | Pattern analysis script (JSON output) |
followup-cadence.mjs | Follow-up cadence calculator (JSON output) |
data/follow-ups.md | Follow-up history tracker |
scan.mjs | Zero-token portal scanner — hits Greenhouse/Ashby/Lever APIs directly, zero LLM cost |
check-liveness.mjs | Job posting liveness checker |
liveness-core.mjs | Shared 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:
- Does
cv.mdexist? - Does
config/profile.ymlexist (not just profile.example.yml)? - Does
modes/_profile.mdexist (not just _profile.template.md)? - Does
portals.ymlexist (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:
- Paste your CV here and I'll convert it to markdown
- Paste your LinkedIn URL and I'll extract the key info
- 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-scanif using OpenCode) to search portals- Run
/career-opsto see all commandsEverything 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.mdorconfig/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.mdfor user-specific weighting, or editmodes/_shared.mdandbatch/batch-prompt.mdonly 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:
- User says "use German modes" → read from
modes/de/instead ofmodes/ - User sets
language.modes_dir: modes/deinconfig/profile.yml→ always use German modes - 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:
- User says "use French modes" → read from
modes/fr/instead ofmodes/ - User sets
language.modes_dir: modes/frinconfig/profile.yml→ always use French modes - 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:
- User says "use Japanese modes" → read from
modes/ja/instead ofmodes/ - User sets
language.modes_dir: modes/jainconfig/profile.yml→ always use Japanese modes - 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:
- User says "use Turkish modes" → read from
modes/tr/instead ofmodes/ - User sets
language.modes_dir: modes/trinconfig/profile.yml→ always use Turkish modes - 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 URL | auto-pipeline (evaluate + report + PDF + tracker) |
| Asks to evaluate offer | oferta |
| Asks to compare offers | ofertas |
| Wants LinkedIn outreach | contacto |
| Asks for company research | deep |
| Preps for interview at specific company | interview-prep |
| Wants to generate CV/PDF | pdf |
| Evaluates a course/cert | training |
| Evaluates portfolio project | project |
| Asks about application status | tracker |
| Fills out application form | apply |
| Searches for new offers | scan |
| Processes pending URLs | pipeline |
| Batch processes offers | batch |
| Asks about rejection patterns or wants to improve targeting | patterns |
| Asks about follow-ups or application cadence | followup |
CV Source of Truth
cv.mdin project root is the canonical CVarticle-digest.mdhas 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:
browser_navigateto the URLbrowser_snapshotto read content- 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:
| CLI | Command |
| Claude Code | claude -p "prompt" |
| Gemini CLI | gemini -p "prompt" |
| Copilot CLI | copilot -p "prompt" |
| Codex | codex exec "prompt" |
| OpenCode | opencode run "prompt" |
| Qwen | qwen -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 inreports/ - JDs in
jds/(referenced aslocal: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.mjsto 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):
num-- sequential number (integer)date-- YYYY-MM-DDcompany-- short company namerole-- job titlestatus-- canonical status (e.g.,Evaluated)score-- formatX.X/5(e.g.,4.2/5)pdf--✅or❌report-- markdown link[num](reports/...)notes-- one-line summary
Note: In applications.md, score comes BEFORE status. The merge script handles this column swap automatically.
Pipeline Integrity
- NEVER edit applications.md to ADD new entries -- Write TSV in
batch/tracker-additions/andmerge-tracker.mjshandles the merge. - YES you can edit applications.md to UPDATE status/notes of existing entries.
- All reports MUST include
**URL:**in the header (between Score and PDF). Include**Legitimacy:** {tier}(see Block G inmodes/oferta.md). - All statuses MUST be canonical (see
templates/states.yml). - Health check:
node verify-pipeline.mjs - Normalize statuses:
node normalize-statuses.mjs - Dedup:
node dedup-tracker.mjs
Canonical States (applications.md)
Source of truth: templates/states.yml
| State | When to use |
Evaluated | Report completed, pending decision |
Applied | Application sent |
Responded | Company responded |
Interview | In interview process |
Offer | Offer received |
Rejected | Rejected by company |
Discarded | Discarded by candidate or offer closed |
SKIP | Doesn'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)
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
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.

