@xluos/dev-assets-cli 0.1.0 → 0.2.0

package/README.md

@@ -37,16 +37,27 @@ npx skills add xluos/dev-asset-skill-suite --all -g -y
 ## Repository Layout
 
 ```text
+bin/
+  dev-assets.js              # `npx dev-assets` CLI entry (hooks + install helpers)
+hooks/
+  hooks.json                 # Claude hook template (.claude/settings.local.json)
+  codex-hooks.json           # Codex hook template (.codex/hooks.json)
+  README.md
+lib/
+  dev_asset_common.py        # shared library used by hook scripts
+scripts/
+  hooks/                     # session_start/pre_compact/stop/session_end .py — invoked via `dev-assets hook ...`
+  install_codex_hooks.sh     # one-shot installer; symlinked as install_claude_hooks.sh
+  install_claude_hooks.sh -> install_codex_hooks.sh
+  install_suite.py           # local symlink-based skill install (dev only)
+  npm/                       # package check/build helpers
 skills/
   using-dev-assets/
   dev-assets-setup/
   dev-assets-context/
   dev-assets-update/
   dev-assets-sync/
-lib/
-  dev_asset_common.py
-scripts/
-  install_suite.py
+suite-manifest.json          # canonical list of suite + legacy skill names
 ```
 
 ## Storage Layout
@@ -74,6 +85,7 @@ By default the suite stores memory outside the repository:
 - `repo/`: shared memory for the whole Git repository
 - `branches/<branch>/`: branch-local working memory
 - `repo-key`: derived from repository identity, not just the folder name
+- `DEV_ASSETS_ROOT`: environment variable that overrides the default storage root (`~/.dev-assets/repos`); honored by the CLI and all bundled skill scripts
 
 ## Lifecycle Hooks
 
@@ -97,29 +109,37 @@ Shared behavior:
 - `Stop`: persist a lightweight HEAD marker after each response
 - `SessionEnd`: persist the final HEAD marker at session end
 
-Quick Codex install into the current repository:
+Recommended: install the CLI once globally, then merge hooks per repo.
 
 ```bash
-sh scripts/install_codex_hooks.sh
+npm install -g @xluos/dev-assets-cli                 # once
+dev-assets install-hooks codex                       # in the target repo (defaults to cwd)
+dev-assets install-hooks claude
 ```
 
-Or run it directly from GitHub in the repository you want to enable:
+Or merge hooks into the agent's **user-level** config instead of per-repo:
 
 ```bash
-sh -c "$(curl -fsSL https://raw.githubusercontent.com/xluos/dev-asset-skill-suite/main/scripts/install_codex_hooks.sh)"
+dev-assets install-hooks codex --global              # writes ~/.codex/hooks.json
+dev-assets install-hooks claude --global             # writes ~/.claude/settings.json
 ```
 
-The installer will:
+Without a global CLI install, run via `npx` (downloads on demand):
+
+```bash
+npx -y @xluos/dev-assets-cli install-hooks codex
+npx -y @xluos/dev-assets-cli install-hooks claude --global
+```
 
-- install `@xluos/dev-assets-cli` into the target repository
-- merge Codex hooks into `.codex/hooks.json`
-- make hooks call `npx dev-assets hook ...`, so they no longer depend on repo-local Python paths
+`install-hooks <agent>` merges hooks into the target config. Repo scope writes `.codex/hooks.json` or `.claude/settings.local.json`; `--global` writes `~/.codex/hooks.json` or `~/.claude/settings.json`. Hooks call `dev-assets hook ...`, so the CLI must be reachable on PATH (global install) or resolvable via `npx`. `--repo` defaults to the current working directory when omitted.
 
-You can also merge hooks manually after the CLI is installed:
+Shell installers (`scripts/install_codex_hooks.sh`, `scripts/install_claude_hooks.sh`) are thin wrappers around the same command for environments that prefer a shell entry:
 
 ```bash
-npx dev-assets install-hooks codex
-npx dev-assets install-hooks claude
+sh scripts/install_codex_hooks.sh                    # Codex, repo-scoped
+sh scripts/install_codex_hooks.sh --agent claude     # Claude, repo-scoped
+sh scripts/install_codex_hooks.sh --global           # Codex, user-level
+sh scripts/install_claude_hooks.sh --global          # Claude, user-level
 ```
 
 Boundary:
@@ -129,6 +149,15 @@ Boundary:
 - Global skill installs do not auto-load hooks yet, because this project is a skill suite rather than a standalone plugin
 - Hook execution is now expected to go through `dev-assets` CLI, not raw `python3 scripts/hooks/*.py`
 
+## Two Invocation Tracks
+
+This suite has two distinct entry surfaces. They look similar but should not be confused.
+
+- Lifecycle hooks → `npx dev-assets hook <session-start|pre-compact|stop|session-end>`. These run automatically from `.codex/hooks.json` or `.claude/settings.local.json` and are the only place where the `dev-assets` CLI is the right entry point.
+- In-conversation skill workflows (`dev-assets-setup`, `dev-assets-context`, `dev-assets-update`, `dev-assets-sync`) → invoke each skill's bundled Python script under `<skill-dir>/scripts/`. The CLI does not wrap these because they are interactive workflow steps with skill-specific arguments, not background hook actions.
+
+Inside SKILL.md files these script paths appear as `python3 /absolute/path/to/<skill>/scripts/<name>.py`. The agent is expected to substitute the actual on-disk skill directory at call time (the path the harness loaded the skill from), not to pass the literal placeholder string.
+
 ## Notes
 
 - The suite no longer stores its primary memory inside the Git worktree by default.
@@ -137,4 +166,8 @@ Boundary:
 - Shared document entrances can live in repo-level `sources.md`; branch-specific progress and next-step live in branch files.
 - `dev-assets-setup` can migrate legacy `.dev-assets/<branch>/` content into the new user-home branch directory.
 - `npx skills` does not need `scripts/install_suite.py`; the repository already follows standard skill discovery rules.
-- `scripts/install_suite.py` remains useful for local symlink-based installs during development.
+- `scripts/install_suite.py` remains useful for local symlink-based installs during development. Example — symlink all suite skills into Codex's user-level skill directory and prune legacy aliases:
+
+  ```bash
+  python3 scripts/install_suite.py --target ~/.codex/skills --force --remove-legacy
+  ```

package/bin/dev-assets.js

@@ -116,6 +116,12 @@ function targetPathForAgent(agent, repoRoot) {
   fail(`unsupported agent: ${agent}`);
 }
 
+function globalTargetPathForAgent(agent) {
+  if (agent === "codex") return path.join(os.homedir(), ".codex", "hooks.json");
+  if (agent === "claude") return path.join(os.homedir(), ".claude", "settings.json");
+  fail(`unsupported agent: ${agent}`);
+}
+
 function mergeHookLists(existingItems, incomingItems) {
   const merged = existingItems.map((item) => ({ ...item }));
   const index = new Map();
@@ -145,20 +151,6 @@ function mergeConfig(existingConfig, templateConfig) {
   return result;
 }
 
-function installPackage(packageSpec, repoRoot) {
-  const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
-  const result = spawnSync(
-    npmCmd,
-    ["install", "--save-dev", packageSpec],
-    { cwd: repoRoot, encoding: "utf8", stdio: ["inherit", "pipe", "pipe"] }
-  );
-  if (result.stdout) process.stdout.write(result.stdout);
-  if (result.stderr) process.stderr.write(result.stderr);
-  if (result.status !== 0) {
-    process.exit(result.status || 1);
-  }
-}
-
 function commandHook(positional, options) {
   const action = positional[0];
   const repoRoot = path.resolve(options.repo || process.cwd());
@@ -167,28 +159,31 @@ function commandHook(positional, options) {
 
 function commandInstallHooks(positional, options) {
   const agent = positional[0] || options.agent || "codex";
-  const repoRoot = path.resolve(options.repo || process.cwd());
-  const targetPath = targetPathForAgent(agent, repoRoot);
+  const isGlobal = Boolean(options.global);
   const template = loadJson(templatePathForAgent(agent));
+  let targetPath;
+  let scope;
+  let repoRoot = null;
+  if (isGlobal) {
+    targetPath = globalTargetPathForAgent(agent);
+    scope = "global";
+  } else {
+    repoRoot = path.resolve(options.repo || process.cwd());
+    targetPath = targetPathForAgent(agent, repoRoot);
+    scope = "repo";
+  }
   const existing = fs.existsSync(targetPath) ? loadJson(targetPath) : {};
   const merged = mergeConfig(existing, template);
   writeJson(targetPath, merged);
-  process.stdout.write(
-    `${JSON.stringify({ repo_root: repoRoot, agent, target: targetPath, events: Object.keys(template.hooks || {}) }, null, 2)}\n`
-  );
-}
-
-function commandInstallCli(_positional, options) {
-  const repoRoot = path.resolve(options.repo || process.cwd());
-  const packageSpec = options.package || "@xluos/dev-assets-cli";
-  installPackage(packageSpec, repoRoot);
+  const report = { agent, scope, target: targetPath, events: Object.keys(template.hooks || {}) };
+  if (repoRoot) report.repo_root = repoRoot;
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
 }
 
 function printHelp() {
   process.stdout.write(`Usage:
   dev-assets hook <session-start|pre-compact|stop|session-end> [--repo PATH]
-  dev-assets install-hooks <codex|claude> [--repo PATH]
-  dev-assets install-cli [--repo PATH] [--package SPEC]
+  dev-assets install-hooks <codex|claude> [--repo PATH] [--global]
 
 Environment:
   DEV_ASSETS_ROOT defaults to ${DEFAULT_STORAGE_ROOT}
@@ -210,10 +205,6 @@ function main() {
     commandInstallHooks(positional, options);
     return;
   }
-  if (command === "install-cli") {
-    commandInstallCli(positional, options);
-    return;
-  }
   fail(`unknown command: ${command}`);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xluos/dev-assets-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI for dev-assets hooks and repo-local setup",
   "license": "MIT",
   "scripts": {

package/skills/dev-assets-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dev-assets-sync
-description: Use when the current conversation reaches a commit-related checkpoint or another clear persistence checkpoint, and Codex should write only this round's durable memory back into the current branch memory while keeping repo-shared metadata in sync.
+description: Use when the current conversation reaches a commit-related checkpoint or another clear persistence checkpoint where this round's progress, risks, next steps, and decisions should now be snapshotted for the next session. Use this skill for commit-time, handoff-ready, lifecycle-hook, or milestone snapshots, not for correcting existing memory or persisting one-off clarifications. Repo-shared source updates here mean shared documents and links, not branch-only hot paths.
 ---
 
 # Dev Assets Sync
@@ -11,9 +11,19 @@ description: Use when the current conversation reaches a commit-related checkpoi
 
 ## Workflow
 
-### Step 1: Decide whether this moment is worth syncing
+### Step 1: Confirm this is a real checkpoint
 
-只在当前时点已经形成明确的持久化价值时触发 `sync`。
+进入 sync 前，确认当前时点确实是检查点：
+
+- 刚完成一次提交、准备提交、或刚完成一轮代码/排查检查点
+- 当前进展、阻塞、下一步已经清晰到值得 handoff 或跨会话延续
+- 阶段性方向已经收敛，适合在这个检查点留一份快照
+- 本轮新增了仓库共享层之后还会复用的文档入口、链接或决策结论
+- lifecycle hook 触发
+
+如果只是单次排查里刚确认 root cause / scope / 某条规则，还不到检查点，就别进 sync。具体路由判定（包括 sync 与 update 的关系）以 `using-dev-assets` 为准。
+
+确认是检查点后，sync 是一个"复合动作包"：本流程内部如果同时发现需要改写某条旧记忆，先按 `dev-assets-update` 改写对应 section，再回到 Step 2 做 record-session。
 
 ### Step 2: Summarize only what this checkpoint should leave behind
 
@@ -25,7 +35,11 @@ description: Use when the current conversation reaches a commit-related checkpoi
 - 关键决策与原因
 - 本次新增的共享资料入口
 
-然后运行：
+这里的“共享资料入口”只指仓库共享层应该复用的文档、链接、外部资料，不包括当前分支后续要看的 hot paths、目录或局部代码入口。
+
+`record-session` 不接受任意自定义字段名（例如 `current_progress`、`blockers_or_caveats`、`shared_sources` 都会被忽略；`decisions` 必须是 object 数组而不是 string 数组，否则脚本会直接报错）。准备 `summary.json` 之前请先读 `references/commit-sync.md`，里面有完整字段表、别名、最小示例和常见错误模式，不要凭印象脑补 schema。
+
+整理好 summary 后运行：
 
 ```bash
 python3 /absolute/path/to/dev-assets-sync/scripts/dev_asset_sync.py record-session --repo <repo-path> --summary-file <summary.json>
@@ -39,6 +53,11 @@ python3 /absolute/path/to/dev-assets-sync/scripts/dev_asset_sync.py record-sessi
 - 新增资料入口 → repo `sources.md`
 - HEAD / 最近访问分支 → manifest
 
+额外约束：
+
+- 写进 `repo/sources.md` 的必须是 repo 共享资料入口
+- branch-only 导航、hot paths、局部代码入口不属于这里的 `sources`
+
 它默认不做这些事：
 
 - 不重建整个 branch memory

package/skills/dev-assets-sync/references/commit-sync.md

@@ -8,3 +8,64 @@ It should:
 2. update only the branch or repo memory sections directly affected by this commit
 3. update lightweight commit metadata when needed
 4. leave detailed implementation history in Git
+
+## `record-session` summary schema
+
+`dev_asset_sync.py record-session` expects a JSON object with script-recognized keys. Do not infer field names from the prose bullets alone.
+
+Accepted keys:
+
+- `title`: string
+- `overview_summary`: string or string array
+- `implementation_notes`: string or string array
+- `changes`: string or string array; alias of `implementation_notes`
+- `risks`: string or string array
+- `next_steps`: string or string array
+- `sources`: string or string array
+- `source_updates`: string or string array; alias of `sources`
+- `decisions`: object array; each item should look like `{ "decision": "...", "reason": "...", "impact": "..." }`
+- `memory`: string or string array
+- `context_updates`: string or string array; alias of `memory`
+- `review_notes`: string or string array
+- `frontend_updates`: string or string array
+- `backend_updates`: string or string array
+- `test_updates`: string or string array
+
+Minimal example:
+
+```json
+{
+  "title": "本次检查点标题",
+  "implementation_notes": [
+    "完成了当前轮次最值得留存的进展"
+  ],
+  "risks": [
+    "还有一个已知风险未消除"
+  ],
+  "next_steps": [
+    "下次继续先做什么"
+  ],
+  "decisions": [
+    {
+      "decision": "之后优先检查页面入口装配和插件注入",
+      "reason": "同批功能整组缺失时，先看单插件显隐容易偏题",
+      "impact": "适用于同类插件化页面的排查顺序"
+    }
+  ],
+  "sources": [
+    "apps/example/page.tsx - 与这次检查点相关的共享资料入口"
+  ]
+}
+```
+
+Common mistakes:
+
+- `current_progress` is not recognized; use `implementation_notes`
+- `blockers_or_caveats` is not recognized; use `risks`
+- `shared_sources` is not recognized; use `sources`
+- `decisions` must be an object array, not a string array
+
+Failure mode to remember:
+
+- Wrong field names such as `shared_sources` are ignored
+- `decisions` as `string[]` will fail when the script evaluates `item.get("decision")`

package/skills/dev-assets-update/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dev-assets-update
-description: Use when current development memory needs to be corrected or supplemented, whether explicitly requested by the user or implicitly required because the conversation produced new stable understanding or new shared source entry points for the current repository.
+description: Use when current development memory needs to be corrected, rewritten, or supplemented because the existing dev-assets are wrong, stale, missing a key premise, or the user explicitly wants a durable update. Implicit use is limited to repeated corrections or invalidated conclusions, and to newly provided relevant sources or links that should change future understanding. Do not use this skill for ordinary checkpoint summaries or one-off clarifications; use dev-assets-sync for checkpoint snapshots.
 ---
 
 # Dev Assets Update
@@ -9,6 +9,17 @@ description: Use when current development memory needs to be corrected or supple
 
 **Announce at start:** 用一句简短的话说明将先重写相关 section，而不是继续追加历史。
 
+## Trigger Hints
+
+`update` 是非检查点时刻的零散修正/补充入口。典型触发：
+
+- 用户明确要求"记一下"、"同步到 dev-assets"、"把这条经验写进去"
+- 发现之前的工作记忆写错了、过时了、缺少关键前提
+- 会话里反复出现理解偏差、口径被纠正、或先前结论已经失效
+- 用户提供了新的相关资料、链接、文档入口，且这些信息会影响后续理解
+
+检查点时刻（commit / handoff / 阶段收敛 / lifecycle hook）请走 `dev-assets-sync`，由 sync 在其流程内部再决定是否调用 update。完整路由判定见 `using-dev-assets`。
+
 ## Workflow
 
 ### Step 1: Locate the current assets
@@ -30,6 +41,11 @@ python3 /absolute/path/to/dev-assets-update/scripts/dev_asset_update.py show --r
 - branch `context.md`：why / caveat / workaround / decision
 - repo `sources.md`：共享资料入口
 
+补充约束：
+
+- `source` / `link` / `shared-source` 这类更新默认面向 repo 共享资料入口
+- 当前分支后续要看的 hot paths、目录、局部代码入口，不要伪装成 repo `sources.md` 更新
+
 如果是显式 repo 共享层更新，使用这些 kind：
 
 - `shared-overview`
@@ -88,6 +104,6 @@ python3 /absolute/path/to/dev-assets-update/scripts/dev_asset_update.py touch-ma
 **Never:**
 
 - 把所有新增信息都堆到一个文件里
-- 用“之后再整理”为理由跳过沉淀
+- 用"之后再整理"为理由跳过沉淀
 - 继续把 `update` 当成 append-only 笔记工具
 - 把 branch-specific 当前工作态写进 repo 共享层

package/skills/using-dev-assets/SKILL.md

@@ -14,48 +14,38 @@ description: >-
 
 ## Routing
 
-### Route to `dev-assets-context`
+按下面的顺序判断，命中第一个就走对应 skill：
 
-当用户是在已有分支上继续开发、排查、解释、修改时：
+| 当前情境 | 走哪个 skill |
+| --- | --- |
+| 当前 repo 还没有当前 branch 的资产目录，或这是新需求/新分支第一次开始 | `dev-assets-setup` |
+| 在已有分支上继续开发、排查、解释、修改（默认情况） | `dev-assets-context` |
+| 已经到了检查点：刚提交 / 准备提交 / handoff / 阶段收敛 / lifecycle hook 触发 | `dev-assets-sync` |
+| 不是检查点，但对话里出现了"现有记忆写错了/缺了/被新资料推翻了" | `dev-assets-update` |
+| 都不命中 | 不进入套件，正常对话 |
 
-- 先恢复当前 branch 记忆
-- 还不够时再看 repo 共享层
-- 只有需要原始事实时再看 branch / repo `sources.md`
+### Update 与 Sync 的关系
 
-### Route to `dev-assets-setup`
+不是平级互斥的两个触发器，而是：
 
-当当前仓库还没有当前 branch 的资产目录，或者用户明确表示这是新需求 / 新分支第一次开始时：
+- `sync` 是检查点时刻的**复合动作包**：内部可以包含 0–N 次 update + HEAD marker + manifest 刷新。
+- 检查点时如果同时发现某条旧记忆需要修正，正确路径是"在 sync 流程里先调一次 update，再 record-session"，不要两个都跳过、也不要纠结二选一。
+- 非检查点的零散修正/补充才是 update 的独立触发场景。
+- 一次性澄清、普通问答、低价值波动既不该 sync 也不该 update。
 
-- 初始化用户目录下的 repo+branch 存储
-- 先搭好当前记忆和共享资料入口，而不是复制完整文档
-
-### Route to `dev-assets-sync`
-
-当当前对话已经到达明确的检查点，并且本轮产生了需要跨会话保留的稳定记忆时：
-
-- 把它视为“沉淀本次检查点留下的关键信息”的时刻
-- 不是生成流水账，也不是重建整个状态
-
-### Route to `dev-assets-update`
-
-当当前记忆需要被补充或纠正，并且更新后的内容会明显改善后续恢复上下文或回源效率时：
-
-- 定位 repo + branch 资产目录
-- 选择最合适的目标文件和 section
-- 把本轮新信息和相关会话上下文整理后重写进去
+子 skill 内部不再重复这条边界，统一以本表为准。
 
 ## Always / Never
 
 **Always:**
 
 - 在 Git 仓库开发对话开头先做一次路由判断
-- 把“继续开发”“提交检查点”和“阶段性里程碑”都视为高优先级触发场景
 - 优先维护当前 branch 的有效记忆
-- 在新理解会影响后续恢复时，主动判断是否该隐式触发 `update`
+- 把检查点时刻理解为"sync 包含若干 update"，而不是二选一
 
 **Never:**
 
 - 明知道在继续分支开发，却跳过 dev-assets 判断
 - 把 repo 共享层当成 branch 当前工作态的替代品
 - 在 branch 资产缺失时直接开始实现
-- 因为低价值波动或一次性澄清就频繁触发 `update`
+- 因为低价值波动或一次性澄清就触发任何写入