@ai-content-space/loopx 0.2.8 → 0.2.10

package/README.md

@@ -70,8 +70,16 @@ Support skills:
 - `tdd`
 - `debug`
 - `verify`
+- `doc-readability`
+- `requirement-analyzer`
 - `go-style`
 - `kratos`
+- `api-designer`
+- `architecture-designer`
+- `sql-style`
+- `cli-developer`
+
+Support skills are lenses, not workflow states. They can be invoked directly by users, or applied by workflow skills when relevant. `requirement-analyzer` and `doc-readability` assess source documents; `api-designer`, `architecture-designer`, `sql-style`, `cli-developer`, `go-style`, and `kratos` add domain discipline during design, execution, and review without changing the core flow.
 
 ## Artifacts
 
@@ -86,6 +94,16 @@ For the v1 skill-suite workflow, human-maintained artifacts live under `docs/loo
 
 `docs/loopx/memory/` stores git-tracked shared memory for lightweight project knowledge that should follow a user across machines but is not stable enough to become a spec.
 
+### Repo Specs And Memory
+
+`docs/loopx/specs/` is binding long-lived repo context. Workflow skills read relevant specs before clarification, design, planning, build, and review work. Specs define durable repo rules and constraints; they are stronger than local memory and should be updated through reviewed workflow changes.
+
+Summary: docs/loopx/specs/ is binding long-lived repo context; .loopx/memory/MEMORY.md is advisory curated memory.
+
+`docs/loopx/specs/index.md` is optional. When present, agents use it only as a map for retrieval and prioritization; the directory remains valid without an index.
+
+`.loopx/memory/MEMORY.md` is advisory curated memory. It summarizes useful project knowledge, but must not override current user instructions, approved source documents, or binding specs. `.loopx/memory/index.jsonl` is optional and retrieval-only: it helps agents find relevant active memory cards and is not an append-only log.
+
 `finish` may generate spec candidates in `docs/loopx/specs/` when completed work produces stable team rules. These candidates are repo-tracked and must remain visible in the git diff.
 
 `finish` also writes a local audit ledger under `.loopx/finish/<audit-id>/`. `none` means the work was audited, but it did not produce a durable learning candidate. Choice recording lives in that local finish audit directory, while repo-tracked spec candidates stay in `docs/loopx/specs/`.
@@ -94,13 +112,9 @@ Finish runtime commands are advanced agent/runtime plumbing, not the normal user
 
 `finish` is the terminal completion step for one implementation decision. Rerun it only after keep-as-is, PR iteration, interruption before executing a choice, or new changes after review feedback. Do not rerun it after merge or discard.
 
-### Archive compatibility
-
-archive is not part of the public v1 finish flow. Older runtime state may still contain archive fields or a hidden `loopx archive <slug>` compatibility command, but normal users should complete work through `finish`.
-
 Generated support state, hook diagnostics, installer metadata, HTML views, manifests, and runtime JSON remain under `.loopx/`.
 
-Local agent memory lives under `.loopx/memory/`:
+Local advisory agent memory lives under `.loopx/memory/`:
 
 - `.loopx/memory/MEMORY.md`
 - `.loopx/memory/index.jsonl`
@@ -159,8 +173,8 @@ loopx doctor
 Undo installed files when you want to remove loopx-managed user-level artifacts:
 
 ```bash
-rm -rf ~/.agents/skills/{clarify,spec,plan-to-exec,subagent-exec,exec,review,final-review,fix-review,finish,refactor-plan,tdd,debug,verify,go-style,kratos}
-rm -rf ~/.claude/skills/{clarify,spec,plan-to-exec,subagent-exec,exec,review,final-review,fix-review,finish,refactor-plan,tdd,debug,verify,go-style,kratos}
+rm -rf ~/.agents/skills/{clarify,spec,plan-to-exec,subagent-exec,exec,review,final-review,fix-review,finish,refactor-plan,tdd,debug,verify,doc-readability,requirement-analyzer,go-style,kratos,api-designer,architecture-designer,sql-style,cli-developer}
+rm -rf ~/.claude/skills/{clarify,spec,plan-to-exec,subagent-exec,exec,review,final-review,fix-review,finish,refactor-plan,tdd,debug,verify,doc-readability,requirement-analyzer,go-style,kratos,api-designer,architecture-designer,sql-style,cli-developer}
 rm -f ~/.codex/hooks/codex-workflow-hook.mjs ~/.claude/hooks/loopx-workflow-hook.mjs
 ```
 
@@ -171,10 +185,13 @@ loopx install-skills
 loopx install-skills --target codex
 loopx install-skills --target claude
 loopx install-skills --target claude --project
+loopx install-skills --target all --add-agent-guidance
 loopx install-skills --target all --yes
 ```
 
-Claude project install writes to the current repository's `.claude/skills/` and `.claude/settings.json`.
+Agent guidance is opt-in. `--add-agent-guidance` writes a loopx managed block that tells agents to read Repo Specs And Memory context. For Codex user installs it writes to `~/.codex/AGENTS.md`; for Claude user installs it writes to `~/.claude/CLAUDE.md`; for Claude project installs it writes to the current repo's `CLAUDE.md`. User content outside the managed block is preserved.
+
+Claude project install writes skills and settings to the current repository's `.claude/skills/` and `.claude/settings.json`.
 
 ## Codex Plugin
 
@@ -198,7 +215,7 @@ The CLI supports installation, diagnostics, rendering, and runtime maintenance:
 
 ```bash
 loopx --version
-loopx install-skills [--target <codex|claude|all>] [--project] [--mode <copy|symlink>] [--dir <path>] [--yes] [--dry-run] [--json]
+loopx install-skills [--target <codex|claude|all>] [--project] [--mode <copy|symlink>] [--dir <path>] [--add-agent-guidance] [--yes] [--dry-run] [--json]
 loopx init [--slug <slug>] [--enable-agent-delegation] [--auto-agent-delegation] [--agent-delegation-threshold <local|critic-only|parallel-review>] [--json]
 loopx clarify <slug> [--standard|--deep] [--json]
 loopx render [slug|--all]

package/README.zh-CN.md

@@ -70,8 +70,16 @@ loopx install-skills --target all --json
 - `tdd`
 - `debug`
 - `verify`
+- `doc-readability`
+- `requirement-analyzer`
 - `go-style`
 - `kratos`
+- `api-designer`
+- `architecture-designer`
+- `sql-style`
+- `cli-developer`
+
+辅助 skills 是 lens，不是 workflow state。用户可以直接调用它们，workflow skills 也可以在相关场景套用它们。`requirement-analyzer` 和 `doc-readability` 用于评估源文档；`api-designer`、`architecture-designer`、`sql-style`、`cli-developer`、`go-style` 和 `kratos` 在设计、执行、评审阶段提供领域纪律，但不改变核心流程。
 
 ## 产物
 
@@ -86,6 +94,16 @@ v1 skill-suite 工作流的人工维护长期产物放在 `docs/loopx/`：
 
 `docs/loopx/memory/` 用于保存纳入 git 的 shared memory，适合需要跟随用户跨机器同步、但还没有稳定到 spec 级别的轻量项目知识。
 
+### Repo Specs And Memory
+
+`docs/loopx/specs/` 是 binding long-lived repo context。工作流 skills 会在澄清、设计、计划、构建和评审前读取相关 specs。Specs 定义持久 repo rules 和 constraints；它们优先于本地 memory，并应通过经过评审的工作流变更来更新。
+
+Summary: docs/loopx/specs/ is binding long-lived repo context; .loopx/memory/MEMORY.md is advisory curated memory.
+
+`docs/loopx/specs/index.md` 是可选的。存在时，agent 只把它当作 retrieval 和 prioritization map；即使没有 index，这个目录仍然有效。
+
+`.loopx/memory/MEMORY.md` 是 advisory curated memory。它总结有用的项目知识，但不能覆盖当前用户指令、已批准的 source documents 或 binding specs。`.loopx/memory/index.jsonl` 也是可选且 retrieval-only：它帮助 agent 找到相关 active memory cards，不是 append-only log。
+
 当完成的工作产生稳定团队规则时，`finish` 可以在 `docs/loopx/specs/` 生成 spec candidates。这些候选是 repo-tracked，必须保留在 git diff 中供审阅。
 
 `finish` 还会在 `.loopx/finish/<audit-id>/` 下写入本地 audit ledger。`none` 表示已经完成审计，但没有产生可持久化的 learning candidate。choice recording 也放在这个本地 finish audit 目录里，而 repo-tracked 的 spec candidates 仍然保留在 `docs/loopx/specs/`。
@@ -94,13 +112,9 @@ Finish runtime 命令是给 agent、hooks 和兼容路径使用的高级 plumbin
 
 `finish` 是一次 implementation decision 的终端完成步骤。只有在上次选择保留、PR 迭代、执行选择前中断，或 review feedback 后出现新变更时才重新执行；merge 或 discard 后不要重复执行。
 
-### Archive 兼容性
-
-archive 不属于公开 v1 finish 流程。旧 runtime state 仍可能包含 archive 字段，也可能通过隐藏的 `loopx archive <slug>` 兼容命令处理历史状态，但普通用户应通过 `finish` 完成工作。
-
 生成的支撑状态、hook 诊断、安装元数据、HTML views、manifests 和 runtime JSON 仍放在 `.loopx/` 下。
 
-本地 agent memory 放在 `.loopx/memory/`：
+本地 advisory agent memory 放在 `.loopx/memory/`：
 
 - `.loopx/memory/MEMORY.md`
 - `.loopx/memory/index.jsonl`
@@ -159,8 +173,8 @@ loopx doctor
 撤销已安装文件，移除 loopx 管理的用户级 artifacts：
 
 ```bash
-rm -rf ~/.agents/skills/{clarify,spec,plan-to-exec,subagent-exec,exec,review,final-review,fix-review,finish,refactor-plan,tdd,debug,verify,go-style,kratos}
-rm -rf ~/.claude/skills/{clarify,spec,plan-to-exec,subagent-exec,exec,review,final-review,fix-review,finish,refactor-plan,tdd,debug,verify,go-style,kratos}
+rm -rf ~/.agents/skills/{clarify,spec,plan-to-exec,subagent-exec,exec,review,final-review,fix-review,finish,refactor-plan,tdd,debug,verify,doc-readability,requirement-analyzer,go-style,kratos,api-designer,architecture-designer,sql-style,cli-developer}
+rm -rf ~/.claude/skills/{clarify,spec,plan-to-exec,subagent-exec,exec,review,final-review,fix-review,finish,refactor-plan,tdd,debug,verify,doc-readability,requirement-analyzer,go-style,kratos,api-designer,architecture-designer,sql-style,cli-developer}
 rm -f ~/.codex/hooks/codex-workflow-hook.mjs ~/.claude/hooks/loopx-workflow-hook.mjs
 ```
 
@@ -171,10 +185,13 @@ loopx install-skills
 loopx install-skills --target codex
 loopx install-skills --target claude
 loopx install-skills --target claude --project
+loopx install-skills --target all --add-agent-guidance
 loopx install-skills --target all --yes
 ```
 
-Claude project install 会写入当前仓库的 `.claude/skills/` 和 `.claude/settings.json`。
+Agent guidance 是 opt-in。`--add-agent-guidance` 会写入 loopx managed block，提示 agent 读取 Repo Specs And Memory context。Codex user install 写入 `~/.codex/AGENTS.md`；Claude user install 写入 `~/.claude/CLAUDE.md`；Claude project install 写入当前 repo 的 `CLAUDE.md`。Managed block 之外的用户内容会保留。
+
+Claude project install 会把 skills 和 settings 写入当前仓库的 `.claude/skills/` 和 `.claude/settings.json`。
 
 ## Codex Plugin
 
@@ -198,7 +215,7 @@ CLI 用于安装、诊断、渲染和 runtime 维护：
 
 ```bash
 loopx --version
-loopx install-skills [--target <codex|claude|all>] [--project] [--mode <copy|symlink>] [--dir <path>] [--yes] [--dry-run] [--json]
+loopx install-skills [--target <codex|claude|all>] [--project] [--mode <copy|symlink>] [--dir <path>] [--add-agent-guidance] [--yes] [--dry-run] [--json]
 loopx init [--slug <slug>] [--enable-agent-delegation] [--auto-agent-delegation] [--agent-delegation-threshold <local|critic-only|parallel-review>] [--json]
 loopx clarify <slug> [--standard|--deep] [--json]
 loopx render [slug|--all]

package/docs/loopx/design/loopx-skill-suite-v1-design.md

@@ -21,8 +21,14 @@ The v1 product surface is the installed and governed bundled skill suite:
 - `tdd`
 - `debug`
 - `verify`
+- `doc-readability`
+- `requirement-analyzer`
 - `go-style`
 - `kratos`
+- `api-designer`
+- `architecture-designer`
+- `sql-style`
+- `cli-developer`
 
 Runtime-only skills are not installed as Codex or Claude skills in v1.
 
@@ -44,6 +50,12 @@ clarify -> spec? -> plan-to-exec -> (subagent-exec | exec) -> final-review -> fi
 
 `finish` verifies completion, extracts local memory, proposes repo-tracked spec candidates when stable team rules emerged, then presents merge, PR, keep, or discard options. It is the terminal completion step for one implementation decision; rerun it only after keep-as-is, PR iteration, interruption before choice execution, or new changes after review feedback. Do not rerun it after merge or discard.
 
+## Support Skills
+
+Support skills are installed and governed, but they do not create workflow states. `requirement-analyzer` behaves like `doc-readability`: it can analyze source documents and produce reports without advancing workflow state. `api-designer`, `architecture-designer`, `sql-style`, and `cli-developer` behave like `go-style`: they are discipline lenses applied directly or from workflow skills during design, execution, and review.
+
+`sql-style` is the shared bundled SQL/database lens. It fuses selected SQL optimization, schema, migration, index, and dialect guidance with loopx workflow discipline. Related skills should call `sql-style` when SQL/database discipline is relevant; do not delete useful SQL guidance from those skills merely because `sql-style` exists.
+
 ## Artifacts
 
 Human-maintained v1 skill-suite artifacts use `docs/loopx/`: