@pingvinen/donna-assistant 0.10.0 → 0.11.0

package/README.md

@@ -111,6 +111,7 @@ If a CLI tool version is newer than what the AI model knows, Donna will re-learn
   donna/
     role.md          # your job role definition
     recurring.md     # recurring task schedule
+    follow-ups.md    # scheduled follow-up tasks with due dates
     tools.md         # registered tool configurations
   daily/
     2026-03-16.md    # today's tasks, tool data, notes
@@ -152,6 +153,7 @@ Instead, run `/donna:run-tools` on demand when you want fresh data, or let `/don
 | `/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-follow-up-task` | Schedule a task for a future date -- Donna reminds you when it is due |
 | `/donna:focus` | Distill today's tasks into a short prioritized focus list |
 
 ### Tool management

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pingvinen/donna-assistant",
-  "version": "0.10.0",
+  "version": "0.11.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, remove-tool, relearn-tools, run-tools, help, contribute-idea, adjust-tool, focus) to ${provider.stubTarget}`,
+                `Copied donna skills (setup, add-task, done, set-role, begin-the-day, add-tool, remove-tool, relearn-tools, run-tools, help, contribute-idea, adjust-tool, focus, add-follow-up-task) to ${provider.stubTarget}`,
             );
         }
     } else {

package/stubs/claude-code/donna/add-follow-up-task.md

@@ -0,0 +1,17 @@
+---
+name: donna:add-follow-up-task
+description: Schedule a follow-up task for a future date
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Run the Donna follow-up workflow.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/follow-up.md
+</execution_context>

package/workflows/begin-the-day.md

@@ -94,6 +94,26 @@ 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="check-follow-ups">
+Read `<storage_repo>/donna/follow-ups.md` with the Read tool. If the file does not exist, set `<follow_up_tasks>` to an empty list, set `<follow_ups_modified>` to `false`, and continue (follow-ups are optional).
+
+Parse each line matching the pattern `- [ ] <description> | due: YYYY-MM-DD`. For each matching entry:
+
+- Parse the `due` date (YYYY-MM-DD).
+- If `due <= <today>`: add to `<follow_up_tasks>` as: `- [ ] <description>` (no annotation).
+- If `due > <today>`: task is future — leave the line in follow-ups.md. Do not add to `<follow_up_tasks>`.
+
+After collecting all due/past-due tasks, remove those matched lines from follow-ups.md (the matched lines are NOT written back — only future lines remain). Write the updated file back with the Write tool. If lines were removed, set `<follow_ups_modified>` to `true`. If no lines were removed, set `<follow_ups_modified>` to `false` and skip the file write. Per D-03: items are removed, not checked off or left with a marker.
+
+Store `<follow_up_tasks>` for use in the deduplicate step.
+
+CRITICAL constraints:
+- The step reads only one specific named file (`donna/follow-ups.md`) — no directory scan, no wildcard listing
+- File existence check is done via the Read tool (handle missing file gracefully)
+- macOS date command uses the exact same `date -j` pattern as the existing check-recurring step
+- Invalid date strings caught by `date -j`; skip the entry (do not surface, do not remove)
+</step>
+
 <step name="pull-tool-data">
 Read `<storage_repo>/donna/tools.md` with the Read tool.
 
@@ -212,7 +232,9 @@ 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.
+4. Add `<follow_up_tasks>` as-is — for each follow-up 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.
+
+5. 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.
 
@@ -239,6 +261,7 @@ 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>
+<follow-up tasks not already in existing>
 
 ## From Tools
 <tool tasks not already in existing — only if there are tool tasks>
@@ -250,7 +273,7 @@ date: <today>
 <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.
+Tasks are written in this order: existing tasks first (preserving their original order and state), then carried-forward tasks, then recurring tasks, then follow-up 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`).
@@ -265,10 +288,17 @@ If no "every other" recurring tasks were added, skip this step.
 </step>
 
 <step name="git-commit">
-Run via Bash:
+If `<follow_ups_modified>` is `true` (the check-follow-ups step modified follow-ups.md), run via Bash:
+```bash
+node ~/.donna/donna-tools.cjs commit "donna(daily): <today> daily brief" --files <daily_folder>/<today>.md donna/follow-ups.md
+```
+
+Otherwise (follow-ups.md was not modified), run via Bash:
 ```bash
 node ~/.donna/donna-tools.cjs commit "donna(daily): <today> daily brief" --files <daily_folder>/<today>.md
 ```
+
+Per D-07: follow-ups.md is included in the commit when items were surfaced and removed from the standing file.
 </step>
 
 <step name="print-brief">
@@ -293,6 +323,13 @@ If there are recurring tasks due today (tasks from `<recurring_tasks>` that were
 - [ ] Review sprint backlog
 ```
 
+If there are follow-up tasks (tasks from `<follow_up_tasks>` that were added to the final list), print:
+```
+## Follow-ups
+- [ ] Review design doc
+- [ ] Submit expense report
+```
+
 If there are tool tasks (tasks from `<tool_tasks>` that were added to the final list), print:
 ```
 ## From Tools
@@ -311,7 +348,7 @@ 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 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:
+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 follow-up tasks, omit the "## Follow-ups" section. If no tool tasks, omit the "## From Tools" section. If no tool warnings, omit the "## Warnings" section. If carried-forward, recurring, follow-up, AND tool tasks are all empty and there are no existing tasks, print:
 ```
 No tasks for today — enjoy your day!
 ```

package/workflows/follow-up.md

@@ -0,0 +1,163 @@
+# Donna Follow-Up Workflow
+
+<objective>
+Capture a follow-up task with a future due date, resolve relative time expressions to concrete dates, store in donna/follow-ups.md, and commit via donna-tools.cjs.
+</objective>
+
+<step name="init">
+Run via Bash:
+```bash
+INIT=$(node ~/.donna/donna-tools.cjs init)
+```
+
+Parse the JSON response. If the `error` field is `"not_configured"`, print:
+```
+x Donna is not configured. Run /donna:setup first.
+```
+Stop.
+
+Extract `storage_repo`, `daily_folder`, `auto_push` from the JSON.
+
+If `update_available` is non-null, print:
+```
+Donna v<update_available> available -- run npx @pingvinen/donna-assistant to update
+```
+Continue normally.
+</step>
+
+<step name="parse-input">
+The argument is the full user text (e.g., "/donna:add-follow-up-task remind team about Q3 planning in 2 months").
+
+**If an argument was provided:**
+Use language understanding to extract two things from the argument:
+1. `<description>`: The task description (everything that is not a time expression)
+2. `<due_expression>`: A time expression (e.g., "in 2 months", "on 2026-09-15", "next Tuesday", "in 3 weeks") — or null if no time expression is found
+
+Examples:
+- "remind team about Q3 planning in 2 months" → description: "remind team about Q3 planning", due_expression: "in 2 months"
+- "call dentist on 2026-09-15" → description: "call dentist", due_expression: "on 2026-09-15"
+- "review the design doc" → description: "review the design doc", due_expression: null
+- "/donna:add-follow-up-task schedule 1:1 with Sarah next Tuesday at 2pm" → description: "schedule 1:1 with Sarah", due_expression: "next Tuesday"
+
+**If no argument was provided:**
+CRITICAL: Both AskUserQuestion prompts must use free-text input mode — do NOT use a picker with predefined options.
+
+Print the following as prose (before asking any questions):
+```
+Time expression examples: "in 2 months", "on 2026-09-15", "next Tuesday", "in 3 weeks", or leave blank for today.
+```
+
+Use AskUserQuestion to ask two questions:
+
+First question:
+```
+What task would you like to schedule?
+```
+Store the free-text response as `<description>`.
+
+Second question:
+```
+When is it due?
+```
+Store the free-text response as `<due_expression>`. If the user leaves it blank or says "today", set `<due_expression>` to null.
+</step>
+
+<step name="resolve-date">
+Three cases for resolving the due date:
+
+**Case 1: due_expression is null**
+Use today's date. Run via Bash:
+```bash
+node -e "const d=new Date();const y=d.getFullYear();const m=String(d.getMonth()+1).padStart(2,'0');const dd=String(d.getDate()).padStart(2,'0');console.log(y+'-'+m+'-'+dd)"
+```
+Store the output as `<due_date>`.
+
+**Case 2: due_expression matches YYYY-MM-DD format**
+Extract the YYYY-MM-DD part from the expression (strip any leading words like "on"). Store directly as `<due_date>`.
+
+**Case 3: due_expression is a relative expression**
+The agent parses the natural language expression into structured {value, unit} pairs:
+- "in 2 months" → months: 2
+- "in 3 weeks" → weeks: 3
+- "in 2 weeks and 3 days" → weeks: 2, days: 3
+- "in 1 month and 2 weeks" → months: 1, weeks: 2
+- "in 2 months and 5 days" → months: 2, days: 5
+- "next Tuesday" → next occurrence of Tuesday from today (count days until the next Tuesday)
+- "tomorrow" → days: 1
+- "in 5 days" → days: 5
+
+Inject the arithmetic into a Bash node -e command. Command template:
+```bash
+node -e "
+const d = new Date();
+<apply setMonth first: d.setMonth(d.getMonth() + N)>
+<apply setDate next: d.setDate(d.getDate() + N)>
+<apply setFullYear last: d.setFullYear(d.getFullYear() + N)>
+const yyyy = d.getFullYear();
+const mm = String(d.getMonth() + 1).padStart(2, '0');
+const dd = String(d.getDate()).padStart(2, '0');
+console.log(yyyy + '-' + mm + '-' + dd);
+"
+```
+
+Example for "in 2 months and 5 days":
+```bash
+node -e "const d=new Date();d.setMonth(d.getMonth()+2);d.setDate(d.getDate()+5);const y=d.getFullYear();const m=String(d.getMonth()+1).padStart(2,'0');const dd=String(d.getDate()).padStart(2,'0');console.log(y+'-'+m+'-'+dd)"
+```
+
+Example for "in 3 weeks":
+```bash
+node -e "const d=new Date();d.setDate(d.getDate()+21);const y=d.getFullYear();const m=String(d.getMonth()+1).padStart(2,'0');const dd=String(d.getDate()).padStart(2,'0');console.log(y+'-'+m+'-'+dd)"
+```
+
+CRITICAL: Always use local date component extraction (`getFullYear()`, `getMonth() + 1`, `getDate()`) with padding. NEVER use `toISOString()` — it returns UTC which can produce off-by-one dates for users in timezones ahead of UTC.
+
+If the resolved date is NaN or invalid (check by verifying the output matches YYYY-MM-DD format), print:
+```
+x Invalid date expression: <due_expression>. Use formats like "tomorrow", "next friday", "in 3 days", or YYYY-MM-DD.
+```
+Then stop the workflow. Do NOT fall back to today — the user must correct their date expression.
+
+If the date resolved successfully, store the output as `<due_date>`.
+</step>
+
+<step name="ensure-file">
+Check if `<storage_repo>/donna/follow-ups.md` exists. Use the Read tool to attempt reading it.
+
+If the file does not exist (Read tool returns an error), create it with the Write tool using this content:
+```markdown
+---
+created: <today>
+---
+
+## Follow-ups
+```
+Where `<today>` is today's date in YYYY-MM-DD format.
+
+If the file already exists, continue to the next step.
+</step>
+
+<step name="append-entry">
+Read `<storage_repo>/donna/follow-ups.md` with the Read tool.
+
+Append the follow-up entry on a new line at the end of the file:
+```
+- [ ] <description> | due: <due_date>
+```
+
+Write the updated file back with the Write tool.
+</step>
+
+<step name="git-commit">
+Run via Bash:
+```bash
+node ~/.donna/donna-tools.cjs commit "donna(follow-up): <description>" --files donna/follow-ups.md
+```
+</step>
+
+<step name="confirm">
+Print:
+```
+✓ Follow-up scheduled: <description> (due: <due_date>)
+```
+</step>