Skip to content
This repository was archived by the owner on Oct 21, 2026. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions .agents/plugins/marketplace.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
{
"name": "loop-engineering",
"interface": {
"displayName": "Loop Engineering"
},
"plugins": [
{
"name": "loop-engineering",
"source": {
"source": "local",
"path": "./plugins/loop-engineering"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}
]
}
15 changes: 15 additions & 0 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"name": "loop-engineering",
"owner": {
"name": "Moshuiwang"
},
"description": "Evidence-driven GitHub delivery planning, execution, and retrospective skills.",
"plugins": [
{
"name": "loop-engineering",
"source": "./plugins/loop-engineering",
"description": "Plan, execute, and retrospect on evidence-driven GitHub delivery loops.",
"version": "2.3.0"
}
]
}
22 changes: 22 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
name: validate

on:
pull_request:
push:
branches: [main]

permissions:
contents: read

jobs:
distribution:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Validate dual-host plugin distribution
run: python3 scripts/validate_distribution.py
- name: Run validator regression tests
run: python3 -m unittest discover -s tests -v
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
node_modules/
__pycache__/
*.pyc
103 changes: 78 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,39 +1,92 @@
# loop-engineering

Claude Code 的 Loop 系列 skill:把"用 GitHub Issue/Project 做持续交付"这套长期打磨出来的
工作方式,封装成 4 个可组合的 skill,供 Claude Code(以及适配后的 Codex)直接调用。
Loop Engineering 把基于 GitHub Issue、Project、PR 与 CI 的持续交付方法封装为一个原子化
plugin,同时支持 Codex 与 Claude Code。两个宿主加载同一组 skill 和同一份 Plan 合同,不再
维护或手工复制平行版本。

这个仓库原先是一套 Loop 持续交付 runner 的代码实现;随着经验沉淀为下面这 4 个 skill,
runner 代码已被 skill 化的工作流取代,仓库内容替换为 skill 定义本身。
## 能力

## Skill 系列
plugin 按顺序提供四个可组合 skill:

按执行顺序:
1. **[loop-starter](plugins/loop-engineering/skills/loop-starter/SKILL.md)**:确定范围、
`governance` 档位与 Plan 级目标证据层级。
2. **[loop-planner](plugins/loop-engineering/skills/loop-planner/SKILL.md)**:形成可由人类批准的
Loop Execution Plan v2 机器可读合同。
3. **[loop-executor](plugins/loop-engineering/skills/loop-executor/SKILL.md)**:按获批 Plan 实现、
复查、等待 CI、交付并在 merge 后 closeout。
4. **[loop-retrospective](plugins/loop-engineering/skills/loop-retrospective/SKILL.md)**:基于真实
Issue、PR、CI 与 Project 证据复盘周期、质量和治理规则。

1. **[loop-starter](skills/loop-starter/SKILL.md)** — 门禁定标阶段。确定本次 loop 的范围
(哪些 Issue 进入、Epic 粗分组)、仪式重量(复查预算、合并政策、检查点)与 Plan 级最终
验收,写入 Plan Issue 的 `governance` 骨架。
2. **[loop-planner](skills/loop-planner/SKILL.md)** — 把范围细化为一份可批准的 Loop
Execution Plan(v2 机器可读合同),持久化为 GitHub Issue。合同规范见
[`references/plan-contract-v2.md`](skills/loop-planner/references/plan-contract-v2.md)。
3. **[loop-executor](skills/loop-executor/SKILL.md)** — 按已批准的 Plan 持续执行:测试优先
实现、按风险分级的独立 Review、CI 等待、人工 merge 后 closeout、证据回写。
4. **[loop-retrospective](skills/loop-retrospective/SKILL.md)** — 基于 Issue/PR/CI 证据复盘
一份 Plan 的执行效率与规则改进点。
合同格式的唯一真值是
[plan-contract-v2.md](plugins/loop-engineering/skills/loop-planner/references/plan-contract-v2.md)。

## 安装

### Codex

```bash
codex plugin marketplace add Moshuiwang/loop-engineering
codex plugin add loop-engineering@loop-engineering
```

升级已安装版本:

```bash
codex plugin marketplace upgrade loop-engineering
codex plugin add loop-engineering@loop-engineering
```

### Claude Code

个人跨项目使用:

```bash
mkdir -p ~/.claude/skills
cp -r skills/loop-starter skills/loop-planner skills/loop-executor skills/loop-retrospective \
~/.claude/skills/
claude plugin marketplace add Moshuiwang/loop-engineering
claude plugin install loop-engineering@loop-engineering --scope user
```

## 治理与真值顺序
需要把启用声明提交到某个业务仓库时,改用 `--scope project`。升级已安装版本:

```bash
claude plugin marketplace update loop-engineering
claude plugin update loop-engineering@loop-engineering
```

安装或升级后开启新会话再使用。不要把本仓库的 skill 手工复制到 `~/.codex/skills`、
`~/.claude/skills` 或业务仓库;plugin cache 是可再生安装产物,不是编辑入口。

Codex 使用 `$loop-engineering:loop-starter`、`$loop-engineering:loop-planner`、
`$loop-engineering:loop-executor`、`$loop-engineering:loop-retrospective` 显式调用;Claude Code
使用对应的 `/loop-engineering:loop-starter` 等命名空间命令。

## 开发与验证

只在本仓库的 `plugins/loop-engineering/skills/` 修改技能。四个 skill 作为一个 suite 随 plugin
版本原子发布;合同或治理语义变化必须同时检查四个 skill,不能只更新单个宿主副本。

```bash
python3 scripts/validate_distribution.py
python3 -m unittest discover -s tests -v
claude plugin validate --strict plugins/loop-engineering
claude plugin validate --strict .
```

本仓库 CI 运行不依赖本机 Codex/Claude 安装的结构、版本、路径与合同一致性检查;宿主 CLI
validator 与 Codex 内建的 skill/plugin validator 仍应在发布前本地执行。

## 问题回流

- 只适用于某个业务仓库的命令、验收或授权规则,修改该仓库的 `AGENTS.md`/`CLAUDE.md`。
- 通用 loop 工作流、合同或宿主兼容问题,在本仓库创建 Issue 并通过分支与 PR 修复。
- 紧急试验使用本仓库分支和本地 marketplace;不直接修改用户 skill 目录或 plugin cache。
- 修复时记录宿主、plugin 版本、触发步骤、预期/实际和脱敏证据,并把真实故障转成回归检查。

- 目标仓库自己的 `AGENTS.md`/`CLAUDE.md`、Project README 定义治理与边界;
- Plan Issue 的 `loop-plan` YAML 块保存获批队列、依赖、授权、`governance` 与完成条件;
- GitHub Project 是唯一 `Status` 真值;
- Git、PR、CI 保存实施证据。
## 治理与事实源

不建平行的 Markdown 进度表。批准只能来自会话内人类的明确指示。
- GitHub `Moshuiwang/loop-engineering` 是唯一可写源码权威;`main` 保存已接受现状,PR 只保存
候选变更,tag/Release 标识可安装版本。
- GitLab 历史 remote 只用于归档或只读追溯,不接受新提交,也不反向覆盖 GitHub。
- 目标业务仓库的 `AGENTS.md`/`CLAUDE.md`、Project README 定义项目边界。
- Plan Issue 的 `loop-plan` YAML 保存批准队列、依赖、授权、`governance` 与完成条件。
- GitHub Project 是唯一 Status 真值;Git、PR、CI 与结构化评论保存实施证据。
- 不建立平行 Markdown 进度表。批准只能来自会话内人类的明确指示。
12 changes: 12 additions & 0 deletions plugins/loop-engineering/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"name": "loop-engineering",
"version": "2.3.0",
"description": "Plan, execute, and retrospect on evidence-driven GitHub delivery loops.",
"author": {
"name": "Moshuiwang",
"url": "https://github.com/Moshuiwang"
},
"homepage": "https://github.com/Moshuiwang/loop-engineering",
"repository": "https://github.com/Moshuiwang/loop-engineering",
"keywords": ["github", "delivery", "planning", "review", "retrospective"]
}
27 changes: 27 additions & 0 deletions plugins/loop-engineering/.codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
{
"name": "loop-engineering",
"version": "2.3.0",
"description": "Plan, execute, and retrospect on evidence-driven GitHub delivery loops.",
"author": {
"name": "Moshuiwang",
"url": "https://github.com/Moshuiwang"
},
"homepage": "https://github.com/Moshuiwang/loop-engineering",
"repository": "https://github.com/Moshuiwang/loop-engineering",
"keywords": ["github", "delivery", "planning", "review", "retrospective"],
"skills": "./skills/",
"interface": {
"displayName": "Loop Engineering",
"shortDescription": "Evidence-driven GitHub delivery loops",
"longDescription": "Scope, plan, execute, and retrospect on approved GitHub delivery plans with explicit authorization, review, CI, and evidence gates.",
"developerName": "Moshuiwang",
"category": "Productivity",
"capabilities": ["Interactive", "Write"],
"websiteURL": "https://github.com/Moshuiwang/loop-engineering",
"defaultPrompt": [
"Use $loop-engineering:loop-starter to scope and govern a new delivery loop.",
"Use $loop-engineering:loop-planner to create an approvable Loop Execution Plan.",
"Use $loop-engineering:loop-retrospective to audit a completed Loop Plan."
]
}
}
Loading
Loading