opencode-worklog 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luke Garceau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+```
+ ██╗    ██╗ ██████╗ ██████╗ ██╗  ██╗██╗      ██████╗  ██████╗ 
+ ██║    ██║██╔═══██╗██╔══██╗██║ ██╔╝██║     ██╔═══██╗██╔════╝ 
+ ██║ █╗ ██║██║   ██║██████╔╝█████╔╝ ██║     ██║   ██║██║  ███╗
+ ██║███╗██║██║   ██║██╔══██╗██╔═██╗ ██║     ██║   ██║██║   ██║
+ ╚███╔███╔╝╚██████╔╝██║  ██║██║  ██╗███████╗╚██████╔╝╚██████╔╝
+  ╚══╝╚══╝  ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝ ╚═════╝  ╚═════╝ 
+```
+
+<div align="center">
+
+**Cross-session work management for AI agents. Your todos survive. Your decisions persist. Your context comes back.**
+
+[![npm](https://img.shields.io/npm/v/opencode-worklog)](https://www.npmjs.com/package/opencode-worklog)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![works with opencode](https://img.shields.io/badge/works%20with-opencode-black)](https://opencode.ai)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![runtime: bun](https://img.shields.io/badge/runtime-bun-fbf0df?logo=bun&logoColor=black)](https://bun.sh)
+
+</div>
+
+---
+
+## The problem
+
+OpenCode sessions are stateless. Every context compaction or restart wipes the agent's working memory — todos vanish, blockers disappear, half-finished decisions evaporate. You're left re-explaining context that was perfectly documented ten minutes ago.
+
+`opencode-worklog` fixes this. It persists todos, blockers, and decisions to disk, then automatically injects them back into context at compaction time. Work in progress survives session resets.
+
+---
+
+## What it does
+
+An OpenCode plugin (`index.ts`) that hooks into two lifecycle events:
+
+1. **On session start** — bootstraps the `.worklog/` directory structure in the project root (idempotent; safe to run repeatedly)
+2. **On session start** — auto-installs 6 skills to `.opencode/skills/` (skips any already present)
+3. **On context compaction** — reads open todos and active blockers from disk, injects them into the compaction payload so they land in the next session's context
+
+---
+
+## How it works
+
+```
+Session Start
+     │
+     ├──► Bootstrap .worklog/ directory structure
+     │
+     └──► Auto-install skills to .opencode/skills/
+                │
+                ▼
+         Inject system prompt:
+         "use /worklog, /worklog-todo, /worklog-decide…"
+                │
+                ▼
+          [ work happens ]
+                │
+                ▼
+     Context Compaction
+                │
+                └──► Read todos.json + blockers.md
+                          │
+                          ▼
+                   Inject into compaction payload
+                          │
+                          ▼
+                  Open work survives reset ✓
+```
+
+---
+
+## Install
+
+Add to `opencode.json` in your project root:
+
+```json
+{
+  "plugins": ["opencode-worklog"]
+}
+```
+
+That's it. On the next session start the plugin bootstraps `.worklog/` and installs the skills automatically. No further configuration needed.
+
+### Local / development
+
+```json
+{
+  "plugins": ["file:../opencode-worklog"]
+}
+```
+
+> **Peer dependency:** `@opencode-ai/plugin`  
+> **Runtime:** Bun (OpenCode's native runtime)
+
+---
+
+## Skills reference
+
+Six skills are installed to `.opencode/skills/` automatically. Invoke them by slash command or by describing what you want to the agent.
+
+| Skill | Triggers | Purpose |
+|---|---|---|
+| `worklog` | `/worklog` · `/worklog checkpoint` · `/worklog end` | Session dashboard, mid-session checkpoint, close-out summary |
+| `worklog-todo` | `/worklog-todo add <title>` · `list` · `done <id>` · `drop <id>` | Cross-session todo list backed by `.worklog/todos.json` |
+| `worklog-archive` | `/worklog-archive` | Move done/dropped todos to `todos.done.json` |
+| `worklog-blocker` | `/worklog-blocker add <title>` · `resolve <id>` | Record and resolve blockers and open questions |
+| `worklog-decide` | `/worklog-decide` | Lightweight ADR appended to `.worklog/decisions.md` |
+| `worklog-docs` | `/worklog-docs` · `new adr` · `new report` · `new research` | Full ADR, formal report, and research note management |
+
+---
+
+## `.worklog/` layout
+
+```
+.worklog/
+├── todos.json          ← active todos (JSON array)
+├── todos.done.json     ← archived done/dropped todos
+├── blockers.md         ← open questions and blockers
+├── decisions.md        ← lightweight ADRs (ADR-001…)
+├── sessions/           ← daily session files (YYYY-MM-DD.md)
+├── adrs/               ← pre-decision technical research
+├── reports/            ← formal investigation reports
+└── research/           ← quick audit notes
+
+docs/
+└── adr-NNN-*.md        ← full formal ADRs (committed, permanent)
+```
+
+---
+
+## Gitignore recommendations
+
+```gitignore
+# Session files are noisy — safe to ignore
+.worklog/sessions/
+
+# Auto-installed skills — reinstalled each session start
+.opencode/skills/worklog
+.opencode/skills/worklog-todo
+.opencode/skills/worklog-archive
+.opencode/skills/worklog-blocker
+.opencode/skills/worklog-decide
+.opencode/skills/worklog-docs
+```
+
+**Worth committing:** `.worklog/todos.json`, `.worklog/decisions.md`, `.worklog/blockers.md`, and everything under `docs/`. These are your persistent project memory.
+
+---
+
+## Contributing
+
+PRs and issues welcome on [GitHub](https://github.com/lgarceau768/worklog). Keep it small — this plugin is intentionally minimal.
+
+---
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,72 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import { join } from "path"
+import { fileURLToPath } from "url"
+
+const SKILLS = [
+  "worklog",
+  "worklog-todo",
+  "worklog-archive",
+  "worklog-blocker",
+  "worklog-decide",
+  "worklog-docs",
+]
+
+// ponytail: package root via import.meta.url — works with Bun's native TS execution
+const PKG_SKILLS = join(fileURLToPath(new URL(".", import.meta.url)), "skills")
+
+export const WorklogPlugin: Plugin = async ({ directory, $ }) => {
+  const wl = join(directory, ".worklog")
+  await $`mkdir -p ${wl}/sessions ${wl}/adrs ${wl}/reports ${wl}/research`
+
+  const decisions = join(wl, "decisions.md")
+  const blockers = join(wl, "blockers.md")
+  const todosFile = join(wl, "todos.json")
+
+  await $`test -f ${decisions} || printf '# Decisions\n\n_No decisions recorded yet._\n' > ${decisions}`
+  await $`test -f ${blockers} || printf '# Blockers & Open Questions\n\n_No open blockers._\n' > ${blockers}`
+  await $`test -f ${todosFile} || printf '{"version":1,"todos":[]}\n' > ${todosFile}`
+
+  // Auto-install skills to .opencode/skills/ (idempotent — skips if already present)
+  const projectSkillsDir = join(directory, ".opencode", "skills")
+  await $`mkdir -p ${projectSkillsDir}`
+  for (const skill of SKILLS) {
+    const dest = join(projectSkillsDir, skill)
+    await $`test -d ${dest} || cp -r ${join(PKG_SKILLS, skill)} ${dest}`
+  }
+
+  return {
+    // Remind the agent when to use each worklog skill — fires on every LLM call
+    "experimental.chat.system.transform": async (_input, output) => {
+      output.system.push(
+        `## Worklog — Cross-Session Continuity\n` +
+        `At session start, run \`/worklog\` to review open todos and blockers.\n` +
+        `During work: record tasks with \`/worklog-todo\`, blockers with \`/worklog-blocker\`, and decisions with \`/worklog-decide\`.\n` +
+        `At session end, run \`/worklog end\` to write a closing summary.`
+      )
+    },
+
+    // Inject open todos and blockers into compaction context so they survive resets
+    "experimental.session.compacting": async (_input, output) => {
+      try {
+        const todosRaw = await $`cat ${todosFile}`.text()
+        const todos = JSON.parse(todosRaw)
+        const open = (todos.todos ?? []).filter((t: { status: string }) => t.status === "open")
+
+        if (open.length > 0) {
+          const lines = open
+            .map((t: { priority: string; id: string; title: string }) => `- [${t.priority}] ${t.id} — ${t.title}`)
+            .join("\n")
+          output.context.push(`## Open Worklog TODOs\n${lines}`)
+        }
+
+        const blockersRaw = await $`grep -c '\\[OPEN\\]' ${blockers}`.text().catch(() => "0")
+        if (parseInt(blockersRaw.trim()) > 0) {
+          const blockersContent = await $`grep -A3 '\\[OPEN\\]' ${blockers}`.text()
+          output.context.push(`## Open Worklog Blockers\n${blockersContent}`)
+        }
+      } catch {
+        // .worklog not present — skip silently
+      }
+    },
+  }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "opencode-worklog",
+  "version": "0.0.1",
+  "description": "Cross-session work management for OpenCode — todos, blockers, decisions, ADRs, and session checkpoints.",
+  "type": "module",
+  "main": "index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "skills/",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "worklog",
+    "adr",
+    "todos",
+    "session",
+    "agentic"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lgarceau768/worklog.git"
+  },
+  "homepage": "https://github.com/lgarceau768/worklog#readme",
+  "bugs": {
+    "url": "https://github.com/lgarceau768/worklog/issues"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "latest",
+    "@types/node": "^22",
+    "typescript": "^5"
+  }
+}

package/skills/worklog/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: worklog
+description: Cross-session work management. Use when the user wants to see current work status, save a checkpoint mid-session, or write a closing summary at the end of a session. Subcommands — no args: dashboard; "checkpoint": save progress now; "end": close out session with full summary.
+---
+
+# Worklog — Session Management
+
+Manages `.worklog/` for cross-session continuity.
+
+## Invocation forms
+
+| Command | What to do |
+|---|---|
+| `/worklog` | Show the **status dashboard** |
+| `/worklog checkpoint` | Write current progress to today's session file |
+| `/worklog end` | Write a full closing summary and update todos/blockers |
+
+---
+
+## `/worklog` — Status Dashboard
+
+Read these files and present a concise dashboard:
+
+1. **Open TODOs** — read `.worklog/todos.json`, list items where `"status": "open"`, sorted by priority
+2. **Open Blockers** — read `.worklog/blockers.md`, list any `[OPEN]` entries
+3. **Today's session** — read `.worklog/sessions/YYYY-MM-DD.md` if it exists (use today's date), show Activity section
+4. **Last decision** — read `.worklog/decisions.md`, show the most recent lightweight ADR
+5. **Recent formal ADRs** — list `docs/adr-*.md` files (filename + first heading line only); use `ls docs/adr-*.md` and read the `# ADR-NNN` line from each
+
+Format:
+```
+## Worklog Status — YYYY-MM-DD
+
+### Open TODOs (N)
+- [high] 001 — Description
+
+### Open Blockers
+- none
+
+### Today's session
+- 14:32:01
+- 14:45:22
+[summary if written]
+
+### Last decision (.worklog/decisions.md)
+ADR-005 — Brief title
+
+### Formal ADRs (docs/)
+- adr-005-some-decision.md — Some Decision
+```
+
+> To browse, read, or write ADRs/reports/research in full, use `/worklog-docs`.
+
+---
+
+## `/worklog checkpoint` — Mid-Session Checkpoint
+
+Write a checkpoint to `.worklog/sessions/YYYY-MM-DD.md`.
+
+1. Read the current session file (create with template header if missing)
+2. Append a `## Checkpoint — HH:MM` section containing:
+   - What is currently in progress
+   - Any decisions made so far this session
+   - Files changed (summarize, don't list every line)
+3. Write the updated file
+
+Template for a new checkpoint section:
+```markdown
+## Checkpoint — HH:MM
+
+**In progress:** [what's being worked on]
+
+**Done so far:**
+- [item]
+
+**Files touched:** [brief list]
+
+**Next:** [what comes next]
+```
+
+---
+
+## `/worklog end` — Close Session
+
+Write a full closing summary to today's session file.
+
+1. Read `.worklog/todos.json` — ask the user if any todos changed status; update if so
+2. Read `.worklog/blockers.md` — note any new or resolved blockers
+3. Append a `## Summary` section to `.worklog/sessions/YYYY-MM-DD.md`:
+
+```markdown
+## Summary
+
+**Accomplished:**
+- [bullet per major thing done]
+
+**Commits:** [list commit SHAs or descriptions if any]
+
+**Decisions made:** [reference ADR numbers if any were added this session]
+
+**Handoff:** [what the next session should pick up first]
+```
+
+4. Write the session file
+5. If todos changed, write `.worklog/todos.json`

package/skills/worklog-archive/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: worklog-archive
+description: Archive completed todos from todos.json into todos.done.json. Use when the user asks to archive done items, clean up the todo list, or move completed work out of the active list. Args: "archive" (default — move all done/dropped), "archive <id>" (move one specific item).
+---
+
+# Worklog — Archive Done Todos
+
+Moves `"status": "done"` or `"status": "dropped"` items from `.worklog/todos.json`
+into `.worklog/todos.done.json`, keeping the active list clean.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `.worklog/todos.json` | Active todos — open items only after archive |
+| `.worklog/todos.done.json` | Permanent archive of done/dropped items |
+
+---
+
+## `/worklog-archive` or `/worklog-archive archive`
+
+Archive all non-open items.
+
+1. Read `.worklog/todos.json`
+2. Read `.worklog/todos.done.json` (create with `{"version":1,"archived":[]}` if missing)
+3. Partition todos into `keep` (status=open) and `move` (status=done or dropped)
+4. If `move` is empty, report "Nothing to archive." and stop
+5. Append `move` items to `archived` array in `todos.done.json`
+   - Deduplicate by `id` — if the id already exists in `archived`, skip (idempotent)
+6. Write `todos.done.json` with merged archive
+7. Write `todos.json` with only `keep` items
+8. Report:
+
+```
+Archived N item(s) → .worklog/todos.done.json
+  - [done] 001 — Description
+  ...
+
+Active todos remaining: M open item(s).
+```
+
+---
+
+## `/worklog-archive archive <id>`
+
+Archive a single item by id.
+
+1. Read both files (same as above)
+2. Find item with matching `id` in `todos.json`
+3. If not found: "Todo <id> not found in todos.json."
+4. If found and status is `open`: warn "Todo <id> is still open — archive anyway? (y/n)" and wait for confirmation
+5. Move the item and write both files
+6. Report: `Archived <id>: <title>`
+
+---
+
+## `/worklog-archive list`
+
+Show what's in the archive without modifying anything.
+
+1. Read `.worklog/todos.done.json`
+2. Print items grouped by closed date (newest first), showing id, title, closed date
+
+```
+### Archived Todos (16)
+
+2026-06-21
+  [done] 022 — Description
+  ...
+
+2026-06-20
+  [done] 009 — Description
+  ...
+```
+
+---
+
+## Schema reference
+
+`todos.json` item shape:
+```json
+{
+  "id": "NNN",
+  "title": "...",
+  "status": "open | done | dropped",
+  "priority": "high | medium | low",
+  "created": "YYYY-MM-DD",
+  "closed": "YYYY-MM-DD",
+  "notes": "..."
+}
+```
+
+`todos.done.json` shape:
+```json
+{
+  "version": 1,
+  "archived": [ /* same item shape as above */ ]
+}
+```
+
+---
+
+## Notes
+
+- Archive is append-only and idempotent — running twice is safe.
+- Never delete items from `todos.done.json`; only append.
+- `todos.json` must never contain `"status": "done"` or `"status": "dropped"` items after a successful archive run.

package/skills/worklog-blocker/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: worklog-blocker
+description: Record or resolve an open question or blocker in .worklog/blockers.md. Use when something is blocking progress or needs investigation before work can continue. Args: no args = list open; "add <title>"; "resolve <id>".
+---
+
+# Worklog — Blockers & Open Questions
+
+Manages `.worklog/blockers.md`.
+
+## Format in the file
+
+```markdown
+## BLOCKER-NNN — YYYY-MM-DD [OPEN]
+**What:** One sentence describing the blocker or question.  
+**Impact:** What can't be done until this is resolved?  
+**Needs:** What would resolve it (investigation, upstream fix, decision, etc.)?
+```
+
+When resolved, update `[OPEN]` → `[RESOLVED YYYY-MM-DD]` and add a resolution line:
+```markdown
+**Resolution:** What turned out to be the answer or workaround.
+```
+
+---
+
+## `/worklog-blocker` — List Open Blockers
+
+1. Read `.worklog/blockers.md`
+2. Print all entries where status is `[OPEN]`
+3. If none: print `No open blockers.`
+
+---
+
+## `/worklog-blocker add <title>`
+
+1. Read `.worklog/blockers.md`
+2. Find the highest BLOCKER-NNN and increment
+3. Ask for / infer:
+   - **What:** description
+   - **Impact:** what's blocked
+   - **Needs:** what would unblock it
+4. Append the formatted block to the file
+5. Remove the `_No open blockers._` placeholder if present
+6. Confirm: `Recorded BLOCKER-NNN: <title>`
+
+---
+
+## `/worklog-blocker resolve <id>`
+
+1. Read `.worklog/blockers.md`
+2. Find `BLOCKER-<id>`
+3. Change `[OPEN]` to `[RESOLVED YYYY-MM-DD]`
+4. Append `**Resolution:** <user-provided or inferred resolution>`
+5. Write file
+6. Confirm: `Resolved BLOCKER-<id>`

package/skills/worklog-decide/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: worklog-decide
+description: Record an architectural or design decision (ADR) in .worklog/decisions.md. Use when a non-obvious decision is made that future sessions should understand — why something was done a certain way, what was rejected, or what constraints apply.
+---
+
+# Worklog — Decision Recording
+
+Appends a lightweight ADR to `.worklog/decisions.md`.
+
+## Decision routing — which tool to use?
+
+| Decision size | Tool | Output |
+|---|---|---|
+| Small (1–2 sentences, inline context) | `/worklog-decide` (this skill) | Appends to `.worklog/decisions.md` |
+| Major (version selection, architecture change, new system, alternatives considered) | `/worklog-docs new adr <title>` | Creates `docs/adr-NNN-*.md` — committed, permanent |
+
+**Use this skill when:**
+- A design choice that isn't obvious from the code
+- A decision that rejected an alternative worth remembering
+- A constraint imposed by the runtime, framework, or environment that shapes code structure
+- Anything you'd explain in a PR description that isn't in the diff
+
+**Escalate to `/worklog-docs new adr` when:**
+- The decision affects a whole subsystem
+- Alternatives were seriously compared with trade-offs
+- Future contributors need the full context to avoid re-litigating it
+
+## Steps
+
+1. Read `.worklog/decisions.md`
+2. Find the current highest ADR number (e.g. `ADR-002`) and increment
+3. Prompt for (or infer from context):
+   - **Context:** Why did this come up?
+   - **Decision:** What was chosen?
+   - **Alternatives considered:** (optional, only if relevant)
+   - **Status:** `Accepted` | `Superseded by ADR-NNN` | `Experimental`
+4. Append to the file:
+
+```markdown
+## ADR-NNN — YYYY-MM-DD: <short title>
+**Context:** ...  
+**Decision:** ...  
+**Status:** Accepted
+```
+
+5. Confirm: `Recorded ADR-NNN: <title>`
+
+## Format notes
+
+- Keep context and decision to 1–2 sentences each
+- Only add Alternatives if the other option was seriously considered
+- Use `Superseded by ADR-NNN` when a later decision overrides this one — don't delete old ADRs

package/skills/worklog-docs/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: worklog-docs
+description: Browse, read, and write documentation across the worklog system — ADRs, reports, and research notes. Use when asked to "check the ADRs", "look at research on X", "write a report about Y", "what do we know about Z", or "create an ADR". Covers .worklog/adrs/, .worklog/reports/, .worklog/research/, docs/adr-*.md, and .worklog/decisions.md.
+---
+
+# Worklog — Documentation (ADRs, Reports, Research)
+
+Manages the documentation layer of `.worklog/` and `docs/`. Not to be confused with the session log (`/worklog`) or decision recorder (`/worklog-decide`).
+
+---
+
+## Directory Map
+
+```
+.worklog/
+  decisions.md          ← lightweight inline ADRs (ADR-001…), managed by /worklog-decide
+  adrs/                 ← deep technical research docs (content is research, not decisions)
+  reports/              ← formal reports on topics, investigations, reconnaissance
+  research/             ← audit notes, quick investigation outputs
+
+docs/
+  adr-NNN-*.md          ← full formal ADRs (longer form, versioned, committed)
+  architecture.md       ← (if present) high-level architecture overview
+```
+
+### Which location for which content?
+
+| Content type | Location | When to use |
+|---|---|---|
+| Lightweight ADR (2–4 sentences) | `.worklog/decisions.md` | Use `/worklog-decide` for these |
+| Formal ADR (full context, alternatives, consequences) | `docs/adr-NNN-*.md` | Major architectural decisions affecting long-term direction |
+| Deep technical research (API survey, version compat, integration patterns) | `.worklog/adrs/<topic>.md` | Pre-implementation research drop; not a decision, just findings |
+| Formal report (recon, analysis, design proposals) | `.worklog/reports/<name>.md` | Multi-section structured output for a specific topic |
+| Quick audit / investigation notes | `.worklog/research/<name>.md` | Ad-hoc findings from a focused spike |
+
+---
+
+## `/worklog-docs` — List All Docs
+
+List every file across all doc locations:
+
+1. Run: `find .worklog/adrs .worklog/reports .worklog/research -name "*.md" | sort`
+2. List `docs/adr-*.md` files
+3. Summarize `.worklog/decisions.md` — just the ADR numbers and titles (one line each)
+
+Output format:
+```
+## Worklog Docs Index
+
+### Formal ADRs (docs/)
+- adr-005-some-decision.md — Some Decision
+
+### Lightweight ADRs (.worklog/decisions.md)
+- ADR-001 — Brief title
+- ADR-002 — Brief title
+
+### Research (.worklog/adrs/)
+- topic-research.md
+
+### Reports (.worklog/reports/)
+- investigation-report.md
+
+### Research Notes (.worklog/research/)
+- audit-notes.md
+```
+
+---
+
+## `/worklog-docs read <keyword>`
+
+Find and read a doc by keyword or topic name.
+
+1. Search all doc locations for files matching the keyword (filename or title):
+   - `find .worklog/adrs .worklog/reports .worklog/research docs -name "*.md" | grep -i <keyword>`
+   - Also scan `.worklog/decisions.md` for matching ADR titles
+2. If multiple matches: list them, ask which to open
+3. If one match: read and display the file
+4. If none: search file contents — `grep -rl "<keyword>" .worklog/ docs/adr-*.md`
+
+---
+
+## `/worklog-docs new report <title>`
+
+Create a new formal report in `.worklog/reports/`.
+
+1. Derive filename from title: lowercase, spaces → underscores, e.g. `performance_audit.md`
+2. Ask / infer: Is this a sub-topic of an existing report folder? If so, place under that subfolder.
+3. Write the file with this template:
+
+```markdown
+# <Title>
+
+**Generated:** YYYY-MM-DD  
+**Scope:** <one-sentence scope>
+
+---
+
+## 1. <Section>
+
+...
+
+## 2. <Section>
+
+...
+```
+
+4. Confirm: `Created .worklog/reports/<filename>.md`
+
+---
+
+## `/worklog-docs new research <title>`
+
+Create a new research/audit note in `.worklog/research/`.
+
+1. Derive filename: lowercase-with-dashes, e.g. `auth-flow-audit.md`
+2. Write with template:
+
+```markdown
+# <Title>
+
+_Date: YYYY-MM-DD_  
+_Scope: <one sentence>_
+
+---
+
+## Findings
+
+...
+
+## Open Questions
+
+...
+```
+
+3. Confirm: `Created .worklog/research/<filename>.md`
+
+---
+
+## `/worklog-docs new adr <title>`
+
+Create a new **formal** ADR in `docs/`.
+
+1. Read `docs/` to find the highest existing `adr-NNN-*.md` number; increment
+2. Derive filename: `adr-NNN-<kebab-title>.md`
+3. Write with this template:
+
+```markdown
+# ADR-NNN — <Title>
+
+**Status:** Accepted  
+**Date:** YYYY-MM-DD  
+**Deciders:** [author]
+
+---
+
+## Context
+
+<Why did this decision come up? What problem does it solve?>
+
+## Decision
+
+<What was decided?>
+
+## Alternatives Considered
+
+| Option | Reason rejected |
+|---|---|
+| <alt> | <reason> |
+
+## Consequences
+
+**Positive:**
+- ...
+
+**Negative / Risks:**
+- ...
+
+## References
+
+- [link]()
+```
+
+4. Add a reference line to `docs/architecture.md` if that file exists and the ADR affects architecture.
+5. Confirm: `Created docs/adr-NNN-<title>.md`
+
+---
+
+## `/worklog-docs new research-adr <title>`
+
+Create a deep technical research doc in `.worklog/adrs/` (not a decision — a knowledge dump).
+
+1. Derive filename: `<kebab-title>.md`
+2. Write with template:
+
+```markdown
+# <Title> — Research
+
+_Researched: YYYY-MM-DD_
+
+---
+
+## 1. Findings
+
+...
+
+## 2. Recommended Approach
+
+...
+
+## 3. Key API / Code Patterns
+
+```
+
+3. Confirm: `Created .worklog/adrs/<filename>.md`
+
+---
+
+## Notes
+
+- Formal ADRs in `docs/` should be committed and treated as permanent record.
+- Lightweight ADRs in `.worklog/decisions.md` are session-local context that doesn't need a full file.
+- When recording a major decision, use the formal ADR path if the decision will affect future sessions or new contributors.
+- Use `/worklog-decide` for small, quick decisions that don't warrant a full ADR file.
+- The `.worklog/adrs/` folder holds research (pre-decision knowledge), not decisions — don't confuse it with `docs/adr-*.md` formal ADRs.

package/skills/worklog-todo/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: worklog-todo
+description: Manage the cross-session todo list in .worklog/todos.json. Use when the user wants to add, complete, list, or edit todos. Args: "list" (default), "add <title>", "done <id>", "drop <id>".
+---
+
+# Worklog — Todo Management
+
+Manages `.worklog/todos.json`.
+
+## Schema
+
+```json
+{
+  "version": 1,
+  "todos": [
+    {
+      "id": "NNN",
+      "title": "...",
+      "status": "open | done | dropped",
+      "priority": "high | medium | low",
+      "created": "YYYY-MM-DD",
+      "closed": "YYYY-MM-DD",
+      "notes": "optional context or file references"
+    }
+  ]
+}
+```
+
+---
+
+## `/worklog-todo` or `/worklog-todo list`
+
+1. Read `.worklog/todos.json`
+2. Print open items grouped by priority (high first), then a count of done/dropped items
+
+```
+### Open TODOs
+
+[high]  001 — Description
+        Created 2026-06-20 | Notes: ...
+
+[medium] 002 — ...
+
+--- 1 done, 0 dropped ---
+```
+
+---
+
+## `/worklog-todo add <title>`
+
+1. Read `.worklog/todos.json`
+2. Generate next ID (max existing ID + 1, zero-padded to 3 digits)
+3. Ask priority if not obvious from context (default: medium)
+4. Append new todo with `"status": "open"`, today's date
+5. Write file
+6. Confirm: `Added TODO-NNN: <title>`
+
+---
+
+## `/worklog-todo done <id>`
+
+1. Read `.worklog/todos.json`
+2. Find item with matching id
+3. Set `"status": "done"`, add `"closed": "YYYY-MM-DD"`
+4. Write file
+5. Confirm: `Marked TODO-NNN done: <title>`
+
+---
+
+## `/worklog-todo drop <id>`
+
+Same as `done` but sets `"status": "dropped"` and `"closed": "YYYY-MM-DD"`. Use when a todo is no longer relevant.
+
+---
+
+## `/worklog-todo note <id> <text>`
+
+Appends to the `notes` field of an existing todo.