@pingvinen/donna-assistant 0.4.0 → 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/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.4.0",
+  "version": "0.5.0",
   "description": "Donna - your AI powered personal assistant",
   "bin": {
     "donna-assistant": "./bin/donna-assistant"

package/src/installer.cjs

@@ -77,7 +77,7 @@ async function run(options = {}) {
         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}`,
+                `Copied donna skills (setup, add-task, done, set-role, begin-the-day, add-tool, relearn-tools, run-tools) to ${provider.stubTarget}`,
             );
         }
     } else {

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

@@ -21,6 +21,47 @@ Extract the `storage_repo`, `daily_folder` (default: `daily`), and `auto_push` (
 - 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`).
 

package/workflows/add-tool.md

@@ -0,0 +1,261 @@
+# Donna Add-Tool Workflow
+
+<objective>
+Declare an external CLI tool, verify its installation and authentication, learn its capabilities, and persist the result to tools.md in 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`, `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="detect-noted-tools">
+Read `<storage_repo>/donna/role.md` and `<storage_repo>/donna/role-research.md` with the Read tool. If either file does not exist, skip reading that file.
+
+Look for lines containing tool names noted by set-role's approve-tools step. These lines follow the pattern `✓ Noted: <ToolName>` or `- Noted: <ToolName>`. Collect the noted tool names as `<noted_tools>`.
+
+If `<noted_tools>` has more than one entry and no specific tool name was provided as argument to the command, offer batch mode via AskUserQuestion:
+
+```
+Set-role noted these tools: <list>. Configure all of them now? (yes/no)
+```
+
+If yes, set batch mode active and process each tool sequentially through steps 4–11 below. If no, proceed to ask-tool-name for a single tool.
+</step>
+
+<step name="ask-tool-name">
+If a tool name was provided as argument (e.g. `/donna:add-tool gh`), use it directly. Otherwise, use AskUserQuestion:
+
+```
+What tool would you like to add? (e.g. gh, jira, kubectl)
+```
+
+Store the answer as `<tool_name>`.
+
+Resolve the CLI command — default to the tool name itself. If the tool name is in `<noted_tools>`, pre-fill any context from set-role notes. Use AskUserQuestion to confirm or override the CLI command:
+
+```
+CLI command for <tool_name>? (default: <tool_name>)
+```
+
+If the user presses enter without typing, use the default. Store the confirmed CLI command as `<command>`.
+</step>
+
+<step name="verify-installation">
+Run via Bash:
+```bash
+which <command> && echo "INSTALLED=true" || echo "INSTALLED=false"
+```
+
+If INSTALLED=false, print:
+```
+! <command> is not installed. You can still save it, but data pulling won't work until you install it.
+```
+Continue (do not stop — user may want to pre-configure).
+
+If INSTALLED=true, run:
+```bash
+<command> --version 2>/dev/null | head -1
+```
+
+Store the output as `<version>`. If the command does not support `--version`, store `<version>` as `unknown`.
+</step>
+
+<step name="auth-test">
+For well-known tools, run the appropriate auth test via Bash with a 10-second timeout:
+
+- `gh`: `timeout 10 gh api user --jq '.login' 2>&1`
+- `jira`: `timeout 10 jira me 2>&1`
+- `kubectl`: `timeout 10 kubectl auth whoami 2>&1`
+- Other tools: skip auth test, print `ℹ No known auth test for <command>. Verify manually.`
+
+On success (exit 0): print `✓ Authenticated as <output>`.
+
+On failure (non-zero exit): print `! Authentication failed for <command>. Fix: <tool-specific fix instructions>`.
+
+Fix instructions per tool:
+- `gh` → run `gh auth login`
+- `jira` → run `jira init`
+- `kubectl` → check your kubeconfig
+
+Continue (do not stop — user may want to save the tool despite auth issues).
+</step>
+
+<step name="ask-scope">
+Ask the user to define the scope/context for this tool. Different tools need different scope:
+
+- **gh**: Which GitHub orgs or repos to pull from (e.g., `mycompany`, `mycompany/api mycompany/web`)
+- **jira**: Which Jira project(s) or board(s) (e.g., `AUTH`, `AUTH PLAT`)
+- **kubectl**: Which namespace(s) or cluster(s) (e.g., `production`, `staging production`)
+- **Other tools**: Any relevant filtering context
+
+Use AskUserQuestion:
+```
+What scope should Donna use for <tool_name>?
+(e.g., for gh: which orgs/repos; for jira: which projects)
+Leave blank for no filtering.
+```
+
+Store the answer as `<scope>`. If blank, set to empty string.
+</step>
+
+<step name="learn-capabilities">
+Determine if the tool is well-known (gh, jira, kubectl) or unknown. For well-known tools, synthesize capabilities from training data. Do NOT parse --help for well-known tools.
+
+**gh (GitHub CLI) — training data baseline:**
+
+If `<scope>` is set, add `--owner=<org>` to each search command for each org in scope (space-separated). If scope contains specific repos (format `owner/repo`), use `--repo=<owner/repo>` instead. If scope is empty, do not add owner/repo filters.
+
+- list-assigned-prs: `gh search prs --assignee=@me --state=open --json number,title,url --limit 20`
+- list-review-requests: `gh search prs --review-requested=@me --state=open --json number,title,url --limit 20`
+- list-assigned-issues: `gh search issues --assignee=@me --state=open --json number,title,url --limit 20`
+
+**jira (ankitpokhrel/jira-cli) — training data baseline:**
+
+If `<scope>` is set, add `-p<project>` to each command for each project in scope (space-separated). If scope is empty, do not add project filters.
+
+- list-sprint-issues: `jira sprint list --current -a$(jira me) --plain`
+- list-my-issues: `jira issue list -a$(jira me) --plain`
+
+**kubectl — training data baseline:**
+
+If `<scope>` is set, replace `--all-namespaces` with `-n <namespace>` for each namespace in scope. If scope is empty, keep `--all-namespaces`.
+
+- list-pods: `kubectl get pods --all-namespaces --field-selector=status.phase!=Succeeded -o wide`
+- list-failing: `kubectl get pods --all-namespaces --field-selector=status.phase=Failed -o wide`
+
+For **unknown tools**, run `<command> --help 2>&1 | head -80` via Bash and use Claude's understanding to identify 3–5 capabilities relevant to daily task management. If `<scope>` is set, incorporate the scope into the CLI invocations where appropriate. Format each as `name: <cli invocation>`.
+
+Store the full list as `<available_capabilities>`.
+</step>
+
+<step name="select-capabilities">
+Present `<available_capabilities>` to the user via AskUserQuestion with multi-select. All capabilities are checked by default. The question text:
+
+```
+Which capabilities should Donna use for <tool_name>? (deselect any you don't want, or type additional ones)
+```
+
+If the user types additional capabilities as free text, parse them into the same `name: command` format.
+
+Store the final selections as `<selected_capabilities>`.
+</step>
+
+<step name="write-tools-md">
+Read `<storage_repo>/donna/tools.md` with the Read tool. If the file does not exist, create it with:
+```markdown
+---
+# tools.md — managed by donna:add-tool
+---
+```
+
+Upsert (not overwrite) the tool's section. Each tool section has this format:
+```markdown
+## <tool_name>
+
+- command: <command>
+- version: <version>
+- learned: <today's date YYYY-MM-DD>
+- auth_test: <auth_test_command or "none">
+- scope: <scope or "none">
+
+### Capabilities
+- <capability_name>: <cli_invocation>
+```
+
+If a section for this tool already exists in tools.md, replace it entirely. Write the full file back with the Write tool. Preserve all other tool sections unchanged.
+</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-tool): added <tool_name>"
+```
+
+If `auto_push` is true in config, also run:
+```bash
+git -C <storage_repo> push
+```
+</step>
+
+<step name="confirm">
+Print:
+```
+✓ Added <tool_name> to tools registry
+  Command: <command>
+  Version: <version>
+  Capabilities: <count> configured
+
+  Run /donna:begin-the-day to see tool data in your daily brief.
+```
+
+If in batch mode, repeat steps ask-tool-name through confirm for each remaining tool in `<noted_tools>`, then print a final summary:
+```
+✓ Configured <N> tools: <tool_name_1>, <tool_name_2>, ...
+```
+</step>

package/workflows/begin-the-day.md

@@ -21,6 +21,47 @@ Extract the `storage_repo`, `daily_folder` (default: `daily`), and `auto_push` (
 - 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-today">
 Run via Bash to get today's date, day-of-week, and day-of-month:
 ```bash
@@ -66,7 +107,7 @@ Do NOT modify the previous file — it is a historical record and must remain un
 </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).
+Read `<storage_repo>/donna/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.
 
@@ -86,6 +127,46 @@ For each task, determine if it is due today using this logic:
 Store the descriptions of all due tasks as `<recurring_tasks>` (just the description text, without the interval suffix).
 </step>
 
+<step name="pull-tool-data">
+Read `<storage_repo>/donna/tools.md` with the Read tool.
+
+If the file does not exist or has no tool sections (no `## ` headers after the frontmatter), set `<tool_tasks>` to an empty list and `<tool_warnings>` to an empty list. Continue to the next step. Do NOT print any error — tools are optional.
+
+For each tool section in tools.md, parse the `command` field and the `### Capabilities` entries. For each capability entry (format: `- <name>: <cli_invocation>`):
+
+Run the CLI invocation via Bash with a 10-second timeout:
+```bash
+timeout 10 <cli_invocation> 2>&1
+```
+
+**On success (exit 0):**
+Parse the output into task entries. Every task line MUST include both a tool tag and a descriptive link.
+
+CRITICAL — tool tag format: Every tool task line MUST start with `(<tool_name>)` after the checkbox, where `<tool_name>` is the `## <tool_name>` section header from tools.md (e.g., `gh`, `jira`, `kubectl`). This tag identifies which tool sourced the task. Example: if processing the `## gh` section, every task line starts with `- [ ] (gh) `.
+
+For `gh` JSON output (`--json number,title,url`): parse the JSON array. Extract `<owner>/<repo>` from the `url` field (e.g., `https://github.com/acme/api/pull/42` → `acme/api`). For each item, create:
+`- [ ] (gh) <title> [<owner/repo>#<number>](<url>)`
+
+For `jira` plain output: parse each row. For each issue, create:
+`- [ ] (jira) <summary> [<key>](https://<jira_host>/browse/<key>)`
+Note: jira plain output may not include URLs — if the URL is not available, use the issue key only: `- [ ] (jira) <summary> [<key>](<key>)`
+
+For other tools: use Claude's understanding to extract task-like items from the output. Format with a descriptive identifier as the link text and URL if available:
+`- [ ] (<tool_name>) <description> [<identifier>](<url>)`
+
+**On failure (non-zero exit):**
+Determine the failure type from the exit code and output:
+- Exit 124: `! <tool_name>: timed out after 10s — check network connectivity`
+- Exit 1 with "auth" or "login" in output: `! <tool_name>: authentication failed — run \`<auth_fix_command>\``
+- Exit 127 or "not found" in output: `! <tool_name>: command not found — install <command> first`
+- Other: `! <tool_name>: <first line of stderr>`
+
+Add the warning to `<tool_warnings>`. Continue to next capability/tool. Never retry. Tool failures must never block manual tasks, carry-forward, or recurring task processing.
+
+Collect all task entries as `<tool_tasks>`.
+Collect all warning messages as `<tool_warnings>`.
+</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>`.
 
@@ -95,7 +176,7 @@ If the file does not exist, `<existing_tasks>` is an empty list.
 <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.
+**Normalization for comparison:** strip `- [ ] ` or `- [x] ` prefix, strip any leading `(<tool>) ` prefix (tool tag, matching the pattern `\(\w+\) `), strip any trailing ` (N times)` suffix (where N is any integer), strip any trailing ` [<text>](<url>)` suffix (tool source link, matching the pattern ` \[[^\]]+\]\([^\)]+\)`), strip any trailing ` (<reason>)` suffix (e.g. `(merged)`, `(closed)`), lowercase all text, trim whitespace.
 
 1. Start with `<existing_tasks>` — both open and closed tasks take priority. Add them all to the final list.
 
@@ -103,8 +184,12 @@ Assemble the full task list using a single-pass deduplication to ensure idempote
 
 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.
 
+4. Add `<tool_tasks>` as-is — for each tool 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: A closed task `- [x] (gh) Review PR #42 [acme/api#42](https://...)` must block a tool task `- [ ] (gh) Review PR #42 [acme/api#42](https://...)` from being re-added. The normalization (strip tool tag + source link) ensures both normalize to "review pr #42".
+
 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>`.
@@ -126,13 +211,25 @@ date: <today>
 <existing tasks, preserving their original order and open/closed state>
 <carried-forward tasks not already in existing>
 <recurring tasks not already in existing>
+
+## From Tools
+<tool tasks not already in existing — only if there are tool tasks>
+
+## Resolved
+<resolved tool tasks — only if there are resolved items>
+
+## Warnings
+<tool warnings — only if there are warnings>
 ```
 
 Tasks are written in this order: existing tasks first (preserving their original order and state), then carried-forward tasks, then recurring tasks.
+
+If `<tool_tasks>` is empty and there are no resolved items, omit the `## From Tools` and `## Resolved` sections entirely.
+If `<tool_warnings>` is empty, omit the `## Warnings` section entirely. Each warning is written as-is (e.g., `! jira: command not found — install jira first`).
 </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`.
+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>/donna/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.
 
@@ -167,7 +264,7 @@ git -C <storage_repo> push
 Print the daily brief to the terminal:
 ```
 ══════════════════════════════════════
- DONNA — Daily Brief for <today>
+ Donna — Daily Brief for <today>
 ══════════════════════════════════════
 ```
 
@@ -185,12 +282,25 @@ If there are recurring tasks due today (tasks from `<recurring_tasks>` that were
 - [ ] Review sprint backlog
 ```
 
+If there are tool tasks (tasks from `<tool_tasks>` that were added to the final list), print:
+```
+## From Tools
+- [ ] (gh) Review PR #42 [org/repo#42](https://github.com/org/repo/pull/42)
+- [ ] (jira) Implement AUTH-07 [AUTH-07](https://company.atlassian.net/browse/AUTH-07)
+```
+
+If there are tool warnings (`<tool_warnings>` is not empty), print:
+```
+## Warnings
+! gh: authentication failed — run `gh auth login`
+```
+
 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:
+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 no tool tasks, omit the "## From Tools" section. If no tool warnings, omit the "## Warnings" section. If carried-forward, recurring, AND tool tasks are all empty and there are no existing tasks, print:
 ```
 No tasks for today — enjoy your day!
 ```

package/workflows/done.md

@@ -21,6 +21,47 @@ Extract the `storage_repo`, `daily_folder` (default: `daily`), and `auto_push` (
 - 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="find-daily-file">
 Run via Bash to get today's date:
 ```bash
@@ -41,7 +82,7 @@ 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.
+When presenting task descriptions to the user (in the numbered list or match confirmation), strip any leading `(<tool>) ` prefix (tool tag, e.g., `(gh) Review PR #42...` becomes `Review PR #42...`), strip any trailing ` (N times)` suffix (where N is any integer, e.g., `Follow up with Sarah (3 times)` becomes `Follow up with Sarah`), and strip any trailing ` [<text>](<url>)` suffix (e.g., `Review PR #42 [org/repo#42](https://github.com/org/repo/pull/42)` becomes `Review PR #42`) for cleaner display. Keep the full line internally for file operations.
 
 If no open tasks are found, print:
 ```
@@ -54,7 +95,7 @@ Stop.
 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.
+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). Also strip any leading `(<tool>) ` prefix (tool tag, matching the regex `^\(\w+\) `) and any trailing ` [<text>](<url>)` suffix (source link, matching the regex ` \[[^\]]+\]\([^\)]+\)`, e.g., `(gh) Review PR #42 [org/repo#42](https://github.com/org/repo/pull/42)` becomes `Review PR #42` for matching purposes). These suffixes are added by begin-the-day and are 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:
 ```
@@ -63,7 +104,7 @@ 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.
+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). Also strip any leading `(<tool>) ` prefix (tool tag, matching the regex `^\(\w+\) `) and any trailing ` [<text>](<url>)` suffix (source link, matching the regex ` \[[^\]]+\]\([^\)]+\)`, e.g., `(gh) Review PR #42 [org/repo#42](https://github.com/org/repo/pull/42)` becomes `Review PR #42` for matching purposes). These suffixes are added by begin-the-day and are 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:
 ```
@@ -86,6 +127,8 @@ For each task in `<completed_tasks>`, replace `- [ ] <description>` with `- [x]
 
 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).
 
+When marking a tool-sourced task as complete, keep both the `(<tool>)` prefix and `[<identifier>](<url>)` suffix on the completed line (they serve as provenance). The completed task should read `- [x] (gh) Review PR #42 [org/repo#42](https://github.com/org/repo/pull/42)` (tool tag and source link preserved for traceability).
+
 Write the updated file with the Write tool.
 </step>
 

package/workflows/relearn-tools.md

@@ -0,0 +1,180 @@
+# Donna Relearn-Tools Workflow
+
+<objective>
+Check each registered tool's installed version against its stored version and re-learn capabilities for tools that have been updated. Tools at the same version are skipped.
+</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="read-tools-md">
+Read `<storage_repo>/donna/tools.md` with the Read tool. If the file does not exist, print:
+```
+✗ No tools registered. Run /donna:add-tool first.
+```
+Stop.
+
+Parse each tool section (starting with `## <tool_name>`). For each tool, extract:
+- `command` — the CLI command to run
+- `version` — the stored version string
+- `learned` — the date capabilities were last learned
+- capabilities list under `### Capabilities`
+
+Store the parsed tools as `<registered_tools>`.
+</step>
+
+<step name="check-versions">
+For each tool in `<registered_tools>`, run via Bash:
+```bash
+<command> --version 2>/dev/null | head -1
+```
+
+Compare the output against the stored `version` field using simple string equality — "is it different?" is sufficient; no semver parsing required.
+
+If `<command>` is not found (command fails), treat it as changed with a warning note.
+
+Collect tools into two lists:
+- `<changed_tools>` — installed version differs from stored version (or command not found)
+- `<unchanged_tools>` — installed version matches stored version exactly
+</step>
+
+<step name="report-unchanged">
+For each tool in `<unchanged_tools>`, print:
+```
+⊘ <tool_name>: unchanged at <version> — skipped
+```
+
+If ALL tools are in `<unchanged_tools>` (no changes found), print:
+```
+✓ All tools up to date. Nothing to re-learn.
+```
+Stop.
+</step>
+
+<step name="relearn-changed">
+For each tool in `<changed_tools>`, apply the same learn-capabilities logic as add-tool.md's learn-capabilities step.
+
+Determine if the tool is well-known (gh, jira, kubectl) or unknown. For well-known tools, synthesize capabilities from training data. Do NOT parse --help for well-known tools.
+
+**gh (GitHub CLI) — training data baseline:**
+- list-assigned-prs: `gh search prs --assignee=@me --state=open --json number,title,url --limit 20`
+- list-review-requests: `gh search prs --review-requested=@me --state=open --json number,title,url --limit 20`
+- list-assigned-issues: `gh search issues --assignee=@me --state=open --json number,title,url --limit 20`
+
+**jira (ankitpokhrel/jira-cli) — training data baseline:**
+- list-sprint-issues: `jira sprint list --current -a$(jira me) --plain`
+- list-my-issues: `jira issue list -a$(jira me) --plain`
+
+**kubectl — training data baseline:**
+- list-pods: `kubectl get pods --all-namespaces --field-selector=status.phase!=Succeeded -o wide`
+- list-failing: `kubectl get pods --all-namespaces --field-selector=status.phase=Failed -o wide`
+
+For **unknown tools**, run `<command> --help 2>&1 | head -80` via Bash and use Claude's understanding to identify 3–5 capabilities relevant to daily task management.
+
+Do NOT ask the user to re-select capabilities — keep the same capability names, update only the CLI invocations if the training data suggests changes.
+
+Get the new installed version:
+```bash
+<command> --version 2>/dev/null | head -1
+```
+
+Print:
+```
+✓ Re-learned <tool_name> (was <old_version>, now <new_version>)
+```
+</step>
+
+<step name="write-tools-md">
+Update `<storage_repo>/donna/tools.md`: for each re-learned tool, update its `version`, `learned` date (today's date YYYY-MM-DD), and capabilities section with the new invocations.
+
+Upsert — replace only the re-learned tool sections, do not remove other tool sections. Preserve all unchanged tool sections exactly as they are.
+
+Write the full file back 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(relearn-tools): updated <count> tool(s)"
+```
+
+If `auto_push` is true in config, also run:
+```bash
+git -C <storage_repo> push
+```
+</step>
+
+<step name="confirm">
+Print summary:
+```
+✓ Re-learned <count> tool(s): <tool_names>
+  <count> tool(s) unchanged: <tool_names>
+```
+</step>

package/workflows/run-tools.md

@@ -0,0 +1,214 @@
+# Donna Run-Tools Workflow
+
+<objective>
+Execute all configured external tool commands, pull fresh data, and smart-merge results into today's daily file. Does not run the full begin-the-day carry-forward or recurring task logic — this is a mid-day update only.
+</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="read-tools-md">
+Read `<storage_repo>/donna/tools.md` with the Read tool. If the file does not exist, print:
+```
+✗ No tools registered. Run /donna:add-tool first.
+```
+Stop.
+
+Parse each tool section (starting with `## <tool_name>`). For each tool, extract the `command` field and the capabilities list under `### Capabilities`.
+
+Store the parsed tools and their capabilities as `<registered_tools>`.
+</step>
+
+<step name="find-daily-file">
+Get today's date via Bash:
+```bash
+date +%Y-%m-%d
+```
+Store as `<today>`.
+
+Construct the path: `<storage_repo>/<daily_folder>/<today>.md`.
+
+If the file does not exist, print:
+```
+✗ No daily file for today. Run /donna:begin-the-day first.
+```
+Stop.
+</step>
+
+<step name="read-existing-tool-tasks">
+Read today's daily file with the Read tool.
+
+Extract all lines from the `## From Tools` section and the `## Resolved` section.
+
+For each line, extract the embedded URL from the `[<text>](<url>)` pattern — this URL is the stable identifier for matching. Store as `<existing_tool_lines>`: a map of URL to full line (including its checkbox state `[ ]` or `[x]` and tool tag).
+
+If the `## From Tools` section does not exist in today's file, set `<existing_tool_lines>` to an empty map. The section will be created during smart-merge.
+</step>
+
+<step name="pull-fresh-data">
+For each tool in `<registered_tools>`, for each capability:
+
+Run the capability command via Bash with a 10-second timeout:
+```bash
+timeout 10 <capability_command> 2>&1
+```
+
+**On success (exit 0):** Parse the output into task entries. Every task line MUST include both a tool tag and a descriptive link.
+
+CRITICAL — tool tag format: Every tool task line MUST start with `(<tool_name>)` after the checkbox, where `<tool_name>` is the `## <tool_name>` section header from tools.md (e.g., `gh`, `jira`, `kubectl`). This tag identifies which tool sourced the task. Example: if processing the `## gh` section, every task line starts with `- [ ] (gh) `.
+
+For gh JSON output, extract `number`, `title`, `url` fields from each JSON object. Use the `url` field as the stable identifier. Extract `<owner>/<repo>` from the URL (e.g., `https://github.com/acme/api/pull/42` → `acme/api`). Format:
+```
+- [ ] (gh) <title> [<owner/repo>#<number>](<url>)
+```
+
+For jira plain output, extract the issue key and summary from each line. Format:
+```
+- [ ] (jira) <summary> [<issue_key>](https://jira.company.com/browse/<issue_key>)
+```
+
+For other tools: use Claude's understanding to extract task-like items from the output. Format with a descriptive identifier as the link text and URL if available:
+```
+- [ ] (<tool_name>) <description> [<identifier>](<url>)
+```
+
+**On failure (exit non-zero, including exit 124 for timeout):** Add a warning:
+```
+! <tool_name>: <error_description>
+```
+Continue to the next capability. Never retry.
+
+Store all fresh tasks as `<fresh_tool_tasks>`: a map of URL to task line.
+Collect all warning messages as `<tool_warnings>`.
+</step>
+
+<step name="smart-merge">
+Apply three-way merge rules in priority order. This is a read-modify-write operation — the entire daily file is rewritten atomically with all sections updated.
+
+Read the full current content of today's daily file.
+
+**Process existing tool lines** (from `<existing_tool_lines>`):
+
+For each URL in `<existing_tool_lines>`:
+1. If the line is `[x]` (user manually checked): **KEEP AS-IS** — user intent wins (Rule 1). Do not change regardless of tool state.
+2. If the line is `[ ]` AND the URL exists in `<fresh_tool_tasks>`: **KEEP OPEN** — item is still active (Rule 2).
+3. If the line is `[ ]` AND the URL is NOT in `<fresh_tool_tasks>`: the item was removed from the tool (reassigned, deleted, or closed).
+   - For gh items: check if the PR/issue was closed or merged via Bash: `timeout 10 gh pr view <number> --json state --jq '.state' 2>/dev/null || timeout 10 gh issue view <number> --json state --jq '.state' 2>/dev/null`
+   - If closed or merged: change to `- [x] (<tool>) <description> [<identifier>](<url>) (<reason>)` and move to `## Resolved` (Rule 3a).
+   - If status check fails or item simply no longer appears: move to `## Resolved` with `(removed)` (Rule 3b).
+
+**Add new items** (from `<fresh_tool_tasks>`):
+
+For each URL in `<fresh_tool_tasks>` that is NOT in `<existing_tool_lines>`:
+- **ADD** the task line to the `## From Tools` section (Rule 4 — new item).
+
+**Rebuild the file:**
+
+Rewrite today's daily file with the Write tool, preserving all non-tool sections exactly. The `## From Tools` section contains only currently open tool tasks. The `## Resolved` section contains closed/removed items appended to any existing resolved items.
+
+CRITICAL: Remove items from `## From Tools` when moving them to `## Resolved`. Do NOT just append. The entire file is rewritten in one Write operation.
+
+If `## From Tools` does not yet exist in the file, add it after the `## Tasks` section. If `## Resolved` does not yet exist, add it at the end of the file when needed.
+</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(run-tools): refreshed tool data for <today>"
+```
+
+If `auto_push` is true in config, also run:
+```bash
+git -C <storage_repo> push
+```
+</step>
+
+<step name="print-summary">
+Print:
+```
+══════════════════════════════════════
+ Donna — Run Tools for <today>
+══════════════════════════════════════
+```
+
+If new tasks were added (Rule 4), print each new task line.
+If tasks were auto-closed (Rule 3a), print each with reason.
+If tasks were moved to Resolved (Rule 3b), print each with reason.
+If there are warnings from `<tool_warnings>`, print each warning line.
+If nothing changed, print:
+```
+No changes from tools.
+```
+
+End with:
+```
+══════════════════════════════════════
+```
+</step>

package/workflows/set-role.md

@@ -16,10 +16,51 @@ Stop.
 Extract the `storage_repo` and `auto_push` (default: false) fields from the YAML frontmatter.
 </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="check-existing-role">
 Run via Bash:
 ```bash
-test -f <storage_repo>/role.md && echo "exists" || echo "missing"
+test -f <storage_repo>/donna/role.md && echo "exists" || echo "missing"
 ```
 
 If the output is "exists", proceed to the rerun-menu step.
@@ -39,8 +80,8 @@ A role definition already exists. What would you like to do?
 ```
 
 - 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 "diff-update" (option 2): read current `<storage_repo>/donna/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 `<storage_repo>/donna/recurring.md`). Preserve any manually-added recurring tasks (tasks in recurring.md not in the research suggestions).
+- On "re-research" (option 3): read current `<storage_repo>/donna/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>
 
@@ -132,7 +173,7 @@ 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.
+Write `<storage_repo>/donna/role.md` with the Write tool.
 
 Use this format (substituting actual values):
 ```markdown
@@ -151,7 +192,7 @@ updated: <today's date in YYYY-MM-DD format>
 [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.
+Write `<storage_repo>/donna/role-research.md` with the Write tool.
 
 Use this format:
 ```markdown
@@ -185,7 +226,7 @@ role: <job_title>
 </step>
 
 <step name="save-recurring">
-Write `<storage_repo>/recurring.md` with the Write tool.
+Write `<storage_repo>/donna/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.
@@ -202,7 +243,7 @@ Use this format:
 ```
 
 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.
+1. Read the existing `<storage_repo>/donna/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.

package/workflows/setup.md

@@ -103,16 +103,17 @@ Set `<daily_folder>` to `daily`. Print:
 </step>
 
 <step name="create-storage-structure">
-Create the daily directory:
+Create the daily and donna directories:
 
 Run via Bash:
 ```bash
 mkdir -p <repo>/<daily_folder>
+mkdir -p <repo>/donna
 ```
 
 Print:
 ```
-✓ Created <daily_folder>/ directory
+✓ Created <daily_folder>/ and donna/ directories
 ```
 </step>