@pingvinen/donna-assistant 0.3.2 → 0.4.0

package/bin/donna-assistant

@@ -3,7 +3,9 @@
 
 const { run } = require("../src/installer.cjs");
 
-run().catch((err) => {
+const force = process.argv.includes("--force");
+
+run({ force }).catch((err) => {
     console.error(`\nInstallation failed: ${err.message}`);
     process.exit(1);
 });

package/package.json

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

package/src/installer.cjs

@@ -14,10 +14,12 @@ const providers = require("./providers/index.cjs");
  *
  * @param {object} [options]
  * @param {string} [options.homeDir] - Override home directory (for testing)
+ * @param {boolean} [options.force] - Force re-install even if version matches
  * @returns {Promise<void>}
  */
 async function run(options = {}) {
     const homeDir = options.homeDir || os.homedir();
+    const force = options.force || false;
     const donnaDir = path.join(homeDir, ".donna");
     const migrationsDir = path.join(__dirname, "..", "migrations");
     const workflowsSource = path.join(__dirname, "..", "workflows");
@@ -36,7 +38,7 @@ async function run(options = {}) {
     const lastMigration = current?.lastMigration || 0;
 
     // Check if already up to date
-    if (currentVersion === packageVersion) {
+    if (currentVersion === packageVersion && !force) {
         // Check for pending migrations too
         const pendingResults = migrator.runMigrations(migrationsDir, donnaDir, lastMigration);
         if (pendingResults.length === 0) {
@@ -74,7 +76,9 @@ async function run(options = {}) {
     if (detected.length > 0) {
         for (const provider of detected) {
             fs.cpSync(provider.stubSource, provider.stubTarget, { recursive: true });
-            output.success(`Copied donna:setup to ${provider.stubTarget}`);
+            output.success(
+                `Copied donna skills (setup, add-task, done, set-role, begin-the-day) to ${provider.stubTarget}`,
+            );
         }
     } else {
         output.info("No supported AI providers detected");
@@ -92,6 +96,7 @@ async function run(options = {}) {
     output.success(`Version ${packageVersion} installed`);
 
     // Final message
+    console.log("");
     output.info("Run /donna:setup in Claude Code to get started.");
 }
 

package/src/output.cjs

@@ -2,7 +2,7 @@
 
 function banner() {
     console.log("");
-    console.log("━━━ DONNA ━━━");
+    console.log("━━━ Donna ━━━");
     console.log("");
 }
 
@@ -23,7 +23,7 @@ function upgradeHeader(from, to) {
 }
 
 function migrationLine(desc) {
-    console.log(`    \u2022 ${desc}`);
+    console.log(`  \u2713 ${desc}`);
 }
 
 module.exports = { banner, success, fail, info, upgradeHeader, migrationLine };

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

@@ -0,0 +1,17 @@
+---
+name: donna:add-task
+description: Capture a task to today's daily journal
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Run the Donna add-task workflow.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/add-task.md
+</execution_context>

package/stubs/claude-code/donna/begin-the-day.md

@@ -0,0 +1,16 @@
+---
+name: donna:begin-the-day
+description: Start your day — carry forward open tasks, surface recurring tasks due today, get your daily brief
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Run the Donna begin-the-day workflow.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/begin-the-day.md
+</execution_context>

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

@@ -0,0 +1,17 @@
+---
+name: donna:done
+description: Mark tasks as complete in today's daily journal
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Run the Donna done workflow.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/done.md
+</execution_context>

package/stubs/claude-code/donna/set-role.md

@@ -0,0 +1,18 @@
+---
+name: donna:set-role
+description: Define your job role, research recurring tasks, and build your daily rhythm
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+  - WebSearch
+---
+
+<objective>
+Run the Donna set-role workflow. This command guides the user through defining their job role: collecting role details, researching recurring tasks and tools, presenting findings for approval, and persisting everything to the storage repo.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/set-role.md
+</execution_context>

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

@@ -1,13 +1,15 @@
 ---
 name: donna:setup
-description: Set up Donna assistant for this machine
+description: Set up Donna — configure storage repo, initialize file structure, create bootstrap config
 allowed-tools:
   - Read
+  - Write
   - Bash
+  - AskUserQuestion
 ---
 
 <objective>
-Run the Donna setup workflow. This command verifies that Donna is installed correctly by loading the setup workflow from the shared runtime directory and displaying the current installation status.
+Run the Donna setup workflow. This command guides the user through configuring Donna: setting the storage repo path, initializing the file structure, and writing the bootstrap config at ~/.config/donna/config.md.
 </objective>
 
 <execution_context>

package/workflows/add-task.md

@@ -0,0 +1,97 @@
+# Donna Add-Task Workflow
+
+<objective>
+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="get-description">
+The task description is provided as the argument to this command (e.g., `/donna:add-task buy milk`).
+
+If no argument was provided, use AskUserQuestion to ask:
+```
+What task would you like to add?
+```
+
+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:
+```bash
+mkdir -p <storage_repo>/<daily_folder>
+```
+
+If the daily file does not exist, create it with the Write tool using this content (substituting the actual date):
+```markdown
+---
+date: <date>
+---
+
+## Tasks
+```
+</step>
+
+<step name="append-task">
+Read the daily file with the Read tool.
+
+Append `- [ ] <description>` on a new line at the end of the file.
+
+Write the updated file 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(add-task): <description>"
+```
+
+If `auto_push` is true in config, also run:
+```bash
+git -C <storage_repo> push
+```
+</step>
+
+<step name="confirm">
+Print:
+```
+✓ Added: <description>
+```
+
+Also print the path to the daily file: `<storage_repo>/<daily_folder>/<date>.md`
+</step>

package/workflows/begin-the-day.md

@@ -0,0 +1,198 @@
+# Donna Begin-the-Day Workflow
+
+<objective>
+Carry forward open tasks from the previous day, surface recurring tasks due today, deduplicate, and present a concise daily brief.
+</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="get-today">
+Run via Bash to get today's date, day-of-week, and day-of-month:
+```bash
+date +%Y-%m-%d
+```
+Store the result as `<today>`.
+
+```bash
+date +%A
+```
+Store the result as `<day_of_week>` (e.g., "Monday").
+
+```bash
+date +%-d
+```
+Store the result as `<day_of_month>` (e.g., "1" for the 1st).
+
+Construct the daily file path: `<storage_repo>/<daily_folder>/<today>.md`.
+</step>
+
+<step name="find-previous-file">
+Find the most recent previous daily file. Run via Bash:
+```bash
+TODAY=$(date +%Y-%m-%d)
+DAILY_DIR="<storage_repo>/<daily_folder>"
+PREV_FILE=$(ls "$DAILY_DIR"/*.md 2>/dev/null | sort | grep -v "$TODAY" | tail -1)
+echo "${PREV_FILE:-NONE}"
+```
+
+CRITICAL: The `grep -v "$TODAY"` exclusion prevents a self-referencing loop. If the result is "NONE", there is no previous file — skip the carry-forward step. This reads a directory listing only (satisfies STORE-03), then reads at most ONE previous file.
+</step>
+
+<step name="carry-forward">
+If the previous file result is "NONE", set `<carried_tasks>` to an empty list and continue to the next step.
+
+If a previous file was found, read it with the Read tool. Extract all open tasks — every line matching the pattern `- [ ] <description>`. For each open task:
+- If the description ends with ` (N times)` (where N is any integer): extract N, increment to N+1, replace the suffix with ` (N+1 times)`. For example: `- [ ] Follow up with Sarah (2 times)` becomes `- [ ] Follow up with Sarah (3 times)`.
+- If the description has no such suffix: append ` (1 times)`. For example: `- [ ] Follow up with Sarah` becomes `- [ ] Follow up with Sarah (1 times)`.
+
+Store the resulting list as `<carried_tasks>`.
+
+Do NOT modify the previous file — it is a historical record and must remain unchanged.
+</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).
+
+Parse each line matching the pattern `- <description>: <interval>`. For "every other" intervals, also parse the `| last_run: YYYY-MM-DD` suffix.
+
+For each task, determine if it is due today using this logic:
+- `every <DayName>` (e.g., "every Monday"): due if `<day_of_week>` matches DayName
+- `every weekday`: due if `<day_of_week>` is Monday, Tuesday, Wednesday, Thursday, or Friday
+- `first <DayName> of month`: due if `<day_of_week>` matches DayName AND `<day_of_month>` <= 7
+- `every other <DayName>` with `| last_run: YYYY-MM-DD`: due if `<day_of_week>` matches DayName AND days since last_run >= 14. Use macOS-compatible date arithmetic:
+  ```bash
+  LAST_RUN="<last_run_date>"
+  last_run_epoch=$(date -j -f "%Y-%m-%d" "$LAST_RUN" "+%s")
+  today_epoch=$(date +%s)
+  days=$(( (today_epoch - last_run_epoch) / 86400 ))
+  echo "$days"
+  ```
+
+Store the descriptions of all due tasks as `<recurring_tasks>` (just the description text, without the interval suffix).
+</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>`.
+
+If the file does not exist, `<existing_tasks>` is an empty list.
+</step>
+
+<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.
+
+1. Start with `<existing_tasks>` — both open and closed tasks take priority. Add them all to the final list.
+
+2. Add `<carried_tasks>` — for each carried task, normalize its description and check whether any task already in the final list (from existing_tasks) normalizes to the same value. If no match, add it. If a match exists, skip it.
+
+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.
+
+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: 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>`.
+</step>
+
+<step name="write-daily-file">
+Ensure the daily folder exists:
+```bash
+mkdir -p <storage_repo>/<daily_folder>
+```
+
+Write today's daily file with the Write tool. Content format:
+```markdown
+---
+date: <today>
+---
+
+## Tasks
+<existing tasks, preserving their original order and open/closed state>
+<carried-forward tasks not already in existing>
+<recurring tasks not already in existing>
+```
+
+Tasks are written in this order: existing tasks first (preserving their original order and state), then carried-forward tasks, then recurring tasks.
+</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`.
+
+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.
+
+If no "every other" recurring tasks were added, skip this step.
+</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(begin-the-day): daily brief for <today>"
+```
+
+If `auto_push` is true in config, also run:
+```bash
+git -C <storage_repo> push
+```
+</step>
+
+<step name="print-brief">
+Print the daily brief to the terminal:
+```
+══════════════════════════════════════
+ DONNA — Daily Brief for <today>
+══════════════════════════════════════
+```
+
+If there are carried-forward tasks (tasks from `<carried_tasks>` that were added to the final list), print:
+```
+## Carried Forward
+- [ ] Follow up with Sarah (3 times)
+- [ ] Review design doc (1 times)
+```
+
+If there are recurring tasks due today (tasks from `<recurring_tasks>` that were added to the final list), print:
+```
+## Due Today
+- [ ] Check team Slack
+- [ ] Review sprint backlog
+```
+
+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:
+```
+No tasks for today — enjoy your day!
+```
+in place of both sections.
+</step>

package/workflows/done.md

@@ -0,0 +1,126 @@
+# Donna Done Workflow
+
+<objective>
+Mark one or more tasks as complete in today's daily journal file and commit the change 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="find-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`.
+
+If the file does not exist, print:
+```
+✗ No daily file for today. Add a task first with /donna:add-task
+```
+Stop.
+</step>
+
+<step name="read-tasks">
+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.
+
+If no open tasks are found, print:
+```
+✓ All tasks already complete for today!
+```
+Stop.
+</step>
+
+<step name="select-tasks">
+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.
+
+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:
+```
+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.
+
+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:
+```
+Which task(s) did you finish? (or type something you did that's not on the list)
+```
+
+If the user submits without selecting anything or typing anything, print:
+```
+Nothing selected — nothing to do.
+```
+Stop.
+
+If the user selects from the list, store the selected task(s) as `<completed_tasks>`.
+
+If the user types free text instead of selecting an option, treat it as a task that was already done: append `- [x] <typed text>` to the daily file (creating it if needed, same as add-task's ensure-daily-file step). Store it as `<completed_tasks>` so the git-commit and confirm steps handle it normally.
+</step>
+
+<step name="mark-complete">
+For each task in `<completed_tasks>`, replace `- [ ] <description>` with `- [x] <description>` in the daily file.
+
+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).
+
+Write the updated file 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.
+
+If one task was completed, run:
+```bash
+git -C <storage_repo> commit -m "donna(done): <description>"
+```
+
+If multiple tasks were completed, run:
+```bash
+git -C <storage_repo> commit -m "donna(done): <N> tasks completed"
+```
+
+If `auto_push` is true in config, also run:
+```bash
+git -C <storage_repo> push
+```
+</step>
+
+<step name="confirm">
+For each completed task, print:
+```
+✓ Done: <description>
+```
+</step>

package/workflows/set-role.md

@@ -0,0 +1,247 @@
+# Donna Set-Role Workflow
+
+<objective>
+Define the user's job role, research recurring tasks and tools for that role using WebSearch, present findings for approval, and persist role definition and recurring tasks to 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` and `auto_push` (default: false) fields from the YAML frontmatter.
+</step>
+
+<step name="check-existing-role">
+Run via Bash:
+```bash
+test -f <storage_repo>/role.md && echo "exists" || echo "missing"
+```
+
+If the output is "exists", proceed to the rerun-menu step.
+If the output is "missing", proceed to the ask-role step.
+</step>
+
+<step name="rerun-menu">
+Use AskUserQuestion to present the re-run menu:
+
+```
+A role definition already exists. What would you like to do?
+
+1. Something got messed up — start fresh (reset)
+2. Got promoted or changed roles — update (diff-update)
+3. Just want to refresh the research — re-research current role
+4. Cancel
+```
+
+- On "reset" (option 1): proceed to ask-role (fresh start, will overwrite role.md and recurring.md).
+- On "diff-update" (option 2): read current role.md with the Read tool, proceed to ask-role but pre-fill with current values and note this is an update. After research, show delta (added/removed recurring tasks vs current recurring.md). Preserve any manually-added recurring tasks (tasks in recurring.md not in the research suggestions).
+- On "re-research" (option 3): read current role.md with the Read tool to get the existing role data, skip to the research step.
+- On "Cancel" (option 4): print "Cancelled." and stop.
+</step>
+
+<step name="ask-role">
+Stage 1: Collect role details interactively.
+
+Use AskUserQuestion to ask the following questions in sequence:
+
+1. "What is your job title?" — store as `<job_title>`.
+2. "How large is your team? How many direct reports do you have? (e.g. team of 8, 3 direct reports)" — store as `<team_info>`.
+3. "What are 2–3 things you focus on most in your role? (e.g. sprint planning, hiring, technical architecture)" — store as `<key_responsibilities>`.
+
+Parse `<team_info>` into `<team_size>` (total team) and `<direct_reports>` (direct reports count) as best you can.
+Parse `<key_responsibilities>` into an array of 2–3 items.
+
+Store all values for use in subsequent steps.
+</step>
+
+<step name="research">
+Stage 2: Research the role using WebSearch.
+
+Construct targeted queries using ALL collected data from Stage 1. Run 2–3 focused searches:
+
+1. `<job_title> daily recurring tasks responsibilities`
+2. `<job_title> <key_responsibilities[0]> common tools workflows`
+3. (optional) `<job_title> weekly monthly recurring tasks best practices`
+
+Use WebSearch for each query. Synthesize findings into a structured summary matching the role-research.md format:
+
+- **Daily tasks**: recurring things done every workday
+- **Weekly tasks**: recurring things done each week
+- **Monthly tasks**: recurring things done each month
+- **Tool suggestions**: tools commonly used for this role (with brief descriptions)
+
+Tailor suggestions to the specific responsibilities the user described — avoid generic results that don't reflect their actual focus areas.
+</step>
+
+<step name="present-summary">
+Print a concise summary of research findings (2–3 sentences covering the key patterns found).
+
+Then use AskUserQuestion:
+```
+Which category would you like to review?
+1. Recurring tasks
+2. Tool suggestions
+3. Both
+4. Skip (accept all recurring tasks as-is)
+```
+
+Store the choice for subsequent steps.
+</step>
+
+<step name="approve-recurring">
+If the user chose to review recurring tasks (options 1 or 3):
+
+Display each category in turn (daily, weekly, monthly) and use AskUserQuestion for each task:
+```
+[Daily] Check team Slack and unblock blockers
+→ Approve, reject, or modify? (approve / reject / [type modification)
+```
+
+Interpret modifications naturally:
+- "make this biweekly" → change interval to "every other week"
+- "every other Monday" → interval becomes "every other Monday"
+- "first Monday of the month" → interval becomes "first Monday of month"
+
+After reviewing all categories, ask: "Would you like to add any recurring tasks I missed?" Accept free-text additions.
+
+Collect the final approved list with their intervals.
+
+If the user chose to skip (option 4): accept all suggested recurring tasks with their default intervals.
+</step>
+
+<step name="approve-tools">
+If the user chose to review tool suggestions (options 2 or 3):
+
+Display each tool suggestion and use AskUserQuestion:
+```
+Tool: Jira (sprint management)
+→ Note this for future configuration? (yes / no)
+```
+
+For noted tools, print:
+```
+✓ Noted: <tool name>. Run /donna:add-tool to configure <tool name> (available in a future update).
+```
+
+Do NOT create tools.md or configure anything — only note the user's interest.
+</step>
+
+<step name="save-role">
+Write `<storage_repo>/role.md` with the Write tool.
+
+Use this format (substituting actual values):
+```markdown
+---
+job_title: <job_title>
+team_size: <team_size>
+direct_reports: <direct_reports>
+key_responsibilities:
+  - <responsibility 1>
+  - <responsibility 2>
+updated: <today's date in YYYY-MM-DD format>
+---
+
+# Role: <job_title>
+
+[Write a 2–3 sentence prose summary of the role as described by the user, incorporating their key responsibilities and team context.]
+```
+
+Write `<storage_repo>/role-research.md` with the Write tool.
+
+Use this format:
+```markdown
+---
+researched: <today's date in YYYY-MM-DD format>
+role: <job_title>
+---
+
+# Role Research: <job_title>
+
+## Summary
+[2–3 sentence overview of what the research found for this role]
+
+## Recurring Task Suggestions
+
+### Daily
+[List daily task suggestions from research]
+
+### Weekly
+[List weekly task suggestions from research]
+
+### Monthly
+[List monthly task suggestions from research]
+
+## Tool Suggestions
+[List tool suggestions with brief descriptions]
+
+## Notes
+[Any additional context from research relevant to this specific role]
+```
+</step>
+
+<step name="save-recurring">
+Write `<storage_repo>/recurring.md` with the Write tool.
+
+Format: one approved recurring task per line as `- Task description: interval`.
+For "every other" intervals (biweekly, every other Monday, etc.), append ` | last_run: <today's date>` suffix.
+
+Use this format:
+```markdown
+---
+# Recurring tasks — managed by donna:set-role
+---
+
+- <task 1>: <interval 1>
+- <task 2>: <interval 2>
+- <task 3>: <interval 3> | last_run: <today's date>
+```
+
+If this is a diff-update (user chose option 2 in rerun-menu):
+1. Read the existing `<storage_repo>/recurring.md` with the Read tool.
+2. Identify manually-added tasks: tasks in recurring.md that were NOT in the research suggestions.
+3. Merge: keep manually-added tasks, add new approved tasks, remove tasks the user rejected.
+4. Write the merged result.
+</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(set-role): define role as <job_title>"
+```
+
+If `auto_push` is true in config, also run:
+```bash
+git -C <storage_repo> push
+```
+</step>
+
+<step name="confirm">
+Print:
+```
+✓ Role defined: <job_title>
+✓ <N> recurring tasks saved to recurring.md
+✓ Research saved to role-research.md
+```
+
+If any tools were noted during approve-tools, remind:
+```
+→ Run /donna:add-tool to configure your noted tools (available in a future update).
+```
+</step>

package/workflows/setup.md

@@ -1,42 +1,184 @@
 # Donna Setup Workflow
 
 <objective>
-Display the Donna installation status and confirm the stub-to-workflow pipeline is working.
+Guide the user through configuring Donna: set the storage repo path, initialize the file structure, and write the bootstrap config at ~/.config/donna/config.md.
 </objective>
 
 <step name="banner">
-Print the DONNA banner:
+Print the Donna banner:
 ```
-━━━ DONNA ▸ Setup ━━━
+━━━ Donna ▸ Setup ━━━
 ```
 </step>
 
-<step name="version">
-Read `~/.donna/version.md` and display the installed version. If the file exists, show:
+<step name="check-existing-config">
+Read `~/.config/donna/config.md`.
+
+If the file exists, proceed to the re-run menu (step: rerun-menu).
+If the file does not exist, proceed to first-run setup (step: ask-storage-path).
+</step>
+
+<step name="rerun-menu">
+An existing Donna configuration was found. Use AskUserQuestion to present the user with this menu:
+
+```
+Donna is already configured. What would you like to do?
+
+1. Change storage repo path
+2. View current config
+3. Reset (start over — deletes config and re-runs full setup)
+4. Cancel
+```
+
+Handle each option:
+
+- **Option 1:** Ask the user for the new storage repo path using AskUserQuestion. Validate and expand the path (run `echo <path>` via Bash to expand ~). Update `~/.config/donna/config.md` with the new storage_repo value. Print `✓ Storage repo updated.` then print the summary (step: summary).
+
+- **Option 2:** Display the contents of `~/.config/donna/config.md`. Then stop.
+
+- **Option 3:** Run `rm ~/.config/donna/config.md` via Bash to delete the config. Proceed to first-run setup (step: ask-storage-path).
+
+- **Option 4:** Print `Setup cancelled.` and stop.
+</step>
+
+<step name="ask-storage-path">
+Use AskUserQuestion to ask the user:
+
+```
+Where is your Donna storage repo?
+
+This is a local git repository where Donna stores your daily journal, tasks, and configuration. You can point to an existing git repo, an empty directory (Donna will initialize it), or a path that doesn't exist yet (Donna will create it).
+
+Enter the path (e.g. ~/Documents/donna-notes):
+```
+
+Wait for the user's response. Store the path as `<storage_path>`.
+</step>
+
+<step name="expand-and-validate-path">
+Expand the path provided by the user:
+
+Run via Bash:
+```bash
+echo <storage_path>
+```
+
+Use the expanded absolute path for all subsequent steps. Store as `<repo>`.
+
+Then check the path status:
+
+- If `<repo>` is an existing git repo (test: `git -C <repo> rev-parse --is-inside-work-tree 2>/dev/null`): use it as-is. Print `✓ Using existing git repo at <repo>`.
+
+- If `<repo>` exists as a directory but is not a git repo: run `git -C <repo> init`. Print `✓ Initialized git repo at <repo>`.
+
+- If `<repo>` does not exist: run `mkdir -p <repo>` then `git -C <repo> init`. Print `✓ Created and initialized git repo at <repo>`.
+</step>
+
+<step name="detect-daily-folder">
+Determine where daily files should live.
+
+**If `<repo>/.obsidian/daily-notes.json` exists:**
+Read it. If it has a `folder` field, use that value as `<daily_folder>`. Print:
+```
+✓ Found Obsidian daily notes folder: <daily_folder>
 ```
-Version: {version}
-Installed: {installed date}
-Last updated: {updated date}
+
+**If `<repo>/.obsidian/` exists but `.obsidian/daily-notes.json` does not exist or has no `folder` field:**
+Set `<daily_folder>` to `daily`. Write `<repo>/.obsidian/daily-notes.json` with:
+```json
+{
+  "folder": "daily"
+}
+```
+Print:
 ```
-If the file does not exist, show:
+✓ Configured Obsidian daily notes to use daily/
 ```
-No version file found. Donna may not be installed correctly.
-Try running: npx @pingvinen/donna-assistant
+
+**If `<repo>/.obsidian/` does not exist:**
+Set `<daily_folder>` to `daily`. Print:
+```
+✓ Using daily/ for daily files
 ```
 </step>
 
-<step name="status">
-Print the following message:
+<step name="create-storage-structure">
+Create the daily directory:
+
+Run via Bash:
+```bash
+mkdir -p <repo>/<daily_folder>
 ```
-This is a stub -- real setup coming in Phase 2.
+
+Print:
+```
+✓ Created <daily_folder>/ directory
 ```
 </step>
 
-<step name="next">
-Print next steps:
+<step name="write-bootstrap-config">
+Create the config directory if it does not exist:
+
+Run via Bash:
+```bash
+mkdir -p ~/.config/donna
 ```
+
+Write `~/.config/donna/config.md` with the following content (substituting the actual expanded path for `<repo>`):
+
+```markdown
+---
+storage_repo: <repo>
+daily_folder: <daily_folder>
+auto_push: false
+---
+
+# Donna Configuration
+
+This file is managed by `/donna:setup`. All Donna skills read this file to find your storage repo.
+```
+
+Print:
+```
+✓ Wrote config at ~/.config/donna/config.md
+```
+</step>
+
+<step name="initial-commit">
+Check whether there is anything to commit:
+
+Run via Bash:
+```bash
+git -C <repo> status --porcelain
+```
+
+If the output is non-empty (there are changes to commit):
+
+Run:
+```bash
+git -C <repo> add -A
+git -C <repo> commit -m "donna(setup): initialize storage"
+```
+
+Print:
+```
+✓ Committed initial structure
+```
+
+If the output is empty (nothing to commit), skip the commit and continue.
+</step>
+
+<step name="summary">
+Print the completion summary:
+
+```
+✓ Donna is ready!
+
+Storage repo: <repo>
+Config: ~/.config/donna/config.md
+
 Next steps:
-  - Run /donna:setup again after upgrading to see new features
-  - Phase 2 will add role configuration, storage setup, and more
+  - Run /donna:add-task to capture your first task
+  - Run /donna:done to mark tasks complete
 ```
 </step>