@ai-content-space/loopx 0.1.5 → 0.1.6

package/README.md

@@ -140,7 +140,15 @@ loopx status my-task
 loopx status my-task --json
 ```
 
-Render derived HTML reading views:
+Planning also writes derived HTML reading views so the plan can be reviewed without another command:
+
+```text
+.loopx/workflows/my-task/view/index.html
+.loopx/workflows/my-task/view/plan.html
+.loopx/views/index.html
+```
+
+Regenerate derived HTML reading views at any time:
 
 ```bash
 loopx render my-task
@@ -174,7 +182,7 @@ loopx repair-install
 
 The CLI is primarily for runtime, debugging, status inspection, and maintenance. The normal Codex-facing product surface is the bundled skill set, for example `$clarify`, `$plan`, `$build`, `$review`, `$archive`, `$autopilot`, `$debug`, `$tdd`, `$verify`, `$go-style`, and `$kratos`.
 
-`loopx status` remains a CLI/runtime diagnostic command rather than a Codex skill. `loopx render` generates human-readable HTML views from existing runtime artifacts; without a slug it renders every non-legacy workflow plus the workspace index. Markdown and JSON remain the canonical machine-readable and editable sources.
+`loopx status` remains a CLI/runtime diagnostic command rather than a Codex skill. `loopx plan` automatically writes human-readable HTML views for the planned workflow and workspace index. `loopx render` regenerates those views from existing runtime artifacts; without a slug it renders every non-legacy workflow plus the workspace index. Markdown and JSON remain the canonical machine-readable and editable sources.
 
 ## Skill Routing and Governance
 
@@ -224,6 +232,8 @@ Main artifacts:
 - `.loopx/workflows/<slug>/development-plan.md`
 - `.loopx/workflows/<slug>/test-plan.md`
 
+After a successful plan run, loopx also writes derived reading views at `.loopx/workflows/<slug>/view/index.html`, `.loopx/workflows/<slug>/view/plan.html`, and `.loopx/views/index.html`. Use these for human review; keep Markdown and JSON as the editable sources of truth.
+
 `spec-delta.md` uses requirement deltas: `## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`, and `## RENAMED Requirements`. ADDED and MODIFIED entries are full `### Requirement:` blocks with SHALL/MUST language and `#### Scenario:` examples, so archive can merge them into the current long-lived spec state.
 
 ### build
@@ -367,7 +377,7 @@ loopx writes runtime state under `.loopx/` in the current project:
 
 `intake` contains immutable clarify snapshots for a specific request. `workflows` contains the active runtime working set. `changes` contains the proposed change delta for the current request. `specs` contains accepted long-lived behavior after archive.
 
-`views/` and `workflows/<slug>/view/` are derived HTML reading views generated by `loopx render`. They are for human review only and are safe to regenerate; agents and tooling should continue to read and update the Markdown and JSON artifacts.
+`views/` and `workflows/<slug>/view/` are derived HTML reading views written after `plan` and regenerated by `loopx render`. They are for human review only and are safe to regenerate; agents and tooling should continue to read and update the Markdown and JSON artifacts.
 
 ### Document Boundaries
 
@@ -377,7 +387,7 @@ Documents users normally need to watch:
 - `.loopx/workflows/<slug>/spec.md`: the current requirement working copy.
 - `.loopx/workflows/<slug>/plan.md`, `architecture.md`, `development-plan.md`, and `test-plan.md`: the current task's plan, architecture, execution, and verification contract.
 - `.loopx/workflows/<slug>/execution-record.md` and `review-report.md`: execution evidence and review result.
-- `.loopx/views/index.html` and `.loopx/workflows/<slug>/view/index.html`: reading entrypoints generated by `loopx render`.
+- `.loopx/views/index.html` and `.loopx/workflows/<slug>/view/index.html`: reading entrypoints written after `plan` and regenerated by `loopx render`.
 
 Documents users may read and modify as workflow fact sources:
 
@@ -394,7 +404,7 @@ Documents and data the tools depend on, or generate as derived evidence:
 - `.loopx/intake/clarify-*.md`: immutable clarify snapshots for audit and traceability; do not treat them as long-lived specs.
 - `.loopx/changes/active/<change-id>/slices.json` and `artifact-graph.json`: structured planning data consumed by build/review/archive.
 - `.loopx/autopilot/<slug>/run.json` and `.loopx/build-active.json`: orchestration and stop-hook runtime state.
-- `.loopx/views/` and `.loopx/workflows/<slug>/view/`: derived HTML views; they can be deleted and regenerated with `loopx render`, and should not be edited as fact sources.
+- `.loopx/views/` and `.loopx/workflows/<slug>/view/`: derived HTML views; they are written after `plan`, can be deleted and regenerated with `loopx render`, and should not be edited as fact sources.
 
 ## Diagnostics and Repair
 
@@ -511,4 +521,4 @@ node src/cli.mjs status --json
 
 ## Version
 
-Current npm package version: `0.1.4`.
+Current npm package version: `0.1.6`.

package/README.zh-CN.md

@@ -142,7 +142,15 @@ loopx status my-task
 loopx status my-task --json
 ```
 
-生成派生 HTML 阅读视图：
+plan 完成后会自动写入派生 HTML 阅读视图，方便直接审阅计划：
+
+```text
+.loopx/workflows/my-task/view/index.html
+.loopx/workflows/my-task/view/plan.html
+.loopx/views/index.html
+```
+
+需要时也可以重新生成派生 HTML 阅读视图：
 
 ```bash
 loopx render my-task
@@ -176,7 +184,7 @@ loopx repair-install
 
 CLI 主要用于运行时、调试、状态观察和维护。日常面向 Codex 的主入口是同名 skills，例如 `$clarify`、`$plan`、`$build`、`$review`、`$archive`、`$autopilot`、`$debug`、`$tdd`、`$verify`、`$go-style`、`$kratos`。
 
-`loopx status` 仍然是 CLI/runtime 诊断命令，不作为单独 Codex skill 暴露。`loopx render` 会基于现有运行时产物生成给人阅读的 HTML 视图；不传 slug 时会渲染所有非 legacy workflow 和工作区首页。Markdown 和 JSON 仍然是机器可读、可编辑的事实源。
+`loopx status` 仍然是 CLI/runtime 诊断命令，不作为单独 Codex skill 暴露。`loopx plan` 会自动为当前计划 workflow 和工作区首页写入给人阅读的 HTML 视图。`loopx render` 会基于现有运行时产物重新生成这些视图；不传 slug 时会渲染所有非 legacy workflow 和工作区首页。Markdown 和 JSON 仍然是机器可读、可编辑的事实源。
 
 ## Skill 路由与治理
 
@@ -226,6 +234,8 @@ node scripts/verify-skills.mjs
 - `.loopx/workflows/<slug>/development-plan.md`
 - `.loopx/workflows/<slug>/test-plan.md`
 
+plan 成功后，loopx 还会写入派生阅读视图：`.loopx/workflows/<slug>/view/index.html`、`.loopx/workflows/<slug>/view/plan.html` 和 `.loopx/views/index.html`。这些视图用于人工审阅；Markdown 和 JSON 仍然是可编辑事实源。
+
 `spec-delta.md` 使用 requirement delta：`## ADDED Requirements`、`## MODIFIED Requirements`、`## REMOVED Requirements` 和 `## RENAMED Requirements`。ADDED / MODIFIED 必须是完整的 `### Requirement:` 块，包含 SHALL/MUST 约束和 `#### Scenario:` 场景，archive 才能把它们合并进长期 spec 当前状态。
 
 ### build
@@ -378,7 +388,7 @@ loopx 在当前项目下写入 `.loopx/`：
 
 `intake` 保存一次需求的 clarify 快照；`workflows` 保存当前任务的运行时工作副本；`changes` 保存本次需求对长期行为的 change delta；`specs` 只保存 archive 后的长期领域行为契约。
 
-`views/` 和 `workflows/<slug>/view/` 是 `loopx render` 生成的派生 HTML 阅读视图，只服务于人的浏览和评审，可以随时重新生成；agent 和工具仍应读取、修改 Markdown 与 JSON 产物。
+`views/` 和 `workflows/<slug>/view/` 是 plan 后写入、也可由 `loopx render` 重新生成的派生 HTML 阅读视图，只服务于人的浏览和评审；agent 和工具仍应读取、修改 Markdown 与 JSON 产物。
 
 ### 文档关注边界
 
@@ -388,7 +398,7 @@ loopx 在当前项目下写入 `.loopx/`：
 - `.loopx/workflows/<slug>/spec.md`：当前需求工作副本。
 - `.loopx/workflows/<slug>/plan.md`、`architecture.md`、`development-plan.md`、`test-plan.md`：当前任务的计划、架构和验证约定。
 - `.loopx/workflows/<slug>/execution-record.md`、`review-report.md`：执行证据和评审结论。
-- `.loopx/views/index.html` 与 `.loopx/workflows/<slug>/view/index.html`：由 `loopx render` 生成的阅读入口。
+- `.loopx/views/index.html` 与 `.loopx/workflows/<slug>/view/index.html`：plan 后写入、也可由 `loopx render` 重新生成的阅读入口。
 
 用户可以阅读和按流程修改的事实源文档：
 
@@ -405,7 +415,7 @@ loopx 在当前项目下写入 `.loopx/`：
 - `.loopx/intake/clarify-*.md`：clarify 快照，用于审计和追溯；不要当作长期 specs 修改。
 - `.loopx/changes/active/<change-id>/slices.json`、`artifact-graph.json`：计划结构化数据，build/review/archive 会消费。
 - `.loopx/autopilot/<slug>/run.json`、`.loopx/build-active.json`：编排和 stop-hook 运行态。
-- `.loopx/views/` 和 `.loopx/workflows/<slug>/view/`：HTML 派生视图，可删除后用 `loopx render` 重新生成，不应作为事实源编辑。
+- `.loopx/views/` 和 `.loopx/workflows/<slug>/view/`：HTML 派生视图，plan 后自动写入，可删除后用 `loopx render` 重新生成，不应作为事实源编辑。
 
 ## 安装诊断与修复
 
@@ -522,4 +532,4 @@ node src/cli.mjs status --json
 
 ## 版本
 
-当前 npm 包版本：`0.1.4`。
+当前 npm 包版本：`0.1.6`。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-content-space/loopx",
   "type": "module",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Skill-first loopx workflow product for Codex",
   "repository": {
     "type": "git",

package/plugins/loopx/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "loopx",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Skill-first loopx workflow product for Codex",
   "skills": "./skills/",
   "interface": {

package/plugins/loopx/skills/archive/SKILL.md

@@ -3,7 +3,7 @@ name: archive
 description: "Archives an approved loopx change delta into long-lived specs and writes an ADR candidate after done approval. Not for active builds or unapproved reviews."
 when_to_use: "archive, done workflow, spec delta, long-lived specs, ADR candidate, review approved, 归档, 同步规格"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 argument-hint: "<workflow slug>"
 ---
 
@@ -11,7 +11,7 @@ argument-hint: "<workflow slug>"
 
 ## Purpose
 
-Use `archive` after a loopx workflow has reached `done`. It syncs the accepted change delta into long-lived `.loopx/specs/` files, archives the change staging directory, and writes an advisory ADR candidate.
+Use `archive` after a loopx workflow has reached `done`, or immediately after an approved review that is waiting for `review -> done` completion. It syncs the accepted change delta into long-lived `.loopx/specs/` files, archives the change staging directory, and writes an advisory ADR candidate.
 
 The accepted delta is requirement-based, not a changelog block. Archive applies:
 
@@ -24,7 +24,7 @@ into the current long-lived `## Requirements` state for each target domain.
 
 ## Inputs
 
-- `<workflow slug>` for a completed loopx workflow
+- `<workflow slug>` for a completed loopx workflow, or for a review-approved workflow whose next route is `done`
 
 ## Behavior
 
@@ -34,9 +34,12 @@ Run:
 loopx archive <slug>
 ```
 
+If review already approved the workflow and the only pending transition is `review -> done`, this command consumes that completion transition before archiving. Do not ask the user to run a separate `loopx approve <slug> --from review --to done` command in that case.
+
 Then report in Chinese:
 
 - whether the change was archived
+- whether `review -> done` was consumed by archive
 - which long-lived spec files were updated
 - the archived change path
 - the ADR candidate path, if written
@@ -44,7 +47,7 @@ Then report in Chinese:
 
 ## Boundaries
 
-- Do not run archive before `review -> done` has been approved.
+- Do not run archive before review has approved the workflow and routed it to `done`.
 - Do not archive malformed requirement deltas. ADDED and MODIFIED entries must use `### Requirement:`, SHALL/MUST language, and at least one `#### Scenario:`.
 - Do not archive when `execution-record.md` declares non-empty `remaining_scope`, `completion_claim` other than `full`, or a mismatch between `planned_scope` and `implemented_scope`; route back to build/plan instead.
 - Do not edit implementation code.

package/plugins/loopx/skills/autopilot/SKILL.md

@@ -3,7 +3,7 @@ name: autopilot
 description: "Runs one bounded autonomous loopx orchestration over clarify, plan, build, and review while preserving canonical artifacts. Not for manual gate-by-gate control."
 when_to_use: "autopilot, autonomous loopx run, end-to-end workflow, run all stages, bounded orchestration, 自动执行, 全流程"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 argument-hint: "<workflow slug>"
 ---
 

package/plugins/loopx/skills/build/SKILL.md

@@ -3,7 +3,7 @@ name: build
 description: "Executes an approved loopx plan or review rework contract with evidence, verification, deslop, and regression gates. Not for unclear requirements or independent review."
 when_to_use: "build, implement approved plan, execute PRD, --from-review, review rework, implementation fixes, 执行, 实现, 修改"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 argument-hint: "[--no-deslop] <approved PRD path or workflow slug> | --from-review <review artifact path>"
 ---
 
@@ -200,6 +200,8 @@ These support artifacts are runtime aids only. They must not become new canonica
 <Final_Response_Contract>
 When `build` reaches review handoff readiness, the final response must include an explicit next skill command using the execution record path:
 
+Default review handoff after build readiness:
+
 ```text
 Next:
 $review .loopx/workflows/<slug>/execution-record.md

package/plugins/loopx/skills/clarify/SKILL.md

@@ -3,7 +3,7 @@ name: clarify
 description: "Clarifies ambiguous loopx work into requirements, non-goals, decision boundaries, and design-ready specs before planning. Not for already-approved plans or concrete implementation tasks."
 when_to_use: "clarify, requirements, ambiguous request, unclear scope, non-goals, decision boundaries, acceptance criteria, 需求澄清, 范围不清"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 ---
 
 # loopx Clarify
@@ -308,8 +308,11 @@ After the clarify spec is ready:
 
 Preferred explicit handoff contract:
 
-- Recommended invocation: `$plan <slug>`
-- Artifact-pinned invocation when needed: `$plan --direct .loopx/intake/clarify-<slug>-<timestamp>.md`
+- Default handoff after normal loopx clarify: `$plan <slug>`
+- Conditional artifact-pinned handoff: `$plan --direct <spec-path>`
+- Recommend `$plan --direct <spec-path>` when the user explicitly wants to plan from a specific requirements artifact, when the source is external/manual/legacy, or when multiple plausible spec files exist and the user has chosen one as the planning source of truth.
+- Do not use `$plan --direct` to work around unclear workflow state, missing approvals, or an uncertain slug; inspect or repair the loopx runtime state instead.
+- For the normal loopx clarify happy path, prefer `$plan <slug>` because the active workflow slug already anchors the clarify artifact and runtime state.
 - Consumer behavior: treat the clarify spec as the source of truth for intent, non-goals, decision boundaries, constraints, and design direction; do not reopen clarification by default
 
 `clarify` itself does not implement the feature. The handoff recommendation must name `plan` as the next workflow step.

package/plugins/loopx/skills/debug/SKILL.md

@@ -3,7 +3,7 @@ name: debug
 description: "Finds root cause for bugs, failing tests, build failures, regressions, and unexpected behavior before fixes. Not for new feature planning or routine code review."
 when_to_use: "debug, bug, test failure, build failure, regression, unexpected behavior, root cause, 报错, 失败, 回归, 排查"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 ---
 
 # Systematic Debugging

package/plugins/loopx/skills/go-style/SKILL.md

@@ -3,7 +3,7 @@ name: go-style
 description: "Applies loopx Go coding style for .go edits, tests, errors, context, naming, and interface boundaries. Not for non-Go code or Kratos-specific architecture by itself."
 when_to_use: "go-style, Go, golang, .go files, go tests, gofmt, idiomatic Go, Go style, Go 代码"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 ---
 
 # Go Style

package/plugins/loopx/skills/kratos/SKILL.md

@@ -3,7 +3,7 @@ name: kratos
 description: "Supports Go-Kratos microservices, proto/buf APIs, service/biz/data layers, middleware, auth, config, and troubleshooting. Not for generic Go style alone."
 when_to_use: "kratos, Go-Kratos, proto, buf, service layer, biz layer, data layer, middleware, auth, config, Kratos 微服务"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 ---
 
 # Kratos

package/plugins/loopx/skills/plan/SKILL.md

@@ -3,7 +3,7 @@ name: plan
 description: "Creates a consensus-first loopx plan package with Planner, Architect, and Critic review from an approved spec. Not for unresolved requirements or direct implementation."
 when_to_use: "plan, planning, consensus planning, PRD, architecture plan, test plan, approved clarify spec, 规划, 方案, 架构评审"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 argument-hint: "[--interactive] [--deliberate] [--direct <spec-path>] <clarified task or spec path>"
 ---
 
@@ -173,6 +173,14 @@ On approval, write canonical planning artifacts:
 - `.loopx/changes/active/<change-id>/slices.json`
 - `.loopx/changes/active/<change-id>/artifact-graph.json`
 
+Also generate derived HTML reading views:
+
+- `.loopx/workflows/<slug>/view/index.html`
+- `.loopx/workflows/<slug>/view/plan.html`
+- `.loopx/views/index.html`
+
+The HTML files are derived reading views for human plan review. They are not canonical fact sources; Markdown and JSON remain authoritative.
+
 The final plan must include:
 
 - ADR: Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups
@@ -199,6 +207,24 @@ In `--interactive` mode, ask for the next lane:
 Without `--interactive`, report the approved plan and recommended next command, but do not launch execution.
 </Consensus_Workflow>
 
+<Final_Response_Contract>
+Default build handoff after an approved plan package:
+
+```text
+Next:
+$build .loopx/plans/prd-<slug>.md
+```
+
+Use the artifact-first PRD path because it pins build to the approved plan package. Do not emit `$build <slug>` as the primary handoff when `.loopx/plans/prd-<slug>.md` is known. If execution is not approved or plan gates remain blocked, state the blocker instead of emitting a build handoff.
+
+Also report the generated HTML reading entrypoint so the user can review the plan without running another command:
+
+```text
+HTML:
+.loopx/workflows/<slug>/view/index.html
+```
+</Final_Response_Contract>
+
 <Runtime_State_Machine>
 `plan` must keep the planning gate machine-checkable. Runtime state should track:
 
@@ -249,6 +275,7 @@ Primary outputs:
 - approved plan package under `.loopx/workflows/<slug>/`
 - canonical PRD and test spec under `.loopx/plans/`
 - change artifacts under `.loopx/changes/active/<change-id>/`
+- derived HTML reading views under `.loopx/workflows/<slug>/view/` and `.loopx/views/`
 - consensus review summary with Planner / Architect / Critic evidence
 - next-step recommendation
 

package/plugins/loopx/skills/review/SKILL.md

@@ -3,7 +3,7 @@ name: review
 description: "Reviews a loopx build execution record for acceptance, code risks, evidence quality, and architecture smells. Not for doing implementation work or replanning."
 when_to_use: "review, code review, acceptance, go no-go, execution-record, architecture smell, build complete, 审查, 验收"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 argument-hint: "<execution-record path or workflow slug>"
 ---
 
@@ -65,6 +65,8 @@ Every no-go review result must end with a concrete next command block.
 
 For implementation fixes:
 
+Default implementation-fix handoff:
+
 ```text
 Next:
 $build --from-review .loopx/workflows/<slug>/review-report.md

package/plugins/loopx/skills/tdd/SKILL.md

@@ -3,7 +3,7 @@ name: tdd
 description: "Guides feature and bugfix implementation through a failing test before production code and red-green-refactor discipline. Not for generated files or throwaway prototypes."
 when_to_use: "tdd, failing test first, feature implementation, bugfix, regression test, red green refactor, 测试先行"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 ---
 
 # Test-Driven Development (TDD)

package/plugins/loopx/skills/verify/SKILL.md

@@ -3,7 +3,7 @@ name: verify
 description: "Requires fresh verification evidence before claiming work is complete, fixed, passing, review-ready, or ready to commit. Not for speculative confidence or stale results."
 when_to_use: "verify, completion claim, fixed claim, tests pass, review-ready, commit, fresh evidence, 验证, 完成前检查"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 ---
 
 # Verification Before Completion

package/skills/archive/SKILL.md

@@ -3,7 +3,7 @@ name: archive
 description: "Archives an approved loopx change delta into long-lived specs and writes an ADR candidate after done approval. Not for active builds or unapproved reviews."
 when_to_use: "archive, done workflow, spec delta, long-lived specs, ADR candidate, review approved, 归档, 同步规格"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 argument-hint: "<workflow slug>"
 ---
 
@@ -11,7 +11,7 @@ argument-hint: "<workflow slug>"
 
 ## Purpose
 
-Use `archive` after a loopx workflow has reached `done`. It syncs the accepted change delta into long-lived `.loopx/specs/` files, archives the change staging directory, and writes an advisory ADR candidate.
+Use `archive` after a loopx workflow has reached `done`, or immediately after an approved review that is waiting for `review -> done` completion. It syncs the accepted change delta into long-lived `.loopx/specs/` files, archives the change staging directory, and writes an advisory ADR candidate.
 
 The accepted delta is requirement-based, not a changelog block. Archive applies:
 
@@ -24,7 +24,7 @@ into the current long-lived `## Requirements` state for each target domain.
 
 ## Inputs
 
-- `<workflow slug>` for a completed loopx workflow
+- `<workflow slug>` for a completed loopx workflow, or for a review-approved workflow whose next route is `done`
 
 ## Behavior
 
@@ -34,9 +34,12 @@ Run:
 loopx archive <slug>
 ```
 
+If review already approved the workflow and the only pending transition is `review -> done`, this command consumes that completion transition before archiving. Do not ask the user to run a separate `loopx approve <slug> --from review --to done` command in that case.
+
 Then report in Chinese:
 
 - whether the change was archived
+- whether `review -> done` was consumed by archive
 - which long-lived spec files were updated
 - the archived change path
 - the ADR candidate path, if written
@@ -44,7 +47,7 @@ Then report in Chinese:
 
 ## Boundaries
 
-- Do not run archive before `review -> done` has been approved.
+- Do not run archive before review has approved the workflow and routed it to `done`.
 - Do not archive malformed requirement deltas. ADDED and MODIFIED entries must use `### Requirement:`, SHALL/MUST language, and at least one `#### Scenario:`.
 - Do not archive when `execution-record.md` declares non-empty `remaining_scope`, `completion_claim` other than `full`, or a mismatch between `planned_scope` and `implemented_scope`; route back to build/plan instead.
 - Do not edit implementation code.

package/skills/autopilot/SKILL.md

@@ -3,7 +3,7 @@ name: autopilot
 description: "Runs one bounded autonomous loopx orchestration over clarify, plan, build, and review while preserving canonical artifacts. Not for manual gate-by-gate control."
 when_to_use: "autopilot, autonomous loopx run, end-to-end workflow, run all stages, bounded orchestration, 自动执行, 全流程"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 argument-hint: "<workflow slug>"
 ---
 

package/skills/build/SKILL.md

@@ -3,7 +3,7 @@ name: build
 description: "Executes an approved loopx plan or review rework contract with evidence, verification, deslop, and regression gates. Not for unclear requirements or independent review."
 when_to_use: "build, implement approved plan, execute PRD, --from-review, review rework, implementation fixes, 执行, 实现, 修改"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 argument-hint: "[--no-deslop] <approved PRD path or workflow slug> | --from-review <review artifact path>"
 ---
 
@@ -200,6 +200,8 @@ These support artifacts are runtime aids only. They must not become new canonica
 <Final_Response_Contract>
 When `build` reaches review handoff readiness, the final response must include an explicit next skill command using the execution record path:
 
+Default review handoff after build readiness:
+
 ```text
 Next:
 $review .loopx/workflows/<slug>/execution-record.md

package/skills/clarify/SKILL.md

@@ -3,7 +3,7 @@ name: clarify
 description: "Clarifies ambiguous loopx work into requirements, non-goals, decision boundaries, and design-ready specs before planning. Not for already-approved plans or concrete implementation tasks."
 when_to_use: "clarify, requirements, ambiguous request, unclear scope, non-goals, decision boundaries, acceptance criteria, 需求澄清, 范围不清"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 ---
 
 # loopx Clarify
@@ -308,8 +308,11 @@ After the clarify spec is ready:
 
 Preferred explicit handoff contract:
 
-- Recommended invocation: `$plan <slug>`
-- Artifact-pinned invocation when needed: `$plan --direct .loopx/intake/clarify-<slug>-<timestamp>.md`
+- Default handoff after normal loopx clarify: `$plan <slug>`
+- Conditional artifact-pinned handoff: `$plan --direct <spec-path>`
+- Recommend `$plan --direct <spec-path>` when the user explicitly wants to plan from a specific requirements artifact, when the source is external/manual/legacy, or when multiple plausible spec files exist and the user has chosen one as the planning source of truth.
+- Do not use `$plan --direct` to work around unclear workflow state, missing approvals, or an uncertain slug; inspect or repair the loopx runtime state instead.
+- For the normal loopx clarify happy path, prefer `$plan <slug>` because the active workflow slug already anchors the clarify artifact and runtime state.
 - Consumer behavior: treat the clarify spec as the source of truth for intent, non-goals, decision boundaries, constraints, and design direction; do not reopen clarification by default
 
 `clarify` itself does not implement the feature. The handoff recommendation must name `plan` as the next workflow step.

package/skills/debug/SKILL.md

@@ -3,7 +3,7 @@ name: debug
 description: "Finds root cause for bugs, failing tests, build failures, regressions, and unexpected behavior before fixes. Not for new feature planning or routine code review."
 when_to_use: "debug, bug, test failure, build failure, regression, unexpected behavior, root cause, 报错, 失败, 回归, 排查"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 ---
 
 # Systematic Debugging

package/skills/go-style/SKILL.md

@@ -3,7 +3,7 @@ name: go-style
 description: "Applies loopx Go coding style for .go edits, tests, errors, context, naming, and interface boundaries. Not for non-Go code or Kratos-specific architecture by itself."
 when_to_use: "go-style, Go, golang, .go files, go tests, gofmt, idiomatic Go, Go style, Go 代码"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 ---
 
 # Go Style

package/skills/kratos/SKILL.md

@@ -3,7 +3,7 @@ name: kratos
 description: "Supports Go-Kratos microservices, proto/buf APIs, service/biz/data layers, middleware, auth, config, and troubleshooting. Not for generic Go style alone."
 when_to_use: "kratos, Go-Kratos, proto, buf, service layer, biz layer, data layer, middleware, auth, config, Kratos 微服务"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 ---
 
 # Kratos

package/skills/plan/SKILL.md

@@ -3,7 +3,7 @@ name: plan
 description: "Creates a consensus-first loopx plan package with Planner, Architect, and Critic review from an approved spec. Not for unresolved requirements or direct implementation."
 when_to_use: "plan, planning, consensus planning, PRD, architecture plan, test plan, approved clarify spec, 规划, 方案, 架构评审"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 argument-hint: "[--interactive] [--deliberate] [--direct <spec-path>] <clarified task or spec path>"
 ---
 
@@ -173,6 +173,14 @@ On approval, write canonical planning artifacts:
 - `.loopx/changes/active/<change-id>/slices.json`
 - `.loopx/changes/active/<change-id>/artifact-graph.json`
 
+Also generate derived HTML reading views:
+
+- `.loopx/workflows/<slug>/view/index.html`
+- `.loopx/workflows/<slug>/view/plan.html`
+- `.loopx/views/index.html`
+
+The HTML files are derived reading views for human plan review. They are not canonical fact sources; Markdown and JSON remain authoritative.
+
 The final plan must include:
 
 - ADR: Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups
@@ -199,6 +207,24 @@ In `--interactive` mode, ask for the next lane:
 Without `--interactive`, report the approved plan and recommended next command, but do not launch execution.
 </Consensus_Workflow>
 
+<Final_Response_Contract>
+Default build handoff after an approved plan package:
+
+```text
+Next:
+$build .loopx/plans/prd-<slug>.md
+```
+
+Use the artifact-first PRD path because it pins build to the approved plan package. Do not emit `$build <slug>` as the primary handoff when `.loopx/plans/prd-<slug>.md` is known. If execution is not approved or plan gates remain blocked, state the blocker instead of emitting a build handoff.
+
+Also report the generated HTML reading entrypoint so the user can review the plan without running another command:
+
+```text
+HTML:
+.loopx/workflows/<slug>/view/index.html
+```
+</Final_Response_Contract>
+
 <Runtime_State_Machine>
 `plan` must keep the planning gate machine-checkable. Runtime state should track:
 
@@ -249,6 +275,7 @@ Primary outputs:
 - approved plan package under `.loopx/workflows/<slug>/`
 - canonical PRD and test spec under `.loopx/plans/`
 - change artifacts under `.loopx/changes/active/<change-id>/`
+- derived HTML reading views under `.loopx/workflows/<slug>/view/` and `.loopx/views/`
 - consensus review summary with Planner / Architect / Critic evidence
 - next-step recommendation
 

package/skills/review/SKILL.md

@@ -3,7 +3,7 @@ name: review
 description: "Reviews a loopx build execution record for acceptance, code risks, evidence quality, and architecture smells. Not for doing implementation work or replanning."
 when_to_use: "review, code review, acceptance, go no-go, execution-record, architecture smell, build complete, 审查, 验收"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 argument-hint: "<execution-record path or workflow slug>"
 ---
 
@@ -65,6 +65,8 @@ Every no-go review result must end with a concrete next command block.
 
 For implementation fixes:
 
+Default implementation-fix handoff:
+
 ```text
 Next:
 $build --from-review .loopx/workflows/<slug>/review-report.md

package/skills/tdd/SKILL.md

@@ -3,7 +3,7 @@ name: tdd
 description: "Guides feature and bugfix implementation through a failing test before production code and red-green-refactor discipline. Not for generated files or throwaway prototypes."
 when_to_use: "tdd, failing test first, feature implementation, bugfix, regression test, red green refactor, 测试先行"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 ---
 
 # Test-Driven Development (TDD)

package/skills/verify/SKILL.md

@@ -3,7 +3,7 @@ name: verify
 description: "Requires fresh verification evidence before claiming work is complete, fixed, passing, review-ready, or ready to commit. Not for speculative confidence or stale results."
 when_to_use: "verify, completion claim, fixed claim, tests pass, review-ready, commit, fresh evidence, 验证, 完成前检查"
 metadata:
-  version: "0.1.5"
+  version: "0.1.6"
 ---
 
 # Verification Before Completion

package/src/workflow.mjs

@@ -357,7 +357,7 @@ function buildWorkspaceReadme() {
     '- `workflows/<slug>/spec.md`',
     '- `workflows/<slug>/plan.md`, `architecture.md`, `development-plan.md`, and `test-plan.md`',
     '- `workflows/<slug>/execution-record.md` and `review-report.md`',
-    '- `views/index.html` and `workflows/<slug>/view/index.html` after `loopx render`',
+    '- `views/index.html` and `workflows/<slug>/view/index.html` after `loopx plan` or `loopx render`',
     '',
     'Documents users may read and edit as workflow fact sources:',
     '',
@@ -2508,6 +2508,28 @@ async function refreshExecutionStatus(root, state) {
   };
 }
 
+async function renderPlanReadingViews(cwd, root, state, slug) {
+  try {
+    const { renderHtmlViews } = await import('./html-views.mjs');
+    const rendered = await renderHtmlViews(cwd, { slug });
+    return {
+      ...state,
+      html_view_status: 'written',
+      html_view_path: rendered.workflowViewPath,
+      workspace_view_path: rendered.workspaceViewPath,
+      html_view_error: null,
+    };
+  } catch (error) {
+    return {
+      ...state,
+      html_view_status: 'failed',
+      html_view_path: join(root, 'view', 'index.html'),
+      workspace_view_path: join(resolveWorkspaceRoot(cwd), 'views', 'index.html'),
+      html_view_error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
 export async function initWorkspace(cwd, { slug } = {}) {
   const workspaceRoot = resolveWorkspaceRoot(cwd);
   const projectConventions = await inspectProjectConventions(cwd);
@@ -2785,8 +2807,64 @@ export async function approveStage(cwd, slug, { from, to }) {
   return { root, state: next };
 }
 
+function isDoneRoute(value) {
+  return value === TRANSITIONS.REVIEW_TO_DONE || value === STAGES.DONE;
+}
+
+function canArchiveConsumePendingDoneApproval(state) {
+  if (state.current_stage !== STAGES.REVIEW) {
+    return false;
+  }
+  const reviewVerdict = String(state.review_verdict || '').trim().toLowerCase();
+  const reviewApproved = reviewVerdict === 'approve' || reviewVerdict === 'go';
+  const routesToDone = [
+    state.pending_user_decision,
+    state.requested_transition,
+    state.review_route,
+    state.requested_transition_after_review,
+  ].some(isDoneRoute);
+  const completionRequested = [
+    APPROVAL_STATES.REQUESTED,
+    APPROVAL_STATES.APPROVED,
+  ].includes(state.approval?.complete) || state.execution_approved === true || state.execution_approved_for_review === true;
+  return reviewApproved && routesToDone && completionRequested;
+}
+
+async function consumePendingDoneApprovalForArchive(cwd, root, state, slug) {
+  if (!canArchiveConsumePendingDoneApproval(state)) {
+    return { root, state, consumed: false };
+  }
+  const normalized = withRecommendedAction({
+    ...state,
+    review_verdict: 'approve',
+    pending_user_decision: TRANSITIONS.REVIEW_TO_DONE,
+    requested_transition: TRANSITIONS.NONE,
+    approval: {
+      ...state.approval,
+      review: APPROVAL_STATES.APPROVED,
+      complete: state.approval?.complete || APPROVAL_STATES.REQUESTED,
+    },
+  });
+  await writeState(root, normalized);
+  const done = await approveStage(cwd, slug, { from: STAGES.REVIEW, to: STAGES.DONE });
+  return {
+    root: done.root,
+    state: {
+      ...done.state,
+      archive_consumed_pending_done_approval: true,
+    },
+    consumed: true,
+  };
+}
+
 export async function archiveStage(cwd, slug) {
-  const { root, state, slug: normalized } = await loadWorkflowState(cwd, slug, { allowLegacy: false });
+  const loaded = await loadWorkflowState(cwd, slug, { allowLegacy: false });
+  const normalized = loaded.slug;
+  let root = loaded.root;
+  let state = loaded.state;
+  const doneApproval = await consumePendingDoneApprovalForArchive(cwd, root, state, normalized);
+  root = doneApproval.root;
+  state = doneApproval.state;
   if (state.current_stage !== STAGES.DONE || !state.completion_confirmed) {
     throw new Error('archive_requires_done_workflow');
   }
@@ -3004,7 +3082,9 @@ export async function planStage(cwd, slug, options = {}) {
     build_context_manifest_path: buildManifest?.path || buildContextManifestPath(root),
   });
   await writeState(root, next);
-  return { root, state: next, architectReview, criticReview };
+  const renderedNext = await renderPlanReadingViews(cwd, root, next, normalized);
+  await writeState(root, renderedNext);
+  return { root, state: renderedNext, architectReview, criticReview };
 }
 
 export async function buildStage(cwd, slug, options = {}) {