helloloop 0.1.0 → 0.1.2

package/README.md

@@ -1,168 +1,190 @@
 # HelloLoop
 
-`HelloLoop` 是一个面向 Codex 的 backlog 驱动开发插件。
+`HelloLoop` 是一个面向 Codex 的独立插件，用来把“根据开发文档接续推进仓库开发”这件事标准化、可追踪、可验证地跑起来。
 
-它把持续开发所需的任务队列、执行策略、验证命令和运行记录集中到目标仓库的 `.helloloop/` 目录里，并通过显式 CLI / skill 入口推动任务逐步落地。
+它会先分析当前仓库真实代码与开发文档之间的差距，再把后续任务、运行状态、执行记录统一写入目标仓库根目录的 `.helloloop/`，让 Codex 能持续接着做，而不是每轮都重新交代背景。
+
+命令入口按 `Node.js 20+` 设计，支持 Windows、macOS 和 Linux。
 
 ## 目录
 
-- [HelloLoop 是什么](#helloloop-是什么)
-- [核心能力](#核心能力)
-- [适用场景](#适用场景)
-- [项目结构](#项目结构)
+- [核心定位](#核心定位)
 - [安装](#安装)
 - [快速开始](#快速开始)
-- [命令说明](#命令说明)
+- [路径规则](#路径规则)
+- [安全底线](#安全底线)
+- [命令速查](#命令速查)
 - [状态目录](#状态目录)
-- [任务与执行模型](#任务与执行模型)
-- [发布到 npm](#发布到-npm)
-- [验证](#验证)
+- [在 Codex 中使用](#在-codex-中使用)
+- [许可证](#许可证)
+- [仓库结构](#仓库结构)
 - [相关文档](#相关文档)
 
-## HelloLoop 是什么
-
-`HelloLoop` 解决的是“让 Codex 在同一个仓库里持续推进任务”这个问题。
+## 核心定位
 
-与一次性执行单个改动不同，它围绕一份 backlog 运行：
+`HelloLoop` 适合这样的场景：
 
-- 先从 backlog 里选择当前最合适的任务
-- 根据项目状态、必读文档和约束生成执行提示
-- 调用 Codex 完成实现
-- 运行验证命令确认结果
-- 失败时按 Ralph Loop 思路重试或换路
-- 把状态、结果和运行产物写回目标仓库
+- 仓库里已经有 `docs/`、方案包、任务文档或阶段说明
+- 代码已经做了一部分，需要先判断“现在做到哪里了”
+- 你希望自动生成足够细的后续 backlog，而不是得到一句“继续开发”
+- 你希望后续每轮执行都带着状态、约束、文档和验证命令继续推进
+- 你希望在开发文档约束不完整时，仍然有一层稳定、安全的执行底线
 
-这意味着你可以把 `HelloLoop` 当成一个“面向仓库持续推进”的执行层，而不是单次脚本集合。
+围绕这个目标，`HelloLoop` 做四件事：
 
-## 核心能力
+1. 自动发现项目仓库与开发文档
+2. 对比当前代码和文档目标，判断真实进度
+3. 生成或刷新 `.helloloop/backlog.json`
+4. 驱动 Codex 按 backlog 接续执行并留下运行记录
 
-- **插件安装**：把运行时 bundle 安装到 `~/.codex/plugins/helloloop`
-- **仓库初始化**：为目标仓库生成 `.helloloop/` 初始状态文件
-- **任务选择**：基于优先级、依赖和风险等级选择下一任务
-- **干跑预览**：先生成下一任务提示词和验证列表，再决定是否执行
-- **单轮执行**：执行一个任务并回写状态
-- **循环执行**：连续执行多个任务，直到达到上限或遇到阻塞
-- **验证联动**：优先读取任务自身验证命令，否则回退到仓库 `.helloagents/verify.yaml`
-- **运行留痕**：把每次执行的提示词、日志、验证输出保存到 `runs/`
+同时，`HelloLoop` 自带一层内建安全底线：
 
-## 适用场景
+- 开发文档缺少必要约束时，自动补上默认工程约束
+- Windows 端优先使用 `pwsh`，也支持 `bash`（如 Git Bash）和 `powershell`，但不回退到 `cmd`
+- 所有流程都要求避免静默失败、危险命令和隐私信息泄露
 
-- 你已经有 backlog，希望 Codex 按队列持续推进
-- 你希望每个任务执行前都自动带上项目状态和文档约束
-- 你希望执行失败后自动进入重试或换路，而不是停在一次失败
-- 你希望把任务状态、验证结果和运行痕迹沉淀在仓库内
-- 你希望通过 npm 分发这个插件，并在 GitHub Tag 发布时自动同步到 npm
+## 安装
 
-## 项目结构
+### npm / npx
 
-```text
-helloloop/
-├── .codex-plugin/         # Codex 插件 manifest
-├── bin/                   # npm bin 入口
-├── docs/                  # 说明文档
-├── scripts/               # CLI 安装脚本与入口
-├── skills/                # 插件技能
-├── src/                   # 核心实现
-├── templates/             # 初始化模板
-└── tests/                 # 回归测试
+```powershell
+npx helloloop install --codex-home <CODEX_HOME>
 ```
 
-源码仓库包含 `docs/` 和 `tests/`，但安装到 Codex Home 时只会复制运行时必需文件。
-
-## 安装
-
-### 方式一：通过 npm / npx 安装
+### 源码仓库
 
 ```powershell
-npx helloloop install --codex-home C:\Users\hellowind\.codex
+node ./scripts/helloloop.mjs install --codex-home <CODEX_HOME>
 ```
 
-### 方式二：从源码仓库安装
+如果你在 Windows 上更习惯 PowerShell，也可以使用：
 
 ```powershell
-pwsh -NoLogo -NoProfile -File .\scripts\install-home-plugin.ps1 -CodexHome C:\Users\hellowind\.codex
+pwsh -NoLogo -NoProfile -File .\scripts\install-home-plugin.ps1 -CodexHome <CODEX_HOME>
 ```
 
-如果已存在同名安装目录，追加 `-Force` 或 `--force` 覆盖即可。
+安装完成后，插件会复制到 `<CODEX_HOME>/plugins/helloloop`，并更新 `<CODEX_HOME>/.agents/plugins/marketplace.json`。
 
-安装完成后，运行时文件会位于：
+## 快速开始
 
-```text
-C:\Users\hellowind\.codex\plugins\helloloop
+### 1. 安装插件
+
+```powershell
+npx helloloop install --codex-home <CODEX_HOME>
 ```
 
-同时会自动更新：
+### 2. 进入目标项目或开发文档目录
 
-```text
-C:\Users\hellowind\.codex\.agents\plugins\marketplace.json
+最短命令就是：
+
+```powershell
+npx helloloop
 ```
 
-## 快速开始
+默认规则如下：
 
-### 1. 安装插件
+- 当前目录是项目仓库根目录时：自动查找开发文档并分析当前进度
+- 当前目录本身是开发文档目录时：优先尝试反推目标仓库
+- 分析完成后：自动生成或刷新目标仓库根目录下的 `.helloloop/`
+
+如果你只知道一个路径，也可以只传一个位置：
 
 ```powershell
-npx helloloop install --codex-home C:\Users\hellowind\.codex
+npx helloloop <PATH>
 ```
 
-### 2. 在目标仓库初始化状态目录
+这里的 `<PATH>` 只能传一个，可以是：
+
+- 项目仓库路径
+- 开发文档目录
+- 开发文档文件
+
+### 3. 查看下一任务
 
 ```powershell
-node C:\Users\hellowind\.codex\plugins\helloloop\scripts\helloloop.mjs init --repo D:\GitHub\dev\your-repo
+npx helloloop next
 ```
 
-### 3. 检查运行条件
+### 4. 执行一次或连续执行
 
 ```powershell
-node C:\Users\hellowind\.codex\plugins\helloloop\scripts\helloloop.mjs doctor --repo D:\GitHub\dev\your-repo
+npx helloloop run-once
+npx helloloop run-loop --max-tasks 2
 ```
 
-### 4. 查看当前状态或下一任务
+如果你已经做了全局安装，也可以把 `npx helloloop` 简写成 `helloloop`。
+
+## 路径规则
+
+- 不传路径：默认分析当前目录
+- 只传一个路径：自动判断它是仓库路径还是开发文档路径
+- 已给开发文档但无法确定仓库：停止并提示补充 `--repo`
+- 已给仓库但找不到开发文档：停止并提示补充 `--docs`
+- `--repo` 和 `--docs` 是高级覆盖选项，不是主工作流
+
+推荐优先使用：
 
 ```powershell
-node C:\Users\hellowind\.codex\plugins\helloloop\scripts\helloloop.mjs status --repo D:\GitHub\dev\your-repo
-node C:\Users\hellowind\.codex\plugins\helloloop\scripts\helloloop.mjs next --repo D:\GitHub\dev\your-repo
+npx helloloop
+npx helloloop <PATH>
 ```
 
-### 5. 执行一个任务或连续执行
+只有在自动发现无法收敛时，再显式补充：
 
 ```powershell
-node C:\Users\hellowind\.codex\plugins\helloloop\scripts\helloloop.mjs run-once --repo D:\GitHub\dev\your-repo
-node C:\Users\hellowind\.codex\plugins\helloloop\scripts\helloloop.mjs run-loop --repo D:\GitHub\dev\your-repo --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 CLI、模板、配置文件和插件文件是否齐备 |
-| `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 |
+| `--config-dir <dir>` | 指定状态目录名，默认 `.helloloop` |
+| `--dry-run` | 只生成提示和预览，不真正调用 Codex |
 | `--task-id <id>` | 指定执行某个任务 |
-| `--max-tasks <n>` | `run-loop` 最多执行多少个任务 |
-| `--max-attempts <n>` | 每种策略内最大重试次数 |
+| `--max-tasks <n>` | `run-loop` 最多执行的任务数 |
+| `--max-attempts <n>` | 每种策略的最大重试次数 |
 | `--max-strategies <n>` | 单任务最大换路次数 |
-| `--allow-high-risk` | 允许执行 `medium` / `high` / `critical` 风险任务 |
+| `--allow-high-risk` | 允许执行 `medium` 及以上风险任务 |
 | `--required-doc <path>` | 追加全局必读文档 |
 | `--constraint <text>` | 追加全局实现约束 |
-| `--force` | 覆盖安装目录 |
+| `--force` | 覆盖已有安装目录 |
 
 ### Skill 名称
 
-安装为 Codex 插件后，可通过插件命名空间使用：
+安装为 Codex 插件后，推荐显式使用：
 
 ```text
 helloloop:helloloop
@@ -170,7 +192,7 @@ helloloop:helloloop
 
 ## 状态目录
 
-`HelloLoop` 在目标仓库内默认使用 `.helloloop/` 保存执行状态。
+`HelloLoop` 默认在目标仓库根目录创建 `.helloloop/`，而不是写回插件目录自身。
 
 典型结构如下：
 
@@ -184,151 +206,49 @@ helloloop:helloloop
 └── runs/
 ```
 
-### 各文件作用
-
-- `backlog.json`：任务列表、优先级、风险、验收条件、依赖关系
-- `policy.json`：循环上限、重试次数、Codex 执行参数
-- `project.json`：全局必读文档、实现约束和 planner 配置
-- `status.json`：机器可读的最近运行状态
-- `STATE.md`：给人看的当前状态摘要
-- `runs/`：每次任务执行的提示词、stdout、stderr 和验证记录
-
-如果旧仓库仍保留 `.helloagents/helloloop/`，当前版本也会自动识别；你也可以显式传 `--config-dir .helloagents/helloloop`。
-
-## 任务与执行模型
-
-### backlog 任务字段
-
-`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`：任务专属验证命令（可选）
-
-### 执行流程
-
-`HelloLoop` 的核心执行逻辑如下：
-
-1. 从 backlog 中筛出可执行任务
-2. 按优先级和依赖关系选择下一任务
-3. 读取仓库状态、必读文档和实现约束
-4. 生成 Codex 执行提示词
-5. 调用 `codex exec`
-6. 运行验证命令
-7. 成功则把任务标记为完成
-8. 失败则按 Ralph Loop 记录失败历史并继续重试或换路
-
-### 风险与阻塞规则
-
-- 默认只自动执行 `low` 风险任务
-- `medium` 及以上风险任务需要显式传入 `--allow-high-risk`
-- 如果存在未收束的 `in_progress` 任务，新的自动执行会被阻塞
-- 如果存在 `failed` 或 `blocked` 任务，执行会停下来等待处理
-- 如果依赖任务未完成，相关任务不会被挑选执行
-
-## 发布到 npm
-
-仓库已加入自动发布工作流：
-
-```text
-.github/workflows/publish.yml
-```
-
-这个工作流借鉴了 `helloagents` 的发布结构，并做了适合 `HelloLoop` 的简化与对齐：
-
-- 以 Git Tag 作为发布触发器
-- 发布前校验 `package.json` 版本与 Tag 是否一致
-- 自动运行 `npm test`
-- 自动运行 `npm pack --dry-run`
-- 自动发布到 npm
-- 自动创建 GitHub Release
-
-### 推荐发布方式
+各文件职责如下：
 
-#### 正式版
+- `backlog.json`：接续开发任务列表
+- `policy.json`：循环上限、重试策略和 Codex 参数
+- `project.json`：开发文档入口和全局约束
+- `status.json`：最近一次运行的机器可读状态
+- `STATE.md`：面向人的当前进展摘要
+- `runs/`：提示词、stdout、stderr、验证输出等运行留痕
 
-1. 修改 `package.json` 中的 `version`
-2. 提交并推送代码
-3. 创建同版本 Tag
+## 在 Codex 中使用
 
-示例：
+可以。
 
-```powershell
-npm version patch --no-git-tag-version
-git add package.json
-git commit -m "chore: release v0.1.1"
-git push origin main
-git tag v0.1.1
-git push origin v0.1.1
-```
+- 在当前 Codex 会话里，直接运行 `npx helloloop ...` 即可，不需要重开终端
+- 如果你使用的是全局安装后的 `helloloop` 短命令，是否需要新终端取决于你的 shell 是否已经刷新 PATH
+- `HelloLoop` 负责组织分析、backlog 和执行流程，真正的代码分析与开发仍然通过本机 `codex` CLI 完成
 
-推送 `v0.1.1` 后，Action 会把 `0.1.1` 发布到 npm 的 `latest` 通道。
+## 许可证
 
-#### Beta 版
+`HelloLoop` 使用 `Apache-2.0` 许可证，许可证文件位于仓库根目录 `LICENSE`。
 
-Beta Tag 采用：
+## 仓库结构
 
 ```text
-v0.2.0-beta.1
-```
-
-这类 Tag 会发布到 npm 的 `beta` 通道。工作流会要求：
-
-- `package.json` 中的基础版本为 `0.2.0`
-- 实际发布版本为 `0.2.0-beta.1`
-
-### npm Trusted Publishing 配置
-
-为了让 GitHub Actions 无需 `NPM_TOKEN` 直接发布到 npm，建议使用 npm Trusted Publishing。
-
-在 npm 包设置中把以下信息绑定为 Trusted Publisher：
-
-- GitHub 仓库：`hellowind777/helloloop`
-- Workflow 文件：`publish.yml`
-- 触发来源：GitHub-hosted runner
-
-发布工作流已经按 Trusted Publishing 方式准备好：
-
-- `id-token: write`
-- Node 24
-- 升级到最新 npm CLI
-- 直接执行 `npm publish`
-
-### 工作流触发规则
-
-- `push tags: v*`：标准自动发布入口
-- `workflow_dispatch`：手动输入 Tag 重新发布某个版本
-
-## 验证
-
-### 本地回归
-
-```powershell
-npm test
-```
-
-### 打包预检
-
-```powershell
-npm pack --dry-run
+helloloop/
+├── .codex-plugin/         # Codex 插件 manifest 与展示元数据
+├── bin/                   # npm 命令入口
+├── docs/                  # 补充说明文档
+├── scripts/               # 安装脚本与 CLI 入口
+├── skills/                # 插件技能
+├── src/                   # 核心实现
+├── templates/             # 初始化时写入 .helloloop/ 的模板
+└── tests/                 # 回归测试
 ```
 
-### 安装烟测
+其中：
 
-```powershell
-node .\bin\helloloop.mjs install --codex-home C:\Users\hellowind\AppData\Local\Temp\helloloop-smoke --force
-```
+- `src/` 放 `HelloLoop` 的实际实现逻辑，例如路径发现、分析提示词生成、运行调度和安装流程
+- `tests/` 放回归测试，确保 CLI、安装链路、bundle 结构和分析流程没有被改坏
+- `templates/` 是初始化目标仓库时写入 `.helloloop/` 的模板来源
 
 ## 相关文档
 
-- 安装说明：`docs/install.md`
-- 插件主说明：`docs/README.md`
-- 官方标准映射：`docs/plugin-standard.md`
+- `docs/install.md`：安装与日常使用方式
+- `docs/README.md`：插件 bundle 结构说明
+- `docs/plugin-standard.md`：官方插件结构与当前实现映射

package/package.json

@@ -1,24 +1,24 @@
 {
   "name": "helloloop",
-  "version": "0.1.0",
-  "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",
-    "url": "https://github.com/hellowind777/helloloop.git"
-  },
-  "homepage": "https://github.com/hellowind777/helloloop#readme",
-  "bugs": {
-    "url": "https://github.com/hellowind777/helloloop/issues"
+    "url": "git+https://github.com/hellowind777/helloloop.git"
   },
   "publishConfig": {
     "access": "public"
   },
   "bin": {
-    "helloloop": "./bin/helloloop.mjs"
+    "helloloop": "bin/helloloop.js"
   },
   "files": [
     ".codex-plugin",
+    "LICENSE",
     "README.md",
     "bin",
     "package.json",
@@ -28,10 +28,9 @@
     "templates"
   ],
   "scripts": {
-    "test": "node --test tests/cli_surface.test.mjs tests/install_script.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,53 +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/`.
-- Current Codex runtime does not auto-load Hook handlers from plugins.
-- This plugin therefore does not support `~helloloop` or automatic Stop-hook continuation.
+- 当前 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 `node <helloloop-plugin-root>/scripts/helloloop.mjs doctor --repo <repo-root>`.
-3. From the target repository, run `node <helloloop-plugin-root>/scripts/helloloop.mjs 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 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
+## 高级命令
 
-- `node <helloloop-plugin-root>/scripts/helloloop.mjs status --repo <repo-root>`
-- `node <helloloop-plugin-root>/scripts/helloloop.mjs next --repo <repo-root>`
-- `node <helloloop-plugin-root>/scripts/helloloop.mjs run-once --repo <repo-root>`
-- `node <helloloop-plugin-root>/scripts/helloloop.mjs 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.
-- Call out any request that depends on Hook-only behavior such as `UserPromptSubmit` or `Stop`, because those are intentionally unsupported here.
-- 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`