claude-works: Instructions file for Claude Code

CLAUDE.md

Claude Works is an MCP server (FastMCP, stdio) exposing a job-application pipeline as typed tools. The honesty policy lives in the modules, not in prompts: hard caps in scoring, gate findings in the resume tools, fill-and-park plans in submission. Do not move policy into docstrings or prompt text.

Companion docs, read before the matching work: PLAYBOOK.md (every per-ATS form-driving lesson; read it before executing a submission plan with Playwright), OPERATING.md (the loop's operating model: queue-first gate, hard walls, de-dup semantics, cadence). To onboard a new candidate end to end, run the bundled /setup command.

Standing rule: append lessons in the same session

When you discover a better way to fill or submit a form (a new ATS, a selector, a validator trick, a submit-blocker), append it to PLAYBOOK.md AND, in terse generic form, to submission.py's ATS_GOTCHAS (tests green, no PII, no em dashes) before the session ends. When a skip reveals a pattern, add it to curation.py's filters. This is how the system remembers; do not wait to be asked.

Commands

pip install -e ".[dev]"          # dev install
ruff check . && mypy && pytest   # the exact checks CI runs (no network needed)
python -m claude_works           # run the server over stdio

Demo mode (all 14 tools work offline, from this clone):

JOBSEARCH_DATA_DIR="$PWD/examples" \
JOBSEARCH_RESUMES_DIR="$PWD/examples/resumes" \
python -m claude_works

Setting it up for a user

Prefer the bundled /setup command: it interviews the user for example jobs + their resume and derives everything below from those examples. The manual outline:

1. pip install claude-works (PyPI) or pip install -e . from a clone.
2. Create a data directory for their search (ledger, queue, and policy live there; empty is fine, readers degrade gracefully).
3. Copy examples/policy.sample.json to <data dir>/policy.json and edit it WITH them: their excluded companies, skill gaps, level terms, scoring vocabulary, curation lanes. The defaults are one specific candidate's policy; never let a new user run on them.
4. Register the server (identity is env-only; nothing personal is in code):