team-constitution

team-constitution

此技能的作用

通过交互式引导，在 {TEAM_AI_DIRECTIVES}/context_modules/constitution.md 中创建或修订团队章程。

由 team-setup（模式 3）写入的脚手架仅包含占位内容（“No team-wide principles defined yet”）。此技能通过引导式征询，将该占位内容转化为真正的章程：

• 根据团队背景（现有规则、CDR、AGENTS.md）提出原则
• 交互式审阅每项原则——确认、编辑或拒绝
• 按既定的团队格式编写章程（OKF v0.2 frontmatter + 编号原则 + Governance 部分）

此技能不是什么：

• 不是 spec-kit 的 spec.constitution 模板机制的移植版——没有占位符、钩子、extensions.yml、模板传播或 Sync Impact Report
• 不是语义化版本控制——团队章程通过团队 AI 指令仓库中的 git 历史进行版本管理；通过 /team-repair 使用 OKF v0.2 frontmatter（generated、verified、stale_after）跟踪时效性
• 不适用于项目级章程（docs/adlc/memory/constitution.md，或旧版 .adlc/memory/constitution.md 回退路径）——使用 spec-kit 时，这些仍属于 spec.constitution 的范畴

何时使用

• 在 team-setup 模式 3 之后：脚手架写入了占位章程——用实际原则填充它
• 新建的团队 AI 指令（克隆或现有）：缺少章程或章程仍是占位内容
• 修订原则：团队希望添加、改写或移除原则

何时不使用

• 项目级章程：使用 spec-kit 的 spec.constitution 来处理 docs/adlc/memory/constitution.md（旧版 .adlc/memory/constitution.md 回退路径）
• 通过 CDR 流程更改章程：如果章程变更是作为 CDR 提出的，请让 /team-levelup 处理
• 未配置团队 AI 指令：先运行 /team-setup

流程

用户输入

$ARGUMENTS

如果用户输入不为空，必须先考虑该输入，再继续操作。

用户输入示例：

• "Focus on testing and security principles" — 引导提案侧重于这些领域
• "Amend principle 3" — 直接跳到修订特定原则
• "Add a principle about AI code review" — 添加特定原则
• 输入为空：执行完整的引导流程（自动检测是创建还是修订）

角色与背景

你将担任团队治理引导者——帮助团队阐明不可妥协的原则。你的职责包括：

• 根据团队实际的指令和实践提出原则（而非泛泛的模板内容）
• 确保每项原则都以声明形式表达、可测试且理由明确
• 保持章程简洁——原则是规则，不是长篇文章

大纲

1. 环境设置（阶段 0）：解析路径，检测章程状态
2. 加载团队背景（阶段 1）：读取现有章程和团队指令，为提案提供依据
3. 征询原则（阶段 2）：交互式创建/修订循环
4. 治理部分（阶段 3）：撰写精简的治理段落
5. 编写章程（阶段 4）：使用 OKF v0.2 frontmatter 写入文件
6. 提交与摘要（阶段 5）：提供提交选项并报告结果

执行步骤

阶段 0：环境设置

从技能的基目录运行设置脚本：

scripts/bash/setup-team-constitution.sh

解析 JSON，获取 REPO_ROOT、TEAM_AI_DIRECTIVES、CONSTITUTION_FILE、CONSTITUTION_STATE、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. CONSTITUTION_FILE — {TEAM_AI_DIRECTIVES}/context_modules/constitution.md
4. CONSTITUTION_STATE：
   • missing — 文件不存在
   • placeholder — 文件存在且包含 "No team-wide principles defined yet"
   • populated — 文件存在且包含实际内容
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）

如果未配置 TEAM_AI_DIRECTIVES：

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

阶段 1：加载团队上下文

阅读以下内容，为原则提案提供依据：

1. 现有章程：{CONSTITUTION_FILE}（如果状态为 populated，则进行修订；如果为 placeholder/missing，则创建）
2. 团队规则索引：{TEAM_AI_DIRECTIVES}/CDR.md — 已接受的规则/角色设定/示例描述可反映团队已有的关注重点
3. 现有规则：浏览 {TEAM_AI_DIRECTIVES}/context_modules/rules/ 中的文件名和标题
4. AGENTS.md：{TEAM_AI_DIRECTIVES}/AGENTS.md — 加载顺序和技能使用预期

原则必须以实际发现为依据——例如，如果规则目录中安全相关模块占多数，那么“默认安全”原则就有事实依据，而非套用模板。如果团队 AI 指令几乎为空，则退而采用一小组入门原则，并明确说明这一点。

阶段 2：征求原则意见

创建模式（missing 或 placeholder）

1. 根据阶段 1 的发现提出一组入门原则（3–7 条）。对于每条原则，请提供：

### Proposed Principle N: {Name}

**Statement**: {Declarative, testable rule — one or two sentences}

**Rationale**: {Why this principle exists; what failure it prevents}

**Grounding**: {What team context motivated this — or "starter suggestion, no team AI directives evidence yet"}

Reply: [Y] accept / [e] edit / [n] reject

2. 对每条回复：

   • Y：将其加入已接受列表
   • e：根据用户的修改调整，并展示修订后的原则以供确认
   • n：删除该原则

3. 提出入门原则后，询问：“还有其他原则吗？” 循环进行，直到用户表示完成。

修订模式（populated）

1. 列出现有原则（编号，每条一行）。
2. 询问要如何处理：修订 N / 新增 / 删除 N / 全面审查。
3. 对于修订和新增，使用与创建模式相同的提出 → 确认/修改/拒绝流程。
4. 删除前必须明确确认——删除是影响最大的更改。

原则质量标准（适用于每条已接受的原则）：

• 明确且可测试：Agent 可以检查是否合规（“每个 X 都必须 Y”），而不是表达愿景（“我们重视 X”）
• 不可妥协的表述：原则必须使用 MUST；偏好和惯例应归入规则，而非章程
• 包含理由：用一句话说明该原则可避免什么失败
• 避免含糊措辞：将 “should” 替换为 MUST/NEVER，或将该条目移至规则

阶段 3：治理部分

撰写简短的治理部分。仅包含以下三点（不要扩展）：

## Governance

- **Amendments**: proposed as CDRs via `/team-init` or `/team-levelup`, reviewed and published via `/team-levelup`. Direct edits via `/team-constitution` are reserved for bootstrapping and explicit team decisions.
- **Compliance**: this constitution is loaded by `team-boot` at the start of every session. Agents and humans MUST follow it; on conflict, the constitution supersedes ad-hoc practices.
- **Alignment**: `/team-repair` (Check 6) verifies project constitutions inherit these principles. Project constitutions may extend, never contradict.

阶段 4：编写章程

按以下确切结构编写 {CONSTITUTION_FILE}：

---
type: Constitution
title: "{TEAM_NAME} Constitution"
description: "Team-wide principles and governance"
resource: ./context_modules/constitution.md
tags: [constitution]
generated: { by: agent:team-constitution, at: {TODAY}T00:00:00Z }
id: constitution
cdr_ref: null
created: {TODAY}
verified:
  - { by: agent:team-constitution, at: {TODAY}T00:00:00Z }
status: stable
stale_after: 180d
---

# {TEAM_NAME} Constitution

1. **{Principle Name}**
   {Statement. Rationale.}

2. **{Principle Name}**
   {Statement. Rationale.}

...

## Governance

{Governance section from Phase 3}

编写规则：

• 修改时保留现有的 OKF v0.2 frontmatter 字段；将 generated.at 更新为今天的日期，并追加到 verified 列表中。如果文件包含自定义字段（created、id、cdr_ref），请保留。删除所有旧版 v0.1 字段（timestamp、modified、age_days、evidence）（如果存在）——/team-repair 会自动处理。
• title 和 H1：如果已有团队名称，则保留；否则根据团队 AI 指令目录名称推导，或询问用户。
• 使用编号的扁平列表（1. **名称**）——每条原则下不得有 ### 子章节，也不得有版本／批准日期行。
• 如果 CONSTITUTION_STATE 为 missing，请先创建父目录：mkdir -p "{TEAM_AI_DIRECTIVES}/context_modules"。

阶段 5：提交与摘要

如果 TD_IS_GIT 为 true 且 TD_CLEAN 为 true，则在当前分支上提出一次提交（不走分支／PR 流程——这属于 CDR 生命周期的职责）：

Commit the constitution update to team-ai-directives?
  git -C "{TEAM_AI_DIRECTIVES}" add context_modules/constitution.md
  git -C "{TEAM_AI_DIRECTIVES}" commit -m "docs: {create|amend} team constitution — {N} principles"
[Y/n]

如果 TD_CLEAN 为 false，则跳过提交，并说明团队 AI 指令有未提交的更改。

报告：

## Team Constitution Summary

**Mode**: {Create | Amend}
**File**: {CONSTITUTION_FILE}
**Principles**: N ({added} added, {amended} amended, {removed} removed)
**Committed**: {yes | no — reason}

### Principles

1. {Name} — {one-line statement}
2. ...

### Next Steps

1. Run `/team-repair` to validate the team AI directives and refresh verification timestamps
2. Review project constitutions for alignment (team-repair Check 6)

关键规则

有依据，不套模板

• 有团队上下文可用时，提案必须引用相关内容（CDR 描述、规则标题、AGENTS.md）
• 团队 AI 指令为空时，说明初始条目为通用内容，并保持简短（3–5 条）

仅限团队格式

• 使用 OKF v0.2 frontmatter、编号原则和 Governance——不使用 spec-kit 模板结构
• 不得添加 **Version**／**Ratified** 行——版本由 git 历史记录
• 每条原则下不得有 ### 子章节——使用编号扁平列表

交互式，而非自动化

• 写入前，每条原则都必须由用户确认
• 绝不可悄然重写现有的 populated 章程——修订模式要求逐条明确决定

不要混淆流程

• 项目章程（docs/adlc/memory/constitution.md）不在范围内
• 由 CDR 驱动的章程变更应通过 /team-levelup 进行，而非使用此技能

工作流指南与衔接

使用 /team-constitution 后

/team-setup (Mode 3 scaffold — placeholder constitution)
    ↓
/team-constitution (this skill — real principles)
    ↓
/team-repair (validate team AI directives, refresh freshness)

后续修订遵循 CDR 生命周期（/team-init 或 /team-levelup → 规范制定 → 澄清 → 发布）；也可以使用 /team-constitution 进行明确的交互式编辑。

验证

• {CONSTITUTION_FILE} 存在，且包含 OKF v0.2 frontmatter（含 type: Constitution 和 generated 字段）
• placeholder 标记文本已删除
• 每条原则都包含加粗名称、陈述性内容和理由
• 存在 Governance 章节，且包含三项内容（修订、合规、对齐）
• 不包含占位符标记（[ALL_CAPS]），也不包含版本／批准日期行
• 修订后的文件保留了原有的自定义 frontmatter 字段，并更新了 modified
• 已报告摘要，包含模式、原则数量和提交状态

配置

• TEAM_AI_DIRECTIVES — 团队 AI 指令的路径（覆盖 .adlc/init-options.json）。
• .adlc/init-options.json — 包含 team_ai_directives 字段的项目级配置文件。
• 默认回退路径：相对于项目根目录的 team-ai-directives/。

12-Factor 对齐

Factor XI（指令即代码）——团队的基础治理文档会创建并维护为受版本控制的产物，绝不会临时嵌入提示词中。

上下文

$ARGUMENTS