Rung

Rung 是面向 Coding Agent 的通用软件开发 Harness，以 Skill 形式提供从设计到交付的工程指导、执行规范与验证要求。它通过渐进式治理与项目既有 Harness 融合，依据当前任务加载所需内容，并复用项目的事实源、工具链与交付机制。

当前稳定版本为 v0.1.0；main 上的候选开发线版本为 0.1.2。稳定引用和候选版本由 rung/contracts/rung-contract.json 维护。产品定义、系统边界和实现约束以 Rung.md 为准。

快速开始

安装稳定版本：

npx skills add https://github.com/LuckRookie/Rung/tree/v0.1.0/rung

安装完成后，可通过显式调用声明开发任务及其约束：

$rung 修复批量取消订单的问题，保持 HTTP 行为与返回格式兼容，完成相关验证。
$rung 为导出功能增加 JSON 格式，保持已有 CSV 行为，并明确相关规则的职责归属。

版本	适用范围
v0.1.0	稳定发布包；具体能力以该 tag 的文档为准
main（0.1.2 候选）	评估当前入口、结构修复指导与 Evidence v2；使用时记录 Git 提交标识，行为收益尚在验证

评估候选版时，应从指定 Git 提交复制完整 rung/ 包至隔离的 Skill 目录；已有安装按照 INSTALL.md 的更新约定处理。仓库变更不会自动同步至已安装副本。完整安装、作用域和验证说明见 安装。

核心能力

能力	预期作用
工程判断	追溯缺陷原因与规则归属，区分必须一致的共享规则和独立变化的实现知识
项目适配	使用项目的模块职责、依赖约束、扩展位置和设计取舍，并维护其既有记录
设计与结构	根据实际行为和变化场景选择职责、接口、数据及代码位置
可执行计划	将完整范围分解为结果块和任务，明确前置条件、实际动作与完成检查
实施与复查	保护用户工作，完成必要的结构调整，检查最终集成结果
验证与交付	依据实际检查报告完成程度，区分验证通过、具备发布条件与已经发布
项目规则演进	以独立证据修订失效的指令、检查和交付要求，保留必要保护

这些能力通过入口和按需指南提供。指南规定预期行为；工程收益仍需通过真实任务和对照评测验证，不能由规则数量或文档完整性推导。

Progressive Governance

Rung 先判断任务是否涉及持续维护的软件及其开发决定，再判断是否需要额外指导。隐式调用适用于职责、契约、状态、兼容、迁移、验证或交付存在实质决定的任务；目标、影响和直接检查均明确的局部可逆修改沿用宿主普通编码路径。显式调用可以用于范围内的小任务。具体边界见 Rung.md §4.1。

安装使 Skill 可被发现，并不保证每个任务都会加载。项目常设指令明确要求使用 Rung 时，在声明范围内按显式调用处理；每次任务重新核对适用指令。采用方式见 INSTALL.md。

任务由一个 Agent 对整体结果负责，按当前需要组合以下指南：

Clarify · Inspect · Design · Plan · Implement · Verify · Review · Release

这些指南支持澄清、调查、设计、计划、实施、验证、复查和交付，可以合并、跳过或重新使用。普通任务通过现有会话和项目工具完成。持久记录、协作 Agent 和确定性助手分别在有助于恢复、执行或可靠检查时使用。详细责任见 执行指南，完成状态见 工作流程。

最终报告说明完成了什么、执行了哪些检查，以及仍有哪些缺口。方案完成不表示已实施，检查通过不表示已发布；交付请求只有在指定且经过授权的目标实际完成后，才能报告发布成功。

项目专属规则

Rung 与项目既有指令、架构文档和工具共同工作。项目接入或实际变更暴露职责缺口时，Agent 恢复模块职责、依赖方向、扩展位置、关键取舍和相关检查，区分当前实现、已接受的约束与待验证的建议。现有结构可以作为证据，不能仅因其已经存在就被固化为规范。

长期规则写入项目已有维护位置，并从宿主实际读取的指令入口引用；缺少适当位置且确有后续使用需求时，才创建简明文档。首次访问不自动触发全仓库扫描、固定命名的架构文档或新增审批。结构变化同步更新对应指导，授权范围内的常规决定继续由 Agent 完成。具体要求见 项目规则与工具指南。

按需扩展

当前问题	指南
项目面向谁、解决什么问题，或新能力是否符合方向	项目画像
重要设计有多条后果不同的合理路径	设计探索
职责、代码位置或依赖关系需要选择	工程结构与架构设计
需要评估既有架构以形成改造决定	架构评估
当前修改存在质量权衡	软件质量
现有状态会使可信的后续工作产生额外成本	技术债
缺少可靠检查或需要修改检查机制	验证系统与规则及工具演进

仅加载当前决定需要的内容，不预加载无关阶段。Lite、Standard、Strict 提示分析与协调深度；验证层级 0–3 表示证据覆盖范围，两者独立选择。必要的分析、完整计划和验证可以增加投入；成本评价同时考虑正确性、返工、恢复和后续维护。

Skill 包

rung/
├── SKILL.md                 # 开发范围、工程指导与按需路由
├── agents/openai.yaml       # Codex UI 元数据
├── references/              # 阶段卡与按需领域指南
├── profiles/                # 可选治理深度提示
├── assets/                  # 可选开发制品模板
└── scripts/                 # 确定性检查助手

安装

Rung 采用 Agent Skills 仓库分发方式。skills CLI 会在仓库中发现 rung/SKILL.md，安装完整 Skill 包，并记录来源和内容哈希。

Codex 用户级安装：

npx skills add https://github.com/LuckRookie/Rung/tree/v0.1.0/rung --skill rung --agent codex --global --yes

安装到当前项目时移除 --global，目标目录为 .agents/skills/rung。用户级安装使 Rung 对该用户的不同项目与工作目录可见；项目级安装将发现范围限定于当前项目。Rung 默认保留隐式调用，description 聚焦实质软件开发决定，Development Scope Gate 负责误触后的二次核对。

Codex 提供 $skill-installer 时，也可以直接发送：

使用 $skill-installer 安装这个 Skill：
https://github.com/LuckRookie/Rung/tree/v0.1.0/rung

完整的作用域、冲突处理、手动安装和验证规则见 INSTALL.md。该文件也可以直接交给 Coding Agent；私有仓库沿用 Agent 环境中已经配置的 GitHub 访问权限：

从 https://github.com/LuckRookie/Rung.git 获取 v0.1.0 tag，完整读取根目录 INSTALL.md，
按照其中的安装契约把 Rung 安装到用户级作用域，并在完成后验证安装结果。

调用

$rung 为现有项目实现导出功能，并准备一个经过验证的可发布版本。

调用后，Agent 按任务范围和实际影响选择指导，使用项目既有规则与检查，并说明结果、验证和未完成范围。

可选确定性工具

重复执行、结构化证据或可靠退出码能够改善任务时，可以使用以下脚本。

运行指导由 Agent 遵循，检查脚本仅在实际调用时验证其覆盖的条件，项目 CI 或宿主控制负责已配置的强制检查。安装 Rung 不会自动建立强制拦截。Rung 助手是可选入口；项目要求的必需检查仍然有效，可以通过项目原生命令执行，不能因未使用助手而省略或报告为通过。

项目检查：

python rung/scripts/inspect_project.py --project .

执行显式 JSON 验证计划：

python rung/scripts/run_verification.py \
  --project . \
  --plan .rung/runs/RUN_ID/verification-plan.json \
  --max-tier 2 \
  --output .rung/runs/RUN_ID/evidence.json

Verification Plan 使用 schema v2；revision 可以省略，也可以填写预期 Commit 或精确 State Identity。Runner 在执行前后记录项目状态和 Plan 摘要，状态漂移会把 Evidence 适用性降为 blocked。--max-tier 选择本次执行的最高验证层并记录跳过项；跳过发布必需检查的 Evidence 不能支持 ready 或 published。命令输出在读取期间保持有界，非法编码使用替换字符保留，Timeout 会终止命令进程组。

候选版本使用 Verification Plan / Evidence v2，Target / Final State 还须具有状态 schema v2 标记。旧 Plan、只有顶层 status 或使用未标记状态算法的 Evidence 需要重新生成，检查器会提示重新验证。Git 项目的身份覆盖整个仓库；子模块等尚未可靠建模的配置明确返回 blocked。覆盖范围、排除规则和兼容边界见 助手证据契约。

需要设计或扩展 Fixture、Mock、测试服务、文档检查、CI Gate、构建、打包或端到端环境时，可以按需形成 .rung/runs/RUN_ID/verification-harness.md；长期 Harness 代码和配置进入目标项目自己的正式结构。

已有 Project Harness 自身进入修改范围时，可以按需形成 .rung/runs/RUN_ID/harness-change.md，记录权威事实、基线、独立证据、Coverage Delta、生效、回退和旧路径清理条件。

检查持久化 Artifact 和 Release Manifest：

python rung/scripts/validate_artifacts.py \
  --run-dir .rung/runs/RUN_ID

python rung/scripts/check_release.py \
  --manifest .rung/runs/RUN_ID/release.yaml \
  --project .

Artifact 检查默认验证运行目录中实际存在的 Rung 制品；需要特定集合时可以重复使用 --require 精确声明。

已确认的技术债通常记录在项目已有管理系统。缺少适当位置且后续工作需要持久记录时，可以选用技术债模板，在可选运行目录中保存为 debt.md。

Release Manifest 标记为 ready 或 published 时，本地 verification 引用使用 Evidence v2。检查器验证 Schema、Check 与聚合状态、Run ID、检查前后状态、Manifest revision，并确认 Plan 中标记 required_for_release 的检查均已执行。Git Clean State 使用 Commit；Git Dirty State 和无 Git 项目使用 Evidence 中的内容身份。外部 CI 或制品 URI 会明确报告为 delegated-unverified，其充分性仍由当前项目流程负责。

inspect_project.py 输出的候选命令带有 confidence: declared | inferred。项目声明的脚本和配置优先；目录名称只有在出现对应语言测试文件时才参与命令推断。

所有脚本只使用 Python 标准库，并输出机器可读 JSON。

核心契约检查：

python rung/scripts/validate_contract.py --skill-root rung

该检查验证范围与启用契约、间接路由可达性、可组合关注面覆盖、上下文预算和包版本事实。它把运行时入口中的关键承诺固定为可验证的契约，但不替代真实 Agent 行为评测。

Scope Gate 的结构化评估：

python rung/scripts/evaluate_scope.py --input scope-classification.json

输入由 Host 提供判断：codebase_relationship、development_claim 取 present | absent | mixed | uncertain；materiality 取 present | absent | uncertain；invocation_mode 取 implicit | explicit。Mixed 表示存在可识别的活跃开发部分；未知不应填写 Mixed。

输出协议为 v2，分别报告 scope 和 activation: enter | bypass | defer。旧的两个字段输入仍能读取，缺失的实质性默认 uncertain，缺失调用方式默认 implicit，不会静默启用。exited_before_references 是退出建议，实际读取必须由 Host Trace 验证；status: pass 仅表示输入有效。工具不替 Agent 判断自然语言，不在每次启动时运行。

开发验证

python -B -m unittest discover -s tests -v
ruff check --no-cache .
python rung/scripts/validate_contract.py --skill-root rung
python rung/scripts/evaluate_scope.py --input <scope-classification.json>

Codex 环境中还应使用 skill-creator 提供的 quick_validate.py 检查 Skill 元数据和结构。

仓库结构

Rung.md                    # 产品与架构事实源
INSTALL.md                 # 人与 Coding Agent 共用的安装契约
rung/                      # 可安装 Skill 包
rung/contracts/            # Scope Gate、路由、预算和版本的机器可读契约
evals/                     # 开发意图、设计探索、项目画像、软件质量、技术债、工程结构、架构评估、Harness 与上下文成本评测
tests/                     # 确定性脚本测试
.github/workflows/ci.yml   # 持续集成
AGENTS.md                  # 本仓库的 Agent 开发约定

v0.1.0

首个稳定版本包含：

• 单一、轻量的 Rung Skill 入口；
• 五个默认治理提示与信号驱动路由；
• 一个明确 Primary Agent、检查半径、Design 持久化、Plan/Implement 责任、Worker/Reviewer 和跨 Session 恢复的 Execution Model Guide；
• 八张可组合的开发关注面提示卡；
• 按代码结构信号加载的工程设计与 diff 复查提醒；
• 按冲突、误报、漏报、漂移和 Gate 变化加载的 Project Harness 与 Harness Evolution 详细指南；
• 按证据缺口加载的 Verification Harness 详细指南、可选 Harness Artifact 与 Tier 筛选执行；
• Lite、Standard、Strict 可选深度提示；
• 可选 DevelopmentRun Artifact 模板；
• 项目检查、验证执行、Artifact 与 Release 检查脚本；
• 无信号、小型 Bugfix、跨模块归属、连续变化、Harness 增长、已有 Harness 演进、单 Session 执行、跨 Session 恢复、Worker 集成和全生命周期指导的行为评测协议；
• 脚本行为测试。

下一轮通过无额外治理信号的 Bugfix、跨模块 Feature、连续 Greenfield 变化、跨 Session 恢复和 Worker-assisted integration 场景，对比基线、当前 Rung 与候选提示，校准触发准确性、执行责任、工程收益、实现多样性和上下文成本。