@pingvinen/donna-assistant 0.3.2 → 0.5.0

package/README.md

@@ -1,2 +1,129 @@
-# donna
-A Claude skill based personal assistant
+# Donna
+
+Your personal, digital version of Harvey Specter's amazing secretary.
+
+Donna is an AI-powered personal assistant that manages the work that falls through the cracks — the 1:1 follow-ups, recurring process tasks, stakeholder requests, and self-initiated work that never makes it into Jira or Linear.
+
+She lives inside your terminal. She knows your role, surfaces what needs attention each day, pulls data from your CLI tools, and captures tasks in seconds — all backed by plain markdown and git.
+
+Donna is designed to be AI-agnostic, but currently only tested with [Claude Code](https://docs.anthropic.com/en/docs/claude-code). She works from any session, in any project — your tasks follow you wherever you work.
+
+## Install
+
+```bash
+npx @pingvinen/donna-assistant
+```
+
+The installer copies skill files into `~/.claude/commands/donna/` and shared runtime into `~/.donna/`. Run it again to upgrade.
+
+**Requirements:** Node.js 18+, an AI coding assistant (tested with Claude Code)
+
+## Setup
+
+```
+/donna:setup
+```
+
+Donna will ask you for a **storage repo** — a git repository (local or remote) where all your tasks and daily files live. Everything is plain markdown, committed to git automatically. If you use [Obsidian](https://obsidian.md), you can open this repo as a vault for a free UI.
+
+Then define your role so Donna can suggest recurring tasks relevant to your job:
+
+```
+/donna:set-role
+```
+
+## Daily workflow
+
+### Start the day
+
+```
+/donna:begin-the-day
+```
+
+This is your morning ritual. Donna will:
+
+- **Carry forward** open tasks from your last working day (handles weekends)
+- **Surface recurring tasks** that are due today based on your role
+- **Pull fresh data** from configured tools (GitHub PRs, Jira tickets, etc.)
+- **Deduplicate** across all sources and give you a brief
+
+### Capture tasks throughout the day
+
+```
+/donna:add-task Review Sarah's design doc before Thursday
+```
+
+One command, zero prompts, committed to git in seconds. Can also be called without arguments for a more conversational capture.
+
+### Mark tasks done
+
+```
+/donna:done design doc
+```
+
+Fuzzy-matches by name. Run without arguments to pick from a list.
+
+### Refresh tool data mid-day
+
+```
+/donna:run-tools
+```
+
+Re-pulls data from all configured tools. New items appear, resolved items get closed automatically. Your manually-marked tasks always win.
+
+## External tools
+
+Donna can pull tasks and status from CLI tools you already have installed. Register them with:
+
+```
+/donna:add-tool gh
+```
+
+Or call it without arguments — Donna will check your role and suggest tools typically associated with your job.
+
+Donna verifies the tool is installed and authenticated, learns its capabilities, and asks what scope to query (which repos, projects, namespaces). Any CLI tool can be added — Donna uses the AI model's knowledge of well-known tools and parses `--help` output for everything else.
+
+If a tool version is newer than what the AI model knows, Donna will inspect it to learn its current capabilities. You can also re-learn tools at any time:
+
+```
+/donna:relearn-tools
+```
+
+## How state is stored
+
+```
+<your-storage-repo>/
+  donna/
+    role.md          # your job role definition
+    recurring.md     # recurring task schedule
+    tools.md         # registered tool configurations
+  daily/
+    2026-03-16.md    # today's tasks, tool data, notes
+    2026-03-15.md
+    ...
+```
+
+Every change is committed to git. Files are plain markdown with YAML frontmatter — human-readable, hand-editable, and version-controlled.
+
+The storage repo is yours. Donna only writes to the `donna/` and `daily/` directories, so you're free to keep any other notes, files, or folder structures alongside it — great if you're already using the repo as an Obsidian vault or similar.
+
+## Idempotent by design
+
+Most commands are safe to run again. Want to update your role? Run `/donna:set-role` again. Added a new tool mid-day? Run `/donna:begin-the-day` again to pull its data in. Re-running a command updates state rather than duplicating it.
+
+## All commands
+
+| Command | What it does |
+|---------|-------------|
+| `/donna:setup` | First-time configuration (storage repo, directories) |
+| `/donna:set-role` | Define your job role, get recurring task suggestions |
+| `/donna:begin-the-day` | Morning brief with carry-forward, recurring tasks, tool data |
+| `/donna:add-task` | Capture a task instantly |
+| `/donna:done` | Mark a task complete |
+| `/donna:add-tool` | Register an external CLI tool |
+| `/donna:run-tools` | Refresh tool data mid-day |
+| `/donna:relearn-tools` | Update tool knowledge after upgrades |
+
+## License
+
+MIT

package/bin/donna-assistant

@@ -3,7 +3,9 @@
 
 const { run } = require("../src/installer.cjs");
 
-run().catch((err) => {
+const force = process.argv.includes("--force");
+
+run({ force }).catch((err) => {
     console.error(`\nInstallation failed: ${err.message}`);
     process.exit(1);
 });

package/migrations/002-standing-files-subfolder.cjs

@@ -0,0 +1,23 @@
+"use strict";
+
+module.exports = {
+    version: "0.4.0",
+    description: "Queue standing file move to donna/ subfolder (runs on next skill use)",
+    up(ctx) {
+        // Standing files live in the user's storage repo, which is not accessible
+        // from the migration context. We write a pending flag to state.md so that
+        // workflows can detect and execute the move on next skill run.
+        const statePath = ctx.path.join(ctx.donnaDir, "state.md");
+
+        if (ctx.fs.existsSync(statePath)) {
+            const content = ctx.fs.readFileSync(statePath, "utf8");
+            if (content.includes("move-standing-files")) {
+                // Already queued — idempotent, nothing to do
+                return;
+            }
+        }
+
+        const pendingFlag = "---\npending_migrations:\n  - move-standing-files\n---\n";
+        ctx.fs.writeFileSync(statePath, pendingFlag, "utf8");
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pingvinen/donna-assistant",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Donna - your AI powered personal assistant",
   "bin": {
     "donna-assistant": "./bin/donna-assistant"

package/src/installer.cjs

@@ -14,10 +14,12 @@ const providers = require("./providers/index.cjs");
  *
  * @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");
@@ -36,7 +38,7 @@ async function run(options = {}) {
     const lastMigration = current?.lastMigration || 0;
 
     // Check if already up to date
-    if (currentVersion === packageVersion) {
+    if (currentVersion === packageVersion && !force) {
         // Check for pending migrations too
         const pendingResults = migrator.runMigrations(migrationsDir, donnaDir, lastMigration);
         if (pendingResults.length === 0) {
@@ -74,7 +76,9 @@ async function run(options = {}) {
     if (detected.length > 0) {
         for (const provider of detected) {
             fs.cpSync(provider.stubSource, provider.stubTarget, { recursive: true });
-            output.success(`Copied donna:setup to ${provider.stubTarget}`);
+            output.success(
+                `Copied donna skills (setup, add-task, done, set-role, begin-the-day, add-tool, relearn-tools, run-tools) to ${provider.stubTarget}`,
+            );
         }
     } else {
         output.info("No supported AI providers detected");
@@ -92,6 +96,7 @@ async function run(options = {}) {
     output.success(`Version ${packageVersion} installed`);
 
     // Final message
+    console.log("");
     output.info("Run /donna:setup in Claude Code to get started.");
 }
 

package/src/output.cjs

@@ -2,7 +2,7 @@
 
 function banner() {
     console.log("");
-    console.log("━━━ DONNA ━━━");
+    console.log("━━━ Donna ━━━");
     console.log("");
 }
 
@@ -23,7 +23,7 @@ function upgradeHeader(from, to) {
 }
 
 function migrationLine(desc) {
-    console.log(`    \u2022 ${desc}`);
+    console.log(`  \u2713 ${desc}`);
 }
 
 module.exports = { banner, success, fail, info, upgradeHeader, migrationLine };

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/add-tool.md

@@ -0,0 +1,17 @@
+---
+name: donna:add-tool
+description: Declare an external CLI tool and teach Donna its capabilities
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Run the Donna add-tool workflow. This command declares external CLI tools (like gh, jira, kubectl) and teaches Donna their capabilities so they can be surfaced in the daily brief.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/add-tool.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/relearn-tools.md

@@ -0,0 +1,16 @@
+---
+name: donna:relearn-tools
+description: Re-learn capabilities for tools whose installed version has changed
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Run the Donna relearn-tools workflow. This command checks each registered tool's installed version against its stored version and re-learns capabilities for tools that have been updated.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/relearn-tools.md
+</execution_context>

package/stubs/claude-code/donna/run-tools.md

@@ -0,0 +1,16 @@
+---
+name: donna:run-tools
+description: Run external tools and pull fresh data into today's daily file
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Run the Donna run-tools workflow. This command executes all configured external tool commands, pulls fresh data, and smart-merges results into today's daily file, without running the full begin-the-day carry-forward and recurring task logic.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/run-tools.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

@@ -1,13 +1,15 @@
 ---
 name: donna:setup
-description: Set up Donna assistant for this machine
+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 verifies that Donna is installed correctly by loading the setup workflow from the shared runtime directory and displaying the current installation status.
+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>

package/workflows/add-task.md

@@ -0,0 +1,138 @@
+# 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="check-pending-migrations">
+Read `~/.donna/state.md` with the Read tool. If the file does not exist or has no `pending_migrations` field in its YAML frontmatter, skip this step.
+
+For each entry in `pending_migrations`:
+
+**`move-standing-files`:** Move standing files from storage repo root to donna/ subfolder.
+
+Run via Bash:
+```bash
+STORAGE_REPO="<storage_repo>"
+DONNA_DIR="$STORAGE_REPO/donna"
+MOVED=0
+
+mkdir -p "$DONNA_DIR"
+for FILE in role.md recurring.md role-research.md; do
+    if [ -f "$STORAGE_REPO/$FILE" ] && [ ! -f "$DONNA_DIR/$FILE" ]; then
+        mv "$STORAGE_REPO/$FILE" "$DONNA_DIR/$FILE"
+        echo "Moved $FILE to donna/$FILE"
+        MOVED=$((MOVED + 1))
+    fi
+done
+
+echo "MOVED=$MOVED"
+```
+
+If MOVED > 0, commit the move:
+```bash
+git -C <storage_repo> add -A
+git -C <storage_repo> diff --cached --quiet || git -C <storage_repo> commit -m "donna(migrate): move standing files to donna/ subfolder"
+```
+
+If `auto_push` is true in config, also push.
+
+After processing all pending migrations, update `~/.donna/state.md` with the Write tool: remove the completed entries from `pending_migrations`. If no entries remain, write:
+```markdown
+---
+pending_migrations: []
+---
+```
+</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>