Improve llmdoc update workflow

.claude-plugin/marketplace.json

@@ -4,12 +4,12 @@
     "name": "TokenRoll",
     "email": "shuaiqijianaho@qq.com"
   },
-  "description": "Marketplace for the minimal llmdoc Claude Code workflow",
+  "description": "Marketplace for the llmdoc Claude Code workflow",
   "plugins": [
     {
       "name": "llmdoc",
       "source": "./",
-      "description": "Minimal llmdoc workflow for Claude Code: init, update, and use"
+      "description": "llmdoc workflow for Claude Code: init, update modes, temporary investigation cache, and use"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "llmdoc",
-  "description": "llmdoc Claude Code plugin with a minimal workflow: init, update, and use",
-  "version": "2.0.0",
+  "description": "llmdoc Claude Code plugin with init, update modes, temporary investigation cache, and use",
+  "version": "2.1.0",
   "author": {
     "name": "DJJ & Danniel"
   }

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "llmdoc",
-  "version": "2.0.0",
-  "description": "Doc-driven workflow with startup docs, reflections, update prompts, and reusable skills for Codex.",
+  "version": "2.1.0",
+  "description": "Doc-driven workflow with startup docs, update modes, temporary investigation cache, and reusable skills for Codex.",
   "author": {
     "name": "DJJ & Danniel",
     "email": "shuaiqijianaho@qq.com",
@@ -13,7 +13,7 @@
   "interface": {
     "displayName": "llmdoc",
     "shortDescription": "Doc-driven coding workflow",
-    "longDescription": "Use startup docs, guides, reflections, and update prompts to improve coding quality and reduce repeated mistakes.",
+    "longDescription": "Use startup docs, guides, update modes, temporary investigation cache, and focused reflections to improve coding quality and reduce repeated work.",
     "developerName": "TokenRoll",
     "category": "Productivity",
     "capabilities": ["Read", "Write"],

.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Publish GitHub Release
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Build release notes
+        id: notes
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          tag="${GITHUB_REF_NAME}"
+          previous_tag="$(git tag --sort=-creatordate | grep -v "^${tag}$" | head -n 1 || true)"
+
+          {
+            echo "## Changes"
+            echo
+            if [ -n "$previous_tag" ]; then
+              git log --pretty='- %s (%h)' "${previous_tag}..${tag}"
+            else
+              git log --pretty='- %s (%h)' "${tag}"
+            fi
+            echo
+            echo "## Changed Files"
+            echo
+            if [ -n "$previous_tag" ]; then
+              git diff --name-only "${previous_tag}..${tag}" | sed 's/^/- /'
+            else
+              git show --name-only --pretty='' "${tag}" | sed '/^$/d; s/^/- /'
+            fi
+          } > release-notes.md
+
+      - name: Publish release
+        uses: softprops/action-gh-release@6cbd405e2c4e67a21c47fa9e383d020e4e28b836 # v2.3.3
+        with:
+          body_path: release-notes.md

AGENTS.example.md

@@ -4,6 +4,10 @@ Before broad source-code exploration, planning, or documentation work, load the
 
 The main assistant should align with the user before non-trivial plans or edits.
 
+Use available `llmdoc` subagents when they fit the task. Prefer `investigator` for context exploration, current-state research, unfamiliar subsystems, and reusable scratch reports; use `recorder` for stable doc updates, `worker` for scoped implementation, and `reflector` for process lessons.
+
 At the end of a non-trivial task, when the work produced durable knowledge, workflow lessons, or useful reflections, the main assistant should proactively use the `llmdoc-update` skill in Codex.
 
+Treat `.llmdoc-tmp/` as a local temporary context cache only. Validate scratch reports before reuse; tracked `llmdoc/` docs are the project knowledge source.
+
 Keep detailed workflow rules, templates, hook behavior, and doc-structure guidance in the `llmdoc` skill.

CLAUDE.example.md

@@ -5,7 +5,11 @@ Load the `llmdoc` skill before broad code exploration, planning, document update
 
 The main assistant should align with the user before non-trivial plans or edits.
 
+Use available `llmdoc` subagents when they fit the task. Prefer `investigator` for context exploration, current-state research, unfamiliar subsystems, and reusable scratch reports; use `recorder` for stable doc updates, `worker` for scoped implementation, and `reflector` for process lessons.
+
 At the end of a non-trivial task, the main assistant should evaluate whether to ask the user to run `/llmdoc:update`.
 
+Treat `.llmdoc-tmp/` as a local temporary context cache only. Validate scratch reports before reuse; tracked `llmdoc/` docs are the project knowledge source.
+
 Keep detailed workflow rules, templates, hook behavior, and doc-structure guidance in the `llmdoc` skill.
 <system-reminder>

README.md

@@ -12,6 +12,7 @@ The default setup is simple:
 - the core skill entry is short, while detailed rationale, protocols, and templates are split under `skills/llmdoc/references/`
 - the core skill defines proactive guide/reflection reading and proactive user discussion before non-trivial edits
 - the workflow restores the good pattern of proactively asking whether to run `/llmdoc:update` at the end of non-trivial tasks
+- `/llmdoc:update` supports lightweight and heavier modes, so immediate post-task doc updates do not always require a full multi-agent pipeline
 - helper Codex skills provide command-like entrypoints without pretending Codex has custom slash commands for this plugin
 - agents and command contracts stay focused on execution instead of carrying a large amount of duplicated guidance
 
@@ -65,14 +66,23 @@ Use `/llmdoc:update` after meaningful work when project knowledge should be pers
 In Claude Code, this is a command.
 In Codex, use the helper skill `llmdoc-update` for the equivalent workflow.
 
+The command keeps tracked `llmdoc/` docs consistent with the current repository. Stable docs should stay compact: either smaller than the source they describe or useful because they explain architecture, implementation intent, boundaries, and stable contracts.
+
+The command selects the lightest mode that can keep docs correct:
+
+- `fast`: default for immediate post-implementation updates when the coordinating assistant has fresh context
+- `analysis`: one focused evidence pass for stale context, current-state research, or unclear impact
+- `full`: separate investigation, reflection, and recording when risk or process learning justifies the extra independence
+
 The command:
 
 1. Rebuilds context from llmdoc and the current working tree
 2. Proactively reads relevant guides and reflections
-3. Investigates impacted concepts
-4. Writes a reflection under `llmdoc/memory/reflections/`
-5. Updates stable docs
-6. Synchronizes `llmdoc/index.md`
+3. Chooses an update mode
+4. Investigates impacted concepts only when the selected mode requires it
+5. Writes a reflection under `llmdoc/memory/reflections/` only when there is a workflow lesson or missing-doc signal
+6. Updates stable docs and reconciles `llmdoc/memory/doc-gaps.md`
+7. Synchronizes `llmdoc/index.md`
 
 In normal use, the main assistant should proactively ask whether to run `/llmdoc:update` when the task produced durable knowledge or a useful reflection.
 
@@ -100,11 +110,13 @@ llmdoc/
 `llmdoc/startup.md` is only the startup reading order.
 They should link to each other, but they should not repeat the same content.
 
+`.llmdoc-tmp/` is a local temporary context cache. Investigator reports can persist across nearby sessions and help avoid repeated research, but they are ignored by git, not indexed, and not a source of truth. Promote only durable conclusions into tracked `llmdoc/` docs.
+
 ## Internal Agents
 
 | Agent | Purpose |
 |------|---------|
-| `investigator` | Evidence gathering for chat or temporary scratch reports |
+| `investigator` | Evidence gathering for chat, current-state research, or temporary scratch reports |
 | `worker` | Executes well-defined tasks |
 | `recorder` | Maintains stable llmdoc documents |
 | `reflector` | Writes post-task reflections |

README.zh-CN.md

@@ -12,6 +12,7 @@
 - core skill 入口保持简短，详细的方法论、协议和模板拆到 `skills/llmdoc/references/`
 - core skill 还定义了主动阅读 guides/reflection，以及在非简单改动前主动和用户沟通
 - 整套工作流还恢复了一个好模式：在非简单任务结束时，主动询问是否运行 `/llmdoc:update`
+- `/llmdoc:update` 支持轻量和重型模式，所以刚完成实现后的文档更新不必每次都跑完整多 agent 流水线
 - Codex helper skills 提供了接近 command 的入口，但不会误导用户以为 Codex 已经支持这个插件的自定义 slash command
 - agent 和 command contract 只负责执行，不再各自复制一大段说明
 
@@ -65,14 +66,23 @@
 在 Claude Code 里，它是 command。
 在 Codex 里，用 helper skill `llmdoc-update` 走等价工作流。
 
+这个命令会让 tracked `llmdoc/` 文档和当前仓库保持一致。稳定文档应该保持紧凑：要么比它描述的源码更小，要么能解释源码搜索无法快速提供的架构、实现意图、边界和稳定契约。
+
+这个命令会选择能保证文档正确的最轻模式：
+
+- `fast`：默认模式，适合主 assistant 刚完成实现、上下文仍然新鲜的情况
+- `analysis`：适合上下文变旧、需要调研当前现状、或影响范围不清时的一次聚焦证据 pass
+- `full`：适合风险较高、事实有争议、或确实需要独立反思与复核的情况
+
 这个命令会：
 
 1. 基于 llmdoc 和当前 working tree 重建上下文
 2. 主动阅读相关 guides 和 reflection
-3. 调研受影响的概念
-4. 在 `llmdoc/memory/reflections/` 下写 reflection
-5. 更新稳定文档
-6. 同步 `llmdoc/index.md`
+3. 选择 update mode
+4. 只在所选模式需要时调研受影响的概念
+5. 只有出现工作流教训或缺失文档信号时，才在 `llmdoc/memory/reflections/` 下写 reflection
+6. 更新稳定文档，并清账 `llmdoc/memory/doc-gaps.md`
+7. 同步 `llmdoc/index.md`
 
 在日常使用里，如果任务产生了值得长期保留的知识或反思，主 assistant 应该主动询问是否现在运行 `/llmdoc:update`。
 
@@ -100,11 +110,13 @@ llmdoc/
 `llmdoc/startup.md` 只负责启动阅读顺序。
 两者可以互相链接，但不应该重复同一批内容。
 
+`.llmdoc-tmp/` 是本地临时 context cache。investigator 报告可以跨相邻会话保留，帮助减少重复调研，但它被 git 忽略、不会进入 index，也不是 source of truth。只有稳定、可复用的结论才应该提升到 tracked `llmdoc/` 文档里。
+
 ## 内部 Agents
 
 | Agent | 用途 |
 |------|------|
-| `investigator` | 做证据驱动的调研，可回对话，也可输出临时调查草稿 |
+| `investigator` | 做证据驱动的调研，可回对话、调研当前现状，也可输出临时调查草稿 |
 | `worker` | 执行明确的任务 |
 | `recorder` | 维护稳定 llmdoc 文档 |
 | `reflector` | 记录任务后的 reflection |

agents/investigator.md

@@ -1,13 +1,15 @@
 ---
 name: investigator
-description: "Evidence-driven codebase investigation for init, update, and ad-hoc analysis. Supports chat replies and temporary scratch reports."
+description: "Evidence-driven codebase investigation for init, update, current-state research, and ad-hoc analysis. Supports chat replies and temporary scratch reports."
 tools: Read, Glob, Grep, Bash, WebSearch, WebFetch, Write, Edit
 model: opus
 color: cyan
 ---
 
 You are `investigator`, an evidence-first agent used to understand the codebase and produce a reusable retrieval map for other agents.
 
+Investigator output can support init, update, or current-state research. It is not stable project memory by itself.
+
 When invoked:
 
 1. Read `llmdoc/index.md` when it exists.
@@ -16,7 +18,7 @@ When invoked:
 4. Read the remaining task-relevant documents from `overview/`, `architecture/`, and `reference/`.
 5. Investigate source code to fill gaps left by the docs.
 6. If you enter a new subsystem, find conflicting evidence, or hit an execution failure, re-read relevant guides and reflections before expanding code search.
-7. Produce the requested output either directly in conversation or as a persistent file.
+7. Produce the requested output either directly in conversation or as a temporary scratch file.
 
 Key practices:
 
@@ -25,6 +27,8 @@ Key practices:
 - **Use line numbers sparingly:** Add line numbers only when they are required to prove a disputed or non-obvious behavior.
 - **Objective:** Report facts and evidence, not design opinions.
 - **Split by sink:** `sink=chat` is for direct answers. `sink=file` is for temporary scratch artifacts, usually under `.llmdoc-tmp/investigations/`.
+- **Temporary means temporary:** `.llmdoc-tmp/` may persist across sessions, but it is ignored by git, not indexed by `llmdoc/index.md`, and can be deleted at any time.
+- **Make reuse safe:** File reports should record date, git revision when available, evidence scope, unresolved gaps, and whether the report is safe to reuse.
 - **No long code pastes:** The reader can open source files directly.
 
 <InputFormat>
@@ -65,7 +69,14 @@ Key practices:
   </OutputFormat_Chat>
 
 <OutputFormat_File>
-Write a markdown file using the same section layout as `<OutputFormat_Chat>`, then return the absolute file path.
+Write a markdown file using the same section layout as `<OutputFormat_Chat>`, plus this metadata block near the top:
+
+- Date:
+- Git Revision:
+- Evidence Scope:
+- Reuse Conditions:
+
+Then return the absolute file path.
 </OutputFormat_File>
 
 Always ensure the investigation is specific, factual, and easy for another agent to reuse.

agents/recorder.md

@@ -8,19 +8,29 @@ color: green
 
 You are `recorder`, the agent responsible for stable llmdoc maintenance.
 
-Your job is to update durable documentation, not to dump raw notes. Temporary investigation artifacts belong in `.llmdoc-tmp/investigations/`. Reflections belong to `reflector`. You also own `memory/decisions/` and `memory/doc-gaps.md`.
+Your job is to keep tracked `llmdoc/` docs consistent with the current repository, not to dump raw notes. Stable docs should be smaller than the source they describe or add architectural explanation, implementation intent, boundaries, and retrieval value. Temporary investigation artifacts belong in `.llmdoc-tmp/investigations/`. Reflections belong to `reflector`. You also own `memory/decisions/` and `memory/doc-gaps.md`.
 
 When invoked:
 
 1. Read `llmdoc/index.md` and `llmdoc/startup.md` when they exist.
 2. Proactively read relevant guides and reflections before deciding how stable docs should change.
-3. Read the relevant raw investigation reports when the task depends on temporary scratch findings, especially during `/llmdoc:init`.
+3. Read the relevant raw investigation reports when the task depends on temporary scratch findings, especially during `/llmdoc:init` or `/llmdoc:update mode=analysis`.
+   - Validate scratch report date, git revision, evidence scope, and unresolved gaps before reusing it.
+   - Treat scratch as evidence, not as source of truth.
 4. Determine the impacted concepts and map each one to the correct llmdoc category.
 5. Keep `llmdoc/index.md` and `llmdoc/startup.md` distinct in purpose and content.
 6. During `/llmdoc:init`, prefer a small number of deep core docs before expanding into many narrower docs.
 7. Update the touched documents and synchronize `llmdoc/index.md`.
 8. Report every file you created, updated, or deleted.
 
+Consistency rules:
+
+- Correct or remove stable-doc claims that no longer match the current code.
+- Do not preserve stale facts just because they were previously documented.
+- Do not add volatile counts, line totals, or incidental implementation inventory unless they are part of a stable contract.
+- Do not index `.llmdoc-tmp/`.
+- Reconcile `memory/doc-gaps.md` during non-trivial updates: close resolved gaps, mark stale gaps, and add only actionable gaps with closure criteria.
+
 llmdoc categories:
 
 - `/must/`: Tiny startup documents that should be read on every run. Only recurring, cross-task, stable knowledge belongs here.
@@ -30,6 +40,14 @@ llmdoc categories:
 - `/reference/`: Stable lookup facts, contracts, schemas, conventions.
 - `/memory/`: Historical process memory such as reflections, decisions, and doc gaps. `reflector` owns `memory/reflections/`. `recorder` owns `memory/decisions/` and `memory/doc-gaps.md`.
 
+Routing tests:
+
+- Use `/must/` only for short, recurring rules that are likely to prevent mistakes on most tasks.
+- Use `/architecture/` for flows, ownership boundaries, invariants, and why the implementation is shaped that way.
+- Use `/reference/` for stable lookup facts and contracts.
+- Use `/guides/` for repeatable workflows.
+- Leave raw investigation, volatile observations, and one-off evidence in `.llmdoc-tmp/`.
+
 Index rules:
 
 - `llmdoc/index.md` is the global map of the documentation system.