# comet-flow

**Repository Path**: genvex/comet-flow

## Basic Information

- **Project Name**: comet-flow
- **Description**: hermes 编程智能编排
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-02
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ☄️ Comet Flow — SDD 自动化工作流

**结构化、可复现的软件交付方法论。**  
Open → Design → Build → Verify → Archive 五阶段状态机，强制守卫条件 + 子代理并行开发 + 两级审核。

> 作者: [Maker羊毛党](https://mp.weixin.qq.com/)  
> 运行环境: [Hermes Agent](https://hermes-agent.nousresearch.com)

---

## 核心理念

不是随意写代码，而是像科学实验一样做软件：

```
┌─────────┐    ┌──────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│  Open   │───▶│  Design  │───▶│  Build  │───▶│ Verify  │───▶│ Archive │
│ 需求→规  │    │ 设计评审  │    │ 子代理开发│    │ 强制验证 │    │ 归档闭环 │
└─────────┘    └──────────┘    └─────────┘    └─────────┘    └─────────┘
```

每个阶段都有 **守卫条件**，交付物没完成不能跳下一阶段。

---

## 组件

| 组件 | 说明 |
|------|------|
| `comet-flow` (Hermes Skill) | 五阶段状态机描述 + 行为规则 |
| `comet-state.sh` | 统一状态管理 CLI（init / get / set / status / list） |
| `comet-guard.sh` | 阶段过渡守卫，条件不满足报错退出 |
| `proposal.md` (模板) | 提案模板：方案对比 + 影响范围 + 安全边界 |
| `phase-behavior.md` | 阶段映射：阶段→Agent 行为→交付物 |
| `iot-project-pattern.md` | IoT 多模块并行开发模式（3+ 独立模块） |
| `subagent-driven-development` (依赖 Skill) | 子代理 + 两级审核（Spec Review → Quality Review） |
| `writing-plans` (依赖 Skill) | 实现计划编写：粒度化任务 + 完整代码 + 命令 |

---

## 快速安装

```bash
# 解压
tar -xzf comet-flow.tar.gz
cd comet-flow

# 运行安装脚本
chmod +x install.sh
./install.sh
```

安装脚本会：
1. ✅ 检查 Hermes Agent 是否安装
2. ✅ 安装 comet-flow skill 到 `~/.hermes/skills/`
3. ✅ 安装依赖技能（subagent-driven-development, writing-plans）
4. ✅ 安装命令行工具（comet-state.sh → ~/.local/bin/comet 别名）
5. ✅ 检查并提示安装 yq（YAML解析器，可选但有更好）
6. ✅ 初始化示例变更

---

## 日常用法

### 启动新变更

```bash
# 初始化
comet init add-flight-filter "给飞行雷达加按高度筛选功能"
comet status

# 在 Hermes 中：
# /comet 你的目标描述
# → 自动创建变更 → 苏格拉底追问 → 生成提案
```

### 推进阶段

```bash
# Hermes slash 命令
/comet-open      # 需求→结构化提案+规格
/comet-design    # 提案→设计文档
/comet-build     # 设计→子代理+TDD开发
/comet-verify    # 强制验证
/comet-archive   # 归档闭环

# 快捷模式
/comet-hotfix    # 修 Bug（跳过设计）
/comet-tweak     # 小改动（跳过设计+完整计划）
```

### 状态管理

```bash
# CLI
comet status             # 查看当前状态
comet list               # 列出所有变更
comet set my-change phase build   # 手动推进阶段
comet set my-change verify_result pass  # 标记验证通过
```

---

## 依赖

- **Hermes Agent**（必需）— 主运行环境
- **yq**（推荐，可选）— YAML 解析器；无 yq 时用 sed 回退

安装 yq：
```bash
# Linux
sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
sudo chmod +x /usr/local/bin/yq

# macOS
brew install yq
```

---

## 设计原则

1. **不清零不进下一级** — 当前阶段交付物未完成，不得推进
2. **守卫强制** — 推进前必须通过 guard 检查
3. **状态持久化** — 每阶段操作更新 `.comet.yaml`
4. **隔离开发** — Build 阶段在分支/工作树进行
5. **验证强约束** — Verify 不通过不得归档
6. **TDD** — 先写测试，再写实现
7. **子代理并行** — 3+ 独立模块并行开发

---

## 文件结构

```
~/.hermes/skills/software-development/comet-flow/
├── SKILL.md                    # 主方法论（Hermes Skill）
├── scripts/
│   ├── comet-state.sh          # 状态管理 CLI
│   └── comet-guard.sh          # 阶段守卫
├── templates/
│   └── proposal.md             # 提案模板
└── references/
    ├── phase-behavior.md       # 阶段→行为映射
    └── iot-project-pattern.md  # IoT 并行开发模式

~/.hermes/comet/
└── changes/
    └── <change-name>/
        ├── .comet.yaml         # 状态文件
        ├── proposal.md
        ├── design-doc.md
        ├── spec.md
        ├── tasks.md
        └── (产出代码)
```