helloloop 0.1.1 → 0.2.0

package/README.md

@@ -1,185 +1,315 @@
 # HelloLoop
 
-`HelloLoop` 是一个面向 Codex 的独立插件，用来把“按 backlog 持续推进仓库开发”这件事标准化、可追踪、可验证地跑起来。
+`HelloLoop` 是一个面向 `Codex CLI`、`Claude Code`、`Gemini CLI` 的多宿主开发工作流插件，用来把“根据开发文档持续接续开发”变成一条可分析、可确认、可验证、可追踪的标准流程。
 
-它不只是在单轮对话里改一段代码，而是把任务队列、必读文档、执行约束、验证命令和运行记录统一放进目标仓库的 `.helloloop/` 目录，让 Codex 可以按明确流程持续接续开发。
+它有两层定位：
 
-命令入口按 `Node.js 20+` 设计，支持 Windows、macOS 和 Linux。
+- `Codex CLI`：首发平台、参考实现、最佳体验路径
+- `Claude Code` / `Gemini CLI`：各自按原生 agent 逻辑执行，但共享同一套 `.helloloop/` 工作流规范
+
+Codex 路径的主工作流只有两种 CLI 入口：
+
+```bash
+npx helloloop
+npx helloloop <PATH>
+```
+
+无论从哪个宿主进入，`HelloLoop` 都遵循同一条主线：
+
+1. 自动识别项目仓库与开发文档
+2. 分析当前代码与文档目标的真实差距
+3. 生成或刷新目标仓库根目录下的 `.helloloop/`
+4. 输出中文执行确认单
+5. 用户确认后，继续按当前宿主的原生 agent 逻辑推进开发、测试和验收
 
 ## 目录
 
-- [HelloLoop 是什么](#helloloop-是什么)
-- [核心能力](#核心能力)
-- [适用场景](#适用场景)
+- [核心流程](#核心流程)
+- [支持矩阵](#支持矩阵)
 - [安装](#安装)
 - [快速开始](#快速开始)
+- [自动发现规则](#自动发现规则)
+- [自动执行边界](#自动执行边界)
+- [Doctor 检查](#doctor-检查)
 - [命令速查](#命令速查)
 - [状态目录](#状态目录)
-- [工作机制](#工作机制)
+- [Skill 用法](#skill-用法)
+- [在 Codex 中使用](#在-codex-中使用)
+- [跨平台与安全](#跨平台与安全)
 - [仓库结构](#仓库结构)
-- [相关文档](#相关文档)
+- [许可证](#许可证)
+
+## 核心流程
 
-## HelloLoop 是什么
+`HelloLoop` 的默认流程固定为 5 步：
 
-`HelloLoop` 解决的是以下问题：
+1. 自动发现项目仓库与开发文档
+2. 对比文档目标与当前代码，识别当前进度和偏差
+3. 生成或刷新目标仓库根目录下的 `.helloloop/`
+4. 输出执行确认单，明确展示仓库、文档、当前进度、待办任务、验证命令和执行边界
+5. 用户确认后，自动推进后续开发、测试和验收，直到全部完成或遇到硬阻塞
 
-- 你的仓库里已经有开发文档、任务拆解或 backlog
-- 你希望 Codex 能按顺序接着做，而不是每次都从头解释背景
-- 你希望每一轮执行前都自动带上项目状态、必读文档和实现约束
-- 你希望每次运行后都留下状态记录、验证结果和运行痕迹
+如果分析识别出偏差修正任务，`HelloLoop` 会优先先收口偏差，再继续后面的开发任务。
 
-围绕这个目标，`HelloLoop` 提供了一套明确的仓库内执行模型：
+工作流统一，但执行器分为两类：
 
-1. 从 backlog 中选择当前可执行任务
-2. 汇总项目上下文、任务目标和约束
-3. 生成面向 Codex 的执行提示
-4. 调用 Codex 完成实现
-5. 执行验证命令
-6. 回写状态、日志和运行记录
+- `Codex CLI`：通过 `npx helloloop` / `$helloloop` 进入，使用当前仓库内的 Node CLI 与 Codex 插件链路
+- `Claude Code` / `Gemini CLI`：通过 `/helloloop` 进入，使用各自原生插件 / 扩展与 agent 工具链
 
-## 核心能力
+## 支持矩阵
 
-- **插件安装**：安装到 Codex Home，作为独立插件使用
-- **仓库初始化**：在目标仓库生成 `.helloloop/` 状态目录
-- **任务调度**：基于优先级、依赖、风险等级挑选下一任务
-- **干跑预览**：先看下一任务、提示词和验证命令，再决定是否执行
-- **单轮执行**：执行一个任务并回写结果
-- **循环执行**：连续执行多个任务，直到完成、阻塞或达到上限
-- **验证联动**：优先使用任务级验证命令，缺省时读取仓库验证配置
-- **运行留痕**：把提示词、stdout、stderr、验证输出沉淀到 `runs/`
+| 宿主 | 安装方式 | 原生使用入口 | 当前定位 |
+| --- | --- | --- | --- |
+| `Codex CLI` | `helloloop install --host codex` | `$helloloop` / `npx helloloop` | 首发平台、参考实现、最佳体验 |
+| `Claude Code` | `helloloop install --host claude` | `/helloloop` | Claude 原生插件工作流 |
+| `Gemini CLI` | `helloloop install --host gemini` | `/helloloop` | Gemini 原生扩展工作流 |
 
-## 适用场景
+如果你希望一次性装好三家宿主：
 
-- 你有一套开发文档，希望 Codex 接续完成后续开发
-- 你有清晰 backlog，希望 AI 按队列逐项推进
-- 你希望把“任务、约束、验证、结果”都放在仓库里长期维护
-- 你希望执行失败后不是停住，而是能按既定策略继续推进
-- 你希望多人协作时，每个人都能快速看懂当前任务状态
+```bash
+npx helloloop install --host all
+```
 
 ## 安装
 
-### 通过 npm / npx 安装
+### npm / npx
 
-```powershell
+默认安装 `Codex` 宿主：
+
+```bash
 npx helloloop install --codex-home <CODEX_HOME>
 ```
 
-### 从源码仓库安装
+安装到指定宿主：
 
-```powershell
+```bash
+npx helloloop install --host codex
+npx helloloop install --host claude
+npx helloloop install --host gemini
+npx helloloop install --host all
+```
+
+可选 home 参数：
+
+```bash
+--codex-home <CODEX_HOME>
+--claude-home <CLAUDE_HOME>
+--gemini-home <GEMINI_HOME>
+```
+
+### 源码仓库
+
+```bash
 node ./scripts/helloloop.mjs install --codex-home <CODEX_HOME>
 ```
 
-如果你在 Windows 上更习惯 PowerShell，也可以使用：
+Windows PowerShell 也可以直接运行：
 
 ```powershell
 pwsh -NoLogo -NoProfile -File .\scripts\install-home-plugin.ps1 -CodexHome <CODEX_HOME>
 ```
 
-安装完成后，插件会被放到：
+安装完成后：
 
-```text
-<CODEX_HOME>\plugins\helloloop
+- Codex 会写入 `<CODEX_HOME>/plugins/helloloop`
+- Claude 会写入 `<CLAUDE_HOME>/marketplaces/helloloop-local`
+- Gemini 会写入 `<GEMINI_HOME>/extensions/helloloop`
+
+如果你想在安装后做一次全宿主环境检查：
+
+```bash
+npx helloloop doctor --host all
 ```
 
-同时会更新：
+## 快速开始
+
+### 1. 选择宿主入口
 
 ```text
-<CODEX_HOME>\.agents\plugins\marketplace.json
+Codex   -> $helloloop / npx helloloop
+Claude  -> /helloloop
+Gemini  -> /helloloop
 ```
 
-## 快速开始
+说明：
 
-### 1. 安装插件
+- `Codex` 路径下，`$helloloop` 与 `npx helloloop` 对齐同一主流程
+- `Claude` 与 `Gemini` 路径下，`/helloloop` 会走各自原生 agent 执行逻辑
+- 三家都会维护同一个 `.helloloop/` 状态目录规范
 
-```powershell
-npx helloloop install --codex-home <CODEX_HOME>
+### 2. 进入项目仓库或开发文档目录
+
+最短命令：
+
+```bash
+npx helloloop
 ```
 
-之后的日常命令推荐直接使用：
+如果你只知道一个路径，也可以只传一个：
 
-```powershell
-npx helloloop <command> [options]
+```bash
+npx helloloop <PATH>
 ```
 
-如果你已经全局安装过：
+这里的 `<PATH>` 可以是：
 
-```powershell
-helloloop <command> [options]
+- 项目仓库路径
+- 开发文档目录
+- 开发文档文件
+
+### 3. 查看执行确认单
+
+分析完成后，`HelloLoop` 会展示一份执行确认单，至少包含：
+
+- 识别出的目标仓库
+- 识别出的开发文档
+- 当前进度摘要
+- 已实现事项
+- 待完成事项
+- 任务统计
+- 首个待执行任务
+- 验证命令预览
+- 自动推进边界
+
+### 4. 确认后自动继续执行
+
+你确认后，`HelloLoop` 会：
+
+- 按 backlog 顺序自动推进
+- 每个任务都走当前宿主的原生 agent 执行与验证
+- 遇到失败、风险超阈值、依赖未满足或环境硬阻塞时立即停下
+- 把分析结果、状态和运行记录都写进目标仓库的 `.helloloop/`
+
+如果你已经做了全局安装，也可以把 `npx helloloop` 简写成 `helloloop`。
+
+如果你想手动查看或接管某一步，也可以使用：
+
+```bash
+npx helloloop status
+npx helloloop next
+npx helloloop run-once
 ```
 
-在 Codex 当前会话里，也可以直接运行同样的 `npx helloloop ...` 命令，不需要重开终端。
+## 自动发现规则
 
-### 2. 在目标仓库初始化 `.helloloop/`
+- 不传路径：默认分析当前目录
+- 只传一个路径：自动判断它是仓库路径还是开发文档路径
+- 当前目录是仓库：自动查找开发文档
+- 当前目录是文档目录：自动尝试反推目标仓库
+- 只给开发文档但无法推断仓库：停止并提示补充 `--repo`
+- 只给仓库但找不到开发文档：停止并提示补充 `--docs`
 
-```powershell
-npx helloloop init --repo <REPO_ROOT>
+推荐始终优先使用：
+
+```bash
+npx helloloop
+npx helloloop <PATH>
 ```
 
-初始化完成后，模板会落在目标仓库根目录下的 `.helloloop/`，而不是插件目录本身。
+只有自动发现无法收敛时，再补充高级参数：
 
-### 3. 检查运行条件
+```bash
+npx helloloop --repo <REPO_ROOT> --docs <DOCS_PATH>
+```
 
-```powershell
-npx helloloop doctor --repo <REPO_ROOT>
+## 自动执行边界
+
+默认主命令会在确认后尽量自动完成整轮 backlog，而不是只跑一个任务。
+
+### 常用执行模式
+
+```bash
+npx helloloop
+npx helloloop <PATH>
+npx helloloop --dry-run
+npx helloloop -y
 ```
 
-### 4. 查看状态与下一任务
+含义如下：
 
-```powershell
-npx helloloop status --repo <REPO_ROOT>
-npx helloloop next --repo <REPO_ROOT>
+- `npx helloloop`：分析 → 展示确认单 → 等待你确认 → 自动执行
+- `npx helloloop <PATH>`：同上，但先用你给的单一路径做自动识别
+- `npx helloloop --dry-run`：只分析并输出确认单，不真正开始执行
+- `npx helloloop -y`：跳过交互确认，分析后直接自动执行
+
+### 停止条件
+
+出现以下情况时，`HelloLoop` 会停止并保留现场，而不是静默降级：
+
+- 无法自动确定目标仓库或开发文档
+- backlog 已存在失败任务、阻塞任务或未满足依赖
+- 后续任务风险超出自动阈值，且你没有显式加 `--allow-high-risk`
+- 验证命令失败
+- 当前宿主 CLI、插件资产或 shell 环境不可安全执行
+
+## Doctor 检查
+
+你可以用 `doctor` 检查当前宿主是否已具备基本运行条件。
+
+### 只检查 Codex
+
+```bash
+npx helloloop doctor
 ```
 
-### 5. 执行一个任务或连续执行
+### 检查全部宿主
 
-```powershell
-npx helloloop run-once --repo <REPO_ROOT>
-npx helloloop run-loop --repo <REPO_ROOT> --max-tasks 2
+```bash
+npx helloloop doctor --host all
 ```
 
+### 检查已安装目录
+
+```bash
+npx helloloop doctor --host all --codex-home <CODEX_HOME> --claude-home <CLAUDE_HOME> --gemini-home <GEMINI_HOME>
+```
+
+`doctor` 当前可检查：
+
+- 宿主 CLI 是否存在
+- 本地运行时资产是否齐全
+- 目标仓库 `.helloloop/` 基础文件是否存在
+- 已安装宿主目录是否已写入对应插件 / 扩展
+
 ## 命令速查
 
 | 命令 | 作用 |
 | --- | --- |
-| `install` | 安装插件到 Codex Home，并更新插件 marketplace |
-| `init` | 初始化目标仓库的 `.helloloop/` |
-| `doctor` | 检查 Codex、插件文件和目标仓库配置是否齐备 |
-| `status` | 查看 backlog 汇总、当前状态和下一任务 |
-| `next` | 生成下一任务预览，不真正调用 Codex |
-| `run-once` | 执行一个任务 |
-| `run-loop` | 连续执行多个任务 |
+| `analyze` | 主工作流；分析并输出确认单，确认后自动接续执行 |
+| `status` | 查看 backlog 汇总与当前状态 |
+| `next` | 预览下一任务，不真正执行 |
+| `run-once` | 手动执行一个任务 |
+| `run-loop` | 手动连续执行多个任务 |
+| `doctor` | 检查所选宿主、运行时资产与目标仓库是否满足运行条件 |
+| `init` | 手动初始化 `.helloloop/` 模板 |
+| `install` | 安装插件到所选宿主目录 |
 
 ### 常用选项
 
 | 选项 | 说明 |
 | --- | --- |
-| `--repo <dir>` | 目标仓库根目录，默认当前目录 |
-| `--codex-home <dir>` | 指定 Codex Home |
-| `--config-dir <dir>` | 指定状态目录名，默认 `.helloloop` |
-| `--dry-run` | 只生成提示词和预览，不真正调用 Codex |
-| `--task-id <id>` | 指定执行某个任务 |
-| `--max-tasks <n>` | `run-loop` 最多执行的任务数 |
-| `--max-attempts <n>` | 每种策略的最大重试次数 |
-| `--max-strategies <n>` | 单任务最大换路次数 |
+| `-y`, `--yes` | 跳过交互确认，分析后直接开始执行 |
+| `--dry-run` | 只分析并输出确认单，不真正开始执行 |
+| `--host <name>` | 选择安装宿主：`codex`、`claude`、`gemini`、`all` |
+| `--repo <dir>` | 高级选项：显式指定项目仓库根目录 |
+| `--docs <dir\|file>` | 高级选项：显式指定开发文档目录或文件 |
 | `--allow-high-risk` | 允许执行 `medium` 及以上风险任务 |
+| `--max-tasks <n>` | 限制手动 `run-loop` 的最大任务数 |
+| `--max-attempts <n>` | 单策略最大重试次数 |
+| `--max-strategies <n>` | 单任务最大换路次数 |
 | `--required-doc <path>` | 追加全局必读文档 |
 | `--constraint <text>` | 追加全局实现约束 |
+| `--codex-home <dir>` | 指定 Codex Home |
+| `--claude-home <dir>` | 指定 Claude Home |
+| `--gemini-home <dir>` | 指定 Gemini Home |
+| `--config-dir <dir>` | 指定状态目录名，默认 `.helloloop` |
 | `--force` | 覆盖已有安装目录 |
 
-### Skill 名称
-
-安装为 Codex 插件后，推荐显式使用：
-
-```text
-helloloop:helloloop
-```
-
 ## 状态目录
 
-`HelloLoop` 默认在目标仓库根目录创建 `.helloloop/`，用来保存 backlog、策略配置、运行状态和执行留痕。
+`HelloLoop` 始终把运行状态写入目标仓库根目录，而不是插件目录自身。
 
-典型结构如下：
+默认目录：
 
 ```text
 .helloloop/
@@ -191,73 +321,120 @@ helloloop:helloloop
 └── runs/
 ```
 
-各文件作用如下：
+其中：
+
+- `backlog.json`：分析后生成的任务队列
+- `policy.json`：自动推进策略、重试上限和 Codex 参数
+- `project.json`：开发文档入口和全局约束
+- `status.json`：最近一次运行状态
+- `STATE.md`：面向人的进度摘要
+- `runs/`：提示词、stdout、stderr、验证日志等留痕
+
+## Skill 用法
+
+如果你已经把 `HelloLoop` 安装成 Codex 插件，也可以直接在 Codex 里调用：
+
+```text
+$helloloop
+```
 
-- `backlog.json`：任务列表、优先级、风险、依赖、验收条件
-- `policy.json`：循环上限、重试策略、Codex 执行参数
-- `project.json`：全局必读文档、实现约束、任务规划提示
-- `status.json`：最近一次运行的机器可读状态
-- `STATE.md`：面向人的当前进展摘要
-- `runs/`：每次执行的提示词、日志和验证输出
+或：
+
+```text
+helloloop:helloloop
+```
+
+此时推荐理解为：
+
+- `$helloloop` 是插件入口
+- `npx helloloop` / `npx helloloop <PATH>` 是实际执行入口
+
+也就是说，用户显式调用 `$helloloop` 时，目标行为应当与主命令保持一致：
+
+1. 先自动识别仓库和开发文档
+2. 再分析当前代码与文档目标
+3. 再展示执行确认单
+4. 最后在你确认后自动接续执行
+
+如果当前目录无法判断目标仓库、缺少开发文档，或者你明确只想先讲解不执行，`HelloLoop` 才应该先停下来问你，而不是直接启动执行。
+
+如果你安装的是 Claude 或 Gemini 宿主，则推荐直接使用：
+
+```text
+/helloloop
+```
+
+它们会按各自 CLI 的原生 agent 逻辑执行，但共享同一套 `.helloloop/` 工作流规范。
+
+## 在 Codex 中使用
+
+可以直接在当前 Codex 会话里运行：
+
+```bash
+npx helloloop
+```
+
+不需要重开终端。
+
+如果你使用的是全局安装后的 `helloloop` 短命令，是否立刻可用取决于当前 shell 是否已经刷新 PATH。
+
+安装为 Codex 插件后，推荐显式使用的 skill 名称是：
+
+```text
+helloloop:helloloop
+```
 
-## 工作机制
+## 跨平台与安全
 
-### 任务模型
+`HelloLoop` 默认兼容 Windows、macOS 和 Linux。
 
-`backlog.json` 中的任务通常包含以下字段：
+### shell 策略
 
-- `id`：任务唯一标识
-- `title`：任务标题
-- `status`：`pending`、`in_progress`、`done`、`failed`、`blocked`
-- `priority`：`P0` 到 `P3`
-- `risk`：`low`、`medium`、`high`、`critical`
-- `goal`：本任务要达成的目标
-- `docs`：执行前必须阅读的文档
-- `paths`：本任务主要涉及的目录
-- `acceptance`：验收条件
-- `dependsOn`：依赖的上游任务
-- `verify`：任务专属验证命令
+- Windows：`pwsh` → `bash`（如 Git Bash）→ `powershell`
+- macOS / Linux：`bash` → `sh`
+- Windows 不会回退到 `cmd.exe`
 
-### 执行流程
+说明：
 
-`HelloLoop` 在每一轮执行中会完成这些事情：
+- `Codex` 路径由当前 Node CLI 严格控制 shell 选择
+- `Claude` / `Gemini` 路径走各自原生插件 / 扩展，但仍应遵守 `HelloLoop` 的安全约束
 
-1. 找出当前可执行任务
-2. 读取仓库状态、任务描述和必读文档
-3. 生成清晰的 Codex 执行提示
-4. 运行 Codex 完成开发
-5. 执行验证命令
-6. 更新任务状态和运行记录
+### 内建兜底规则
 
-### 风险控制
+当开发文档没有给出足够约束时，`HelloLoop` 会自动附加一层最低安全边界，包括但不限于：
 
-- 默认优先自动执行 `low` 风险任务
-- 较高风险任务需要显式允许
-- 存在未完成依赖时，任务不会被挑选执行
-- 存在未收束的执行状态时，循环会停止并等待处理
+- 代码是事实源
+- 验证必须执行
+- 不能静默失败
+- 不能吞掉错误
+- 危险命令必须阻断
+- 路径与 shell 调用必须按跨平台安全方式执行
 
 ## 仓库结构
 
 ```text
 helloloop/
-├── .codex-plugin/         # Codex 插件 manifest 与展示元数据
-├── bin/                   # npm 命令入口
-├── docs/                  # 补充说明文档
-├── scripts/               # 安装脚本与 CLI 入口
-├── skills/                # 插件技能
-├── src/                   # 核心实现
-├── templates/             # 初始化时写入 .helloloop/ 的模板
-└── tests/                 # 回归测试
+├── .claude-plugin/
+├── .codex-plugin/
+├── bin/
+├── docs/
+├── hosts/
+├── scripts/
+├── skills/
+├── src/
+├── templates/
+└── tests/
 ```
 
 其中：
 
-- `src/` 用来放 `HelloLoop` 的实际实现逻辑，例如任务选择、状态加载、执行流程、提示词生成和安装流程
-- `tests/` 用来做回归验证，确保 CLI、模板、插件 bundle 和执行流程没有被改坏
-- `templates/` 是初始化目标仓库时写入 `.helloloop/` 的模板来源
+- `.claude-plugin/`：Claude plugin 元数据
+- `.codex-plugin/`：Codex plugin 元数据
+- `hosts/`：Claude marketplace/plugin 与 Gemini extension 的运行时资产
+- `src/`：核心实现，例如路径发现、分析提示词、任务调度、执行与安装
+- `tests/`：回归测试，覆盖 CLI、安装链路、bundle 结构和关键流程
+- `templates/`：初始化目标仓库 `.helloloop/` 时写入的模板
 
-## 相关文档
+## 许可证
 
-- `docs/README.md`：插件 bundle 结构补充说明
-- `docs/install.md`：安装说明
-- `docs/plugin-standard.md`：官方插件结构与标准对照
+`HelloLoop` 使用 `Apache-2.0`，许可证文件位于仓库根目录 `LICENSE`。

package/hosts/claude/marketplace/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "helloloop-local",
+  "owner": {
+    "name": "HelloLoop"
+  },
+  "plugins": [
+    {
+      "name": "helloloop",
+      "displayName": "HelloLoop",
+      "description": "基于开发文档分析当前进度、展示确认单，并在确认后继续接续开发的 Claude Code 原生插件。",
+      "source": "./plugins/helloloop"
+    }
+  ]
+}

package/hosts/claude/marketplace/plugins/helloloop/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "helloloop",
+  "version": "0.2.0",
+  "description": "HelloLoop 的 Claude Code 原生插件。",
+  "author": {
+    "name": "HelloLoop"
+  },
+  "license": "Apache-2.0"
+}

package/hosts/claude/marketplace/plugins/helloloop/commands/helloloop.md

@@ -0,0 +1,28 @@
+---
+description: 根据开发文档分析当前进度、生成确认单，并在确认后继续接续开发
+argument-hint: [PATH]
+---
+
+你现在正在执行 HelloLoop 的 Claude Code 原生工作流。
+
+规则如下：
+
+1. 将当前代码视为事实源，将开发文档视为目标源。
+2. 如果用户在命令后提供了 `$ARGUMENTS`，只把它解释为一个路径；该路径可能是项目仓库、开发文档目录或开发文档文件。
+3. 自动识别目标仓库与开发文档，并先分析“当前代码做到哪里了”“与文档目标是否存在偏差”。
+4. 在目标仓库根目录创建或刷新 `.helloloop/`，至少维护 `backlog.json`、`project.json`、`status.json`、`STATE.md` 与 `runs/`。
+5. 如果用户给了开发文档但无法定位项目仓库，或者给了项目路径但无法定位开发文档，必须停下来询问用户，而不是猜测。
+6. 在真正执行开发前，必须输出一份中文执行确认单，至少包含：
+   - 目标仓库
+   - 开发文档
+   - 当前进度
+   - 已实现事项
+   - 待完成事项
+   - 任务统计
+   - 首个待执行任务
+   - 验证命令预览
+   - 自动执行停止条件
+7. 未经用户确认，不要开始正式修改代码。
+8. 用户确认后，使用 Claude Code 的原生工具持续推进 backlog，直到完成、遇到硬阻塞或需要用户补充关键信息。
+9. 始终优先使用安全 shell 与原生文件工具；在 Windows 上避免危险的嵌套命令、路径拼接删除和 `cmd` 风格破坏性命令。
+10. 不要调用外部 `npx helloloop` 来替代这个原生工作流；你现在就在 HelloLoop 的 Claude Code 原生模式中。

package/hosts/claude/marketplace/plugins/helloloop/skills/helloloop/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: helloloop
+description: 当用户希望 Claude Code 按开发文档先分析当前进度，再展示确认单，并在确认后持续接续开发时使用。
+---
+
+# HelloLoop for Claude Code
+
+这是 `HelloLoop` 的 Claude Code 原生技能入口。
+
+## 默认流程
+
+1. 自动识别目标仓库与开发文档
+2. 分析当前代码与文档目标之间的真实进度和偏差
+3. 在目标仓库根目录创建或刷新 `.helloloop/`
+4. 输出中文执行确认单
+5. 用户确认后，继续用 Claude Code 原生工具接续开发、测试和验收
+
+## 关键规则
+
+- 如果缺少目标仓库或开发文档，必须停下来询问用户。
+- 不允许跳过执行确认单直接开始正式开发。
+- 不允许把开发文档整体压成一个大任务；需要输出足够细的 backlog。
+- 代码是事实源，开发文档是目标源。
+- 遇到失败、阻塞、依赖未满足或风险超出自动阈值时，必须明确说明当前状态。
+
+## `.helloloop/` 最低要求
+
+- `backlog.json`
+- `project.json`
+- `status.json`
+- `STATE.md`
+- `runs/`
+
+## 安全要求
+
+- Windows 上避免使用危险的嵌套命令、拼接删除命令和 `cmd` 风格破坏性流程。
+- 不允许静默失败、静默回退、吞掉错误。
+- 真正执行前先确认，真正结束前先验证。