@pingvinen/donna-assistant 0.6.0 → 0.8.0

package/README.md

@@ -73,7 +73,14 @@ Re-pulls data from all configured tools. New items appear, resolved items get cl
 
 ## External tools
 
-Donna can pull tasks and status from CLI tools you already have installed. Register them with:
+Donna can pull tasks and status from external tools you already use. She supports four tool types:
+
+- **CLI tools** — shell commands like `gh`, `jira`, `kubectl`
+- **REST APIs** — HTTP endpoints like GitHub API, Slack API
+- **GraphQL APIs** — GraphQL endpoints like Linear, GitHub GraphQL
+- **MCP servers** — Claude Code MCP tools like linear, postgres
+
+Register a tool with:
 
 ```
 /donna:add-tool gh
@@ -81,9 +88,17 @@ Donna can pull tasks and status from CLI tools you already have installed. Regis
 
 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.
+For CLI tools, Donna verifies installation and authentication, learns capabilities, and asks what scope to query. For REST and GraphQL APIs, Donna sets up secure secret management (via a gitignored `secrets.md` file) and validates API connectivity. MCP servers are configured through Claude Code settings.
+
+When multiple tools are registered, Donna runs them in parallel — one agent per tool — so your morning brief stays fast regardless of how many tools you have.
+
+Edit a tool's configuration (scope, capabilities, auth, command, type) at any time:
+
+```
+/donna:adjust-tool
+```
 
-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:
+If a CLI tool version is newer than what the AI model knows, Donna will re-learn its capabilities:
 
 ```
 /donna:relearn-tools
@@ -120,11 +135,13 @@ Most commands are safe to run again. Want to update your role? Run `/donna:set-r
 | `/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:add-tool` | Register an external tool (CLI, REST API, GraphQL API, MCP server) |
+| `/donna:adjust-tool` | Edit a tool's configuration (scope, capabilities, auth, command, type) |
 | `/donna:run-tools` | Refresh tool data mid-day |
-| `/donna:relearn-tools` | Update tool knowledge after upgrades |
+| `/donna:relearn-tools` | Update CLI tool knowledge after upgrades |
 | `/donna:help` | Conversational troubleshooting for config, storage, or skill issues |
 | `/donna:contribute-idea` | Submit a feature idea or bug report via GitHub Issues |
+| `/donna:focus` | Distill today's tasks into a short prioritized focus list |
 
 ## License
 

package/migrations/003-tool-type-backfill.cjs

@@ -0,0 +1,36 @@
+"use strict";
+
+module.exports = {
+    version: "0.7.0",
+    description: "Backfill type: cli on existing tool sections in tools.md",
+    up(ctx) {
+        // tools.md lives 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 backfill 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("backfill-tool-type")) {
+                // Already queued — idempotent, nothing to do
+                return;
+            }
+        }
+
+        if (ctx.fs.existsSync(statePath)) {
+            // Append to existing pending_migrations list
+            const existing = ctx.fs.readFileSync(statePath, "utf8");
+            const updated = existing.replace(
+                /^(pending_migrations:\n(?:\s+-\s+.*\n)*)/m,
+                "$1  - backfill-tool-type\n",
+            );
+            if (updated !== existing) {
+                ctx.fs.writeFileSync(statePath, updated, "utf8");
+                return;
+            }
+        }
+
+        const pendingFlag = "---\npending_migrations:\n  - backfill-tool-type\n---\n";
+        ctx.fs.writeFileSync(statePath, pendingFlag, "utf8");
+    },
+};

package/package.json

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

package/src/installer.cjs

@@ -79,7 +79,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, add-tool, relearn-tools, run-tools, help, contribute-idea) to ${provider.stubTarget}`,
+                `Copied donna skills (setup, add-task, done, set-role, begin-the-day, add-tool, relearn-tools, run-tools, help, contribute-idea, adjust-tool, focus) to ${provider.stubTarget}`,
             );
         }
     } else {

package/stubs/claude-code/donna/adjust-tool.md

@@ -0,0 +1,17 @@
+---
+name: donna:adjust-tool
+description: Edit an existing tool's configuration — scope, capabilities, auth, or command
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Run the Donna adjust-tool workflow. Edit an existing registered tool's configuration.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/adjust-tool.md
+</execution_context>

package/stubs/claude-code/donna/focus.md

@@ -0,0 +1,16 @@
+---
+name: donna:focus
+description: Distill today's tasks into a short prioritized focus list
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Run the Donna focus workflow.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/focus.md
+</execution_context>

package/workflows/add-tool.md

@@ -1,7 +1,7 @@
 # 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.
+Declare an external tool (CLI, REST API, GraphQL API, or MCP server), verify its connectivity, learn its capabilities, and persist the result to tools.md in the storage repo.
 </objective>
 
 <step name="read-config">
@@ -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
 ---
@@ -84,17 +104,43 @@ What tool would you like to add? (e.g. gh, jira, kubectl)
 ```
 
 Store the answer as `<tool_name>`.
+</step>
+
+<step name="ask-tool-type">
+Use AskUserQuestion:
+```
+What type of tool is <tool_name>?
+
+1. CLI — runs shell commands (e.g., gh, jira, kubectl)
+2. REST API — HTTP endpoints (e.g., GitHub API, Slack API)
+3. GraphQL API — GraphQL endpoint (e.g., Linear, GitHub GraphQL)
+4. MCP server — Claude Code MCP tool (e.g., linear, postgres)
+```
 
-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:
+Store the answer as `<tool_type>`: one of `cli`, `rest`, `graphql`, `mcp`.
 
+**If type is `cli`:** Use AskUserQuestion to confirm or override the CLI command:
 ```
 CLI command for <tool_name>? (default: <tool_name>)
 ```
+If the tool name is in `<noted_tools>`, pre-fill any context from set-role notes. If the user presses enter without typing, use the default. Store the confirmed CLI command as `<command>`.
+
+**If type is `rest` or `graphql`:**
 
-If the user presses enter without typing, use the default. Store the confirmed CLI command as `<command>`.
+The base URL is the root API endpoint (for example, https://api.github.com for GitHub REST or https://api.linear.app/graphql for Linear). Guide the user if they seem unsure, but do not include examples in the AskUserQuestion prompt text — inline examples render as picker options in Claude Code.
+
+Use AskUserQuestion:
+```
+What is the base URL for <tool_name>?
+```
+Store as `<base_url>`. Set `<command>` to `<base_url>` (for display purposes).
+
+**If type is `mcp`:** Skip the command question. Set `<command>` to `mcp`.
 </step>
 
 <step name="verify-installation">
+If `<tool_type>` is not `cli`, skip this step.
+
 Run via Bash:
 ```bash
 which <command> && echo "INSTALLED=true" || echo "INSTALLED=false"
@@ -115,6 +161,8 @@ Store the output as `<version>`. If the command does not support `--version`, st
 </step>
 
 <step name="auth-test">
+**If `<tool_type>` is `cli`:**
+
 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`
@@ -132,9 +180,66 @@ Fix instructions per tool:
 - `kubectl` → check your kubeconfig
 
 Continue (do not stop — user may want to save the tool despite auth issues).
+
+**If `<tool_type>` is `rest` or `graphql`:**
+
+Common auth headers include Authorization (for Bearer tokens) and X-API-Key. Do not include examples in the prompt text.
+
+Use AskUserQuestion to ask for the auth header name:
+```
+What auth header does <tool_name> use? Default: Authorization
+```
+Store as `<auth_header>` (default: `Authorization` if blank).
+
+The key name should match the service convention (e.g., GITHUB_TOKEN, SLACK_TOKEN, LINEAR_API_KEY). Guide the user if needed but keep examples out of the prompt.
+
+Use AskUserQuestion to ask for the secret key name:
+```
+What should the secret key be called in secrets.md for <tool_name>?
+```
+Store as `<auth_secret>`.
+
+**Set up secrets.md:**
+Read `<storage_repo>/donna/secrets.md` with the Read tool. If the file does not exist, create it with:
+```markdown
+---
+# secrets.md -- managed by user, never by donna
+# Auto-added to .gitignore
+---
+```
+
+Check if `<auth_secret>` already appears in secrets.md. If not, append a placeholder line:
+```
+<auth_secret>: REPLACE_WITH_YOUR_SECRET
+```
+
+Write the updated secrets.md.
+
+**Ensure secrets.md is gitignored:**
+Read `<storage_repo>/.gitignore` with the Read tool. If the file does not exist or does not contain `donna/secrets.md`, append `donna/secrets.md` to `.gitignore` and write back. If `.gitignore` does not exist, create it with `donna/secrets.md` as its sole content.
+
+**Validate API connectivity:**
+Read `<storage_repo>/donna/secrets.md` to get the current value for `<auth_secret>`. If the value is `REPLACE_WITH_YOUR_SECRET` or the key is absent, print:
+```
+! No secret set for <auth_secret> — edit donna/secrets.md before testing connectivity.
+```
+Skip validation.
+
+If a real secret value exists, run via Bash:
+```bash
+curl -s -o /dev/null -w "%{http_code}" -H "<auth_header>: <resolved_secret>" <base_url> 2>&1
+```
+- 200-299: print `✓ API reachable at <base_url>`
+- 401/403: print `! Authentication failed — check <auth_secret> in donna/secrets.md`
+- Other/timeout: print `! Could not reach <base_url>`
+
+**If `<tool_type>` is `mcp`:**
+Print `ℹ MCP server auth is managed in Claude Code settings. Skipping auth test.`
 </step>
 
 <step name="ask-scope">
+**If `<tool_type>` is `cli`:**
+
 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`)
@@ -149,10 +254,28 @@ What scope should Donna use for <tool_name>?
 Leave blank for no filtering.
 ```
 
+**If `<tool_type>` is `rest` or `graphql`:**
+
+Use AskUserQuestion:
+```
+What scope should Donna use for <tool_name>? (e.g., specific endpoints or resource filters to apply)
+Leave blank for no filtering.
+```
+
+**If `<tool_type>` is `mcp`:**
+
+Use AskUserQuestion:
+```
+What scope should Donna use for <tool_name>? (e.g., specific resources to monitor)
+Leave blank for no filtering.
+```
+
 Store the answer as `<scope>`. If blank, set to empty string.
 </step>
 
 <step name="learn-capabilities">
+**If `<tool_type>` is `cli`:**
+
 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:**
@@ -179,6 +302,50 @@ If `<scope>` is set, replace `--all-namespaces` with `-n <namespace>` for each n
 
 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>`.
 
+**If `<tool_type>` is `rest`:**
+
+Print to user:
+```
+Each capability is a name and HTTP method + path.
+Format: <name>: <METHOD> /path?params
+Example: list-issues: GET /repos/{owner}/{repo}/issues?state=open
+Example: my-profile: GET /user
+```
+
+Use AskUserQuestion:
+```
+Enter capabilities for <tool_name> (one per line, blank line when done):
+```
+
+**If `<tool_type>` is `graphql`:**
+
+Print to user:
+```
+Each capability is a name and a GraphQL query (single line).
+Format: <name>: query { ... }
+Example: my-issues: query { viewer { issues(first: 20, states: OPEN) { nodes { title url } } } }
+```
+
+Use AskUserQuestion:
+```
+Enter capabilities for <tool_name> (one per line, blank line when done):
+```
+
+**If `<tool_type>` is `mcp`:**
+
+Print to user:
+```
+Each capability is a name and an MCP tool reference.
+Format: <name>: mcp:<server_name>/<tool_name>
+Example: list-issues: mcp:linear/list_issues
+Example: search-docs: mcp:notion/search
+```
+
+Use AskUserQuestion:
+```
+Enter capabilities for <tool_name> (one per line, blank line when done):
+```
+
 Store the full list as `<available_capabilities>`.
 </step>
 
@@ -202,11 +369,14 @@ Read `<storage_repo>/donna/tools.md` with the Read tool. If the file does not ex
 ---
 ```
 
-Upsert (not overwrite) the tool's section. Each tool section has this format:
+Upsert (not overwrite) the tool's section. Each tool section has a type-specific format:
+
+**CLI tools:**
 ```markdown
 ## <tool_name>
 
 - command: <command>
+- type: cli
 - version: <version>
 - learned: <today's date YYYY-MM-DD>
 - auth_test: <auth_test_command or "none">
@@ -216,6 +386,47 @@ Upsert (not overwrite) the tool's section. Each tool section has this format:
 - <capability_name>: <cli_invocation>
 ```
 
+**REST API tools:**
+```markdown
+## <tool_name>
+
+- type: rest
+- base_url: <base_url>
+- auth_header: <auth_header>
+- auth_secret: <auth_secret>
+- scope: <scope or "none">
+- learned: <today's date YYYY-MM-DD>
+
+### Capabilities
+- <capability_name>: <METHOD> /path
+```
+
+**GraphQL API tools:**
+```markdown
+## <tool_name>
+
+- type: graphql
+- base_url: <base_url>
+- auth_header: <auth_header>
+- auth_secret: <auth_secret>
+- scope: <scope or "none">
+- learned: <today's date YYYY-MM-DD>
+
+### Capabilities
+- <capability_name>: <graphql_query>
+```
+
+**MCP server tools:**
+```markdown
+## <tool_name>
+
+- type: mcp
+- learned: <today's date YYYY-MM-DD>
+
+### Capabilities
+- <capability_name>: mcp:<server>/<tool>
+```
+
 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>
 
@@ -244,6 +455,8 @@ git -C <storage_repo> push
 </step>
 
 <step name="confirm">
+**If `<tool_type>` is `cli`:**
+
 Print:
 ```
 ✓ Added <tool_name> to tools registry
@@ -254,6 +467,29 @@ Print:
   Run /donna:begin-the-day to see tool data in your daily brief.
 ```
 
+**If `<tool_type>` is `rest` or `graphql`:**
+
+Print:
+```
+✓ Added <tool_name> to tools registry (type: <tool_type>)
+  Base URL: <base_url>
+  Capabilities: <count> configured
+  Secrets: Edit donna/secrets.md to set <auth_secret>
+
+  Run /donna:begin-the-day to see tool data in your daily brief.
+```
+
+**If `<tool_type>` is `mcp`:**
+
+Print:
+```
+✓ Added <tool_name> to tools registry (type: mcp)
+  Capabilities: <count> configured
+
+  Ensure the MCP server is configured in Claude Code settings.
+  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>, ...