@forwardimpact/basecamp 2.4.2 → 2.6.0

package/template/.claude/skills/synthesize-deck/scripts/extract-pptx.mjs

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+/**
+ * Extract text from PowerPoint (.pptx) slides.
+ *
+ * PPTX files are ZIP archives containing XML. This script extracts all text
+ * from each slide and outputs it as structured markdown with slide headings.
+ * Handles multiple files and outputs to stdout or a file.
+ *
+ * Usage:
+ *   node scripts/extract-pptx.mjs <path-to-pptx>
+ *   node scripts/extract-pptx.mjs <path-to-pptx> -o /tmp/extract.txt
+ *   node scripts/extract-pptx.mjs file1.pptx file2.pptx
+ *   node scripts/extract-pptx.mjs -h|--help
+ *
+ * No external dependencies — uses Node.js built-in modules only.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { basename } from "node:path";
+
+const HELP = `extract-pptx — extract slide text from .pptx files
+
+Usage:
+  node scripts/extract-pptx.mjs <file.pptx> [file2.pptx ...]
+  node scripts/extract-pptx.mjs <file.pptx> -o <output.txt>
+  node scripts/extract-pptx.mjs -h|--help
+
+Options:
+  -o <path>   Write output to file instead of stdout
+  -h, --help  Show this help
+
+Output: Markdown-formatted text with ## Slide N headings per slide.
+Multiple files get # Deck: filename.pptx headings.`;
+
+if (
+  process.argv.includes("-h") ||
+  process.argv.includes("--help") ||
+  process.argv.length < 3
+) {
+  console.log(HELP);
+  process.exit(process.argv.length < 3 ? 1 : 0);
+}
+
+// --- Parse arguments ---
+
+const args = process.argv.slice(2);
+let outputPath = null;
+const files = [];
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "-o" && i + 1 < args.length) {
+    outputPath = args[++i];
+  } else if (!args[i].startsWith("-")) {
+    files.push(args[i]);
+  }
+}
+
+if (files.length === 0) {
+  console.error("Error: no .pptx files provided");
+  process.exit(1);
+}
+
+// --- ZIP parsing (no dependencies) ---
+
+/**
+ * Parse a ZIP file's central directory to extract file entries.
+ * @param {Buffer} buf
+ * @returns {Array<{name: string, offset: number, compressedSize: number, compressionMethod: number}>}
+ */
+function parseZipEntries(buf) {
+  // Find End of Central Directory record (signature 0x06054b50)
+  let eocdOffset = -1;
+  for (let i = buf.length - 22; i >= 0; i--) {
+    if (
+      buf[i] === 0x50 &&
+      buf[i + 1] === 0x4b &&
+      buf[i + 2] === 0x05 &&
+      buf[i + 3] === 0x06
+    ) {
+      eocdOffset = i;
+      break;
+    }
+  }
+  if (eocdOffset === -1) throw new Error("Not a valid ZIP file");
+
+  const cdOffset = buf.readUInt32LE(eocdOffset + 16);
+  const cdEntries = buf.readUInt16LE(eocdOffset + 10);
+
+  const entries = [];
+  let pos = cdOffset;
+
+  for (let e = 0; e < cdEntries; e++) {
+    // Central directory file header signature: 0x02014b50
+    if (buf.readUInt32LE(pos) !== 0x02014b50) break;
+
+    const compressionMethod = buf.readUInt16LE(pos + 10);
+    const compressedSize = buf.readUInt32LE(pos + 20);
+    const nameLen = buf.readUInt16LE(pos + 28);
+    const extraLen = buf.readUInt16LE(pos + 30);
+    const commentLen = buf.readUInt16LE(pos + 32);
+    const localHeaderOffset = buf.readUInt32LE(pos + 42);
+    const name = buf.toString("utf8", pos + 46, pos + 46 + nameLen);
+
+    entries.push({
+      name,
+      offset: localHeaderOffset,
+      compressedSize,
+      compressionMethod,
+    });
+    pos += 46 + nameLen + extraLen + commentLen;
+  }
+
+  return entries;
+}
+
+const { inflateRawSync } = await import("node:zlib");
+
+/**
+ * Read the uncompressed content of a ZIP entry.
+ * @param {Buffer} buf
+ * @param {{offset: number, compressedSize: number, compressionMethod: number}} entry
+ * @returns {Buffer}
+ */
+function readEntry(buf, entry) {
+  const pos = entry.offset;
+  const nameLen = buf.readUInt16LE(pos + 26);
+  const extraLen = buf.readUInt16LE(pos + 28);
+  const dataStart = pos + 30 + nameLen + extraLen;
+  const raw = buf.subarray(dataStart, dataStart + entry.compressedSize);
+
+  if (entry.compressionMethod === 0) return raw;
+  if (entry.compressionMethod === 8) return inflateRawSync(raw);
+  throw new Error(
+    `Unsupported compression method ${entry.compressionMethod} for ${entry.name}`,
+  );
+}
+
+/**
+ * Extract all text content from slide XML using the DrawingML namespace.
+ * Matches <a:t>text</a:t> elements used by PowerPoint.
+ * @param {string} xml
+ * @returns {string[]}
+ */
+function extractTextFromXml(xml) {
+  const texts = [];
+  const re = /<a:t>([^<]*)<\/a:t>/g;
+  let match;
+  while ((match = re.exec(xml)) !== null) {
+    const text = match[1].trim();
+    if (text) texts.push(text);
+  }
+  return texts;
+}
+
+/**
+ * Extract slide text from a .pptx file.
+ * @param {string} filePath
+ * @returns {string} Markdown-formatted slide text
+ */
+function extractPptx(filePath) {
+  const buf = readFileSync(filePath);
+  const entries = parseZipEntries(buf);
+
+  // Find slide XML files and sort by slide number
+  const slideEntries = entries
+    .filter(
+      (e) => e.name.startsWith("ppt/slides/slide") && e.name.endsWith(".xml"),
+    )
+    .sort((a, b) => {
+      const numA = parseInt(a.name.match(/(\d+)/)?.[1] || "0", 10);
+      const numB = parseInt(b.name.match(/(\d+)/)?.[1] || "0", 10);
+      return numA - numB;
+    });
+
+  const lines = [];
+
+  for (const entry of slideEntries) {
+    const xml = readEntry(buf, entry).toString("utf8");
+    const texts = extractTextFromXml(xml);
+
+    if (texts.length > 0) {
+      const num = entry.name.match(/(\d+)/)?.[1] || "?";
+      lines.push(`## Slide ${num}`);
+      lines.push(texts.join("\n"));
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n");
+}
+
+// --- Main ---
+
+const outputs = [];
+
+for (const file of files) {
+  if (files.length > 1) {
+    outputs.push(`# Deck: ${basename(file)}\n`);
+  }
+  outputs.push(extractPptx(file));
+}
+
+const result = outputs.join("\n");
+
+if (outputPath) {
+  writeFileSync(outputPath, result);
+  console.log(`Extracted ${files.length} deck(s) → ${outputPath}`);
+} else {
+  process.stdout.write(result);
+}

package/template/.claude/skills/track-candidates/SKILL.md

@@ -36,6 +36,7 @@ Run this skill:
 
 - `knowledge/Candidates/{Full Name}/brief.md` — candidate profile note
 - `knowledge/Candidates/{Full Name}/CV.pdf` — local copy of CV (or `CV.docx`)
+- `knowledge/Candidates/{Full Name}/headshot.jpeg` — candidate headshot photo
 - `~/.cache/fit/basecamp/state/graph_processed` — updated with processed threads
 
 ---
@@ -192,6 +193,48 @@ cp "~/.cache/fit/basecamp/apple_mail/attachments/{thread_id}/{filename}" \
 Use `CV.pdf` for PDF files and `CV.docx` for Word documents. The `## CV` link in
 the brief uses a relative path: `./CV.pdf`.
 
+### Headshot Discovery
+
+Search two locations for candidate headshot photos:
+
+1. **Email attachments** —
+   `~/.cache/fit/basecamp/apple_mail/attachments/{thread_id}/` may contain
+   headshot images sent by recruiters alongside CVs. Look for `.jpg`, `.jpeg`,
+   or `.png` files with candidate name fragments in the filename or that are
+   clearly portrait photos (not logos, signatures, or email decorations like
+   `image001.png`).
+
+2. **Downloads folder** — search `~/Downloads/` recursively (including
+   subdirectories) for headshot images:
+
+```bash
+find ~/Downloads -maxdepth 3 -type f \( -iname "*.jpg" -o -iname "*.jpeg" -o -iname "*.png" -o -iname "*.heic" \) 2>/dev/null
+```
+
+Match images to candidates by name similarity in the filename (e.g.
+`vitalii.jpeg` matches "Vitalii Huliai", `qazi.jpeg` matches "Qazi Rehman"). Use
+first name, last name, or full name matching — case-insensitive.
+
+When a headshot is found, copy it into the candidate directory with a
+standardized name:
+
+```bash
+cp "{source_path}" "knowledge/Candidates/{Full Name}/headshot.jpeg"
+```
+
+Always use `headshot.jpeg` as the filename regardless of the source format. If
+the source is PNG or HEIC, convert it first:
+
+```bash
+# PNG to JPEG
+magick "{source}.png" "knowledge/Candidates/{Full Name}/headshot.jpeg"
+# HEIC to JPEG
+magick "{source}.heic" "knowledge/Candidates/{Full Name}/headshot.jpeg"
+```
+
+If headshots exist in both locations, prefer the Downloads folder version (more
+likely to be a curated, high-quality photo).
+
 ## Step 3: Determine Pipeline Status
 
 Assign a status based on the email context:
@@ -430,3 +473,5 @@ produces a full framework-aligned assessment.
 - [ ] Skills tagged using framework skill IDs where possible
 - [ ] Gender field populated only from explicit pronouns/titles (never
       name-inferred)
+- [ ] Headshots searched in email attachments and `~/Downloads/` (recursive)
+- [ ] Found headshots copied as `headshot.jpeg` into candidate directory

package/template/.claude/skills/workday-requisition/SKILL.md

@@ -49,11 +49,13 @@ Run this skill:
 
 ## Workday Export Format
 
-The Workday requisition export contains multiple sheets. This skill uses:
+The Workday export format varies between versions. The parser handles both
+automatically using header-driven column mapping and dynamic header row
+detection.
 
 ### Sheet 1 — Requisition Metadata
 
-Key-value pairs, one per row:
+**Old format** — key-value pairs with Hiring Manager, Recruiter, Location:
 
 | Row | Field                 | Example                                |
 | --- | --------------------- | -------------------------------------- |
@@ -66,38 +68,58 @@ Key-value pairs, one per row:
 | 7   | Recruiter Title       | `Recruiter`                            |
 | 8   | Recruiter             | Name                                   |
 
-### Sheet 3 — Candidates
-
-Row 3 contains column headers. Data rows start at row 4. After the last
-candidate, stage-summary rows appear (these are not candidates).
-
-| Column | Field                  | Maps to brief field…     |
-| ------ | ---------------------- | ------------------------ |
-| B      | Candidate name         | `# {Name}`               |
-| C      | Stage                  | Status derivation        |
-| D      | Step / Disposition     | Status derivation        |
-| G      | Resume filename        | Reference only (no file) |
-| H      | Date Applied           | **First seen**           |
-| I      | Current Job Title      | **Current title**, Title |
-| J      | Current Company        | **Current title** suffix |
-| K      | Source                 | **Source**               |
-| L      | Referred by            | **Source** suffix        |
-| N      | Availability Date      | **Availability**         |
-| O      | Visa Requirement       | Notes                    |
-| P      | Eligible to Work       | Notes                    |
-| Q      | Relocation             | Notes                    |
-| R      | Salary Expectations    | **Rate**                 |
-| S      | Non-Compete            | Notes                    |
-| T      | Candidate Location     | **Location**             |
-| U      | Phone                  | **Phone**                |
-| V      | Email                  | **Email**                |
-| W      | Total Years Experience | Summary context          |
-| X      | All Job Titles         | Work History context     |
-| Y      | Companies              | Work History context     |
-| Z      | Degrees                | Education                |
-| AA     | Fields of Study        | Education                |
-| AB     | Language               | **English** / Language   |
-| AC     | Resume Text            | `CV.md` content          |
+**New format** — stage-count summary (no HM/Recruiter/Location):
+
+| Row | Field             | Example                                |
+| --- | ----------------- | -------------------------------------- |
+| 1   | Title header      | `4951493 Principal Software Engineer…` |
+| 2   | Active Candidates | `74 of 74`                             |
+| 3   | Active Referrals  | `3 of 3`                               |
+| 4   | Active Internal   | `4 of 4`                               |
+| 7+  | Stage counts      | `56 → Considered`                      |
+
+### Candidates Sheet
+
+The parser auto-detects the candidates sheet and header row:
+
+- **Old format**: 3+ sheets; candidates on "Candidates" sheet or Sheet3; header
+  at row 3 (index 2); two "Job Application" columns
+- **New format**: 2 sheets; candidates on Sheet2; header at row 8 (index 7);
+  single "Job Application" column
+
+Column mapping is header-driven — the parser reads the header row and maps
+columns by name, not position. Columns that vary between exports (e.g. "Jobs
+Applied to", "Referred by", "Convenience Task") are handled automatically.
+
+**Core columns** (present in all formats):
+
+| Header                 | Maps to brief field…                     |
+| ---------------------- | ---------------------------------------- |
+| Job Application        | `# {Name}`                               |
+| Stage                  | Row detection only (not used for status) |
+| Step / Disposition     | **Workday step** → status derivation     |
+| Resume                 | Reference only (no file)                 |
+| Date Applied           | **First seen**                           |
+| Current Job Title      | **Current title**, Title                 |
+| Current Company        | **Current title** suffix                 |
+| Source                 | **Source**                               |
+| Referred by            | **Source** suffix                        |
+| Candidate Location     | **Location**                             |
+| Phone                  | **Phone**                                |
+| Email                  | **Email**                                |
+| Availability Date      | **Availability**                         |
+| Visa Requirement       | Notes                                    |
+| Eligible to Work       | Notes                                    |
+| Relocation             | Notes                                    |
+| Salary Expectations    | **Rate**                                 |
+| Non-Compete            | Notes                                    |
+| Total Years Experience | Summary context                          |
+| All Job Titles         | Work History context                     |
+| Companies              | Work History context                     |
+| Degrees                | Education                                |
+| Fields of Study        | Education                                |
+| Language               | **English** / Language                   |
+| Resume Text            | `CV.md` content                          |
 
 #### Name Annotations
 
@@ -153,25 +175,36 @@ Use fuzzy matching — the Workday name may differ slightly from an existing not
 
 ## Step 3: Determine Pipeline Status
 
-Map Workday stage and step/disposition to the `track-candidates` pipeline
-status:
-
-| Workday Step / Disposition   | Pipeline Status    |
-| ---------------------------- | ------------------ |
-| `Considered`                 | `new`              |
-| `Manager Resume Screen`      | `screening`        |
-| `Assessment`                 | `screening`        |
-| `Interview` / `Phone Screen` | `first-interview`  |
-| `Second Interview`           | `second-interview` |
-| `Reference Check`            | `second-interview` |
-| `Offer`                      | `offer`            |
-| `Employment Agreement`       | `offer`            |
-| `Background Check`           | `hired`            |
-| `Ready for Hire`             | `hired`            |
-| `Rejected` / `Declined`      | `rejected`         |
-
-If the step is identical to the stage (e.g. both "Considered"), default to
-`new`.
+Map the **Step / Disposition** column to the `track-candidates` pipeline status.
+Do NOT use the Stage column for status — it is only used for row detection (stop
+condition):
+
+| Workday Step / Disposition             | Pipeline Status    |
+| -------------------------------------- | ------------------ |
+| `Considered`                           | `new`              |
+| `Review`                               | `new`              |
+| `Manager Resume Screen`                | `screening`        |
+| `Schedule Recruiter Phone Screen`      | `screening`        |
+| `Manager Request to Move Forward (HS)` | `screening`        |
+| `Proposed Interview Slate`             | `screening`        |
+| `Assessment`                           | `screening`        |
+| `Manager Request to Decline (HS)`      | `rejected`         |
+| `Interview` / `Phone Screen`           | `first-interview`  |
+| `Second Interview`                     | `second-interview` |
+| `Reference Check`                      | `second-interview` |
+| `Offer`                                | `offer`            |
+| `Employment Agreement`                 | `offer`            |
+| `Background Check`                     | `hired`            |
+| `Ready for Hire`                       | `hired`            |
+| `Rejected` / `Declined`                | `rejected`         |
+
+If the step value is empty or not recognized, default to `new`.
+
+**Important:** The raw `step` value is always preserved in the JSON output and
+should be stored in the candidate brief's **Pipeline** section (e.g.
+`Applied via LinkedIn — Step: Manager Request to Move Forward (HS)`). This
+allows the user to filter and query candidates by their exact Workday
+disposition.
 
 ## Step 4: Create CV.md from Resume Text
 

package/template/.claude/skills/workday-requisition/scripts/parse-workday.mjs

@@ -107,20 +107,86 @@ const requisition = {
   recruiter: reqMeta["Recruiter"] || "",
 };
 
-// --- Sheet 3: Candidates ---
+// --- Candidates sheet ---
 
-// Find the "Candidates" sheet (usually index 2, but search by name to be safe)
+// Find the candidates sheet. Workday exports vary:
+//   - Old format: 3+ sheets, candidates on a sheet named "Candidates" or Sheet3
+//   - New format: 2 sheets, candidates on Sheet2
 const candSheetName =
   wb.SheetNames.find((n) => n.toLowerCase() === "candidates") ||
-  wb.SheetNames[2];
+  wb.SheetNames[Math.min(2, wb.SheetNames.length - 1)];
 const ws3 = wb.Sheets[candSheetName];
 const candRows = XLSX.utils.sheet_to_json(ws3, { header: 1, defval: "" });
 
-// Row 3 (index 2) has column headers. Data starts at row 4 (index 3).
-// Stage summary rows start when column A has a non-empty value that looks like
-// a label or number — detect by checking if column C (Stage) is empty and
-// column A has a value.
-const DATA_START = 3;
+// Find the header row dynamically — look for a row containing "Stage"
+// Old format: row 3 (index 2). New format: row 8 (index 7).
+let HEADER_ROW = 2;
+for (let i = 0; i < Math.min(15, candRows.length); i++) {
+  if (candRows[i].some((c) => String(c).trim().toLowerCase() === "stage")) {
+    HEADER_ROW = i;
+    break;
+  }
+}
+const DATA_START = HEADER_ROW + 1;
+
+// --- Build header-driven column index map ---
+// Column layout varies between Workday exports (extra columns like "Jobs Applied to"
+// or "Referred by" shift indices). Map by header name to be resilient.
+
+const headerRow = candRows[HEADER_ROW] || [];
+const colMap = {};
+const HEADER_ALIASES = {
+  "job application": "name", // second "Job Application" column (index 1) has candidate name
+  stage: "stage",
+  "step / disposition": "step",
+  "awaiting me": "awaitingMe",
+  "awaiting action": "awaitingAction",
+  resume: "resumeFile",
+  "date applied": "dateApplied",
+  "current job title": "currentTitle",
+  "current company": "currentCompany",
+  source: "source",
+  "referred by": "referredBy",
+  "availability date": "availabilityDate",
+  "visa requirement": "visaRequirement",
+  "eligible to work": "eligibleToWork",
+  relocation: "relocation",
+  "salary expectations": "salaryExpectations",
+  "non-compete": "nonCompete",
+  "candidate location": "location",
+  phone: "phone",
+  email: "email",
+  "total years experience": "totalYearsExperience",
+  "all job titles": "allJobTitles",
+  companies: "companies",
+  degrees: "degrees",
+  "fields of study": "fieldsOfStudy",
+  language: "language",
+  "resume text": "resumeText",
+};
+
+// Skip columns we don't need (e.g. "Jobs Applied to", "Create Candidate Home Account URL")
+for (let i = 0; i < headerRow.length; i++) {
+  const hdr = String(headerRow[i]).trim().toLowerCase();
+  const field = HEADER_ALIASES[hdr];
+  if (field) {
+    // "Job Application" appears twice (cols A and B) — always take the latest
+    // occurrence so we end up with the second one (index 1) which has the name
+    colMap[field] = i;
+  }
+}
+
+// Fallback: if "name" wasn't mapped, use index 0 (new format) or 1 (old format)
+if (colMap.name === undefined) colMap.name = 1;
+// In new format there's only one "Job Application" column (index 0) — the
+// "always take latest" logic already handles this correctly.
+
+/** Get a cell value by field name, with fallback to empty string. */
+function col(row, field) {
+  const idx = colMap[field];
+  if (idx === undefined) return "";
+  return row[idx] ?? "";
+}
 
 /**
  * Clean a candidate name by stripping annotations like (Prior Worker),
@@ -180,45 +246,45 @@ const candidates = [];
 
 for (let i = DATA_START; i < candRows.length; i++) {
   const row = candRows[i];
-  const rawName = String(row[1] || "").trim(); // Column B (index 1)
-  const stage = String(row[2] || "").trim(); // Column C (index 2)
+  const rawName = String(col(row, "name") || "").trim();
+  const stage = String(col(row, "stage") || "").trim();
 
-  // Stop at stage-summary rows: column A has a value, column C (stage) is empty
-  if (!rawName || (!stage && String(row[0] || "").trim())) break;
+  // Skip empty rows; stop at stage-summary rows (name present but no stage)
   if (!rawName) continue;
+  if (!stage) break;
 
   const { cleanName, internalExternal: nameIE } = parseName(rawName);
-  const source = String(row[10] || "").trim();
+  const source = String(col(row, "source") || "").trim();
 
   candidates.push({
     name: rawName,
     cleanName,
     stage,
-    step: String(row[3] || "").trim(),
-    awaitingMe: String(row[4] || "").trim(),
-    awaitingAction: String(row[5] || "").trim(),
-    resumeFile: String(row[6] || "").trim(),
-    dateApplied: fmtDate(row[7]),
-    currentTitle: String(row[8] || "").trim(),
-    currentCompany: String(row[9] || "").trim(),
+    step: String(col(row, "step") || "").trim(),
+    awaitingMe: String(col(row, "awaitingMe") || "").trim(),
+    awaitingAction: String(col(row, "awaitingAction") || "").trim(),
+    resumeFile: String(col(row, "resumeFile") || "").trim(),
+    dateApplied: fmtDate(col(row, "dateApplied")),
+    currentTitle: String(col(row, "currentTitle") || "").trim(),
+    currentCompany: String(col(row, "currentCompany") || "").trim(),
     source,
-    referredBy: String(row[11] || "").trim(),
-    availabilityDate: fmtDate(row[13]),
-    visaRequirement: String(row[14] || "").trim(),
-    eligibleToWork: String(row[15] || "").trim(),
-    relocation: String(row[16] || "").trim(),
-    salaryExpectations: String(row[17] || "").trim(),
-    nonCompete: String(row[18] || "").trim(),
-    location: String(row[19] || "").trim(),
-    phone: String(row[20] || "").trim(),
-    email: String(row[21] || "").trim(),
-    totalYearsExperience: String(row[22] || "").trim(),
-    allJobTitles: multiline(row[23]),
-    companies: multiline(row[24]),
-    degrees: multiline(row[25]),
-    fieldsOfStudy: multiline(row[26]),
-    language: multiline(row[27]),
-    resumeText: String(row[28] || "").trim(),
+    referredBy: String(col(row, "referredBy") || "").trim(),
+    availabilityDate: fmtDate(col(row, "availabilityDate")),
+    visaRequirement: String(col(row, "visaRequirement") || "").trim(),
+    eligibleToWork: String(col(row, "eligibleToWork") || "").trim(),
+    relocation: String(col(row, "relocation") || "").trim(),
+    salaryExpectations: String(col(row, "salaryExpectations") || "").trim(),
+    nonCompete: String(col(row, "nonCompete") || "").trim(),
+    location: String(col(row, "location") || "").trim(),
+    phone: String(col(row, "phone") || "").trim(),
+    email: String(col(row, "email") || "").trim(),
+    totalYearsExperience: String(col(row, "totalYearsExperience") || "").trim(),
+    allJobTitles: multiline(col(row, "allJobTitles")),
+    companies: multiline(col(row, "companies")),
+    degrees: multiline(col(row, "degrees")),
+    fieldsOfStudy: multiline(col(row, "fieldsOfStudy")),
+    language: multiline(col(row, "language")),
+    resumeText: String(col(row, "resumeText") || "").trim(),
     internalExternal: inferInternalExternal(source, nameIE),
   });
 }

package/template/CLAUDE.md

@@ -87,6 +87,7 @@ wake, they observe KB state, decide the most valuable action, and execute.
 | **concierge**      | Meeting prep and transcripts   | Every 10 min    | sync-apple-calendar, meeting-prep, process-hyprnote                                            |
 | **librarian**      | Knowledge graph maintenance    | Every 15 min    | extract-entities, organize-files, manage-tasks                                                 |
 | **recruiter**      | Engineering recruitment        | Every 30 min    | track-candidates, analyze-cv, workday-requisition, right-to-be-forgotten, fit-pathway, fit-map |
+| **head-hunter**    | Passive talent scouting        | Every 60 min    | scan-open-candidates, fit-pathway, fit-map                                                     |
 | **chief-of-staff** | Daily briefings and priorities | 7am, Mon 7:30am | weekly-update _(Mon)_, _(reads all state for daily briefings)_                                 |
 
 Each agent writes a triage file to `~/.cache/fit/basecamp/state/` every wake
@@ -96,9 +97,10 @@ cycle. The naming convention is `{agent}_triage.md`:
 - `concierge_triage.md` — schedule, meeting prep status, unprocessed transcripts
 - `librarian_triage.md` — unprocessed files, knowledge graph size
 - `recruiter_triage.md` — candidate pipeline, assessments, track distribution
+- `head_hunter_triage.md` — prospect pipeline, source rotation, match strength
 
-The **chief-of-staff** reads all three triage files to synthesize daily
-briefings in `knowledge/Briefings/`.
+The **chief-of-staff** reads all five triage files to synthesize daily briefings
+in `knowledge/Briefings/`.
 
 ## Cache Directory (`~/.cache/fit/basecamp/`)
 
@@ -110,13 +112,20 @@ Synced data and runtime state live outside the knowledge base in
 ├── apple_mail/              # Synced Apple Mail threads (.md files)
 │   └── attachments/         # Copied email attachments by thread
 ├── apple_calendar/          # Synced Apple Calendar events (.json files)
+├── head-hunter/             # Head hunter agent memory
+│   ├── cursor.tsv           # Source rotation state
+│   ├── failures.tsv         # Consecutive failure tracking
+│   ├── seen.tsv             # Deduplication index
+│   ├── prospects.tsv        # Prospect index
+│   └── log.md               # Append-only activity log
 └── state/                   # Runtime state
     ├── apple_mail_last_sync # ISO timestamp of last mail sync
     ├── graph_processed      # TSV of processed files (path<TAB>hash)
     ├── postman_triage.md    # Agent triage files ({agent}_triage.md)
     ├── concierge_triage.md
     ├── librarian_triage.md
-    └── recruiter_triage.md
+    ├── recruiter_triage.md
+    └── head_hunter_triage.md
 ```
 
 This separation keeps the knowledge base clean — only the parsed knowledge
@@ -208,6 +217,7 @@ Available skills (grouped by function):
 | `workday-requisition`   | Import candidates from Workday XLSX      |
 | `analyze-cv`            | CV assessment against career framework   |
 | `right-to-be-forgotten` | GDPR data erasure with audit trail       |
+| `scan-open-candidates`  | Scan public sources for open-for-hire    |
 | `weekly-update`         | Weekly priorities from tasks + calendar  |
 | `process-hyprnote`      | Extract entities from Hyprnote sessions  |
 | `organize-files`        | Tidy Desktop/Downloads, chain to extract |