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