@forwardimpact/basecamp 2.4.1 → 2.5.0

package/template/.claude/skills/draft-emails/scripts/send-email.mjs

@@ -6,13 +6,18 @@
  * Apple Mail. The script writes a temporary .scpt file, executes it with
  * osascript, and cleans up afterwards. Mail.app must be running.
  *
- * The body should be plain text — no HTML. Do NOT include an email signature;
- * Apple Mail appends the user's configured signature automatically.
+ * The body should be plain text — no HTML. Do NOT include an email signature
+ * or sign-off; Apple Mail appends the user's configured signature automatically.
  */
 
 import { execFileSync } from "node:child_process";
-import { mkdtempSync, writeFileSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
+import {
+  appendFileSync,
+  mkdtempSync,
+  writeFileSync,
+  unlinkSync,
+} from "node:fs";
+import { basename, join } from "node:path";
 import { tmpdir } from "node:os";
 
 const HELP = `send-email — send an email via Apple Mail
@@ -25,9 +30,10 @@ Options:
   --bcc <addrs>      Comma-separated BCC recipients
   --subject <subj>   Email subject line (required)
   --body <text>      Plain-text email body (required)
+  --draft <path>     Draft file — deleted after send, ID appended to drafts/handled
   -h, --help         Show this help message and exit
 
-Mail.app must be running. No email signature needed — Apple Mail appends it.`;
+Mail.app must be running. No signature or sign-off needed — Apple Mail appends it.`;
 
 if (process.argv.includes("-h") || process.argv.includes("--help")) {
   console.log(HELP);
@@ -59,7 +65,8 @@ function main() {
     cc = "",
     bcc = "",
     subject = "",
-    body = "";
+    body = "",
+    draft = "";
 
   for (let i = 0; i < args.length; i++) {
     switch (args[i]) {
@@ -78,6 +85,9 @@ function main() {
       case "--body":
         body = args[++i] ?? "";
         break;
+      case "--draft":
+        draft = args[++i] ?? "";
+        break;
     }
   }
 
@@ -87,6 +97,13 @@ function main() {
     process.exit(1);
   }
 
+  // Strip leading two-space padding from each line and trim overall whitespace
+  body = body
+    .split("\n")
+    .map((line) => line.replace(/^  /, ""))
+    .join("\n")
+    .trim();
+
   const lines = [
     'tell application "Mail"',
     `    set newMessage to make new outgoing message with properties {subject:"${escapeAS(subject)}", content:"${escapeAS(body)}", visible:false}`,
@@ -106,6 +123,24 @@ function main() {
     writeFileSync(tmp, lines);
     execFileSync("osascript", [tmp], { stdio: "inherit" });
     console.log(`Sent: ${subject}`);
+
+    // Clean up draft and mark thread as handled
+    if (draft) {
+      try {
+        unlinkSync(draft);
+        console.log(`Removed draft: ${draft}`);
+      } catch {
+        // ignore if draft already gone
+      }
+
+      // Extract email ID from draft filename (e.g. "drafts/12345_draft.md" → "12345")
+      const draftBasename = basename(draft, ".md");
+      const emailId = draftBasename.replace(/_draft$/, "");
+      if (emailId) {
+        appendFileSync("drafts/handled", emailId + "\n");
+        console.log(`Marked as handled: ${emailId}`);
+      }
+    }
   } finally {
     try {
       unlinkSync(tmp);

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

@@ -0,0 +1,386 @@
+---
+name: scan-open-candidates
+description: >
+  Scan publicly available sources for candidates who indicate they are open for
+  hire. Uses WebFetch to read public APIs (HN Algolia, GitHub, dev.to).
+  Writes prospect notes to knowledge/Prospects/. Maintains
+  cursor/dedup state in ~/.cache/fit/basecamp/head-hunter/. Use when the
+  head-hunter agent is woken or when the user asks to scan for open candidates.
+---
+
+# Scan Open Candidates
+
+Fetch and filter publicly available candidate posts from platforms where people
+explicitly indicate they are open for hire. This skill handles the web fetching,
+filtering, and deduplication logic.
+
+## Trigger
+
+Run this skill:
+
+- When the head-hunter agent is woken by the scheduler
+- When the user asks to scan for open candidates or prospects
+
+## Prerequisites
+
+- `WebFetch` tool available (Claude Code built-in — no curl/wget needed)
+- `fit-pathway` CLI available (`npx fit-pathway`)
+- Memory directory at `~/.cache/fit/basecamp/head-hunter/`
+
+## Inputs
+
+- `~/.cache/fit/basecamp/head-hunter/cursor.tsv` — source rotation state
+- `~/.cache/fit/basecamp/head-hunter/seen.tsv` — deduplication index
+- Framework data via `npx fit-pathway skill --list` and `npx fit-pathway job`
+
+## Outputs
+
+- `knowledge/Prospects/{Name}.md` — prospect notes
+- `~/.cache/fit/basecamp/head-hunter/cursor.tsv` — updated cursors
+- `~/.cache/fit/basecamp/head-hunter/seen.tsv` — updated seen index
+- `~/.cache/fit/basecamp/head-hunter/prospects.tsv` — updated prospect index
+- `~/.cache/fit/basecamp/head-hunter/log.md` — appended activity log
+- `~/.cache/fit/basecamp/state/head_hunter_triage.md` — triage report
+
+---
+
+## Source Definitions
+
+### 1. Hacker News "Who Wants to Be Hired?"
+
+A monthly thread where candidates self-post their availability. Posted on the
+1st of each month on Hacker News.
+
+**Find the thread:**
+
+```
+WebFetch URL: https://hn.algolia.com/api/v1/search?query=%22Who+wants+to+be+hired%22&tags=ask_hn&hitsPerPage=5
+```
+
+Parse the JSON response. The first hit with a title matching "Who wants to be
+hired?" and `created_at` in the current or previous month is the target thread.
+
+**Fetch candidate posts:**
+
+```
+WebFetch URL: https://hn.algolia.com/api/v1/items/{objectID}
+```
+
+The `children` array contains top-level comments — each is one candidate. Parse
+the `text` field (HTML) for:
+
+- **Location** — often first line: "Location: New York" or "NYC / Remote"
+- **Remote** — "Remote: Yes" or "Open to remote"
+- **Skills** — tech stack listings, language/framework mentions
+- **Experience** — years, role titles, past companies
+- **Contact** — email (often obfuscated: "name [at] domain [dot] com")
+- **Resume/CV** — links to personal sites, GitHub, LinkedIn
+
+**Cursor:** Store the `objectID` of the thread and the ID of the last processed
+child comment.
+
+**Rate limit:** HN Algolia API has no strict rate limit but be respectful — one
+fetch per source per wake cycle.
+
+### 2. GitHub Open to Work
+
+Search for GitHub users whose bio signals availability. The GitHub user search
+API returns candidates with bios, locations, and repository metadata.
+
+**Search by location (rotate one query per wake):**
+
+```
+WebFetch URL: https://api.github.com/search/users?q=%22open+to+work%22+location:UK&per_page=30&sort=joined&order=desc
+WebFetch URL: https://api.github.com/search/users?q=%22open+to+work%22+location:Europe&per_page=30&sort=joined&order=desc
+WebFetch URL: https://api.github.com/search/users?q=%22looking+for+work%22+location:remote&per_page=30&sort=joined&order=desc
+```
+
+Alternative bio phrases to search (rotate across wakes):
+- `"available for hire"`
+- `"seeking opportunities"`
+- `"seeking new role"`
+- `"open to new opportunities"`
+- `"currently exploring"`
+- `"freelance" "available"`
+- `"between roles"`
+- `"on the market"`
+- `"open to opportunities"`
+
+Response has `total_count` and `items` array. Each item has `login`,
+`html_url`, `score`.
+
+**Fetch full profile for promising candidates:**
+
+```
+WebFetch URL: https://api.github.com/users/{login}
+```
+
+Profile fields:
+- `name` — display name
+- `bio` — bio text (contains open-to-work signals)
+- `location` — geographic location
+- `hireable` — boolean, explicit hire signal
+- `blog` — personal site URL
+- `company` — current employer (null = likely available)
+- `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.
+
+**Rate limit:** 10 requests/minute unauthenticated. Fetch at most 5 full
+profiles per wake cycle (1 search + 5 profile fetches = 6 requests).
+
+### 3. dev.to
+
+Developer articles where candidates signal availability via tags.
+
+**Fetch articles tagged with job-seeking:**
+
+```
+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`.
+
+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`
+- `job`
+- `remotework`
+
+**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.
+
+---
+
+## Creative Fallback Strategies
+
+When the primary query for a source yields zero new prospects after filtering,
+try these alternative approaches before reporting an empty scan.
+
+### Strategy 1: Alternative Search Terms
+
+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`
+
+**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
+  WebFetch URL: https://api.github.com/search/users?q=%22full+stack%22+%22available+for+hire%22&per_page=30&sort=joined&order=desc
+  WebFetch URL: https://api.github.com/search/users?q=%22devops%22+%22looking+for%22&per_page=30&sort=joined&order=desc
+  ```
+- Search repos with README availability signals:
+  ```
+  WebFetch URL: https://api.github.com/search/repositories?q=%22hire+me%22+in:readme&sort=updated&order=desc&per_page=10
+  ```
+- Try different location terms: `Greece`, `Athens`, `Warsaw`, `Bucharest`,
+  `Sofia`, `Manchester`, `Edinburgh`
+
+**dev.to:**
+- Try broader tags: `jobsearch`, `career`, `remotework`
+- Search articles directly:
+  ```
+  WebFetch URL: https://dev.to/api/articles?tag=career&per_page=25
+  ```
+  Then filter article titles/descriptions for availability signals.
+
+### 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)
+
+### 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
+  richer signal
+
+### Logging Alternatives
+
+Log every alternative approach in `log.md`:
+
+```markdown
+## 2026-03-05 14:00
+
+Source: github_open_to_work
+Primary query: "open to work" location:UK — 30 results, 0 new after dedup
+Alternative 1: "data engineering" "open to work" — 12 results, 1 new prospect
+Alternative 2: "full stack" "available for hire" — 8 results, 0 new
+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:
+
+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
+   ```
+
+2. **Do not retry** the same source in this wake cycle. Move on.
+
+3. **Suspend after 3 consecutive failures.** During source selection, skip any
+   source with count ≥ 3 in `failures.tsv`. The agent should still attempt
+   suspended sources once every 7 days to detect recovery.
+
+4. **Common failure patterns:**
+   - **503 with HTML redirect** — Corporate proxy blocking the domain
+     (social-networking category). Source will not recover without network
+     change.
+   - **403 Forbidden** — API requires authentication or blocks automated
+     requests. Source may not recover.
+   - **429 Too Many Requests** — Rate limited. Will recover. Don't suspend
+     permanently.
+   - **Empty response / timeout** — Transient. Will likely recover.
+
+5. **Log all failures** in `log.md` with the HTTP status and error details.
+
+6. **Reset on success.** When a previously-failing source succeeds, reset its
+   count to 0 in `failures.tsv`.
+
+## Filtering Pipeline
+
+Apply these filters to each candidate post, in order:
+
+### Filter 1: Open-for-Hire Signal
+
+- HN "Who Wants to Be Hired?" — **auto-pass** (thread is explicitly opt-in)
+- GitHub — must have `hireable: true`, or bio containing open-to-work phrases
+- dev.to — must be tagged `opentowork` or `lookingforwork`
+
+### Filter 2: Deduplication
+
+```bash
+grep -q "^{source}\t{post_id}\t" ~/.cache/fit/basecamp/head-hunter/seen.tsv
+```
+
+If found, skip. Otherwise continue.
+
+### Filter 3: Geographic Fit
+
+Look for location mentions. Prefer candidates in or open to:
+
+- **US East Coast** (NYC, Boston, DC, Philadelphia, etc.)
+- **UK** (London, Manchester, Edinburgh, etc.)
+- **EU** — especially Greece, Poland, Romania, Bulgaria
+- **Remote / Anywhere / Global**
+
+Skip candidates explicitly locked to incompatible locations (e.g., "San
+Francisco only", "APAC only"). When location is ambiguous or unstated, include
+the candidate — let the user decide.
+
+### Filter 4: Skill Alignment
+
+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
+- Full-stack development with business context
+- Non-traditional path (law, policy, academia → tech)
+- 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
+- Performance, scalability, reliability
+
+**Minimum bar:** At least 2 framework-relevant skills must be identifiable from
+the post. Skip candidates with purely non-technical profiles.
+
+### Filter 5: Experience Level
+
+Estimate career level from signals:
+
+| Signal                                      | Likely Level |
+| ------------------------------------------- | ------------ |
+| "junior", "entry-level", 0-2 years          | J040         |
+| "mid-level", 3-5 years                      | J060         |
+| "senior", 5-8 years, "lead"                 | J070         |
+| "staff", "principal", 8+ years, "architect" | J090+        |
+
+When uncertain, default to J060 with low confidence.
+
+## Prospect Note Format
+
+Write to `knowledge/Prospects/{Name}.md`:
+
+```markdown
+# {Name}
+
+## Info
+**Source:** [{platform}]({permalink})
+**Date found:** {YYYY-MM-DD}
+**Location:** {location or "Not specified"}
+**Estimated level:** {J040–J110} (confidence: {high/medium/low})
+**Best track fit:** {forward_deployed / platform / either}
+**Match strength:** {strong / moderate}
+
+## Profile
+{2-4 sentences: who they are, what they do, why they match. Reference specific
+framework skill IDs in parentheses where possible.}
+
+## Framework Alignment
+**Matching skills:** {comma-separated skill IDs}
+**Key strengths:** {what stands out relative to the framework}
+**Gaps:** {notable missing skills for the estimated role}
+
+## Source Post
+> {Brief excerpt or summary of the original post — 2-3 lines max}
+
+## Notes
+{Additional observations: polymath signals, AI tool usage, unusual background
+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.
+
+## Quality Checklist
+
+- [ ] Selected the least-recently-checked source from cursor.tsv
+- [ ] Fetched data using WebFetch (not curl/wget)
+- [ ] Applied all 5 filters in order
+- [ ] Checked seen.tsv before processing each post
+- [ ] Used fit-pathway to benchmark each prospect against a real job
+- [ ] Prospect notes follow the standard format
+- [ ] Updated cursor.tsv with new position
+- [ ] Appended all processed post IDs to seen.tsv
+- [ ] Appended new prospects to prospects.tsv
+- [ ] Appended wake summary to log.md
+- [ ] Wrote triage report to state 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