@pingvinen/donna-assistant 0.5.0 → 0.7.0

package/workflows/adjust-tool.md

@@ -0,0 +1,250 @@
+# Donna Adjust-Tool Workflow
+
+<objective>
+Edit an existing registered tool's configuration — scope, capabilities, auth/secrets, command, or type.
+</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.
+
+**`backfill-tool-type`:** Backfill `type` on existing tool sections in tools.md using heuristic detection.
+
+Read `<storage_repo>/donna/tools.md` with the Read tool. If the file does not exist or has no tool sections, skip this handler.
+
+For each tool section (starting with `## <tool_name>`), check if a `- type:` line already exists. If the `- type:` line is missing, detect the correct type:
+
+1. If the tool section contains a `- command:` line where the value starts with `mcp:` (e.g., `- command: mcp:linear`), insert `- type: mcp` immediately after the `- command:` line.
+2. Else, if the tool section contains a `- base_url:` line:
+   - If the capabilities section contains entries that look like GraphQL queries (contain `query {` or `mutation {`), insert `- type: graphql` immediately after `## <tool_name>` (REST/GraphQL tools have no `- command:` line).
+   - Otherwise, insert `- type: rest` immediately after `## <tool_name>`.
+3. Else (no `mcp:` prefix, no `base_url` field), insert `- type: cli` immediately after the `- command:` line.
+
+Write the updated file back with the Write tool. If any changes were made, commit:
+```bash
+git -C <storage_repo> add -A
+git -C <storage_repo> diff --cached --quiet || git -C <storage_repo> commit -m "donna(migrate): backfill tool types on existing tools"
+```
+
+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 or has no tool sections, print:
+```
+! No tools registered. Run /donna:add-tool first.
+```
+Stop.
+
+Parse each tool section (starting with `## <tool_name>`). For each tool, extract the `type` field (if absent, treat as "cli"), `command`, `version`, `learned`, `auth_test`, `scope`, and capabilities list under `### Capabilities`.
+
+Store as `<registered_tools>`.
+</step>
+
+<step name="select-tool">
+If a tool name was provided as argument (e.g., `/donna:adjust-tool gh`), look it up in `<registered_tools>`. If not found, print `! Tool "<name>" not found in tools.md` and stop.
+
+If no argument was provided, list all registered tools via AskUserQuestion:
+```
+Which tool would you like to adjust?
+
+<numbered list of tool names from registered_tools>
+```
+Store the selected tool as `<selected_tool>`.
+</step>
+
+<step name="show-current-config">
+Display the current configuration of `<selected_tool>`:
+```
+Current configuration for <tool_name>:
+
+  command:   <command>
+  type:      <type>
+  version:   <version>
+  learned:   <learned>
+  auth_test: <auth_test>
+  scope:     <scope>
+
+  Capabilities:
+  - <name>: <invocation>
+  - ...
+```
+</step>
+
+<step name="ask-what-to-change">
+Use AskUserQuestion:
+```
+What would you like to change?
+
+1. scope — filtering context (orgs, repos, projects, namespaces)
+2. capabilities — add, remove, or modify capability commands
+3. command — the CLI command or base URL
+4. auth — auth test command or API secrets
+5. type — tool type (cli, rest, graphql, mcp)
+```
+Store as `<change_choice>`.
+</step>
+
+<step name="apply-change">
+Based on `<change_choice>`:
+
+**1. scope:**
+Show current scope. Use AskUserQuestion: `New scope for <tool_name>? (current: <scope>)`. Store new value.
+Then ask via AskUserQuestion: `Scope changed. Re-learn capabilities with new scope? (yes/no)`.
+If yes, run the same learn-capabilities logic as add-tool.md (well-known baselines for gh/jira/kubectl, `--help` parse for unknown tools), incorporating the new scope into CLI invocations.
+
+**2. capabilities:**
+Show current capabilities numbered. Use AskUserQuestion:
+```
+Current capabilities:
+1. <name>: <invocation>
+2. ...
+
+Type "remove <number>" to remove, "add <name>: <command>" to add, or "edit <number> <new_command>" to modify.
+```
+Apply the change. Allow multiple edits — keep asking until user says "done".
+
+**3. command:**
+Use AskUserQuestion: `New command for <tool_name>? (current: <command>)`. Store new value.
+Verify installation: `which <new_command>` via Bash. Print result.
+
+**4. auth:**
+For type=cli: Use AskUserQuestion to update auth_test command.
+For type=rest|graphql: Print `Edit your secrets in <storage_repo>/donna/secrets.md directly. The auth_secret field references the key name in that file.` Use AskUserQuestion to update `auth_secret` field name if needed.
+For type=mcp: Print `MCP server auth is managed in Claude Code settings, not in Donna.`
+
+**5. type:**
+Use AskUserQuestion:
+```
+What is the correct type for <tool_name>? (cli, rest, graphql, mcp) Current: <type>
+```
+Store new value as `<new_type>`.
+
+If `<new_type>` differs from `<type>`, check for capability format mismatches:
+
+**Detect format mismatches:**
+For each capability line (`- <name>: <invocation>`), check if the invocation matches the expected format for `<new_type>`:
+- `cli`: invocation should be a shell command (no `mcp:` prefix, no `GET /` or `POST /` pattern, no `query {` pattern)
+- `rest`: invocation should match `<METHOD> /path` pattern (e.g., `GET /repos/...`)
+- `graphql`: invocation should contain `query {` or `mutation {`
+- `mcp`: invocation should match `mcp:<server>/<tool>` pattern
+
+If ANY capability does not match the expected format for `<new_type>`, print:
+
+```
+⚠ Capability format mismatch detected. Current capabilities are in <type> format but type is changing to <new_type>.
+
+Mismatched capabilities:
+<list each mismatched capability with its current invocation>
+```
+
+Use AskUserQuestion:
+```
+How would you like to fix the capabilities?
+```
+Suggest these options:
+1. Re-enter capabilities manually (interactive editor)
+2. Clear all capabilities (start fresh with adjust-tool later)
+3. Keep as-is (may cause runtime errors)
+
+If option 1: Present the same interactive capabilities editing loop (show numbered list, accept "remove N", "add name: invocation", "edit N new_invocation", "done"). Pre-populate with existing capability NAMES but empty invocations so the user only needs to type the new format.
+
+If option 2: Clear the capabilities section entirely. Print `✓ Capabilities cleared. Run /donna:adjust-tool <tool_name> to add new capabilities.`
+
+If option 3: Print `⚠ Keeping mismatched capabilities — runtime errors may occur.`
+
+**Update structural fields when type changes:**
+- Changing TO rest/graphql: ensure `base_url`, `auth_header`, `auth_secret` fields exist. If missing, prompt for them (same prompts as add-tool).
+- Changing TO mcp: remove `command`, `version`, `base_url`, `auth_header`, `auth_secret` fields if present.
+- Changing TO cli: ensure `command`, `version` fields exist. If missing, prompt for command and run version check.
+- Changing FROM rest/graphql: remove `base_url`, `auth_header`, `auth_secret` fields.
+</step>
+
+<step name="write-tools-md">
+Read `<storage_repo>/donna/tools.md`. Update only the `<selected_tool>` section with the changed fields. Preserve all other tool sections unchanged. 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(adjust-tool): updated <tool_name> (<change_description>)"
+```
+
+If `auto_push` is true in config, also run:
+```bash
+git -C <storage_repo> push
+```
+</step>
+
+<step name="confirm">
+Print:
+```
+! Updated <tool_name>:
+  <field>: <old_value> -> <new_value>
+```
+</step>

package/workflows/begin-the-day.md

@@ -54,6 +54,26 @@ git -C <storage_repo> diff --cached --quiet || git -C <storage_repo> commit -m "
 
 If `auto_push` is true in config, also push.
 
+**`backfill-tool-type`:** Backfill `type` on existing tool sections in tools.md using heuristic detection.
+
+Read `<storage_repo>/donna/tools.md` with the Read tool. If the file does not exist or has no tool sections, skip this handler.
+
+For each tool section (starting with `## <tool_name>`), check if a `- type:` line already exists. If the `- type:` line is missing, detect the correct type:
+
+1. If the tool section contains a `- command:` line where the value starts with `mcp:` (e.g., `- command: mcp:linear`), insert `- type: mcp` immediately after the `- command:` line.
+2. Else, if the tool section contains a `- base_url:` line:
+   - If the capabilities section contains entries that look like GraphQL queries (contain `query {` or `mutation {`), insert `- type: graphql` immediately after `## <tool_name>` (REST/GraphQL tools have no `- command:` line).
+   - Otherwise, insert `- type: rest` immediately after `## <tool_name>`.
+3. Else (no `mcp:` prefix, no `base_url` field), insert `- type: cli` immediately after the `- command:` line.
+
+Write the updated file back with the Write tool. If any changes were made, commit:
+```bash
+git -C <storage_repo> add -A
+git -C <storage_repo> diff --cached --quiet || git -C <storage_repo> commit -m "donna(migrate): backfill tool types on existing tools"
+```
+
+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
 ---
@@ -132,9 +152,33 @@ 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>`):
+Parse each tool section (starting with `## <tool_name>`). For each tool, extract the `type` field (if absent, treat as "cli"), the `command` field (or `base_url` for rest/graphql), and the capabilities list under `### Capabilities`.
+
+Store the parsed tools and their capabilities as `<registered_tools>`.
+
+**If only one tool is registered**, run it directly (no Task spawning needed) using the type-aware execution logic below.
+
+**If multiple tools are registered**, spawn one Task agent per tool. Each agent receives:
+
+- The tool name, type, and its capabilities list
+- For REST/GraphQL tools: the base_url, auth_header, and auth_secret fields
+- For MCP tools: the capability names with mcp: prefix
+- Instructions to execute all capabilities and return results as a structured list
+- Instructions to NEVER write to any file or run git commands
+
+**CRITICAL constraints for Task agents:**
+- Agents return raw task lists and warnings ONLY
+- Agents must NOT write to any file (no Write tool calls to daily file)
+- Agents must NOT run git commands (SSH signing constraint from CLAUDE.md)
+- All file writing happens in the main workflow after agents return
+
+**Global timeout:** Wait for all Task agents to complete, up to 2 minutes total. After 2 minutes, collect whatever results have been returned and treat non-responding tools as failed with warning: `! <tool_name>: timed out (2-minute batch limit)`.
 
-Run the CLI invocation via Bash with a 10-second timeout:
+**Type-aware execution within each agent (or direct execution for single tool):**
+
+For `type: cli` capabilities (format: `<name>: <cli_invocation>`):
+
+Run via Bash with a 10-second timeout:
 ```bash
 timeout 10 <cli_invocation> 2>&1
 ```
@@ -161,7 +205,44 @@ Determine the failure type from the exit code and output:
 - 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.
+Add the warning to `<tool_warnings>`. Continue to next capability/tool. Never retry.
+
+For `type: rest` capabilities (format: `<name>: <METHOD> /path`):
+1. Read `<storage_repo>/donna/secrets.md` with the Read tool. Parse key-value pairs from under the frontmatter.
+2. Resolve the `auth_secret` key to get the actual secret value. If the key is not found in secrets.md or the value is `REPLACE_WITH_YOUR_SECRET`, add warning `! <tool_name>: missing secret <auth_secret> — edit donna/secrets.md` and skip this tool.
+3. For each capability, run via Bash with a 10-second timeout:
+```bash
+timeout 10 curl -s -H "<auth_header>: <resolved_secret>" "<base_url><path>" 2>&1
+```
+4. Parse the JSON response using Claude's understanding to extract task-like items. Format:
+`- [ ] (<tool_name>) <description> [<identifier>](<url>)`
+
+**On any failure** (non-zero exit, timeout, missing secret):
+Add a warning: `! <tool_name>: <error_description>`
+Continue. Never retry.
+
+For `type: graphql` capabilities (format: `<name>: <graphql_query>`):
+1. Same secrets resolution as REST.
+2. For each capability, run via Bash with a 10-second timeout:
+```bash
+timeout 10 curl -s -X POST -H "<auth_header>: <resolved_secret>" -H "Content-Type: application/json" -d '{"query":"<graphql_query>"}' "<base_url>" 2>&1
+```
+3. Parse the JSON response to extract task-like items. Same format as REST.
+
+**On any failure** (non-zero exit, timeout, missing secret):
+Add a warning: `! <tool_name>: <error_description>`
+Continue. Never retry.
+
+For `type: mcp` capabilities (format: `<name>: mcp:<server>/<tool>`):
+1. Invoke the MCP tool directly using Claude's native MCP tool invocation (NOT via Bash).
+2. Parse the MCP tool's response using Claude's understanding of the tool to extract task-like items. Format:
+`- [ ] (<tool_name>) <description> [<identifier>](<url>)`
+
+**On any failure:**
+Add a warning: `! <tool_name>: <error_description>`
+Continue. 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>`.

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/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>