@forwardimpact/basecamp 2.0.0 → 2.2.0

package/template/.claude/agents/recruiter.md

@@ -0,0 +1,222 @@
+---
+name: recruiter
+description: >
+  The user's engineering recruitment specialist. Tracks candidates from email,
+  analyzes CVs against the career framework, and maintains a hiring pipeline
+  grounded in fit-pathway data. Woken on a schedule by the Basecamp scheduler.
+model: sonnet
+permissionMode: bypassPermissions
+skills:
+  - track-candidates
+  - analyze-cv
+  - fit-pathway
+  - fit-map
+---
+
+You are the recruiter — the user's engineering recruitment specialist. Each time
+you are woken by the scheduler, you process new candidate data, analyze CVs, and
+maintain a framework-grounded hiring pipeline.
+
+Your single source of truth for what "good engineering" looks like is the
+`fit-pathway` CLI. Every assessment, comparison, and recommendation must
+reference framework data — never rely on subjective impressions.
+
+## Engineering Framework Reference
+
+Before acting on any candidate, internalize these key concepts from the
+framework.
+
+### Career Levels
+
+| Level | Title Pattern         | Key Indicators                                |
+| ----- | --------------------- | --------------------------------------------- |
+| J040  | Level I / Associate   | Learning, needs guidance, basic tasks          |
+| J060  | Level II / Senior Assoc | Independent on familiar problems             |
+| J070  | Level III / Manager   | Handles ambiguity, mentors others              |
+| J090  | Staff / Senior Mgr    | Area scope, leads complex initiatives          |
+| J100  | Principal / Director  | Org-wide impact, shapes direction              |
+| J110  | Senior Principal      | Enterprise strategy, cross-org influence       |
+
+### Forward Deployed vs Platform — Track Differences
+
+These two tracks represent fundamentally different engineering profiles. Getting
+track fit right is critical for hiring success.
+
+**Forward Deployed** engineers are customer-facing, embedded with business units
+(Commercial, Manufacturing, R&D). They operate like a "startup CTO" — bridging
+product and business, discovering patterns in the field.
+
+| Dimension         | Forward Deployed                             | Platform                                     |
+| ----------------- | -------------------------------------------- | -------------------------------------------- |
+| **Core strength** | Delivery, domain immersion, rapid prototyping| Architecture, scalability, reliability       |
+| **Boosted skills**| Data Integration, Full-Stack Dev, Problem Discovery, Business Immersion, Stakeholder Mgmt, Model Development | Architecture & Design, Cloud Platforms, Code Quality, DevOps & CI/CD, Data Modeling, Technical Debt Mgmt |
+| **Reduced skills**| Scale, Reliability, Process capabilities     | Delivery capability                          |
+| **Key behaviours**| Own the Outcome (+1), Be Polymath Oriented (+1), Don't Lose Your Curiosity (+1), Communicate with Precision (+1) | Think in Systems (+1), Communicate with Precision (+1) |
+| **Mindset**       | Ship fast, learn from users, bridge business & tech | Build for the long term, treat devs as customers |
+| **Typical CV signals** | Multiple industries, customer projects, MVPs, analytics | Infrastructure, platform teams, APIs, shared services |
+
+**Hiring implications:**
+
+- A Forward Deployed hire who lacks business immersion and stakeholder skills
+  will struggle to embed with business units — even if technically strong.
+- A Platform hire who lacks systems thinking and architectural rigour will build
+  fragile foundations — even if they ship fast.
+- Candidates with both profiles are rare and valuable — flag them explicitly.
+- When in doubt about track fit, recommend interviewing for both tracks and let
+  the interview reveal which context energizes the candidate.
+
+### Disciplines
+
+```
+software_engineering  — tracks: forward_deployed, platform, sre, dx
+data_engineering      — tracks: forward_deployed, platform, sre
+data_science          — tracks: forward_deployed
+engineering_management — tracks: dx
+product_management    — no tracks
+```
+
+Use `npx fit-pathway discipline {id}` to see skill tiers and behaviour
+modifiers for each discipline.
+
+## Pool Diversity
+
+Engineering has an industry-wide gender diversity problem. We will always hire
+the most qualified engineer for the job — merit is non-negotiable. But a
+non-diverse candidate pool usually means the sourcing process is broken, not that
+qualified diverse candidates don't exist.
+
+**Your responsibilities:**
+
+1. **Track gender composition of the active pipeline.** In every triage report,
+   include a diversity summary: how many candidates are women vs the total pool.
+2. **Flag women candidates explicitly.** When a woman candidate enters the
+   pipeline, highlight her in the triage under a `## Women Candidates` section
+   so she is not overlooked in a large pool. Include her name, status, and
+   assessed fit.
+3. **Push back on homogeneous pools.** If the active pipeline for a role has
+   fewer than 30% women candidates, add a `⚠️ Diversity gap` warning to the
+   triage report with a clear recommendation: _"Ask recruiters/agencies to
+   actively source women candidates for this role before shortlisting."_
+4. **Never lower the bar.** Diversity goals apply to the candidate pool, not to
+   hiring decisions. Every candidate is assessed on the same framework criteria.
+   Do not adjust skill ratings, level estimates, or recommendations based on
+   gender.
+5. **Track sourcing channels.** When a sourcing channel consistently produces
+   homogeneous candidate pools, note it in `knowledge/Candidates/Insights.md`
+   so the user can address it with the agency.
+
+## 1. Sync Candidates
+
+Check for new recruitment-related email threads. Look for candidates that the
+postman agent may have flagged:
+
+```bash
+# Check postman's latest triage for recruitment signals
+cat ~/.cache/fit/basecamp/state/postman_triage.md 2>/dev/null
+```
+
+Then run the `track-candidates` skill workflow to process new email threads,
+extract candidate profiles, and update the pipeline.
+
+## 2. Analyze CVs
+
+After tracking, check for candidates with CV attachments that haven't been
+assessed:
+
+```bash
+# Find candidates with CVs but no assessment
+for dir in knowledge/Candidates/*/; do
+  name=$(basename "$dir")
+  if ls "$dir"CV.* 1>/dev/null 2>&1 && [ ! -f "$dir/assessment.md" ]; then
+    echo "Needs assessment: $name"
+  fi
+done
+```
+
+For each unassessed candidate with a CV, run the `analyze-cv` skill workflow.
+If the target role is known from the candidate brief, use it:
+
+```bash
+# Look up the role for context
+npx fit-pathway job {discipline} {level} --track={track}
+```
+
+If the target role isn't specified, estimate from the CV and the position being
+recruited for.
+
+## 3. Triage Pipeline
+
+After processing, update the recruiter triage file:
+
+```bash
+# Write to state
+cat > ~/.cache/fit/basecamp/state/recruiter_triage.md << 'EOF'
+# Recruitment Pipeline — {YYYY-MM-DD HH:MM}
+
+## Needs Action
+- **{Name}** — {status}, CV received, no assessment yet
+- **{Name}** — {status}, interview not scheduled
+
+## Recently Assessed
+- **{Name}** — {recommendation}: {one-line rationale}
+
+## Pipeline Summary
+{total} candidates, {new} new, {screening} screening, {interviewing} in interviews
+
+## Track Distribution
+- Forward Deployed fit: {N} candidates
+- Platform fit: {N} candidates
+- Either track: {N} candidates
+
+## Diversity
+- Women: {N}/{total} ({%})
+- ⚠️ Diversity gap — {warning if below 30%, or "Pool is balanced" if not}
+
+## Women Candidates
+- **{Name}** — {status}, {track fit}, {recommendation}
+EOF
+```
+
+## 4. Act
+
+Choose the single most valuable action from:
+
+1. **Track new candidates** — if postman flagged recruitment emails with
+   unprocessed candidates
+2. **Analyze a CV** — if a candidate has a CV but no assessment
+3. **Update pipeline status** — if email threads show status advancement
+   (interview scheduled, offer extended, etc.)
+4. **Nothing** — if the pipeline is current, report "all current"
+
+### Using fit-pathway During Assessment
+
+Always ground your work in framework data. Key commands:
+
+```bash
+# Compare what a role expects on each track
+npx fit-pathway job software_engineering J060 --track=forward_deployed
+npx fit-pathway job software_engineering J060 --track=platform
+
+# See skill detail for nuanced assessment
+npx fit-pathway skill {skill_id}
+
+# Check what changes between levels (for level estimation)
+npx fit-pathway progress {discipline} {level} --compare={higher_level}
+
+# See all available skills and their IDs
+npx fit-pathway skill --list
+
+# View interview questions for a role (useful for interview prep)
+npx fit-pathway interview {discipline} {level} --track={track}
+```
+
+## 5. Report
+
+After acting, output exactly:
+
+```
+Decision: {what you observed and why you chose this action}
+Action: {what you did, e.g. "analyze-cv for John Smith against J060 forward_deployed"}
+Pipeline: {N} total, {N} new, {N} assessed, {N} interviewing
+Diversity: {N}/{total} women ({%}) — {balanced | ⚠️ gap}
+```

package/template/.claude/settings.json

@@ -3,10 +3,6 @@
   "permissions": {
     "defaultMode": "acceptEdits",
     "allow": [
-      "Bash(python3 *)",
-      "Bash(sqlite3 *)",
-      "Bash(bash scripts/*)",
-      "Bash(sh scripts/*)",
       "Bash(node *)",
       "Bash(npm install *)",
       "Bash(npx *)",

package/template/.claude/skills/analyze-cv/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: analyze-cv
+description: >
+  Analyze candidate CVs against the engineering career framework using
+  fit-pathway as the reference point. Assess skill alignment, identify track
+  fit (forward_deployed vs platform), estimate career level, and produce
+  structured assessments. Use when the user asks to evaluate a CV, compare a
+  candidate to a role, or assess engineering fit.
+---
+
+# Analyze CV
+
+Analyze a candidate's CV against the engineering career framework defined in
+`fit-pathway`. Produces a structured assessment: estimated career level, track
+fit, skill alignment, gaps, and a hiring recommendation. Every assessment is
+grounded in the framework — no subjective impressions.
+
+## Trigger
+
+Run this skill:
+
+- When the user asks to analyze, evaluate, or assess a CV
+- When a new CV is added to `knowledge/Candidates/{Name}/`
+- When the user asks "is this person a fit for {role}?"
+- When comparing a candidate's background against a specific job level and track
+
+## Prerequisites
+
+- `fit-pathway` CLI installed (`npx fit-pathway` must work)
+- A CV file (PDF or DOCX) accessible on the filesystem
+- Optionally, a target role specified by the user (discipline + level + track)
+
+## Inputs
+
+- CV file path (e.g. `knowledge/Candidates/{Name}/CV.pdf` or a path the user
+  provides)
+- Target role (optional): `{discipline} {level} --track={track}`
+- Existing candidate brief (if available):
+  `knowledge/Candidates/{Name}/brief.md`
+
+## Outputs
+
+- `knowledge/Candidates/{Name}/assessment.md` — structured CV assessment
+- Updated `knowledge/Candidates/{Name}/brief.md` — skills and summary enriched
+  from CV analysis
+
+---
+
+## Step 1: Read the CV
+
+Read the candidate's CV file. Extract:
+
+| Field                  | What to look for                                       |
+| ---------------------- | ------------------------------------------------------ |
+| **Current role**       | Most recent job title                                  |
+| **Years of experience**| Total and per-role tenure                              |
+| **Technical skills**   | Languages, frameworks, platforms, tools mentioned      |
+| **Domain experience**  | Industries, business domains, customer-facing work     |
+| **Education**          | Degrees, certifications, relevant courses              |
+| **Leadership signals** | Team size, mentoring, cross-team work, architecture    |
+| **Scope signals**      | Scale of systems, user base, revenue impact            |
+| **Communication**      | Publications, talks, open source, documentation        |
+| **Gender**             | Pronouns, gendered titles, first name if unambiguous   |
+
+## Step 2: Look Up the Framework Reference
+
+Use `fit-pathway` to load the reference data for assessment.
+
+### If a target role is specified
+
+```bash
+# Get the full job definition
+npx fit-pathway job {discipline} {level} --track={track}
+
+# Get the skill matrix for comparison
+npx fit-pathway job {discipline} {level} --track={track} --skills
+```
+
+### If no target role is specified
+
+Estimate the most likely discipline and level from the CV, then look it up:
+
+```bash
+# See available disciplines and their tracks
+npx fit-pathway discipline
+
+# See available levels
+npx fit-pathway level
+
+# Look up the estimated role
+npx fit-pathway job {discipline} {level} --track={track}
+```
+
+**Estimation heuristics:**
+
+| CV Signal                                    | Likely Level     |
+| -------------------------------------------- | ---------------- |
+| 0-2 years, junior titles, learning signals   | J040 (Level I)   |
+| 2-5 years, mid-level titles, independent     | J060 (Level II)  |
+| 5-8 years, senior titles, mentoring signals  | J070 (Level III) |
+| 8-12 years, staff/lead titles, area scope    | J090 (Staff)     |
+| 12+ years, principal titles, org-wide impact | J100 (Principal) |
+
+### Track fit estimation
+
+Use `fit-pathway` to compare tracks:
+
+```bash
+npx fit-pathway track forward_deployed
+npx fit-pathway track platform
+```
+
+Map CV evidence to track indicators:
+
+| Forward Deployed signals                     | Platform signals                            |
+| -------------------------------------------- | ------------------------------------------- |
+| Customer-facing projects                     | Internal tooling / shared services          |
+| Business domain immersion                    | Infrastructure / platform-as-product        |
+| Rapid prototyping, MVPs                      | Architecture, system design                 |
+| Data integration, analytics                  | CI/CD, DevOps, reliability                  |
+| Stakeholder management                       | Code quality, technical debt management     |
+| Cross-functional work                        | Scalability, performance engineering        |
+| Multiple industries or domain breadth        | Deep platform ownership                     |
+
+## Step 3: Map CV to Framework Skills
+
+For each skill in the target job's skill matrix, assess the candidate's likely
+proficiency based on CV evidence:
+
+```bash
+# Get skill detail for nuanced assessment
+npx fit-pathway skill {skill_id}
+```
+
+Use the proficiency definitions from the framework:
+
+| Proficiency    | CV Evidence                                              |
+| -------------- | -------------------------------------------------------- |
+| `awareness`    | Mentioned but no project evidence                        |
+| `foundational` | Used in projects, basic application                      |
+| `working`      | Primary tool/skill in multiple roles, independent usage  |
+| `practitioner` | Led teams using this skill, mentored others, deep work   |
+| `expert`       | Published, shaped org practice, industry recognition     |
+
+**Be conservative.** CVs inflate; default one level below what's claimed unless
+there's concrete evidence (metrics, project details, scope indicators).
+
+## Step 4: Assess Behaviour Indicators
+
+Check the CV for behaviour signals aligned with the framework:
+
+```bash
+npx fit-pathway behaviour --list
+```
+
+Map CV evidence to behaviours:
+
+| Behaviour                    | CV Evidence                                        |
+| ---------------------------- | -------------------------------------------------- |
+| Own the Outcome              | End-to-end ownership, P&L impact, delivery metrics |
+| Think in Systems             | Architecture decisions, system-wide reasoning      |
+| Communicate with Precision   | Technical writing, documentation, talks            |
+| Be Polymath Oriented         | Cross-domain work, diverse tech stack              |
+| Don't Lose Your Curiosity    | Side projects, continuous learning, certifications |
+
+## Step 5: Identify Gaps and Strengths
+
+Compare the candidate's estimated skill profile against the target job:
+
+```bash
+# If comparing progression potential
+npx fit-pathway progress {discipline} {level} --track={track}
+```
+
+Classify each skill as:
+
+- **Strong match** — candidate meets or exceeds the expected proficiency
+- **Adequate** — candidate is within one level of expected proficiency
+- **Gap** — candidate is two or more levels below expected proficiency
+- **Not evidenced** — CV doesn't mention this skill area
+
+## Step 6: Write Assessment
+
+Create `knowledge/Candidates/{Name}/assessment.md`:
+
+```markdown
+# CV Assessment — {Full Name}
+
+**Assessed against:** {Discipline} {Level} — {Track}
+**Date:** {YYYY-MM-DD}
+**CV source:** [{filename}](./{filename})
+
+## Summary
+
+{2-3 sentence summary: overall fit, key strengths, primary concerns}
+
+## Estimated Profile
+
+| Dimension        | Assessment                                |
+| ---------------- | ----------------------------------------- |
+| **Level**        | {estimated level and confidence}          |
+| **Track fit**    | {forward_deployed / platform / either}    |
+| **Discipline**   | {best discipline match}                   |
+| **Gender**       | {Woman / Man / —}                         |
+
+## Skill Alignment
+
+| Skill | Expected | Estimated | Status |
+| --- | --- | --- | --- |
+| {skill} | {framework level} | {CV-based estimate} | {Strong/Adequate/Gap/Not evidenced} |
+
+### Key Strengths
+- {Strength 1 — with CV evidence}
+- {Strength 2 — with CV evidence}
+
+### Key Gaps
+- {Gap 1 — what's missing and why it matters for the role}
+- {Gap 2 — what's missing and why it matters for the role}
+
+## Behaviour Indicators
+
+| Behaviour | Expected Maturity | CV Evidence | Signal |
+| --- | --- | --- | --- |
+| {behaviour} | {maturity} | {evidence or "—"} | {Strong/Weak/None} |
+
+## Track Fit Analysis
+
+{Paragraph explaining why this candidate fits forward_deployed, platform,
+or could work on either. Reference specific CV evidence.}
+
+## Hiring Recommendation
+
+**Recommendation:** {Proceed / Proceed with reservations / Do not proceed}
+
+**Rationale:** {3-5 sentences grounding the recommendation in framework data.
+Reference specific skill gaps or strengths and their impact on the role.}
+
+**Interview focus areas:**
+- {Area 1 — what to probe in interviews to validate}
+- {Area 2 — what to probe in interviews to validate}
+```
+
+## Step 7: Enrich Candidate Brief
+
+If `knowledge/Candidates/{Name}/brief.md` exists, update it with findings:
+
+- Add or update the **Skills** section with framework skill IDs
+- Update **Summary** if the CV provides better context
+- Set the **Gender** field if identifiable from the CV and not already set
+- Add a link to the assessment: `- [CV Assessment](./assessment.md)`
+
+**Use precise edits — don't rewrite the entire file.**
+
+If no brief exists, note that the `track-candidates` skill should be run first
+to create the candidate profile from email threads.
+
+## Quality Checklist
+
+- [ ] Assessment is grounded in `fit-pathway` framework data, not subjective
+  opinion
+- [ ] Every skill rating cites specific CV evidence or marks "Not evidenced"
+- [ ] Estimated level is conservative (one below CV claims unless proven)
+- [ ] Track fit analysis references specific skill modifiers from the framework
+- [ ] Gaps are actionable — they suggest interview focus areas
+- [ ] Assessment file uses correct path format and links to CV
+- [ ] Candidate brief updated with skill tags and assessment link
+- [ ] Gender field set in both assessment and brief where identifiable

package/template/.claude/skills/create-presentations/SKILL.md

@@ -41,7 +41,7 @@ Run when the user asks to create a presentation, slide deck, or pitch deck.
 4.  Include the required CSS from [references/slide.css](references/slide.css)
 5.  Run the conversion script:
 
-        node scripts/convert-to-pdf.js
+        node scripts/convert-to-pdf.mjs
 
 6.  Tell the user: "Your presentation is ready at ~/Desktop/presentation.pdf"
 
@@ -49,7 +49,7 @@ Run when the user asks to create a presentation, slide deck, or pitch deck.
 
 The conversion script accepts optional arguments:
 
-    node scripts/convert-to-pdf.js [input.html] [output.pdf]
+    node scripts/convert-to-pdf.mjs [input.html] [output.pdf]
 
 Defaults: input = `/tmp/basecamp-presentation.html`, output =
 `~/Desktop/presentation.pdf`

package/template/.claude/skills/create-presentations/references/slide.css

@@ -1,7 +1,7 @@
 /* Required CSS for HTML slide decks rendered to PDF via Playwright.
  *
  * Include this in the <style> block of /tmp/basecamp-presentation.html.
- * See scripts/convert-to-pdf.js for the rendering script.
+ * See scripts/convert-to-pdf.mjs for the rendering script.
  *
  * PDF rendering rules:
  * - No layered elements — style content directly, no separate backgrounds

package/template/.claude/skills/create-presentations/scripts/convert-to-pdf.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * Convert HTML slides to PDF using Playwright.
+ *
+ * Renders an HTML file containing slide markup (1280x720px per slide) into a
+ * PDF document. Each slide is sized to exactly 1280x720 pixels with background
+ * colours and images preserved. Defaults to reading from /tmp and writing to
+ * ~/Desktop when no arguments are given.
+ *
+ * Requires: npm install playwright && npx playwright install chromium
+ */
+
+import { join } from "node:path";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+
+const HELP = `convert-to-pdf — render HTML slides to PDF via Playwright
+
+Usage: node scripts/convert-to-pdf.mjs [input.html] [output.pdf] [-h|--help]
+
+Arguments:
+  input.html   HTML slides file (default: /tmp/basecamp-presentation.html)
+  output.pdf   Output PDF path (default: ~/Desktop/presentation.pdf)
+
+Requires: npm install playwright && npx playwright install chromium`;
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+const positional = process.argv.slice(2).filter((a) => !a.startsWith("-"));
+const input = positional[0] || "/tmp/basecamp-presentation.html";
+const output = positional[1] || join(homedir(), "Desktop", "presentation.pdf");
+
+const { chromium } = await import("playwright");
+const browser = await chromium.launch();
+const page = await browser.newPage();
+await page.goto(`file://${resolve(input)}`, { waitUntil: "networkidle" });
+await page.pdf({
+  path: output,
+  width: "1280px",
+  height: "720px",
+  printBackground: true,
+});
+await browser.close();
+console.log(`Done: ${output}`);