Su Init

---
name: su-init
description: 初始化 CCB 项目骨架，检查依赖，自动扫描项目事实，生成项目级 CLAUDE.md、AGENTS.md、.claude/settings.json 与 docs/.ccb 目录。
metadata:
  short-description: SU 项目初始化
---

# SU 项目初始化

## 触发条件
- 用户要在新项目启用 SU/CCB 协作流程。
- 当前项目缺少 `CLAUDE.md`、`AGENTS.md`、`.claude/settings.json` 或 `docs/.ccb/`。
- 用户要求重跑初始化以同步模板更新。

## 输入
- 项目根目录。
- 现有 `CLAUDE.md`、`AGENTS.md`、`.claude/settings.json` 是否存在。
- 项目是否为空项目（无代码文件）。

## 依赖检查

初始化时自动检查三层依赖：

### 检查项

| 依赖 | 检查方式 | 等级 |
|------|---------|------|
| ccb-transport — Bash 命令：`ask`、`pend`；Skill：`/mounted`、`/cping` | 命令/skill 可用性 | 必需 |
| SuperClaude | `~/.claude/commands/sc/` 存在 + 核心命令（design.md, brainstorm.md, build.md, test.md, load.md） | 可选增强 |
| Superpowers | `~/.codex/superpowers/skills/` 存在 + 核心 skill（brainstorming, writing-plans, executing-plans, verification-before-completion, systematic-debugging） | 可选增强 |

### 检查结果等级
- **Installed**：完整安装，所有核心组件存在
- **Partial**：部分安装，缺少某些核心组件
- **Missing**：未安装

### 总评行
- **可完整运行**：必需依赖 + 全部增强层就位
- **可降级运行**：必需依赖就位，增强层部分或缺失
- **需先补依赖**：缺少必需依赖（ccb-transport）

## 项目事实自动扫描

### 扫描策略

| 项目状态 | 扫描行为 | project.yaml |
|---------|---------|-------------|
| 非空项目（有代码文件） | best-effort 自动扫描 | 有发现则生成，无发现不创建 |
| 空项目（无代码文件） | 跳过扫描 | 不创建，延迟到首次 `/ccb:su-plan` |

### 自动检测信号

| 文件/目录 | 可推断的信息 | confidence |
|----------|------------|-----------|
| `package.json` | Node/JS/TS 技术栈、scripts | high |
| `pyproject.toml` / `requirements.txt` | Python 技术栈 | high |
| `go.mod` | Go 模块 | high |
| `Cargo.toml` | Rust | high |
| `tsconfig.json` | TypeScript | high |
| `Dockerfile` / `docker-compose.yml` | 容器/运行时 | medium |
| `.github/workflows/` | CI 验证命令 | medium |
| `Makefile` / `justfile` | 开发者命令 | medium |
| 顶层 `src/` / `app/` / `packages/` | 关键目录 | medium |

### 扫描产出

若检测到有意义的信息，生成 `docs/.ccb/index/project.yaml`：
- 每个字段含 `value`、`confidence`、`source`
- 手动修正的字段在重新扫描时受保护
- **永远不生成 `[待填写]` 占位符**

### 重扫保护规则

| 已有字段来源 | 新扫描结果 | 行为 |
|------------|----------|------|
| 手动修正 | auto 检测 | 保留手动值 |
| auto 检测 | auto（更高 confidence） | 替换 |
| auto 检测 | auto（同等/更低 confidence） | 保留已有 |
| 不存在 | auto 检测 | 新增 |

## 执行流程

1. 执行依赖检查，输出检查结果。
2. 判断项目是否为空项目。
3. 检查项目是否已有 `CLAUDE.md`、`AGENTS.md`、`.claude/settings.json` 与 `docs/.ccb/`。
4. 读取模板：`claude-md-template.md`、`codex-md-template.md`、`project-scaffold.md`。
5. 生成或更新 `CLAUDE.md`（CCB:CLAUDE-ROLE 命名块，含路由指引，不含可变项目事实）。
6. 生成或更新 `AGENTS.md`（CCB:CODEX-ROLE 命名块，含路由指引，不含可变项目事实）。
7. 生成或更新 `.claude/settings.json`，写入 hooks 模板。
8. 创建 `docs/.ccb/` 骨架目录（templates/、state/、specs/active/、specs/archive/、index/、decisions/）。
9. 将 ask 模板、回执模板、协商模板、归档模板复制到项目模板目录。
10. **非空项目**：自动扫描项目事实，有发现则写入 `docs/.ccb/index/project.yaml`。
11. **空项目**：跳过扫描，提示首次 `/ccb:su-plan` 时会自动补充。
12. 输出初始化结果摘要。

## SuperClaude 集成

### 条件触发
- 需要 SuperClaude 会话加载能力时：`/sc:load`

## 输出格式
- 依赖检查结果 + 总评行。
- 项目扫描结果（非空项目时）。
- 初始化结果摘要。
- 新建或更新的路径列表。
- 后续使用指引。

## 停止条件
- 依赖检查已完成。
- 关键模板已写入项目（角色+规则+路由，不含可变事实）。
- 所有命名块插入成功。
- 非空项目的 project.yaml 已生成（或无可检测信息）。
- 用户已获得后续使用入口说明（`/ccb:su-plan` 开始规划）。

## 升级条件（回抛给用户）
- 现有文件结构冲突，无法安全定位插入点。
- `.claude/settings.json` 已有复杂 hooks，无法无损合并。
- 项目根目录不明确，或用户未确认初始化目标路径。
- 缺少必需依赖（ccb-transport），需先补依赖。