Getting Started

Every other chapter in this documentation is organised by subject: the rubric in one place, the resume model in another, scheduling in a third. That is the right shape for looking something up, and the wrong shape for the first day, when the question is not “how does scoring work” but “what do I do next.”

This chapter is the order. It carries almost no explanation of its own. Each step says what to run, what you should see, and which chapter explains it, then sends you there.

What you need before you start

The two kinds of command

This trips up everyone once, so it is worth thirty seconds up front. Throughout this page the two are styled differently, so you can always tell which one you are looking at.

$ bash scripts/daily_run.sh

Shell commands start with bash, .venv/bin/python, cp, grep. You run these in a terminal, in the repository directory. They are ordinary scripts.

> /evaluate-job all

Slash commands are not scripts, and there is no file on disk you can execute. They are instructions to an AI agent. Each names a file under skills/, and CLAUDE.md in the repository root is the routing table that maps one to the other. They only do anything inside an agent session opened with this repository as the working directory, which for Claude Code means running claude from this directory.

The split matters beyond typing. The shell half is deterministic: it finds jobs and writes a digest, the same way every morning, with no model involved. The agent half is where judgment lives: grading, tailoring and the writing. You can run the first half alone. The second half without the first has nothing to work on.

At the end of this stage the pipeline works, and everything it says is about a fictional person.

1.1  Get the code

$ git clone https://github.com/Cre8Chaos/job-search-engine.git
$ cd job-search-engine

If you were given the repository under a different owner or name, use that URL instead. Everything after this step assumes your terminal is in the repository directory, and every path in all eleven chapters is relative to it.

1.2  Check your Python, then install

Follow README step 1. It builds the virtualenv, installs requirements and installs the headless browser. Check your Python version first, as that step says: the failure mode for an old version is a syntax error deep inside an import that names nothing useful.

The browser install is not optional-in-practice. It is needed for PDF rendering and for four tests that drive a real browser deliberately. README step 1 gives you the marker to deselect those four if you choose to skip it.

1.3  Copy the example configuration

Follow README step 2. Three cp commands. Do not edit anything yet.

You now have a working configuration belonging to a fictional candidate, which is the point: it lets you prove the machine runs before you have to make any decisions about yourself.

1.4  Run the tests

Follow README step 3, and read what it says about running this after step 1.3 rather than before. The trap it describes is the important part: on a bare clone some tests skip rather than fail, so a green-looking run before you have config files is quietly checking fewer things than it appears to be.

1.5  Run the pipeline once

Follow README step 4.

$ bash scripts/daily_run.sh

This is stages 1 through 6 of the pipeline: scan the configured boards, filter, select, fetch descriptions, write job files, write the digest. No credentials required, no model involved, no application submitted.

config/companies.yaml ships with eight example boards, two for each supported ATS. They exist to prove each adapter works, not as a recommendation, and you will replace them in Stage 2.

1.6  Read what it produced

Open data/digests/<today>.md and read it end to end. Then look at one file in data/jobs/. This is the shape of the thing you will read every morning, so it is worth five minutes now.

README steps 5 and 6 are two verification commands worth running once: one confirms no LinkedIn or Indeed scraping happened, the other confirms nothing was written outside the repository directory.

This is the stage people skip, and skipping it is how you end up with a beautifully engineered digest of jobs that are wrong for you.

Chapter 3 (docs/setup.md) is this stage. Work through it section by section. It is written as an interview rather than a form, because the questions it asks — which towns would you really commute to, what does a good offer look like — are ones only you can answer.

The three inputs nothing can default for you

1. config/profile.yaml — your target roles, location policy, salary band and scoring weights. Sections 1 through 4 of Chapter 3.
2. Your master resumes, config/resume.md and config/resume-ai.md. These are the source of truth for every tailored resume the pipeline ever writes, and they are treated as immutable: no skill in this repository edits them. Every fact in every generated resume has to already exist in one of these files. That constraint is the product. Chapter 3 section 6, and docs/resumes.md for the full model.
3. config/companies.yaml — the employers you actually want scanned. Delete the eight examples. Chapter 9 has a section on adding a company whose board is not on a supported ATS.

Then re-run the test suite and one real pipeline run against your own values, and finish with Chapter 3’s closing checklist, which is the authoritative “you are set up” gate. Do not treat it as a formality. Every line on it is a thing that silently degrades the results if it is false.

This is the loop you repeat.

3.1  Discover

$ bash scripts/daily_run.sh

Same command as step 1.5. New jobs land in data/jobs/ at status New, and the digest lists them. Nothing has been graded yet.

3.2  Judge

Open Claude Code in this directory, then take one of two lanes.

The whole morning at once

> /daily-run

This finishes what the shell run started: evaluates every New job, tailors the A and B grades, runs the QA gate, generates PDFs and rewrites the digest. It stops at status Ready. It is a hard rule of that skill that it never applies to anything.

Or one job at a time

Worth doing manually the first few times, so you can see each stage.

> /evaluate-job all
> /rewrite-resume data/jobs/<file>.md
> /generate-pdf data/jobs/<file>.md

Tailor only A and B grades. That is a rule in the skill, not a suggestion: tailoring a C is work spent on a job the rubric already told you not to take. docs/rubric.md explains the six dimensions behind the letter, and how to recalibrate them when the grades disagree with your gut. Expect to recalibrate. A rubric that has never been argued with is a rubric nobody has checked.

3.3  The gate

Between tailoring and the PDF sits scripts/qa_resume.py, which compares the tailored resume against the master it was tailored from and hard-fails on anything the master does not contain. Chapter 1 of the README is a sixty second demo of it catching a planted fabrication.

/daily-run runs this for you. Going stage by stage, run it yourself between /rewrite-resume and /generate-pdf, passing the same master the resume was tailored from:

$ .venv/bin/python scripts/qa_resume.py data/jobs/<file>.md \
      --master config/resume.md

The **Resume Variant:** line inside the job file names which master that is. Always QA against the master it was tailored from, never the other one. docs/resumes.md covers why this is a hard block rather than a warning.

3.4  Apply

3.5  Record what you did

$ .venv/bin/python scripts/update-pipeline.py update "Company" "Role" \
      --status Applied --date $(date +%F)

Statuses move New → Evaluated → Tailored → Ready → Applied, with Skip and Rejected for the ones that end. data/pipeline.md is the master table, and /pipeline displays and filters it.

Keeping this current is not bookkeeping for its own sake. The outreach engine reads status and dates to work out what follow-up is due, so a stale table quietly stops producing follow-ups.

3.6  Outreach (optional)

> /outreach

Finds a contact, drafts a message and tracks follow-ups. It never sends anything and never invents a person. docs/integrations.md covers the Slack and Gmail pieces, both optional.

> /interview-prep data/jobs/<file>.md --round recruiter

Writes a round-specific prep brief. Run it once per round, and update the pipeline status as things move.

/recruiter-review is worth running once on your master resume, separately from any job. It reads the document the way a screener actually reads it — six seconds, then thirty — and reports what gets ignored. It never edits your master.

Once the daily loop is boring, docs/scheduling.md covers running it unattended on a split cadence. Read that chapter’s section on what unattended running does and does not protect you from before turning it on, and note its point about knowing when a scheduled run did not happen at all.

When something looks wrong

Three checks answer most of it.

1. Did the run happen? data/digests/run-<date>.log exists and ends with a done line.
2. Did it find anything? A zero-job run is usually a board change, not a crash. docs/operations.md has “A board went quiet”.
3. Is it a slash command doing nothing? Confirm you are in an agent session rooted at this repository. See the second section of this page.

Past that, docs/operations.md is organised by symptom rather than by subsystem, which is the right index when you do not yet know what broke. It also documents the rollback convention for getting back to a known-good state.

What you are responsible for

Read docs/rules-and-safety.md (Chapter 10) in full before you rely on this. The short version, which is not a substitute for the chapter:

• It never applies to anything. Every submission is your own act.
• It never invents experience. The QA gate enforces that mechanically, and the gate is the reason the rest is trustworthy. If you find yourself wanting to route around it, that is the moment to reread Chapter 10.
• Real personal data now lives in this directory. Your resume, your salary expectations, your pipeline. The gitignore covers the known files. Check before you push anything anywhere.
• One capability carries real legal risk if you turn it on. Chapter 10 names it and explains what changes. It is off by default.
• Reading a company’s own careers board is not all the same thing. Some of the supported ATSes are genuine API reads and one is a rendered-page read. Chapter 10 says exactly which is which, and what each one’s terms mean for you, since running this is your decision and not the author’s.

Where to go next