docs: plan journal worklog plugin
This commit is contained in:
parent
a6916d83fb
commit
b61bc94a05
|
|
@ -0,0 +1,178 @@
|
|||
# Journal Worklog Plugin 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:** Create a baseline `verstak.journal` plugin that stores worklog entries and imports Activity worklog suggestions.
|
||||
|
||||
**Architecture:** Implement Journal as a plain official frontend plugin. Store entries in plugin settings by workspace key, render a workspace/global Journal view, and consume Activity suggestions through `api.commands.executeFor`.
|
||||
|
||||
**Tech Stack:** Official plugin JSON manifest, browserless JavaScript bundle, Node smoke test, Markdown docs.
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- Journal/worklog remains plugin functionality, not desktop core.
|
||||
- Do not build billing reports or invoice export in this slice.
|
||||
- Import from Activity must degrade cleanly when Activity is unavailable.
|
||||
- Use TDD: write and run a failing smoke test before creating the plugin.
|
||||
- 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-journal-worklog-plugin-design.md`
|
||||
- Create: `/home/mirivlad/git/verstak2/verstak-docs/docs/superpowers/plans/2026-06-29-journal-worklog-plugin.md`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces a written contract for `verstak.journal`.
|
||||
|
||||
- [ ] **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-journal-worklog-plugin-design.md docs/superpowers/plans/2026-06-29-journal-worklog-plugin.md
|
||||
git commit -m "docs: plan journal worklog plugin"
|
||||
git push
|
||||
```
|
||||
|
||||
Expected: docs `main` is clean and pushed.
|
||||
|
||||
### Task 2: Journal Plugin
|
||||
|
||||
**Files:**
|
||||
- Create: `/home/mirivlad/git/verstak2/verstak-official-plugins/plugins/journal/plugin.json`
|
||||
- Create: `/home/mirivlad/git/verstak2/verstak-official-plugins/plugins/journal/frontend/src/index.js`
|
||||
- Create: `/home/mirivlad/git/verstak2/verstak-official-plugins/scripts/smoke-journal-plugin.js`
|
||||
- Modify: `/home/mirivlad/git/verstak2/verstak-official-plugins/scripts/check.sh`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces plugin id `verstak.journal`.
|
||||
- Produces component `JournalView`.
|
||||
- Consumes `api.commands.executeFor('verstak.activity', 'verstak.activity.suggestWorklog', args)`.
|
||||
|
||||
- [ ] **Step 1: Write the failing smoke test**
|
||||
|
||||
Create `scripts/smoke-journal-plugin.js` and assert manifest identity,
|
||||
mounting, manual entry storage, Activity import, duplicate prevention, and
|
||||
global aggregation.
|
||||
|
||||
- [ ] **Step 2: Run RED**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cd /home/mirivlad/git/verstak2/verstak-official-plugins
|
||||
node scripts/smoke-journal-plugin.js
|
||||
```
|
||||
|
||||
Expected: fails because the Journal manifest and frontend entry do not exist.
|
||||
|
||||
- [ ] **Step 3: Add manifest and frontend**
|
||||
|
||||
Create `plugins/journal/plugin.json` with `provides` of `worklog`, `journal`,
|
||||
and `report.worklog`, optional dependency `activity.reconstruction`, and
|
||||
workspace/sidebar UI contributions. Create `JournalView` that stores entries
|
||||
under `worklog:workspace:<encoded workspace root>`.
|
||||
|
||||
- [ ] **Step 4: Wire check script**
|
||||
|
||||
Add `node "$ROOT/scripts/smoke-journal-plugin.js"` to the frontend smoke
|
||||
section in `scripts/check.sh`.
|
||||
|
||||
- [ ] **Step 5: Run GREEN**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cd /home/mirivlad/git/verstak2/verstak-official-plugins
|
||||
node scripts/smoke-journal-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/journal scripts/smoke-journal-plugin.js scripts/check.sh
|
||||
git commit -m "feat: add journal worklog plugin"
|
||||
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 Journal plugin commit.
|
||||
- Produces docs matching implemented behavior.
|
||||
|
||||
- [ ] **Step 1: Update Journal status**
|
||||
|
||||
Add a current status sentence describing the baseline Journal plugin, manual
|
||||
worklog entries, and Activity suggestion import.
|
||||
|
||||
- [ ] **Step 2: Update roadmap**
|
||||
|
||||
Change:
|
||||
|
||||
```md
|
||||
- implement journal/worklog plugin that can consume activity suggestions.
|
||||
```
|
||||
|
||||
to:
|
||||
|
||||
```md
|
||||
- [x] implement journal/worklog plugin that can consume activity suggestions.
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Verify docs**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cd /home/mirivlad/git/verstak2/verstak-docs
|
||||
git diff --check
|
||||
rg -n "implement journal/worklog plugin that can consume activity suggestions|baseline `verstak.journal`" 05_Official_Plugins.md 07_Full_Implementation_Roadmap.md
|
||||
```
|
||||
|
||||
Expected: `git diff --check` exits 0 and `rg` shows the checked roadmap line
|
||||
and Journal status.
|
||||
|
||||
- [ ] **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 journal worklog plugin complete"
|
||||
git push
|
||||
```
|
||||
|
||||
Expected: docs `main` is clean and pushed.
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
# Journal Worklog Plugin Design
|
||||
|
||||
## Purpose
|
||||
|
||||
Add the first official Journal plugin as a replaceable plugin, not a desktop
|
||||
core feature. It must give users a visible worklog surface and consume Activity
|
||||
worklog suggestions through the command runtime added in
|
||||
`verstak.activity.suggestWorklog`.
|
||||
|
||||
## Scope
|
||||
|
||||
This slice creates `verstak.journal` with workspace-scoped worklog storage,
|
||||
manual entry creation, and one-click import from Activity suggestions.
|
||||
It does not implement billing reports, invoice export, timers, sync-specific
|
||||
conflict handling, or cross-workspace report aggregation.
|
||||
|
||||
## Behavior
|
||||
|
||||
- Journal appears as both a sidebar view and a workspace item.
|
||||
- In a workspace, entries are stored under a workspace settings key.
|
||||
- In the global view, Journal aggregates entries from every workspace key.
|
||||
- A manual entry contains:
|
||||
- `entryId`;
|
||||
- `workspaceRootPath`;
|
||||
- `date`;
|
||||
- `title`;
|
||||
- `summary`;
|
||||
- `minutes`;
|
||||
- `billable`;
|
||||
- optional `sourceSuggestionId`.
|
||||
- Importing Activity suggestions calls:
|
||||
|
||||
```text
|
||||
api.commands.executeFor(
|
||||
'verstak.activity',
|
||||
'verstak.activity.suggestWorklog',
|
||||
{ workspaceRootPath }
|
||||
)
|
||||
```
|
||||
|
||||
- Imported suggestions become non-billable entries by default.
|
||||
- Import is idempotent by `sourceSuggestionId`: importing the same Activity
|
||||
suggestion twice does not create duplicates.
|
||||
- If Activity is unavailable, Journal stays usable for manual entries and shows
|
||||
a status message.
|
||||
|
||||
## Storage
|
||||
|
||||
Workspace entries use settings keys:
|
||||
|
||||
```text
|
||||
worklog:workspace:<encoded workspace root>
|
||||
```
|
||||
|
||||
Global aggregation reads all settings keys with the `worklog:workspace:`
|
||||
prefix.
|
||||
|
||||
## Testing
|
||||
|
||||
`scripts/smoke-journal-plugin.js` must verify:
|
||||
|
||||
- manifest identity, capabilities, optional Activity dependency, and UI
|
||||
contributions;
|
||||
- the Journal view mounts;
|
||||
- manual entry creation stores and renders an entry;
|
||||
- Activity import calls the command runtime and stores suggestions as entries;
|
||||
- importing the same suggestion twice does not duplicate entries;
|
||||
- global Journal aggregates workspace entries.
|
||||
Loading…
Reference in New Issue