job-search-hq
CLAUDE.md1 starsChanged 5 months agoMITView on GitHub
An agent-maintained job-search CRM. A single JSON board is the source of truth, a self-contained static HTML file is the viewer, config files hold the knobs, and a suite of Claude Code skills do the work. No frameworks, zero runtime deps (Python stdlib only; dev/CI tooling may add dev-only deps). - data/vacancies.json — source of truth, a v2 envelope: { "schemaVersion": 2, "vacancies": [ … ] }. Gitignored (real data). The committed demo is data/vacancies.sample.json (synthetic, regenerated by scripts/make_demo.py). scripts/board.py…
In this repository9 other files it gives its agents.
- add-sourceSkill
- add-vacancySkill
- build-profileSkill
- cover-letterSkill
- ingest-cvSkill
- interview-prepSkill
- recheck-statusesSkill
- refresh-listingsSkill
- update-statusSkill
The file
We split this CLAUDE.md into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 45
Pipeline-locked statuses are sacred: Never overwrite applied, hr_screen, tech_interview, final, offer, rejected during a sweep.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.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
Job Search HQ — Claude Code project context
An agent-maintained job-search CRM. A single JSON board is the source of truth, a self-contained static HTML file is the viewer, config files hold the knobs, and a suite of Claude Code skills do the work. No frameworks, zero runtime deps (Python stdlib only; dev/CI tooling may add dev-only deps).
Where things live
data/vacancies.json— source of truth, a v2 envelope:{ "schemaVersion": 2, "vacancies": [ … ] }. Gitignored (real data). The committed demo isdata/vacancies.sample.json(synthetic, regenerated byscripts/make_demo.py).scripts/board.pyis the one place that knows the shape.job-search-hq.html— the viewer. Carries the data + app config baked into<script type="application/json">blocks (sentinel-bounded) sofile://works anywhere. Always baked from the sample — real data only ever lands in the gitignoredjob-search-hq.local.html(viaserve.py).config/—app.json·scoring.json·platforms.json·sources.json. One source of truth per concern;*.local.json(gitignored) overrides merge on top.schema/vacancy.schema.json— the data contract.validate.pychecks against it (via the stdlib mini-validator inscripts/schema_check.py).profile/—candidate.md+profile.json(gitignored real;*.example.*committed) andcv/(gitignored CVs). Read by assessment skills at scoring time.docs/—schema.md,rubric.md(generated bygen_rubric.py),scheduling.md.scripts/—serve.py(live server) ·build.py(validate+bake) ·bake.py·validate.py·score.py·migrate.py·init.py·make_demo.py·gen_rubric.py·board.py·config_util.py·schema_check.py..claude/skills/— the skills (see below).tests/— stdlibunittest.
Conventions
- Single source of truth per concern. Data →
data/. Config →config/. Schema →schema/. Don't duplicate constants across Python/JS/CSS —bake.pyinjects{app, scoring, platforms}into the HTML so the UI can't drift. - Never commit real data. Real
data/vacancies.json,profile/candidate.md,profile/profile.json,profile/cv/*,config/*.local.json, andjob-search-hq.local.htmlare gitignored. Work against the*.sample/*.examplefiles. The committed HTML and the Pages demo are sample-only. - After editing data, run
python3 scripts/build.py --real(validates real data + rebakes the gitignored local snapshot).build.pywith no args rebuilds the committed demo from the sample (what CI's drift check runs). - Score via the script. Pick 5 honest sub-scores per
docs/rubric.md, thenpython3 scripts/score.py compute <tech> <comp> <level> <company> <appeal> [risk]. Weights/tiers come fromconfig/scoring.json. Tier is derived — never hand-set. - Pipeline-locked statuses are sacred. Never overwrite
applied,hr_screen,tech_interview,final,offer,rejectedduring a sweep. altLinksare verified, not synthesised — every URL must return a role-relevant 200.- Escape untrusted text in the viewer (
esc/safeUrl/sanitizeRich);statusDetailis the one field allowed a small formatting-tag allowlist.
Running
Nothing to install. Stdlib only.
- Live (recommended):
python3 scripts/serve.py→http://127.0.0.1:8765/job-search-hq.html. The viewer detects/api/vacanciesand auto-saves every change (atomic write, ETag/409 concurrency guard, schema-validated on PUT). - Read-only: open
job-search-hq.htmlviafile://— the demo renders from the baked block. - Tests:
python3 -m unittest discover -s tests.
Skills overview
| Skill | Purpose |
build-profile | Create/refresh profile/candidate.md + profile.json (interview or parse CV/LinkedIn). |
ingest-cv | Parse a CV in profile/cv/ → structured data linked from the profile. |
add-vacancy | Ingest one URL / bulk list / aggregator → score → append. Honors crossLink. |
refresh-listings | Sweep the sources in config/sources.json (Claude in Chrome) → hand to add-vacancy. |
recheck-statuses | Mark dead postings closed; pipeline-locked statuses stay. |
update-status | Move a role through the pipeline; timestamp statusDetail; offer interview prep. |
interview-prep | Research + build a prep brief → events[].prep. |
cover-letter | Tailored, human-sounding cover letter → coverLetter. |
add-source | Add/edit/disable a source in config/sources.json. |
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.

