@forwardimpact/basecamp 2.0.0 → 2.3.0

package/template/.claude/skills/draft-emails/SKILL.md

@@ -1,57 +1,46 @@
 ---
 name: draft-emails
-description: Draft email responses using the knowledge base and calendar for full context on every person and conversation. Use when the user asks to draft, reply to, or respond to an email. Looks up people and organizations in the knowledge base before drafting.
+description: Draft and send email responses using the knowledge base and calendar for context. Use when the user asks to draft, reply to, respond to, or send an email.
 ---
 
 # Draft Emails
 
-Help the user draft email responses. Uses the knowledge base and calendar for
-full context on every person and conversation. This is an interactive skill —
-the user triggers it by asking to draft or reply to emails.
+Draft and send email responses. Uses the knowledge base and calendar for full
+context on every person and conversation. All drafts require explicit user
+approval before sending.
 
 ## Trigger
 
-Run when the user asks to draft, reply to, or respond to an email.
+Run when the user asks to draft, reply to, respond to, or send an email.
 
 ## Prerequisites
 
 - Knowledge base populated (from `extract-entities` skill)
-- Synced email data in `~/.cache/fit/basecamp/apple_mail/` or
-  `~/.cache/fit/basecamp/gmail/`
+- Synced email data in `~/.cache/fit/basecamp/apple_mail/`
 
-## Inputs
+## Data Locations
 
-- `knowledge/People/*.md` — person context
-- `knowledge/Organizations/*.md` — organization context
-- `~/.cache/fit/basecamp/apple_mail/*.md` or `~/.cache/fit/basecamp/gmail/*.md`
-  — email threads
-- `~/.cache/fit/basecamp/apple_calendar/*.json` — calendar events (for
-  scheduling)
-- `drafts/last_processed` — timestamp of last processing run
-- `drafts/drafted` — list of drafted email IDs (one per line)
-- `drafts/ignored` — list of ignored email IDs (one per line)
-
-## Outputs
-
-- `drafts/{email_id}_draft.md` — draft email files
-- `drafts/last_processed` — updated timestamp
-- `drafts/drafted` — updated with newly drafted IDs
-- `drafts/ignored` — updated with newly ignored IDs
+| Data            | Location                                      |
+| --------------- | --------------------------------------------- |
+| People          | `knowledge/People/*.md`                       |
+| Organizations   | `knowledge/Organizations/*.md`                |
+| Email threads   | `~/.cache/fit/basecamp/apple_mail/*.md`       |
+| Calendar events | `~/.cache/fit/basecamp/apple_calendar/*.json` |
+| Drafted IDs     | `drafts/drafted` (one ID per line)            |
+| Ignored IDs     | `drafts/ignored` (one ID per line)            |
+| Draft files     | `drafts/{email_id}_draft.md`                  |
 
 ---
 
-## Critical: Always Look Up Context First
-
-**BEFORE drafting any email, you MUST look up the person/organization in the
-knowledge base.**
+## Always Look Up Context First
 
-When the user says "draft an email to Monica" or mentions ANY person:
+**BEFORE drafting any email, look up the person/organization in the knowledge
+base.**
 
-1. **STOP** — Do not draft anything yet
-2. **SEARCH** — Look them up: `rg -l "Monica" knowledge/`
-3. **READ** — Read their note: `cat "knowledge/People/Monica Smith.md"`
-4. **UNDERSTAND** — Extract role, organization, relationship history, open items
-5. **THEN DRAFT** — Only now draft the email, using this context
+1. **Search** — `rg -l "Name" knowledge/`
+2. **Read** — `cat "knowledge/People/Name.md"`
+3. **Understand** — Extract role, organization, relationship history, open items
+4. **Draft** — Only now draft the email, using this context
 
 ## Key Principles
 
@@ -59,55 +48,46 @@ When the user says "draft an email to Monica" or mentions ANY person:
 
 - If intent is unclear, ASK what the email should be about
 - If a person has multiple contexts, ASK which one
-- **WRONG:** "Here are three variants — pick one"
-- **RIGHT:** "I see Akhilesh is involved in Rowboat and banking. Which topic?"
 
-**Be decisive, not generic:**
+**Be decisive:**
 
-- Once you know the context, draft ONE email — no multiple versions
-- Every draft must be personalized from knowledge base context
-- Infer tone and approach from context
-
-## Processing Flow
-
-### Step 1: Scan for New Emails
+- Draft ONE email — no multiple versions
+- Personalize from knowledge base context
+- Match the tone of the incoming email
 
-Find unprocessed emails using the scan script:
+**User approves before sending:**
 
-    bash scripts/scan-emails.sh
+- Always present the draft for review before sending
+- Never send without explicit approval
 
-This outputs tab-separated `email_id<TAB>subject` for each email not yet in
-`drafts/drafted` or `drafts/ignored`.
+## Workflow
 
-### Step 2: Parse Email
+### 1. Scan for New Emails
 
-Each email file is markdown with headers:
+```bash
+node scripts/scan-emails.mjs
+```
 
-- `# Subject Line`
-- `**Thread ID:** <id>`
-- `**Message Count:** <count>`
-- `### From: Name <email@example.com>`
-- `**Date:** <date>`
+Outputs tab-separated `email_id<TAB>subject` for unprocessed emails.
 
-### Step 3: Classify Email
+### 2. Classify
 
-**IGNORE** (append ID to `drafts/ignored`):
+**Ignore** (append ID to `drafts/ignored`):
 
 - Newsletters, marketing, automated notifications
 - Spam or irrelevant cold outreach
 - Outbound emails from user with no reply
 
-**DRAFT response for:**
+**Draft response for:**
 
 - Meeting requests or scheduling
 - Personal emails from known contacts
-- Business inquiries
-- Follow-ups on existing conversations
+- Business inquiries or follow-ups
 - Emails requesting information or action
 
-### Step 4: Gather Context
+### 3. Gather Context
 
-**Knowledge Base (REQUIRED for every draft):**
+**Knowledge base** (required for every draft):
 
 ```bash
 rg -l "sender_name" knowledge/
@@ -115,106 +95,88 @@ cat "knowledge/People/Sender Name.md"
 cat "knowledge/Organizations/Company Name.md"
 ```
 
-**Calendar (for scheduling emails):**
+**Calendar** (for scheduling emails):
 
 ```bash
-ls ~/.cache/fit/basecamp/apple_calendar/ ~/.cache/fit/basecamp/google_calendar/ 2>/dev/null
+ls ~/.cache/fit/basecamp/apple_calendar/ 2>/dev/null
 cat "$HOME/.cache/fit/basecamp/apple_calendar/event123.json"
 ```
 
-### Step 5: Create Draft
+### 4. Write Draft
 
-Write draft to `drafts/{email_id}_draft.md`:
+Save to `drafts/{email_id}_draft.md`:
 
 ```markdown
 # Draft Response
 
-**Original Email ID:** {id}
-**Original Subject:** {subject}
-**From:** {sender}
-**Date Processed:** {date}
-
----
-
-## Context Used
-- Calendar: {relevant info or N/A}
-- Knowledge: {relevant notes or N/A}
+**To:** recipient@example.com
+**CC:** other@example.com
+**Subject:** Re: {subject}
 
 ---
 
-## Draft Response
-
-Subject: Re: {subject}
-
 {personalized draft body}
 
 ---
 
 ## Notes
-{why this response was crafted this way}
+- **Original Email ID:** {id}
+- **From:** {sender}
+- **Context:** {knowledge base notes used}
 ```
 
-**Guidelines:**
+Guidelines:
 
-- Draft ONE email — no multiple versions
-- Reference past interactions naturally
-- Match the tone of the incoming email
-- For scheduling: propose specific times from calendar
-- If unsure about intent, ask a clarifying question
+- Draft ONE email — reference past interactions naturally
+- For scheduling: propose specific times from calendar availability
+- If unsure about intent, ask a clarifying question instead of drafting
+
+### 5. Present for Review
+
+Show the draft to the user. Wait for explicit approval before sending. The user
+may request edits — apply them and present again.
 
-### Step 6: Update State
+### 6. Send
 
-After each email, update the state files:
+After the user approves, send via Apple Mail:
 
 ```bash
-echo "$EMAIL_ID" >> drafts/drafted   # or drafts/ignored
-date -u '+%Y-%m-%dT%H:%M:%SZ' > drafts/last_processed
+node scripts/send-email.mjs \
+  --to "recipient@example.com" \
+  --cc "other@example.com" \
+  --subject "Re: Subject" \
+  --body "Plain text body"
 ```
 
-### Step 7: Summary
+Options: `--to` (required), `--cc` (optional), `--bcc` (optional), `--subject`
+(required), `--body` (required, plain text only).
 
-```
-## Processing Summary
-**Emails Scanned:** X
-**Drafts Created:** Y
-**Ignored:** Z
+Do NOT include an email signature — Apple Mail appends the configured signature
+automatically.
 
-### Drafts Created:
-- {id}: {subject} — {reason}
+### 7. Update State
 
-### Ignored:
-- {id}: {subject} — {reason}
+```bash
+echo "$EMAIL_ID" >> drafts/drafted   # or drafts/ignored
 ```
 
 ## Recruitment & Staffing Emails
 
-**CRITICAL: Candidates must NEVER be copied on internal emails about them.**
-
-When an email involves recruitment, staffing, or hiring:
+**Candidates must NEVER be copied on internal emails about them.**
 
-1. **Identify the candidate** — Determine who the candidate is from the email
-   thread and knowledge base (`knowledge/Candidates/`, `knowledge/People/`)
-2. **Strip the candidate from recipients** — The draft must ONLY be addressed to
-   internal stakeholders (hiring managers, recruiters, interview panel, etc.).
-   The candidate’s email address must NOT appear in To, CC, or BCC
-3. **Only recruiters email candidates directly** — If the email is a direct
-   reply TO a candidate (e.g., scheduling an interview, extending an offer),
-   flag it clearly so only the recruiter sends it. Add a note:
+1. **Identify the candidate** from the thread and knowledge base
+2. **Strip the candidate from recipients** — draft to internal stakeholders only
+3. **Direct-to-candidate emails** — flag with:
    `⚠️ RECRUITER ONLY — This email goes directly to the candidate.`
 
-**Examples of internal recruitment emails (candidate must NOT be copied):**
-
-- Interview feedback or debrief
-- Candidate evaluation or comparison
-- Hiring decision discussions
-- Compensation/offer discussions
-- Reference check follow-ups between colleagues
+Internal recruitment emails (candidate excluded): interview feedback, candidate
+evaluation, hiring decisions, compensation discussions, reference checks.
 
-**When in doubt:** If an email thread mentions a candidate by name and involves
-multiple internal recipients, treat it as internal and exclude the candidate.
+**When in doubt:** If an email thread mentions a candidate and involves multiple
+internal recipients, treat it as internal and exclude the candidate.
 
 ## Constraints
 
-- Never actually send emails — only create drafts
+- Never send without explicit user approval
 - Be conservative with ignore — when in doubt, create a draft
-- For ambiguous emails, create a draft with a note explaining the ambiguity
+- For ambiguous emails, draft with a note explaining the ambiguity

package/template/.claude/skills/draft-emails/scripts/scan-emails.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * Scan for unprocessed emails and output their IDs and subjects.
+ *
+ * Checks ~/.cache/fit/basecamp/apple_mail/ for email thread markdown files not
+ * yet listed in drafts/drafted or drafts/ignored. Outputs one tab-separated
+ * line per unprocessed thread: email_id<TAB>subject. Used by the draft-emails
+ * skill to identify threads that need a reply.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { homedir } from "node:os";
+
+const HELP = `scan-emails — list unprocessed email threads
+
+Usage: node scripts/scan-emails.mjs [-h|--help]
+
+Scans ~/.cache/fit/basecamp/apple_mail/ for .md thread files not yet
+recorded in drafts/drafted or drafts/ignored. Outputs one line per
+unprocessed thread as: email_id<TAB>subject`;
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+const HOME = homedir();
+const MAIL_DIR = join(HOME, ".cache/fit/basecamp/apple_mail");
+
+/** Load a file of IDs (one per line) into a Set. */
+function loadIdSet(path) {
+  const ids = new Set();
+  if (!existsSync(path)) return ids;
+  for (const line of readFileSync(path, "utf-8").split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed) ids.add(trimmed);
+  }
+  return ids;
+}
+
+/** Extract the first H1 heading from a markdown file. */
+function extractSubject(filePath) {
+  const text = readFileSync(filePath, "utf-8");
+  const match = text.match(/^# (.+)$/m);
+  return match ? match[1] : "";
+}
+
+function main() {
+  if (!existsSync(MAIL_DIR)) return;
+
+  const drafted = loadIdSet("drafts/drafted");
+  const ignored = loadIdSet("drafts/ignored");
+
+  for (const name of readdirSync(MAIL_DIR).sort()) {
+    if (!name.endsWith(".md")) continue;
+
+    const emailId = basename(name, ".md");
+    if (drafted.has(emailId) || ignored.has(emailId)) continue;
+
+    const subject = extractSubject(join(MAIL_DIR, name));
+    console.log(`${emailId}\t${subject}`);
+  }
+}
+
+main();

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

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * Send an email via Apple Mail using AppleScript.
+ *
+ * Builds an AppleScript command to create and send an outgoing message through
+ * 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.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const HELP = `send-email — send an email via Apple Mail
+
+Usage: node scripts/send-email.mjs --to <addrs> --subject <subj> --body <text> [options]
+
+Options:
+  --to <addrs>       Comma-separated To recipients (required)
+  --cc <addrs>       Comma-separated CC recipients
+  --bcc <addrs>      Comma-separated BCC recipients
+  --subject <subj>   Email subject line (required)
+  --body <text>      Plain-text email body (required)
+  -h, --help         Show this help message and exit
+
+Mail.app must be running. No email signature needed — Apple Mail appends it.`;
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+/** Escape a string for AppleScript double-quoted context. */
+function escapeAS(s) {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+/** Build recipient lines for AppleScript. */
+function recipientLines(type, addrs) {
+  if (!addrs) return "";
+  return addrs
+    .split(",")
+    .map((a) => a.trim())
+    .filter(Boolean)
+    .map(
+      (addr) =>
+        `        make new ${type} at end of ${type}s with properties {address:"${escapeAS(addr)}"}`,
+    )
+    .join("\n");
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  let to = "",
+    cc = "",
+    bcc = "",
+    subject = "",
+    body = "";
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case "--to":
+        to = args[++i] ?? "";
+        break;
+      case "--cc":
+        cc = args[++i] ?? "";
+        break;
+      case "--bcc":
+        bcc = args[++i] ?? "";
+        break;
+      case "--subject":
+        subject = args[++i] ?? "";
+        break;
+      case "--body":
+        body = args[++i] ?? "";
+        break;
+    }
+  }
+
+  if (!to || !subject || !body) {
+    console.error("Error: --to, --subject, and --body are required.");
+    console.error("Run with --help for usage info.");
+    process.exit(1);
+  }
+
+  const lines = [
+    'tell application "Mail"',
+    `    set newMessage to make new outgoing message with properties {subject:"${escapeAS(subject)}", content:"${escapeAS(body)}", visible:false}`,
+    "    tell newMessage",
+    recipientLines("to recipient", to),
+    cc ? recipientLines("cc recipient", cc) : "",
+    bcc ? recipientLines("bcc recipient", bcc) : "",
+    "    end tell",
+    "    send newMessage",
+    "end tell",
+  ]
+    .filter(Boolean)
+    .join("\n");
+
+  const tmp = join(mkdtempSync(join(tmpdir(), "send-email-")), "mail.scpt");
+  try {
+    writeFileSync(tmp, lines);
+    execFileSync("osascript", [tmp], { stdio: "inherit" });
+    console.log(`Sent: ${subject}`);
+  } finally {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+}
+
+main();

package/template/.claude/skills/extract-entities/SKILL.md

@@ -68,7 +68,7 @@ Run this skill:
 1.  Read `USER.md` to get the user's name, email, and domain
 2.  Find new/changed files to process:
 
-         python3 scripts/state.py check
+         node scripts/state.mjs check
 
     This outputs one file path per line for all source files that are new or
     have changed since last processing.
@@ -434,7 +434,7 @@ Always use absolute links: `[[People/Sarah Chen]]`,
 
 After processing each file, update the state:
 
-    python3 scripts/state.py update "$FILE"
+    node scripts/state.mjs update "$FILE"
 
 ## Source Type Rules Summary
 

package/template/.claude/skills/extract-entities/scripts/state.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * Manage graph_processed state for entity extraction.
+ *
+ * Tracks which source files (synced emails and calendar events) have already
+ * been processed by the extract-entities skill. The `check` command lists files
+ * that are new or changed since their last recorded hash; `update` marks files
+ * as processed by storing their current SHA-256 hash.
+ *
+ * State is persisted as a TSV file at
+ * ~/.cache/fit/basecamp/state/graph_processed (path<TAB>hash).
+ */
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  console.log(`state — manage graph_processed state for entity extraction
+
+Usage:
+  node scripts/state.mjs check                    List new/changed files
+  node scripts/state.mjs update <path> [<path>…]  Mark files as processed
+  node scripts/state.mjs -h|--help                 Show this help message
+
+State file: ~/.cache/fit/basecamp/state/graph_processed (TSV: path<TAB>hash)`);
+  process.exit(0);
+}
+
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const HOME = homedir();
+const STATE_FILE = join(HOME, ".cache/fit/basecamp/state/graph_processed");
+const SOURCE_DIRS = [
+  join(HOME, ".cache/fit/basecamp/apple_mail"),
+  join(HOME, ".cache/fit/basecamp/apple_calendar"),
+];
+
+/** Compute SHA-256 hash of a file. */
+function fileHash(filePath) {
+  const data = readFileSync(filePath);
+  return createHash("sha256").update(data).digest("hex");
+}
+
+/** Load the state file into a Map of {path → hash}. */
+function loadState() {
+  const state = new Map();
+  if (!existsSync(STATE_FILE)) return state;
+  const text = readFileSync(STATE_FILE, "utf-8");
+  for (const line of text.split("\n")) {
+    if (!line) continue;
+    const idx = line.indexOf("\t");
+    if (idx === -1) continue;
+    state.set(line.slice(0, idx), line.slice(idx + 1));
+  }
+  return state;
+}
+
+/** Write the full state Map back to the state file. */
+function saveState(state) {
+  const dir = join(HOME, ".cache/fit/basecamp/state");
+  mkdirSync(dir, { recursive: true });
+  const entries = [...state.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+  const text = entries.length
+    ? entries.map(([p, h]) => `${p}\t${h}`).join("\n") + "\n"
+    : "";
+  writeFileSync(STATE_FILE, text);
+}
+
+/** Find source files that are new or have changed since last processing. */
+function check() {
+  const state = loadState();
+  const newFiles = [];
+  for (const dir of SOURCE_DIRS) {
+    if (!existsSync(dir)) continue;
+    for (const name of readdirSync(dir)) {
+      const filePath = join(dir, name);
+      const stat = statSync(filePath, { throwIfNoEntry: false });
+      if (!stat || !stat.isFile()) continue;
+      const h = fileHash(filePath);
+      if (state.get(filePath) !== h) {
+        newFiles.push(filePath);
+      }
+    }
+  }
+  newFiles.sort();
+  for (const f of newFiles) {
+    console.log(f);
+  }
+  return newFiles.length;
+}
+
+/** Mark files as processed by updating their hashes in state. */
+function update(filePaths) {
+  const state = loadState();
+  for (const fp of filePaths) {
+    if (!existsSync(fp)) {
+      console.error(`Warning: File not found: ${fp}`);
+      continue;
+    }
+    state.set(fp, fileHash(fp));
+  }
+  saveState(state);
+  console.log(`Updated ${filePaths.length} file(s) in graph state`);
+}
+
+// --- CLI ---
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+if (cmd === "check") {
+  const count = check();
+  console.error(`\n${count} file(s) to process`);
+} else if (cmd === "update" && args.length >= 2) {
+  update(args.slice(1));
+} else {
+  console.error(
+    "Usage:\n" +
+      "  node scripts/state.mjs check\n" +
+      "  node scripts/state.mjs update <file-path> [<file-path> …]",
+  );
+  process.exit(1);
+}