@ai-content-space/loopx 0.2.3 → 0.2.7

package/README.md

@@ -18,6 +18,32 @@ Recommended v1 flow:
 clarify -> spec? -> plan -> (subagent-exec | exec) -> final-review -> fix-review? -> finish
 ```
 
+## Quick start
+
+```bash
+loopx install-skills --target all --yes
+loopx init --slug my-feature
+loopx clarify my-feature
+loopx status my-feature
+```
+
+For the shortest next-step prompt after a workflow exists, run:
+
+```bash
+loopx next my-feature
+```
+
+Human output is the default for first-use commands such as `loopx init`, `loopx clarify`, `loopx status`, `loopx doctor`, and `loopx install-skills`. Use `--json` when an agent or script needs the complete runtime payload:
+
+```bash
+loopx init --slug my-feature --json
+loopx clarify my-feature --json
+loopx doctor --json
+loopx install-skills --target all --json
+```
+
+The JSON flag also works on the default init path: `loopx init --json`.
+
 `spec` is conditional. Use it when API, data, state, permission, migration, compatibility, product behavior, or architecture decisions must be fixed before planning. Skip it when the remaining work is local implementation choice.
 
 ## Skills
@@ -55,12 +81,23 @@ For the v1 skill-suite workflow, human-maintained artifacts live under `docs/loo
 - `docs/loopx/plans/`
 - `docs/loopx/reviews/`
 - `docs/loopx/refactors/`
+- `docs/loopx/memory/`
 - `docs/loopx/specs/`
 
+`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.
+
 `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/`.
+
+Finish runtime commands are advanced agent/runtime plumbing, not the normal user path. `finish-start` records the starting commit for plan execution, and `finish-audit` uses that baseline to include committed `baseline..HEAD` evidence, changed files, and uncommitted status in `.loopx/finish/<audit-id>/finish-state.json` as `audit.change_window`, so finish learning/spec extraction still has input after the worktree is clean. It also writes draft `audit.extraction_candidates` for memory/spec review; agents must accept or reject those drafts before recording a done finish choice.
+
 `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/`:
@@ -72,6 +109,8 @@ Local agent memory lives under `.loopx/memory/`:
 
 `MEMORY.md` is a bounded curated project memory summary. `index.jsonl` is a curated active index for agent file-search, not an append-only log.
 
+Shared agent memory lives under `docs/loopx/memory/`. It is repo-tracked for multi-machine continuity and should stay concise, evidence-backed, and below spec-level stability.
+
 ## Installation
 
 Install globally:
@@ -87,6 +126,44 @@ Postinstall installs user-level skills and hooks for Codex and Claude:
 - Codex hook: `~/.codex/hooks/codex-workflow-hook.mjs`
 - Claude hook: `~/.claude/hooks/loopx-workflow-hook.mjs`
 
+To inspect without writing files:
+
+```bash
+loopx install-skills --target all --dry-run
+```
+
+Use the explicit target form for dry-run checks so the command stays non-interactive.
+
+Successful install output lists the targets and installed skill roots. `loopx install-skills --json` includes the full inspection payload for scripts and support cases.
+
+To opt out during npm postinstall:
+
+```bash
+LOOPX_SKIP_POSTINSTALL=1 npm install -g @ai-content-space/loopx
+LOOPX_POSTINSTALL=0 npm install -g @ai-content-space/loopx
+```
+
+To disable loopx hooks for one process:
+
+```bash
+LOOPX_HOOKS=0 codex
+```
+
+Repair an interrupted or conflicted install with:
+
+```bash
+loopx repair-install
+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 -f ~/.codex/hooks/codex-workflow-hook.mjs ~/.claude/hooks/loopx-workflow-hook.mjs
+```
+
 Run the installer manually or choose targets interactively:
 
 ```bash
@@ -121,23 +198,42 @@ 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]
-loopx init [--slug <slug>] [--enable-agent-delegation] [--auto-agent-delegation] [--agent-delegation-threshold <local|critic-only|parallel-review>]
-loopx clarify <slug> [--standard|--deep]
-loopx approve <slug> --from <stage> --to <stage>
-loopx plan [slug] [--interactive] [--deliberate]
-loopx build <slug> [--no-deslop]
-loopx build --from-review <review-report-path> [--no-deslop]
-loopx review <slug> [--reviewer <name>]
-loopx autopilot <slug> [--reviewer <name>]
+loopx install-skills [--target <codex|claude|all>] [--project] [--mode <copy|symlink>] [--dir <path>] [--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]
 loopx status [slug] [--json]
+loopx next <slug> [--json]
 loopx setup-context
-loopx doctor
+loopx doctor [--json]
 loopx migrate
 loopx repair-install
 ```
 
+Advanced runtime commands:
+
+```bash
+loopx help advanced
+```
+
+These commands are kept for skills, hooks, and compatibility paths. Normal users should follow `loopx status`, `loopx next`, and the suggested skill commands.
+
+## Golden path
+
+This is the smallest complete first-run loop:
+
+```bash
+loopx install-skills --target all --dry-run
+loopx install-skills --target all --yes
+loopx doctor
+loopx init --slug my-feature
+loopx clarify my-feature
+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.
+
 ## Governance
 
 The bundled skill resolver lives at:

package/README.zh-CN.md

@@ -18,6 +18,32 @@
 clarify -> spec? -> plan -> (subagent-exec | exec) -> final-review -> fix-review? -> finish
 ```
 
+## 快速开始
+
+```bash
+loopx install-skills --target all --yes
+loopx init --slug my-feature
+loopx clarify my-feature
+loopx status my-feature
+```
+
+工作流存在后，如果只想看下一步命令：
+
+```bash
+loopx next my-feature
+```
+
+默认输出面向人类，例如 `loopx init`、`loopx clarify`、`loopx status`、`loopx doctor` 和 `loopx install-skills`。当 agent 或脚本需要完整 runtime payload 时使用 `--json`：
+
+```bash
+loopx init --slug my-feature --json
+loopx clarify my-feature --json
+loopx doctor --json
+loopx install-skills --target all --json
+```
+
+默认 init 路径也可以使用 JSON 输出：`loopx init --json`。
+
 `spec` 是条件设计门。涉及 API、数据、状态、权限、迁移、兼容、产品行为或架构决策时使用；只剩局部实现选择时可以跳过，直接进入 `plan`。
 
 ## Skills
@@ -55,12 +81,23 @@ v1 skill-suite 工作流的人工维护长期产物放在 `docs/loopx/`：
 - `docs/loopx/plans/`
 - `docs/loopx/reviews/`
 - `docs/loopx/refactors/`
+- `docs/loopx/memory/`
 - `docs/loopx/specs/`
 
+`docs/loopx/memory/` 用于保存纳入 git 的 shared memory，适合需要跟随用户跨机器同步、但还没有稳定到 spec 级别的轻量项目知识。
+
 当完成的工作产生稳定团队规则时，`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/`。
+
+Finish runtime 命令是给 agent、hooks 和兼容路径使用的高级 plumbing，不是普通用户主路径。`finish-start` 会记录计划执行开始时的提交，`finish-audit` 使用这个基线把已提交的 `baseline..HEAD` 证据、变更文件和未提交状态写入 `.loopx/finish/<audit-id>/finish-state.json` 的 `audit.change_window`，因此即使执行过程中已经 commit、当前工作区是 clean，finish 的记忆/spec 提取仍有稳定输入。它还会写入用于记忆/spec 审核的草稿 `audit.extraction_candidates`；agent 必须接受或拒绝这些草稿后，才能把 finish choice 记录为 done。
+
 `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/`：
@@ -72,6 +109,8 @@ v1 skill-suite 工作流的人工维护长期产物放在 `docs/loopx/`：
 
 `MEMORY.md` 是有上限的 curated project memory summary。`index.jsonl` 是用于 agent 文件检索的 curated active index，不是 append-only log。
 
+shared agent memory 放在 `docs/loopx/memory/`。它会纳入 repo，用于多机器连续性；内容应简短、有证据，并且还没有稳定到 spec 级别。
+
 ## 安装
 
 全局安装：
@@ -87,6 +126,44 @@ postinstall 默认安装 Codex 和 Claude 用户级 skills 与 hooks：
 - Codex hook：`~/.codex/hooks/codex-workflow-hook.mjs`
 - Claude hook：`~/.claude/hooks/loopx-workflow-hook.mjs`
 
+只检查、不写文件：
+
+```bash
+loopx install-skills --target all --dry-run
+```
+
+dry-run 检查使用显式 target，避免命令进入交互选择。
+
+安装成功后的输出会列出 targets 和安装到的 skill roots。`loopx install-skills --json` 会输出完整 inspection payload，供脚本和排查使用。
+
+npm postinstall 阶段跳过自动安装：
+
+```bash
+LOOPX_SKIP_POSTINSTALL=1 npm install -g @ai-content-space/loopx
+LOOPX_POSTINSTALL=0 npm install -g @ai-content-space/loopx
+```
+
+只在当前进程禁用 loopx hooks：
+
+```bash
+LOOPX_HOOKS=0 codex
+```
+
+修复中断或冲突的安装：
+
+```bash
+loopx repair-install
+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 -f ~/.codex/hooks/codex-workflow-hook.mjs ~/.claude/hooks/loopx-workflow-hook.mjs
+```
+
 也可以手动运行安装器或交互式选择目标：
 
 ```bash
@@ -121,23 +198,42 @@ CLI 用于安装、诊断、渲染和 runtime 维护：
 
 ```bash
 loopx --version
-loopx install-skills [--target <codex|claude|all>] [--project] [--mode <copy|symlink>] [--dir <path>] [--yes]
-loopx init [--slug <slug>] [--enable-agent-delegation] [--auto-agent-delegation] [--agent-delegation-threshold <local|critic-only|parallel-review>]
-loopx clarify <slug> [--standard|--deep]
-loopx approve <slug> --from <stage> --to <stage>
-loopx plan [slug] [--interactive] [--deliberate]
-loopx build <slug> [--no-deslop]
-loopx build --from-review <review-report-path> [--no-deslop]
-loopx review <slug> [--reviewer <name>]
-loopx autopilot <slug> [--reviewer <name>]
+loopx install-skills [--target <codex|claude|all>] [--project] [--mode <copy|symlink>] [--dir <path>] [--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]
 loopx status [slug] [--json]
+loopx next <slug> [--json]
 loopx setup-context
-loopx doctor
+loopx doctor [--json]
 loopx migrate
 loopx repair-install
 ```
 
+高级 runtime 命令：
+
+```bash
+loopx help advanced
+```
+
+这些命令保留给 skills、hooks 和兼容路径。普通用户应跟随 `loopx status`、`loopx next` 和提示的 skill 命令。
+
+## 黄金路径
+
+最小完整首次使用路径：
+
+```bash
+loopx install-skills --target all --dry-run
+loopx install-skills --target all --yes
+loopx doctor
+loopx init --slug my-feature
+loopx clarify my-feature
+loopx status my-feature
+loopx next my-feature
+```
+
+`clarify` 之后，把控制权交给提示的 skill 命令，通常是 `$plan <slug>`。后续继续跟随 `loopx status <slug>` 或 `loopx next <slug>`，直到 `final-review` 和 `$finish` 完成收尾。
+
 ## 治理
 
 bundled skill resolver 位于：