⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

open-to-work

rwtibbs@rwtibbs⭐ 8 stars· last commit 4mo ago· 0 open issues

A complete, self-contained job-search pipeline for ANY user. Onboards once — building resume, fact pack, voice, and styling files from a resume, LinkedIn/portfolio, or quick interview. After that it tailors your resume to any job (truthfully, never fabricating), builds a one-page DOCX + PDF, runs an ATS scoring loop twice, writes a cover letter in your voice, answers application questions, and can fill/upload the form in the browser. Scans job boards on a schedule, preps for interviews (prep kit, mock, debrief), drafts outreach to recruiters or hiring managers, and tracks every application in a standing pipeline ledger with follow-ups, thank-yous, and offer-negotiation help — all feeding one self-improving library. Use for anything job-search related — onboarding, tailoring, cover letters, ATS scoring, applying, scanning, interview prep or debrief, outreach, tracking applications, negotiating offers, or any time they paste a job posting. If there's a chance this is a job-search task, load it.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 8 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Open to Work

A complete job-search pipeline as a single Claude skill.

Scan boards, tailor your resume, score it against the ATS, write the cover letter, fill the application, prep for the interview, debrief it, reach out to the recruiter — all tracked in a standing ledger. You stay in the loop; the skill does the legwork.

→ opentowork.tools


Quick start

  1. Download open-to-work.skill
  2. Install it in Claude Cowork or Claude Code (Settings → Capabilities → Install skill, or drop it in your skills directory)
  3. Run python3 scripts/selfcheck.py to confirm dependencies
  4. Say: "Start my job search"

Onboarding handles everything else.


Where it runs

The full system needs Claude Cowork or Claude Code — a persistent filesystem (so your library survives between sessions) and a shell (to run the bundled scripts). A plain claude.ai chat can talk strategy but can't save a library or produce real files.

Dependencies: Python 3.8+, python-docx, LibreOffice (PDF export), and poppler (pdfinfo/pdftotext — pypdf auto-fallback if absent). The job scanner is pure standard library. The Claude for Chrome extension powers the logged-in LinkedIn/Wellfound browser pass and application fill/upload; onboarding walks you through it.


What's in the box

open-to-work/
├── SKILL.md                              # orchestrator (onboard + run + scan + prep + outreach)
├── scripts/
│   ├── generate_resume.py                # resume markdown → polished one-page .docx
│   ├── export_pdf.py                     # .docx → .pdf via LibreOffice
│   ├── page_count.py                     # page-length guard; prints overflow
│   ├── build_cover_letter.py             # cover-letter markdown → matching .docx
│   ├── job_scanner.py                    # config-driven scanner: broad discovery + watchlist
│   ├── lint_copy.py                      # AI-tell + ATS parse-safety linter
│   └── selfcheck.py                      # verify deps + scanner logic after install/edits
├── references/
│   ├── onboarding-interview.md           # Quick (~5 min) + Thorough (~20 min) question sets
│   ├── profile-template.json
│   ├── base_resume-template.md
│   ├── fact-pack-template.md
│   ├── voice-template.md
│   ├── format-template.json
│   ├── writing-standards.md              # house style: the structural AI tells to avoid
│   ├── cover-letter-playbook.md          # opener hierarchy, anti-staccato, truthfulness rules
│   ├── ats-rubric.md                     # self-contained ATS scorer
│   ├── browser-autofill.md               # Claude-in-Chrome fill/upload procedure
│   ├── interview-prep.md                 # prep kit, mock interview, transcript debrief
│   ├── outreach-playbook.md              # tier-gated recruiter/HM outreach
│   ├── application-tracker.md            # standing pipeline ledger (applications.json)
│   ├── followup-and-negotiation.md       # thank-yous, status nudges, offer negotiation
│   ├── scheduling.md                     # recurring scan setup + unattended run flow
│   ├── scanner_config.template.json
│   └── scanner-scheduled-task.template.md
└── user-library/
    └── NOT_ONBOARDED.md                  # first-run marker; replaced during onboarding

How the loop works

1. Onboard once

The first time you talk about your job search, it opens with a short overview then kicks off onboarding to build your personal user-library. You choose the depth:

  • Quick (~5 min) — upload your resume; it parses and asks only the gaps.
  • Thorough (~20 min) — a guided interview for a richer fact pack and sharper voice capture.

You can start from an uploaded resume, a pasted LinkedIn/portfolio, or pure Q&A. It produces your profile.json, base_resume.md, fact-pack.md, voice.md, and format.json, reads them back to confirm, and you're set.

2. Target a role

Paste a job description (full text — a URL alone isn't enough) and say something like "tailor my resume for this." It will:

  1. Tailor your resume to the role — truthfully, never inventing experience.
  2. Build the one-page DOCX and a matching PDF.
  3. Run an ATS scoring loop twice, implementing only truthful fixes and reporting the gaps it deliberately didn't fake.
  4. Write a cover letter in your voice and answer any open-ended application questions, coordinated so your stories don't repeat.
  5. Optionally fill and upload the application in your browser, stopping at the final Submit for your review.

3. Scan automatically

Set up job scanning during onboarding (or any time). Give it your target roles, levels, locations, comp floor, recency window, role shape, priority domains, and an optional company watchlist.

The scanner does broad market discovery across keyless remote-job aggregators (Remotive, RemoteOK, Arbeitnow, Jobicy; Adzuna optional) plus the optional Greenhouse/Lever/Ashby watchlist. It scores in two stages: a cheap card-level pass rules out obvious mismatches; only promising cards get the full JD fetched and re-scored. LinkedIn and Wellfound are covered via a logged-in browser pass (Claude for Chrome extension).

Run on demand or schedule it (default: twice daily). Each scan surfaces a ranked shortlist of new matching roles — deduped so nothing repeats — and you can drop any one straight into the tailoring pipeline.

4. Stay in the loop after you apply

  • Prep and practice — when you land an interview, it builds a tailored prep kit and runs a live mock, then debriefs the real interview from a transcript (Meetily recommended) and feeds the lessons back into your library.
  • Reach out — on strong-fit roles it helps you find the recruiter or hiring manager and drafts a short note in your voice. Tier-gated; never auto-sent.
  • Track everything — a standing ledger (user-library/applications.json) records what you applied to, reached out on, and interviewed for. Ask "what's still open?" and get a real answer.

Privacy

All of your personal data — resume, fact pack, voice, contact details, form answers, and job-search history — lives in your own user-library/ files, on your machine. The skill ships with only empty templates and a first-run marker. Your information isn't embedded in the skill and isn't shared by installing or distributing it. Pass the .skill file to someone else and they get the machinery; they onboard themselves into their own library.


License

MIT

// HOW IT'S BUILT

// FILES

33 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md59 KB8a14d5e096c7truncatedupstream ↗

    Showing the inlined prefix. The rest is in the upstream file.

    ---
    name: open-to-work
    description: A complete, self-contained job-search pipeline for ANY user. Onboards once — building resume, fact pack, voice, and styling files from a resume, LinkedIn/portfolio, or quick interview. After that it tailors your resume to any job (truthfully, never fabricating), builds a one-page DOCX + PDF, runs an ATS scoring loop twice, writes a cover letter in your voice, answers application questions, and can fill/upload the form in the browser. Scans job boards on a schedule, preps for interviews (prep kit, mock, debrief), drafts outreach to recruiters or hiring managers, and tracks every application in a standing pipeline ledger with follow-ups, thank-yous, and offer-negotiation help — all feeding one self-improving library. Use for anything job-search related — onboarding, tailoring, cover letters, ATS scoring, applying, scanning, interview prep or debrief, outreach, tracking applications, negotiating offers, or any time they paste a job posting. If there's a chance this is a job-search task, load it.
    ---
    
    # Open To Work
    
    A full job-search loop in one self-contained skill: **scan → shortlist → tailor →
    ATS-score → cover letter + application answers → browser fill/upload.** It works
    for *any* user because all personal content lives in the user's own
    **`user-library/`** files, which the skill builds during onboarding. Nothing about
    any specific person is hardcoded.
    
    There are four entry paths. Pick based on the request and on whether the user is
    already onboarded.
    
    - **A. ONBOARDING** — builds the user-library. Runs on first use, or when the user
      says "set me up / onboard me / customize me", or whenever the user-library is
      missing or empty.
    - **B. RUN** — the tailor-and-apply pipeline for a specific job. Runs once the
      user-library exists and the user brings a job description (or picks one from a
      scan).
    - **C. PREP** — interview preparation for a role the user already applied to (or is
      about to interview for), plus **post-interview debrief** that grades a real interview
      transcript against the prep and feeds the lessons back. Runs when the user says they
      "got an interview", asks to "prep", "practice", or "get ready" — or afterward,
      "debrief that interview / how did I do / review my interview". Best invoked **in the
      same chat where the application was built** — the strategy doc and JD are already in
      context — but works standalone too. See **C. PREP** below.
    - **D. OUTREACH** — a direct, personal note (email or LinkedIn) to the recruiter or
      hiring manager, to pull a strong application out of the pile. Runs when the user
      asks to "reach out", "email the hiring manager/recruiter", "find their email", or
      do "cold outreach" — and is **offered proactively at the end of a strong tier-1
      RUN**. Gated to genuinely strong-fit roles. See **D. OUTREACH** below.
    
    ## The one rule that overrides everything
    
    **Never fabricate experience.** Every word on the resume, in the cover letter, and
    in the application answers must trace to the user's real background as recorded in
    their `user-library/fact-pack.md` and `base_resume.md`, or to something they say in
    the conversation. Tailoring means *reordering, reframing, and resurfacing* real
    experience to match a role — never inventing employers, titles, metrics, skills,
    tools, or projects. When the ATS step asks for something the user can't truthfully
    claim, you do not add it; you flag it. A higher score earned by a lie is worthless
    and collapses in an interview.
    
    ## Everything you write follows the house writing standard
    
    All copy this kit produces — résumé bullets, the cover letter, application answers,
    outreach notes, prep-kit framing — should read like the user wrote it, not like an AI.
    **`references/writing-standards.md`** is the advisory house style: the structural tells
    of machine-written prose (anaphora, the "not X, it's Y" false-negative, antithesis,
    asyndeton, rhetorical-question transitions, clever comparative endings, staccato
    fragments), the positive habits that read as human, and how the standard flexes by
    format (a résumé bullet is terse and fragment-normal; a cover letter flows). Hold it in
    mind *while drafting* so output adheres by construction — it's a writing habit, not a
    post-hoc scoring gate. It never overrides the two rules above it: `voice.md` (the user's
    actual voice) wins any conflict, and nothing it suggests excuses fabricating.
    
    ## The library is a living system — improve it on every pass
    
    The user-library is not a static file you only read. It's a **self-improving record**
    that should get richer and more accurate every time the user works with the kit. The
    truthfulness rule and the enrichment habit are two sides of the same coin: you never
    *invent* a fact to fill a gap, but you always *capture* a real one when it surfaces.
    
    Across **every mode**, stay alert for material that belongs in the library but isn't
    there yet, and for entries that have gone stale:
    
    - a **real metric** the user mentions in chat that a fact-pack bullet was missing;
    - a **story** they tell (a conflict, a failure, a 0→1 win) not yet in `fact-pack.md`;
    - a **new role, title, or tool** they reference that post-dates the base resume;
    - a **recurring hard-gap** worth noting as a standing pattern, or one that's now
      *closed* because they've gained the experience;
    - a **refined preference** (a domain they're done with, a role shape they keep
      picking) that should update `scanner_config.json`;
    - a **gap with no prepared framing** that prep should add.
    
    **How to capture, safely:**
    
    1. **Only ever record what the user actually stated or confirmed.** Never infer a fact
       into the library to make an answer or score better. A fillable gap (a missing
       number the user knows) → ask. A genuine gap (no domain experience) → leave it
       logged as-is; don't nag about what can't truthfully change.
    2. **Batch it at the end, never mid-task.** Don't interrupt a tailoring or prep flow
       to do bookkeeping. Collect candidate additions and handle them in the close-out
       step of each mode.
    3. **Respect the enrichment mode** in `profile.json → library_enrichment.mode`:
       - **`confirm`** (default) — list the candidate additions at the end and ask before
         writing anything. Trust comes first; the user should always know what's in their
         library.
       - **`silent`** — auto-write the clearly-true, unambiguous additions, then briefly
         note what you saved ("added that 40% metric to your Zoom entry"). Still pause to
         confirm genuinely ambiguous ones. The never-fabricate rule is absolute in both
         modes.
    4. **Keep `base_resume.md` clean.** Enrich it only with confirmed durable facts (a new
       role, a real metric) — never with role-specific tailoring from a single RUN.
    
    ## Track the pipeline — one standing ledger
    
    Where the library captures *who the user is*, the **`user-library/applications.json`**
    ledger captures *where every role stands* — applied, reached out, interviewing, heard
    back — and what's owed next. Every mode updates it in its close-out (RUN logs an
    application, OUTREACH logs a note, PREP logs an interview, the debrief logs the outcome),
    so the user can ask "what's still open?" or "who do I owe a follow-up?" and get a real
    answer. The full schema and the per-mode update rules are in
    **`references/application-tracker.md`**. It's the same discipline as the library: agent-
    maintained plain JSON, written at close-out (not mid-task), under `library_enrichment.mode`,
    recording only what actually happened. Thank-yous, status nudges, and offer-negotiation
    briefs hang off it — see **`references/followup-and-negotiation.md`**.
    
    ## This skill needs Cowork or Claude Code — not a plain chat
    
    **The full system only works in an environment with a persistent filesystem, a shell,
    and (for the power features) scheduled tasks and browser control — i.e. Claude Cowork
    or Claude Code.** This is not optional polish; several core pieces silently fail
    without it, and a user who runs this in a regular cl
  • README.md6.6 KB1a65fe082f54upstream ↗
    # Open to Work
    
    **A complete job-search pipeline as a single Claude skill.**
    
    Scan boards, tailor your resume, score it against the ATS, write the cover letter, fill the application, prep for the interview, debrief it, reach out to the recruiter — all tracked in a standing ledger. You stay in the loop; the skill does the legwork.
    
    → **[opentowork.tools](https://opentowork.tools)**
    
    ---
    
    ## Quick start
    
    1. Download [`open-to-work.skill`](files/open-to-work.skill)
    2. Install it in **Claude Cowork** or **Claude Code** (Settings → Capabilities → Install skill, or drop it in your skills directory)
    3. Run `python3 scripts/selfcheck.py` to confirm dependencies
    4. Say: *"Start my job search"*
    
    Onboarding handles everything else.
    
    ---
    
    ## Where it runs
    
    The full system needs **Claude Cowork or Claude Code** — a persistent filesystem (so your library survives between sessions) and a shell (to run the bundled scripts). A plain claude.ai chat can talk strategy but can't save a library or produce real files.
    
    **Dependencies:** Python 3.8+, `python-docx`, LibreOffice (PDF export), and poppler (`pdfinfo`/`pdftotext` — `pypdf` auto-fallback if absent). The job scanner is pure standard library. The **Claude for Chrome extension** powers the logged-in LinkedIn/Wellfound browser pass and application fill/upload; onboarding walks you through it.
    
    ---
    
    ## What's in the box
    
    ```
    open-to-work/
    ├── SKILL.md                              # orchestrator (onboard + run + scan + prep + outreach)
    ├── scripts/
    │   ├── generate_resume.py                # resume markdown → polished one-page .docx
    │   ├── export_pdf.py                     # .docx → .pdf via LibreOffice
    │   ├── page_count.py                     # page-length guard; prints overflow
    │   ├── build_cover_letter.py             # cover-letter markdown → matching .docx
    │   ├── job_scanner.py                    # config-driven scanner: broad discovery + watchlist
    │   ├── lint_copy.py                      # AI-tell + ATS parse-safety linter
    │   └── selfcheck.py                      # verify deps + scanner logic after install/edits
    ├── references/
    │   ├── onboarding-interview.md           # Quick (~5 min) + Thorough (~20 min) question sets
    │   ├── profile-template.json
    │   ├── base_resume-template.md
    │   ├── fact-pack-template.md
    │   ├── voice-template.md
    │   ├── format-template.json
    │   ├── writing-standards.md              # house style: the structural AI tells to avoid
    │   ├── cover-letter-playbook.md          # opener hierarchy, anti-staccato, truthfulness rules
    │   ├── ats-rubric.md                     # self-contained ATS scorer
    │   ├── browser-autofill.md               # Claude-in-Chrome fill/upload procedure
    │   ├── interview-prep.md                 # prep kit, mock interview, transcript debrief
    │   ├── outreach-playbook.md              # tier-gated recruiter/HM outreach
    │   ├── application-tracker.md            # standing pipeline ledger (applications.json)
    │   ├── followup-and-negotiation.md       # thank-yous, status nudges, offer negotiation
    │   ├── scheduling.md                     # recurring scan setup + unattended run flow
    │   ├── scanner_config.template.json
    │   └── scanner-scheduled-task.template.md
    └── user-library/
        └── NOT_ONBOARDED.md                  # first-run marker; replaced during onboarding
    ```
    
    ---
    
    ## How the loop works
    
    ### 1. Onboard once
    
    The first time you talk about your job search, it opens with a short overview then kicks off onboarding to build your personal **user-library**. You choose the depth:
    
    - **Quick (~5 min)** — upload your resume; it parses and asks only the gaps.
    - **Thorough (~20 min)** — a guided interview for a richer fact pack and sharper voice capture.
    
    You can start from an uploaded resume, a pasted LinkedIn/portfolio, or pure Q&A. It produces your `profile.json`, `base_resume.md`, `fact-pack.md`, `voice.md`, and `format.json`, reads them back to confirm, and you're set.
    
    ### 2. Target a role
    
    Paste a job description (full text — a URL alone isn't enough) and say something like *"tailor my resume for this."* It will:
    
    1. Tailor your resume to the role — truthfully, never inventing experience.
    2. Build the one-page DOCX and a matching PDF.
    3. Run an ATS scoring loop **twice**, implementing only truthful fixes and reporting the gaps it deliberately didn't fake.
    4. Write a cover letter in your voice and answer any open-ended application questions, coordinated so your stories don't repeat.
    5. Optionally fill and upload the application in your browser, stopping at the final Submit for your review.
    
    ### 3. Scan automatically
    
    Set up job scanning during onboarding (or any time). Give it your target roles, levels, locations, comp floor, recency window, role shape, priority domains, and an optional company watchlist.
    
    The scanner does **broad market discovery** across keyless remote-job aggregators (Remotive, RemoteOK, Arbeitnow, Jobicy; Adzuna optional) plus the optional Greenhouse/Lever/Ashby watchlist. It scores in two stages: a cheap card-level pass rules out obvious mismatches; only promising cards get the full JD fetched and re-scored. LinkedIn and Wellfound are covered via a logged-in browser pass (Claude for Chrome extension).
    
    Run on demand or schedule it (default: twice daily). Each scan surfaces a ranked shortlist of **new** matching roles — deduped so nothing repeats — and you can drop any one straight into the tailoring pipeline.
    
    ### 4. Stay in the loop after you apply
    
    - **Prep and practice** — when you land an interview, it builds a tailored prep kit and runs a live mock, then debriefs the real interview from a transcript (Meetily recommended) and feeds the lessons back into your library.
    - **Reach out** — on strong-fit roles it helps you find the recruiter or hiring manager and drafts a short note in your voice. Tier-gated; never auto-sent.
    - **Track everything** — a standing ledger (`user-library/applications.json`) records what you applied to, reached out on, and interviewed for. Ask *"what's still open?"* and get a real answer.
    
    ---
    
    ## Privacy
    
    All of your personal data — resume, fact pack, voice, contact details, form answers, and job-search history — lives in **your own `user-library/` files**, on your machine. The skill ships with only empty templates and a first-run marker. Your information isn't embedded in the skill and isn't shared by installing or distributing it. Pass the `.skill` file to someone else and they get the machinery; they onboard themselves into their own library.
    
    ---
    
    ## License
    
    MIT
    
  • scripts/build_cover_letter.py7.7 KBbddb63946867upstream ↗
    #!/usr/bin/env python3
    """
    build_cover_letter.py — Render a cover letter to a polished .docx whose
    letterhead matches the resume. NO personal data and NO styling is hardcoded:
    the name font, body font, and accent color come from format.json (the same file
    the resume uses), and the contact identity comes from the letter's frontmatter
    (or profile.json). Swap those and the letterhead matches whoever's applying.
    
    WHY THIS EXISTS: the cover letter and resume go in the same envelope, so they
    must look like they came from the same person. Reusing the resume's design tokens
    keeps them a matched set. Do NOT hand-write raw .docx or re-derive the styling.
    
    The PROSE is not this script's job. The model writes the letter (in the user's
    voice, per the skill) and saves it as markdown; this only renders that markdown.
    
    INPUT markdown format:
        ---
        name: Jane Doe
        location: City, ST
        email: [email protected]
        phone: (555) 123-4567
        website: example.com        # display text; link target is website_url below
        website_url: https://example.com/   # optional explicit link target
        date: June 2026             # optional
        salutation: Dear Hiring Team,   # optional
        signature: Jane Doe         # optional, defaults to name
        ---
    
        First paragraph...
    
        Second paragraph...
    
    Usage:
        python build_cover_letter.py --input coverletter_<company>.md \
            --output "CoverLetter_<Name>_<Company>.docx" \
            --format ../user-library/format.json --profile ../user-library/profile.json
    """
    import argparse
    import json
    import os
    import sys
    
    try:
        from docx import Document
        from docx.shared import Pt, Inches, RGBColor
        from docx.oxml.ns import qn
        from docx.oxml import OxmlElement
    except ImportError:
        sys.stderr.write(
            "ERROR: python-docx is not installed — the cover-letter builder needs it.\n"
            "Install it with:  pip install python-docx\n"
            "(Run scripts/selfcheck.py to verify all dependencies at once.)\n"
        )
        sys.exit(3)
    
    # Defaults — overwritten from format.json so the letter matches the resume.
    TEXT  = RGBColor(0x1A, 0x1A, 0x1A)
    MUTED = RGBColor(0x6B, 0x6B, 0x6B)
    LINK_HEX = "175DC9"
    FONT = "Calibri"
    NAME_FONT = "Canela Text"
    
    
    def _hex_to_rgb(h):
        h = h.lstrip("#")
        return RGBColor(int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))
    
    
    def load_json(path):
        if path and os.path.exists(path):
            with open(path) as f:
                return json.load(f)
        return {}
    
    
    def apply_format(fmt):
        global TEXT, MUTED, LINK_HEX, FONT, NAME_FONT
        if fmt.get("text_color"):
            TEXT = _hex_to_rgb(fmt["text_color"])
        if fmt.get("muted_color"):
            MUTED = _hex_to_rgb(fmt["muted_color"])
        if fmt.get("accent_color"):
            LINK_HEX = fmt["accent_color"].lstrip("#").upper()
        if fmt.get("body_font"):
            FONT = fmt["body_font"]
        if fmt.get("name_font"):
            NAME_FONT = fmt["name_font"]
    
    
    def _run(p, text, size_pt, bold=False, italic=False, color=None, font=None):
        r = p.add_run(text)
        r.font.name = font or FONT
        r.font.size = Pt(size_pt)
        r.bold = bold
        r.italic = italic
        if color:
            r.font.color.rgb = color
        return r
    
    
    def _fmt(p, space_before=0, space_after=0, line_spacing_pt=None, alignment=None):
        pf = p.paragraph_format
        pf.space_before = Pt(space_before)
        pf.space_after = Pt(space_after)
        if line_spacing_pt:
            pf.line_spacing = Pt(line_spacing_pt)
        if alignment is not None:
            p.alignment = alignment
    
    
    def _add_link(paragraph, text, url, size_pt=9):
        """Accent-colored underlined hyperlink — same treatment as the resume."""
        r_id = paragraph.part.relate_to(
            url,
            "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink",
            is_external=True,
        )
        hl = OxmlElement("w:hyperlink")
        hl.set(qn("r:id"), r_id)
        run_elem = OxmlElement("w:r")
        rPr = OxmlElement("w:rPr")
        rFonts = OxmlElement("w:rFonts")
        rFonts.set(qn("w:ascii"), FONT)
        rFonts.set(qn("w:hAnsi"), FONT)
        rPr.append(rFonts)
        sz = OxmlElement("w:sz")
        sz.set(qn("w:val"), str(int(size_pt * 2)))
        rPr.append(sz)
        clr = OxmlElement("w:color")
        clr.set(qn("w:val"), LINK_HEX)
        rPr.append(clr)
        u = OxmlElement("w:u")
        u.set(qn("w:val"), "single")
        rPr.append(u)
        run_elem.append(rPr)
        t = OxmlElement("w:t")
        t.text = text
        t.set(qn("xml:space"), "preserve")
        run_elem.append(t)
        hl.append(run_elem)
        paragraph._p.append(hl)
    
    
    def parse(filepath):
        with open(filepath, "r") as f:
            text = f.read()
        fm, body = {}, text
        if text.startswith("---"):
            end = text.index("---", 3)
            for line in text[3:end].strip().split("\n"):
                if ":" in line:
                    k, v = line.split(":", 1)
                    fm[k.strip()] = v.strip()
            body = text[end + 3:].strip()
        paras = [p.strip().replace("\n", " ") for p in body.split("\n\n") if p.strip()]
        return fm, paras
    
    
    def build(fm, paragraphs, profile=None):
        profile = profile or {}
        doc = Document()
        sec = doc.sections[0]
        sec.page_width = Inches(8.5)
        sec.page_height = Inches(11)
        sec.top_margin = Inches(0.8)
        sec.bottom_margin = Inches(0.8)
        sec.left_margin = Inches(1.0)
        sec.right_margin = Inches(1.0)
    
        normal = doc.styles["Normal"]
        normal.font.name = FONT
        normal.paragraph_format.space_before = Pt(0)
        normal.paragraph_format.space_after = Pt(0)
    
        def g(key):
            return fm.get(key, profile.get(key, ""))
    
        name = g("name")
        website = g("website")
        website_url = fm.get("website_url") or profile.get("website_url") or (
            ("https://" + website) if website else "")
    
        # Header — name in the display font, then the muted contact line.
        np = doc.add_paragraph()
        _fmt(np, space_before=0, space_after=2)
        _run(np, name, size_pt=20, color=TEXT, font=NAME_FONT)
    
        cp = doc.add_paragraph()
        _fmt(cp, space_before=0, space_after=0)
        contact = "  ·  ".join(x for x in [g("location"), g("email"), g("phone")] if x)
        _run(cp, contact + ("  ·  " if website else ""), size_pt=9, color=MUTED)
        if website and website_url:
            _add_link(cp, website, website_url, size_pt=9)
        elif website:
            _run(cp, website, size_pt=9, color=MUTED)
    
        if fm.get("date"):
            dp = doc.add_paragraph()
            _fmt(dp, space_before=14, space_after=0)
            _run(dp, fm["date"], size_pt=10.5, color=MUTED)
    
        if fm.get("salutation"):
            sp = doc.add_paragraph()
            _fmt(sp, space_before=14, space_after=0, line_spacing_pt=15)
            _run(sp, fm["salutation"], size_pt=10.5, color=TEXT)
    
        for i, para in enumerate(paragraphs):
            bp = doc.add_paragraph()
            _fmt(bp, space_before=10 if (i > 0 or fm.get("salutation")) else 14,
                 space_after=0, line_spacing_pt=15)
            _run(bp, para, size_pt=10.5, color=TEXT)
    
        sig = doc.add_paragraph()
        _fmt(sig, space_before=14, space_after=0)
        _run(sig, fm.get("signature", name), size_pt=10.5, color=TEXT)
        return doc
    
    
    if __name__ == "__main__":
        ap = argparse.ArgumentParser(description="Render a cover letter .docx")
        ap.add_argument("--input", required=True)
        ap.add_argument("--output", required=True)
        ap.add_argument("--format", default=None, help="Path to format.json")
        ap.add_argument("--profile", default=None, help="Path to profile.json")
        args = ap.parse_args()
    
        fmt = load_json(args.format)
        if fmt:
            apply_format(fmt)
        profile = load_json(args.profile)
    
        fm, paragraphs = parse(args.input)
        if not paragraphs:
            print("ERROR: no body paragraphs found in input markdown", file=sys.stderr)
            sys.exit(1)
        doc = build(fm, paragraphs, profile=profile)
        doc.save(args.output)
        print(f"Saved -> {args.output}")
    
  • scripts/export_pdf.py2.2 KBd7b93b0be9bcupstream ↗
    #!/usr/bin/env python3
    """
    export_pdf.py — Deterministic DOCX -> PDF export via LibreOffice headless.
    
    This is the sanctioned way to produce the PDF for a generated resume or cover
    letter. LibreOffice (soffice) renders the .docx faithfully — same fonts, layout,
    and links the recruiter will open. Do NOT reach for pypdf/reportlab/docx2pdf;
    those re-render and drift from the Word file.
    
    Usage:
        python export_pdf.py /path/to/Resume_<Name>_<Company>.docx
        python export_pdf.py <docx> --outdir /path/to/dir   # defaults to docx's dir
    
    Exit code 0 on success (prints the PDF path), non-zero on failure.
    """
    import argparse
    import os
    import shutil
    import subprocess
    import sys
    
    
    def find_soffice():
        for name in ("soffice", "libreoffice"):
            path = shutil.which(name)
            if path:
                return path
        mac = "/Applications/LibreOffice.app/Contents/MacOS/soffice"
        if os.path.exists(mac):
            return mac
        return None
    
    
    def export(docx_path, outdir=None):
        docx_path = os.path.abspath(docx_path)
        if not os.path.exists(docx_path):
            print(f"ERROR: docx not found: {docx_path}", file=sys.stderr)
            return None
        outdir = os.path.abspath(outdir) if outdir else os.path.dirname(docx_path)
    
        soffice = find_soffice()
        if not soffice:
            print("ERROR: LibreOffice (soffice/libreoffice) not found on PATH.", file=sys.stderr)
            return None
    
        pdf_path = os.path.join(
            outdir, os.path.splitext(os.path.basename(docx_path))[0] + ".pdf"
        )
    
        # Two attempts: LibreOffice headless can no-op on the first cold start.
        for _ in range(2):
            subprocess.run(
                [soffice, "--headless", "--convert-to", "pdf", "--outdir", outdir, docx_path],
                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
            )
            if os.path.exists(pdf_path):
                print(pdf_path)
                return pdf_path
        print(f"ERROR: conversion produced no PDF at {pdf_path}", file=sys.stderr)
        return None
    
    
    if __name__ == "__main__":
        ap = argparse.ArgumentParser(description="Convert a .docx to .pdf via LibreOffice")
        ap.add_argument("docx")
        ap.add_argument("--outdir", default=None)
        args = ap.parse_args()
        result = export(args.docx, args.outdir)
        sys.exit(0 if result else 1)
    
  • scripts/generate_resume.py20 KBb0111ef80a5bupstream ↗
    #!/usr/bin/env python3
    """
    generate_resume.py — Parse a resume markdown file and produce a polished
    single-column .docx. Fully parametrized: NO personal data and NO letterhead
    styling is hardcoded. Identity (name, contact, portfolio link) comes from the
    resume markdown frontmatter and/or a profile.json; visual styling (fonts,
    colors) comes from a format.json. Swap those two files and the same script
    produces a different person's resume in a different visual identity.
    
    WHY A SCRIPT: building the .docx by hand (python-docx calls, hairline rules,
    tab-aligned dates, link styling) is fiddly and drifts every time it's re-derived.
    This renders identically every run. The *content* is the model's job (tailor the
    markdown); the *rendering* is this script's job.
    
    Usage:
      python generate_resume.py --input resume_base.md --output resume.docx
      python generate_resume.py --input resume_acme.md --output Resume_Jane_Acme.docx \
          --profile ../user-library/profile.json --format ../user-library/format.json
      # optional company logo in the header:
      python generate_resume.py --input resume_acme.md --output out.docx \
          --logo logos/acme.png --logo-height 38
    
    format.json (all keys optional — sensible defaults applied):
      {
        "name_font": "Canela Text",   # display font for the name
        "body_font": "Calibri",       # everything else
        "text_color": "1A1A1A",       # near-black: name, company, body
        "muted_color": "6B6B6B",      # gray: role titles, dates, contact
        "rule_color": "C8C8C8",       # hairline section rules / tab leader
        "accent_color": "175DC9"      # links (portfolio, projects)
      }
    
    profile.json (only website_url is read here; the rest is used elsewhere):
      { "website_url": "https://example.com/" }
    
    The resume markdown frontmatter carries the visible identity:
      ---
      name: Jane Doe
      title: [role-tailored title line]
      location: City, ST
      email: [email protected]
      phone: (555) 123-4567
      website: example.com          # display text; link target is website_url
      ---
    """
    
    import argparse
    import json
    import os
    import re
    import sys
    
    try:
        from docx import Document
        from docx.shared import Pt, Inches, RGBColor
        from docx.enum.text import WD_ALIGN_PARAGRAPH
        from docx.enum.table import WD_ALIGN_VERTICAL
        from docx.oxml.ns import qn
        from docx.oxml import OxmlElement
    except ImportError:
        sys.stderr.write(
            "ERROR: python-docx is not installed — the resume builder needs it.\n"
            "Install it with:  pip install python-docx\n"
            "(Run scripts/selfcheck.py to verify all dependencies at once.)\n"
        )
        sys.exit(3)
    
    # ── Style tokens (set at runtime from format.json; these are the defaults) ──────
    # Kept as module globals because the block builders below reference them. They
    # are overwritten by apply_format() before any building happens.
    TEXT  = RGBColor(0x1A, 0x1A, 0x1A)
    MUTED = RGBColor(0x6B, 0x6B, 0x6B)
    RULE  = RGBColor(0xC8, 0xC8, 0xC8)
    LINK  = RGBColor(0x17, 0x5D, 0xC9)
    
    FONT         = "Calibri"
    NAME_FONT    = "Canela Text"
    RULE_HEX     = "C8C8C8"
    PORTFOLIO_URL = ""
    
    CONTENT_W_IN  = 7.20
    CONTENT_W_DXA = int(CONTENT_W_IN * 1440)
    
    
    def _hex_to_rgb(h):
        h = h.lstrip("#")
        return RGBColor(int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))
    
    
    def apply_format(fmt):
        """Overwrite the module style globals from a format dict (all keys optional)."""
        global TEXT, MUTED, RULE, LINK, FONT, NAME_FONT, RULE_HEX
        if fmt.get("text_color"):
            TEXT = _hex_to_rgb(fmt["text_color"])
        if fmt.get("muted_color"):
            MUTED = _hex_to_rgb(fmt["muted_color"])
        if fmt.get("rule_color"):
            RULE = _hex_to_rgb(fmt["rule_color"])
            RULE_HEX = fmt["rule_color"].lstrip("#").upper()
        if fmt.get("accent_color"):
            LINK = _hex_to_rgb(fmt["accent_color"])
        if fmt.get("body_font"):
            FONT = fmt["body_font"]
        if fmt.get("name_font"):
            NAME_FONT = fmt["name_font"]
    
    
    def load_json(path):
        if path and os.path.exists(path):
            with open(path) as f:
                return json.load(f)
        return {}
    
    
    # ── XML helpers ────────────────────────────────────────────────────────────────
    
    def _add_right_tab_leader(paragraph, position_dxa=None, leader="none"):
        if position_dxa is None:
            position_dxa = CONTENT_W_DXA
        pPr = paragraph._p.get_or_add_pPr()
        for existing in pPr.findall(qn('w:tabs')):
            pPr.remove(existing)
        tabs = OxmlElement('w:tabs')
        tab = OxmlElement('w:tab')
        tab.set(qn('w:val'), 'right')
        tab.set(qn('w:pos'), str(int(position_dxa)))
        tab.set(qn('w:leader'), leader)
        tabs.append(tab)
        pPr.append(tabs)
    
    
    def _set_cell_width(cell, width_dxa):
        tcPr = cell._tc.get_or_add_tcPr()
        tcW = OxmlElement('w:tcW')
        tcW.set(qn('w:w'), str(int(width_dxa)))
        tcW.set(qn('w:type'), 'dxa')
        tcPr.append(tcW)
    
    
    def _set_table_width(table, width_dxa):
        tbl = table._tbl
        tblPr = tbl.find(qn('w:tblPr'))
        if tblPr is None:
            tblPr = OxmlElement('w:tblPr')
            tbl.insert(0, tblPr)
        tblW = OxmlElement('w:tblW')
        tblW.set(qn('w:w'), str(int(width_dxa)))
        tblW.set(qn('w:type'), 'dxa')
        tblPr.append(tblW)
        tblLayout = OxmlElement('w:tblLayout')
        tblLayout.set(qn('w:type'), 'fixed')
        tblPr.append(tblLayout)
    
    
    def _remove_table_borders(table):
        tbl = table._tbl
        tblPr = tbl.find(qn('w:tblPr'))
        if tblPr is None:
            tblPr = OxmlElement('w:tblPr')
            tbl.insert(0, tblPr)
        tblBorders = OxmlElement('w:tblBorders')
        for side in ['top', 'left', 'bottom', 'right', 'insideH', 'insideV']:
            node = OxmlElement(f'w:{side}')
            node.set(qn('w:val'), 'none')
            node.set(qn('w:sz'), '0')
            node.set(qn('w:space'), '0')
            node.set(qn('w:color'), 'auto')
            tblBorders.append(node)
        tblPr.append(tblBorders)
    
    
    def _remove_cell_borders(cell):
        tcPr = cell._tc.get_or_add_tcPr()
        tcBorders = OxmlElement('w:tcBorders')
        for side in ['top', 'left', 'bottom', 'right']:
            node = OxmlElement(f'w:{side}')
            node.set(qn('w:val'), 'none')
            node.set(qn('w:sz'), '0')
            node.set(qn('w:space'), '0')
            node.set(qn('w:color'), 'auto')
            tcBorders.append(node)
        tcPr.append(tcBorders)
    
    
    def _set_cell_margin(cell, top=0, start=0, bottom=0, end=0):
        tcPr = cell._tc.get_or_add_tcPr()
        tcMar = OxmlElement('w:tcMar')
        for side, val in [('top', top), ('start', start), ('bottom', bottom), ('end', end)]:
            node = OxmlElement(f'w:{side}')
            node.set(qn('w:w'), str(val))
            node.set(qn('w:type'), 'dxa')
            tcMar.append(node)
        tcPr.append(tcMar)
    
    
    # ── Style helpers ──────────────────────────────────────────────────────────────
    
    def _run(p, text, size_pt, bold=False, italic=False, color=None, font=None):
        r = p.add_run(text)
        r.font.name = font or FONT
        r.font.size = Pt(size_pt)
        r.bold = bold
        r.italic = italic
        if color:
            r.font.color.rgb = color
        return r
    
    
    def _fmt(p, space_before=0, space_after=0, line_spacing_pt=None,
             keep_with_next=False, left_indent_in=None, alignment=None):
        pf = p.paragraph_format
        pf.space_before = Pt(space_before)
        pf.space_after  = Pt(space_after)
        if line_spacing_pt:
            pf.line_spacing = Pt(line_spacing_pt)
        if keep_with_next:
            pf.keep_with_next = True
        if left_indent_in is not None:
            pf.left_indent = Inches(left_indent_in)
        if alignment is not None:
            p.alignment = alignment
    
    
    # ── Block builders ─────────────────────────────────────────────────────────────
    
    def _add_top_border(paragraph, sz=4):
        pPr = paragraph._p.get_or_add_pPr()
        pBdr = OxmlElement('w:pBdr')
        top = OxmlElement('w:top')
        top.set(qn('w:val'), 'single')
        top.set(qn('w:sz'), str(sz))
        top.set(qn('w:space'), '6')
        top.set(qn('w:color'), RULE_HEX)
        pBdr.append(top)
        pPr.append(pBdr)
    
    
    def _section_header(doc, title):
        p = doc.add_paragraph()
        _fmt(p, space_before=14, space_after=3, keep_with_next=True)
        _add_top_border(p)
        _run(p, title.upper(), size_pt=8, bold=True, color=TEXT)
        return p
    
    
    def _role_header(doc, company, role, date):
        p = doc.add_paragraph()
        _fmt(p, space_before=6, space_after=1, keep_with_next=True)
        _add_right_tab_leader(p)
        _run(p, company, size_pt=10.5, bold=True, color=TEXT)
        _run(p, '  /  ', size_pt=10.5, color=MUTED)
        _run(p, role, size_pt=10.5, color=MUTED)
        tab_r = p.add_run('\t')
        tab_r.font.name = FONT
        tab_r.font.size = Pt(10.5)
        if date:
            _run(p, date, size_pt=9, color=MUTED)
        return p
    
    
    def _add_link(paragraph, text, url, size_pt=9, color_hex=None, underline=True):
        """Clickable hyperlink run, colored + optionally underlined."""
        r_id = paragraph.part.relate_to(
            url,
            'http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink',
            is_external=True,
        )
        hl = OxmlElement('w:hyperlink')
        hl.set(qn('r:id'), r_id)
        run_elem = OxmlElement('w:r')
        rPr = OxmlElement('w:rPr')
        rFonts = OxmlElement('w:rFonts')
        rFonts.set(qn('w:ascii'), FONT)
        rFonts.set(qn('w:hAnsi'), FONT)
        rPr.append(rFonts)
        sz = OxmlElement('w:sz')
        sz.set(qn('w:val'), str(int(size_pt * 2)))
        rPr.append(sz)
        clr = OxmlElement('w:color')
        clr.set(qn('w:val'), color_hex or ('%02X%02X%02X' % (LINK[0], LINK[1], LINK[2])))
        rPr.append(clr)
        if underline:
            u = OxmlElement('w:u')
            u.set(qn('w:val'), 'single')
            rPr.append(u)
        run_elem.append(rPr)
        t = OxmlElement('w:t')
        t.text = text
        t.set(qn('xml:space'), 'preserve')
        run_elem.append(t)
        hl.append(run_elem)
        paragraph._p.append(hl)
    
    
    def _description(doc, text, space_after=3, is_last=False):
        p = doc.add_paragraph()
        _fmt(p, space_before=0, space_after=0 if is_last else space_after,
             line_spacing_pt=11, left_indent_in=0.18)
        _run(p, text, size_pt=9, color=TEXT)
        return p
    
    
    # ── Markdown parser ────────────────────────────────────────────────────────────
    
    def _parse_frontmatter(text):
        fm = {}
        if text.startswith('---'):
            end = text.index('---', 3)
            for line in text[3:end].strip().split('\n'):
                if ':' in line:
                    k, v = line.split(':', 1)
                    fm[k.strip()] = v.strip()
            text = text[end + 3:].strip()
        return fm, text
    
    
    def _parse_sections(text):
        sections = {}
        sec_re = re.compile(r'^## (.+)$', re.MULTILINE)
        matches = list(sec_re.finditer(text))
        for i, m in enumerate(matches):
            name = m.group(1).strip()
            start = m.end()
            end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
            sections[name] = text[start:end].strip()
        return sections
    
    
    def _parse_experience(content):
        roles = []
        role_re = re.compile(r'^### (.+)$', re.MULTILINE)
        matches = list(role_re.finditer(content))
        for i, m in enumerate(matches):
            header = m.group(1).strip()
            start = m.end()
            end = matches[i + 1].start() if i + 1 < len(matches) else len(content)
            body = content[start:end].strip()
            if ' | ' in header:
                role_line, date = header.rsplit(' | ', 1)
            else:
                role_line, date = header, ''
            if ' — ' in role_line:
                company, role = role_line.split(' — ', 1)
            else:
                company, role = role_line, ''
            lines = []
            for line in body.split('\n'):
                line = line.strip()
                if line.startswith('- '):
                    lines.append(line[2:])
                elif line:
                    lines.append(line)
            roles.append({'company': company.strip(), 'role': role.strip(),
                          'date': date.strip(), 'lines': lines})
        return roles
    
    
    def _parse_projects(content):
        items = []
        for line in content.split('\n'):
            line = line.strip()
            if line.startswith('- '):
                url = ''
                inner = line[2:]
                if ' | http' in inner:
                    inner, url = inner.rsplit(' | ', 1)
                    url = url.strip()
                m = re.match(r'\*\*(.+?)\*\*\s*[—\-]+\s*(.*)', inner)
                if m:
                    items.append({'name': m.group(1).strip(), 'desc': m.group(2).strip(), 'url': url})
                else:
                    items.append({'name': inner, 'desc': '', 'url': url})
        return items
    
    
    def _parse_skills(content):
        skills = []
        for line in content.split('\n'):
            m = re.match(r'\*\*(.+?):\*\*\s*(.*)', line.strip())
            if m:
                skills.append({'label': m.group(1).strip(), 'content': m.group(2).strip()})
        return skills
    
    
    def _parse_education(content):
        return [l.strip()[2:] for l in content.split('\n') if l.strip().startswith('- ')]
    
    
    def parse_resume(filepath):
        with open(filepath, 'r') as f:
            text = f.read()
        fm, body = _parse_frontmatter(text)
        sections = _parse_sections(body)
        return fm, sections
    
    
    # ── Document assembler ─────────────────────────────────────────────────────────
    
    def build_resume(fm, sections, profile=None, logo_path=None, logo_height_pt=40.0):
        profile = profile or {}
        doc = Document()
    
        sec = doc.sections[0]
        sec.page_width    = Inches(8.5)
        sec.page_height   = Inches(11)
        sec.top_margin    = Inches(0.65)
        sec.bottom_margin = Inches(0.65)
        sec.left_margin   = Inches(0.65)
        sec.right_margin  = Inches(0.65)
    
        normal = doc.styles['Normal']
        normal.font.name = FONT
        normal.paragraph_format.space_before = Pt(0)
        normal.paragraph_format.space_after  = Pt(0)
    
        # Identity from frontmatter, falling back to profile.json.
        name     = fm.get('name', profile.get('name', ''))
        title    = fm.get('title', '')
        location = fm.get('location', profile.get('location', ''))
        email    = fm.get('email', profile.get('email', ''))
        phone    = fm.get('phone', profile.get('phone', ''))
        website  = fm.get('website', profile.get('website', ''))
        has_logo = logo_path and os.path.exists(logo_path)
    
        # Link target for the website display text: profile website_url, else https://<display>.
        portfolio_url = (PORTFOLIO_URL or profile.get('website_url')
                         or (('https://' + website) if website else ''))
    
        def _contact_paragraph(container):
            cp = container.add_paragraph() if hasattr(container, 'add_paragraph') else container
            _fmt(cp, space_before=0, space_after=0)
            prefix = "  ·  ".join(x for x in [location, email, phone] if x)
            _run(cp, prefix + ("  ·  " if website else ""), size_pt=8.5, color=MUTED)
            if website and portfolio_url:
                _add_link(cp, website, portfolio_url, size_pt=8.5)
            elif website:
                _run(cp, website, size_pt=8.5, color=MUTED)
    
        if has_logo:
            logo_col_dxa = 2376
            name_col_dxa = CONTENT_W_DXA - logo_col_dxa
            tbl = doc.add_table(rows=1, cols=2)
            _remove_table_borders(tbl)
            _set_table_width(tbl, CONTENT_W_DXA)
            left_cell  = tbl.cell(0, 0)
            right_cell = tbl.cell(0, 1)
            _set_cell_width(left_cell,  name_col_dxa)
            _set_cell_width(right_cell, logo_col_dxa)
            _remove_cell_borders(left_cell)
            _remove_cell_borders(right_cell)
            _set_cell_margin(left_cell,  top=0, start=0,  bottom=0, end=80)
            _set_cell_margin(right_cell, top=0, start=80, bottom=0, end=0)
            left_cell.vertical_alignment  = WD_ALIGN_VERTICAL.CENTER
            right_cell.vertical_alignment = WD_ALIGN_VERTICAL.CENTER
    
            np = left_cell.paragraphs[0]
            _fmt(np, space_before=0, space_after=2)
            _run(np, name, size_pt=20, color=TEXT, font=NAME_FONT)
            if title:
                tp = left_cell.add_paragraph()
                _fmt(tp, space_before=0, space_after=2)
                _run(tp, title, size_pt=9, color=MUTED)
            _contact_paragraph(left_cell)
    
            lp = right_cell.paragraphs[0]
            _fmt(lp, space_before=0, space_after=0, alignment=WD_ALIGN_PARAGRAPH.RIGHT)
            lp.add_run().add_picture(logo_path, height=Pt(logo_height_pt))
        else:
            np = doc.add_paragraph()
            _fmt(np, space_before=0, space_after=2)
            _run(np, name, size_pt=20, color=TEXT, font=NAME_FONT)
            if title:
                tp = doc.add_paragraph()
                _fmt(tp, space_before=0, space_after=2)
                _run(tp, title, size_pt=9, color=MUTED)
            _contact_paragraph(doc)
    
        # Summary.
        summary_raw = sections.get('Summary', '').strip()
        if summary_raw:
            sp = doc.add_paragraph()
            _fmt(sp, space_before=8, space_after=0, line_spacing_pt=11)
            _run(sp, summary_raw, size_pt=9, color=TEXT)
    
        # Projects (inline).
        projects = _parse_projects(sections.get('Projects', ''))
        if projects:
            p = doc.add_paragraph()
            _fmt(p, space_before=8, space_after=3, line_spacing_pt=11)
            _run(p, 'Select Case Studies:  ', size_pt=9, bold=True, color=TEXT)
            for i, proj in enumerate(projects):
                if i > 0:
                    _run(p, '  •  ', size_pt=9, color=MUTED)
                full_name = (proj['name'] + ' ' + proj['desc']).strip()
                url = proj.get('url', '')
                if url:
                    _add_link(p, full_name, url, size_pt=9)
                else:
                    _run(p, full_name, size_pt=9, color=TEXT)
    
        # Experience.
        if sections.get('Experience'):
            _section_header(doc, 'Professional Experience')
            for role in _parse_experience(sections.get('Experience', '')):
                _role_header(doc, role['company'], role['role'], role['date'])
                for i, line in enumerate(role['lines']):
                    _description(doc, line, is_last=(i == len(role['lines']) - 1))
    
        # Skills.
        if sections.get('Skills'):
            _section_header(doc, 'Skills')
            for i, skill in enumerate(_parse_skills(sections.get('Skills', ''))):
                p = doc.add_paragraph()
                _fmt(p, space_before=3 if i > 0 else 1, space_after=0, line_spacing_pt=12)
                _run(p, skill['label'] + ':  ', size_pt=9, bold=True, color=TEXT)
                _run(p, skill['content'], size_pt=9, color=TEXT)
    
        # Education.
        if sections.get('Education'):
            _section_header(doc, 'Education')
            for i, item in enumerate(_parse_education(sections.get('Education', ''))):
                p = doc.add_paragraph()
                _fmt(p, space_before=3 if i > 0 else 1, space_after=0,
                     line_spacing_pt=12, left_indent_in=0.18)
                _run(p, item, size_pt=9, color=TEXT)
    
        return doc
    
    
    # ── CLI ────────────────────────────────────────────────────────────────────────
    
    if __name__ == '__main__':
        ap = argparse.ArgumentParser(description='Generate a resume .docx from markdown')
        ap.add_argument('--input',  required=True, help='Resume markdown file')
        ap.add_argument('--output', required=True, help='Output .docx path')
        ap.add_argument('--profile', default=None, help='Path to profile.json (contact/website_url defaults)')
        ap.add_argument('--format',  default=None, help='Path to format.json (fonts/colors)')
        ap.add_argument('--logo',    default=None, help='Path to a company logo (PNG/JPG)')
        ap.add_argument('--logo-height', type=float, default=40.0, help='Logo height in points')
        args = ap.parse_args()
    
        fmt = load_json(args.format)
        if fmt:
            apply_format(fmt)
        profile = load_json(args.profile)
    
        print(f'Parsing {args.input}...')
        fm, sections = parse_resume(args.input)
        print(f"Building resume for {fm.get('name', profile.get('name', '?'))}...")
        doc = build_resume(fm, sections, profile=profile,
                           logo_path=args.logo, logo_height_pt=args.logo_height)
        doc.save(args.output)
        print(f'Saved -> {args.output}')
    
  • scripts/job_scanner.py52 KB43e42a32bc56upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • scripts/lint_copy.py9.1 KB1a0b6f432842upstream ↗
    #!/usr/bin/env python3
    """
    lint_copy.py — advisory checks for the prose this kit writes and the resume it
    builds. ADVISORY, not a gate: it surfaces likely problems for a human (or the
    agent) to judge — it never rewrites, and a clean exit is not a guarantee of good
    writing. The real standard lives in references/writing-standards.md and the
    user's voice.md; this just catches the mechanical tells that slip through.
    
    Two modes:
    
      prose <file.md|->   Scan a cover letter / outreach note / application answers
                          for the STRUCTURAL AI tells from writing-standards.md
                          (false-negative "not X, it's Y", rhetorical-question
                          transitions, staccato fragment runs, empty-intensifier
                          openers, asyndeton, em-dash overuse, known AI-tell words).
                          Reads stdin if the file is "-".
    
      summary <resume.md>  Check a tailored résumé's ## Summary reads first-person and
                          isn't mirroring the JD's "who you are" trait language
                          (the two résumé-summary tells, #12 and #13 in
                          writing-standards.md). Reads stdin if the file is "-".
    
      parse <resume.pdf> [--expect STR ...]
                          ATS parse-safety: extract the PDF's text the way a parser
                          would (pdftotext, else pypdf) and confirm each --expect
                          string survives extraction in readable order. Catches the
                          classic failure where a styled header (e.g. a logo table)
                          renders fine but extracts garbled or out of order.
    
    Exit code is 0 when nothing flagged, 1 when there are findings (so a caller can
    choose to surface them) — but treat it as advisory either way.
    
    Usage:
        python3 scripts/lint_copy.py prose CoverLetter_Jane_Acme.md
        python3 scripts/lint_copy.py summary resume_acme.md
        python3 scripts/lint_copy.py parse Resume_Jane_Acme.pdf --expect "Jane Doe" "EXPERIENCE" "SKILLS"
    """
    import argparse
    import re
    import shutil
    import subprocess
    import sys
    
    # (regex, label) — conservative, high-signal patterns. Case-insensitive.
    PROSE_TELLS = [
        (r"\b(?:isn'?t|wasn'?t|aren'?t|not)\b[^.?!\n]{1,60}?,?\s+it'?s\b",
         "false-negative setup ('not X, it's Y') — state the thing directly"),
        (r"(?:^|[.!?]\s+)(?:the result|the catch|the kicker|the best part|why does this matter|so what'?s the (?:point|catch))\?\s",
         "rhetorical-question transition — just make the statement"),
        (r"\b(?:here'?s the thing|what if i told you|let that sink in|make no mistake|here'?s the kicker)\b",
         "empty-intensifier opener — delete the runway, start at the point"),
        (r"\b(?:delve|tapestry|testament to|seamlessly|in today'?s world|navigating the landscape|ever-evolving|it'?s worth noting|not only\b[^.\n]{0,40}\bbut also)\b",
         "known AI-tell word/phrase — cut on sight"),
        (r"\bno\s+\w+,\s*no\s+\w+,\s*no\s+\w+\b",
         "asyndeton ('no X, no Y, no Z') — write it as a normal sentence"),
    ]
    
    
    def lint_prose(text):
        findings = []
        for rx, label in PROSE_TELLS:
            for m in re.finditer(rx, text, re.I | re.M):
                ln = text.count("\n", 0, m.start()) + 1
                snippet = re.sub(r"\s+", " ", m.group(0)).strip()[:70]
                findings.append((ln, label, snippet))
    
        # staccato run: 3+ consecutive ultra-short sentences/fragments (<=4 words)
        sentences = re.split(r"(?<=[.!?])\s+", re.sub(r"\s+", " ", text).strip())
        run = []
        for s in sentences:
            wc = len(s.split())
            if 0 < wc <= 4:
                run.append(s)
                if len(run) == 3:
                    findings.append((0, "staccato fragment run (3+ ultra-short sentences) — let clauses flow",
                                     " / ".join(run)[:70]))
            else:
                run = []
    
        # em-dash density
        dashes = text.count("—")
        words = max(1, len(text.split()))
        if dashes >= 4 and dashes / words > 0.012:
            findings.append((0, "em-dash overuse ({} in {} words) — vary the punctuation per voice.md".format(dashes, words), ""))
    
        return sorted(findings, key=lambda f: f[0])
    
    
    # --- résumé summary voice checks (tells #12 third-person persona, #13 JD trait-mirroring) ---
    FIRST_PERSON = re.compile(r"\b(?:i|i'?m|i'?ve|i'?d|i'?ll|my|me|myself)\b", re.I)
    # gendered singular pronouns in a personal summary almost always point at the user
    SELF_THIRD_PERSON = re.compile(r"\b(?:he|him|his|she|her|hers)\b", re.I)
    # high-signal JD "who you are" trait echoes — advisory, conservative
    MIRROR_TELLS = [
        r"holds? a point of view",
        r"pragmatic about where ai pays off",
        r"comfortable being (?:the|a) senior ic",
        r"it just works",
        r"keeps? (?:people|users|customers|you) in control",
        r"raises? the bar for (?:the |everyone |those )?(?:team|teams|people|around)",
        r"bias (?:for|toward) action",
        r"high[ -]agency",
        r"roll up (?:your|my|their) sleeves",
    ]
    
    
    def extract_summary(md_text):
        """Return the text of the ## Summary section (up to the next heading), or ''."""
        m = re.search(r"(?im)^[ \t]*#{1,6}[ \t]*summary[ \t]*$(.*?)(?=^[ \t]*#{1,6}[ \t]|\Z)",
                      md_text, re.S)
        return m.group(1).strip() if m else ""
    
    
    def lint_summary(md_text):
        findings = []
        summary = extract_summary(md_text)
        if not summary:
            findings.append((0, "no '## Summary' section found — cannot check summary voice", ""))
            return findings
        flat = re.sub(r"\s+", " ", summary).strip()
        if not FIRST_PERSON.search(summary):
            findings.append((0, "summary is NOT first person — no 'I / I'm / I've / my' found; "
                                "reads as third-person persona (tell #12). Rewrite as the user speaking.",
                             flat[:70]))
        for m in SELF_THIRD_PERSON.finditer(summary):
            ln = summary.count("\n", 0, m.start()) + 1
            findings.append((ln, "third-person pronoun in summary — if it refers to the user, "
                                 "switch to first person (tell #12)", m.group(0)))
        for rx in MIRROR_TELLS:
            for m in re.finditer(rx, summary, re.I):
                ln = summary.count("\n", 0, m.start()) + 1
                findings.append((ln, "possible JD trait-mirroring (tell #13) — would the user write "
                                     "this without the posting?", re.sub(r"\s+", " ", m.group(0))))
        return findings
    
    
    def extract_pdf_text(pdf_path):
        if shutil.which("pdftotext"):
            return subprocess.run(["pdftotext", "-layout", pdf_path, "-"],
                                  capture_output=True, text=True).stdout
        try:
            from pypdf import PdfReader
            return "\n".join((pg.extract_text() or "") for pg in PdfReader(pdf_path).pages)
        except Exception:
            return None
    
    
    def lint_parse(pdf_path, expect):
        text = extract_pdf_text(pdf_path)
        if text is None:
            print("WARN: could not extract text (install poppler or pypdf to run the parse check)")
            return []
        norm = re.sub(r"\s+", " ", text).lower()
        missing = [s for s in expect if re.sub(r"\s+", " ", s).lower() not in norm]
        findings = []
        for s in missing:
            findings.append((0, "ATS parse-safety: expected text not found after extraction", s))
        # crude order check on the ones that are present
        present = [s for s in expect if s not in missing]
        positions = [norm.find(re.sub(r"\s+", " ", s).lower()) for s in present]
        if positions != sorted(positions):
            findings.append((0, "ATS parse-safety: --expect strings extracted OUT OF ORDER "
                                "(styled header/table may be scrambling parse order)", ""))
        return findings
    
    
    def report(findings, what):
        if not findings:
            print("clean — no {} flagged (advisory).".format(what))
            return 0
        print("{} finding(s) — advisory, judge each:".format(len(findings)))
        for ln, label, snippet in findings:
            loc = "L{}".format(ln) if ln else " · "
            print("  [{}] {}{}".format(loc, label, "  →  \"{}\"".format(snippet) if snippet else ""))
        return 1
    
    
    if __name__ == "__main__":
        ap = argparse.ArgumentParser(description="Advisory prose / parse-safety linter")
        sub = ap.add_subparsers(dest="mode", required=True)
        pp = sub.add_parser("prose", help="scan a prose file for structural AI tells")
        pp.add_argument("file", help="markdown/text file, or - for stdin")
        ps = sub.add_parser("summary", help="check a résumé summary's voice (first-person, no JD trait-mirroring)")
        ps.add_argument("file", help="resume_<company>.md file, or - for stdin")
        pa = sub.add_parser("parse", help="ATS parse-safety check on a resume PDF")
        pa.add_argument("pdf")
        pa.add_argument("--expect", nargs="*", default=[],
                        help="strings that must survive text extraction in order (name, section headers)")
        args = ap.parse_args()
    
        if args.mode == "prose":
            text = sys.stdin.read() if args.file == "-" else open(args.file, encoding="utf-8").read()
            sys.exit(report(lint_prose(text), "tells"))
        elif args.mode == "summary":
            text = sys.stdin.read() if args.file == "-" else open(args.file, encoding="utf-8").read()
            sys.exit(report(lint_summary(text), "summary issues"))
        else:
            sys.exit(report(lint_parse(args.pdf, args.expect), "parse issues"))
    
  • scripts/page_count.py2.8 KBed2a3456a32aupstream ↗
    #!/usr/bin/env python3
    """
    page_count.py — Deterministic page-length check for a resume PDF.
    
    A resume should fit a target length — one page for most roles, but some fields
    (academic CV, federal, senior/technical) legitimately run longer. Judging that
    by eye from a render is unreliable, so this reads the real page count and, when
    the resume spills past the target, prints the text that landed on the overflow
    pages so the caller knows exactly what to trim.
    
    The target defaults to 1 page but is configurable: pass --max-pages N, or let the
    RUN step read it from the user's format.json ("max_pages": N) and pass it through.
    
    Usage:
        python page_count.py /path/to/Resume_<Name>_<Company>.pdf
        python page_count.py <pdf> --max-pages 2
    
    Output:
        PAGES: <n>
        (if over target) a "=== OVERFLOW (page N+) ===" block with the spilled text
    
    Exit code 0 if the PDF is within the target page count, 1 otherwise (so it can
    gate a loop).
    """
    import argparse
    import re
    import shutil
    import subprocess
    import sys
    
    
    def page_count(pdf_path):
        if shutil.which("pdfinfo"):
            out = subprocess.run(["pdfinfo", pdf_path], capture_output=True, text=True).stdout
            m = re.search(r"Pages:\s*(\d+)", out)
            if m:
                return int(m.group(1))
        try:
            from pypdf import PdfReader
            return len(PdfReader(pdf_path).pages)
        except Exception:
            return None
    
    
    def overflow_text(pdf_path, first_overflow_page):
        """Text from first_overflow_page onward. Prefer pdftotext (poppler); fall
        back to pypdf so the 'what spilled' hint still works without poppler."""
        if shutil.which("pdftotext"):
            return subprocess.run(
                ["pdftotext", "-f", str(first_overflow_page), pdf_path, "-"],
                capture_output=True, text=True,
            ).stdout.strip()
        try:
            from pypdf import PdfReader
            pages = PdfReader(pdf_path).pages
            chunks = [pages[i].extract_text() or "" for i in range(first_overflow_page - 1, len(pages))]
            return "\n".join(chunks).strip()
        except Exception:
            return ""
    
    
    if __name__ == "__main__":
        ap = argparse.ArgumentParser(description="Check that a resume PDF fits a page target")
        ap.add_argument("pdf")
        ap.add_argument("--max-pages", type=int, default=1,
                        help="Target page count (default 1; read from format.json max_pages for longer-format fields)")
        args = ap.parse_args()
        target = max(1, args.max_pages)
    
        n = page_count(args.pdf)
        if n is None:
            print("ERROR: could not determine page count", file=sys.stderr)
            sys.exit(2)
    
        print(f"PAGES: {n}")
        if n <= target:
            sys.exit(0)
    
        spill = overflow_text(args.pdf, target + 1)
        if spill:
            print(f"\n=== OVERFLOW (page {target + 1}+) ===")
            print(spill)
        sys.exit(1)
    
  • scripts/selfcheck.py7.3 KBb8694d91ccfeupstream ↗
    #!/usr/bin/env python3
    """
    selfcheck.py — verify an open-to-work install is healthy before you rely on it.
    
    Run this after installing the skill, after editing any script, or whenever a run
    fails in a confusing way. It does three things:
    
      1. COMPILE  — byte-compiles every bundled script so a syntax error surfaces
                    here, not mid-pipeline.
      2. DEPS     — reports which runtime dependencies are present:
                      • python-docx   (required to build DOCX)   — hard
                      • LibreOffice   (soffice/libreoffice)      — hard for PDF export
                      • poppler       (pdfinfo / pdftotext)      — used by the page
                                       check + ATS text extraction (pypdf is a fallback)
                      • pypdf         (fallback page count / text)— soft
      3. LOGIC    — runs job_scanner against a tiny in-memory fixture and asserts the
                    two behaviors most likely to silently regress:
                      • a strong role surfaces and is flagged deep_read=true;
                      • exclude_keywords match on WORD BOUNDARIES — a posting whose
                        text merely contains "define" is NOT dropped by exclude
                        ["defi"]; a posting that really mentions "defi" IS dropped.
    
    Exit code 0 if all hard checks pass (soft/dep warnings don't fail the run);
    non-zero if a script won't compile or the scanner logic is wrong.
    
    Usage:
        python3 scripts/selfcheck.py
    """
    import contextlib
    import importlib.util
    import io
    import json
    import os
    import py_compile
    import shutil
    import sys
    import tempfile
    
    HERE = os.path.dirname(os.path.abspath(__file__))
    
    OK, WARN, FAIL = "  ok ", " warn", "FAIL "
    _failed = False
    
    
    def line(status, msg):
        print("[{}] {}".format(status, msg))
    
    
    def mark_fail(msg):
        global _failed
        _failed = True
        line(FAIL, msg)
    
    
    # --- 1. COMPILE ------------------------------------------------------------- #
    def check_compile():
        print("\n— compile —")
        for fn in sorted(os.listdir(HERE)):
            if fn.endswith(".py"):
                path = os.path.join(HERE, fn)
                try:
                    py_compile.compile(path, doraise=True)
                    line(OK, fn)
                except py_compile.PyCompileError as e:
                    mark_fail("{}: {}".format(fn, str(e).splitlines()[-1]))
    
    
    # --- 2. DEPS ---------------------------------------------------------------- #
    def check_deps():
        print("\n— dependencies —")
        if importlib.util.find_spec("docx"):
            line(OK, "python-docx (DOCX builder)")
        else:
            line(WARN, "python-docx MISSING — resume/cover-letter DOCX will fail. `pip install python-docx`")
        if shutil.which("soffice") or shutil.which("libreoffice"):
            line(OK, "LibreOffice (PDF export)")
        else:
            line(WARN, "LibreOffice MISSING — PDF export will fail. Install LibreOffice.")
        have_pdfinfo = bool(shutil.which("pdfinfo"))
        have_pdftotext = bool(shutil.which("pdftotext"))
        if have_pdfinfo and have_pdftotext:
            line(OK, "poppler (pdfinfo + pdftotext)")
        else:
            missing = ", ".join(n for n, ok in
                                (("pdfinfo", have_pdfinfo), ("pdftotext", have_pdftotext)) if not ok)
            if importlib.util.find_spec("pypdf"):
                line(WARN, "poppler partial/missing ({}) — pypdf fallback present, page check still works".format(missing))
            else:
                line(WARN, "poppler MISSING ({}) and no pypdf fallback — page check + ATS text extraction degrade. "
                           "Install poppler (brew install poppler / apt-get install poppler-utils) or `pip install pypdf`".format(missing))
    
    
    # --- 3. LOGIC --------------------------------------------------------------- #
    def _import_scanner():
        spec = importlib.util.spec_from_file_location("job_scanner", os.path.join(HERE, "job_scanner.py"))
        mod = importlib.util.module_from_spec(spec)
        spec.loader.exec_module(mod)
        return mod
    
    
    def check_scanner_logic():
        print("\n— scanner logic —")
        try:
            js = _import_scanner()
        except Exception as e:
            mark_fail("could not import job_scanner.py: {}".format(e))
            return
    
        criteria = {
            "role_title_regex": r"(senior|staff|principal|lead).*(product design|design)",
            "levels": ["principal", "staff", "lead", "senior"],
            "locations": ["United States", "Remote US"],
            "us_only": True,
            "comp_target": 180000, "comp_floor": 150000,
            "signal_keywords": ["design system"],
            "tier1_keywords": ["design system"],
            "shape_signals": ["0 to 1", "founding"],
            "exclude_keywords": ["defi"],   # crypto hard-no — must NOT match "define"
            "deep_read_threshold": 50,
            "result_cap": 8,
        }
        good = {"id": 1, "company_name": "Acme", "title": "Senior Product Designer",
                "candidate_required_location": "USA", "url": "https://acme.test/1",
                "description": "You will define the design system and own 0 to 1 work. $180,000-$210,000",
                "salary": "$180,000-$210,000", "publication_date": "2026-06-13T10:00:00"}
        crypto = {"id": 2, "company_name": "CoinCo", "title": "Senior Product Designer",
                  "candidate_required_location": "USA", "url": "https://coin.test/2",
                  "description": "Design our DeFi exchange. We live and breathe defi.",
                  "publication_date": "2026-06-13T10:00:00"}
    
        with tempfile.TemporaryDirectory() as d:
            cfg = os.path.join(d, "config.json")
            fetched = os.path.join(d, "fetched")
            os.makedirs(fetched)
            json.dump({"discovery_sources": {"remotive": {"enabled": True, "queries": ["x"]},
                                             "remoteok": {"enabled": False}, "arbeitnow": {"enabled": False},
                                             "jobicy": {"enabled": False}},
                       "watchlist_enabled": False, "criteria": criteria}, open(cfg, "w"))
            json.dump({"jobs": [good, crypto]}, open(os.path.join(fetched, "remotive__x.json"), "w"))
            with contextlib.redirect_stdout(io.StringIO()):  # swallow the scanner's own markdown
                out = js.run(cfg, os.path.join(d, "seen.json"), os.path.join(d, "sl.json"),
                             dry_run=True, input_dir=fetched)
    
        titles = {p["company"]: p for p in out["shortlist"]}
        if "Acme" in titles:
            line(OK, "strong role surfaced (the 'define' posting was NOT dropped by exclude ['defi'])")
            if titles["Acme"].get("deep_read"):
                line(OK, "strong role flagged deep_read=true (score {})".format(titles["Acme"]["score"]))
            else:
                mark_fail("strong role surfaced but deep_read=false — scoring/threshold regression")
        else:
            mark_fail("WORD-BOUNDARY EXCLUDE REGRESSION: a posting containing 'define' was dropped by "
                      "exclude ['defi']. job_scanner must use regex \\bword\\b, not substring matching.")
        if "CoinCo" not in titles:
            line(OK, "genuine 'defi' posting correctly excluded")
        else:
            mark_fail("crypto posting that really mentions 'defi' was NOT excluded — exclude gate broken")
    
    
    if __name__ == "__main__":
        print("open-to-work selfcheck")
        check_compile()
        check_deps()
        check_scanner_logic()
        print("\n" + ("SELFCHECK FAILED — fix the FAIL lines above." if _failed
                      else "SELFCHECK PASSED — compile + scanner logic OK (heed any 'warn' deps)."))
        sys.exit(1 if _failed else 0)
    
  • references/application-tracker.md4.2 KB0c1691ea7d49upstream ↗
    # Application Tracker — the standing ledger of where every role stands
    
    The scanner remembers what it has *shown* you (`seen_postings.json`); the tracker
    remembers what you've *done* — applied, reached out, interviewed, heard back — and what
    you owe next. It's a single plain-JSON file the agent maintains:
    **`user-library/applications.json`**. No script renders it; you read and update it
    directly, the same way you maintain the rest of the library, and under the same
    **`library_enrichment.mode`** (confirm vs. silent) and never-fabricate rules — only ever
    record what actually happened.
    
    This is what lets the user ask "what's still open?", "who do I owe a follow-up?", or
    "what did I apply to last week?" and get a real answer instead of a shrug.
    
    ## When to touch it (across modes)
    
    - **RUN (apply):** when an application is built — and especially after a browser
      fill/upload — append or update the role's record: `status: "applied"` (or
      `"prepared"` if the docs are made but not submitted), the deliverable paths, the JD
      link, the ATS, and the tier.
    - **OUTREACH:** when a note is drafted/sent, set `outreach` (method, who, date,
      email-confidence) and, if outreach is the only action so far, `status: "outreach_sent"`.
    - **PREP:** when the user says they have an interview, add an entry to `interviews`
      (round, date) and set `status: "interviewing"`.
    - **Debrief:** mark that interview `debriefed: true` with a one-line outcome read.
    - **Scan / discovery:** optional — a strong shortlisted role the user wants to pursue
      can be logged `status: "discovered"` so it doesn't get lost before they apply.
    - **Status changes the user reports** ("got rejected", "they ghosted me", "got the
      offer"): update `status` and clear/keep `next_action` accordingly.
    
    Always batch tracker writes into a mode's **close-out step**, never mid-task, and (in
    `confirm` mode) show the user the record you're about to write.
    
    ## Record shape
    
    `applications.json` is `{"applications": [ ... ]}`. Each record:
    
    ```json
    {
      "company": "Acme",
      "role": "Senior Product Designer",
      "tier": 1,
      "source": "linkedin",
      "jd_url": "https://acme.com/jobs/123",
      "apply_url": "https://boards.greenhouse.io/acme/jobs/123",
      "ats": "greenhouse",
      "status": "interviewing",
      "applied_date": "2026-06-10",
      "deliverables": {
        "resume": "Resume_Jane_Acme.pdf",
        "cover_letter": "CoverLetter_Jane_Acme.pdf"
      },
      "outreach": {
        "sent": true, "method": "email", "to": "Dana Lee (Head of Design)",
        "email_confidence": "deduced", "date": "2026-06-10"
      },
      "interviews": [
        { "round": "recruiter screen", "date": "2026-06-14", "debriefed": true, "outcome": "advanced" },
        { "round": "hiring manager", "date": "2026-06-20", "debriefed": false, "outcome": null }
      ],
      "next_action": "Prep for the hiring-manager round",
      "next_action_date": "2026-06-19",
      "notes": "Real hook: long-time user of their product.",
      "updated_at": "2026-06-14"
    }
    ```
    
    Keep fields honest and omit what you don't know (don't invent a date or an outcome).
    `status` is one of: `discovered` · `prepared` · `applied` · `outreach_sent` ·
    `interviewing` · `offer` · `rejected` · `withdrawn` · `ghosted`.
    
    ## Answering "what's outstanding?"
    
    When the user asks for their pipeline, read `applications.json` and report a tight,
    grouped view — active roles first, then by `next_action_date`:
    
    - **Needs action now** — anything whose `next_action_date` is past/today, or
      `status: applied` with no response in ~7–10 days (a polite status-check nudge is the
      natural follow-up — see `references/followup-and-negotiation.md`).
    - **In flight** — `interviewing` / `offer`, with the next round or decision date.
    - **Applied, waiting** — recent applications inside the normal response window.
    - **Closed** — `rejected` / `withdrawn` / `ghosted`, collapsed to a count unless asked.
    
    Offer to take the obvious next step (draft the follow-up, prep the next round, log a
    new outcome). The tracker exists to drive action, not just to store rows.
    
    ## First-run
    
    If `applications.json` doesn't exist when a mode first needs it, create it as
    `{"applications": []}` (same as the empty `seen_postings.json` seed). Mention to the
    user once that you're now keeping a pipeline ledger they can query anytime.
    
  • references/ats-rubric.md4.6 KBe2cf1449c0a3upstream ↗
    # ATS Scoring Rubric (self-contained)
    
    The RUN pipeline scores the tailored resume against the JD twice. This rubric is
    the scorer — no external skill needed. Apply it honestly: a higher score earned by
    a lie is worthless and will collapse in an interview. The scorer's only job is to
    find gaps; closing them (truthfully) happens back in the tailoring step.
    
    ## Inputs
    
    Both must be present: the resume text (extract with `pdftotext -layout <pdf> -`)
    and the **full JD text** (not just a URL).
    
    ## Step 1 — Classify the JD before scoring (required)
    
    Before reading the resume, classify the JD's sections by intent and state it
    explicitly. Skipping this is a scoring error.
    
    | Section type | Signal phrases | How to treat it |
    |---|---|---|
    | **Role description** | "You will…", "This role owns…", "Your work will…" | Scope context only. Do NOT score gaps against it. |
    | **Qualifications** | "Requirements", "Who you are", "You have…", "We're looking for…" | The actual hiring bar. Score against this. |
    | **Integrated JD** (no clear split) | Mixed/absent headers | Extract implied qualifications (years, domain, skills), then apply the role-native rule below. |
    
    **Role-native knowledge rule:** never penalize the candidate for lacking
    proprietary, platform-specific, or internal knowledge that could only be acquired
    by working in this exact seat (a company's internal tool names, their specific
    implementation of a common technology, product areas unique to that org). Those
    belong to the role description, not the hiring bar — exclude them from gap scoring.
    
    State before scoring: **Qualifications section identified**, **Excluded terms**
    (role-description-only items that must not appear in the gap list), and **Scoring
    basis** (one sentence on what you're scoring against).
    
    ## Step 2 — Score, 1–100, weighted
    
    Be calibrated. Most resumes land 40–75. A 90+ means near-perfect keyword and
    experience match; sub-40 means meaningful gaps.
    
    | Category | Weight | What to evaluate |
    |---|---|---|
    | **Keyword Match** | 35% | Hard skills, tools, technologies, role-specific terms from the JD that appear in the resume |
    | **Title & Level Alignment** | 20% | How closely the candidate's current/recent title and seniority match the posted role |
    | **Experience Relevance** | 40% | Depth of relevant experience — whether past work aligns with the actual JD responsibilities, not just years |
    | **Education & Credentials** | 5% | Degree/certs/credentials the JD calls out |
    
    ## Output format
    
    ```
    ## ATS Score: [X]/100
    
    ### Keyword Match — [X]/35
    [2–3 sentences on coverage]
    Present: [matched terms]
    Missing: [unmatched JD terms]
    Near-misses: [resume uses a synonym/related phrase instead of the exact JD term]
    
    ### Title & Level Alignment — [X]/20
    [1–2 sentences; note any parsing risks]
    
    ### Experience Relevance — [X]/40
    [2–3 sentences; name specific JD responsibilities not reflected in the resume]
    
    ### Education & Credentials — [X]/5
    [1 sentence]
    
    ### Summary
    [3–4 sentences: overall read, the 1–2 highest-impact gaps, and an honest ceiling —
    "with these addressed, this resume could realistically reach X/100"]
    
    ### Gap List
    Numbered, priority order by score impact. Gaps only — no fixes. Each item names the
    JD term/requirement that's missing or underrepresented, where in the resume it's
    absent, and whether it's a HARD gap (experience doesn't exist) or a SOFT gap
    (experience exists but isn't surfaced).
    1. **[gap name]** — Missing from [location]. [Hard/Soft] gap.
    ```
    
    ## Behavioral rules
    
    - **Be an ATS, not a cheerleader.** Score on signal matching, not writing quality.
    - **Penalize missing keywords even when the experience clearly implies them.** ATS
      matches strings, not inferences. Near-misses get partial credit, not full.
    - **Don't inflate.** A 70 should feel like a real 70.
    - **No fixes here.** This step identifies gaps; the tailoring step closes the soft
      ones (truthfully) and records the hard ones for the report.
    - After the score, add a 2–3 sentence **Human Reviewer Take** noting where the ATS
      score and a human's impression are likely to diverge (common for senior
      candidates whose strengths don't reduce to keywords).
    
    ## How the RUN loop uses this
    
    For each of two rounds: score → triage each gap through the truthfulness filter
    (soft gap → reword/surface it truthfully; **hard gap → do NOT fix; record it for
    the report**) → apply edits to `resume_<company>.md` → rebuild docx/pdf and
    re-check one page. Round 2 scores what Round 1 produced. Capture both scores and
    the specific changes for the final report, and list every recommendation
    deliberately skipped because it would require fabricating experience — that list is
    a feature, not an apology.
    
  • references/base_resume-template.md1.9 KBbec067100a32upstream ↗
    ---
    name: Your Name
    title: [The role-tailored title line — match the target role's language. Highest-impact single change.]
    location: City, ST
    email: [email protected]
    phone: (555) 123-4567
    website: yoursite.com
    ---
    
    ## Summary
    [One tight paragraph. Lead with the most role-relevant angle. Same length whatever the role — tailor by rewording, not lengthening.]
    
    ## Experience
    ### Company — Role Title | Mon YYYY – Present
    Description line — verb-first, impact-driven, a real number as payoff where you have one. No bullet prefix needed; each line on its own row renders as its own indented item.
    Another line for the same role.
    
    ### Company — Role Title | Mon YYYY – Mon YYYY
    A role with no detail lines is fine — the header alone renders (useful for older/short roles).
    
    ## Projects
    - **Owner/Company** — Project Title | https://link-to-case-study
    - **Owner/Company** — Another Project | https://link
    
    ## Skills
    **Category:** term, term, term
    **Another Category:** term, term, term
    
    ## Education
    - Institution — Degree
    - Institution — Certificate
    
    <!--
    HOW THIS FILE IS USED
    - generate_resume.py parses this markdown and renders the .docx. The section
      names above (Summary, Experience, Projects, Skills, Education) are the ones it
      recognizes — keep them. Order is fixed: Summary -> Projects -> Experience ->
      Skills -> Education.
    - Experience headers use:  Company — Role Title | Date    (em dash between
      company and role, a pipe before the date).
    - Projects use:  - **Name** — description | https://url   (the URL is optional).
    - Skills use:  **Label:** comma, separated, terms
    - This is your MASTER copy. To tailor for a role, COPY it to resume_<company>.md
      and edit the copy — never edit this base file, so it stays clean for next time.
    - Everything here must be TRUE. Tailoring = reordering, reframing, resurfacing
      real experience — never inventing employers, titles, metrics, tools, or skills.
    -->
    
  • references/browser-autofill.md5.8 KB70eee80db0baupstream ↗
    # Browser Auto-Fill & Upload (Claude-in-Chrome)
    
    How to fill an application form and attach the tailored PDFs in a browser, using
    the Claude-in-Chrome tools. This is the apply step at the end of the RUN pipeline.
    The method below is the *only* one that reliably works for file uploads — the
    obvious alternatives don't, for the reasons noted. None of this is person-specific.
    
    **Prerequisite: the Claude for Chrome extension.** This whole step depends on it,
    plus the browser being open and the user logged in to the ATS / job site. If the
    extension isn't connected, you can't fill or upload — say so and point the user to
    Step A3c (extension setup) rather than failing silently. (The same extension powers
    the scheduled LinkedIn/Wellfound browser pass, so a user who set up scanning likely
    already has it.)
    
    ## The one irreversible rule
    
    **Always STOP at the final Submit.** Fill everything, attach the files, verify, and
    then hand control back so the user reviews and submits themselves. Submitting is
    the one step you never take for them — unless the user has explicitly authorized you
    to submit.
    
    ## Apply on the canonical ATS, not a profile-only aggregator
    
    Before filling anything, check **where** you're applying. Some sources — notably
    **Wellfound and LinkedIn Easy Apply** — only transmit the user's *profile* and offer
    **no file upload at all**, so the tailored résumé and cover letter can never be
    attached. When the role was found on one of those, first search for the same posting
    on the company's **real ATS** (Greenhouse / Ashby / Lever) or careers page and apply
    **there**, where the documents can actually be uploaded. Profile-only is the fallback
    only when no canonical posting exists. (At the shortlist stage, that canonical "Apply
    at" link should already be surfaced — see `scheduling.md`.)
    
    ## Stage the PDFs to the OUTPUTS folder first
    
    The Chrome `file_upload` tool can only attach a file that lives in a **writable
    outputs/working folder** (it's writable and the tool drops the file straight into the
    form's own file input) — **not** a read-only skill/bundle dir, and **not** a
    Drive/Dropbox location. So before applying, copy the final PDFs into the outputs
    folder with their exact deliverable names:
    
    ```bash
    cp "Resume_<Name>_<Company>.pdf" "CoverLetter_<Name>_<Company>.pdf" "<outputs folder>/"
    ```
    
    Keep the filenames exactly as the deliverables — they're what the recruiter sees,
    and you'll verify them by name after upload.
    
    ## Upload procedure
    
    1. **One tab per application.** Open EACH application in its OWN browser tab and
       never reuse a tab — navigating away wipes a filled form. Applying to several
       roles in a batch means several parallel tabs.
    2. **Fill standard fields from `profile.json`** — name, email, phone, location,
       links, work authorization / sponsorship answer, and the `standard_form_answers`
       (how-you-heard, start date, EEO fields the user chose to pre-fill). Leave blank
       anything the user left blank.
    3. **Upload the résumé.** `find` the specific résumé file input (type=file), then
       `file_upload` with the outputs path. **Re-find the input ref immediately before
       the upload** — refs shift, and a mid-task extension reconnect can land a file in
       the wrong slot.
    4. **Upload the cover letter** the same way — re-find its input first, then upload.
    5. **Verify the filenames landed in the right slots.** Read back the attached
       filenames and confirm the résumé is in the Résumé/CV field and the cover letter
       is in the Cover Letter field. If they're mis-slotted (the reconnect slot-shuffle
       bug), remove and redo. This check is not optional — a swapped pair looks fine to
       the upload tool but wrong to the recruiter.
    6. **Fill remaining fields and STOP at Submit** for the user to review.
    
    ## Some forms have no cover-letter slot and/or no essay questions
    
    Not every ATS form accepts a cover letter, and some have no open-ended essay
    questions at all (certain Ashby forms, for instance, offer neither). That's fine and
    expected — it doesn't mean skip the cover letter. The cover letter is **always a
    standalone deliverable**: produce and render it regardless, so the user can email it
    or hand it to a recruiter even when the form won't take an upload. If there's no
    essay box, there's simply nothing to paste — note it and move on.
    
    ## Leave genuine user-judgment fields for the human
    
    Fill only what you can verify from `profile.json`. **Never auto-answer or auto-agree**
    to fields that are the user's call to make:
    
    - **Relocation-willingness** questions ("are you willing to relocate to X?").
    - **"Have you used <product> before?"** / familiarity questions.
    - **Terms / consent / acknowledgment checkboxes.**
    - The final **Submit**.
    
    Leave these for the user. Surface them clearly when you hand control back, fill
    everything you legitimately can, and stop — unless the user has explicitly told you
    to answer or submit on their behalf.
    
    ## What NOT to do (these genuinely don't work)
    
    - **Don't use the board's Google Drive / Dropbox "import" buttons.** They open a
      third-party, cross-origin file chooser the agent cannot operate — clicks and
      keystrokes don't reach inside it.
    - **Don't rely on the native OS file dialog.** It's invisible to the agent.
    - The outputs-folder → `file_upload` path is the only working upload method.
    
    ## Open-ended questions live behind the Apply button
    
    Most application forms hide their essay-style questions ("Why this company?",
    "Walk us through a project") behind the Apply button, so they often don't appear in
    the JD text at all. When you have the application page open, **pull those questions
    straight from the form** and answer them (in the user's voice, per the
    cover-letter playbook's coordinated-set rule) before stopping at Submit. If you
    only ever had the JD and never opened the form, tell the user plainly that
    form-gated questions may exist that you couldn't see, and offer to answer any they
    paste back.
    
  • references/cover-letter-playbook.md6.0 KBac219a2cbc4eupstream ↗
    # Cover-Letter Playbook (universal principles)
    
    Load this in the writing pass, alongside the user's `voice.md` and `fact-pack.md`.
    It governs *how* a strong cover letter is shaped; the user's files govern *what*
    goes in it and *whose voice* it's in. None of this is person-specific — it applies
    to anyone using the kit.
    
    The goal every time: a specific, confident, human letter with zero generic filler,
    in the applicant's real voice, that proves they read *this* posting.
    
    ---
    
    ## 1. Open with the strongest *authentic* entry point — strict hierarchy
    
    Decide honestly which tier applies **before** writing. Scan the user's documented
    personal hooks for a real connection to *this* company, product, or domain; if one
    genuinely fits, lead with it; if not, use the elevator pitch. Don't force a
    connection that isn't real.
    
    - **PREFERRED — a genuine personal connection or passion**, drawn *only* from the
      user's documented hooks in `fact-pack.md` (or something they've said in the
      conversation). When real, this is the warmest, most memorable opener — a product
      they actually use every day, a cause they genuinely care about, the field they
      came from. The bar is **authenticity**: it must be traceable and must not be a
      stretch. **Never invent or inflate a connection.** A manufactured "I've always
      been passionate about [X]" is worse than having no connection at all — recruiters
      can smell it, and it's the opposite of a real voice.
    - **FALLBACK — the elevator pitch**, lightly tailored (the user's canonical version
      is in `fact-pack.md`). Use when no genuine connection is strong enough to lead
      with. It's a clean, confident statement of who they are — the safe default, not a
      failure.
    - **BANNED — the thesis cold open.** Never open with a pronouncement about the
      industry or what the role is "really" about. It reads as pretentious and
      overreaching — like explaining the company's own job back to them — and it
      recurs, so kill it on sight. Cautionary example of exactly what NOT to write:
      *"Most AI products look like a database that learned to talk — functional, and a
      little joyless. The interesting version of this role is refusing to let that
      happen…"* However clever it sounds, that pattern is banned.
    
    "I am writing to apply for…" is also dead on arrival. After the opener, move
    straight into evidence.
    
    ## 2. Prove it with real evidence
    
    One or two paragraphs of concrete work, selected and framed for *this* role, drawn
    from `fact-pack.md`. Use real numbers as payoff, not decoration. Tell the small,
    specific story (the recovery flow, the research insight, the rescued deadline)
    rather than listing responsibilities.
    
    ## 3. Be specific about *this* company
    
    Name the actual product or problem and connect the applicant's experience to it.
    This is the paragraph that proves they read the posting and aren't mass-blasting.
    Generic praise ("I admire your innovative culture") is filler — cut it.
    
    ## 4. If there's an honest gap, name it plainly
    
    When the role has a domain the applicant can't truthfully claim, the strongest play
    is one plain sentence naming it, then a pivot to the transferable strength — e.g.
    *"I don't have direct [domain] experience, and I'd rather say that plainly than let
    you find it in the résumé."* Honesty reads as confidence. Never invent adjacent
    experience to cover a gap.
    
    ## 5. Close short and confident
    
    A line, not a paragraph — *"I'd love to talk."* / *"I'd love to work on this."*
    Then the signature.
    
    ---
    
    ## Rhythm — write like a person, not like ad copy  *(the single most important craft rule)*
    
    The most common way these letters go wrong is **artificially short, clipped
    sentences and fragments deployed for effect**, which reads as machine-generated
    rather than human. The tell is a sentence fragment standing in for a clause — e.g.
    *"I started in advertising — a degree in it, then years at agencies."* ("a degree
    in it" is a fragment-for-effect).
    
    Favor fuller sentences whose clauses actually connect, joined with conjunctions, em
    dashes, semicolons, or commas. Vary length, but a genuinely short sentence should
    be **rare and earned** — used for real emphasis, never as the default cadence. Read
    each paragraph back and ask whether a person would say it that way out loud; if it
    feels staccato or punchy-for-the-sake-of-it, rewrite it to flow.
    
    ## Length & format
    
    Keep it to one page, ~3–5 tight paragraphs. Render it with `build_cover_letter.py`
    so the letterhead matches the resume — never hand-write the docx or re-style it.
    
    Always produce the letter as a **standalone deliverable**, even when the application
    form has no cover-letter upload slot (some ATS forms don't). A rendered letter the
    user can email or hand to a recruiter is worth having regardless of whether a given
    form will accept it.
    
    ---
    
    ## Coordinating the cover letter with application answers (distribute the evidence)
    
    Cover letters and open-ended application answers should be planned **as one set**,
    because the fastest way to look generic is to lead every piece with the same story.
    Most applicants have a finite stock of proof points. Map each question (and the
    letter) to a *distinct* primary example wherever the prompts allow: if the letter
    leads on story A, let a "work you're proud of" answer lean on story B, a
    "navigating ambiguity" answer pull from story C, and so on. Reuse a story across
    two pieces only when it truly is the best fit for both — and even then, frame it
    from a different angle. Someone reading the whole application should come away
    seeing range, not the same anecdote on a loop.
    
    For the answers specifically: match length to the ask (a "why this company" box
    usually wants 80–120 words; "walk us through a project" might want 200–300), respect
    any stated limits, answer the actual question with no throat-clearing preamble, and
    hold to truth-only — every claim traces to `fact-pack.md` or something the user
    said. Output answers inline in chat as copy-paste-ready text (they go into a web
    form), never as a file: each as a markdown heading with the exact question text and
    the answer beneath it.
    
  • references/fact-pack-template.md5.5 KBadea754f14f0upstream ↗
    # Experience Fact Pack — [Your Name]
    
    This is the single source of truth for **what you've actually done** and the
    **stories, hooks, and differentiators** your applications draw on. Onboarding
    writes a filled copy to `user-library/fact-pack.md`. The resume tailors from the
    roles-and-metrics half; the cover letter and application answers draw on the
    narrative half. **Everything here must be true** — if a future role needs a hook
    or claim that isn't supported here, the honest move is to ask you, not to invent
    one.
    
    Fill in the bracketed prompts. Delete sections that genuinely don't apply, but
    the richer this is, the stronger and more specific every application gets.
    
    ---
    
    ## Core Profile
    
    [2–3 sentences: who you are professionally, years of experience, the through-line
    of your work, and the kinds of organizations/problems you've worked in. This is
    the "elevator pitch" raw material.]
    
    ## Key Strength Areas
    
    For each strength, name it and give 2–4 concrete supporting facts.
    
    **[Strength area 1, e.g. "Product strategy"]**
    - [specific capability with evidence]
    - [specific capability with evidence]
    
    **[Strength area 2]**
    - [...]
    
    **[Strength area 3]**
    - [...]
    
    ---
    
    ## Professional Experience
    
    List every role that matters, most recent first. For each, capture more than the
    resume shows — the resume picks from this.
    
    ### [Company] — [Role] | [Dates]
    **Context:** [what the company does, team size, who you reported to, scope]
    **How you operated:** [the hats you wore, how you actually worked]
    **Key contributions:** [the 3–6 things you actually did, each with specifics]
    **Metrics / outcomes:** [real numbers — revenue, %, time saved, scale, headcount,
    funding. These are the payoffs your resume and letters lean on. If you don't have
    a number for something, leave it out rather than inventing one.]
    **Problems you were solving:** [the recurring hard problems — useful for "tell me
    about a time…" answers]
    
    ### [Company] — [Role] | [Dates]
    [repeat]
    
    ---
    
    ## Signature Stories
    
    These are the narrative set-pieces you return to. Each should be a real situation
    with a real outcome, told as a small story rather than a list of duties.
    
    ### The "0→1 / built it from nothing" story
    [A time you created structure, a product, a team, or a function where none
    existed. What was missing, what you built, what resulted.]
    
    ### The "deviated from standard process" story  *(important — most applications ask a version of this)*
    [A time you broke from the normal way of doing things because the situation
    demanded it — a compressed deadline, a scope change mid-flight, a constraint that
    made the standard playbook fail. What the standard approach would have been, what
    you did instead, and the outcome. This is the go-to answer for "tell us about a
    time you challenged the process / led through ambiguity / hit an impossible
    deadline." Make it specific and true.]
    
    ### The "I use what I build / practitioner" story (if applicable)
    [A time your hands-on, in-the-trenches experience of a problem made the work
    better — you weren't just designing/building for users, you were one.]
    
    ### [Any other recurring story you tell]
    [...]
    
    ---
    
    ## Personal Hooks & Passions (genuine connections — the FIRST place a cover letter looks)
    
    A real, specific, *documented* personal connection to a company, product, or
    domain makes the warmest cover-letter opener. List only authentic ones — things
    that are actually true of you. A forced or inflated hook is worse than none and
    reads as the opposite of your voice.
    
    - [e.g. "Long-time user of [product/category] since [year] — know it as a
      customer, not from a deck." Good hook for that category.]
    - [e.g. "[Genuine passion / cause / background] — confirmed true, not a stretch.
      Strong opener for companies in that space. Frame as authentic motivation, never
      as expertise you don't have."]
    - [e.g. "[Background / field you came from] — makes [adjacent industry] familiar
      territory."]
    - [Add every real one you can. Note for each what kind of role it fits.]
    
    ## Elevator Pitch (the fallback opener when no genuine hook fits)
    
    [1–2 sentences about you, recognizably the same person every time, that can open
    a letter when there's no authentic personal connection to lead with. Concrete and
    confident, not buzzwordy. e.g. "I'm a [what you are] with [N years] across
    [contexts] — [the two qualities you pair]. Right now I'm [current role/focus]."]
    
    ## Recurring Narrative Threads (your strongest reusable framings)
    
    The throughlines you come back to. Pick the one that matches a role's core
    problem.
    
    - **[Thread name]** — [the framing, and the real evidence that backs it]
    - **[Thread name]** — [...]
    
    ## Differentiators / Proof Points
    
    The specific, evidence-backed things that set you apart — deploy as evidence in
    letters and answers. Lead with real numbers as payoff.
    
    - [proof point with a real metric]
    - [proof point with a real metric]
    - [proof point]
    
    ---
    
    ## Honest Gaps
    
    An honest list of what you genuinely *can't* claim — domains, tools, scales, or
    experience you don't have. This isn't self-criticism; it's the truthfulness guard
    rail. When a role exposes one of these, the strongest move is to name it plainly
    in one sentence and pivot to a transferable strength — never to paper over it or
    invent adjacent experience. Knowing your real gaps up front is what lets the rest
    of the application stay confident and honest.
    
    - [gap — e.g. "No direct [domain] experience."]
    - [gap]
    - [gap]
    
    ---
    
    ## Education & Credentials
    
    - [Institution — Degree]
    - [Institution — Certificate / credential]
    
  • references/followup-and-negotiation.md4.0 KB8b21ef70bbeeupstream ↗
    # Follow-ups, Thank-yous & Offer Negotiation
    
    Two short, high-leverage moments that come *after* the application and interview, and
    share the kit's rules: written in the user's voice (`voice.md` +
    `references/writing-standards.md`), grounded only in what's true (`fact-pack.md` and what
    the user actually says), delivered copy-paste-ready, and **never auto-sent**. Both feed
    the tracker (`references/application-tracker.md`) and the living library.
    
    These are offered, not forced. Surface them at the natural moment — a thank-you right
    after a debrief, a status nudge when the tracker shows an application gone quiet, a
    negotiation brief when the user reports an offer.
    
    ---
    
    ## 1. The post-interview thank-you
    
    Send within ~24 hours of an interview. Its job isn't etiquette theater — it's one more
    honest, specific touch that reinforces fit.
    
    - **Specific, not generic.** Reference something real from *that conversation* — a
      problem the interviewer described, a point of genuine agreement, a question you've kept
      thinking about. "Thank you for your time" with nothing concrete is worse than nothing.
      Pull the specifics from the debrief transcript if there is one; otherwise ask the user
      for the one thing that stuck with them.
    - **Short.** 3–5 sentences. Warm, in their voice, no résumé recap.
    - **Optional repair.** If the debrief flagged an answer that landed weak, a thank-you is
      a clean place to add the one sentence they wish they'd said — honestly, briefly, not as
      a do-over essay.
    - **Per interviewer.** A panel gets a lightly distinct note each (same coordinated-
      evidence logic as cover letter + answers — don't send four identical notes).
    - Deliver copy-paste-ready; the human sends. Log it on the role's tracker record.
    
    ## 2. The status-check follow-up (the polite nudge)
    
    When the tracker shows an application or interview gone quiet past the normal window
    (~7–10 days, or past a date the recruiter named), offer a brief, low-pressure nudge:
    restate continued interest, reference the specific role, ask about timeline. One nudge,
    not a campaign — and never needy. If a recruiter gave a date, wait for it first. Mark the
    follow-up on the tracker so it isn't repeated.
    
    ---
    
    ## 3. Offer negotiation brief
    
    When the user reports an offer, help them think it through and respond well. This is
    advisory and truth-bound: **never fabricate a competing offer, a deadline, or a number**
    the user doesn't actually have — manufactured leverage is the same lie as a fabricated
    résumé, and it collapses just as badly.
    
    **Build a short brief, not a script to read robotically:**
    
    1. **Read the whole offer, not just base.** Base, bonus, equity (and what it's plausibly
       worth — note honestly when that's unknowable), benefits, start date, level/title.
    2. **Anchor to their real numbers.** Pull `compensation.target`/`floor` from
       `profile.json`. Where the offer sits relative to both is the spine of the brief. If
       they have genuine market data (their own past comp, a real range from the recruiter, a
       real other offer), use it; never invent one.
    3. **Find the honest levers.** What can truthfully move — base vs. a sign-on, level,
       start date, remote flexibility, a review timeline — and which the user actually cares
       about. Don't push them to negotiate things they don't want.
    4. **Draft the response in their voice** — appreciative, clear, specific: enthusiasm for
       the role, the one or two asks framed around fit and the value they bring (from
       `fact-pack.md`), never an ultimatum unless they truly have and mean one. Give the
       email/verbal version they'll actually be comfortable saying.
    5. **Know the walk-away.** Their `floor` is the honest line; name it plainly so they
       negotiate from a real position, and respect it if they say a number is fine.
    
    Deliver as a brief + a draftable message. The user decides and the user sends. Capture
    any durable new fact (their real floor moved, a market number they confirmed) to the
    library per `library_enrichment.mode`, and update the tracker (`status: "offer"`, then
    the outcome).
    
  • references/format-template.json1.5 KB9ab9f3968f76upstream ↗
    {
      "_comment": "Visual identity for your resume and cover letter. Onboarding writes a filled copy to user-library/format.json. Both generate_resume.py and build_cover_letter.py read it, so the two documents always look like a matched set. All keys are optional — anything omitted falls back to a clean default. Fonts must be installed on the machine that exports the PDF (LibreOffice); if a font is missing it silently substitutes, so prefer common fonts unless you know the font is present.",
    
      "name_font": "Georgia",
      "body_font": "Calibri",
    
      "text_color": "1A1A1A",
      "muted_color": "6B6B6B",
      "rule_color": "C8C8C8",
      "accent_color": "175DC9",
    
      "max_pages": 1,
    
      "_color_help": "Colors are 6-digit hex, no leading #. text_color = name/company/body (near-black reads best). muted_color = role titles, dates, contact line. rule_color = the hairline section dividers. accent_color = links (portfolio, projects, cover-letter website).",
      "_font_help": "name_font is the display font for the name only; body_font is everything else. Pick a name_font you actually have installed. Safe cross-platform display fonts: Georgia, Garamond, Cambria. Safe body fonts: Calibri, Arial, Helvetica.",
      "_max_pages_help": "Target resume length in pages (default 1). One page is right for most roles; set 2 for fields where a longer resume is standard (academic CV, federal, senior/technical). The RUN step passes this to page_count.py as --max-pages so the one-page loop enforces YOUR target, not a hardcoded 1."
    }
    
  • references/interview-prep.md16 KB2bb9e3c1b95eupstream ↗
    # Interview Prep Playbook
    
    The reference for **C. PREP**. Two deliverables — a **prep kit** (a written brief)
    and a **mock interview** (an interactive loop) — plus the round-by-round emphasis
    that shapes both. The governing principle is **continuity**: prep emphasizes the
    exact strengths the application positioned on and defends the exact gaps it logged,
    so the user stays consistent with what got them the call. Never generic advice.
    
    The never-fabricate rule applies here in full. In prep you are helping the user
    present *their real* material as well as possible — sharpening, reordering, and
    framing true experience. You never invent a story, metric, or credential to make an
    answer land, and when the user fumbles, you help them reshape something real, not
    substitute a better fiction.
    
    ---
    
    ## Inputs — gather before you start
    
    Pull as much of this as exists; prep degrades gracefully if some is missing.
    
    - **The JD** — ideally the original posting. In the application chat it's already in
      context; in a fresh chat, ask for it.
    - **The strategy/tailoring notes** — the positioning angle, the strengths surfaced,
      and the ATS hard-gaps recorded in the RUN report. This is the spine of the kit.
    - **`fact-pack.md`** — signature stories (incl. the "deviated from process" story and
      a failure/conflict story), metrics, elevator pitch, differentiators, honest gaps.
    - **`profile.json`** — comp target/floor, work auth, logistics answers.
    - **`resume_<company>.md`** — the tailored resume, if still around, shows exactly
      which lines were emphasized for this role.
    - **The round** — recruiter / hiring-manager / panel / portfolio / technical / final.
      Ask if unclear; default to hiring-manager behavioral.
    
    If there's no library yet, prep can still run thin off just the JD and whatever the
    user tells you — but say the kit will be sharper after onboarding.
    
    ---
    
    ## The prep kit — the eight parts
    
    Assemble these from the inputs above. Keep each tight; the whole kit should be
    phone-readable before an interview, not a research dossier. Deliver as chat text by
    default; offer a file only if the user wants something to keep.
    
    ### 1. Company & role refresher
    What the company does in plain terms, who it serves, and how this role fits. If you
    have web access and there may be recent news (funding, launches, leadership changes,
    layoffs), do a quick check so the user isn't blindsided — but don't pad with trivia.
    Then a plain read of what the role **actually owns and is measured on**, decoded from
    the JD's responsibilities (not its adjectives).
    
    ### 2. Your angle
    The one-line positioning the application led with, restated as the through line to
    hold across every answer. Everything else in the kit hangs off this.
    
    ### 3. Strengths to emphasize
    The 3–5 strongest alignments between the user's background and this role. For each:
    the claim, the proof point (a real metric or outcome from the fact pack), and the
    story to reach for if pressed. These are what the user steers toward.
    
    ### 4. Gaps to manage
    The honest gaps logged during the application, plus any new ones the JD implies. For
    each, a **prepared, non-defensive framing** — acknowledge plainly, bridge to adjacent
    real experience, show the learning curve is short. These are the "questions you're
    afraid of." Flag them as the highest-priority rehearsal targets. Never coach the user
    to bluff a gap — coach them to handle it honestly and move on.
    
    ### 5. Story bank, mapped
    Take the signature stories from `fact-pack.md` and **map each to the competencies
    this role screens for**, so the user knows which story answers which kind of question.
    Cover at minimum: a leadership/influence story, a conflict or disagreement story, a
    failure/what-I'd-do-differently story, and the "deviated from standard process"
    story (very commonly asked). Note the one-line STAR spine for each (Situation →
    Task → Action → Result) so they're recallable under pressure.
    
    ### 6. Predicted questions
    The behavioral and role-specific questions **this posting** is most likely to
    generate — derived from its responsibilities, its seniority, and the gaps — each with
    a one-line angle and which mapped story to reach for. Include the obvious openers
    ("walk me through your background", "why this company", "why leaving") plus 4–6
    role-specific ones. This is not a generic 50-question bank; it's the short list most
    likely to actually come up.
    
    ### 7. Questions to ask them
    Tiered by interviewer, because asking the right person the right thing reads as
    seniority:
    - **Recruiter** — process, timeline, comp range, what the team is solving for.
    - **Hiring manager** — what success looks like at 90 days / 1 year, the hardest part
      of the role, how decisions get made.
    - **Skip-level / exec** — strategy, where the team is headed, what would make this a
      great hire a year from now.
    Include 1–2 questions that quietly surface **red flags** (why the role is open, how
    the last person in it did, how the team handles disagreement).
    
    ### 8. Logistics & comp
    The user's target/floor from `profile.json`; how to **deflect an early comp
    question** (defer to range, redirect to fit) without stonewalling; and any format
    specifics they've shared (who they're meeting, how long, remote/onsite).
    
    ---
    
    ## Round-by-round emphasis
    
    The round reshapes which parts matter most:
    
    - **Recruiter screen** — lead with parts 2 (angle), 7 (comp/logistics questions), and
      the tight version of 1. Tighten the elevator pitch. Comp positioning matters here
      more than story depth.
    - **Hiring-manager / behavioral** — the core round. Parts 5 (mapped stories) and 4
      (gap defense) carry it. Drill STAR delivery.
    - **Panel / cross-functional** — emphasize breadth and working-style stories; prep a
      stakeholder-management and a cross-team-conflict story. Different panelists probe
      different competencies — map stories to each likely interviewer.
    - **Portfolio / case review** (design, eng, PM) — which work to lead with and why,
      how to narrate decisions and tradeoffs, and how to handle "what would you do
      differently." Pick 2–3 pieces that map to this role's problems; rehearse the
      narration, not just the artifacts.
    - **Technical / take-home** — scope expectations, what "good" looks like, and how to
      talk through tradeoffs out loud. Prep the user to state assumptions and reason
      aloud rather than chase a single right answer.
    - **Final / executive / skip-level** — vision, trajectory, culture-add, and smart
      upward questions (part 7, exec tier). Less "can you do the job," more "where are
      you taking it and do we want you in the room."
    
    ---
    
    ## The mock interview loop
    
    Run it like a real interview, not a quiz.
    
    1. **Set the frame.** State the round you're simulating and who you're playing ("I'll
       be the hiring manager for the Staff PM role"). Tell them you'll ask one question
       at a time and give feedback after each, and that they can tap out anytime.
    2. **One question at a time.** Ask, then **stop and wait** for their answer. Never
       stack questions or answer for them.
    3. **Feedback after each.** Brief and specific: what landed, what to tighten, whether
       they reached for the right story, whether a STAR answer had a real Result. Praise
       what's genuinely strong; don't manufacture praise.
    4. **Calibrate to the round** and lean into the **gap questions** — those are where
       reps matter most. Pull from the predicted-questions list; escalate difficulty as
       they warm up.
    5. **Hold the line on truth.** If they fumble or start inventing, stop and help them
       rebuild the answer from their *real* material. A polished lie rehearsed here
       detonates in the room.
    6. **Wrap.** After ~6–10 questions (or when they call it), give a short overall read:
       strongest answers, the 2–3 highest-leverage fixes, and any story that still needs
       sharpening before the real thing.
    
    Keep your interviewer turns short — the user should be doing most of the talking, as
    in a real interview.
    
    ---
    
    ## Closing the session
    
    Point the user to whichever deliverable they haven't used ("want to run the mock
    now?" / "want the written kit to take with you?"). Remind them prep is sharpest when
    run **from the application chat**, where the JD and strategy are already loaded. If
    the library was thin where it mattered (no failure story, a sparse story bank, gaps
    with no prepared framing), name it so they can enrich `fact-pack.md` before the next
    round — every prep session is a chance to make the library better.
    
    ---
    
    # The Debrief — learning from the real interview
    
    Prep gets the user ready; the debrief is how the kit gets *better* at preparing them.
    After a real interview, it grades what actually happened against the prep kit and feeds
    the result back into the library, so every interview sharpens the next one. This is the
    highest-value signal the kit ever receives — real performance under real pressure, not
    rehearsal.
    
    ## The hard input requirement: a transcript, or nothing
    
    The debrief runs on a **written transcript** of the actual interview. It does **not**
    run on the user's memory of how it went. A from-recollection recap is too lossy and too
    biased by the user's own in-the-moment impression — people misremember which questions
    were asked, overweight the one answer that felt awkward, and forget the three that
    landed. Grading that recap would produce confident, wrong feedback, which is worse than
    none. So: **no transcript → no debrief.** Say so plainly, and point them at the capture
    setup below so they have one next time. Don't offer a memory-based substitute.
    
    **Any accurate plain-text transcript works** — Meetily (recommended below), Otter,
    Fathom, the call platform's own captions (Zoom / Google Meet / Teams export), or a clean
    manual transcription. What matters is fidelity to what was actually said, not the tool;
    speaker labels help but aren't required. The user pastes the text in (or saves it to a
    file).
    
    ## Consent tier — check this before recommending recording
    
    Recording a call captures the other party's voice. Whether the user needs the other
    party's consent depends on where the recording takes place. Check
    `profile.json → interview_recording.consent_tier` before surfacing any recording
    recommendation:
    
    - **`one_party`** — only the user's own consent is required (most US states, including
      CO). Recommend Meetily freely; the caveat is a single line the first time, then drop
      it.
    - **`two_party`** — all parties must consent before recording begins. States in this
      category include CA, CT, FL, IL, MD, MA, MI, MT, NH, OR, PA, WA (and equivalents
      elsewhere — verify locally). **Almost never raise recording unprompted** when this
      tier is set. If the user brings it up or asks, surface the caveat first and leave
      the choice entirely with them: *"[State] requires all parties to consent before you
      record. If you disclose at the start of the call and get agreement, a tool like
      Meetily works well — but that disclosure is yours to make."* Do not push or repeat.
    - **`null` (unknown)** — ask before recommending. One question: *"What state (or
      country) are you recording in? That affects whether you can record without disclosing
      it."* Once they answer, apply the appropriate tier above and save `consent_tier` to
      `profile.json → interview_recording.consent_tier`.
    
    This is the user's legal call to make, not the kit's — flag it; don't police it.
    Don't refuse to process a transcript the user brings regardless of tier.
    
    ## Capturing the transcript — Meetily and alternatives
    
    **Any accurate plain-text transcript works** — Meetily (recommended for one-party
    users below), Otter, Fathom, the call platform's own captions (Zoom / Google Meet /
    Teams export), or a clean manual transcription. Speaker labels help but aren't
    required. The user pastes the text in (or saves it to a file and references the path).
    
    ### Meetily (recommended for one-party-consent users — free, discreet, local)
    
    When `consent_tier` is `one_party` and the user doesn't already have a tool set up,
    recommend Meetily: a free, open-source (MIT) notetaker that records and transcribes
    **locally on the user's own machine** with Whisper/Parakeet — no bot joins the call,
    no audio leaves the device, no account required. It's recommended because it's discreet
    (nothing shows up on the interviewer's end) and private (transcript stays on the user's
    machine). Two capture modes:
    
    - **Video call (Zoom / Google Meet / Teams):** Meetily taps **system audio**, so both
      the user and the interviewer come through cleanly from the same stream that reaches
      the speakers. No participant appears in the call. This is the high-fidelity path.
    - **Phone call:** a phone call's audio doesn't route through the computer, so put the
      call on **speakerphone** and let Meetily capture it through the laptop **mic**. The
      user's voice is clean; the interviewer's voice is whatever the phone speaker plays
      into the room. Practical tips: quiet room, phone volume up, phone close to the laptop
      mic, and **run a 60-second test recording beforehand** to confirm the speaker side
      transcribes legibly. Whisper handles speakerphone audio reasonably but is more
      sensitive to a noisy room than a direct stream.
    
    Either way the user exports the transcript as plain text and pastes it into the chat.
    Nothing is uploaded anywhere. When `consent_tier` is `two_party`, skip this
    recommendation unless the user explicitly asks; apply the caveat above first.
    
    ## Running the debrief
    
    With a transcript in hand:
    
    1. **Anchor to the prep kit.** Pull the predicted-questions list, the mapped stories,
       and the logged gaps from the prep session (or reconstruct them from the JD + library
       if this is a fresh chat). The debrief's whole value is grading *against what you
       prepped*, not generic critique.
    2. **Walk the transcript and assess:**
       - **Coverage** — which predicted questions actually came up, and which real questions
         the prep *failed* to predict (these are gold for next time).
       - **Answer quality** — for the questions that mattered, how did the answer land? Was
         there a real STAR arc with a concrete Result, or did it trail off? Did the user
         reach for the story the prep mapped, or grab a weaker one?
       - **Gap handling** — which logged gaps got probed, and did the prepared framing hold
         up under follow-up, or crumble?
       - **Signal from the other side** — where the interviewer leaned in, pushed back, went
         quiet, or redirected. Note it without over-reading a transcript.
    3. **Deliver a tight learning report**, not a transcript re-narration:
       - the 2–3 answers that landed strongest (and why, so they're repeatable);
       - the 2–3 highest-leverage fixes, each tied to a specific moment in the transcript
         and a concrete reshaping — what to say instead next time;
       - any story that underperformed and how to rebuild it (from real material only);
       - questions the prep missed, so they go into the bank.
       Keep it honest and specific. Praise what genuinely worked; don't manufacture
       encouragement, and don't pile on — the point is the next interview, not a grade.
    
    ## Enriching the library from a debrief
    
    Per "The library is a living system," the debrief writes back the most valuable updates
    the kit ever makes, because they're grounded in real performance:
    
    - **Underperforming stories** → flag in `fact-pack.md` for reshaping, with a note on
      *why* it didn't land (no clear result, too long, wrong emphasis).
    - **Unpredicted questions** → add to the predicted-question patterns so future prep for
      similar roles anticipates them.
    - **Gap-framings that failed** → rewrite the framing in the gap notes so next time it
      holds.
    - **A genuinely strong answer** → capture the version that worked, so it's reusable.
    
    Record only what the transcript actually supports — never infer a fact about the user to
    fill a gap. Apply the user's `library_enrichment.mode` (confirm vs. silent) as
    everywhere else. Over a job search, this is what turns the kit from a static helper into
    a system that measurably gets better at getting *this user* through interviews.
    
  • references/onboarding-interview.md7.5 KB422db7b9895fupstream ↗
    # Onboarding Interview — Quick & Thorough question sets
    
    This is the question bank the onboarding step (Step A in SKILL.md) draws on to
    build the user's library. Two depths; the user picks at runtime. Whatever the
    depth, **parse any uploaded resume / pasted LinkedIn or portfolio first** and only
    ask for what's genuinely missing — don't re-ask for things you can already read.
    Confirm everything back before writing the files.
    
    The goal of every question is to fill a specific library file:
    `profile.json`, `base_resume.md`, `fact-pack.md`, `voice.md`, `format.json`, and
    (optionally) `scanner_config.json`.
    
    ---
    
    ## QUICK path (~5 minutes)
    
    Best when the user uploads a resume. Parse it, then ask only the gaps.
    
    **Identity & profile (profile.json)**
    1. Confirm name, email, phone, location, and the personal website/portfolio URL
       I parsed — fix anything wrong, add what's missing.
    2. LinkedIn URL? Any other links (GitHub, portfolio) to keep on file?
    3. Are you authorized to work in [country], and do you now or will you in future
       need visa sponsorship?
    4. Comp target and floor (a number or a range — used only when a form demands one;
       "open" is fine).
    5. Anything you want pre-filled for the standard form questions (how you heard
       about roles, earliest start date, relocation/remote preference)? The EEO
       demographic questions are always optional — skip any you'd rather leave blank.
    
    **Resume content (base_resume.md)**
    6. I've drafted your master resume from what you uploaded — does the summary,
       the role list, and the skills look right? Anything understated or missing?
    
    **Stories & differentiators (fact-pack.md)**
    7. One real story where you **deviated from the standard process** — compressed
       deadline, mid-flight scope change, a constraint that broke the normal playbook.
       What was standard, what you did instead, the outcome. (Almost every application
       asks a version of this.)
    8. Any **genuine personal connections** to companies/products/domains you're
       targeting — something you actually use, a cause you actually care about, a field
       you came from? Only real ones.
    9. The 2–3 metrics or wins you're proudest of (real numbers).
    10. An honest list of gaps — domains/tools/scales you genuinely can't claim. (This
        keeps the rest of your application confident and truthful.)
    
    **Voice (voice.md)**
    11. Can you paste something you've written that sounds like you (an old cover
        letter you liked, a post, a detailed email)? If not, I'll capture your voice
        from how you write to me.
    
    **Format (format.json)**
    12. Any preference on the resume's look — a display font for your name, an accent
        color for links? Otherwise I'll use a clean default.
    
    ---
    
    ## THOROUGH path (~20 minutes)
    
    Best when there's no resume, or the user wants a richer fact pack and voice. Covers
    everything in QUICK, plus the following — ask conversationally, in batches, not as
    a rigid quiz.
    
    **Career history (base_resume.md + fact-pack.md)** — for each role, most recent
    first:
    - Company, what it does, your title, dates, team size, who you reported to.
    - What you actually owned and how you operated (the hats you wore).
    - The 3–6 concrete things you did, each with a real outcome or number.
    - The recurring hard problems you were solving (fuel for "tell me about a time…").
    
    **Strength areas (fact-pack.md)**
    - What are the 3–4 things you're genuinely best at? Two pieces of real evidence
      each.
    
    **Signature stories (fact-pack.md)** — get real, specific versions of:
    - The 0→1 / built-from-nothing story.
    - The deviated-from-process story (deadline / scope change / ambiguity).
    - The practitioner / "I use what I build" story, if you have one.
    - Any other story you find yourself telling.
    
    **Personal hooks & motivation (fact-pack.md)**
    - Products/categories you genuinely use and love; causes you actually care about;
      the field you came from. What kind of company would each be a real connection to?
    - Your reusable elevator pitch — 1–2 sentences about you, the same person every
      time, for when there's no specific hook to open with.
    
    **Voice (voice.md)** — capture from a sample if possible; otherwise dig in:
    - How would you describe the way you write? Show me a sentence you're proud of.
    - What kind of writing makes you cringe? (Their "never" list.)
    - Formal or casual? Humor or straight? Do you use dashes, short punchy lines, long
      flowing ones?
    
    **Format (format.json)**
    - Display font for your name, body font, accent color, or a vibe ("understated and
      serif" / "modern and clean"). I'll translate it into tokens.
    
    **Automation & browser apply (Step A3 — prompt for these, don't just mention them)**
    
    These are the high-leverage features; walk the user into setting them up.
    
    - *Scanner config (`scanner_config.json`).* Set up automated scanning?
      - Target roles and seniority levels (e.g. "Senior/Staff Product Designer").
      - Locations — remote, specific cities/states, US-only?
      - Comp floor (the number below which it's not worth surfacing).
      - The role *shape* you most want (founding / first-hire / 0→1 / generalist) and
        your priority vs. hard-no domains.
      - **Translate the config examples to THEIR field.** The `scanner_config.template.json`
        ships with role-neutral defaults plus example values phrased for one role (e.g.
        design: "first design hire", "founding designer", role-title regex around "product
        design"). Do NOT leave the design examples as-is for a non-design user. Rewrite every
        example slot to the user's actual profession before saving their `scanner_config.json`:
        - `role_keywords` / `role_title_regex` → their job titles (e.g. "growth marketing
          manager", "backend engineer", "staff nurse").
        - `shape_signals` → the equivalent shape language for THEIR role: add "founding
          engineer / first backend hire", "first PM / founding product manager", "first sales
          hire", "charge nurse / unit lead", etc., while keeping the role-neutral ones that
          already generalize ("founding", "first hire", "0 to 1", "generalist", "broad scope",
          "end-to-end ownership", "wear many hats", "build the X function").
        - `tier1/tier2/exclude` keywords → their domains and hard-nos.
        - For a non-US / non-USD search, set `accept_currencies` and `comp_band` to their
          currency (see the template's `_currency_note`).
        Confirm the rewritten lists back to the user before writing the file.
      - Any companies for the watchlist? (I'll find + verify their Greenhouse/Lever/Ashby
        slugs.)
      - Recency window and how many results per digest.
    - *Schedule.* I'll run it twice a day (~8am/4pm your time) and send a ranked
      shortlist — or pick your own cadence. (Confirm timezone.)
    - *Claude for Chrome extension.* This unlocks two things, so let's get it installed:
      (1) the logged-in **LinkedIn + Wellfound** browser pass in your scans — the only
      way to include those two — and (2) **browser fill & upload** of applications at the
      end of a run. Are you able to install it and stay signed in to those sites? If you
      skip it, scanning runs on the API sources only and applications hand back to you to
      submit.
    
    ---
    
    ## After either path
    
    1. Write the filled files into `user-library/` and **delete `NOT_ONBOARDED.md`**.
    2. Read back a concise confirmation: identity, the roles captured, the hooks and
       the deviated-from-process story, the gap list, and a 2–3 sentence pastiche in
       the captured voice ("does this sound like you?").
    3. Tell them they're set up and can now say e.g. "tailor my resume for this job"
       (paste a JD) or, if scanning was configured, "scan for jobs."
    
  • references/outreach-playbook.md8.6 KBbcd7d55b1991upstream ↗
    # Direct Outreach Playbook
    
    The reference for **D. OUTREACH**. After an application is in, a personal note to the
    right human can pull it out of the pile — but only when the fit is genuine. This
    governs *how* to find the person, reach them, and write the note. As everywhere in
    the kit, the user's `voice.md` and `fact-pack.md` govern *what* it says and *whose
    voice* it's in; nothing here is person-specific.
    
    The goal: one specific, confident, human message to one real person, proving the
    applicant read *this* role and has a real reason to want *this* job — never a
    templated blast.
    
    ---
    
    ## The tier gate — this is the most important rule
    
    Outreach works **because it's genuine**. The energy that makes a cold note land — "the
    overlap felt too perfect to leave to chance" — only exists when there's an actual
    connection: a real passion for the domain, a near-exact experience match, a personal
    hook to the product. Without that, the same note reads as forced and *hurts* the
    candidacy.
    
    So gate it by fit:
    
    - **Tier-1 (strong, genuine fit)** — recommend outreach proactively, and draft it
      without being asked. This is where it's worth the user's time and most likely to
      work. If a scan score is available, tier-1 ≈ the top band; standalone, judge it: does
      the user have a real hook to this company/role/domain in `fact-pack.md`?
    - **Tier-2 / Tier-3 (decent or weak fit, no genuine hook)** — **don't push it.** Offer
      only if the user asks, and be honest: without a real connection the note is weaker
      and a generic "I'd be great for this" cold email can read as spam. If they still want
      it, write the most honest version possible — never manufacture a passion or
      connection the user doesn't have. (The never-fabricate rule is absolute here too.)
    
    When you finish a tier-1 RUN, offer outreach as the natural next step. When it's
    tier-2/3, finish at the application and mention outreach is available if they have a
    personal angle worth playing.
    
    ---
    
    ## Two methods: email preferred, LinkedIn as fallback
    
    - **Email (preferred)** — highest hit rate, lands in a real inbox, carries a subject
      line and full message. Use whenever the address is findable and the user is willing
      to cold-email.
    - **LinkedIn message (fallback)** — when the email can't be found/verified, or the user
      would rather not cold-email. A shorter note (no subject line), same voice and hooks,
      trimmed to LinkedIn-message length. Still personal, still tier-gated.
    
    On a strong tier-1 role you can prepare **both** — email as the primary, a LinkedIn
    variant ready in case the address bounces or the user prefers it.
    
    ---
    
    ## Step 1 — Find the right person
    
    Use LinkedIn research (the Chrome extension, if available, or guide the user) to
    identify a **real named human**, not a generic address:
    
    - **Hiring manager** — the person the role most likely reports to (a design role → a
      Head/Director of Design; an eng role → an Eng Manager). Best for a "here's why I'm a
      fit" note.
    - **Recruiter** — the recruiter on the posting or a talent partner at the company.
      Best for a "just applied, is this still active, would you flag my application" note.
    - If both are findable, the **hiring manager** usually gets the stronger version of the
      note; a recruiter is the safer bet for "is this live" logistics.
    
    Never invent a name or title. If you can't confidently identify a person, say so and
    fall back to LinkedIn outreach to the most plausible contact, or skip.
    
    ## Step 2 — Get the email address
    
    Email deduction is **probabilistic — be honest about that**:
    
    - Find the company's email **format** — via hunter.io in the browser (the user's manual
      flow), or by inferring the pattern from any one known company address
      (`first@`, `first.last@`, `flast@`, `firstl@`). Apply that pattern to the person's
      name.
    - **Flag the confidence.** Tell the user whether the address is verified (hunter.io
      confirmed) or deduced (pattern-inferred and may bounce). Never present a guessed
      address as confirmed. Suggest a verification pass if it matters.
    - **Optional upgrade:** hunter.io's API (free tier covers a small monthly volume) can
      *verify* an address rather than guess — note this to power users who want a higher hit
      rate, but the browser/manual flow is the default and needs no key.
    
    If the address can't be found or verified and the user isn't comfortable sending to a
    deduced address, switch to the **LinkedIn** method.
    
    ## Step 3 — Write the note (in the user's voice)
    
    Load `voice.md` and hold it for every line — and load `cover-letter-playbook.md` too:
    the opener hierarchy and the **anti-staccato rule** (flowing sentences, not clipped
    fragments-for-effect — the #1 machine-written tell) apply here as much as in a cover
    letter. Ground every claim in `fact-pack.md`. The note must read like the user wrote
    it on a good day, not like AI cold-email.
    
    ### The structure (adapt it — don't stamp it)
    
    This is a decoded pattern that works, **not a fill-in-the-blanks template.** Shape it to
    the individual user's voice, material, and what they have prepped. A user with a dry,
    minimal voice should get a shorter, plainer note than a warm conversational one. If the
    user's `voice.md` points away from any move below, follow the voice.
    
    **Subject line (email).** The strongest subjects stack a few identity hooks that each
    map to something the role wants, then close with earned confidence. A working formula:
    
    > `[personal connection or passion] · [hard technical/experience match] · [way of
    > working or soft skill that maps to the JD] … [a confident line that this role fits]`
    
    The point isn't the exact punctuation — it's that the subject does three things fast:
    signals a genuine hook, signals a hard-skill match, and conveys real (not boastful)
    confidence. Pull the three hooks from the actual overlap between `fact-pack.md` and
    this JD. If the user has only one genuine hook, use one — a true single hook beats three
    stretched ones.
    
    **Body — a tight arc, ~4–5 short paragraphs:**
    
    1. **Open human.** Note that they applied and are reaching out directly; it's fine to
       name the slight discomfort of cold-emailing — it disarms and reads as honest. One or
       two sentences.
    2. **The proof, specific.** The one or two strongest *genuine* overlaps — ideally one
       personal/passion hook and one hard experience match — each concrete and drawn from
       real history. This is the paragraph that does the work; it must be unfakeable
       specifics, not adjectives. A framing like "two things rarely line up this cleanly"
       can set it up, but only if the two things are real.
    3. **Soft ask + proof link.** A low-pressure "if the fit looks as strong on your end,
       I'd love to connect," plus a portfolio/relevant link if they have one.
    4. **Sign off** in their normal style.
    
    Keep it short — a recruiter or HM skims on a phone. Every sentence earns its place.
    
    ### LinkedIn variant
    
    Same hooks and voice, no subject line, trimmed to a few sentences (LinkedIn truncates
    and people read it as a message, not a letter): a one-line who/why, the single
    strongest genuine overlap, a soft connect ask. Warm, brief, direct.
    
    ## Step 4 — Deliver, never auto-send
    
    Output the email (subject + body) and/or LinkedIn message as **copy-paste-ready chat
    text**, clearly labeled, with the target person, their inferred email + a confidence
    note, and which method you'd lead with. Optionally save the email as a file if the user
    wants to keep it.
    
    **Stop before send.** Cold outreach must always be the user pressing send on something
    genuinely personal — never auto-sent. Auto-sent cold email is where deliverability
    collapses and personalized outreach turns into spam, which is against the spirit of the
    whole move. (If the user has Gmail connected and explicitly asks you to draft it into a
    Gmail *draft* for them to review and send, that's fine — but the human sends.)
    
    ## Step 5 — Enrich the library
    
    Per "The library is a living system," capture anything true that surfaced — a personal
    hook the user named that wasn't in `fact-pack.md`, a company they're especially excited
    about — using their `library_enrichment.mode`. Record only what they actually said.
    
    ---
    
    ## Why tier-gating and never-fabricate matter most here
    
    Outreach is the highest-trust, highest-risk move in the kit: it goes straight to a
    human, unmediated by a form. A great genuine note opens doors; a manufactured one (a
    faked passion, an invented connection, a guessed address presented as real) burns a
    contact and the user's name with them. So the bar is the same as everywhere, just
    higher-stakes: only real hooks, only honest confidence about the email, only on roles
    where the fit is genuine, and always the human's finger on send.
    
  • references/profile-template.json2.4 KB557b981cf4abupstream ↗
    {
      "_comment": "Your standing application profile. Onboarding writes a filled copy to user-library/profile.json. It holds your contact identity, links, and the standard answers nearly every application form asks for, so the browser auto-fill module can complete them without re-interviewing you each time. No role-specific content lives here.",
    
      "name": "",
      "email": "",
      "phone": "",
      "location": "",
      "website": "",
      "website_url": "",
    
      "links": {
        "linkedin": "",
        "portfolio": "",
        "github": "",
        "other": ""
      },
    
      "work_authorization": {
        "authorized_to_work_in_country": "",
        "requires_sponsorship": null,
        "notes": ""
      },
    
      "compensation": {
        "target": null,
        "floor": null,
        "currency": "USD",
        "notes": "What to put when a form demands a number. Leave a range or 'open' if you prefer not to anchor."
      },
    
      "standard_form_answers": {
        "_comment": "Verbatim answers to the recurring single-value questions on application forms. Fill what applies; leave blanks for ones you'd rather answer per-application.",
        "how_did_you_hear": "",
        "earliest_start_date": "",
        "willing_to_relocate": null,
        "remote_preference": "",
        "pronouns": "",
        "gender": "",
        "race_ethnicity": "",
        "veteran_status": "",
        "disability_status": "",
        "require_visa_now_or_future": null,
        "previously_employed_here": null
      },
    
      "library_enrichment": {
        "_comment": "How the kit handles new true facts about you that surface during a run (a real metric you mention, a story not yet in the fact pack, a refined role preference). 'confirm' (default) asks before saving anything. 'silent' lets the kit auto-save clearly-true additions without asking, and only checks in on ambiguous ones. Either way it NEVER invents or infers a fact you didn't actually state.",
        "mode": "confirm"
      },
    
      "interview_recording": {
        "_comment": "Tool you use to transcribe interviews for the debrief step. Set tool to the app name (e.g. 'meetily', 'otter', 'fathom', 'zoom') or null if not set up. consent_tier is derived from your recording location: 'one_party' means only your own consent is required (most US states); 'two_party' means all parties must consent before recording (CA, CT, FL, IL, MD, MA, MI, MT, NH, OR, PA, WA and others — verify for your jurisdiction). Onboarding sets both fields; update if you move or change tools.",
        "tool": null,
        "consent_tier": null
      }
    }
    
  • references/scanner-scheduled-task.template.md7.9 KB04bb14b955fbupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • references/scanner_config.template.json11 KB6aa5d6e68d33upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • references/scheduling.md10 KBceb75977f03bupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • references/voice-template.md4.5 KBb74af8442fe8upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • references/writing-standards.md8.5 KB961912c71357upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • .gitignore18 B5a77bd0439b6upstream ↗
    .DS_Store
    .vercel
    
  • .vercelignore54 Bc9fb33c5cf72upstream ↗
    .DS_Store
    SKILL.md
    references/
    scripts/
    user-library/
    
  • files/open-to-work.skill115 KBe811cb088232upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • index.html54 KB23b49f587bbfupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • LICENSE1.0 KB83b0a4c37952upstream ↗
    MIT License
    
    Copyright (c) 2026 rwtibbs
    
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.
    
  • user-library/NOT_ONBOARDED.md1.1 KB754f2b715bf0upstream ↗
    # Not onboarded yet
    
    This folder is where **your** personal job-application files live. It's empty
    because you haven't been onboarded yet.
    
    The presence of this `NOT_ONBOARDED.md` file is how the skill knows this is your
    **first run**. The first time you use it, the skill briefly explains what it does
    and what you'll need to provide, then kicks off **onboarding** — a ~5 or ~20 minute
    setup that builds:
    
    - `profile.json` — your contact info, links, work authorization, and the standard
      answers application forms ask for
    - `base_resume.md` — your master resume
    - `fact-pack.md` — your real roles, metrics, stories, hooks, and honest gaps
    - `voice.md` — how you write, so cover letters sound like you
    - `format.json` — your resume's fonts and colors
    - `scanner_config.json` + `seen_postings.json` — optional, only if you set up job
      scanning
    
    To get started, just say **"onboard me"** (or paste a job description and the skill
    will offer to set you up first).
    
    Once onboarding finishes, this file is deleted and your real library files take its
    place. Everything in this folder stays on your own machine — see the privacy note
    in the README.
    
  • vercel.json1.1 KB8de395d48f82upstream ↗
    {
      "cleanUrls": true,
      "trailingSlash": false,
      "headers": [
        {
          "source": "/(.*)",
          "headers": [
            {
              "key": "X-Frame-Options",
              "value": "DENY"
            },
            {
              "key": "X-Content-Type-Options",
              "value": "nosniff"
            },
            {
              "key": "Referrer-Policy",
              "value": "strict-origin-when-cross-origin"
            },
            {
              "key": "Permissions-Policy",
              "value": "geolocation=(), microphone=(), camera=()"
            },
            {
              "key": "Strict-Transport-Security",
              "value": "max-age=31536000; includeSubDomains; preload"
            },
            {
              "key": "Content-Security-Policy",
              "value": "default-src 'self'; script-src 'self' 'unsafe-inline' https://*.clarity.ms; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data: https://c.bing.com https://*.clarity.ms; connect-src 'self' https://*.clarity.ms https://c.bing.com https://vitals.vercel-insights.com; worker-src blob:; frame-ancestors 'none'"
            }
          ]
        }
      ]
    }
    

Plain-text copy, no login: /skill-bundles/rwtibbs-open-to-work.md

// REPO STATS

8 stars
0 open issues
Last commit: 4mo ago