---
name: cc-switch-dev-workflow
description: Run the internal CC Switch multi-agent delivery workflow with fixed stack/model routing, 7 stages, and playbooks for scaffold, spec backfill, and gap closure.
type: workflow
domain: ai-agents
tags: [cc-switch, workflow, spec-driven, multi-agent, hono, nextjs, typescript]
---

# CC Switch Dev Workflow

用这套 skill 把内部 AI Agent 开发流程固定下来，不让 agent 在技术栈、模型路由、handoff 和阶段节奏上随机发挥。

## Use This When

- 你要用 `CC Switch` 编排多 agent 开发流程。
- 你要在 `新项目脚手架启动 / 老项目补 Spec 并重构 / Spec-Code Gap Closure` 三条主路径里选一条执行。
- 你要固定 `GPT-5.4 Pro xhigh`、`Claude Opus 4.6` 和 fallback 模型的职责边界。
- 你要把知识库、模板、handoff 契约和本机 `~/.cc-switch` 当前配置对齐。

## Do This First

1. 先判断当前任务对应哪条 playbook：
   - 新项目：`references/knowledge-base/playbooks/new-project-from-scaffold.md`
   - 老项目补 Spec：`references/knowledge-base/playbooks/existing-project-spec-backfill-and-refactor.md`
   - Spec/Code 收敛：`references/knowledge-base/playbooks/spec-code-alignment-gap-closure.md`
2. 再读取本机运行时对齐信息：
   - 先看 `references/local-cc-switch-runtime.md`
   - 需要实时确认时运行：

```bash
python3 scripts/inspect_cc_switch_runtime.py --format markdown
```

3. 如果用户明确要一键初始化目标 repo，并直接生成首轮 `CLAUDE.md / AGENTS.md / ANALYSIS.md / TODO.yaml / SPECS/`，优先用：

```bash
python3 scripts/init_workflow_repo.py \
  --target-dir /absolute/path/to/project \
  --playbook new-project-from-scaffold \
  --project-name "Project Name" \
  --goal "One-sentence goal"
```

4. 如果只需要轻量骨架和模板拷贝，再用：

```bash
python3 scripts/bootstrap_workflow_workspace.py \
  --target-dir /absolute/path/to/project \
  --playbook new-project-from-scaffold
```

5. 只把高密度产物传给下一阶段，禁止把整段原始聊天直接 handoff 给下一个 agent。

## Default Operating Rules

- 主控/计划/实现主链路默认走 `GPT-5.4 Pro xhigh`。
- 长文档消化、Spec 审读、第二视角复核默认走 `Claude Opus 4.6`。
- fallback 只允许 `GLM / Minimax / Kimi`，且只在主模型受限时使用。
- fallback 结束后必须压缩回标准 handoff，并 reset 上下文。
- 默认技术栈白名单固定为 `TypeScript + React`。
- 默认优先轨道是 `Hono + React SSR + TanStack Router + TanStack Query + Better Auth + shadcn/ui + Tailwind + Drizzle + PostgreSQL`。
- 有明确理由时可选 `Next.js 全栈`，但不能无依据摇摆。
- `Python / PHP` 禁止进入产品应用主链路，只允许工具脚本、迁移脚本或一次性数据处理。
- 实施与重构至少按 `1:1` 预算，复杂项目允许到 `1:2`。

## Stage Order

按下面顺序执行，不跳阶段：

1. `Stage 0 Setup`
2. `Stage 1 Research`
3. `Stage 2 Spec`
4. `Stage 3 Code`
5. `Stage 4 Alignment`
6. `Stage 5 Refinement`
7. `Stage 6 Acceptance`

需要细节时，按需读取：

- `references/knowledge-base/workflows/stage-0-setup.md`
- `references/knowledge-base/workflows/stage-1-research.md`
- `references/knowledge-base/workflows/stage-2-spec.md`
- `references/knowledge-base/workflows/stage-3-code.md`
- `references/knowledge-base/workflows/stage-4-alignment.md`
- `references/knowledge-base/workflows/stage-5-refinement.md`
- `references/knowledge-base/workflows/stage-6-acceptance.md`

不要一次性把整个 `references/knowledge-base/` 全量读入上下文。先选 playbook，再只读当前阶段需要的页面。

## Required Deliverables

在大多数项目里，至少会出现这些产物：

- `CLAUDE.md`
- `AGENTS.md`
- `ANALYSIS.md`
- `TODO.yaml`
- `SPECS/*.md`
- `.plans/*.md`
- handoff 文档
- acceptance checklist
- 需要偏离默认规则时的 ADR

模板都在 `references/knowledge-base/templates/`。

## Orchestration Rules

- 主控 agent 决定阶段目标、角色分工、进入/退出条件。
- 研究 agent 只收集事实，不直接改代码。
- 计划 agent 把事实压缩成 `ANALYSIS.md`、`TODO.yaml`、Spec 或 `.plans/*.md`。
- 实现 agent 只读已批准的高密度产物。
- 审查 agent 用第二视角做 Spec 审查、一致性检查和质量复核。
- 同一文件的最终定稿不能多 agent 并行改。

需要完整规则时读取：

- `references/knowledge-base/orchestration/cc-switch-operating-model.md`
- `references/knowledge-base/orchestration/agent-handoff-contract.md`

## Stable Knowledge Vs Runtime Context

- 稳定知识进入这个 skill 的 `references/knowledge-base/`。
- 会议纪要、一次性报错、探索日志、临时判断只作为阶段输入，不直接升级为长期规则。
- 当前机器上的 provider、模型、MCP、skill repo 和内部 host 归类为运行时上下文，需要优先对照本机 `~/.cc-switch` 实况。

## Secret Handling

- 这个 skill 面向私有内网仓库，可以记录内部 host、私有 repo 地址和私有运行约束。
- 默认仍然优先读取本机 `~/.cc-switch` 或环境变量，不主动把原始 API key 固化到文档。
- 只有用户明确要求把某个内部 token/credential 放进私有仓库时，才这样做，并在提交说明里写清作用域。

## Reference Map

- 总入口：`references/knowledge-base/README.md`
- Playbooks：`references/knowledge-base/playbooks/`
- 7 阶段：`references/knowledge-base/workflows/`
- 技术栈与模型路由：`references/knowledge-base/platform/`
- 多 agent 编排：`references/knowledge-base/orchestration/`
- 模板：`references/knowledge-base/templates/`
- 当前机器对齐快照：`references/local-cc-switch-runtime.md`

## Anti-Patterns

- 不要直接让 agent “随便选一个框架先写起来”。
- 不要把 `Python`、`PHP` 或无类型 `JavaScript-only` 引进产品主链路。
- 不要让 fallback 模型变成默认主链路。
- 不要跳过 Spec 审核直接进入 Code。
- 不要把 refactor 当作最后可有可无的装饰步骤。