# CraftKit 协作约定

本文件适用于 CraftKit 仓库及其全部子目录。更深层目录若存在自己的 `AGENTS.md`，以更具体的约定为准。

## 项目目标

CraftKit 面向 Codex 插件市场，提供简洁、中性、可独立安装和维护的 Skill。每项能力都应具备清晰边界，并能够独立理解与验证。

## 沟通与改动

- 所有回答、文档和代码注释使用中文；公开 API、标准名称和代码标识可以保留英文。
- 修改前先说明方案。简单改动可在说明后直接执行；复杂或高风险改动先明确范围、影响和验证方式。
- 阅读、分析和评审任务默认只读，不因发现问题自动扩大为修改任务。
- 未经明确要求，不提交、不推送、不安装插件，也不修改用户级 Codex 配置。
- 保留工作区已有改动；提交时只暂存本次确认范围内的文件。

## 目录职责

| 路径 | 职责 |
| --- | --- |
| `.agents/plugins/marketplace.json` | CraftKit 市场及插件入口 |
| `plugins/dev/` | 软件设计、编码、审查与测试 Skill |
| `plugins/doc/` | 文档转换、整理与写作 Skill |
| `plugins/git/` | Git 操作与交付 Skill |
| `plugins/knowledge/` | 交接、复盘与知识维护 Skill |
| `plugins/skill/` | Skill 与项目规范辅助工具 |

## Skill 设计规则

- Skill 名称使用小写字母、数字和连字符，简短且以动作或明确领域为中心。
- Skill 文件夹名必须与 `SKILL.md` frontmatter 的 `name` 完全一致。
- `description` 只说明能力和触发场景，避免大而全、宽泛兜底或堆砌关键词。
- `SKILL.md` 只保留共同目标、关键流程和必要边界；条件性细节放入 `references/`。
- 只有重复执行且确定性逻辑明显时才新增 `scripts/`；新增脚本必须有可运行验证。
- 只有产物确实需要模板、图片或样例文件时才新增 `assets/`。
- 不创建没有实际用途的空目录、占位文档或重复 README。
- 自动发现保持默认开启；只有用户明确要求时才设置为仅显式调用。

推荐结构：

```text
plugins/<plugin>/skills/<skill>/
├─ SKILL.md
├─ agents/openai.yaml      # 有 UI 元数据时使用
├─ scripts/                # 有确定性自动化时使用
├─ references/             # 有条件加载的详细资料
└─ assets/                 # 生成产物需要的素材
```

## 维护原则

- 以当前 Codex 能力、项目实际情况、公开标准和用户需求为依据设计 Skill。
- 技术规则应注明适用版本；依赖外部资料时记录资料入口和验证日期。
- 新增内容应具备明确用途，避免重复能力、过期说明和仅用于记录开发过程的文档。

## 新增与修改流程

1. 阅读目标插件、相邻 Skill、适用的 `AGENTS.md` 和当前 Git 状态，确认职责边界与已有改动。
2. 明确用户目标、输入、输出、触发条件、副作用、权限和不包含事项。
3. 检查是否应复用或扩展已有 Skill，避免名称不同但职责重复的实现。
4. 修改前向用户说明目标文件、实现方式、风险和验证方法；高风险或范围不明确时等待确认。
5. 按最小必要结构实现，优先使用项目证据和官方资料，不猜测接口、版本或运行行为。
6. 完成结构、引用、插件清单及必要行为验证，并分别记录通过项和未验证边界。
7. 展示实际变更、验证结果、剩余风险和建议提交信息；只有用户明确授权后才执行本地提交。

## CraftKit 项目目录

- `.craftkit/` 是项目级 Agent 配置、规范、知识和运行状态的统一目录，目录名固定为全小写；不能把整个目录视为本地缓存或整体排除。
- 可共享内容包括 `project.json`、`agents/`、`standards/`、`knowledge/` 和 `handoff/`，可以根据用户确认正常提交和同步。
- `project.json` 记录项目类型、技术栈、源码与包边界、内部依赖标识、常用命令和规范入口；不得记录凭据、完整连接信息或个人机器绝对路径。
- 成熟项目优先延续已有且有充分证据的风格；空项目根据需求、用户选择和已授权参考建立最小上下文，不自行猜测框架、包名或内部依赖。
- 引用其他项目时先确认参考范围，只提炼结构、依赖、命名、测试、规范或工具约定；共享配置优先记录相对路径，不能共享的本地位置放入 `local/`。
- 公共框架版本差异由 CraftKit 公共 profile 维护；项目在 `project.json` 选择实际版本和 profile，并在 `standards/` 保存项目补充规则。
- `agents/` 保存项目对特定 Agent 的补充说明；`standards/` 保存项目开发规范；`knowledge/pitfalls/` 保存经验证且可复用的问题经验；`knowledge/decisions/` 保存重要技术决策。
- 本地内容统一放入 `local/`，缓存统一放入 `cache/`。`.craftkit/.gitignore` 必须排除 `/local/` 和 `/cache/`，但不得排除整个 `.craftkit/`。
- 本地交接默认位于 `.craftkit/local/handoff/current.md`；只有用户明确选择共享时才写入 `.craftkit/handoff/current.md`。
- 只在实际需要时创建目录，不一次生成空的 `agents/`、`standards/`、`knowledge/`、`handoff/`、`local/` 或 `cache/`。
- Git Skill 默认排除 `.craftkit/local/**` 和 `.craftkit/cache/**`；其他 `.craftkit` 内容按普通项目资产评估，并在提交建议中单独标识。
- 如果本地目录已经被 Git 跟踪，或整个 `.craftkit/` 被全局规则、`.git/info/exclude` 或项目规则忽略，应提示冲突并停止自动处理；不得自动修改索引或历史。
- `.craftkit/` 不得保存凭据、令牌、私钥、个人机器绝对路径或无必要的个人信息。

## 验证要求

每个新增或修改的 Skill 至少完成：

1. 检查目录名、frontmatter、引用路径和工具名称。
2. 运行仓库现有的 Skill 校验器及所属插件校验器。
3. 检查凭据、无效路径、未替换占位符和无效工具名称。
4. 有脚本时运行核心行为测试；有生成物时检查实际产物。
5. 以真实请求检查触发边界、权限边界和输出是否符合描述。

静态检查通过不代表真实行为已经验证，交付时应分别说明静态校验、脚本测试和实际场景验证结果。

## Git 约定

- 使用 Conventional Commits，提交说明使用中文。
- 推荐类型：`feat`、`fix`、`docs`、`refactor`、`test`、`chore`。
- 提交前执行 `git status --short`、`git diff --cached --check` 并检查暂存文件清单。
- 不提交本地配置、凭据、缓存、运行产物和 IDE 私有状态。
- 不使用破坏性历史改写，也不推送，除非用户明确授权。

## 分支与发布约定

- 一个完整主题使用一个短生命周期开发分支；分支只包含同一能力闭环，不为凑版本混入无关变更。
- 分支命名优先遵循仓库现有约定；没有更具体规则时使用 `feature/<short-name>`、`fix/<short-name>`、`docs/<short-name>` 或 `chore/<short-name>`。
- 工作区不干净、当前 checkout 被 IDE/服务/测试占用，或用户要求不影响主工作区时，使用独立 Worktree。分支任务完成后必须通过安全清理门禁移除额外 Worktree，保留分支和提交。
- 已验证的开发分支合入 `master` 后，先在 `CHANGELOG.md` 的 `Unreleased` 累计；形成一组相关、完整、可交付的能力后再发布，不因每次普通修改单独发版。
- 阻断性缺陷、安全问题或已发布能力的明确回归可以单独发布修订版本；不得为等待批次延迟必要修复。
- 仓库整体版本遵循 SemVer：不兼容变化升级主版本，向后兼容的新能力升级次版本，向后兼容的问题修复升级修订版本。
- `dev`、`doc`、`git`、`knowledge` 和 `skill` 插件清单版本按实际变化独立维护；修改某个插件的可见能力时同步评估其 `plugin.json` 版本。
- 发布前必须确认工作区、发布范围、版本号、验证证据、`CHANGELOG.md`、插件清单版本、标签目标和远程地址。版本提交、标签和推送分别按用户授权执行。