@pingvinen/donna-assistant 0.0.0 → 0.4.0

package/README.md

@@ -1 +1,2 @@
-Placeholder release for trusted publishing setup. Real content will be published via CI.
+# donna
+A Claude skill based personal assistant

package/bin/donna-assistant

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+"use strict";
+
+const { run } = require("../src/installer.cjs");
+
+const force = process.argv.includes("--force");
+
+run({ force }).catch((err) => {
+    console.error(`\nInstallation failed: ${err.message}`);
+    process.exit(1);
+});

package/migrations/001-initial.cjs

@@ -0,0 +1,12 @@
+"use strict";
+
+module.exports = {
+    version: "0.1.0",
+    description: "Initial directory structure",
+    up(ctx) {
+        const dirs = ["workflows", "templates", "references"];
+        for (const dir of dirs) {
+            ctx.fs.mkdirSync(ctx.path.join(ctx.donnaDir, dir), { recursive: true });
+        }
+    },
+};

package/package.json

@@ -1,8 +1,44 @@
 {
-    "name": "@pingvinen/donna-assistant",
-    "version": "0.0.0",
-    "description": "Donna - your AI powered personal assistant (placeholder for trusted publishing setup)",
-    "publishConfig": {
-        "access": "public"
-    }
+  "name": "@pingvinen/donna-assistant",
+  "version": "0.4.0",
+  "description": "Donna - your AI powered personal assistant",
+  "bin": {
+    "donna-assistant": "./bin/donna-assistant"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "stubs/",
+    "workflows/",
+    "migrations/",
+    "templates/",
+    "references/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "test": "node --test 'test/*.test.cjs'",
+    "prepublishOnly": "chmod +x bin/donna-assistant"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0"
+  },
+  "keywords": [
+    "claude-code",
+    "assistant",
+    "productivity",
+    "ai"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pingvinen/donna"
+  }
 }

package/src/installer.cjs

@@ -0,0 +1,103 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+const output = require("./output.cjs");
+const version = require("./version.cjs");
+const migrator = require("./migrator.cjs");
+const providers = require("./providers/index.cjs");
+
+/**
+ * Main installer orchestration.
+ *
+ * @param {object} [options]
+ * @param {string} [options.homeDir] - Override home directory (for testing)
+ * @param {boolean} [options.force] - Force re-install even if version matches
+ * @returns {Promise<void>}
+ */
+async function run(options = {}) {
+    const homeDir = options.homeDir || os.homedir();
+    const force = options.force || false;
+    const donnaDir = path.join(homeDir, ".donna");
+    const migrationsDir = path.join(__dirname, "..", "migrations");
+    const workflowsSource = path.join(__dirname, "..", "workflows");
+    const pkg = require("../package.json");
+    const packageVersion = pkg.version;
+
+    // Print banner
+    output.banner();
+
+    // Create donnaDir if it doesn't exist
+    fs.mkdirSync(donnaDir, { recursive: true });
+
+    // Read current version
+    const current = version.readVersion(donnaDir);
+    const currentVersion = current?.version || null;
+    const lastMigration = current?.lastMigration || 0;
+
+    // Check if already up to date
+    if (currentVersion === packageVersion && !force) {
+        // Check for pending migrations too
+        const pendingResults = migrator.runMigrations(migrationsDir, donnaDir, lastMigration);
+        if (pendingResults.length === 0) {
+            output.info(`Already up to date at ${packageVersion}`);
+            return;
+        }
+    }
+
+    // If upgrading (current version exists but differs)
+    if (currentVersion && currentVersion !== packageVersion) {
+        output.upgradeHeader(currentVersion, packageVersion);
+    }
+
+    // Run migrations
+    const results = migrator.runMigrations(migrationsDir, donnaDir, lastMigration);
+
+    // Track last successful migration number
+    let lastSuccessful = lastMigration;
+
+    for (const result of results) {
+        if (result.ok) {
+            output.migrationLine(result.description);
+            lastSuccessful = result.num;
+        } else {
+            output.fail(`Migration ${result.num} failed: ${result.error.message}`);
+            // Write version.md with last successful migration
+            version.writeVersion(donnaDir, packageVersion, lastSuccessful);
+            throw result.error;
+        }
+    }
+
+    // Detect providers and copy stubs
+    const detected = providers.detectProviders(homeDir);
+
+    if (detected.length > 0) {
+        for (const provider of detected) {
+            fs.cpSync(provider.stubSource, provider.stubTarget, { recursive: true });
+            output.success(
+                `Copied donna skills (setup, add-task, done, set-role, begin-the-day) to ${provider.stubTarget}`,
+            );
+        }
+    } else {
+        output.info("No supported AI providers detected");
+        output.info("Install Claude Code and re-run to add donna skills");
+    }
+
+    // Copy workflows to donnaDir/workflows/
+    const workflowsTarget = path.join(donnaDir, "workflows");
+    fs.mkdirSync(workflowsTarget, { recursive: true });
+    fs.cpSync(workflowsSource, workflowsTarget, { recursive: true });
+    output.success("Installed workflows to ~/.donna/workflows/");
+
+    // Write version.md
+    version.writeVersion(donnaDir, packageVersion, lastSuccessful);
+    output.success(`Version ${packageVersion} installed`);
+
+    // Final message
+    console.log("");
+    output.info("Run /donna:setup in Claude Code to get started.");
+}
+
+module.exports = { run };

package/src/migrator.cjs

@@ -0,0 +1,44 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+/**
+ * Run pending migrations from migrationsDir against donnaDir.
+ * Skips migrations with numeric prefix <= lastMigration.
+ * Stops on first failure.
+ *
+ * @param {string} migrationsDir - Directory containing numbered .cjs migration files
+ * @param {string} donnaDir - The ~/.donna/ directory
+ * @param {number} lastMigration - Last successfully applied migration number
+ * @returns {Array<{num: number, description: string, ok: boolean, error?: Error}>}
+ */
+function runMigrations(migrationsDir, donnaDir, lastMigration) {
+    if (!fs.existsSync(migrationsDir)) return [];
+
+    const files = fs
+        .readdirSync(migrationsDir)
+        .filter((f) => f.endsWith(".cjs"))
+        .sort((a, b) => Number.parseInt(a, 10) - Number.parseInt(b, 10));
+
+    const pending = files.filter((f) => Number.parseInt(f, 10) > lastMigration);
+    const results = [];
+
+    for (const file of pending) {
+        const migration = require(path.join(migrationsDir, file));
+        const num = Number.parseInt(file, 10);
+
+        try {
+            migration.up({ donnaDir, fs, path, os });
+            results.push({ num, description: migration.description, ok: true });
+        } catch (err) {
+            results.push({ num, description: migration.description, ok: false, error: err });
+            break;
+        }
+    }
+
+    return results;
+}
+
+module.exports = { runMigrations };

package/src/output.cjs

@@ -0,0 +1,29 @@
+"use strict";
+
+function banner() {
+    console.log("");
+    console.log("━━━ Donna ━━━");
+    console.log("");
+}
+
+function success(msg) {
+    console.log(`  \u2713 ${msg}`);
+}
+
+function fail(msg) {
+    console.log(`  \u2717 ${msg}`);
+}
+
+function info(msg) {
+    console.log(`  ${msg}`);
+}
+
+function upgradeHeader(from, to) {
+    console.log(`  Upgrading ${from} \u2192 ${to}:`);
+}
+
+function migrationLine(desc) {
+    console.log(`  \u2713 ${desc}`);
+}
+
+module.exports = { banner, success, fail, info, upgradeHeader, migrationLine };

package/src/providers/claude-code.cjs

@@ -0,0 +1,18 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+module.exports = {
+    name: "Claude Code",
+
+    detect(homeDir) {
+        return fs.existsSync(path.join(homeDir, ".claude"));
+    },
+
+    stubSource: path.join(__dirname, "..", "..", "stubs", "claude-code"),
+
+    getStubTarget(homeDir) {
+        return path.join(homeDir, ".claude", "commands");
+    },
+};

package/src/providers/index.cjs

@@ -0,0 +1,21 @@
+"use strict";
+
+const claudeCode = require("./claude-code.cjs");
+
+const PROVIDERS = [claudeCode];
+
+/**
+ * Detect which AI coding assistant providers are installed.
+ *
+ * @param {string} homeDir - The user's home directory
+ * @returns {Array<{name: string, stubSource: string, stubTarget: string}>}
+ */
+function detectProviders(homeDir) {
+    return PROVIDERS.filter((p) => p.detect(homeDir)).map((p) => ({
+        name: p.name,
+        stubSource: p.stubSource,
+        stubTarget: p.getStubTarget(homeDir),
+    }));
+}
+
+module.exports = { detectProviders };

package/src/version.cjs

@@ -0,0 +1,49 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+function readVersion(donnaDir) {
+    const versionPath = path.join(donnaDir, "version.md");
+    if (!fs.existsSync(versionPath)) return null;
+
+    const content = fs.readFileSync(versionPath, "utf8");
+    const version = content.match(/\*\*Version:\*\* (.+)/)?.[1] || "0.0.0";
+    const lastMigration = Number.parseInt(
+        content.match(/\*\*Last migration:\*\* (\d+)/)?.[1] || "0",
+        10,
+    );
+    const installed = content.match(/\*\*Installed:\*\* (.+)/)?.[1] || null;
+    const updated = content.match(/\*\*Updated:\*\* (.+)/)?.[1] || null;
+
+    return { version, lastMigration, installed, updated };
+}
+
+function writeVersion(donnaDir, version, lastMigration) {
+    const versionPath = path.join(donnaDir, "version.md");
+    const now = new Date().toISOString();
+
+    let installed = now;
+
+    // Preserve the original "Installed" timestamp if file already exists
+    if (fs.existsSync(versionPath)) {
+        const existing = readVersion(donnaDir);
+        if (existing?.installed) {
+            installed = existing.installed;
+        }
+    }
+
+    const content = [
+        "# Donna",
+        "",
+        `- **Version:** ${version}`,
+        `- **Last migration:** ${String(lastMigration).padStart(3, "0")}`,
+        `- **Installed:** ${installed}`,
+        `- **Updated:** ${now}`,
+        "",
+    ].join("\n");
+
+    fs.writeFileSync(versionPath, content);
+}
+
+module.exports = { readVersion, writeVersion };

package/stubs/claude-code/donna/add-task.md

@@ -0,0 +1,17 @@
+---
+name: donna:add-task
+description: Capture a task to today's daily journal
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Run the Donna add-task workflow.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/add-task.md
+</execution_context>

package/stubs/claude-code/donna/begin-the-day.md

@@ -0,0 +1,16 @@
+---
+name: donna:begin-the-day
+description: Start your day — carry forward open tasks, surface recurring tasks due today, get your daily brief
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Run the Donna begin-the-day workflow.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/begin-the-day.md
+</execution_context>

package/stubs/claude-code/donna/done.md

@@ -0,0 +1,17 @@
+---
+name: donna:done
+description: Mark tasks as complete in today's daily journal
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Run the Donna done workflow.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/done.md
+</execution_context>

package/stubs/claude-code/donna/set-role.md

@@ -0,0 +1,18 @@
+---
+name: donna:set-role
+description: Define your job role, research recurring tasks, and build your daily rhythm
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+  - WebSearch
+---
+
+<objective>
+Run the Donna set-role workflow. This command guides the user through defining their job role: collecting role details, researching recurring tasks and tools, presenting findings for approval, and persisting everything to the storage repo.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/set-role.md
+</execution_context>

package/stubs/claude-code/donna/setup.md

@@ -0,0 +1,17 @@
+---
+name: donna:setup
+description: Set up Donna — configure storage repo, initialize file structure, create bootstrap config
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Run the Donna setup workflow. This command guides the user through configuring Donna: setting the storage repo path, initializing the file structure, and writing the bootstrap config at ~/.config/donna/config.md.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/setup.md
+</execution_context>

package/workflows/add-task.md

@@ -0,0 +1,97 @@
+# Donna Add-Task Workflow
+
+<objective>
+Capture a new task to today's daily journal file in the storage repo and commit it to git.
+</objective>
+
+<step name="read-config">
+Read `~/.config/donna/config.md`.
+
+If the file does not exist, print:
+```
+✗ Donna is not configured. Run /donna:setup first.
+```
+Stop.
+
+Extract the `storage_repo`, `daily_folder` (default: `daily`), and `auto_push` (default: false) fields from the YAML frontmatter.
+
+**Obsidian sync:** Check if `<storage_repo>/.obsidian/daily-notes.json` exists.
+- If it exists and has a `folder` field that differs from `<daily_folder>`: update `<daily_folder>` to match Obsidian's value, and update `~/.config/donna/config.md` with the new `daily_folder`. Print `✓ Synced daily folder with Obsidian: <daily_folder>`.
+- If `<storage_repo>/.obsidian/` exists but `daily-notes.json` does not exist or has no `folder` field: write `<storage_repo>/.obsidian/daily-notes.json` with `{"folder":"<daily_folder>"}`. Print `✓ Configured Obsidian daily notes to use <daily_folder>/`.
+- Otherwise: do nothing.
+</step>
+
+<step name="get-description">
+The task description is provided as the argument to this command (e.g., `/donna:add-task buy milk`).
+
+If no argument was provided, use AskUserQuestion to ask:
+```
+What task would you like to add?
+```
+
+Store the response as `<description>`.
+</step>
+
+<step name="ensure-daily-file">
+Run via Bash to get today's date:
+```bash
+date +%Y-%m-%d
+```
+
+Store the result as `<date>`. Construct the daily file path: `<storage_repo>/<daily_folder>/<date>.md`.
+
+Run via Bash to ensure the daily folder exists:
+```bash
+mkdir -p <storage_repo>/<daily_folder>
+```
+
+If the daily file does not exist, create it with the Write tool using this content (substituting the actual date):
+```markdown
+---
+date: <date>
+---
+
+## Tasks
+```
+</step>
+
+<step name="append-task">
+Read the daily file with the Read tool.
+
+Append `- [ ] <description>` on a new line at the end of the file.
+
+Write the updated file with the Write tool.
+</step>
+
+<step name="git-commit">
+Run via Bash:
+```bash
+git -C <storage_repo> add -A
+```
+
+Check whether there is anything to commit:
+```bash
+git -C <storage_repo> status --porcelain
+```
+
+If the output is empty, skip the commit and continue.
+
+Otherwise, run:
+```bash
+git -C <storage_repo> commit -m "donna(add-task): <description>"
+```
+
+If `auto_push` is true in config, also run:
+```bash
+git -C <storage_repo> push
+```
+</step>
+
+<step name="confirm">
+Print:
+```
+✓ Added: <description>
+```
+
+Also print the path to the daily file: `<storage_repo>/<daily_folder>/<date>.md`
+</step>

package/workflows/begin-the-day.md

@@ -0,0 +1,198 @@
+# Donna Begin-the-Day Workflow
+
+<objective>
+Carry forward open tasks from the previous day, surface recurring tasks due today, deduplicate, and present a concise daily brief.
+</objective>
+
+<step name="read-config">
+Read `~/.config/donna/config.md`.
+
+If the file does not exist, print:
+```
+✗ Donna is not configured. Run /donna:setup first.
+```
+Stop.
+
+Extract the `storage_repo`, `daily_folder` (default: `daily`), and `auto_push` (default: false) fields from the YAML frontmatter.
+
+**Obsidian sync:** Check if `<storage_repo>/.obsidian/daily-notes.json` exists.
+- If it exists and has a `folder` field that differs from `<daily_folder>`: update `<daily_folder>` to match Obsidian's value, and update `~/.config/donna/config.md` with the new `daily_folder`. Print `✓ Synced daily folder with Obsidian: <daily_folder>`.
+- If `<storage_repo>/.obsidian/` exists but `daily-notes.json` does not exist or has no `folder` field: write `<storage_repo>/.obsidian/daily-notes.json` with `{"folder":"<daily_folder>"}`. Print `✓ Configured Obsidian daily notes to use <daily_folder>/`.
+- Otherwise: do nothing.
+</step>
+
+<step name="get-today">
+Run via Bash to get today's date, day-of-week, and day-of-month:
+```bash
+date +%Y-%m-%d
+```
+Store the result as `<today>`.
+
+```bash
+date +%A
+```
+Store the result as `<day_of_week>` (e.g., "Monday").
+
+```bash
+date +%-d
+```
+Store the result as `<day_of_month>` (e.g., "1" for the 1st).
+
+Construct the daily file path: `<storage_repo>/<daily_folder>/<today>.md`.
+</step>
+
+<step name="find-previous-file">
+Find the most recent previous daily file. Run via Bash:
+```bash
+TODAY=$(date +%Y-%m-%d)
+DAILY_DIR="<storage_repo>/<daily_folder>"
+PREV_FILE=$(ls "$DAILY_DIR"/*.md 2>/dev/null | sort | grep -v "$TODAY" | tail -1)
+echo "${PREV_FILE:-NONE}"
+```
+
+CRITICAL: The `grep -v "$TODAY"` exclusion prevents a self-referencing loop. If the result is "NONE", there is no previous file — skip the carry-forward step. This reads a directory listing only (satisfies STORE-03), then reads at most ONE previous file.
+</step>
+
+<step name="carry-forward">
+If the previous file result is "NONE", set `<carried_tasks>` to an empty list and continue to the next step.
+
+If a previous file was found, read it with the Read tool. Extract all open tasks — every line matching the pattern `- [ ] <description>`. For each open task:
+- If the description ends with ` (N times)` (where N is any integer): extract N, increment to N+1, replace the suffix with ` (N+1 times)`. For example: `- [ ] Follow up with Sarah (2 times)` becomes `- [ ] Follow up with Sarah (3 times)`.
+- If the description has no such suffix: append ` (1 times)`. For example: `- [ ] Follow up with Sarah` becomes `- [ ] Follow up with Sarah (1 times)`.
+
+Store the resulting list as `<carried_tasks>`.
+
+Do NOT modify the previous file — it is a historical record and must remain unchanged.
+</step>
+
+<step name="check-recurring">
+Read `<storage_repo>/recurring.md` with the Read tool. If the file does not exist, set `<recurring_tasks>` to an empty list and continue (recurring tasks are optional — set-role may not have been run yet).
+
+Parse each line matching the pattern `- <description>: <interval>`. For "every other" intervals, also parse the `| last_run: YYYY-MM-DD` suffix.
+
+For each task, determine if it is due today using this logic:
+- `every <DayName>` (e.g., "every Monday"): due if `<day_of_week>` matches DayName
+- `every weekday`: due if `<day_of_week>` is Monday, Tuesday, Wednesday, Thursday, or Friday
+- `first <DayName> of month`: due if `<day_of_week>` matches DayName AND `<day_of_month>` <= 7
+- `every other <DayName>` with `| last_run: YYYY-MM-DD`: due if `<day_of_week>` matches DayName AND days since last_run >= 14. Use macOS-compatible date arithmetic:
+  ```bash
+  LAST_RUN="<last_run_date>"
+  last_run_epoch=$(date -j -f "%Y-%m-%d" "$LAST_RUN" "+%s")
+  today_epoch=$(date +%s)
+  days=$(( (today_epoch - last_run_epoch) / 86400 ))
+  echo "$days"
+  ```
+
+Store the descriptions of all due tasks as `<recurring_tasks>` (just the description text, without the interval suffix).
+</step>
+
+<step name="read-existing-today">
+If today's daily file already exists, read it with the Read tool. Extract all task lines — both open (`- [ ] ...`) and closed (`- [x] ...`). Store as `<existing_tasks>`.
+
+If the file does not exist, `<existing_tasks>` is an empty list.
+</step>
+
+<step name="deduplicate">
+Assemble the full task list using a single-pass deduplication to ensure idempotency:
+
+**Normalization for comparison:** strip `- [ ] ` or `- [x] ` prefix, strip any trailing ` (N times)` suffix (where N is any integer), lowercase all text, trim whitespace.
+
+1. Start with `<existing_tasks>` — both open and closed tasks take priority. Add them all to the final list.
+
+2. Add `<carried_tasks>` — for each carried task, normalize its description and check whether any task already in the final list (from existing_tasks) normalizes to the same value. If no match, add it. If a match exists, skip it.
+
+3. Add `<recurring_tasks>` as `- [ ] <description>` — for each recurring task, normalize its description and check whether any task already in the final list normalizes to the same value. If no match, add it. If a match exists, skip it.
+
+CRITICAL: A closed task `- [x] Review PRs` must block a recurring `- [ ] Review PRs` from being re-added. Both open AND closed existing tasks count for deduplication.
+
+CRITICAL: If a carried-forward task already exists in today's file (from a previous run of begin-the-day today), do not re-add it or re-increment its counter. The normalization (strip suffix) ensures this.
+
+Store the result as `<final_tasks>`.
+</step>
+
+<step name="write-daily-file">
+Ensure the daily folder exists:
+```bash
+mkdir -p <storage_repo>/<daily_folder>
+```
+
+Write today's daily file with the Write tool. Content format:
+```markdown
+---
+date: <today>
+---
+
+## Tasks
+<existing tasks, preserving their original order and open/closed state>
+<carried-forward tasks not already in existing>
+<recurring tasks not already in existing>
+```
+
+Tasks are written in this order: existing tasks first (preserving their original order and state), then carried-forward tasks, then recurring tasks.
+</step>
+
+<step name="update-recurring-last-run">
+If any tasks from `<recurring_tasks>` came from "every other" intervals and were added to today's file, update their `last_run` date in `<storage_repo>/recurring.md`.
+
+Read the full recurring.md file. For each such task, find the line and update the `| last_run: <old_date>` suffix to `| last_run: <today>`. If no `last_run` suffix exists, append ` | last_run: <today>` to the line. Write the full file back with the Write tool.
+
+If no "every other" recurring tasks were added, skip this step.
+</step>
+
+<step name="git-commit">
+Run via Bash:
+```bash
+git -C <storage_repo> add -A
+```
+
+Check whether there is anything to commit:
+```bash
+git -C <storage_repo> status --porcelain
+```
+
+If the output is empty, skip the commit and continue.
+
+Otherwise, run:
+```bash
+git -C <storage_repo> commit -m "donna(begin-the-day): daily brief for <today>"
+```
+
+If `auto_push` is true in config, also run:
+```bash
+git -C <storage_repo> push
+```
+</step>
+
+<step name="print-brief">
+Print the daily brief to the terminal:
+```
+══════════════════════════════════════
+ DONNA — Daily Brief for <today>
+══════════════════════════════════════
+```
+
+If there are carried-forward tasks (tasks from `<carried_tasks>` that were added to the final list), print:
+```
+## Carried Forward
+- [ ] Follow up with Sarah (3 times)
+- [ ] Review design doc (1 times)
+```
+
+If there are recurring tasks due today (tasks from `<recurring_tasks>` that were added to the final list), print:
+```
+## Due Today
+- [ ] Check team Slack
+- [ ] Review sprint backlog
+```
+
+Always end with:
+```
+══════════════════════════════════════
+```
+
+Show ALL tasks — never truncate. If no carried-forward tasks, omit the "## Carried Forward" section. If no recurring tasks due today, omit the "## Due Today" section. If both sections are empty and there are no existing tasks, print:
+```
+No tasks for today — enjoy your day!
+```
+in place of both sections.
+</step>

package/workflows/done.md

@@ -0,0 +1,126 @@
+# Donna Done Workflow
+
+<objective>
+Mark one or more tasks as complete in today's daily journal file and commit the change to git.
+</objective>
+
+<step name="read-config">
+Read `~/.config/donna/config.md`.
+
+If the file does not exist, print:
+```
+✗ Donna is not configured. Run /donna:setup first.
+```
+Stop.
+
+Extract the `storage_repo`, `daily_folder` (default: `daily`), and `auto_push` (default: false) fields from the YAML frontmatter.
+
+**Obsidian sync:** Check if `<storage_repo>/.obsidian/daily-notes.json` exists.
+- If it exists and has a `folder` field that differs from `<daily_folder>`: update `<daily_folder>` to match Obsidian's value, and update `~/.config/donna/config.md` with the new `daily_folder`. Print `✓ Synced daily folder with Obsidian: <daily_folder>`.
+- If `<storage_repo>/.obsidian/` exists but `daily-notes.json` does not exist or has no `folder` field: write `<storage_repo>/.obsidian/daily-notes.json` with `{"folder":"<daily_folder>"}`. Print `✓ Configured Obsidian daily notes to use <daily_folder>/`.
+- Otherwise: do nothing.
+</step>
+
+<step name="find-daily-file">
+Run via Bash to get today's date:
+```bash
+date +%Y-%m-%d
+```
+
+Store the result as `<date>`. Construct the daily file path: `<storage_repo>/<daily_folder>/<date>.md`.
+
+If the file does not exist, print:
+```
+✗ No daily file for today. Add a task first with /donna:add-task
+```
+Stop.
+</step>
+
+<step name="read-tasks">
+Read the daily file with the Read tool.
+
+Find all lines matching the pattern `- [ ] <description>` (open tasks). Collect them as `<open_tasks>`. Do not print the list — it will be shown in the next step via AskUserQuestion.
+
+When presenting task descriptions to the user (in the numbered list or match confirmation), strip any trailing ` (N times)` suffix (where N is any integer, e.g., `Follow up with Sarah (3 times)` becomes `Follow up with Sarah`) for cleaner display. Keep the full line internally for file operations.
+
+If no open tasks are found, print:
+```
+✓ All tasks already complete for today!
+```
+Stop.
+</step>
+
+<step name="select-tasks">
+Two modes based on whether an argument was provided to this command:
+
+**With argument** (e.g., `/donna:done buy milk`):
+When fuzzy-matching task descriptions, strip any trailing ` (N times)` suffix (where N is any integer, matching the regex `\(\d+ times\)`, e.g., `Follow up with Sarah (3 times)` becomes `Follow up with Sarah` for matching purposes). This counter is added by begin-the-day's carry-forward and is transparent to task completion.
+
+Use your natural language understanding to fuzzy-match the argument against the open task descriptions (after stripping the counter suffix). If a match is found, show it and use AskUserQuestion to confirm:
+```
+Mark as done: '<task>'? (yes/no)
+```
+If no match is found, tell the user and list all open tasks.
+
+**Without argument**:
+When fuzzy-matching task descriptions, strip any trailing ` (N times)` suffix (where N is any integer, matching the regex `\(\d+ times\)`, e.g., `Follow up with Sarah (3 times)` becomes `Follow up with Sarah` for matching purposes). This counter is added by begin-the-day's carry-forward and is transparent to task completion.
+
+Use AskUserQuestion to ask which task to mark as done. Provide the open task descriptions as options so the user can select from a list. The question text should be:
+```
+Which task(s) did you finish? (or type something you did that's not on the list)
+```
+
+If the user submits without selecting anything or typing anything, print:
+```
+Nothing selected — nothing to do.
+```
+Stop.
+
+If the user selects from the list, store the selected task(s) as `<completed_tasks>`.
+
+If the user types free text instead of selecting an option, treat it as a task that was already done: append `- [x] <typed text>` to the daily file (creating it if needed, same as add-task's ensure-daily-file step). Store it as `<completed_tasks>` so the git-commit and confirm steps handle it normally.
+</step>
+
+<step name="mark-complete">
+For each task in `<completed_tasks>`, replace `- [ ] <description>` with `- [x] <description>` in the daily file.
+
+When marking a carry-forward task as complete, strip the ` (N times)` suffix from the completed line. The completed task should read `- [x] Follow up with Sarah` (clean, no counter).
+
+Write the updated file with the Write tool.
+</step>
+
+<step name="git-commit">
+Run via Bash:
+```bash
+git -C <storage_repo> add -A
+```
+
+Check whether there is anything to commit:
+```bash
+git -C <storage_repo> status --porcelain
+```
+
+If the output is empty, skip the commit and continue.
+
+If one task was completed, run:
+```bash
+git -C <storage_repo> commit -m "donna(done): <description>"
+```
+
+If multiple tasks were completed, run:
+```bash
+git -C <storage_repo> commit -m "donna(done): <N> tasks completed"
+```
+
+If `auto_push` is true in config, also run:
+```bash
+git -C <storage_repo> push
+```
+</step>
+
+<step name="confirm">
+For each completed task, print:
+```
+✓ Done: <description>
+```
+</step>

package/workflows/set-role.md

@@ -0,0 +1,247 @@
+# Donna Set-Role Workflow
+
+<objective>
+Define the user's job role, research recurring tasks and tools for that role using WebSearch, present findings for approval, and persist role definition and recurring tasks to the storage repo.
+</objective>
+
+<step name="read-config">
+Read `~/.config/donna/config.md`.
+
+If the file does not exist, print:
+```
+✗ Donna is not configured. Run /donna:setup first.
+```
+Stop.
+
+Extract the `storage_repo` and `auto_push` (default: false) fields from the YAML frontmatter.
+</step>
+
+<step name="check-existing-role">
+Run via Bash:
+```bash
+test -f <storage_repo>/role.md && echo "exists" || echo "missing"
+```
+
+If the output is "exists", proceed to the rerun-menu step.
+If the output is "missing", proceed to the ask-role step.
+</step>
+
+<step name="rerun-menu">
+Use AskUserQuestion to present the re-run menu:
+
+```
+A role definition already exists. What would you like to do?
+
+1. Something got messed up — start fresh (reset)
+2. Got promoted or changed roles — update (diff-update)
+3. Just want to refresh the research — re-research current role
+4. Cancel
+```
+
+- On "reset" (option 1): proceed to ask-role (fresh start, will overwrite role.md and recurring.md).
+- On "diff-update" (option 2): read current role.md with the Read tool, proceed to ask-role but pre-fill with current values and note this is an update. After research, show delta (added/removed recurring tasks vs current recurring.md). Preserve any manually-added recurring tasks (tasks in recurring.md not in the research suggestions).
+- On "re-research" (option 3): read current role.md with the Read tool to get the existing role data, skip to the research step.
+- On "Cancel" (option 4): print "Cancelled." and stop.
+</step>
+
+<step name="ask-role">
+Stage 1: Collect role details interactively.
+
+Use AskUserQuestion to ask the following questions in sequence:
+
+1. "What is your job title?" — store as `<job_title>`.
+2. "How large is your team? How many direct reports do you have? (e.g. team of 8, 3 direct reports)" — store as `<team_info>`.
+3. "What are 2–3 things you focus on most in your role? (e.g. sprint planning, hiring, technical architecture)" — store as `<key_responsibilities>`.
+
+Parse `<team_info>` into `<team_size>` (total team) and `<direct_reports>` (direct reports count) as best you can.
+Parse `<key_responsibilities>` into an array of 2–3 items.
+
+Store all values for use in subsequent steps.
+</step>
+
+<step name="research">
+Stage 2: Research the role using WebSearch.
+
+Construct targeted queries using ALL collected data from Stage 1. Run 2–3 focused searches:
+
+1. `<job_title> daily recurring tasks responsibilities`
+2. `<job_title> <key_responsibilities[0]> common tools workflows`
+3. (optional) `<job_title> weekly monthly recurring tasks best practices`
+
+Use WebSearch for each query. Synthesize findings into a structured summary matching the role-research.md format:
+
+- **Daily tasks**: recurring things done every workday
+- **Weekly tasks**: recurring things done each week
+- **Monthly tasks**: recurring things done each month
+- **Tool suggestions**: tools commonly used for this role (with brief descriptions)
+
+Tailor suggestions to the specific responsibilities the user described — avoid generic results that don't reflect their actual focus areas.
+</step>
+
+<step name="present-summary">
+Print a concise summary of research findings (2–3 sentences covering the key patterns found).
+
+Then use AskUserQuestion:
+```
+Which category would you like to review?
+1. Recurring tasks
+2. Tool suggestions
+3. Both
+4. Skip (accept all recurring tasks as-is)
+```
+
+Store the choice for subsequent steps.
+</step>
+
+<step name="approve-recurring">
+If the user chose to review recurring tasks (options 1 or 3):
+
+Display each category in turn (daily, weekly, monthly) and use AskUserQuestion for each task:
+```
+[Daily] Check team Slack and unblock blockers
+→ Approve, reject, or modify? (approve / reject / [type modification)
+```
+
+Interpret modifications naturally:
+- "make this biweekly" → change interval to "every other week"
+- "every other Monday" → interval becomes "every other Monday"
+- "first Monday of the month" → interval becomes "first Monday of month"
+
+After reviewing all categories, ask: "Would you like to add any recurring tasks I missed?" Accept free-text additions.
+
+Collect the final approved list with their intervals.
+
+If the user chose to skip (option 4): accept all suggested recurring tasks with their default intervals.
+</step>
+
+<step name="approve-tools">
+If the user chose to review tool suggestions (options 2 or 3):
+
+Display each tool suggestion and use AskUserQuestion:
+```
+Tool: Jira (sprint management)
+→ Note this for future configuration? (yes / no)
+```
+
+For noted tools, print:
+```
+✓ Noted: <tool name>. Run /donna:add-tool to configure <tool name> (available in a future update).
+```
+
+Do NOT create tools.md or configure anything — only note the user's interest.
+</step>
+
+<step name="save-role">
+Write `<storage_repo>/role.md` with the Write tool.
+
+Use this format (substituting actual values):
+```markdown
+---
+job_title: <job_title>
+team_size: <team_size>
+direct_reports: <direct_reports>
+key_responsibilities:
+  - <responsibility 1>
+  - <responsibility 2>
+updated: <today's date in YYYY-MM-DD format>
+---
+
+# Role: <job_title>
+
+[Write a 2–3 sentence prose summary of the role as described by the user, incorporating their key responsibilities and team context.]
+```
+
+Write `<storage_repo>/role-research.md` with the Write tool.
+
+Use this format:
+```markdown
+---
+researched: <today's date in YYYY-MM-DD format>
+role: <job_title>
+---
+
+# Role Research: <job_title>
+
+## Summary
+[2–3 sentence overview of what the research found for this role]
+
+## Recurring Task Suggestions
+
+### Daily
+[List daily task suggestions from research]
+
+### Weekly
+[List weekly task suggestions from research]
+
+### Monthly
+[List monthly task suggestions from research]
+
+## Tool Suggestions
+[List tool suggestions with brief descriptions]
+
+## Notes
+[Any additional context from research relevant to this specific role]
+```
+</step>
+
+<step name="save-recurring">
+Write `<storage_repo>/recurring.md` with the Write tool.
+
+Format: one approved recurring task per line as `- Task description: interval`.
+For "every other" intervals (biweekly, every other Monday, etc.), append ` | last_run: <today's date>` suffix.
+
+Use this format:
+```markdown
+---
+# Recurring tasks — managed by donna:set-role
+---
+
+- <task 1>: <interval 1>
+- <task 2>: <interval 2>
+- <task 3>: <interval 3> | last_run: <today's date>
+```
+
+If this is a diff-update (user chose option 2 in rerun-menu):
+1. Read the existing `<storage_repo>/recurring.md` with the Read tool.
+2. Identify manually-added tasks: tasks in recurring.md that were NOT in the research suggestions.
+3. Merge: keep manually-added tasks, add new approved tasks, remove tasks the user rejected.
+4. Write the merged result.
+</step>
+
+<step name="git-commit">
+Run via Bash:
+```bash
+git -C <storage_repo> add -A
+```
+
+Check whether there is anything to commit:
+```bash
+git -C <storage_repo> status --porcelain
+```
+
+If the output is empty, skip the commit and continue.
+
+Otherwise, run:
+```bash
+git -C <storage_repo> commit -m "donna(set-role): define role as <job_title>"
+```
+
+If `auto_push` is true in config, also run:
+```bash
+git -C <storage_repo> push
+```
+</step>
+
+<step name="confirm">
+Print:
+```
+✓ Role defined: <job_title>
+✓ <N> recurring tasks saved to recurring.md
+✓ Research saved to role-research.md
+```
+
+If any tools were noted during approve-tools, remind:
+```
+→ Run /donna:add-tool to configure your noted tools (available in a future update).
+```
+</step>

package/workflows/setup.md

@@ -0,0 +1,184 @@
+# Donna Setup Workflow
+
+<objective>
+Guide the user through configuring Donna: set the storage repo path, initialize the file structure, and write the bootstrap config at ~/.config/donna/config.md.
+</objective>
+
+<step name="banner">
+Print the Donna banner:
+```
+━━━ Donna ▸ Setup ━━━
+```
+</step>
+
+<step name="check-existing-config">
+Read `~/.config/donna/config.md`.
+
+If the file exists, proceed to the re-run menu (step: rerun-menu).
+If the file does not exist, proceed to first-run setup (step: ask-storage-path).
+</step>
+
+<step name="rerun-menu">
+An existing Donna configuration was found. Use AskUserQuestion to present the user with this menu:
+
+```
+Donna is already configured. What would you like to do?
+
+1. Change storage repo path
+2. View current config
+3. Reset (start over — deletes config and re-runs full setup)
+4. Cancel
+```
+
+Handle each option:
+
+- **Option 1:** Ask the user for the new storage repo path using AskUserQuestion. Validate and expand the path (run `echo <path>` via Bash to expand ~). Update `~/.config/donna/config.md` with the new storage_repo value. Print `✓ Storage repo updated.` then print the summary (step: summary).
+
+- **Option 2:** Display the contents of `~/.config/donna/config.md`. Then stop.
+
+- **Option 3:** Run `rm ~/.config/donna/config.md` via Bash to delete the config. Proceed to first-run setup (step: ask-storage-path).
+
+- **Option 4:** Print `Setup cancelled.` and stop.
+</step>
+
+<step name="ask-storage-path">
+Use AskUserQuestion to ask the user:
+
+```
+Where is your Donna storage repo?
+
+This is a local git repository where Donna stores your daily journal, tasks, and configuration. You can point to an existing git repo, an empty directory (Donna will initialize it), or a path that doesn't exist yet (Donna will create it).
+
+Enter the path (e.g. ~/Documents/donna-notes):
+```
+
+Wait for the user's response. Store the path as `<storage_path>`.
+</step>
+
+<step name="expand-and-validate-path">
+Expand the path provided by the user:
+
+Run via Bash:
+```bash
+echo <storage_path>
+```
+
+Use the expanded absolute path for all subsequent steps. Store as `<repo>`.
+
+Then check the path status:
+
+- If `<repo>` is an existing git repo (test: `git -C <repo> rev-parse --is-inside-work-tree 2>/dev/null`): use it as-is. Print `✓ Using existing git repo at <repo>`.
+
+- If `<repo>` exists as a directory but is not a git repo: run `git -C <repo> init`. Print `✓ Initialized git repo at <repo>`.
+
+- If `<repo>` does not exist: run `mkdir -p <repo>` then `git -C <repo> init`. Print `✓ Created and initialized git repo at <repo>`.
+</step>
+
+<step name="detect-daily-folder">
+Determine where daily files should live.
+
+**If `<repo>/.obsidian/daily-notes.json` exists:**
+Read it. If it has a `folder` field, use that value as `<daily_folder>`. Print:
+```
+✓ Found Obsidian daily notes folder: <daily_folder>
+```
+
+**If `<repo>/.obsidian/` exists but `.obsidian/daily-notes.json` does not exist or has no `folder` field:**
+Set `<daily_folder>` to `daily`. Write `<repo>/.obsidian/daily-notes.json` with:
+```json
+{
+  "folder": "daily"
+}
+```
+Print:
+```
+✓ Configured Obsidian daily notes to use daily/
+```
+
+**If `<repo>/.obsidian/` does not exist:**
+Set `<daily_folder>` to `daily`. Print:
+```
+✓ Using daily/ for daily files
+```
+</step>
+
+<step name="create-storage-structure">
+Create the daily directory:
+
+Run via Bash:
+```bash
+mkdir -p <repo>/<daily_folder>
+```
+
+Print:
+```
+✓ Created <daily_folder>/ directory
+```
+</step>
+
+<step name="write-bootstrap-config">
+Create the config directory if it does not exist:
+
+Run via Bash:
+```bash
+mkdir -p ~/.config/donna
+```
+
+Write `~/.config/donna/config.md` with the following content (substituting the actual expanded path for `<repo>`):
+
+```markdown
+---
+storage_repo: <repo>
+daily_folder: <daily_folder>
+auto_push: false
+---
+
+# Donna Configuration
+
+This file is managed by `/donna:setup`. All Donna skills read this file to find your storage repo.
+```
+
+Print:
+```
+✓ Wrote config at ~/.config/donna/config.md
+```
+</step>
+
+<step name="initial-commit">
+Check whether there is anything to commit:
+
+Run via Bash:
+```bash
+git -C <repo> status --porcelain
+```
+
+If the output is non-empty (there are changes to commit):
+
+Run:
+```bash
+git -C <repo> add -A
+git -C <repo> commit -m "donna(setup): initialize storage"
+```
+
+Print:
+```
+✓ Committed initial structure
+```
+
+If the output is empty (nothing to commit), skip the commit and continue.
+</step>
+
+<step name="summary">
+Print the completion summary:
+
+```
+✓ Donna is ready!
+
+Storage repo: <repo>
+Config: ~/.config/donna/config.md
+
+Next steps:
+  - Run /donna:add-task to capture your first task
+  - Run /donna:done to mark tasks complete
+```
+</step>