diff --git a/docs/superpowers/plans/2026-06-29-activity-worklog-suggestions.md b/docs/superpowers/plans/2026-06-29-activity-worklog-suggestions.md new file mode 100644 index 0000000..a814301 --- /dev/null +++ b/docs/superpowers/plans/2026-06-29-activity-worklog-suggestions.md @@ -0,0 +1,196 @@ +# Activity Worklog Suggestions Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add a minimal Activity reconstruction layer that renders and exposes worklog suggestions from recorded activity events. + +**Architecture:** Keep reconstruction inside `verstak.activity`. Generate suggestions from normalized stored events, render them in the Activity view, and expose them through a command-backed runtime contract for the future Journal plugin. + +**Tech Stack:** Official plugin browserless JavaScript bundle, Node smoke tests, JSON plugin manifest, Markdown docs. + +## Global Constraints + +- Do not move activity or journal logic into desktop core. +- Do not build the Journal plugin in this slice. +- Suggestions are derived from existing Activity events and are informational. +- Use TDD: update the activity smoke test first, run it red, then implement. +- Commit and push each affected repository after meaningful changes. + +--- + +### Task 1: Document The Slice + +**Files:** +- Create: `/home/mirivlad/git/verstak2/verstak-docs/docs/superpowers/specs/2026-06-29-activity-worklog-suggestions-design.md` +- Create: `/home/mirivlad/git/verstak2/verstak-docs/docs/superpowers/plans/2026-06-29-activity-worklog-suggestions.md` + +**Interfaces:** +- Produces: written contract for `verstak.activity.suggestWorklog`. + +- [ ] **Step 1: Write spec and plan** + +Write the design and this implementation plan. + +- [ ] **Step 2: Verify docs** + +Run: + +```bash +cd /home/mirivlad/git/verstak2/verstak-docs +git diff --check +``` + +Expected: exits 0. + +- [ ] **Step 3: Commit and push docs** + +Run: + +```bash +cd /home/mirivlad/git/verstak2/verstak-docs +git add docs/superpowers/specs/2026-06-29-activity-worklog-suggestions-design.md docs/superpowers/plans/2026-06-29-activity-worklog-suggestions.md +git commit -m "docs: plan activity worklog suggestions" +git push +``` + +Expected: docs `main` is clean and pushed. + +### Task 2: Activity Suggestions Runtime + +**Files:** +- Modify: `/home/mirivlad/git/verstak2/verstak-official-plugins/plugins/activity/plugin.json` +- Modify: `/home/mirivlad/git/verstak2/verstak-official-plugins/plugins/activity/frontend/src/index.js` +- Modify: `/home/mirivlad/git/verstak2/verstak-official-plugins/scripts/smoke-activity-plugin.js` + +**Interfaces:** +- Produces command: `verstak.activity.suggestWorklog(args?: { workspaceRootPath?: string }): Promise<{ suggestions: WorklogSuggestion[] }>` +- Produces DOM: `data-activity-section="worklog-suggestions"` and `data-worklog-suggestion=""` + +- [ ] **Step 1: Write the failing smoke assertions** + +Extend `scripts/smoke-activity-plugin.js` to read the Activity manifest, mock +`api.commands.register`, and assert that: + +- `commands.register` permission exists; +- command contribution `verstak.activity.suggestWorklog` exists; +- the command is registered after mount; +- Project events render a suggestion; +- executing the command returns a suggestion with `minutes`, `summary`, and + source `eventIds`; +- global Activity renders separate Project and ClientA suggestions; +- clear removes the rendered suggestion. + +- [ ] **Step 2: Run RED** + +Run: + +```bash +cd /home/mirivlad/git/verstak2/verstak-official-plugins +node scripts/smoke-activity-plugin.js +``` + +Expected: fails because `verstak.activity.suggestWorklog` is not registered. + +- [ ] **Step 3: Update manifest** + +Add `commands.register` to permissions and add: + +```json +{ + "id": "verstak.activity.suggestWorklog", + "title": "Suggest Worklog From Activity", + "handler": "verstak.activity.suggestWorklog" +} +``` + +under `contributes.commands`. + +- [ ] **Step 4: Implement suggestions** + +In `plugins/activity/frontend/src/index.js`: + +- define `WORKLOG_COMMAND_ID = 'verstak.activity.suggestWorklog'`; +- add `suggestions` state; +- derive suggestions from normalized events grouped by workspace/day; +- render a suggestions band above the activity list; +- register the command with `api.commands.register`; +- recompute suggestions after load, event refresh, and clear. + +- [ ] **Step 5: Run GREEN** + +Run: + +```bash +cd /home/mirivlad/git/verstak2/verstak-official-plugins +node scripts/smoke-activity-plugin.js +./scripts/check.sh +``` + +Expected: both commands exit 0. + +- [ ] **Step 6: Commit and push official plugin** + +Run: + +```bash +cd /home/mirivlad/git/verstak2/verstak-official-plugins +git add plugins/activity/plugin.json plugins/activity/frontend/src/index.js scripts/smoke-activity-plugin.js +git commit -m "feat: suggest worklogs from activity" +git push +``` + +Expected: official plugins `main` is clean and pushed. + +### Task 3: Mark Roadmap Progress + +**Files:** +- Modify: `/home/mirivlad/git/verstak2/verstak-docs/05_Official_Plugins.md` +- Modify: `/home/mirivlad/git/verstak2/verstak-docs/07_Full_Implementation_Roadmap.md` + +**Interfaces:** +- Consumes verified official plugin commit. +- Produces docs matching implemented behavior. + +- [ ] **Step 1: Update Activity status** + +Replace the sentence saying reconstruction/worklog suggestions are future work +with a sentence describing the implemented suggestion band and command. + +- [ ] **Step 2: Update roadmap** + +Change: + +```md +- implement activity reconstruction and worklog suggestions; +``` + +to: + +```md +- [x] implement activity reconstruction and worklog suggestions; +``` + +- [ ] **Step 3: Verify docs** + +Run: + +```bash +cd /home/mirivlad/git/verstak2/verstak-docs +git diff --check +rg -n "Reconstruction and worklog suggestions are still future work|implement activity reconstruction and worklog suggestions" 05_Official_Plugins.md 07_Full_Implementation_Roadmap.md +``` + +Expected: `git diff --check` exits 0. `rg` shows only the checked roadmap line. + +- [ ] **Step 4: Commit and push docs** + +Run: + +```bash +cd /home/mirivlad/git/verstak2/verstak-docs +git add 05_Official_Plugins.md 07_Full_Implementation_Roadmap.md +git commit -m "docs: mark activity worklog suggestions complete" +git push +``` + +Expected: docs `main` is clean and pushed. diff --git a/docs/superpowers/specs/2026-06-29-activity-worklog-suggestions-design.md b/docs/superpowers/specs/2026-06-29-activity-worklog-suggestions-design.md new file mode 100644 index 0000000..63cffcf --- /dev/null +++ b/docs/superpowers/specs/2026-06-29-activity-worklog-suggestions-design.md @@ -0,0 +1,99 @@ +# Activity Worklog Suggestions Design + +## Purpose + +`verstak.activity` already records public plugin events and displays scoped +activity streams. The next roadmap step is to turn that stream into a small, +useful reconstruction layer that can suggest worklog entries without making +Journal a core feature. + +## Scope + +This slice adds worklog suggestions to the official Activity plugin only. +It does not create the Journal plugin, reports, billing states, manual time +editing, or final worklog persistence. Those remain the next roadmap item. + +## Behavior + +- Activity reconstructs suggestions from the same normalized events it already + renders. +- Suggestions are scoped the same way as the Activity view: + - a workspace Activity view uses only that workspace stream; + - the global Activity view aggregates all streams and produces suggestions + per workspace/day. +- Events are grouped by workspace and calendar day using `occurredAt` or + `receivedAt`. +- Each group produces one suggestion with: + - stable `suggestionId`; + - `workspaceRootPath`; + - `date`; + - `title`; + - `summary`; + - `minutes`; + - source `eventIds`. +- Estimated time is conservative: + - one event: 15 minutes; + - multiple events: time span between first and last event, rounded up to + 15-minute increments; + - minimum 15 minutes, maximum 480 minutes. + +## Runtime Contract + +The Activity plugin contributes and registers this command: + +```text +verstak.activity.suggestWorklog +``` + +Arguments: + +```json +{ + "workspaceRootPath": "Project" +} +``` + +`workspaceRootPath` is optional. When omitted, the command returns suggestions +for all available activity streams. + +Result: + +```json +{ + "suggestions": [ + { + "suggestionId": "worklog:Project:2026-06-27", + "workspaceRootPath": "Project", + "date": "2026-06-27", + "title": "Project work on 2026-06-27", + "summary": "Example Article; Saved note", + "minutes": 30, + "eventIds": ["capture-1", "note-1"] + } + ] +} +``` + +If the command cannot read settings, it returns an empty suggestions array and +does not throw for normal UI consumption. + +## UI + +Activity shows a compact suggestions band above the event list when suggestions +exist. The band is informational only in this slice. It exposes stable DOM data +attributes for smoke tests and later Journal wiring: + +- `data-activity-section="worklog-suggestions"` +- `data-worklog-suggestion=""` + +## Testing + +`scripts/smoke-activity-plugin.js` must verify: + +- the manifest requests `commands.register`; +- the manifest declares `verstak.activity.suggestWorklog`; +- Activity registers the command when mounted; +- workspace Activity renders a worklog suggestion for multiple events; +- the command returns the same suggestion shape; +- global Activity groups suggestions by workspace and day; +- clearing Activity clears suggestions.