applicator

# Agents — Workflow Reference

Agents in Applicator act on instruction. They do not run autonomously. The user triggers a workflow by pointing the agent at a job — the agent then extracts, tailors, and writes output files.

---

## Entry point

`new_job.sh` always runs first (human-triggered). It creates the folder structure, copies or moves the raw file to `raw/`, and writes a skeleton `details.json`. The agent starts after that — the folder exists, the raw material is there, the agent fills in the rest.

For a fresh clone, `scripts/setup_user.py` runs before the first application.
It collects the user's contact details, role focus, location/remote preferences,
compensation constraints, availability, languages, and basic profile metadata,
then writes `user/profile.json`, `user/details.md`, `user/looking-for.md`,
`user/requirements.json`, and CV headers. `user/profile.json` is the structured
source of truth for identity, contact data, profile headline, application
languages, and artifact filename slug. If a user brings an old CV, transfer it into
`user/files/cv/cv.{lang}.md` first, then split durable sections into the LaTeX
fragments under `user/files/cv/{lang}/` only after the Markdown source reads
correctly.

Newly captured job materials live in `_new/` first. When material is adopted into a specific application folder, it must be moved into that folder's `raw/` directory and removed from `_new/`. Use `new_job.sh` for the first raw file of a new application, and `scripts/adopt_new_material.sh` for additional `_new` files that belong to an existing application.

Application folders are physically grouped below `applications/preparation`, `applications/running`, `applications/closed`, `applications/deferred`, and `applications/archive`. New applications start in `preparation`. When changing `status.stage`, use `scripts/set_application_stage.sh <application-dir> <stage> [notes]` so the JSON history and folder location stay synchronized. Use `scripts/defer_application.sh <secondary-dir> <primary-dir> [priority] [notes]` for same-company alternatives that should wait for a primary application outcome. Use `scripts/reject_application.sh <primary-dir> [notes]` when rejecting a primary application that may have deferred alternatives. Use `scripts/archive_application.sh <application-dir> [notes]` for applications that should be kept for reference but hidden from dashboard rows. Use `scripts/organize_applications.sh` to repair or migrate folder placement from existing `details.json` stages.

## Inputs

| File | Purpose |
|---|---|
| `_new/*` | Inbox for newly captured job materials before they are adopted into an application folder |
| `raw/*` | Original job posting file — primary input, read-only |
| `emails/*` | Curated summaries of email communication; each summary links to the original `.eml` in `raw/` |
| `description.md` | Plaintext version of the posting (auto-copied if raw file is text-based) |
| `user/profile.json` | Structured applicant identity, contact details, headline, language list, artifact filename slug |
| `user/details.md` | Applicant profile — background, experience, skills |
| `user/looking-for.md` | Preferences and dealbreakers — informs tailoring decisions |
| `user/requirements.json` | Structured requirements (salary floor, remote minimum, etc.) |
| `user/skills.md` | Skill inventory for targeted coverage beyond the standard CV |
| `user/skill-gaps.md` | Negative and pending skill inventory for honest match scoring |
| `user/files/cv/cv.{lang}.md` | CV in the target language — source for tailoring |
| `user/files/cover-letter/cover-letter.{lang}.tex` | Cover letter template |
| `user/documents/*.{lang}.md` | Supporting documents (interim reports, references, etc.) |
| `details.json` | Current application state — read before writing |

Documents are loaded lazily — only when needed. Always prefer the job language variant; fall back to `en` if the target language file does not exist.
Files named `example-*` are starter examples only. Do not use them as evidence
in real application materials; replace or delete them during setup.

Do not parse identity or contact fields from Markdown headings. Use
`user/profile.json` for full name, email, phone, links, language preferences, and
artifact slugs. `user/details.md` is free-form evidence for match scoring and
document writing only.

Email convention: put original email files in `raw/` through `new_job.sh` or `scripts/adopt_new_material.sh`; do not cite Desktop/Downloads paths in persistent notes. Summarize emails in `emails/YYYY-MM-DD_short-subject.md` and list them in `emails/index.json`. Keep `meetings/` for actual scheduled conversations only.

Meeting convention: list each actual conversation only once in `meetings/index.json`, even when separate raw-note or reconstruction files exist for it. Every indexed meeting uses `status: scheduled`, `status: completed`, or `status: cancelled`. Change the status when the appointment happens or is cancelled. Dashboard and Excel counts include only `completed` entries; scheduled and cancelled appointments remain documented without increasing the meeting count.

Index schemas: `emails/index.json` follows `schemas/emails.schema.json` and uses `date`, `direction`, `subject`, `contact`, `file`, `raw`, and optional `related_raw`. `meetings/index.json` follows `schemas/meetings.schema.json` and uses `date`, `title`, `file`, `type`, `status`, plus optional `contact` and `notes`. Run `scripts/validate_indexes.py` after changing either index.

---

## Workflow: New Job Application

### Step 1 — Extract structured data

Read `raw/` contents (preferred — full original) or `description.md` (text fallback). Extract everything that maps to `details.json` fields:

- Job title, company, location, country, remote policy
- Travel requirement (as percentage)
- Compensation range (if stated)
- Contact person (if named)
- Application language (infer from posting language, confirm with user if unclear)

Write extracted data to `details.json`. Set `status.stage` to `open` if not yet applied. If submitting now, run `scripts/set_application_stage.sh <application-dir> applied "..."` after writing details so the application moves from `preparation` to `running`.

For the job title, preserve the raw title in `extensions.job_title_raw` when the posting contains marketing suffixes, gender markers, IDs, or location fluff. Use the cleaned, application-facing title in `job.title` when the cleanup is obvious, for example stripping `(m/w/d)`, `Jobs Tirol`, `Kennziffer ...`, or duplicated location text. Keep meaningful specialization or domain phrases if they are part of the actual role title. If it is unclear whether a phrase is part of the real title or just fluff, keep it and note the ambiguity in `extensions`.

Do not invent data. If a field is not stated in the posting, leave it `null`.

### Step 2 — Assess match

Compare the job requirements against `user/details.md`, `user/skills.md`, `user/skill-gaps.md`, and `user/requirements.json`:

- Score the match (0–100) — be honest, not optimistic
- List concrete strengths (where the applicant clearly fits)
- List concrete gaps (missing skills, wrong seniority, etc.)
- If a requirement is covered in `user/skills.md`, do not list it as a gap just because it is absent from the standard CV
- If a required or nice-to-have skill is not clearly covered in `user/details.md`, `user/skills.md`, CV sources, supporting documents, or `user/skill-gaps.md`, ask the user before final scoring and tailoring
- If the user confirms the skill is covered, update `user/skills.md`; if the user confirms it is not covered, update `user/skill-gaps.md`
- Confirmed gaps in `user/skill-gaps.md` must affect the match score based on how central the skill is to the job

Write to `details.json` under `match`.

### Step 3 — Load source documents

Determine `job.language` from `details.json`.

Load in order:
1. `user/files/cv/cv.{lang}.md` — fallback to `cv.en.md`
2. Relevant documents from `user/documents/` in the target language — fallback to `en`

Only load what is needed for the tailoring. Do not load PDFs.

### Step 4 — Tailor CV

Using the loaded CV and the job description:

- Reorder or re-weight experience sections to match the role
- Adjust skill emphasis to mirror the posting's language and priorities
- Use `user/skills.md` to decide whether requested tools/skills deserve CV space; include them when they are central enough for screening or keyword coverage
- Do not fabricate experience or inflate responsibilities
- Keep the applicant's voice consistent
- For German LaTeX output, write natural German with real umlauts and `ß` (`möchten`, `für`, `über`, `schließe`, `Grüßen`). Do not use ASCII transliterations like `moechten`, `fuer`, `ueber`, or `Gruesse` in prose.
- The tailored CV must render to exactly one well-filled page. Use the available page space for relevant work, projects, thesis topics, measurable results, and job-specific evidence; do not make the CV sparse just to be safe. Cut only as much as strictly necessary: first tighten wording and prioritization, then make small layout-preserving adjustments, and remove relevant content only when the rendered PDF would otherwise spill to page 2.

Write the result to `build/cv.{lang}.tex`.

### Step 5 — Tailor cover letter

Using the cover letter template and the job description:

- Address the specific role and company
- Reference concrete experience that maps to stated requirements
- Use `user/skills.md` to cover requested tools/skills that are relevant but too narrow for the one-page CV
- Address gaps proactively if the match score has significant weaknesses
- Match the tone of the posting (formal DE vs. casual EN startup, etc.)
- For German LaTeX output, write natural German with real umlauts and `ß` (`möchten`, `für`, `über`, `schließe`, `Grüßen`). Do not use ASCII transliterations like `moechten`, `fuer`, `ueber`, or `Gruesse` in prose.

Write the result to `build/cover-letter.{lang}.tex`.

### Step 6 — Render artifacts

Before rendering a German application, scan the generated `.tex` files for common ASCII transliterations in prose (`ae`, `oe`, `ue`, `ss` in words such as `moechten`, `fuer`, `ueber`, `schliesse`, `Gruessen`) and correct them to proper German spelling where applicable.

Run the project renderer after both LaTeX sources have been written:

```sh
./scripts/render-tex.sh <application-dir>
```

The renderer compiles every `.tex` file in `build/`, writes final PDFs to `artifacts/`, and keeps compile logs in `bin/{job-name}/`. If rendering fails, do not try to patch around the script; report the failing file and log path so the user can inspect the LaTeX error.

After rendering, verify the generated CV PDF page count and visual density. If the CV has more than one page, shorten `build/cv.{lang}.tex` by the smallest necessary amount, render again, and repeat until the CV is one page. If the CV is one page but leaves substantial blank space, restore relevant work/project details and render again so the page is used well without overlap.

### Step 7 — Prepare submission

Determine the submission channel from the posting.

- For applications submitted by email, write a complete, send-ready draft to `artifacts/submission-email.{lang}.md`. It must include recipient, subject, body, and the exact artifact filenames to attach. Record the file in `details.json` under `documents.other` and record the submission method in `extensions.submission_method`.
- Keep the final unsent submission email in `artifacts/`; only actual sent or received communication belongs in `emails/`.
- For application portals, record the portal URL and any required form responses or submission notes in `extensions`.
- An application may only have `status.stage: ready` when all materials required for its actual submission channel are complete. For an email application, CV and cover letter PDFs alone are not sufficient: the send-ready email draft is mandatory.

### Step 8 — Report

Tell the user:
- What was extracted and written to `details.json`
- What tailoring decisions were made and why
- Whether rendering succeeded, which PDFs were written, or where the failing logs are
- Anything that could not be resolved confidently (flag, do not guess)
- Whether any fallback language was used

---

## Workflow: Status Update

When the user reports a new stage (interview scheduled, offer received, rejected):

1. Read current `details.json`
2. Run `scripts/set_application_stage.sh <application-dir> <stage> "notes"` instead of editing the status manually
3. The script updates `status.stage`, appends to `status.history`:
   ```json
   { "date": "YYYY-MM-DD", "stage": "interview", "notes": "..." }
   ```
4. The script updates `meta.updated` to today and moves the folder:
   - `prospecting`, `reaching_out`, `open`, `ready` → `applications/preparation/`
   - `applied`, `screening`, `interview`, `assessment`, `offer`, `negotiation` → `applications/running/`
   - `accepted`, `rejected`, `withdrawn`, `ghosted` → `applications/closed/`
   - `deferred` → `applications/deferred/`
   - `archived` → `applications/archive/`

---

## Workflow: Callbacks

Use `details.json.callbacks` for expected follow-ups and reminders that should surface in the dashboard. A job may have multiple callbacks, for example one expected feedback deadline and one later technical-interview deadline.

Each callback should include:

- `id`: stable per-application identifier
- `kind`: `follow_up`, `expected_feedback`, `interview`, `technical_interview`, `assessment`, `prepare`, or `other`
- `status`: `open`, `resolved`, or `cancelled`
- `created`: date the callback was recorded
- `due`: date from which the dashboard should show it as an action
- `expected_from` / `expected_to`: optional expected window
- `action`: concrete user-facing action
- `source` and `notes`: short context
- `priority`: `low`, `normal`, or `high`

When a callback is satisfied by an email, interview, status transition, user report, or manual follow-up, update it to `resolved`, set `resolved` to the date, and write a concrete `resolution_note`, for example `"Nachfrage an Jakob geschickt"` or `"Feedback erhalten: Technical Interview terminiert"`. When a callback no longer applies, set it to `cancelled`, set `resolved`, and write a `resolution_note` that explains why. Do not leave stale `open` callbacks after the application moves out of `running`.

---

## Language Fallback

```
Requested language: de
  → look for cv.de.md           found → use it
  → look for cv.de.md           missing → use cv.en.md, note the fallback in report

EN variant must always exist. DE is optional.
```

---

## Rules

- Work only when instructed — no autonomous runs
- Before publishing or after changing schemas/workflow scripts, run `scripts/validate_project.py`
- Render PDFs at the end of a successful tailoring run by calling `./scripts/render-tex.sh <application-dir>`
- Keep `_new/` as an inbox only; once job material belongs to a specific application, move it to that application's `raw/` and remove the `_new` copy
- Keep original `.eml` files in `raw/`; write readable email summaries and communication state to `emails/`, not `meetings/`
- Keep application folder placement synchronized with `status.stage` by using `scripts/set_application_stage.sh`, `scripts/defer_application.sh`, `scripts/reject_application.sh`, or `scripts/archive_application.sh`; do not hand-move status transitions unless the user explicitly asks
- German prose in generated `.tex` files must use UTF-8 umlauts and `ß`; ASCII-only spelling is only for filenames, URLs, code identifiers, commands, and other technical literals
- Generated CV PDFs must be one well-filled page; verify page count and visual density after rendering and iterate if needed
- Do not mark an email application `ready` until `artifacts/submission-email.{lang}.md` exists and contains recipient, subject, body, and exact attachment filenames
- Never mention salary, salary expectations, compensation requirements, or salary limits in initial application materials or first-contact messages
- Never describe a CV, resume, cover letter, or other application document as "tailored", "customized", "zugeschnitten", or "angepasst" in applicant-facing materials
- Never modify `user/` files without explicit instruction
- Never write to `raw/` except when adopting job material from `_new/` via `new_job.sh` or `scripts/adopt_new_material.sh`; after adoption, `raw/` is read-only reference material
- Salary and compensation fields: only write what is explicitly stated in the posting
- `meta.version` is never changed by the agent