@forwardimpact/basecamp 1.0.0 → 2.2.0

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);
+}

package/template/.claude/skills/manage-tasks/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: manage-tasks
+description: Create, update, list, and close tasks on per-person task boards in knowledge/Tasks/. Manages task lifecycle, extracts action items from other skills, and keeps boards current. Use when the user asks to add, update, or review tasks, or when chained from extract-entities or process-hyprnote.
+---
+
+# Manage Tasks
+
+Manage per-person task boards in `knowledge/Tasks/`. Each person has a single
+living document that tracks all their open, in-progress, blocked, and recently
+completed tasks. Task boards are the **canonical source** for task tracking —
+other notes (People, Projects) link to them rather than duplicating.
+
+## Trigger
+
+Run this skill:
+
+- When the user asks to add, update, close, or list tasks
+- When chained from `extract-entities` or `process-hyprnote` with extracted
+  action items
+- When the user asks to see someone's task board or workload
+- On a schedule to perform housekeeping (prune done items, flag overdue)
+
+## Prerequisites
+
+- `knowledge/Tasks/` directory exists
+- User identity configured in `USER.md`
+
+## Inputs
+
+### User-initiated
+
+- Person name and task details from the user's request
+
+### Chained from other skills
+
+Action items extracted by `extract-entities` or `process-hyprnote`, passed as
+structured data:
+
+```
+TASKS:
+- Owner: {Full Name}
+  Task: {Description — starts with a verb}
+  Priority: high|medium|low
+  Due: YYYY-MM-DD (if known)
+  Source: meeting|email
+  Source date: YYYY-MM-DD
+  Project: {Project Name} (if applicable)
+  Context: {Brief context about where this came from}
+```
+
+## Outputs
+
+- `knowledge/Tasks/{Person Name}.md` — created or updated task boards
+
+---
+
+## Task Board Format
+
+Each task board is a markdown file with four sections, always in this order:
+
+```markdown
+# {Person Name}
+
+## In Progress
+## Open
+## Blocked
+## Recently Done
+```
+
+All four sections are always present, even if empty.
+
+**Task entry format:**
+
+```
+- [ ] **{Task title}** | {priority} | due {YYYY-MM-DD} | [[Projects/Name]]
+  {Context line with source info and backlinks.}
+```
+
+**Key conventions:**
+
+- **Priorities:** `high` | `medium` | `low` — omit if medium (default)
+- **Due dates:** Only include if there's a real deadline. Format:
+  `due YYYY-MM-DD`
+- **No task IDs.** Tasks are identified by their bold title. Keep titles unique
+  within a person's board.
+- **Recently Done:** Keep the last 14 days. Older items pruned during
+  housekeeping.
+
+## Before Starting
+
+1. Read `USER.md` to get user identity.
+2. Determine the operation: **add**, **update**, **close**, **list**, or
+   **housekeeping**.
+
+## Step 1: Resolve the Person
+
+For any task operation, resolve the person to their canonical name:
+
+```bash
+ls knowledge/Tasks/
+rg "{name}" knowledge/People/
+```
+
+If the person doesn't have a task board yet, create one from the template (Step
+4 covers creation).
+
+## Step 2: Read Current Task Board
+
+```bash
+cat "knowledge/Tasks/{Person Name}.md"
+```
+
+Parse existing tasks to:
+
+- Avoid duplicates (same person, similar description)
+- Understand current workload
+- Find the right insertion point
+
+## Step 3: Perform the Operation
+
+### Add a Task
+
+1. Check for duplicates — same person, similar task title or description. If a
+   near-duplicate exists, update it instead of creating a new entry.
+2. Determine the section:
+   - Default: `## Open`
+   - If user says "I'm working on" / "started" → `## In Progress`
+   - If blocked → `## Blocked`
+3. Format the task entry:
+   ```
+   - [ ] **{Task title}** | {priority} | due {YYYY-MM-DD} | [[Projects/Name]]
+     {Context line with source info and backlinks.}
+   ```
+4. Add the entry at the **bottom** of the appropriate section.
+5. If the task references a project, verify the project note exists.
+
+### Update a Task
+
+1. Find the task by title (fuzzy match OK — bold text between `**`).
+2. Apply changes:
+   - **Status change:** Move the entire entry between sections
+   - **Priority change:** Update the `| {priority} |` segment
+   - **Due date change:** Update or add `| due YYYY-MM-DD |`
+   - **Add context:** Append to the indented line
+3. Use the Edit tool for targeted modifications.
+
+### Close a Task
+
+1. Find the task by title.
+2. Remove it from its current section.
+3. Add to the **top** of `## Recently Done`:
+   ```
+   - [x] **{Task title}** | completed {YYYY-MM-DD}
+   ```
+   (Drop priority, due date, project link, and context — keep it compact.)
+
+### List Tasks
+
+Query across all task boards:
+
+```bash
+# All open/in-progress tasks
+rg "^- \[ \] \*\*" knowledge/Tasks/
+
+# Tasks for a specific project
+rg "Projects/{Name}" knowledge/Tasks/
+
+# High priority tasks
+rg "\| high \|" knowledge/Tasks/
+
+# Overdue tasks — find all due dates and compare against today
+rg "due 20[0-9]{2}-[0-9]{2}-[0-9]{2}" knowledge/Tasks/
+
+# Blocked tasks
+rg -A1 "^- \[ \]" knowledge/Tasks/ | rg -B1 "Waiting on"
+```
+
+Present results in a clean summary, grouped by person or project as appropriate
+for the user's question.
+
+### Housekeeping (Scheduled)
+
+Run across all task boards:
+
+1. **Prune done items:** Remove completed tasks older than 14 days from
+   `## Recently Done`.
+2. **Flag overdue:** Any task with `due {date}` in the past that's still in
+   `## Open` or `## In Progress` — check if it needs attention. Do NOT
+   auto-modify the task; instead, report overdue items to the user.
+3. **Deduplicate:** If identical tasks appear on the same board, merge them.
+4. **Validate links:** Spot-check that `[[People/]]` and `[[Projects/]]`
+   references point to existing notes.
+
+## Step 4: Write Updates
+
+### New task board
+
+Create `knowledge/Tasks/{Person Name}.md` with all four sections:
+
+```markdown
+# {Person Name}
+
+## In Progress
+
+## Open
+
+## Blocked
+
+## Recently Done
+```
+
+### Existing task board
+
+Use the Edit tool to make targeted changes — add, move, or modify individual
+task entries. Do NOT rewrite the entire file.
+
+## Step 5: Migrate Open Items (One-time)
+
+When first setting up task boards, or when the user asks, migrate existing
+`## Open items` from People and Project notes:
+
+1. Scan notes for `## Open items` sections with content:
+   ```bash
+   rg -l "## Open items" knowledge/People/ knowledge/Projects/
+   ```
+2. For each note with open items, read the items and convert them to task board
+   entries.
+3. Add each item to the appropriate person's task board.
+4. **Do NOT remove** the original open items from source notes — they serve as
+   the historical record. The task board becomes the living tracker.
+
+## Quality Checklist
+
+- [ ] Task title is clear and actionable (starts with a verb)
+- [ ] Priority set appropriately (omit if medium)
+- [ ] Due date included only if there's a real deadline
+- [ ] Project linked with `[[Projects/Name]]` if applicable
+- [ ] No duplicate tasks on the board
+- [ ] Recently Done pruned to last 14 days (housekeeping)
+- [ ] All backlinks use absolute paths `[[Folder/Name]]`
+- [ ] Context line is concise (1-2 lines max)
+- [ ] New task board has all four sections present

package/template/.claude/skills/organize-files/SKILL.md

@@ -61,7 +61,7 @@ Run when the user asks to find, organize, clean up, or tidy files on their Mac.
 
 Get an overview of both directories:
 
-    bash scripts/summarize.sh
+    node scripts/summarize.mjs
 
 ## Finding Files
 
@@ -79,8 +79,8 @@ find ~/Desktop -maxdepth 1 \( -name "Screenshot*" -o -name "Screen Shot*" \)
 Organize a directory into type-based subdirectories (Documents, Images,
 Archives, Installers, Screenshots):
 
-    bash scripts/organize-by-type.sh ~/Downloads
-    bash scripts/organize-by-type.sh ~/Desktop
+    node scripts/organize-by-type.mjs ~/Downloads
+    node scripts/organize-by-type.mjs ~/Desktop
 
 The script creates subdirectories and moves matching files. It does NOT delete
 anything.

package/template/.claude/skills/organize-files/scripts/organize-by-type.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * Organize files in a directory by type into subdirectories.
+ *
+ * Scans the top level of the given directory and moves files into category
+ * subdirectories: Screenshots, Documents, Images, Archives, and Installers.
+ * Categories are determined by file extension and name prefix. Files that do
+ * not match any category are left in place. Does NOT delete anything.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  renameSync,
+  statSync,
+} from "node:fs";
+import { extname, join } from "node:path";
+
+const HELP = `organize-by-type — sort files into type-based subdirectories
+
+Usage: node scripts/organize-by-type.mjs <directory> [-h|--help]
+
+Creates subdirectories (Documents, Images, Archives, Installers, Screenshots)
+and moves matching top-level files into them. Does NOT delete any files.`;
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+const CATEGORIES = [
+  {
+    name: "Screenshots",
+    test: (name) =>
+      name.startsWith("Screenshot") || name.startsWith("Screen Shot"),
+  },
+  {
+    name: "Documents",
+    test: (_name, ext) =>
+      [
+        ".pdf",
+        ".doc",
+        ".docx",
+        ".txt",
+        ".md",
+        ".rtf",
+        ".csv",
+        ".xlsx",
+      ].includes(ext),
+  },
+  {
+    name: "Images",
+    test: (_name, ext) =>
+      [".png", ".jpg", ".jpeg", ".gif", ".webp"].includes(ext),
+  },
+  {
+    name: "Archives",
+    test: (name, ext) =>
+      [".zip", ".rar"].includes(ext) || name.endsWith(".tar.gz"),
+  },
+  {
+    name: "Installers",
+    test: (_name, ext) => ext === ".dmg",
+  },
+];
+
+function main() {
+  const dir = process.argv[2];
+  if (!dir) {
+    console.error("Usage: node scripts/organize-by-type.mjs <directory>");
+    process.exit(1);
+  }
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+    console.error(`Error: Directory not found: ${dir}`);
+    process.exit(1);
+  }
+
+  // Create subdirectories
+  for (const cat of CATEGORIES) {
+    mkdirSync(join(dir, cat.name), { recursive: true });
+  }
+
+  let moved = 0;
+  for (const name of readdirSync(dir)) {
+    const fullPath = join(dir, name);
+    const stat = statSync(fullPath, { throwIfNoEntry: false });
+    if (!stat || !stat.isFile()) continue;
+
+    const ext = extname(name).toLowerCase();
+    for (const cat of CATEGORIES) {
+      if (cat.test(name, ext)) {
+        const dest = join(dir, cat.name, name);
+        renameSync(fullPath, dest);
+        console.log(`${name} -> ${cat.name}/`);
+        moved++;
+        break;
+      }
+    }
+  }
+
+  console.log(`\nOrganization complete: ${dir} (${moved} files moved)`);
+}
+
+main();