Engineering Playbook

面向人类与 AI Coding Agent 的可追溯、可验证工程治理系统。

默认路径是 T1 合并门禁：重要改动有 Change Record，生产代码变化有测试或有效豁免，CI 可以拦住不合规 PR。更高追溯（RFC/ADR/矩阵）只在风险升级或显式选择 T2/T3 时启用。

3 步用上（推荐）

从本仓库源码安装（发布 tag 后也可用同一方式固定版本）：

python3 -m pip install "git+https://github.com/biuworks/engineering-playbook.git@v0.2.0"
cd /path/to/your-repo
playbook init                  # 默认 T1 + zh-CN
playbook doctor

开发者在本仓库内联安装：

python3 -m pip install -e '.[test]'
cd /path/to/your-repo
playbook init
playbook doctor

然后在目标仓库复制 Skill 与 Agent 入口（默认也是 T1，不会铺满空文档模板）：

python3 /path/to/engineering-playbook/scripts/adopt-playbook.py .

日常最小闭环：

playbook start --title "Fix checkout bug" --type fix
# ... 改代码并补测试 ...
playbook check --base origin/main --mode work
playbook finish CHG-0001 --base HEAD

把 Playbook Compliance 配成 Required Status Check（见 Required Status Check）。第一周建议只开：活动 Change + 生产改动测试/豁免。

进阶：T2/T3

需要架构决策、需求追溯、安全/隐私审查时再升级：

playbook init --level T2 --language zh-CN
python3 scripts/adopt-playbook.py /path/to/target-repo --level T2 --language zh-CN

等级含义见下方表格；完整流程见 Adoption Guide。

Current Standards

• Documentation Index
• Project Roadmap
• Traceable Engineering Standard
• Adoption Guide
• Skill Adoption
• Playbook CLI Error Codes
• Required Status Check Setup
• Tool-Neutral Agent Hooks
• Ecosystem Integrations and Organization Policy

Templates

• Documentation Index Template
• Project Charter Template
• Glossary Template
• Roadmap Template
• Project Conventions Template
• Discussion Note Template
• RFC Template
• ADR Template
• Requirement Template
• Traceability Matrix Template
• Incident Template
• Release Template
• Security Review Template
• Privacy Review Template
• Issue Template
• Pull Request Template

Agent Skill Pack

• Traceable Engineering Skill
• OpenAI Skill Metadata

GitHub Templates

• Traceable Task Issue Template
• Pull Request Template

Validation

Run repository checks after changing templates, links, or skills:

python3 scripts/check-playbook.py

安装开发环境并运行机器合规检查：

python3 -m pip install -e '.[test]'
playbook start --title "Add OAuth login" --type feature --level T2
playbook check --base origin/main --mode work

共享策略位于 .playbook/policy.yaml；Policy 与 Change Record 合同分别位于 schemas/policy.schema.json 和 schemas/change.schema.json。

CI 使用 --mode merge，要求活动 Change 达到 verified。仓库管理员还需按 Required Status Check 配置指南 将 Playbook Compliance 设为必需检查。

Agent 执行入口：

playbook context --base HEAD --format json
playbook fix --base origin/main --title "Add example" --type feature
playbook hook write --path src/example.py
playbook hook write --path src/example.py --severity warn
playbook hook stop --base HEAD
playbook finish CHG-0001 --base HEAD
playbook doctor

生态和并行 Change：

playbook start --title "Change orders" --type feature --scope 'src/orders/**' --scope 'tests/orders/**'
playbook link CHG-0001 --adapter openspec --path openspec/changes/change-orders

Adopt the playbook and skill pack in another repository:

python3 scripts/adopt-playbook.py /path/to/target-repo
python3 scripts/adopt-playbook.py /path/to/target-repo --level T2 --language zh-CN

旧版兼容别名（不提供额外能力）：

python3 scripts/adopt-project.py /path/to/target-repo --level T3 --language zh-CN

Options

Supported documentation languages: en-US, zh-CN.

默认 --language zh-CN。需要英文优先文档时显式传入 --language en-US。所选语言写入目标仓库的 AGENTS.md 与 docs/project/conventions.md（T2+）。

The adoption scripts copy AGENTS.md and skills/traceable-engineering/ into the target repository. Agents should use skills/traceable-engineering/SKILL.md as the shared workflow entrypoint. AGENTS.md remains the tool-neutral fallback entrypoint for tools that do not auto-discover repository skills.

Recommended Project Adoption

对于大多数仓库，先用 T1（见上方「3 步用上」）。T1 只复制：

AGENTS.md
skills/
  traceable-engineering/
    SKILL.md
.github/
  ISSUE_TEMPLATE/
  PULL_REQUEST_TEMPLATE.md
  workflows/playbook-compliance.yml

For a T2/T3 project, also copy the docs tree:

docs/
  00-index.md
  project/
    charter.md
    glossary.md
    roadmap.md
    conventions.md
  notes/
  rfcs/
  adrs/
  requirements/
    traceability.md
  incidents/
  releases/

For T3 projects, also create:

docs/
  security/
  privacy/

Then decide the traceability level:

Level	Use Case	Required Artifacts
T0	Temporary scripts or experiments	Clear commit messages
T1	Normal projects（默认）	Change、verification、tests/exemption
T2	Important projects	Notes, RFC, ADR, requirements, traceability matrix
T3	Open source, commercial, security-sensitive, or long-term projects	T2 plus security, privacy, release notes, incidents/postmortems

Upgrade the level when a change involves data migration, authentication, authorization, privacy, security, public APIs, protocols, infrastructure, deployment, release, rollback, or incident response.

Adoption Manifest

复制映射及适用等级的机器可读单一事实源是 adoption-manifest.json。scripts/adopt-playbook.py 直接读取该文件；修改 adoption 内容时不要在 README 复制映射规则。