@pingvinen/donna-assistant 0.9.1 → 0.11.0

package/workflows/add-task.md

@@ -4,62 +4,25 @@
 Capture a new task to today's daily journal file in the storage repo and commit it 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.
-
+<step name="init">
 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"
+INIT=$(node ~/.donna/donna-tools.cjs init)
 ```
 
-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"
+Parse the JSON response. If the `error` field is `"not_configured"`, print:
 ```
+x Donna is not configured. Run /donna:setup first.
+```
+Stop.
 
-If `auto_push` is true in config, also push.
+Extract `storage_repo`, `daily_folder`, `auto_push` from the JSON.
 
-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: []
----
+If `update_available` is non-null, print:
+```
+Donna v<update_available> available -- run npx @pingvinen/donna-assistant to update
 ```
+Continue normally.
 </step>
 
 <step name="get-description">
@@ -74,17 +37,11 @@ Store the response as `<description>`.
 </step>
 
 <step name="ensure-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`.
-
-Run via Bash to ensure the daily folder exists:
+Get the daily file path via donna-tools:
 ```bash
-mkdir -p <storage_repo>/<daily_folder>
+DAILY_PATH=$(node ~/.donna/donna-tools.cjs daily-path | node -e "process.stdin.resume();let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>console.log(JSON.parse(d).path))")
 ```
+Store the result as `<daily_file_path>`. Extract `<date>` from the filename (last path component without `.md`).
 
 If the daily file does not exist, create it with the Write tool using this content (substituting the actual date):
 ```markdown
@@ -107,24 +64,7 @@ Write the updated file with the Write tool.
 <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-task): <description>"
-```
-
-If `auto_push` is true in config, also run:
-```bash
-git -C <storage_repo> push
+node ~/.donna/donna-tools.cjs commit "donna(task): added <description>" --files <daily_folder>/<date>.md
 ```
 </step>
 

package/workflows/add-tool.md

@@ -4,82 +4,25 @@
 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">
-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.
-
+<step name="init">
 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"
+INIT=$(node ~/.donna/donna-tools.cjs init)
 ```
 
-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"
+Parse the JSON response. If the `error` field is `"not_configured"`, print:
 ```
-
-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"
+x Donna is not configured. Run /donna:setup first.
 ```
+Stop.
 
-If `auto_push` is true in config, also push.
+Extract `storage_repo`, `daily_folder`, `auto_push` from the JSON.
 
-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: []
----
+If `update_available` is non-null, print:
+```
+Donna v<update_available> available -- run npx @pingvinen/donna-assistant to update
 ```
+Continue normally.
 </step>
 
 <step name="detect-noted-tools">
@@ -163,11 +106,11 @@ Store the output as `<version>`. If the command does not support `--version`, st
 <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:
+For well-known tools, run the appropriate auth test via Bash (set the Bash tool's `timeout` parameter to `10000`):
 
-- `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`
+- `gh`: run `gh api user --jq '.login' 2>&1` via Bash with `timeout: 10000`
+- `jira`: run `jira me 2>&1` via Bash with `timeout: 10000`
+- `kubectl`: run `kubectl auth whoami 2>&1` via Bash with `timeout: 10000`
 - Other tools: skip auth test, print `ℹ No known auth test for <command>. Verify manually.`
 
 On success (exit 0): print `✓ Authenticated as <output>`.
@@ -219,7 +162,7 @@ Write the updated secrets.md.
 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:
+Resolve the secret via Bash: `node ~/.donna/donna-tools.cjs resolve-secret <auth_secret>`. Parse the JSON response. If `error` is `"key_not_found"` or `"placeholder_value"`, print:
 ```
 ! No secret set for <auth_secret> — edit donna/secrets.md before testing connectivity.
 ```
@@ -300,7 +243,48 @@ If `<scope>` is set, replace `--all-namespaces` with `-n <namespace>` for each n
 - 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>`.
+For **unknown tools**, use a cascading approach to learn capabilities. Each stage builds on the previous. Stop when 3-5 relevant capabilities have been identified.
+
+**Stage 1 — Local docs:**
+Attempt to find local documentation for the tool:
+```bash
+TOOL_PATH=$(which <command> 2>/dev/null)
+```
+If found, check for README or docs in the tool's package directory:
+```bash
+TOOL_DIR=$(dirname "$(dirname "$TOOL_PATH")")
+ls "$TOOL_DIR"/README* "$TOOL_DIR"/doc* "$TOOL_DIR"/docs* 2>/dev/null | head -5
+```
+If doc files exist, read the entry-point doc (prefer README, then docs/index or equivalent). Then follow internal links, references, or "see also" pointers to the sections most relevant to daily task management. Use Claude's understanding to navigate — don't stop at a fixed line count.
+
+**Stage 2 — CLI help (baseline):**
+Run `<command> --help 2>&1 | head -80` via Bash. If the help output lists subcommands, also run `<command> <subcommand> --help` for the 3-5 most relevant-looking subcommands. Combine with any Stage 1 findings. Use Claude's understanding to identify 3-5 capabilities relevant to daily task management. If `<scope>` is set, incorporate the scope into CLI invocations.
+
+**Stage 3 — Web docs (if stages 1-2 found fewer than 3 capabilities):**
+If fewer than 3 capabilities identified so far, attempt to fetch the tool's documentation from the web. Use WebFetch on common doc URLs:
+- `https://<command>.dev` or `https://<command>.io`
+- The homepage URL from `<command> --help` output if one was printed
+
+If a docs page is found, follow links to CLI reference, commands, or API sections rather than reading only the landing page. Extract additional capabilities from those deeper pages.
+
+**Stage 4 — Source code analysis (user opt-in per D-09):**
+After stages 1-3, if the tool path was found in Stage 1, print the number of capabilities discovered and ask the user:
+
+Use AskUserQuestion:
+```
+Found <N> capabilities from docs and help output. Want me to analyze <command>'s source code for more?
+```
+
+If the user says yes:
+- Read the main entry point (e.g., bin/<command>, cli.js, main.py)
+- Follow imports/requires to command registration, subcommand definitions, or handler modules
+- Navigate into the files that define actual commands and actions — don't stop at the entry point
+- Identify additional capabilities from function names, subcommands, or API surface
+- Add any new relevant capabilities to the list
+
+If the user says no, continue with what was found.
+
+Format each capability as `name: <cli invocation>`.
 
 **If `<tool_type>` is `rest`:**
 
@@ -433,24 +417,7 @@ If a section for this tool already exists in tools.md, replace it entirely. Writ
 <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
+node ~/.donna/donna-tools.cjs commit "donna(add-tool): registered <tool_name>" --files donna/tools.md
 ```
 </step>
 

package/workflows/adjust-tool.md

@@ -1,85 +1,28 @@
 # Donna Adjust-Tool Workflow
 
 <objective>
-Edit an existing registered tool's configuration — scope, capabilities, auth/secrets, command, or type.
+Edit an existing registered tool's configuration — scope, capabilities, auth/secrets, or command.
 </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.
-
+<step name="init">
 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"
+INIT=$(node ~/.donna/donna-tools.cjs init)
 ```
 
-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"
+Parse the JSON response. If the `error` field is `"not_configured"`, print:
 ```
-
-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"
+x Donna is not configured. Run /donna:setup first.
 ```
+Stop.
 
-If `auto_push` is true in config, also push.
+Extract `storage_repo`, `daily_folder`, `auto_push` from the JSON.
 
-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: []
----
+If `update_available` is non-null, print:
+```
+Donna v<update_available> available -- run npx @pingvinen/donna-assistant to update
 ```
+Continue normally.
 </step>
 
 <step name="read-tools-md">
@@ -133,9 +76,18 @@ What would you like to change?
 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>`.
+
+**If the user asks to change the type** (response mentions "type", "change type", "switch type", etc.):
+Print:
+```
+Tool type cannot be changed in-place — it affects how capabilities are learned and how the tool is invoked. To change a tool's type, remove and re-add:
+
+1. /donna:remove-tool <tool_name>
+2. /donna:add-tool <tool_name>
+```
+Stop — do not proceed to apply-change.
 </step>
 
 <step name="apply-change">
@@ -166,51 +118,6 @@ 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">
@@ -220,24 +127,7 @@ Read `<storage_repo>/donna/tools.md`. Update only the `<selected_tool>` section
 <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
+node ~/.donna/donna-tools.cjs commit "donna(adjust-tool): updated <tool_name> (<change_description>)" --files donna/tools.md
 ```
 </step>