opencode-skills-collection 4.0.0 → 4.0.1

package/bundled-skills/lore/WORKFLOWS.md

@@ -0,0 +1,216 @@
+# Workflows
+
+lore has seven workflows. This document explains when to use each one, in plain language. For the operational specification the agent follows when running them, see [`SKILL.md`](SKILL.md).
+
+> [中文版](./WORKFLOWS.zh-CN.md)
+
+## Overview
+
+| Workflow | What it does | Frequency |
+|---|---|---|
+| [`init`](#init) | Set up `.lore/` and platform mirror files | Once per project |
+| [`sync`](#sync) | Update `.lore/` after a code change | After each feature |
+| [`query`](#query) | Search `.lore/` for an answer | Every session |
+| [`audit`](#audit) | Find stale or contradictory entries | Quarterly |
+| [`compress`](#compress) | Rebuild `SUMMARY.md` | When SUMMARY is stale |
+| [`mirror`](#mirror) | Regenerate platform files from `.lore/` | After batch of syncs |
+| [`history`](#history) | Show git commits for an entry / file / scope | When investigating |
+
+---
+
+## `init`
+
+**One-line**: Create `.lore/` and take over your existing `CLAUDE.md` / `AGENTS.md`.
+
+**When you say it**: "lore init" — once per project, or when adding lore to a project that already has platform files.
+
+**What happens**:
+1. Agent scans for existing platform files (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, etc.)
+2. For each file found, asks you: take over / preserve / abort
+3. Detects monorepo structure (pnpm workspaces, Cargo workspace, etc.) and proposes scope list
+4. Writes initial `.lore/` draft (entries with `#added:<today>` + deterministic IDs)
+5. Shows you a summary of what will be created
+6. On your confirm: moves draft to `.lore/`, generates `SUMMARY.md`, refreshes platform files
+
+**Real scenarios**:
+- New project, first time using lore → `lore init`
+- Old project already has `CLAUDE.md`, want lore to manage it → `lore init` and take over
+- Monorepo with separate `frontend/` and `backend/` → init detects both, asks for scope names
+
+**Output**: Full `.lore/` directory + updated platform files + populated `.config.json`.
+
+---
+
+## `sync`
+
+**One-line**: After a code change, update `.lore/` with what changed.
+
+**When you say it**: "lore sync" — after committing a feature, refactor, or new dependency.
+
+**What happens**:
+1. Agent runs `git diff --stat HEAD` to see what changed
+2. If changes are significant (≥50 lines / ≥2 dirs, or new module/dir/dep), agent proactively proposes
+3. For each change, agent classifies it as `[NEW]` / `[STALE]` / `[REFINED]`
+4. Emits a proposal with markers
+5. You accept or reject per marker
+6. Accepted markers get applied to `.lore/*.md`
+
+**Real scenarios**:
+- "I just added a new dependency — update lore" → `lore sync`
+- "We decided to stop using React Query, switch to SWR" → `lore sync` after the code change
+- "There's a new module — capture it" → `lore sync`
+
+**Output**: Updated `.lore/*.md` files with new entries (and `#verified` / `#stale` tags where appropriate).
+
+**Note**: `sync` does NOT update platform mirror files (that's a separate `mirror` command). Reason: keeps `git log` of agent-facing files readable.
+
+---
+
+## `query`
+
+**One-line**: Search `.lore/` for an answer to a question.
+
+**When you say it**: "lore query <term>" — any time you want to know what's in memory.
+
+**What happens**:
+1. Agent reads `.lore/SUMMARY.md` (the table of contents)
+2. Fuzzy matches your query against entries
+3. Returns matched entries with stable `[file#ID]` references
+4. Optionally drills into specific scope files for more detail
+
+**Real scenarios**:
+- "What database does this project use?" → `lore query database`
+- "Why did we pick Zustand?" → `lore query zustand`
+- "What are the conventions for backend modules?" → `lore query backend:conventions`
+
+**Output**: Bounded list of matched entries:
+
+```
+[_global/DECISIONS.md#DEC-2026-07-11-6137] Picked OpenAI-compatible LLM API
+[scopes/backend/CONVENTIONS.md#CONV-2026-07-11-9b89] Embedding has two backends
+```
+
+The `[file#ID]` reference lets the agent `cat` the file for full text.
+
+---
+
+## `audit`
+
+**One-line**: Find stale or contradictory entries in `.lore/`.
+
+**When you say it**: "lore audit" — quarterly review, or before a big refactor.
+
+**What happens**:
+1. Runs `find_stale.py` to find entries with `#added` > 90 days ago and no `#verified`
+2. Runs `find_duplicates.py` to find entries that contradict each other
+3. Cross-checks entry-referenced code paths against current filesystem
+4. Emits an `[ALERT]` report
+
+**Real scenarios**:
+- "Are there any lore entries that contradict the current code?" → `lore audit`
+- Quarterly hygiene check → `lore audit`
+- Before onboarding a new contributor → `lore audit` to clean up stale entries
+
+**Output**: A report grouped by issue type:
+
+```
+[ALERT] 5 entries may be stale (no #verified in >90 days):
+  - ARCH-2026-01-15-d7a3  last verified 2026-04-12
+  ...
+
+[ALERT] 2 entries contradict current code:
+  - CONV-2026-03-01-1f8c  says "use webpack"; project now uses Vite
+```
+
+**Note**: `audit` does NOT modify files. To act on findings, run `sync` with proposal-driven updates.
+
+---
+
+## `compress`
+
+**One-line**: Rebuild `.lore/SUMMARY.md` from current entries.
+
+**When you say it**: "lore compress" — when SUMMARY is stale (entries > 500, or > 30 days since last compress), or before sharing lore with someone new.
+
+**What happens**:
+1. Enumerates all entries via `list_entries.py`
+2. Skips recently-stale entries
+3. For each `(scope, layer)` pair, picks 3–5 most important entries
+4. Writes `SUMMARY.md` per template
+5. If `auto_mirror: true` in config, regenerates platform mirrors; otherwise asks per target and only writes the ones you accept. (This is the second mirror update trigger — `sync` deliberately does not regenerate mirrors.)
+6. Stops after mirror regeneration has either written or been declined per target.
+
+**Real scenarios**:
+- "Refresh the summary" → `lore compress`
+- "I haven't compressed in 2 months" → `lore compress`
+- "Onboard a new contributor — make sure SUMMARY is fresh" → `lore compress`
+
+**Output**: Updated `SUMMARY.md` (and possibly mirror files).
+
+**Idempotent**: Running twice produces the same result (modulo date stamp).
+
+---
+
+## `mirror`
+
+**One-line**: Regenerate platform files (`CLAUDE.md`, `AGENTS.md`, etc.) from current `.lore/`.
+
+**When you say it**: "lore mirror" — after a batch of syncs, or to manually sync mirrors after editing `.lore/*.md`.
+
+**What happens**:
+1. Reads current `.lore/SUMMARY.md` and scope indices
+2. For each target, detects section boundary (`## Lore` / `---` / `## My notes`)
+3. Computes new Lore section content
+4. **Content-based dedup**: skips write if byte-identical to existing
+5. Replaces Lore section; preserves My notes verbatim
+6. Writes file back
+
+**Real scenarios**:
+- "I just did a batch of syncs — update the agent-facing files" → `lore mirror`
+- "I edited `.lore/SUMMARY.md` manually — propagate to mirrors" → `lore mirror`
+- "Verify the mirror hasn't drifted" → `lore mirror` (no-op reports confirm)
+
+**Output**: Updated `CLAUDE.md` / `AGENTS.md` / etc., or "No changes needed" if nothing changed.
+
+---
+
+## `history`
+
+**One-line**: Show git commits related to an entry, file, or scope.
+
+**When you say it**: "lore history <entry-id>|<file-path>|--scope=<name>" — when investigating "why does this exist" or "when did this change".
+
+**What happens**:
+- **Entry form**: `lore history DEC-2026-02-03-7c19` — finds the entry, derives its `#added` date, runs `git log --since=<date>` on the referenced code file
+- **File form**: `lore history frontend/src/store.ts` — runs `git log --since=1970` on that path
+- **Scope form**: `lore history --scope=frontend` — runs file form on every `.lore/scopes/frontend/*.md`
+
+**Real scenarios**:
+- "Why did we pick Postgres?" → find the entry via `query`, then `lore history <id>`
+- "When did this file change?" → `lore history <file>`
+- Debugging: "what's the recent history of this module?" → `lore history <path>`
+
+**Output**:
+
+```markdown
+# history: [DEC-2026-02-03-7c19]
+
+  abc1234  2026-05-12  refactor: extract chat agent_loop (#87)
+  def5678  2026-03-08  feat: switch chat chain to chat_fast (#74)
+```
+
+---
+
+## Quick reference
+
+| I want to... | Use |
+|---|---|
+| Start lore on a project | `init` |
+| Update lore after a code change | `sync` |
+| Find what's in memory | `query` |
+| Find stale entries | `audit` |
+| Refresh the summary | `compress` |
+| Update agent-facing files | `mirror` |
+| Trace why something exists | `history` |
+
+For the operational specification (what the agent actually does step-by-step), see [`SKILL.md`](SKILL.md). For per-platform file mapping (which platforms read which files), see [`references/platform-mirrors.md`](references/platform-mirrors.md).

package/bundled-skills/lore/WORKFLOWS.zh-CN.md

@@ -0,0 +1,216 @@
+# 工作流
+
+lore 有七个工作流。本文用平实语言解释每个什么时候用。Agent 跑它们时的 operational 规范见 [`SKILL.md`](SKILL.md)。
+
+> [English](./WORKFLOWS.md)
+
+## 概览
+
+| Workflow | 做什么 | 频率 |
+|---|---|---|
+| [`init`](#init) | 建 `.lore/` + 接管平台 mirror 文件 | 每个项目 1 次 |
+| [`sync`](#sync) | 代码变更后更新 `.lore/` | 每个 feature 后 |
+| [`query`](#query) | 搜 `.lore/` 找答案 | 每个 session |
+| [`audit`](#audit) | 找 stale / 矛盾的 entry | 季度 |
+| [`compress`](#compress) | 重建 `SUMMARY.md` | SUMMARY 过期时 |
+| [`mirror`](#mirror) | 从 `.lore/` 重新生成平台文件 | 一批 sync 后 |
+| [`history`](#history) | 列出 entry / 文件 / scope 的 git commits | 调查时 |
+
+---
+
+## `init`
+
+**一句话**：建 `.lore/`，接管你已有的 `CLAUDE.md` / `AGENTS.md`。
+
+**怎么用**：`lore init` —— 每个项目 1 次，或老项目第一次接入 lore。
+
+**agent 做什么**：
+1. 扫现有平台文件（`CLAUDE.md`、`AGENTS.md`、`.cursorrules` 等）
+2. 每个文件问你：接管 / 保留 / 中止
+3. 检测 monorepo 结构（pnpm workspaces、Cargo workspace 等），给 scope 列表
+4. 写初始 `.lore/draft/`（entry 带 `#added:<today>` + 确定性 ID）
+5. 给你看 summary
+6. 你确认后：移到 `.lore/`，生成 `SUMMARY.md`，刷新平台文件
+
+**真实场景**：
+- 新项目第一次用 lore → `lore init`
+- 老项目已有 `CLAUDE.md`，想让 lore 接管 → `lore init` 选「接管」
+- Monorepo 有 `frontend/` 和 `backend/` → init 自动识别两个 scope，问名字
+
+**输出**：完整 `.lore/` 目录 + 更新过的平台文件 + 写好的 `.config.json`。
+
+---
+
+## `sync`
+
+**一句话**：代码改了，把变化落到 `.lore/`。
+
+**怎么用**：`lore sync` —— 提交完 feature / refactor / 依赖变更后。
+
+**agent 做什么**：
+1. 跑 `git diff --stat HEAD` 看变更
+2. 变更显著时（≥50 行 / 跨 ≥2 目录，或新 module/dir/dep），agent 主动提议
+3. 每个变更分类成 `[NEW]` / `[STALE]` / `[REFINED]`
+4. 输出 marker 提案
+5. 你按 marker 接受 / 拒绝
+6. 接受的 marker 落到 `.lore/*.md`
+
+**真实场景**：
+- 「我刚加了新依赖 —— 更新 lore」 → `lore sync`
+- 「我们决定不用 React Query 了，换 SWR」 → 代码改完后 `lore sync`
+- 「新加了个 module —— 记一下」 → `lore sync`
+
+**输出**：更新过的 `.lore/*.md` 文件（新 entry 和 `#verified` / `#stale` tag）。
+
+**注意**：`sync` 不会更新平台 mirror 文件（那是独立的 `mirror` 命令）。理由：保持 agent 端文件 `git log` 可读。
+
+---
+
+## `query`
+
+**一句话**：搜 `.lore/` 找答案。
+
+**怎么用**：`lore query <term>` —— 任何想问「memory 里有什么」的时候。
+
+**agent 做什么**：
+1. 读 `.lore/SUMMARY.md`（目录）
+2. 对 entry 文本做模糊匹配
+3. 返回命中 entry，带稳定 `[file#ID]` 引用
+4. 可选地深入具体 scope 文件拿更完整上下文
+
+**真实场景**：
+- 「这个项目用什么数据库？」 → `lore query database`
+- 「为什么选 Zustand？」 → `lore query zustand`
+- 「backend module 的约定是什么？」 → `lore query backend:conventions`
+
+**输出**：bounded 命中列表：
+
+```
+[_global/DECISIONS.md#DEC-2026-07-11-6137] Picked OpenAI-compatible LLM API
+[scopes/backend/CONVENTIONS.md#CONV-2026-07-11-9b89] Embedding has two backends
+```
+
+`[file#ID]` 引用让 agent `cat` 文件对应行拿完整文本。
+
+---
+
+## `audit`
+
+**一句话**：找 `.lore/` 里的 stale / 矛盾 entry。
+
+**怎么用**：`lore audit` —— 季度 review，或大重构前。
+
+**agent 做什么**：
+1. 跑 `find_stale.py` 找 `#added` > 90 天且无 `#verified` 的 entry
+2. 跑 `find_duplicates.py` 找互相矛盾的 entry
+3. 交叉检查 entry 引用的代码路径
+4. 输出 `[ALERT]` 报告
+
+**真实场景**：
+- 「有没有跟现状矛盾的 lore entry？」 → `lore audit`
+- 季度体检 → `lore audit`
+- onboarding 新贡献者前 → `lore audit` 清 stale
+
+**输出**：按问题类型分组的报告：
+
+```
+[ALERT] 5 entries may be stale (no #verified in >90 days):
+  - ARCH-2026-01-15-d7a3  last verified 2026-04-12
+  ...
+
+[ALERT] 2 entries contradict current code:
+  - CONV-2026-03-01-1f8c  says "use webpack"; project now uses Vite
+```
+
+**注意**：`audit` 不改文件。要落地整改，跑 `sync` 走提案流程。
+
+---
+
+## `compress`
+
+**一句话**：从当前 entry 重建 `.lore/SUMMARY.md`。
+
+**怎么用**：`lore compress` —— SUMMARY 过期时（entries > 500 或 > 30 天没压），或分享 lore 前。
+
+**agent 做什么**：
+1. 跑 `list_entries.py` 枚举所有 entry
+2. 跳过 recently-stale 的 entry
+3. 每个 `(scope, layer)` 对，按规则挑 3–5 条最重要的
+4. 按模板写 `SUMMARY.md`
+5. 如果 config 里 `auto_mirror: true`，重生成平台 mirror；否则每个 mirror 目标单独问，只写你确认的（这是第二个 mirror 触发点——`sync` 故意不更新 mirror）
+6. mirror 处理完（写或拒绝）后停止
+
+**真实场景**：
+- 「刷新一下 summary」 → `lore compress`
+- 「两个月没压了」 → `lore compress`
+- 「onboarding 新人 —— 确保 SUMMARY 是最新的」 → `lore compress`
+
+**输出**：更新过的 `SUMMARY.md`（以及可能的 mirror 文件）。
+
+**幂等**：跑两次产出同样的结果（日期戳除外）。
+
+---
+
+## `mirror`
+
+**一句话**：从 `.lore/` 重新生成平台文件（`CLAUDE.md`、`AGENTS.md` 等）。
+
+**怎么用**：`lore mirror` —— 一批 sync 之后，或手动改过 `.lore/*.md` 想同步到 mirror。
+
+**agent 做什么**：
+1. 读当前 `.lore/SUMMARY.md` 和 scope 索引
+2. 对每个 target 检测段边界（`## Lore` / `---` / `## My notes`）
+3. 计算新 Lore 段内容
+4. **Content-based dedup**：跟现有 byte-identical 就跳过
+5. 替换 Lore 段；My notes 段原样保留
+6. 写回文件
+
+**真实场景**：
+- 「刚做完一批 sync —— 同步到 agent 端文件」 → `lore mirror`
+- 「我手动改过 `.lore/SUMMARY.md` —— 推到 mirror」 → `lore mirror`
+- 「验证 mirror 没漂移」 → `lore mirror`（无变化报告即确认）
+
+**输出**：更新过的 `CLAUDE.md` / `AGENTS.md` 等，或「No changes needed」无变化报告。
+
+---
+
+## `history`
+
+**一句话**：列出与某 entry / 文件 / scope 相关的 git commits。
+
+**怎么用**：`lore history <entry-id>|<file-path>|--scope=<name>` —— 调查「为什么有这个」或「什么时候改的」。
+
+**agent 做什么**：
+- **Entry 形式**：`lore history DEC-2026-02-03-7c19` —— 找 entry，导 `#added` 日期，跑 `git log --since=<date>` 在引用的代码文件上
+- **File 形式**：`lore history frontend/src/store.ts` —— 跑 `git log --since=1970` 在该路径上
+- **Scope 形式**：`lore history --scope=frontend` —— 对 `.lore/scopes/frontend/*.md` 每个跑 file 形式
+
+**真实场景**：
+- 「为什么选 Postgres？」 → 先 `query` 找到 entry，再 `lore history <id>`
+- 「这个文件什么时候改的？」 → `lore history <file>`
+- 调试：「这个 module 最近的 history？」 → `lore history <path>`
+
+**输出**：
+
+```markdown
+# history: [DEC-2026-02-03-7c19]
+
+  abc1234  2026-05-12  refactor: extract chat agent_loop (#87)
+  def5678  2026-03-08  feat: switch chat chain to chat_fast (#74)
+```
+
+---
+
+## 速查
+
+| 我想…… | 用 |
+|---|---|
+| 在项目上启动 lore | `init` |
+| 代码改了更新 lore | `sync` |
+| 找 memory 里有什么 | `query` |
+| 找 stale entry | `audit` |
+| 刷新 summary | `compress` |
+| 更新 agent 端文件 | `mirror` |
+| 查「为什么有这个」 | `history` |
+
+Agent 跑命令时的 operational 规范（一步步做什么）见 [`SKILL.md`](SKILL.md)。各平台文件映射（哪些 agent 读哪些文件）见 [`references/platform-mirrors.md`](references/platform-mirrors.md)。

package/bundled-skills/lore/references/audit-template.md

@@ -0,0 +1,60 @@
+# Audit report template
+
+`audit` writes its output to `.lore/audit/audit-YYYY-MM-DD.md`. This file is read-only with respect to `.lore/*.md` (see main `SKILL.md` Conflict resolution — audit never mutates and never ALERTs).
+
+## Template
+
+```markdown
+# Memory Audit Report
+
+> Date: 2026-07-09
+> Total entries audited: <N>
+> Findings: <X> CONFLICT, <Y> STALE, <Z> UNVERIFIED
+
+## Global (`_global/`)
+
+### CONFLICT
+- [CONV-2026-01-20-b1e8] claims "all packages TypeScript strict mode"
+  Evidence: `packages/legacy/tsconfig.json` has `"strict": false`
+
+### STALE
+- [ARCH-2026-01-15-d7a3] references `nx.json`
+  Evidence: file no longer exists at repo root
+
+### UNVERIFIED
+- [DEC-2026-02-03-7c19] last verified 2025-09-12 (>90 days)
+
+## Scope: frontend
+
+### CONFLICT
+- ...
+
+### STALE
+- ...
+
+### UNVERIFIED
+- ...
+
+## Summary
+
+Recommended action: run `lore sync` to address these findings.
+Audit itself does not modify any entry.
+```
+
+## Severity definitions
+
+| Severity | Meaning |
+|---|---|
+| `CONFLICT` | Code/config directly contradicts the entry content (e.g. memory says `react@18`, `package.json` says `16`) |
+| `STALE` | Entry references a resource (file, API, version) that no longer exists |
+| `UNVERIFIED` | Entry's `#verified` date is >90 days; needs re-confirmation |
+
+## Required rules
+
+- The audit report **never** modifies any `.lore/*.md` file.
+- The audit report **never** emits ALERT blocks (ALERT noise is contained to `sync` and `query`).
+- Audit is a pure read-and-report operation. To act on findings, the user runs `sync`.
+
+## Evidence format
+
+Each finding includes a one-line `Evidence:` reference pointing to the file path and (when possible) line number that triggered the finding. The agent must verify the evidence exists before writing the report.