levelup-publish

levelup-publish

此技能的功能

将已接受的 CDR编译为 team-ai-directives 团队 AI 指令中的实际产物，并创建草稿 PR。

这是 CDR 生命周期中的实施阶段：

• 根据信号门验证已接受的 CDR
• 发布前检测 CDR 之间的冲突
• 生成上下文模块文件（规则、角色、示例、章程）
• 为评估类型的 CDR 生成评估金标文件（goldset.md + goldset.json）
• 生成技能产物（SKILL.md + .skills-entry.json）
• 更新 .skills.json 清单
• 更新 team-ai-directives 中的 CDR.md 索引
• 创建分支、提交更改并发起草稿 PR

只有在通过 /levelup-clarify 接受 CDR 后，此技能才会运行。

适用场景

• 在 /levelup-clarify 之后：需要发布已接受的 CDR
• 构建单个技能：使用 --skill <name|CDR-id> 构建一个技能
• 仅构建上下文模块：使用 --context-only 跳过技能生成

不适用场景

• 没有已接受的 CDR：先运行 /levelup-clarify
• team-ai-directives 中存在未提交的更改：先清理工作树
• 发现模式：使用 /levelup-init 或 /levelup-specify
• 审核 CDR：使用 /levelup-clarify

流程

用户输入

$ARGUMENTS

如果用户输入不为空，你必须在继续操作前予以考虑。

用户输入示例：

• "--ready" — 创建已就绪的 PR，而不是草稿 PR
• "--skip-skills" — 不包含技能 CDR
• "--context-only" — 仅构建上下文模块
• "--skill CDR-005" — 仅构建来自 CDR-005 的技能
• "CDR-001 CDR-003" — 仅实施指定的 CDR
• 空输入：将所有已接受的 CDR 作为草稿 PR 实施

标志

• --ready：创建已就绪的 PR，而不是草稿 PR
• --skip-skills：跳过技能类型的 CDR
• --context-only：仅构建上下文模块（跳过所有技能）
• --skill <name|CDR-id>：仅从指定的已接受技能 CDR 构建一个技能

角色与上下文

你将担任上下文发布者，负责将已接受的 CDR 从本地草稿移至 team-ai-directives。

你的职责包括：

• 验证 CDR 是否已接受且已就绪
• 根据 CDR 内容创建上下文模块文件
• 根据技能类型的 CDR 创建技能产物
• 管理 Git 操作（分支、提交、推送、PR）

概述

1. 环境设置（阶段 0）：解析路径并列出已接受的 CDR
2. 先决条件检查（阶段 1）：确保已配置 team-ai-directives 且工作树干净
3. 信号门验证（阶段 2）：筛除缺少具体证据的 CDR
4. 跨 CDR 冲突检查（阶段 3）：检测重复目标和规则冲突
5. 分支准备（阶段 4）：在 team-ai-directives 中创建分支
6. 上下文模块生成（阶段 5）：构建规则/角色/示例/章程
7. 评估金标生成（阶段 6）：为评估 CDR 构建 goldset.md + goldset.json
8. 技能生成（阶段 7）：构建 SKILL.md + .skills-entry.json
9. log.md 更新（阶段 8）：将 OKF §9 条目追加到各目录的 log.md
10. AGENTS.md 检查（阶段 9）：如果不存在则创建
11. 提交与 PR（阶段 10）：发布更改
12. 摘要（阶段 11）：报告结果

执行步骤

阶段 0：环境设置

运行：

scripts/bash/setup-levelup-publish.sh

解析 JSON，获取 REPO_ROOT、TEAM_AI_DIRECTIVES、CDR_DRAFTS_DIR、ACCEPTED_CDRS、TD_CONFIGURED、TD_IS_GIT、TD_CLEAN。

如果设置脚本不可用或运行失败，请手动解析：

1. REPO_ROOT — 从当前工作目录向上查找 .adlc/，或运行 git rev-parse --show-toplevel，或使用 pwd。
2. TEAM_AI_DIRECTIVES — 依次检查 TEAM_AI_DIRECTIVES 环境变量、.adlc/init-options.json 中的 team_ai_directives，然后是 REPO_ROOT/team-ai-directives。
3. CDR_DRAFTS_DIR — REPO_ROOT/.adlc/drafts/cdr
4. ACCEPTED_CDRS — 运行 grep -l '^### Status: \*\*Accepted\*\*' CDR_DRAFTS_DIR/CDR-*.md 并提取 ID。
5. TD_IS_GIT — git -C "$TEAM_AI_DIRECTIVES" rev-parse --is-inside-work-tree（退出码为 0 = true）。
6. TD_CLEAN — git -C "$TEAM_AI_DIRECTIVES" status --porcelain（输出为空 = clean）。

如果 TD_IS_GIT 为 false，则无法运行阶段 10（分支／提交／PR）。请提出为 team AI directives 执行 git init，或不使用 git 直接写入文件。

阶段 1：前置条件检查

验证团队指令已配置：

Team AI directives repository not configured.
Run: team-setup
Or set: export TEAM_AI_DIRECTIVES=/path/to/team-ai-directives

检查工作树：

如果 TD_CLEAN 为 false：

team-ai-directives has uncommitted changes.
Please commit or stash changes before running /levelup-publish.

检查已接受的 CDR：

如果 ACCEPTED_CDRS 为空：

No accepted CDRs found.
Run /levelup-clarify to accept CDRs first.

阶段 2：信号门验证

针对每个已接受的 CDR，根据以下四项标准进行评估：

1. 适用于整个团队：此模式是否适用于多个项目／团队，还是仅适用于一个项目？如果 CDR 的上下文或证据只涉及单个项目的内部情况，且没有可推广的经验教训 → 跳过（原因：“特定于项目”）。

2. 证据质量：CDR 是否引用了具体的文件路径、提交 SHA 或测试用例？如果证据部分为空或内容模糊（“各种文件”、“一般做法”）→ 跳过（原因：“没有证据”）。

3. 独特性：这是否与 team-ai-directives 中现有的指令重复？检查 context_modules/rules/、context_modules/examples/ 和 CDR.md 中是否有重叠内容。如果存在重叠 → 跳过（原因：“重复”）。

4. 高价值：这是一个真正有用的模式，还是一个可有可无的小便利？如果 CDR 明确写明“价值低”或“只是小便利”，或者该模式过于简单（例如“使用分号”）→ 跳过（原因：“价值低”）。

跳过未通过任一标准的 CDR。被跳过的 CDR 仍保留在本地草稿中。

报告：

## Signal Gate Validation

**Passing**: N | **Skipped**: M

### Skipped CDRs

| CDR | Reason |
|---|---|
| CDR-003 | No evidence |
| CDR-005 | Project-specific |

阶段 3：跨 CDR 冲突检查

检查以下情况：

1. 目标重复：多个 CDR 指向同一模块路径
2. 规则冲突：关注点相同，但实现方式不同
3. 未解决的不一致：类型为“Inconsistency”且未标记为 Resolved 的 CDR

如果发现冲突：

Cross-CDR conflicts detected. Resolve via /levelup-clarify before implementing.

阶段 4：分支准备

在 team-ai-directives 中创建分支（如果 TD_IS_GIT=false 则跳过——git 操作将在阶段 10 中处理）：

cd "$TEAM_AI_DIRECTIVES"
git checkout -b "levelup/$(basename "$REPO_ROOT")" main 2>/dev/null || git checkout -b "levelup/$(basename "$REPO_ROOT")"

阶段 5：生成上下文模块

为每个已接受的非技能类 CDR 创建或更新目标文件。

从 CDR 中提取字段：CDR 使用单行字段格式（### Field: value）。解析 ### 前缀后面的行以提取值：

• title — 来自 ## CDR-NNN: 标题
• description — 来自 ### Descriptor: 行
• id — 来自 ## CDR-NNN 标题（例如，CDR-001）
• cdr_ref — 与 id 相同
• domain — 来自 ### Domain: 行（默认值：general）
• context-type — 来自 ### Context Type: 行（转换为小写；默认值：rule）
• created — 来自 ### Date: 行（若未提供，则使用今天的日期）
• evidence — 来自 ### Feature Implementation Evidence 或 ### Evidence 部分正文
• {Content from CDR} — 来自 ### Context 部分正文
• OKF v0.2 字段由此生成：resource = 基于上下文类型/领域/文件的相对路径，tags = 上下文类型，generated.at = ISO 8601 日期时间。如果存在 evidence 条目，则将每项映射为一个 sources[] 条目；如果为空，则省略 sources。

规则（OKF v0.2 前置内容）：

---
type: Rule
title: {title}
description: {description}
resource: ./context_modules/rules/{domain}/{file}.md
tags: [{context-type}]
generated: { by: agent:levelup-publish, at: {today}T00:00:00Z }
id: {id}
cdr_ref: {cdr_ref}
created: {created}
verified:
  - { by: agent:levelup-publish, at: {today}T00:00:00Z }
status: stable
stale_after: 180d
sources:
  - id: {evidence-id-or-derived}
    resource: {evidence-resource-or-path}
    title: {evidence-title}
---

# {Title}

{Content from CDR}

## Source

Contributed from: {project-name}
CDR: {cdr_ref}

写入模块文件后，向 context_modules/rules/index.md 追加一行（OKF §8 列表格式）：

* [{Title}](relative-path.md) - {description}

如果 context_modules/rules/index.md 不存在，则先创建该文件，并添加 # Rules 标题。

Persona 和 Example 使用类似模板，并设置相应的 type。

Constitution：

• 对于 Constitution Creation CDR：创建 context_modules/constitution.md
• 对于 Constitution Amendment CDR：追加到现有 constitution

阶段 6：生成评测 Goldenset

为每个已接受的评测类型 CDR 在 team-ai-directives/evals/ 中生成 goldenset 文件。

从评测 CDR 中提取字段：解析 CDR 的单行字段：

• directive_id — 来自 ### Paired Directive CDR: 行（例如，CDR-001）
• descriptor — 来自 ### Descriptor: 行
• pass_cases — 来自 ### Pass Cases 部分正文
• fail_cases — 来自 ### Fail Cases 部分正文
• adversarial_cases — 来自 ### Adversarial Cases 部分正文

步骤 1：创建 evals 目录

mkdir -p "$TEAM_AI_DIRECTIVES/evals/{directive_id}"

步骤 2：编写 goldset.md

编写 {TEAM_AI_DIRECTIVES}/evals/{directive_id}/goldset.md：

---
type: Eval
title: {title from CDR}
description: {descriptor from CDR}
resource: ./evals/{directive_id}/goldset.md
tags: [eval]
generated: { by: agent:levelup-publish, at: {today}T00:00:00Z }
id: {eval CDR id}
cdr_ref: {eval CDR id}
paired_directive: {directive_id}
created: {date from CDR}
verified:
  - { by: agent:levelup-publish, at: {today}T00:00:00Z }
status: stable
stale_after: 180d
---

# Goldset: {Title}

## Directive Under Test

- **CDR**: {directive_id}
- **Path**: {target module of paired directive CDR}

## Pass Cases

{pass cases from CDR — each with scenario, input, output, why-it-passes}

## Fail Cases

{fail cases from CDR — each with scenario, input, output, why-it-fails, correction}

## Adversarial Cases

{adversarial cases from CDR — each with scenario, expected}

步骤 3：编写 goldset.json

编写 {TEAM_AI_DIRECTIVES}/evals/{directive_id}/goldset.json — 供评分器使用的机器可读版本：

{
  "id": "{eval CDR id}",
  "paired_directive": "{directive_id}",
  "title": "{title}",
  "description": "{descriptor}",
  "cases": [
    {
      "id": "PASS-001",
      "type": "pass",
      "scenario": "...",
      "input_context": "...",
      "expected_output": "...",
      "actual_output": "...",
      "reason": "..."
    },
    {
      "id": "FAIL-001",
      "type": "fail",
      "scenario": "...",
      "input_context": "...",
      "expected_output": "...",
      "actual_output": "...",
      "reason": "...",
      "correction": "..."
    }
  ]
}

步骤 4：报告

Eval goldenset published: evals/{directive_id}/goldset.md
Eval goldenset JSON: evals/{directive_id}/goldset.json

阶段 7：生成技能

如果指定了 --skip-skills，或所有技能类 CDR 均已排除，则跳过。

对于技能类型的 CDR（或指定了 --skill <name|CDR-id> 时）：

1. 生成 skills/{name}/SKILL.md：

---
name: {name}
description: {description from CDR}
disable-model-invocation: true
---

# {name}

## What this skill does

{Summary}

## When to use

- {Trigger 1}
- {Trigger 2}

## Steps

1. {Step 1}
2. {Step 2}

## Example

{Minimal example}

## Verification

{How to verify}

## Related

- CDRs: {cdr_ref}

2. 生成 skills/{name}/.skills-entry.json：

{
  "name": "{name}",
  "description": "{description}",
  "version": "1.0.0",
  "cdr_ref": "{cdr_ref}"
}

3. 在 .skills.json 中注册：

{
  "local:./skills/{name}": {
    "version": "1.0.0",
    "description": "{description}",
    "categories": ["..."]
  }
}

4. 在 AGENTS.md 的 Skills 部分中更新新技能。

阶段 8：更新 log.md（OKF §9）

对于每个已接受且在阶段 5 中已写入模块的 CDR，向相应的 context_modules/<type>/log.md 文件追加一条记录（OKF §9 按日期分组的格式，最新记录在前）：

## {today}
* **Creation**: Added [{Title}](relative-path.md) — {one-line description}. CDR: {cdr_ref}.

如果 context_modules/<type>/log.md 不存在，则先创建该文件，并添加 # {Type} Update Log 标题。

publish 不再手动更新 CDR.md。 CDR.md 是派生文件，由 /team-repair 根据各目录的 index.md 文件自动生成。合并 PR 后，运行 /team-repair 以重新生成 CDR.md。

阶段 9：检查 AGENTS.md

如果缺少 AGENTS.md，则根据模板创建。

阶段 10：提交并创建 PR

验证已创建的文件，然后按照 git 决策树操作：

情况 A：team-ai-directives 是 git 仓库（TD_IS_GIT=true）

1. 创建分支（如果存在 main，则使用它；否则使用 HEAD）：

cd "$TEAM_AI_DIRECTIVES"
git checkout -b "levelup/$(basename "$REPO_ROOT")" main 2>/dev/null || git checkout -b "levelup/$(basename "$REPO_ROOT")"

2. 提交：

git add -A
git commit -m "Add context modules from $(basename "$REPO_ROOT")

CDRs implemented:
- CDR-001: ...
- CDR-002: ...
"

3. 检查是否存在远程仓库：

git remote get-url origin 2>/dev/null

4a. 如果存在远程仓库“origin”且 gh CLI 可用 — 推送并创建草稿 PR：

git push -u origin "levelup/$(basename "$REPO_ROOT")"
gh pr create --draft --title "Add context modules from $(basename "$REPO_ROOT")" --body "..."

4b. 如果存在远程仓库“origin”但 gh 不可用 — 仅推送，并告知用户手动创建 PR：

git push -u origin "levelup/$(basename "$REPO_ROOT")"

报告：“已推送到 origin/levelup/{project-name}。请在 Git 托管平台手动创建 PR。”

4c. 如果不存在远程仓库 — 仅在本地提交。报告：“已提交到本地分支 levelup/{project-name}。准备就绪后，添加远程仓库（git remote add origin <url>）并推送。”

情况 B：team-ai-directives 不是 git 仓库（TD_IS_GIT=false）

向用户提供两个选项：

1. git init + 提交 — 初始化 git，使用脚手架创建初始提交，然后提交新的上下文模块：

cd "$TEAM_AI_DIRECTIVES"
git init
git add -A
git commit -m "Initial team-ai-directives scaffold"
git checkout -b "levelup/$(basename "$REPO_ROOT")"
git add -A
git commit -m "Add context modules from $(basename "$REPO_ROOT")"

然后按照上述第 3–4 步操作（检查远程仓库）。

2. 仅写入文件 — 跳过所有 git 操作。文件将直接写入工作树。报告：“文件已写入 {TEAM_AI_DIRECTIVES}。准备就绪后初始化 git 并提交。”

阶段 11：摘要

## LevelUp Implement Summary

**Project**: {project-name}
**Branch**: levelup/{project-name}
**CDRs Implemented**: N
**CDRs Skipped (Signal Gate)**: M

### Artifacts Created

| Type | Count |
|---|---|
| Rules | N |
| Personas | N |
| Examples | N |
| Skills | N |
| Constitution Changes | N |
| Evals | N |

### PR Details

**URL**: {PR-URL}
**Status**: Draft

### Next Steps

1. Review PR
2. Merge when approved
3. Run `/team-repair` after merge to re-index and validate

关键规则

仅实现已接受的 CDR

• 状态必须为 Accepted
• 跳过 Discovered/Proposed/Rejected 状态的 CDR

信号门控

• 严格模式：跳过缺少具体证据的 CDR
• 被跳过的 CDR 保留在本地草稿中，以供完善

跨 CDR 验证

• 遇到未解决的冲突时停止
• 必须使用 /levelup-clarify 解决

记忆工程

• 已发布文件包含 YAML frontmatter，其中包含 OKF v0.2 系列：generated、verified（列表）、status、stale_after
• log.md 文件跟踪每个目录的审计记录（OKF §9）
• CDR.md 由 /team-repair 根据 index.md 文件派生，不手动维护

先创建上下文模块，再编辑 log.md

• 重要：先创建所有上下文模块和技能文件，再向 log.md 追加内容
• 不要先写入 log.md 条目，却跳过实际模块的创建

工作流指南与转换

执行 /levelup-publish 后

在 team-ai-directives 中合并 PR 后，运行 /team-repair 以：

• 将所有剩余的 v0.1 frontmatter 迁移到 v0.2（始终执行）
• 重建各目录的 index.md 和 log.md 文件
• 根据 index.md 文件重新派生 CDR.md 扁平表格
• 扫描冲突
• 刷新验证时间戳

完整的 CDR 生命周期

/levelup-init or /levelup-specify
    ↓
/levelup-clarify
    ↓
/levelup-publish
    ↓
PR merged
    ↓
/team-repair --validate

后续步骤

实施完成后，监控 PR 的评审进度。合并后，运行 /team-repair 验证更新后的团队 AI 指令。

验证

• 所有已接受的 CDR 均通过信号门控，或被明确跳过
• 在 {TEAM_AI_DIRECTIVES}/context_modules/ 中创建上下文模块文件，并包含 OKF v0.2 frontmatter（generated、verified 列表、status、stale_after）
• 追加各目录的 index.md 条目（OKF §8 列表格式）
• 追加各目录的 log.md 条目（OKF §9 按日期分组的格式）
• 在 {TEAM_AI_DIRECTIVES}/evals/ 中创建评测 goldenset 文件（适用于评测类型的 CDR）
• 在 {TEAM_AI_DIRECTIVES}/skills/ 中创建技能目录（除非已跳过）
• 使用新技能更新 .skills.json
• 创建描述完善的草稿 PR
• 提交后，team-ai-directives 工作树保持干净
• 合并后：运行 /team-repair，根据 index.md 文件重新生成派生的 CDR.md

上下文

$ARGUMENTS