helloloop 0.1.1 → 0.1.2

package/.codex-plugin/plugin.json

@@ -1,11 +1,11 @@
 {
   "name": "helloloop",
-  "version": "0.1.1",
-  "description": "Backlog-driven continuous repository execution for Codex with verification loops and explicit skill and CLI entrypoints.",
+  "version": "0.1.2",
+  "description": "面向 Codex 的 backlog 驱动持续开发插件，支持进度分析、验证循环与显式 skill / CLI 入口。",
   "author": {
     "name": "HelloLoop"
   },
-  "license": "MIT",
+  "license": "Apache-2.0",
   "keywords": [
     "codex",
     "helloloop",
@@ -16,8 +16,8 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "HelloLoop",
-    "shortDescription": "Continuous repo execution with backlog and Ralph Loop guards",
-    "longDescription": "HelloLoop packages backlog-driven continuous development for Codex as an official plugin bundle with explicit skill and CLI entrypoints.",
+    "shortDescription": "基于 backlog 的持续仓库开发与验证循环",
+    "longDescription": "HelloLoop 把基于 backlog 的持续开发能力封装为官方 Codex 插件 bundle，支持自动分析进度、生成后续任务，并通过显式 skill / CLI 入口接续推进。",
     "developerName": "HelloLoop",
     "category": "Coding",
     "capabilities": [
@@ -25,7 +25,7 @@
       "Write"
     ],
     "defaultPrompt": [
-      "Use HelloLoop to inspect backlog state and keep this repo moving with explicit run-loop commands."
+      "使用 HelloLoop 分析当前 backlog 与开发进度，并通过显式命令持续推进这个仓库。"
     ],
     "brandColor": "#0F766E"
   }

package/LICENSE

@@ -0,0 +1,176 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -1,70 +1,57 @@
 # HelloLoop
 
-`HelloLoop` 是一个面向 Codex 的独立插件，用来把“按 backlog 持续推进仓库开发”这件事标准化、可追踪、可验证地跑起来。
+`HelloLoop` 是一个面向 Codex 的独立插件，用来把“根据开发文档接续推进仓库开发”这件事标准化、可追踪、可验证地跑起来。
 
-它不只是在单轮对话里改一段代码，而是把任务队列、必读文档、执行约束、验证命令和运行记录统一放进目标仓库的 `.helloloop/` 目录，让 Codex 可以按明确流程持续接续开发。
+它会先分析当前仓库真实代码与开发文档之间的差距，再把后续任务、运行状态、执行记录统一写入目标仓库根目录的 `.helloloop/`，让 Codex 能持续接着做，而不是每轮都重新交代背景。
 
 命令入口按 `Node.js 20+` 设计，支持 Windows、macOS 和 Linux。
 
 ## 目录
 
-- [HelloLoop 是什么](#helloloop-是什么)
-- [核心能力](#核心能力)
-- [适用场景](#适用场景)
+- [核心定位](#核心定位)
 - [安装](#安装)
 - [快速开始](#快速开始)
+- [路径规则](#路径规则)
+- [安全底线](#安全底线)
 - [命令速查](#命令速查)
 - [状态目录](#状态目录)
-- [工作机制](#工作机制)
+- [在 Codex 中使用](#在-codex-中使用)
+- [许可证](#许可证)
 - [仓库结构](#仓库结构)
 - [相关文档](#相关文档)
 
-## HelloLoop 是什么
+## 核心定位
 
-`HelloLoop` 解决的是以下问题：
+`HelloLoop` 适合这样的场景：
 
-- 你的仓库里已经有开发文档、任务拆解或 backlog
-- 你希望 Codex 能按顺序接着做，而不是每次都从头解释背景
-- 你希望每一轮执行前都自动带上项目状态、必读文档和实现约束
-- 你希望每次运行后都留下状态记录、验证结果和运行痕迹
+- 仓库里已经有 `docs/`、方案包、任务文档或阶段说明
+- 代码已经做了一部分，需要先判断“现在做到哪里了”
+- 你希望自动生成足够细的后续 backlog，而不是得到一句“继续开发”
+- 你希望后续每轮执行都带着状态、约束、文档和验证命令继续推进
+- 你希望在开发文档约束不完整时，仍然有一层稳定、安全的执行底线
 
-围绕这个目标，`HelloLoop` 提供了一套明确的仓库内执行模型：
+围绕这个目标，`HelloLoop` 做四件事：
 
-1. 从 backlog 中选择当前可执行任务
-2. 汇总项目上下文、任务目标和约束
-3. 生成面向 Codex 的执行提示
-4. 调用 Codex 完成实现
-5. 执行验证命令
-6. 回写状态、日志和运行记录
+1. 自动发现项目仓库与开发文档
+2. 对比当前代码和文档目标，判断真实进度
+3. 生成或刷新 `.helloloop/backlog.json`
+4. 驱动 Codex 按 backlog 接续执行并留下运行记录
 
-## 核心能力
+同时，`HelloLoop` 自带一层内建安全底线：
 
-- **插件安装**：安装到 Codex Home，作为独立插件使用
-- **仓库初始化**：在目标仓库生成 `.helloloop/` 状态目录
-- **任务调度**：基于优先级、依赖、风险等级挑选下一任务
-- **干跑预览**：先看下一任务、提示词和验证命令，再决定是否执行
-- **单轮执行**：执行一个任务并回写结果
-- **循环执行**：连续执行多个任务，直到完成、阻塞或达到上限
-- **验证联动**：优先使用任务级验证命令，缺省时读取仓库验证配置
-- **运行留痕**：把提示词、stdout、stderr、验证输出沉淀到 `runs/`
-
-## 适用场景
-
-- 你有一套开发文档，希望 Codex 接续完成后续开发
-- 你有清晰 backlog，希望 AI 按队列逐项推进
-- 你希望把“任务、约束、验证、结果”都放在仓库里长期维护
-- 你希望执行失败后不是停住，而是能按既定策略继续推进
-- 你希望多人协作时，每个人都能快速看懂当前任务状态
+- 开发文档缺少必要约束时，自动补上默认工程约束
+- Windows 端优先使用 `pwsh`，也支持 `bash`（如 Git Bash）和 `powershell`，但不回退到 `cmd`
+- 所有流程都要求避免静默失败、危险命令和隐私信息泄露
 
 ## 安装
 
-### 通过 npm / npx 安装
+### npm / npx
 
 ```powershell
 npx helloloop install --codex-home <CODEX_HOME>
 ```
 
-### 从源码仓库安装
+### 源码仓库
 
 ```powershell
 node ./scripts/helloloop.mjs install --codex-home <CODEX_HOME>
@@ -76,17 +63,7 @@ node ./scripts/helloloop.mjs install --codex-home <CODEX_HOME>
 pwsh -NoLogo -NoProfile -File .\scripts\install-home-plugin.ps1 -CodexHome <CODEX_HOME>
 ```
 
-安装完成后，插件会被放到：
-
-```text
-<CODEX_HOME>\plugins\helloloop
-```
-
-同时会更新：
-
-```text
-<CODEX_HOME>\.agents\plugins\marketplace.json
-```
+安装完成后，插件会复制到 `<CODEX_HOME>/plugins/helloloop`，并更新 `<CODEX_HOME>/.agents/plugins/marketplace.json`。
 
 ## 快速开始
 
@@ -96,68 +73,106 @@ pwsh -NoLogo -NoProfile -File .\scripts\install-home-plugin.ps1 -CodexHome <CODE
 npx helloloop install --codex-home <CODEX_HOME>
 ```
 
-之后的日常命令推荐直接使用：
+### 2. 进入目标项目或开发文档目录
+
+最短命令就是：
 
 ```powershell
-npx helloloop <command> [options]
+npx helloloop
 ```
 
-如果你已经全局安装过：
+默认规则如下：
+
+- 当前目录是项目仓库根目录时：自动查找开发文档并分析当前进度
+- 当前目录本身是开发文档目录时：优先尝试反推目标仓库
+- 分析完成后：自动生成或刷新目标仓库根目录下的 `.helloloop/`
+
+如果你只知道一个路径，也可以只传一个位置：
 
 ```powershell
-helloloop <command> [options]
+npx helloloop <PATH>
 ```
 
-在 Codex 当前会话里，也可以直接运行同样的 `npx helloloop ...` 命令，不需要重开终端。
+这里的 `<PATH>` 只能传一个，可以是：
+
+- 项目仓库路径
+- 开发文档目录
+- 开发文档文件
 
-### 2. 在目标仓库初始化 `.helloloop/`
+### 3. 查看下一任务
 
 ```powershell
-npx helloloop init --repo <REPO_ROOT>
+npx helloloop next
 ```
 
-初始化完成后，模板会落在目标仓库根目录下的 `.helloloop/`，而不是插件目录本身。
-
-### 3. 检查运行条件
+### 4. 执行一次或连续执行
 
 ```powershell
-npx helloloop doctor --repo <REPO_ROOT>
+npx helloloop run-once
+npx helloloop run-loop --max-tasks 2
 ```
 
-### 4. 查看状态与下一任务
+如果你已经做了全局安装，也可以把 `npx helloloop` 简写成 `helloloop`。
+
+## 路径规则
+
+- 不传路径：默认分析当前目录
+- 只传一个路径：自动判断它是仓库路径还是开发文档路径
+- 已给开发文档但无法确定仓库：停止并提示补充 `--repo`
+- 已给仓库但找不到开发文档：停止并提示补充 `--docs`
+- `--repo` 和 `--docs` 是高级覆盖选项，不是主工作流
+
+推荐优先使用：
 
 ```powershell
-npx helloloop status --repo <REPO_ROOT>
-npx helloloop next --repo <REPO_ROOT>
+npx helloloop
+npx helloloop <PATH>
 ```
 
-### 5. 执行一个任务或连续执行
+只有在自动发现无法收敛时，再显式补充：
 
 ```powershell
-npx helloloop run-once --repo <REPO_ROOT>
-npx helloloop run-loop --repo <REPO_ROOT> --max-tasks 2
+npx helloloop --repo <REPO_ROOT> --docs <DOCS_PATH>
 ```
 
+## 安全底线
+
+- `HelloLoop` 会始终附加一组内建安全底线，覆盖 shell 安全、EHRB 命令阻断、跨平台兼容和静默失败防护。
+- 如果项目开发文档或 `.helloloop/project.json` 已有明确约束，则优先使用项目约束；内建安全底线继续作为最低边界。
+- 如果项目没有给出必要约束，则自动启用默认工程约束，例如代码是事实源、体积控制、验证必须执行、阻塞必须明确说明。
+- Windows 环境下，`HelloLoop` 优先使用 `pwsh`，也支持 `bash`（如 Git Bash）和 `powershell`；如果这些安全 shell 都不可用，会直接停止，而不是回退到 `cmd.exe`。
+- macOS / Linux 环境下，`HelloLoop` 优先使用 `bash`，没有 `bash` 时再回退到 `sh`。
+
 ## 命令速查
 
 | 命令 | 作用 |
 | --- | --- |
-| `install` | 安装插件到 Codex Home，并更新插件 marketplace |
-| `init` | 初始化目标仓库的 `.helloloop/` |
-| `doctor` | 检查 Codex、插件文件和目标仓库配置是否齐备 |
-| `status` | 查看 backlog 汇总、当前状态和下一任务 |
-| `next` | 生成下一任务预览，不真正调用 Codex |
+| `analyze` | 自动发现仓库与开发文档，分析进度并刷新 `.helloloop/` |
+| `next` | 预览下一任务，不真正执行 |
 | `run-once` | 执行一个任务 |
 | `run-loop` | 连续执行多个任务 |
+| `status` | 查看 backlog 汇总与当前状态 |
+| `doctor` | 检查 Codex、插件 bundle 与目标仓库是否满足运行条件 |
+| `init` | 手动初始化 `.helloloop/` 模板 |
+| `install` | 安装插件到 Codex Home |
+
+除 `install` 外，其余命令都可以直接在目标仓库目录执行；如果不在目标仓库目录，也可以补一个路径：
+
+```powershell
+npx helloloop next <PATH>
+npx helloloop run-once <PATH>
+npx helloloop status <PATH>
+```
 
 ### 常用选项
 
 | 选项 | 说明 |
 | --- | --- |
-| `--repo <dir>` | 目标仓库根目录，默认当前目录 |
+| `--repo <dir>` | 高级选项：显式指定项目仓库根目录 |
+| `--docs <dir\|file>` | 高级选项：显式指定开发文档目录或文件 |
 | `--codex-home <dir>` | 指定 Codex Home |
 | `--config-dir <dir>` | 指定状态目录名，默认 `.helloloop` |
-| `--dry-run` | 只生成提示词和预览，不真正调用 Codex |
+| `--dry-run` | 只生成提示和预览，不真正调用 Codex |
 | `--task-id <id>` | 指定执行某个任务 |
 | `--max-tasks <n>` | `run-loop` 最多执行的任务数 |
 | `--max-attempts <n>` | 每种策略的最大重试次数 |
@@ -177,7 +192,7 @@ helloloop:helloloop
 
 ## 状态目录
 
-`HelloLoop` 默认在目标仓库根目录创建 `.helloloop/`，用来保存 backlog、策略配置、运行状态和执行留痕。
+`HelloLoop` 默认在目标仓库根目录创建 `.helloloop/`，而不是写回插件目录自身。
 
 典型结构如下：
 
@@ -191,50 +206,26 @@ helloloop:helloloop
 └── runs/
 ```
 
-各文件作用如下：
+各文件职责如下：
 
-- `backlog.json`：任务列表、优先级、风险、依赖、验收条件
-- `policy.json`：循环上限、重试策略、Codex 执行参数
-- `project.json`：全局必读文档、实现约束、任务规划提示
+- `backlog.json`：接续开发任务列表
+- `policy.json`：循环上限、重试策略和 Codex 参数
+- `project.json`：开发文档入口和全局约束
 - `status.json`：最近一次运行的机器可读状态
 - `STATE.md`：面向人的当前进展摘要
-- `runs/`：每次执行的提示词、日志和验证输出
-
-## 工作机制
-
-### 任务模型
-
-`backlog.json` 中的任务通常包含以下字段：
-
-- `id`：任务唯一标识
-- `title`：任务标题
-- `status`：`pending`、`in_progress`、`done`、`failed`、`blocked`
-- `priority`：`P0` 到 `P3`
-- `risk`：`low`、`medium`、`high`、`critical`
-- `goal`：本任务要达成的目标
-- `docs`：执行前必须阅读的文档
-- `paths`：本任务主要涉及的目录
-- `acceptance`：验收条件
-- `dependsOn`：依赖的上游任务
-- `verify`：任务专属验证命令
+- `runs/`：提示词、stdout、stderr、验证输出等运行留痕
 
-### 执行流程
+## 在 Codex 中使用
 
-`HelloLoop` 在每一轮执行中会完成这些事情：
+可以。
 
-1. 找出当前可执行任务
-2. 读取仓库状态、任务描述和必读文档
-3. 生成清晰的 Codex 执行提示
-4. 运行 Codex 完成开发
-5. 执行验证命令
-6. 更新任务状态和运行记录
+- 在当前 Codex 会话里，直接运行 `npx helloloop ...` 即可，不需要重开终端
+- 如果你使用的是全局安装后的 `helloloop` 短命令，是否需要新终端取决于你的 shell 是否已经刷新 PATH
+- `HelloLoop` 负责组织分析、backlog 和执行流程，真正的代码分析与开发仍然通过本机 `codex` CLI 完成
 
-### 风险控制
+## 许可证
 
-- 默认优先自动执行 `low` 风险任务
-- 较高风险任务需要显式允许
-- 存在未完成依赖时，任务不会被挑选执行
-- 存在未收束的执行状态时，循环会停止并等待处理
+`HelloLoop` 使用 `Apache-2.0` 许可证，许可证文件位于仓库根目录 `LICENSE`。
 
 ## 仓库结构
 
@@ -252,12 +243,12 @@ helloloop/
 
 其中：
 
-- `src/` 用来放 `HelloLoop` 的实际实现逻辑，例如任务选择、状态加载、执行流程、提示词生成和安装流程
-- `tests/` 用来做回归验证，确保 CLI、模板、插件 bundle 和执行流程没有被改坏
+- `src/` 放 `HelloLoop` 的实际实现逻辑，例如路径发现、分析提示词生成、运行调度和安装流程
+- `tests/` 放回归测试，确保 CLI、安装链路、bundle 结构和分析流程没有被改坏
 - `templates/` 是初始化目标仓库时写入 `.helloloop/` 的模板来源
 
 ## 相关文档
 
-- `docs/README.md`：插件 bundle 结构补充说明
-- `docs/install.md`：安装说明
-- `docs/plugin-standard.md`：官方插件结构与标准对照
+- `docs/install.md`：安装与日常使用方式
+- `docs/README.md`：插件 bundle 结构说明
+- `docs/plugin-standard.md`：官方插件结构与当前实现映射

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "helloloop",
-  "version": "0.1.1",
-  "description": "Standalone Codex plugin bundle for backlog-driven repository execution with Ralph Loop guards",
+  "version": "0.1.2",
+  "description": "面向 Codex 的独立插件 bundle，用于基于 backlog 持续推进仓库开发并执行验证循环",
+  "author": "HelloWind",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/hellowind777/helloloop",
   "type": "module",
   "repository": {
     "type": "git",
@@ -15,6 +18,7 @@
   },
   "files": [
     ".codex-plugin",
+    "LICENSE",
     "README.md",
     "bin",
     "package.json",
@@ -24,7 +28,7 @@
     "templates"
   ],
   "scripts": {
-    "test": "node --test tests/cli_surface.test.mjs tests/install_script.test.mjs tests/process_shell.test.mjs tests/ralph_loop.test.mjs tests/plugin_bundle.test.mjs"
+    "test": "node --test tests/analyze_cli.test.mjs tests/cli_surface.test.mjs tests/install_script.test.mjs tests/process_shell.test.mjs tests/prompt_guardrails.test.mjs tests/ralph_loop.test.mjs tests/plugin_bundle.test.mjs"
   },
   "engines": {
     "node": ">=20"

package/skills/helloloop/SKILL.md

@@ -1,51 +1,55 @@
 ---
 name: helloloop
-description: Use when the user wants Codex to keep shipping repo work across turns, bootstrap HelloLoop, or inspect backlog-driven execution state through the pure official plugin bundle.
+description: 当用户希望 Codex 先分析仓库当前进度，再生成 backlog 并按队列持续接续开发时使用。
 ---
 
 # HelloLoop
 
-Use this plugin when the task is continuous repository execution rather than a single chat-turn change.
+当任务目标不是单轮对话里改一点代码，而是要基于开发文档持续推进整个仓库时，使用这个插件。
 
-## Official Plugin Boundary
+## 插件边界
 
-- This bundle root is the official plugin surface for HelloLoop.
-- It ships standard Codex plugin metadata through `.codex-plugin/plugin.json` and a plugin skill through `skills/`.
-- This plugin is designed around explicit skill and CLI entrypoints.
+- 当前 bundle 根目录就是 `HelloLoop` 的官方插件目录。
+- 插件元数据位于 `.codex-plugin/plugin.json`，执行逻辑位于 `skills/`、`bin/`、`scripts/`、`src/`、`templates/`。
+- 运行状态统一写入目标仓库根目录下的 `.helloloop/`。
 
-## Setup
+## 使用前准备
 
-1. Install with `npx helloloop install --codex-home <CODEX_HOME>` or use `scripts/install-home-plugin.ps1`.
-2. From the target repository, run `npx helloloop doctor --repo <repo-root>`.
-3. From the target repository, run `npx helloloop init --repo <repo-root>`.
+1. 先通过 `npx helloloop install --codex-home <CODEX_HOME>` 或 `scripts/install-home-plugin.ps1` 安装插件。
+2. 打开目标项目仓库目录，或者打开开发文档所在目录。
+3. 运行 `npx helloloop` 或 `npx helloloop <path>`。
+4. 如果无法自动判断仓库路径或开发文档路径，就停下来提示用户补充；`--repo` 和 `--docs` 只作为显式覆盖选项使用。
 
-## Operating Model
+## 工作模式
 
-- `.helloloop/` is the default CLI and backlog state directory.
-- The installed plugin bundle keeps runtime files such as `src/`, `templates/`, `bin/`, `scripts/`, and `skills/`.
-- Source-only materials such as `docs/` and `tests/` stay in the development repository.
+- 代码是事实源，开发文档是目标源。
+- `HelloLoop` 会先分析当前真实进度，再生成或刷新 `.helloloop/backlog.json`。
+- 后续开发通过 `next`、`run-once`、`run-loop` 按 backlog 接续推进。
+- 真正的代码分析与实现仍由本机 `codex` CLI 完成。
 
-## Invocation
+## 核心命令
 
-- In official Codex plugin mode, plugin skills are namespaced with `plugin_name:`.
-- For this plugin, the unambiguous skill name is `helloloop:helloloop`.
-- Explicitly naming the `helloloop` plugin should also bias Codex toward this skill.
-- Do not promise bare `$helloloop` is the official invocation form.
+- `npx helloloop`
+- `npx helloloop <path>`
+- `npx helloloop next`
+- `npx helloloop run-once`
+- `npx helloloop run-loop --max-tasks <n>`
 
-## Primary Commands
+## 高级命令
 
-- `npx helloloop status --repo <repo-root>`
-- `npx helloloop next --repo <repo-root>`
-- `npx helloloop run-once --repo <repo-root>`
-- `npx helloloop run-loop --repo <repo-root>`
+- `npx helloloop status`
+- `npx helloloop doctor`
+- `npx helloloop init`
+- `npx helloloop --repo <repo-root> --docs <docs-path>`
 
-## Reporting Rules
+## 调用方式
 
-- State explicitly that the plugin runs in pure official plugin mode.
-- Keep Ralph Loop guardrails and repo verification intact.
+- 在官方 Codex 插件模式下，明确的 skill 名称是 `helloloop:helloloop`。
+- 在对话里显式提到 `helloloop` 插件，也会帮助 Codex 更准确地命中这个 skill。
 
-## Docs
+## 参考文档
 
-- Source repo main guide: `docs/README.md`
-- Source repo installation note: `docs/install.md`
-- Source repo official standard and runtime boundary: `docs/plugin-standard.md`
+- 主说明：`README.md`
+- 安装说明：`docs/install.md`
+- Bundle 说明：`docs/README.md`
+- 插件标准映射：`docs/plugin-standard.md`