docs: plan activity worklog suggestions
This commit is contained in:
parent
74f14b4ffc
commit
e0d11c3b52
|
|
@ -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="<suggestionId>"`
|
||||||
|
|
||||||
|
- [ ] **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.
|
||||||
|
|
@ -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="<suggestionId>"`
|
||||||
|
|
||||||
|
## 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.
|
||||||
Loading…
Reference in New Issue