@forwardimpact/basecamp 2.5.0 → 2.6.1

package/template/.claude/skills/scan-open-candidates/SKILL.md

@@ -96,6 +96,7 @@ WebFetch URL: https://api.github.com/search/users?q=%22looking+for+work%22+locat
 ```
 
 Alternative bio phrases to search (rotate across wakes):
+
 - `"available for hire"`
 - `"seeking opportunities"`
 - `"seeking new role"`
@@ -106,8 +107,8 @@ Alternative bio phrases to search (rotate across wakes):
 - `"on the market"`
 - `"open to opportunities"`
 
-Response has `total_count` and `items` array. Each item has `login`,
-`html_url`, `score`.
+Response has `total_count` and `items` array. Each item has `login`, `html_url`,
+`score`.
 
 **Fetch full profile for promising candidates:**
 
@@ -116,6 +117,7 @@ WebFetch URL: https://api.github.com/users/{login}
 ```
 
 Profile fields:
+
 - `name` — display name
 - `bio` — bio text (contains open-to-work signals)
 - `location` — geographic location
@@ -125,8 +127,8 @@ Profile fields:
 - `public_repos` — repository count (technical depth indicator)
 - `created_at` — account age (experience proxy)
 
-**Cursor:** Store the location query last used and page number. Rotate:
-UK → Europe → Remote → repeat.
+**Cursor:** Store the location query last used and page number. Rotate: UK →
+Europe → Remote → repeat.
 
 **Rate limit:** 10 requests/minute unauthenticated. Fetch at most 5 full
 profiles per wake cycle (1 search + 5 profile fetches = 6 requests).
@@ -142,12 +144,13 @@ WebFetch URL: https://dev.to/api/articles?tag=opentowork&per_page=25
 WebFetch URL: https://dev.to/api/articles?tag=lookingforwork&per_page=25
 ```
 
-For articles, parse `title`, `description`, `user.name`, `user.username`,
-`url`, `tag_list`, `published_at`.
+For articles, parse `title`, `description`, `user.name`, `user.username`, `url`,
+`tag_list`, `published_at`.
 
 Skip articles older than 90 days — the candidate may no longer be looking.
 
 Additional tags to try when primary tags yield no results:
+
 - `jobsearch`
 - `career`
 - `hiring`
@@ -156,8 +159,8 @@ Additional tags to try when primary tags yield no results:
 
 **Cursor:** Store the `id` of the most recent article processed.
 
-**Rate limit:** dev.to API allows 30 requests per 30 seconds. One fetch per
-wake is fine.
+**Rate limit:** dev.to API allows 30 requests per 30 seconds. One fetch per wake
+is fine.
 
 ---
 
@@ -172,13 +175,16 @@ Each source has multiple query variations. If the first query returns nothing
 new, try the next variation:
 
 **HN:**
+
 - Check the previous month's "Who Wants to Be Hired?" thread (candidates post
   late or threads stay active)
 - Search for `"Who is hiring"` threads — candidates sometimes post in the wrong
   thread, and comments may link to candidate profiles
-- Try: `https://hn.algolia.com/api/v1/search?query=%22freelancer+available%22&tags=comment`
+- Try:
+  `https://hn.algolia.com/api/v1/search?query=%22freelancer+available%22&tags=comment`
 
 **GitHub:**
+
 - Search by skill + availability instead of just bio phrases:
   ```
   WebFetch URL: https://api.github.com/search/users?q=%22data+engineering%22+%22open+to+work%22&per_page=30&sort=joined&order=desc
@@ -193,6 +199,7 @@ new, try the next variation:
   `Sofia`, `Manchester`, `Edinburgh`
 
 **dev.to:**
+
 - Try broader tags: `jobsearch`, `career`, `remotework`
 - Search articles directly:
   ```
@@ -203,20 +210,23 @@ new, try the next variation:
 ### Strategy 2: Relax Filters
 
 If geographic filtering eliminated all candidates:
+
 - Re-scan the same results without the location filter
 - Candidates without stated locations may still be open to target regions
 - Mark these as "location unconfirmed" in the prospect note
 
 If skill alignment filtered everyone out:
+
 - Lower the minimum bar from 2 framework skills to 1
 - Look for transferable skills (e.g., strong Python → likely data integration
   capability)
-- Consider adjacent skill indicators (e.g., "machine learning" implies
-  data skills)
+- Consider adjacent skill indicators (e.g., "machine learning" implies data
+  skills)
 
 ### Strategy 3: Cross-Reference
 
 When a source yields very few results, cross-reference what you do find:
+
 - If a GitHub profile links to a blog or portfolio, check it for more detail
   (via WebFetch) before deciding on skill fit
 - If an HN post mentions a GitHub username, fetch their GitHub profile for
@@ -240,10 +250,11 @@ Stopped after 2 alternatives (1 prospect found)
 
 ## Failure Handling
 
-When a WebFetch fails (HTTP 4xx, 5xx, timeout, empty response, or redirect to
-a block page), handle it gracefully:
+When a WebFetch fails (HTTP 4xx, 5xx, timeout, empty response, or redirect to a
+block page), handle it gracefully:
 
 1. **Record the failure** in `failures.tsv`:
+
    ```bash
    sed -i '' "s/^{source}\t.*/&/" ~/.cache/fit/basecamp/head-hunter/failures.tsv
    # Or increment the count and update last_error
@@ -307,6 +318,7 @@ Run `npx fit-pathway skill --list` to get the framework skill inventory. Check
 whether the candidate mentions skills that map to framework capabilities:
 
 **Strong signals (forward-deployed track):**
+
 - Multiple industries or domains in background
 - Customer-facing project experience
 - Data integration, analytics, visualization
@@ -315,6 +327,7 @@ whether the candidate mentions skills that map to framework capabilities:
 - AI/ML tool proficiency (Claude, GPT, Cursor, "vibe coding")
 
 **Strong signals (platform track):**
+
 - Infrastructure, cloud platforms, DevOps
 - Architecture and system design
 - API design, shared services
@@ -371,6 +384,83 @@ combinations, anything noteworthy for the user}
 **Naming:** Use the candidate's display name as given. If only a username is
 available, use the username. Never fabricate real names.
 
+## State Management Script
+
+**Use the state script for ALL state file operations.** Do NOT write bespoke
+scripts to update cursor, seen, prospects, failures, or log files.
+
+    node .claude/skills/scan-open-candidates/scripts/state.mjs <command> [args]
+
+### Commands
+
+**Cursor** (source rotation):
+
+```bash
+# Check which source to scan next
+node scripts/state.mjs cursor list
+
+# Get cursor for a specific source
+node scripts/state.mjs cursor get github_open_to_work
+
+# Update cursor after scanning
+node scripts/state.mjs cursor set github_open_to_work "2026-03-09T22:00:00Z" "UK-done_next:Europe"
+```
+
+**Seen** (deduplication):
+
+```bash
+# Check if a candidate was already seen (exit 0=seen, 1=new)
+node scripts/state.mjs seen check github_open_to_work mxmxmx333
+
+# Mark one ID as seen
+node scripts/state.mjs seen add github_open_to_work mxmxmx333
+
+# Mark multiple IDs as seen in one call
+node scripts/state.mjs seen batch github_open_to_work id1 id2 id3 id4
+```
+
+**Prospects**:
+
+```bash
+# Add a new prospect
+node scripts/state.mjs prospect add "Hasan Cam" github_open_to_work strong "J060-J070 platform"
+
+# List recent prospects
+node scripts/state.mjs prospect list --limit 10
+
+# Count total prospects
+node scripts/state.mjs prospect count
+```
+
+**Failures**:
+
+```bash
+# Check failure count (for source selection — skip if ≥3)
+node scripts/state.mjs failure get mastodon_hachyderm
+
+# Record a fetch failure
+node scripts/state.mjs failure increment mastodon_hachyderm
+
+# Reset after successful fetch
+node scripts/state.mjs failure reset github_open_to_work
+```
+
+**Logging**:
+
+```bash
+# Append a formatted wake cycle entry
+node scripts/state.mjs log-wake github_open_to_work "Primary query: 'open to work' location:UK — 30 results, 2 new prospects"
+
+# Append raw text
+node scripts/state.mjs log "Manual note about source rotation"
+```
+
+**Summary** (state overview):
+
+```bash
+node scripts/state.mjs summary
+```
+
 ## Quality Checklist
 
 - [ ] Selected the least-recently-checked source from cursor.tsv

package/template/.claude/skills/scan-open-candidates/scripts/state.mjs

@@ -0,0 +1,396 @@
+#!/usr/bin/env node
+/**
+ * Manage head-hunter agent state files.
+ *
+ * Provides atomic operations on the 5 state files used by the head-hunter agent:
+ *   cursor.tsv   — source rotation state (source, last_checked, position)
+ *   seen.tsv     — deduplication index (source, id, date)
+ *   prospects.tsv — prospect index (name, source, date, strength, level)
+ *   failures.tsv — consecutive failure counts (source, count)
+ *   log.md       — append-only activity log
+ *
+ * Usage:
+ *   node scripts/state.mjs cursor get <source>
+ *   node scripts/state.mjs cursor set <source> <timestamp> <position>
+ *   node scripts/state.mjs seen check <source> <id>
+ *   node scripts/state.mjs seen add <source> <id> [<date>]
+ *   node scripts/state.mjs prospect add <name> <source> <strength> <level>
+ *   node scripts/state.mjs prospect list [--limit N]
+ *   node scripts/state.mjs failure get <source>
+ *   node scripts/state.mjs failure increment <source>
+ *   node scripts/state.mjs failure reset <source>
+ *   node scripts/state.mjs log <message>
+ *   node scripts/state.mjs log-wake <source> <summary>
+ *   node scripts/state.mjs summary
+ */
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const HOME = homedir();
+const STATE_DIR = join(HOME, ".cache/fit/basecamp/head-hunter");
+
+const PATHS = {
+  cursor: join(STATE_DIR, "cursor.tsv"),
+  seen: join(STATE_DIR, "seen.tsv"),
+  prospects: join(STATE_DIR, "prospects.tsv"),
+  failures: join(STATE_DIR, "failures.tsv"),
+  log: join(STATE_DIR, "log.md"),
+};
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  console.log(`state — manage head-hunter agent state
+
+Usage:
+  node scripts/state.mjs <command> [args]
+
+Cursor commands (source rotation):
+  cursor get <source>                         Get current cursor for source
+  cursor set <source> <timestamp> <position>  Update cursor position
+  cursor list                                 List all cursors
+
+Seen commands (deduplication):
+  seen check <source> <id>                    Check if ID was already seen (exit 0=seen, 1=new)
+  seen add <source> <id> [<date>]             Mark ID as seen (date defaults to today)
+  seen batch <source> <id1> <id2> ...         Mark multiple IDs as seen
+
+Prospect commands:
+  prospect add <name> <source> <strength> <level>  Add a new prospect
+  prospect list [--limit N]                         List recent prospects
+  prospect count                                    Count total prospects
+
+Failure commands:
+  failure get <source>                        Get failure count for source
+  failure increment <source>                  Increment failure count
+  failure reset <source>                      Reset failure count to 0
+
+Log commands:
+  log <message>                               Append raw text to log.md
+  log-wake <source> <summary>                 Append a formatted wake cycle entry
+
+Summary:
+  summary                                     Print state overview
+
+State dir: ~/.cache/fit/basecamp/head-hunter/`);
+  process.exit(0);
+}
+
+// --- Ensure state directory exists ---
+
+mkdirSync(STATE_DIR, { recursive: true });
+
+// --- File helpers ---
+
+function readTsv(file) {
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8")
+    .split("\n")
+    .filter((l) => l.trim());
+}
+
+function writeTsv(file, lines) {
+  writeFileSync(file, lines.join("\n") + (lines.length ? "\n" : ""));
+}
+
+function appendTsv(file, line) {
+  appendFileSync(file, line + "\n");
+}
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+// --- Cursor operations ---
+
+function cursorGet(source) {
+  const lines = readTsv(PATHS.cursor);
+  const line = lines.find((l) => l.startsWith(source + "\t"));
+  if (!line) {
+    console.log(`No cursor for source: ${source}`);
+    return null;
+  }
+  const [, timestamp, position] = line.split("\t");
+  console.log(`${source}\t${timestamp}\t${position}`);
+  return { source, timestamp, position };
+}
+
+function cursorSet(source, timestamp, position) {
+  const lines = readTsv(PATHS.cursor);
+  const newLine = `${source}\t${timestamp}\t${position}`;
+  const idx = lines.findIndex((l) => l.startsWith(source + "\t"));
+  if (idx !== -1) {
+    lines[idx] = newLine;
+  } else {
+    lines.push(newLine);
+  }
+  writeTsv(PATHS.cursor, lines);
+  console.log(`Cursor updated: ${newLine}`);
+}
+
+function cursorList() {
+  const lines = readTsv(PATHS.cursor);
+  if (lines.length === 0) {
+    console.log("No cursors.");
+    return;
+  }
+  for (const line of lines) {
+    console.log(line);
+  }
+}
+
+// --- Seen operations ---
+
+function seenCheck(source, id) {
+  const lines = readTsv(PATHS.seen);
+  const found = lines.some((l) => {
+    const parts = l.split("\t");
+    return parts[0] === source && parts[1] === id;
+  });
+  if (found) {
+    console.log(`SEEN: ${source}\t${id}`);
+    process.exit(0);
+  } else {
+    console.log(`NEW: ${source}\t${id}`);
+    process.exit(1);
+  }
+}
+
+function seenAdd(source, id, date) {
+  appendTsv(PATHS.seen, `${source}\t${id}\t${date || today()}`);
+  console.log(`Marked seen: ${source}\t${id}\t${date || today()}`);
+}
+
+function seenBatch(source, ids) {
+  const d = today();
+  const lines = ids.map((id) => `${source}\t${id}\t${d}`);
+  appendFileSync(PATHS.seen, lines.join("\n") + "\n");
+  console.log(`Marked ${ids.length} IDs as seen for ${source}`);
+}
+
+// --- Prospect operations ---
+
+function prospectAdd(name, source, strength, level) {
+  const d = today();
+  appendTsv(PATHS.prospects, `${name}\t${source}\t${d}\t${strength}\t${level}`);
+  console.log(`Prospect added: ${name} (${strength}, ${level})`);
+}
+
+function prospectList(limit) {
+  const lines = readTsv(PATHS.prospects);
+  if (lines.length === 0) {
+    console.log("No prospects.");
+    return;
+  }
+  // Show most recent first
+  const display = lines.slice(-limit).reverse();
+  for (const line of display) {
+    console.log(line);
+  }
+  if (lines.length > limit) {
+    console.log(`\n... ${lines.length - limit} more (${lines.length} total)`);
+  }
+}
+
+function prospectCount() {
+  const lines = readTsv(PATHS.prospects);
+  console.log(lines.length);
+}
+
+// --- Failure operations ---
+
+function failureGet(source) {
+  const lines = readTsv(PATHS.failures);
+  const line = lines.find((l) => l.startsWith(source + "\t"));
+  if (!line) {
+    console.log(`0`);
+    return 0;
+  }
+  const count = parseInt(line.split("\t")[1], 10) || 0;
+  console.log(`${count}`);
+  return count;
+}
+
+function failureIncrement(source) {
+  const lines = readTsv(PATHS.failures);
+  const idx = lines.findIndex((l) => l.startsWith(source + "\t"));
+  if (idx !== -1) {
+    const count = parseInt(lines[idx].split("\t")[1], 10) || 0;
+    lines[idx] = `${source}\t${count + 1}`;
+  } else {
+    lines.push(`${source}\t1`);
+  }
+  writeTsv(PATHS.failures, lines);
+  const newCount = parseInt(
+    lines.find((l) => l.startsWith(source + "\t")).split("\t")[1],
+    10,
+  );
+  console.log(`Failures for ${source}: ${newCount}`);
+  if (newCount >= 3) {
+    console.log(
+      `WARNING: ${source} has ${newCount} consecutive failures (suspended at ≥3)`,
+    );
+  }
+}
+
+function failureReset(source) {
+  const lines = readTsv(PATHS.failures);
+  const idx = lines.findIndex((l) => l.startsWith(source + "\t"));
+  if (idx !== -1) {
+    lines[idx] = `${source}\t0`;
+    writeTsv(PATHS.failures, lines);
+  }
+  console.log(`Failures reset for ${source}`);
+}
+
+// --- Log operations ---
+
+function logAppend(message) {
+  appendFileSync(PATHS.log, message + "\n");
+  console.log("Log entry appended.");
+}
+
+function logWake(source, summary) {
+  const timestamp = new Date().toISOString().slice(0, 16).replace("T", " ");
+  const entry = `\n## ${today()} ${timestamp.slice(11)} — Wake (${source})\n\n${summary}\n\n---\n`;
+  appendFileSync(PATHS.log, entry);
+  console.log(`Wake cycle logged for ${source}`);
+}
+
+// --- Summary ---
+
+function summary() {
+  const cursors = readTsv(PATHS.cursor);
+  const seen = readTsv(PATHS.seen);
+  const prospects = readTsv(PATHS.prospects);
+  const failures = readTsv(PATHS.failures);
+
+  console.log("=== Head-Hunter State Summary ===\n");
+
+  console.log(`Sources: ${cursors.length}`);
+  for (const line of cursors) {
+    const [source, timestamp, position] = line.split("\t");
+    const failLine = failures.find((l) => l.startsWith(source + "\t"));
+    const failCount = failLine ? parseInt(failLine.split("\t")[1], 10) : 0;
+    const status = failCount >= 3 ? " [SUSPENDED]" : "";
+    console.log(`  ${source}: last=${timestamp}, pos=${position}${status}`);
+  }
+
+  console.log(`\nSeen: ${seen.length} entries`);
+  console.log(`Prospects: ${prospects.length} total`);
+
+  // Strength breakdown
+  const byStrength = {};
+  for (const line of prospects) {
+    const strength = line.split("\t")[3] || "unknown";
+    byStrength[strength] = (byStrength[strength] || 0) + 1;
+  }
+  for (const [k, v] of Object.entries(byStrength)) {
+    console.log(`  ${k}: ${v}`);
+  }
+
+  // Recent prospects (last 5)
+  if (prospects.length > 0) {
+    console.log("\nRecent prospects:");
+    for (const line of prospects.slice(-5)) {
+      const [name, source, date, strength, level] = line.split("\t");
+      console.log(
+        `  ${date} | ${name} | ${strength} | ${level} | via ${source}`,
+      );
+    }
+  }
+}
+
+// --- CLI Router ---
+
+const cliArgs = process.argv.slice(2);
+const cmd = cliArgs[0];
+const sub = cliArgs[1];
+
+switch (cmd) {
+  case "cursor":
+    if (sub === "get" && cliArgs[2]) cursorGet(cliArgs[2]);
+    else if (sub === "set" && cliArgs[2] && cliArgs[3] && cliArgs[4])
+      cursorSet(cliArgs[2], cliArgs[3], cliArgs[4]);
+    else if (sub === "list") cursorList();
+    else {
+      console.error(
+        "Usage: cursor get|set|list <source> [<timestamp> <position>]",
+      );
+      process.exit(1);
+    }
+    break;
+
+  case "seen":
+    if (sub === "check" && cliArgs[2] && cliArgs[3])
+      seenCheck(cliArgs[2], cliArgs[3]);
+    else if (sub === "add" && cliArgs[2] && cliArgs[3])
+      seenAdd(cliArgs[2], cliArgs[3], cliArgs[4]);
+    else if (sub === "batch" && cliArgs[2] && cliArgs.length > 3)
+      seenBatch(cliArgs[2], cliArgs.slice(3));
+    else {
+      console.error("Usage: seen check|add|batch <source> <id> [...]");
+      process.exit(1);
+    }
+    break;
+
+  case "prospect":
+    if (sub === "add" && cliArgs[2] && cliArgs[3] && cliArgs[4] && cliArgs[5])
+      prospectAdd(cliArgs[2], cliArgs[3], cliArgs[4], cliArgs[5]);
+    else if (sub === "list") {
+      const lIdx = cliArgs.indexOf("--limit");
+      const lim = lIdx !== -1 ? parseInt(cliArgs[lIdx + 1], 10) || 10 : 10;
+      prospectList(lim);
+    } else if (sub === "count") prospectCount();
+    else {
+      console.error(
+        "Usage: prospect add|list|count <name> <source> <strength> <level>",
+      );
+      process.exit(1);
+    }
+    break;
+
+  case "failure":
+    if (sub === "get" && cliArgs[2]) failureGet(cliArgs[2]);
+    else if (sub === "increment" && cliArgs[2]) failureIncrement(cliArgs[2]);
+    else if (sub === "reset" && cliArgs[2]) failureReset(cliArgs[2]);
+    else {
+      console.error("Usage: failure get|increment|reset <source>");
+      process.exit(1);
+    }
+    break;
+
+  case "log":
+    if (cliArgs.length >= 2) logAppend(cliArgs.slice(1).join(" "));
+    else {
+      console.error("Usage: log <message>");
+      process.exit(1);
+    }
+    break;
+
+  case "log-wake":
+    if (cliArgs[1] && cliArgs.length >= 3)
+      logWake(cliArgs[1], cliArgs.slice(2).join(" "));
+    else {
+      console.error("Usage: log-wake <source> <summary>");
+      process.exit(1);
+    }
+    break;
+
+  case "summary":
+    summary();
+    break;
+
+  default:
+    console.error(
+      "Unknown command. Run with --help for usage.\n" +
+        "Commands: cursor, seen, prospect, failure, log, log-wake, summary",
+    );
+    process.exit(1);
+}

package/template/.claude/skills/sync-apple-calendar/SKILL.md

@@ -96,6 +96,47 @@ Each `{event_id}.json` file:
 - Database locked → wait 2 seconds, retry once
 - Skip events with no summary (likely cancelled or placeholder)
 
+## Querying Events
+
+After syncing, use the query script to filter events by date or time window.
+**Agents should use this script instead of writing bespoke calendar parsers.**
+
+    node scripts/query.mjs [options]
+
+### Time filters (combinable)
+
+| Flag                            | Description                                               |
+| ------------------------------- | --------------------------------------------------------- |
+| `--today`                       | Events starting today (default if no filter given)        |
+| `--tomorrow`                    | Events starting tomorrow                                  |
+| `--upcoming 2h`                 | Events starting within interval (e.g., `2h`, `30m`, `1d`) |
+| `--date 2026-03-09`             | Events on a specific date                                 |
+| `--range 2026-03-09 2026-03-11` | Events between two dates (inclusive)                      |
+
+### Output options
+
+| Flag                | Description                                     |
+| ------------------- | ----------------------------------------------- |
+| `--json`            | Output as JSON array (default: formatted table) |
+| `--include-all-day` | Include all-day events (excluded by default)    |
+| `--no-attendees`    | Omit attendee names from output                 |
+
+### Examples
+
+```bash
+# Concierge: get today + tomorrow for triage
+node scripts/query.mjs --today --tomorrow
+
+# Meeting-prep: get upcoming meetings in next 2 hours as JSON
+node scripts/query.mjs --upcoming 2h --json
+
+# Chief-of-staff: get this week's events
+node scripts/query.mjs --range 2026-03-09 2026-03-13
+
+# Quick count check
+node scripts/query.mjs --today --json | node -e "process.stdin.on('data',d=>console.log(JSON.parse(d).length+' events today'))"
+```
+
 ## Constraints
 
 - Open database read-only (`readOnly: true`)