@pingvinen/donna-assistant 0.4.0 → 0.6.0

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/contribute-idea.md

@@ -0,0 +1,128 @@
+# Donna Contribute Idea Workflow
+
+<objective>
+Help users submit feature ideas or bug reports by checking for duplicates against existing GitHub Issues and the project's pending todos, then creating a new issue if the idea is novel.
+</objective>
+
+<step name="banner">
+Print the Donna banner:
+```
+━━━ Donna ▸ Contribute Idea ━━━
+```
+</step>
+
+<step name="check-gh-auth">
+Run via Bash:
+```bash
+gh auth status 2>&1
+```
+
+If the exit code is non-zero, print:
+```
+✗ The gh CLI is not authenticated. Run 'gh auth login' first, then re-run /donna:contribute-idea.
+```
+Stop.
+</step>
+
+<step name="ask-idea">
+Use AskUserQuestion:
+
+```
+What's your idea or bug report?
+
+Describe it in a few sentences — I'll check if something similar already exists before creating an issue.
+```
+
+Store the response as `<user_idea>`.
+</step>
+
+<step name="check-duplicates">
+Check two sources for potential duplicates.
+
+**Source 1: GitHub Issues**
+
+Run via Bash:
+```bash
+gh issue list --repo pingvinen/donna --state open --json number,title,url --limit 100
+```
+
+Parse the JSON output. Compare each issue title against `<user_idea>` using semantic similarity — judge whether the idea meaningfully overlaps with an existing issue. Do not use brittle substring matching.
+
+**Source 2: GSD pending todos from STATE.md on GitHub**
+
+Run via Bash:
+```bash
+gh api repos/pingvinen/donna/contents/.planning/STATE.md --jq '.content | @base64d'
+```
+
+Parse the `### Pending Todos` section from the decoded content. Each bullet is a pending todo. Compare each todo against `<user_idea>` using semantic similarity.
+
+**If either source has a potential match**, present the match(es) to the user:
+
+```
+I found something similar:
+
+[For GitHub Issue match:]
+→ Issue #<number>: <title>
+  <url>
+  You can upvote or comment on this issue instead of creating a new one.
+
+[For pending todo match:]
+→ Pending todo: "<todo text>"
+  This is already tracked internally.
+```
+
+Then use AskUserQuestion:
+```
+Would you like to:
+1. Create a new issue anyway (it's different enough)
+2. Skip — the existing one covers my idea
+```
+
+If the user chooses option 2, print:
+```
+✓ Thanks for checking! The existing item covers this.
+```
+Stop.
+
+If no duplicates are found, proceed to the create-issue step.
+</step>
+
+<step name="create-issue">
+Help the user create a well-formed GitHub Issue.
+
+Draft a suggested title and body based on `<user_idea>`. Use AskUserQuestion:
+
+```
+Let me help you write up the issue. Here's what I've drafted based on your idea:
+
+Title: <suggested title based on user_idea>
+
+Body:
+<suggested body with description, context, and expected behavior>
+
+Would you like to:
+1. Submit as-is
+2. Edit the title or body first
+3. Cancel
+```
+
+Handle each option:
+
+- **Option 1 (submit as-is):** Run via Bash:
+  ```bash
+  gh issue create --repo pingvinen/donna --title "<title>" --body "<body>"
+  ```
+  Print the resulting issue URL with a success message:
+  ```
+  ✓ Issue created: <url>
+  ```
+
+- **Option 2 (edit):** Use AskUserQuestion to collect edits from the user. Re-present the updated draft and repeat until the user chooses to submit or cancel.
+
+- **Option 3 (cancel):** Print:
+  ```
+  Issue cancelled.
+  ```
+  Stop.
+</step>

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/help.md

@@ -0,0 +1,155 @@
+# Donna Help Workflow
+
+<objective>
+Provide interactive troubleshooting by inspecting Donna's state and guiding the user through diagnosing and resolving issues.
+</objective>
+
+<step name="banner">
+Print the Donna banner:
+```
+━━━ Donna ▸ Help ━━━
+```
+</step>
+
+<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.
+</step>
+
+<step name="ask-problem">
+Use AskUserQuestion:
+
+```
+What do you need help with?
+
+Some things I can help diagnose:
+- Configuration issues
+- Storage repo problems
+- Skills not working
+- Tool integration issues
+- General questions about how Donna works
+
+Describe what's going on:
+```
+
+Store the response as `<user_problem>`.
+</step>
+
+<step name="diagnose">
+Based on `<user_problem>`, inspect relevant state using keyword matching to determine the category and run the appropriate checks.
+
+**Config issues** (keywords: config, setup, configure, path):
+
+Run via Bash:
+```bash
+test -d <storage_repo> && echo "EXISTS" || echo "MISSING"
+```
+```bash
+git -C <storage_repo> status 2>&1 | head -1
+```
+
+Display the contents of `~/.config/donna/config.md`. Report:
+- Whether the storage_repo path exists
+- Whether it is a valid git repository
+
+**Storage issues** (keywords: storage, repo, git, daily, file, missing):
+
+Run via Bash:
+```bash
+test -d <storage_repo> && echo "EXISTS" || echo "MISSING"
+```
+```bash
+git -C <storage_repo> status 2>&1 | head -1
+```
+```bash
+ls <storage_repo>/donna/ 2>/dev/null
+```
+```bash
+ls <storage_repo>/<daily_folder>/ 2>/dev/null | tail -5
+```
+```bash
+git -C <storage_repo> status --short 2>/dev/null
+```
+
+Report whether the storage repo exists and is a git repo, whether the donna/ subfolder is present, the most recent daily files, and any uncommitted changes.
+
+**Skill issues** (keywords: skill, command, slash, workflow, not working, error):
+
+Run via Bash:
+```bash
+ls ~/.claude/commands/donna/ 2>/dev/null
+```
+```bash
+ls ~/.donna/workflows/ 2>/dev/null
+```
+
+Read `~/.donna/version.md` with the Read tool (if it exists).
+
+Report the installed stubs and workflows, compare their counts, and print the Donna version.
+
+**Tool issues** (keywords: tool, gh, jira, integration, pull, refresh):
+
+Read `<storage_repo>/donna/tools.md` with the Read tool if it exists.
+
+For each tool found in tools.md, run via Bash:
+```bash
+which <tool_name> 2>/dev/null
+```
+
+If `gh` is a configured tool, also run:
+```bash
+gh auth status 2>&1
+```
+
+Report which tools are installed and authenticated.
+
+**General / no clear category** (catch-all when no keyword matches):
+
+Run all checks from the above categories and present a full health summary. Include:
+- Donna version (from `~/.donna/version.md`)
+- Config status (file exists, storage_repo path valid)
+- Storage status (git repo exists, donna/ and daily/ present, uncommitted changes)
+- Installed skills count (stubs in `~/.claude/commands/donna/`, workflows in `~/.donna/workflows/`)
+- Configured tools (from `<storage_repo>/donna/tools.md`)
+
+After running diagnostics, present findings clearly:
+- Use `✓` for things that look good
+- Use `✗` for things that look broken
+- Provide specific fix suggestions for each `✗` item
+</step>
+
+<step name="follow-up">
+Use AskUserQuestion:
+
+```
+Did that help? You can:
+1. Ask about something else
+2. Submit a bug report or feature idea (I'll point you to /donna:contribute-idea)
+3. Done — I'm all set
+
+What would you like to do?
+```
+
+Handle each option:
+
+- **Option 1:** Ask the user for a new description of their issue. Loop back to the diagnose step with the new question.
+
+- **Option 2:** Print:
+  ```
+  Tip: Run /donna:contribute-idea to submit ideas or bug reports via GitHub Issues.
+  ```
+  Stop.
+
+- **Option 3:** Print:
+  ```
+  ✓ Glad I could help!
+  ```
+  Stop.
+</step>