@ai-content-space/loopx 0.2.7 → 0.2.9

package/README.md

@@ -15,7 +15,7 @@
 Recommended v1 flow:
 
 ```text
-clarify -> spec? -> plan -> (subagent-exec | exec) -> final-review -> fix-review? -> finish
+clarify -> spec? -> plan-to-exec -> (subagent-exec | exec) -> final-review -> fix-review? -> finish
 ```
 
 ## Quick start
@@ -54,7 +54,7 @@ Core workflow skills:
 
 - `clarify`: interview until scope, non-goals, constraints, and decision boundaries are clear.
 - `spec`: write a design document or lightweight design note when design decisions are required.
-- `plan`: write a bite-sized implementation plan in the superpowers `writing-plans` style.
+- `plan-to-exec`: write a bite-sized implementation plan in the superpowers `writing-plans` style.
 - `subagent-exec`: execute an approved plan with fresh subagents and staged review.
 - `exec`: execute an approved plan inline when subagents are unavailable or not desired.
 - `review`: request independent code review against a git range and plan or requirements.
@@ -86,6 +86,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/`.
@@ -100,7 +110,7 @@ archive is not part of the public v1 finish flow. Older runtime state may still
 
 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 +169,8 @@ loopx doctor
 Undo installed files when you want to remove loopx-managed user-level artifacts:
 
 ```bash
-rm -rf ~/.agents/skills/{clarify,spec,plan,subagent-exec,exec,review,final-review,fix-review,finish,refactor-plan,tdd,debug,verify,go-style,kratos}
-rm -rf ~/.claude/skills/{clarify,spec,plan,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,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 -f ~/.codex/hooks/codex-workflow-hook.mjs ~/.claude/hooks/loopx-workflow-hook.mjs
 ```
 
@@ -171,10 +181,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 +211,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]
@@ -232,7 +245,7 @@ loopx status my-feature
 loopx next my-feature
 ```
 
-After `clarify`, hand control to the suggested skill command, usually `$plan <slug>`. Continue following `loopx status <slug>` or `loopx next <slug>` until `final-review` and `$finish` complete the work.
+After `clarify`, hand control to the suggested skill command, usually `$plan-to-exec <slug>`. Continue following `loopx status <slug>` or `loopx next <slug>` until `final-review` and `$finish` complete the work.
 
 ## Governance
 

package/README.zh-CN.md

@@ -15,7 +15,7 @@
 推荐 v1 流程：
 
 ```text
-clarify -> spec? -> plan -> (subagent-exec | exec) -> final-review -> fix-review? -> finish
+clarify -> spec? -> plan-to-exec -> (subagent-exec | exec) -> final-review -> fix-review? -> finish
 ```
 
 ## 快速开始
@@ -44,7 +44,7 @@ loopx install-skills --target all --json
 
 默认 init 路径也可以使用 JSON 输出：`loopx init --json`。
 
-`spec` 是条件设计门。涉及 API、数据、状态、权限、迁移、兼容、产品行为或架构决策时使用；只剩局部实现选择时可以跳过，直接进入 `plan`。
+`spec` 是条件设计门。涉及 API、数据、状态、权限、迁移、兼容、产品行为或架构决策时使用；只剩局部实现选择时可以跳过，直接进入 `plan-to-exec`。
 
 ## Skills
 
@@ -54,7 +54,7 @@ loopx install-skills --target all --json
 
 - `clarify`：持续追问直到范围、非目标、约束和决策边界清楚。
 - `spec`：在需要设计决策时写设计文档或轻量 design note。
-- `plan`：按 superpowers `writing-plans` 风格写小步实施计划。
+- `plan-to-exec`：按 superpowers `writing-plans` 风格写小步实施计划。
 - `subagent-exec`：用 fresh subagents 和 staged review 执行已批准计划。
 - `exec`：没有 subagent 或用户选择 inline 时顺序执行计划。
 - `review`：基于 git range 和计划/需求发起独立代码评审。
@@ -86,6 +86,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/`。
@@ -100,7 +110,7 @@ archive 不属于公开 v1 finish 流程。旧 runtime state 仍可能包含 arc
 
 生成的支撑状态、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 +169,8 @@ loopx doctor
 撤销已安装文件，移除 loopx 管理的用户级 artifacts：
 
 ```bash
-rm -rf ~/.agents/skills/{clarify,spec,plan,subagent-exec,exec,review,final-review,fix-review,finish,refactor-plan,tdd,debug,verify,go-style,kratos}
-rm -rf ~/.claude/skills/{clarify,spec,plan,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,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 -f ~/.codex/hooks/codex-workflow-hook.mjs ~/.claude/hooks/loopx-workflow-hook.mjs
 ```
 
@@ -171,10 +181,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 +211,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]
@@ -232,7 +245,7 @@ loopx status my-feature
 loopx next my-feature
 ```
 
-`clarify` 之后，把控制权交给提示的 skill 命令，通常是 `$plan <slug>`。后续继续跟随 `loopx status <slug>` 或 `loopx next <slug>`，直到 `final-review` 和 `$finish` 完成收尾。
+`clarify` 之后，把控制权交给提示的 skill 命令，通常是 `$plan-to-exec <slug>`。后续继续跟随 `loopx status <slug>` 或 `loopx next <slug>`，直到 `final-review` 和 `$finish` 完成收尾。
 
 ## 治理
 

package/docs/loopx/design/finish/345/255/246/344/271/240/345/256/241/350/256/241/351/234/200/346/261/202/350/256/276/350/256/241/346/226/207/346/241/243.md

@@ -687,7 +687,7 @@ erDiagram
 - 推荐下一步：
 
 ```text
-$plan docs/loopx/design/finish学习审计需求设计文档.md
+$plan-to-exec docs/loopx/design/finish学习审计需求设计文档.md
 ```
 
 ## 十一、QA

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

@@ -10,7 +10,7 @@ The v1 product surface is the installed and governed bundled skill suite:
 
 - `clarify`
 - `spec`
-- `plan`
+- `plan-to-exec`
 - `subagent-exec`
 - `exec`
 - `review`
@@ -33,12 +33,12 @@ The repository may retain auxiliary or compatibility skill source directories fo
 Recommended flow:
 
 ```text
-clarify -> spec? -> plan -> (subagent-exec | exec) -> final-review -> fix-review? -> finish
+clarify -> spec? -> plan-to-exec -> (subagent-exec | exec) -> final-review -> fix-review? -> finish
 ```
 
-`spec` is a conditional design gate. `clarify` may route directly to `plan` when the remaining questions are local implementation choices. It routes to `spec` when product behavior, APIs, state, data, permissions, migration, compatibility, or architecture decisions need to be fixed before implementation planning.
+`spec` is a conditional design gate. `clarify` may route directly to `plan-to-exec` when the remaining questions are local implementation choices. It routes to `spec` when product behavior, APIs, state, data, permissions, migration, compatibility, or architecture decisions need to be fixed before implementation planning.
 
-`plan` is the superpowers `writing-plans` workflow under the loopx name. It writes executable plans and offers two execution options: `subagent-exec` recommended, or `exec` inline.
+`plan-to-exec` is the superpowers `writing-plans` workflow under the loopx name. It writes executable plans and offers two execution options: `subagent-exec` recommended, or `exec` inline.
 
 `review` is the task or checkpoint code review workflow inside `subagent-exec` or `exec`. `final-review` is the top-level whole-feature runtime, integration, and test-gap review before completion. `fix-review` handles feedback from either review layer.