Shaelz/codebase-trellis-skill

Codebase Trellis

结构化、支持并安全地集成 AI 辅助代码变更。

生态系统：

• codebase-orient 理解代码库。
• codebase-visualize 映射代码库。
• codebase-trellis 支持安全的变更生长和集成。

---

何时使用此技能

使用此技能时

• 文件已更改，需要安全暂存、提交计划或提交执行。
• 需要设置、完成或清理分支或工作树。
• 需要检查或准备推送、PR 或 CI 状态。
• 需要审计 Git/GitHub 仓库状态。
• 长期运行的代理会话在继续前需要进行结构化状态审查。
• 工作树脏乱，下一步正确操作不明确。

跳过此技能时

• 任务是微小的、单一文件的、已知修复，且没有 Git 状态不确定性。
• 正在进行只读探索，且没有计划进行提交/推送/清理工作。
• 另一个技能（codebase-orient、codebase-visualize）刚刚被调用，且之后没有 Git 工作。

---

简单与结构化分类

在运行任何工作流之前，对每次调用进行分类。

简单通过：

• 局部化的 bug 修复
• 仅文档或仅复制更改
• 依赖项升级
• 小型重构
• 仅测试更改
• 已确定范围的提交准备

结构化通过：

• 广泛的多文件更改
• 多个包
• UI 加 API 加测试
• 迁移或生成的文件
• 长期运行的代理工作
• 预期多个提交
• 可能需要的恢复或交接

不确定时默认简单。如果检查证明工作比最初看起来更大，则提升为结构化。在安全状态建立后，永远不要降级。

---

执行层

Trellis 在四层安全模型中运行。这些层不等同，且没有一层可以替代另一层。

第1层：技能纪律（核心 v1 层）

技能检查、报告并限制危险操作。在任何正常的 Git 仓库中工作，无需额外的钩子或 GitHub 访问。这是行为层面的——取决于代理遵循技能。

第2层：本地 Git 钩子

仓库本地钩子可以在提交或推送期间运行。Trellis 可能推荐钩子，但 v1 中不要求或安装它们。钩子可能缺失、可通过 --no-verify 绕过，或不跨克隆共享。

第3层：Claude Code 钩子

主机级钩子可以围绕工具使用、文件更改和权限进行操作。仅是可选的加固——不要求用于独立核心。不要假设它们已安装。

第4层：GitHub 保护

GitHub 侧执行：分支保护、规则集、必需的检查、必需的审查、签名提交、强制推送限制、合并队列、秘密扫描、代码扫描、Dependabot。当 API 访问允许时进行检查和报告；永远不要假设保护存在。

不等价规则：

• 技能纪律不是钩子。
• 本地钩子不是 GitHub 分支保护。
• 通过 grep 的本地检查不是秘密扫描。
• PR 头检查不是合并队列检查。
• 可见的绿色勾号不足以证明所有必需检查已通过相关 SHA。

如果一个层不可用或未验证，请明确说明。

---

互操作性边界

独立核心

Codebase Trellis 必须在任何正常的 Git 仓库中工作，而不需要姐妹技能的工件。它拥有：

• Git 状态和脏状态检查
• 已暂存、未暂存、未跟踪、已忽略、生成、敏感和预先存在的更改检测
• 提交分组和提交计划交接
• 分支/工作树安全
• 推送/PR/CI 门控
• 清理规则
• Trellis 报告输出

可选建议读取

如果姐妹技能工件存在，Trellis 可以仅作为建议上下文读取它们。

来自 codebase-orient（示例：docs/ai/CODEBASE_MAP.md、docs/ai/CHANGE_SURFACES.md、docs/ai/OPEN_QUESTIONS.md）：

• 仓库布局和包/工作区结构
• 已知检查和生成文档策略
• 重要约定和危险区域

来自 codebase-visualize（示例：docs/ai/visualize/codebase-graph.json）：

• 影响范围和受影响的模块
• 文档到代码的边和高中心性文件

规则：

• 不要要求这些文件。
• 不要重新生成它们。
• 不要静默修改它们。
• 不要因为可视化缺失而阻塞常规的提交计划。
• 不要将其视为比源代码/配置/规范文档更具权威性的内容。

交接触发器

• 当仓库结构不清晰、已知检查未知或代理缺乏足够上下文来分类风险时，建议 /codebase-orient。
• 当变更影响广泛或架构性、依赖关系重要或影响范围会改善决策时，建议 /codebase-visualize。

---

通用规则

始终：

1. 从识别仓库根目录、分支和脏状态开始。
2. 在提议命令之前展示状态。
3. 分别列出已暂存、未暂存、未跟踪、已删除和已忽略的文件。
4. 将部分暂存的文件视为模糊且有风险的。
5. 从所有提交计划中排除敏感文件。
6. 偏好精确的文件列表而不是宽泛的路径命令。
7. 命令失败时停止。
8. 当 gh 不可用或缺乏权限时说明。
9. 保持报告简短且可操作。
10. 报告已知和未知的内容；不要将未知状态合并为假定安全。

从不：

1. 未经明确批准确切文件列表，运行 git add .。
2. 未展示计划文件和提交消息就提交。
3. 在提交中包含推送。
4. 在推送中包含合并。
5. 使用 git push --force。
6. 推断 --force-with-lease；必须明确请求。
7. 未经确认分支名称就删除分支。
8. 移除不是此会话创建或不是明确项目本地可丢弃的工作树。
9. 在提交计划中包含 .env、密钥、令牌、凭据或已忽略文件。
10. 除非已验证，否则声称测试、CI 或 GitHub 设置已通过。
11. 仅凭本地 grep 或可见检查就声称“没有机密”或“没有漏洞”。
12. 除非相关 SHA 和必需检查都已确认，否则报告 CI 为绿色。
13. 静默包含预先存在的脏文件。
14. 静默包含未跟踪文件。

---

风险门控

只读——无需批准：

• git status、git diff --stat、git log、git remote -v
• gh pr view、gh run list、gh repo view
• 任何不改变状态的检查或诊断命令

低状态变更——在“执行”模式下需要可见计划和批准：

• 创建本地分支
• 创建本地工作树
• 暂存明确列出的文件
• 根据批准的计划创建提交

高状态变更——需要明确批准：

• 推送（任何分支）
• 创建 PR
• 合并分支
• 变基分支
• 编辑分支保护或规则集
• 删除分支
• 移除工作树

危险——需要键入确认，且优先输出命令而不是执行：

• 推送到受保护分支（需要键入分支名称）
• --force-with-lease 推送（必须明确请求）
• git reset --hard
• git clean -fd 或任何未跟踪文件移除
• 删除包含未合并提交的分支
• 重写公共历史
• 秘密历史修复

git push --force 始终禁止。

---

敏感文件模式

永远不要将这些包含在提交计划中。如果用户警告后覆盖，再次警告并建议不要这样做。

.env
.env.*
*.pem
*.key
*.p12
*.pfx
id_rsa*
*.cert
.aws/credentials
credentials.json
*.secret
token.txt
.npmrc
auth.json
service-account*.json

也排除：已忽略文件、构建输出、缓存和依赖文件夹，除非仓库有意跟踪它们。

常见排除项：

node_modules/
dist/
build/
.cache/
.svelte-kit/
.next/
coverage/
__pycache__/
*.pyc

---

安全可见性边界

Trellis 可能报告可见的安全信号。Trellis 不是完整的扫描器。

可见时报告：

• 本地 diff 中形状像秘密的文件（文件名或模式匹配 .env、*.key 等）
• GitHub 秘密扫描和推送保护是否似乎已启用
• CodeQL 或代码扫描是否已配置
• Dependabot 警报或安全更新是否可见
• 依赖文件在此 diff 中是否更改

永远不要声称：

• 仅因为本地 grep 没找到就声称“未发现机密”
• 仅因为可见的 GitHub 检查是绿色就声称“没有漏洞”
• 安全状态是干净的，除非通过专用安全工具验证

---

GitHub/CI 可见性边界

报告哪些可以验证，哪些不能。不要将未知保护状态合并为假定安全。

CI 模式是不同的——不要混淆它们：

PR 级就绪：

• 此 PR 是否可合并？
• 必需检查是否通过了此 SHA？
• 待处理、跳过或取消的检查是否相关？

工作流运行检查：

• 为什么此运行失败？
• 哪个作业或步骤失败？
• 日志或工件是否可用？

GitHub 保护状态——报告以下之一：

• 保护状态：已验证 — <摘要>
• 保护状态：未验证。不要假设 main 是受保护的。

合并队列——如果要求合并队列，PR 头检查不是最终信号。分别报告：

• PR 头检查
• 必需检查
• 合并队列或合并组检查（如果存在）
• 被检查的 SHA 是否与正在讨论的提交匹配

永远不要添加到合并队列、启用自动合并或未经明确用户批准进行合并。

---

Trellis 报告

Trellis 报告是每次检查或计划传递的签名输出。

完整形式

Trellis report

Root check
- Repo root:     <当前工作目录；如果是链接工作树，这是工作树路径>
- Main repo:     <父仓库根目录，来自 GIT_COMMON_DIR（如果是链接工作树）；如果不是链接工作树则省略>
- Branch:
- Remote/upstream:
- Worktree state: <链接工作树在 <路径> / 主仓库检出 / 分离头指针>
- Identity/signing state:
- Baseline dirty files (pre-existing):

Tangle check
- Staged changes:
- Unstaged changes:
- Untracked files:
- Ignored/generated files of note:
- Sensitive-looking files:
- Partially staged files:
- Mixed concerns:

Growth plan
- Suggested change groups:
- Suggested commit boundaries:
- Suggested PR shape:
- Files excluded from scope:
- Files requiring user decision:

Gate check
- Safe to inspect/read: yes
- Requires approval before staging:
- Requires approval before commit:
- Requires approval before push:
- Requires approval before merge/auto-merge:
- Requires approval before cleanup/delete:

Canopy check
- GitHub repository/PR visibility:
- Required checks:
- CI state and SHA checked:
- Branch protection/ruleset state:
- Merge queue state:
- Security signals visible:
- Unknowns/unverified protections:

Next safe action
- Recommendation:
- Exact commands (read-only only, or with gate annotation):
- Decision required from user:

简短形式

用于简单传递或小型工作树。

Trellis report
- Root: <仓库 / 分支 / 工作树摘要>
- Tangle: <已暂存 / 未暂存 / 未跟踪 / 敏感 / 混合关注点摘要>
- Growth: <提交/PR 分组建议>
- Gates: <需要批准的操作>
- Canopy: <GitHub/CI/保护状态（如果已知），或“未验证”>
- Next: <一个安全的下一步操作>

停止形式

当 Trellis 无法或必须停止时使用。

Trellis stop
- Stop reason:
- Evidence:
- Risk if ignored:
- Safe recovery options:
- Recommended option:

停止原因包括：

• 敏感样式的文件将被暂存。
• 预先存在的脏文件将被静默包含。
• 部分暂存的文件使意图模糊。
• 目标分支受保护或未知，并且请求了推送/合并。
• 请求了强制类似操作而没有明确的风险接受。
• 声明的推送或 CI 状态引用不同的 SHA。
• 另一个分支、工作树或 PR 似乎拥有相同的任务。

---

模式路由

读取 $ARGUMENTS。

如果未提供模式，则运行 audit。

支持的模式：

• audit：只读本地 Git 和 GitHub 状态审查
• start：使用分支或工作树准备隔离的工作
• commit：计划或执行连贯的提交
• push：准备或执行推送和 CI 监控
• finish：通过 PR、本地合并、保留或放弃来结束分支
• recover：从 Git 错误中恢复

---

audit 模式

运行只读诊断。生成 Trellis 报告。永远不要修改任何本地或远程状态。

审计预检——本地 Git

始终首先运行，无论 gh 是否可用：

git rev-parse --show-toplevel 2>/dev/null || echo "ERROR: not a git repo"
git branch --show-current
git status --short
git diff --stat
git diff --cached --stat
git log --oneline -10
git remote -v
git config --show-origin --show-scope --get user.name 2>/dev/null || echo "unset"
git config --show-origin --show-scope --get user.email 2>/dev/null || echo "unset"
git config commit.gpgsign 2>/dev/null || echo "unset"

审计预检——社区文件检查

检查每个文件在本地是否存在/不存在。存在/不存在是已验证的事实；内容质量不是：

test -f README.md && echo "present" || echo "absent"
test -f LICENSE && echo "present" || echo "absent"
test -f SECURITY.md && echo "present" || echo "absent"
test -f CODE_OF_CONDUCT.md && echo "present" || echo "absent"
test -f CONTRIBUTING.md || test -f .github/CONTRIBUTING.md && echo "present" || echo "absent"
test -f .github/PULL_REQUEST_TEMPLATE.md && echo "present" || echo "absent"
test -d .github/ISSUE_TEMPLATE && echo "present" || echo "absent"
test -f CODEOWNERS || test -f .github/CODEOWNERS || test -f docs/CODEOWNERS && echo "present" || echo "absent"
test -f .github/dependabot.yml || test -f .github/dependabot.yaml && echo "present" || echo "absent"
test -d .github/workflows && echo "present" || echo "absent"

GitHub 状态——可用性门控

在运行任何 gh 命令之前：

1. 检查是否存在 GitHub 远程：git remote -v | grep github.com
2. 检查 gh 是否可用：gh auth status 2>/dev/null

如果未检测到 GitHub 远程：将所有 GitHub 状态字段报告为 unavailable -- non-GitHub remote。

如果 gh 不可用

…

[为翻译截断]