@pingvinen/donna-assistant 0.3.2 → 0.5.0

package/workflows/done.md

@@ -0,0 +1,169 @@
+# 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="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
+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 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:
+```
+✓ 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). 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:
+```
+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). 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:
+```
+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).
+
+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>
+
+<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/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>