hao/skills
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动

Add cc-switch-dev-workflow skill

浏览代码
这个提交包含在：
X
2026-03-26 00:27:17 -07:00
父节点 fc8ad7c145
当前提交 dcb2a10ad8
共修改 46 个文件，包含 3393 行新增和 0 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

18
README.md
查看文件

@@ -14,6 +14,7 @@
| Skill | 说明 |
| --- | --- |
| `captcha-third-party-services` | 统一封装 2Captcha / YesCaptcha / Anti-Captcha 的官方 API 工作流。 |
| `cc-switch-dev-workflow` | 内部 CC Switch 多 agent 软件开发工作流，固化 playbook、7 阶段、模型路由、技术栈白名单和本机配置对齐。 |
| `cliproxy-traffic-proxy` | CLIProxy 流量代理相关技能。 |
| `codex-task-server-sync` | 把本地 Codex 工作区迁移到服务器并通过 Gitea 持续双向同步。 |
| `cn86-sms-keyword-verification` | 86 手机号 + 关键词验证码流程，基于 LubanSMS API 完成取号、取码、提码、释放号码。 |
@@ -40,6 +41,23 @@ python3 cn86-sms-keyword-verification/scripts/lubansms_keyword_cli.py balance
python3 cn86-sms-keyword-verification/scripts/lubansms_keyword_cli.py demo --keyword 千问 --timeout 300 --interval 5
```
## 新增技能：`cc-switch-dev-workflow`
适用场景：
- 用 `CC Switch` 管理 `GPT-5.4 Pro xhigh`、`Claude Opus 4.6` 和 fallback 模型的内部开发流程
- 从 `新项目脚手架 / 老项目补 Spec / Spec-Code Gap Closure` 三条主路径里选一条执行
- 需要把 `CLAUDE.md`、`ANALYSIS.md`、`TODO.yaml`、`SPECS/`、handoff、acceptance checklist 一次性种到目标项目
运行示例：
```bash
python3 cc-switch-dev-workflow/scripts/inspect_cc_switch_runtime.py --format markdown
python3 cc-switch-dev-workflow/scripts/bootstrap_workflow_workspace.py \
--target-dir /absolute/path/to/project \
--playbook new-project-from-scaffold
```
## 维护建议
- 新增 skill 时，保持目录名、`name` 字段和用途一致

137
cc-switch-dev-workflow/SKILL.md 普通文件
查看文件

@@ -0,0 +1,137 @@
---
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. 如果用户明确要初始化项目目录，用：
```bash
python3 scripts/bootstrap_workflow_workspace.py \
--target-dir /absolute/path/to/project \
--playbook new-project-from-scaffold
```
4. 只把高密度产物传给下一阶段，禁止把整段原始聊天直接 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`
- `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 当作最后可有可无的装饰步骤。

4
cc-switch-dev-workflow/agents/openai.yaml 普通文件
查看文件

@@ -0,0 +1,4 @@
interface:
display_name: "CC Switch Dev Workflow"
short_description: "Run the internal spec-driven multi-agent delivery workflow"
default_prompt: "Use $cc-switch-dev-workflow to choose the right playbook, align against my local CC Switch config, and run the 7-stage software delivery workflow."

103
cc-switch-dev-workflow/references/knowledge-base/README.md 普通文件
查看文件

@@ -0,0 +1,103 @@
# AI Agent 开发知识库 v1
## Purpose
为内部团队提供一套可执行的 `Handbook + SOP`。本知识库把当前目录的 5 个源资产压缩成统一入口，覆盖 `CC Switch` 多 agent 编排、Spec 驱动开发、模型路由、阶段流程、模板和 ADR。
## When to Use
- 新项目要从标准脚手架和标准流程启动时
- 维护项目要补齐 `SPECS/`、补做 Alignment、补做质量收敛时
- 团队需要统一 `GPT-5.4 Pro xhigh`、`Claude Opus 4.6` 和 `CC Switch` 的分工方式时
- 新成员需要在不回看原始会议纪要的前提下上手执行时
## Inputs
- 根目录下的 3 份会议整理文档
- `workflow.zip`
- `skills.zip`
- 当前项目的会议纪要、参考仓库、业务需求、现有代码库
## Outputs
- 一套可导航的知识库结构
- 7 阶段执行流程
- 3 条主 playbook
- 可复用模板
- 带日期的策略 ADR
## Primary Agent/Model
`CC Switch` 主控线程，默认主推理模型为 `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`，用于长文档消化、Spec 审读、第二视角复核
## Required Skills
- `ralphy-initializing`
- `spec-tasking`
- `spec-reviewing`
- `spec-gap-tasking`
- `tdd-planning`
- `tdd-implementing`
- `code-simplifying`
- `code-refactoring`
- `architecture-audit`
## Steps
1. 从 [`sources/README.md`](./sources/README.md) 确认规则来源和冲突取舍。
2. 从 [`playbooks/`](./playbooks/) 选择最贴近当前项目的执行路径。
3. 按 [`workflows/README.md`](./workflows/README.md) 所列阶段运行，每阶段只保留高密度产物进入下一阶段。
4. 统一使用 [`templates/README.md`](./templates/README.md) 中的模板生成 `CLAUDE.md`、`ANALYSIS.md`、`TODO.yaml`、Spec 和 handoff 文档。
5. 发生技术栈偏离、模型切换、来源冲突时，先写入 [`decisions/README.md`](./decisions/README.md) 中的 ADR，再继续执行。
## Exit Criteria
- 新同事能在不回看原始源文档的前提下，完成至少一轮 `Setup -> Research/Spec -> Code/Alignment` 的准备
- 任何核心规则都能追溯到一个明确源资产
- 多 agent 分工、handoff 契约和 reset 规则清晰且无冲突
## Failure Recovery
- 如果发现规则冲突，暂停扩写，回到 [`sources/README.md`](./sources/README.md) 与 ADR 检查来源优先级
- 如果阶段输入过大或输出发散，按 [`foundations/context-engineering.md`](./foundations/context-engineering.md) 收缩上下文并重置线程
- 如果交付物不能直接执行，优先回看对应 playbook 与模板，而不是回退到原始会议长文
## Related Templates
- [`templates/claude-md-template.md`](./templates/claude-md-template.md)
- [`templates/analysis-template.md`](./templates/analysis-template.md)
- [`templates/todo-yaml-template.md`](./templates/todo-yaml-template.md)
- [`templates/agent-handoff-template.md`](./templates/agent-handoff-template.md)
- [`templates/acceptance-checklist-template.md`](./templates/acceptance-checklist-template.md)
## 目录总览
| 目录 | 作用 |
|---|---|
| `sources/` | 源资产摘要、规则提炼、冲突记录、追溯矩阵 |
| `foundations/` | 长期稳定的原则层知识 |
| `platform/` | 技术栈白名单、框架决策、模型策略 |
| `orchestration/` | `CC Switch` 多 agent 编排与 handoff 契约 |
| `workflows/` | 7 阶段执行版流程 |
| `playbooks/` | 面向具体项目情境的执行路径 |
| `templates/` | 标准输入输出模板 |
| `decisions/` | 可变策略 ADR 和冲突决策 |
## 7 阶段总览
| 阶段 | 目标 | 核心产物 | 默认主模型 | 默认辅模型 |
|---|---|---|---|---|
| 0 Setup | 项目初始化与规则对齐 | `.meetings/`, `.ralphy/config.yaml`, `CLAUDE.md` | `GPT-5.4 Pro xhigh` | `Claude Opus 4.6` |
| 1 Research | 形成调研结论 | `ANALYSIS.md`, `TODO.yaml`, `.research/*.md` | `GPT-5.4 Pro xhigh` | `Claude Opus 4.6` |
| 2 Spec | 形成可实施规范 | `SPECS/*.md` | `GPT-5.4 Pro xhigh` | `Claude Opus 4.6` |
| 3 Code | 按 Spec 实施代码 | `.plans/*.md`, 代码与测试 | `GPT-5.4 Pro xhigh` | `Claude Opus 4.6` |
| 4 Alignment | 补齐 Spec 与代码缺口 | `ANALYSIS.md`, `TODO.yaml`, 补齐实现 | `GPT-5.4 Pro xhigh` | `Claude Opus 4.6` |
| 5 Refinement | 做全局质量收敛 | 简化、重构、模块化/结构重组计划 | `Claude Opus 4.6` | `GPT-5.4 Pro xhigh` |
| 6 Acceptance | 人工验收与交付确认 | 验收报告、发布决定 | 人工主导 | `Claude Opus 4.6` |
## Playbook 选择器
| 你当前的情况 | 直接打开 |
|---|---|
| 新项目，要从脚手架和约束开始 | [`playbooks/new-project-from-scaffold.md`](./playbooks/new-project-from-scaffold.md) |
| 老项目没有完整规范，要补 Spec 并顺带重构 | [`playbooks/existing-project-spec-backfill-and-refactor.md`](./playbooks/existing-project-spec-backfill-and-refactor.md) |
| 已有 Spec，但代码和 Spec 不一致 | [`playbooks/spec-code-alignment-gap-closure.md`](./playbooks/spec-code-alignment-gap-closure.md) |
## Source Precedence
1. 同一主题冲突时，优先更晚、更新、更可执行的来源。
2. `workflow.zip` 提供阶段骨架，会议整理文档提供原则与经验修正。
3. `skills.zip` 提供技能级执行约束，优先用于定义任务颗粒度和质量检查点。
4. 任何取舍都要落到 [`decisions/ADR-2026-03-21-source-precedence-and-conflict-resolution.md`](./decisions/ADR-2026-03-21-source-precedence-and-conflict-resolution.md)。

63
cc-switch-dev-workflow/references/knowledge-base/decisions/ADR-2026-03-21-model-routing-and-fallbacks.md 普通文件
查看文件

@@ -0,0 +1,63 @@
# ADR-2026-03-21 Model Routing And Fallbacks
## Purpose
记录当前默认模型路由和 fallback 边界。
## When to Use
- 需要决定主辅模型时
- 需要启用 fallback 时
## Inputs
- 当前阶段
- 任务类型
- 文档长度
## Outputs
- 模型路由决策
## Primary Agent/Model
项目 owner + `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- 无
## Steps
1. 先判断任务类型。
2. 再确定主辅模型。
3. 若需要 fallback，先写边界，再压缩回主线程。
## Exit Criteria
- 主辅模型与 fallback 路线都明确
## Failure Recovery
- 若 fallback 成为默认路线，说明本 ADR 被破坏，应重新审查
## Related Templates
- [`../templates/agent-handoff-template.md`](../templates/agent-handoff-template.md)
## Status
Accepted
## Context
- 团队需要在长文处理、复杂推演、Spec 审查和实施之间切换最合适模型。
- 不能把临时 fallback 升级为默认主路线。
## Decision
- 默认主模型：`GPT-5.4 Pro xhigh`
- 默认辅模型：`Claude Opus 4.6`
- `GPT-5.4 Pro xhigh` 负责研究规划、任务拆分、结构化文档、实施与重构主链路。
- `Claude Opus 4.6` 负责长文消化、Spec 审读、第二视角复核。
- `GLM / Minimax / Kimi` 仅作受控 fallback，不作为默认项目主链路。
- 任何 fallback 输出都必须压缩为标准 handoff 后才能回到主线程。
## Consequences
- 模型切换更可预测
- handoff 质量变成模型协作的硬约束
- fallback 使用频率可被审计，而不是隐形扩散
## Revisit When
- 主模型能力或成本结构显著变化
- 团队引入新的主编排系统

62
cc-switch-dev-workflow/references/knowledge-base/decisions/ADR-2026-03-21-source-precedence-and-conflict-resolution.md 普通文件
查看文件

@@ -0,0 +1,62 @@
# ADR-2026-03-21 Source Precedence And Conflict Resolution
## Purpose
记录 5 个源资产出现冲突时的裁决规则。
## When to Use
- 两个来源对同一主题给出不同说法时
- 要决定正式知识库采用哪一版规则时
## Inputs
- 冲突条目
- 相关源资产
- 受影响页面
## Outputs
- 冲突取舍结论
## Primary Agent/Model
项目 owner + `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- 无
## Steps
1. 列出冲突项。
2. 判断谁更晚、更新、具体和可执行。
3. 用结论更新正式页面。
## Exit Criteria
- 冲突已收敛到单一入口
## Failure Recovery
- 若正式页面仍保留冲突规则，说明 ADR 未真正落地
## Related Templates
- [`../templates/analysis-template.md`](../templates/analysis-template.md)
## Status
Accepted
## Context
- `workflow.zip` 提供阶段骨架。
- 两份 3 月会议整理文档提供原则和经验修正。
- `skills.zip` 提供更细粒度的执行约束。
## Decision
- 阶段骨架以 `workflow.zip` 为准。
- 长期原则、可靠性和设计哲学，以 2026 年 3 月两份会议整理文档为准。
- 任务结构、检查点和审查门禁，以 `skills.zip` 中对应 skill 的真实行为为准。
- 同一主题若仍冲突，优先更晚、更具体、更可执行的来源。
- 一条正式规则在知识库中只保留一个规范入口。
## Consequences
- 知识库不会成为来源冲突的集合体
- 后续更新时可以明确知道该改哪个层级
## Revisit When
- 新一轮会议整理文档替代现有原则层
- 新技能包改变了关键执行结构

65
cc-switch-dev-workflow/references/knowledge-base/decisions/ADR-2026-03-21-stack-whitelist-and-exception-process.md 普通文件
查看文件

@@ -0,0 +1,65 @@
# ADR-2026-03-21 Stack Whitelist And Exception Process
## Purpose
记录 v1 默认技术栈白名单，以及何时允许偏离。
## When to Use
- 新项目选型
- 老项目迁移
- 团队想引入白名单外技术时
## Inputs
- 项目目标
- 性能与兼容要求
- 现有遗留约束
## Outputs
- 选型决策
- 例外审批结果
## Primary Agent/Model
项目 owner + `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- 无
## Steps
1. 先看是否能落到白名单轨道。
2. 如不能，写出偏离理由和范围。
3. 审批通过后更新模板与执行说明。
## Exit Criteria
- 项目主链路已落到一个明确轨道
## Failure Recovery
- 若白名单外技术已被引入但没有审批，视为待回退问题
## Related Templates
- [`../templates/claude-md-template.md`](../templates/claude-md-template.md)
## Status
Accepted
## Context
- 团队需要避免 agent 在语言、框架、路由、鉴权和 ORM 上随机选型。
- 同时要保留少量例外接口，处理遗留系统和特殊约束。
## Decision
- 默认语言：`TypeScript`
- 默认 UI：`React`
- 默认优先轨道：`Hono + React SSR/TanStack`
- 允许替代轨道：`Next.js 全栈`
- 默认基础组件、样式、鉴权、数据访问和 ORM：`shadcn/ui`, `Tailwind`, `Better Auth`, `TanStack Query`, `Drizzle`
- 禁止 `Python`、`PHP` 作为应用主链路默认语言
- 例外必须由项目 owner 与技术负责人批准，并写 ADR、更新 `CLAUDE.md`、更新相关 playbook 和模板
## Consequences
- agent 在主链路上的自由度下降，但一致性和生成质量上升
- 例外变成显式治理动作，而不是隐性扩散
## Revisit When
- 团队默认栈发生正式变更
- 某个白名单组件长期无法满足主流项目需求

46
cc-switch-dev-workflow/references/knowledge-base/decisions/README.md 普通文件
查看文件

@@ -0,0 +1,46 @@
# Decisions Index
## Purpose
集中管理可变化策略的 ADR，避免把模型偏好、来源优先级和例外流程写死在永久规则里。
## When to Use
- 需要改模型默认路线时
- 需要处理来源冲突时
- 需要批准技术栈例外时
## Inputs
- 当前争议点
- 受影响规则
- 证据与来源
## Outputs
- 带日期的 ADR
## Primary Agent/Model
项目 owner + `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- 无强制 skill
## Steps
1. 先描述问题和受影响范围。
2. 再写决策与后果。
3. 更新受影响的知识库页面。
## Exit Criteria
- 争议已收敛
- 所有受影响页面已同步
## Failure Recovery
- 如果规则变了但没写 ADR，视为无效变更
## Related Templates
- [`../templates/agent-handoff-template.md`](../templates/agent-handoff-template.md)
## ADR List
- [`ADR-2026-03-21-model-routing-and-fallbacks.md`](./ADR-2026-03-21-model-routing-and-fallbacks.md)
- [`ADR-2026-03-21-source-precedence-and-conflict-resolution.md`](./ADR-2026-03-21-source-precedence-and-conflict-resolution.md)
- [`ADR-2026-03-21-stack-whitelist-and-exception-process.md`](./ADR-2026-03-21-stack-whitelist-and-exception-process.md)

60
cc-switch-dev-workflow/references/knowledge-base/foundations/context-engineering.md 普通文件
查看文件

@@ -0,0 +1,60 @@
# Foundation: Context Engineering
## Purpose
定义稳定知识、运行时上下文和 handoff 摘要之间的边界，避免把会议纪要、长文档和临时报错直接堆给所有 agent。
## When to Use
- 设计 `CC Switch` 多 agent 协作方式时
- 某个线程上下文越来越大、输出开始发散时
- 需要决定什么该进入知识库、什么只留在本轮执行时
## Inputs
- 当前阶段的源材料
- 上一阶段的高密度产物
- 当前任务的范围边界
## Outputs
- 边界清晰的 handoff 摘要
- 可复用稳定知识
- 可丢弃的运行时噪音
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- 无强制 skill；遵循本知识库的 handoff 和阶段模板
## Steps
1. 区分“长期规则”和“单次执行信息”。
2. 只把可复用、可稳定引用的内容写入知识库。
3. 每个阶段结束后，把长上下文压缩成 `ANALYSIS.md`、`SPECS/*.md`、`.plans/*.md` 或 handoff 摘要。
4. 进入下一阶段前，优先开新线程，让新线程只读取高密度产物，而不是带着旧对话继续滚动。
## Exit Criteria
- 下一阶段不依赖上一阶段的完整长对话
- handoff 内容短、准、可执行
- 知识库只保留长期有效的规则
## Failure Recovery
- 如果模型开始引用过时讨论、已废弃方案或混乱术语，立即 reset 线程并只提供高密度产物
- 如果手头信息无法压缩成一句目标、一个范围、一个来源清单，说明当前上下文还没整理好，先回到计划阶段
## Related Templates
- [`../templates/analysis-template.md`](../templates/analysis-template.md)
- [`../templates/agent-handoff-template.md`](../templates/agent-handoff-template.md)
## Stable Knowledge
- 设计哲学、命名规则、阶段流程、技术栈白名单、技能映射、模板、ADR
## Runtime Context
- 当前会议摘录
- 单次探索结果
- 临时报错和实验结论
- 某一轮对比参考仓库的细节
## Handoff Rule
- 任何 handoff 必须能回答：要做什么、不能做什么、以什么为准、交付什么、怎么验收。
- handoff 不是全文转发，更不是把整个聊天记录交给下一个 agent。

60
cc-switch-dev-workflow/references/knowledge-base/foundations/human-agent-boundaries.md 普通文件
查看文件

@@ -0,0 +1,60 @@
# Foundation: Human And Agent Boundaries
## Purpose
定义人在这套流程中的职责，以及主 agent、研究 agent、计划 agent、实现 agent、审查 agent 的边界。
## When to Use
- 团队要分清“谁做判断、谁做执行”时
- 需要决定什么时候必须人工接管时
- 要设计多 agent 并行时
## Inputs
- 当前阶段目标
- 上一阶段高密度产物
- 当前范围边界
## Outputs
- 清晰的职责分配
- 并行和接管规则
## Primary Agent/Model
`CC Switch` 主控 + `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- 阶段相关 skill
## Steps
1. 先由主 agent 定义目标、边界、产物和分工。
2. 研究 agent 只收集和压缩事实，不直接替代最终决策。
3. 计划 agent 把事实整理成阶段化产物。
4. 实现 agent 只按照已批准的产物实施。
5. 审查 agent 负责第二视角发现遗漏、过度设计和一致性问题。
6. 人在 Spec 审核、例外审批、最终验收和高风险取舍时接管。
## Exit Criteria
- 每个角色都只拿到完成当前任务所需的上下文
- 人工判断只出现在必须的高杠杆位置
## Failure Recovery
- 如果实现 agent开始决定范围或技术路线，停止执行，回到计划 agent
- 如果研究 agent直接输出最终规范，必须交给计划 agent 或审查 agent 再压缩
## Related Templates
- [`../templates/agent-handoff-template.md`](../templates/agent-handoff-template.md)
- [`../templates/claude-md-template.md`](../templates/claude-md-template.md)
## Human Responsibilities
- 确认项目目标、边界和成功标准
- 审核 `SPECS/*.md`
- 批准技术栈例外和模型例外
- 进行最终验收和发布决定
## Agent Responsibilities
- 主 agent：阶段推进、任务编排、上下文收缩
- 研究 agent：扫描会议、参考仓库、技能与现状
- 计划 agent：产出 `ANALYSIS.md`、`TODO.yaml`、Spec、Plan
- 实现 agent：按计划实施代码和测试
- 审查 agent：做 Spec 审查、Gap 校验、重构建议和第二视角复核

68
cc-switch-dev-workflow/references/knowledge-base/foundations/refactoring-and-gap-closure.md 普通文件
查看文件

@@ -0,0 +1,68 @@
# Foundation: Refactoring And Gap Closure
## Purpose
把 `Code -> Alignment -> Refinement` 之间的关系讲清楚，防止团队把重构当成末尾装饰，把 Gap 当成补锅动作。
## When to Use
- 在实现阶段安排检查点时
- 在对齐阶段判断要补什么、不该补什么时
- 在准备验收前决定优化层级时
## Inputs
- `SPECS/*.md`
- 实现代码
- 测试结果
- 最近变更范围
## Outputs
- Gap 分类结果
- 重构批次
- 优化层级选择
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- `spec-gap-tasking`
- `code-simplifying`
- `code-refactoring`
- `architecture-audit`
## Steps
1. 先比对 Spec 和实现，分类缺口。
2. 缺口补齐后立刻做简化，避免把新增复杂度直接沉积下来。
3. 每完成一批类别，做一次增量重构。
4. 所有功能补齐后，再做全局简化、重构、必要时模块化与结构重组。
## Exit Criteria
- 已知缺口有计划、有实施、有验证
- 重构不再是“以后再说”，而是节奏化动作
- 优化层级与项目目标匹配
## Failure Recovery
- 若对齐阶段开始大规模重写无关代码，回到缺口范围定义
- 若重构修改了行为，回到最近稳定计划和测试
## Related Templates
- [`../templates/tdd-plan-template.md`](../templates/tdd-plan-template.md)
- [`../templates/todo-yaml-template.md`](../templates/todo-yaml-template.md)
## Gap Types
- `Missing`
- `Partial`
- `Divergent`
- `Untested`
- `Integration`
## Refactor Rhythm
- 实施后立即 `Simplify`
- 每 4 个类别做一次 `Refactor`
- 全库阶段做 `Architecture Audit`
## What Not To Do
- 不要在缺口分析前先写修复代码
- 不要把“代码更优雅”当成偏离 Spec 的理由
- 不要把 `Refinement` 用来掩盖前面没有对齐好的问题

66
cc-switch-dev-workflow/references/knowledge-base/foundations/reliability-and-convergence.md 普通文件
查看文件

@@ -0,0 +1,66 @@
# Foundation: Reliability And Convergence
## Purpose
解释为什么 AI 开发必须做层级控制、缺口对齐和多轮收敛，以及为什么“单步 80%”在多阶段流程里并不够用。
## When to Use
- 设计完整 AI 开发流水线时
- 讨论是否真的需要 Alignment 和 Refinement 时
- 评估某条流程是否会放大偏差时
## Inputs
- 需求、会议纪要、Spec、代码、测试
## Outputs
- 可靠性预算
- 阶段收敛设计
- 补齐与重构计划
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- `spec-gap-tasking`
- `code-simplifying`
- `code-refactoring`
- `architecture-audit`
## Steps
1. 明确当前流程有几层放大链路。
2. 计算每层误差会如何叠乘。
3. 用减少层级和提高单步质量两个手段收缩误差。
4. 对遗漏用 Gap 对齐，对过度添加用代码简化，对积累问题用重构和架构审计。
## Exit Criteria
- 每个阶段都有清晰的收敛动作
- 未经收敛的实现不会直接进入下一阶段
## Failure Recovery
- 如果实现大量偏离 Spec，回到 Alignment，不要在 Acceptance 临时补丁
- 如果简化和重构开始改变行为，停回到计划和测试
## Related Templates
- [`../templates/tdd-plan-template.md`](../templates/tdd-plan-template.md)
- [`../templates/acceptance-checklist-template.md`](../templates/acceptance-checklist-template.md)
## Reliability Math
- 典型坏流程：`0.8 x 0.8 x 0.8 x 0.8 = 0.4096`
- 典型改良流程：减少一层并把单步质量提高到 `0.95`
- 三层后：`0.95 x 0.95 x 0.95 = 0.857375`
## The Two Core Failure Modes
- `遗漏`：计划列了 10 项，AI 做了 8 项就说完成
- `过度添加`：Spec 没写的辅助层、抽象层、特性被模型自动加进去
## Convergence Toolkit
- `Alignment` 负责补齐遗漏和偏离
- `code-simplifying` 负责砍掉多余实现
- `code-refactoring` 负责批次级结构清理
- `architecture-audit` 负责全库级系统性健康检查
## Operating Rule
- 所有阶段都要留下高密度产物，便于下一阶段在更干净的上下文中执行。
- 任何“先实现，后面再说”的做法，都会把偏差拖到更昂贵的阶段。

78
cc-switch-dev-workflow/references/knowledge-base/foundations/spec-driven-development.md 普通文件
查看文件

@@ -0,0 +1,78 @@
# Foundation: Spec-Driven Development
## Purpose
定义本知识库的第一原则：先有设计哲学、再有调研、再有 Spec、最后才有代码。代码不是起点，Spec 才是起点。
## When to Use
- 新项目初始化时
- 老项目要补 `SPECS/` 时
- 团队对“为什么不直接让 AI 写代码”存在分歧时
## Inputs
- 会议清洗结果
- `.references/` 调研材料
- 业务需求或问题陈述
## Outputs
- `CLAUDE.md`
- `.research/*.md`
- `SPECS/*.md`
- 面向实施的 `TODO.yaml`
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- `ralphy-initializing`
- `spec-tasking`
- `spec-reviewing`
## Steps
1. 先清洗会议纪要，只留下当前项目相关决策。
2. 建立项目哲学和执行边界，写入 `CLAUDE.md`。
3. 基于参考仓库形成调研结论，而不是凭训练记忆直接拍板。
4. 把调研结论固化为 `SPECS/*.md`，让 Spec 成为实施前的单一真相源。
5. 只在 Spec 通过自动审查和人工审核后，才进入实施。
## Exit Criteria
- 项目有清晰的设计哲学和边界
- `SPECS/` 已覆盖系统契约，而不是散落在聊天和提示词里
- 代码任务都能指向明确的 Spec 条款和参考源
## Failure Recovery
- 若 Spec 过于抽象无法实施，补写接口契约和验收标准
- 若 Spec 过于具体锁死实现，删去实现细节，只保留系统契约
- 若文档重复定义同一概念，回到 SSOT 原则合并
## Related Templates
- [`../templates/claude-md-template.md`](../templates/claude-md-template.md)
- [`../templates/spec-template.md`](../templates/spec-template.md)
- [`../templates/analysis-template.md`](../templates/analysis-template.md)
## Non-Negotiables
- `Spec` 是代码前的单一真相源，不接受“边写边想”的主路径。
- `CLAUDE.md` 必须存在，并明确设计哲学、技能索引、边界和质量标准。
- 会议纪要不是执行输入，会议纪要的清洗结果才是。
- `SPECS/` 只描述系统契约，不混入教程、背景散文和变更历史。
## What Belongs In Spec
- 架构边界
- 命名约束
- 数据模型与接口契约
- 生命周期、处理流程和行为约束
- 禁止模式和决策理由
## What Does Not Belong In Spec
- 教程式用法说明
- 会议背景
- 提示词技巧
- 技能内部实现说明
- Git 变更历史
## Why This Matters For AI Agents
- 规范先行时，AI 的自由度发生在正确层级。
- 高层只定义目标和边界，低层才决定具体实现细节。
- 这样既防止模型随机发挥，也不把高层误判强行塞进代码。

52
cc-switch-dev-workflow/references/knowledge-base/orchestration/agent-handoff-contract.md 普通文件
查看文件

@@ -0,0 +1,52 @@
# Orchestration: Agent Handoff Contract
## Purpose
统一 agent 之间交接任务时的最小契约，防止交接变成全文转发。
## When to Use
- 一个 agent 的输出要交给另一个 agent 时
- 线程 reset 前
- 从 fallback 模型回到主线程时
## Inputs
- 上一角色的高密度产物
- 当前任务边界
- 当前任务验证方式
## Outputs
- 标准化 handoff 文档
- 可直接执行的单任务上下文
## Primary Agent/Model
发起 handoff 的当前 agent
## Secondary Agent/Model
接收 handoff 的下一角色 agent
## Required Skills
- [`../templates/agent-handoff-template.md`](../templates/agent-handoff-template.md)
## Steps
1. 用模板填好 `Goal / Scope / Non-Goals / Source of Truth / Constraints / Deliverable / Validation / Escalation`。
2. 只引用必要文件和必要章节。
3. 删除旧讨论、废弃方案和非本任务噪音。
4. 接收方在执行前复述边界，如边界不清立即打回。
## Exit Criteria
- 接收方无需阅读原线程即可开始执行
- 交接文档足够短，但不缺关键边界
## Failure Recovery
- 如果接收方提出“我还需要看完整聊天记录”，说明 handoff 失败，应重写
- 如果 handoff 把实现细节和设计决策混在一起，先拆成计划与实施两个 handoff
## Related Templates
- [`../templates/agent-handoff-template.md`](../templates/agent-handoff-template.md)
## Contract Rules
- `Goal` 只能有一个主目标
- `Scope` 必须点名路径、模块或文档
- `Non-Goals` 必须明确写出这轮不要碰什么
- `Source of Truth` 只能列真正约束当前任务的文件
- `Validation` 必须可执行，不能写成“看起来没问题”
- `Escalation` 必须说明什么情况停下来找人

77
cc-switch-dev-workflow/references/knowledge-base/orchestration/cc-switch-operating-model.md 普通文件
查看文件

@@ -0,0 +1,77 @@
# Orchestration: CC Switch Operating Model
## Purpose
定义 `CC Switch` 作为主编排层时的角色分工、并行规则、reset 规则和人工接管点。
## When to Use
- 配置新的多 agent 开发流程时
- 需要并行研究、计划、实现、审查时
- 需要明确谁负责推进主线程时
## Inputs
- 当前阶段目标
- 已批准的高密度产物
- 当前任务优先级
## Outputs
- 角色分工
- 并行策略
- reset 与接管规则
## Primary Agent/Model
主控 agent + `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
审查 agent + `Claude Opus 4.6`
## Required Skills
- 阶段相关 skill
- [`../templates/agent-handoff-template.md`](../templates/agent-handoff-template.md) 所定义的 handoff 结构
## Steps
1. 主控 agent 先定义阶段目标、输入输出、角色分工。
2. 研究 agent 并行收集事实，但不直接实施。
3. 计划 agent 把事实压缩成 `ANALYSIS.md`、Spec 或 `.plans/*.md`。
4. 实现 agent 只读取已批准产物做执行。
5. 审查 agent 对关键产物做第二视角复核。
6. 每个阶段结束后 reset，只把高密度产物传到下一阶段。
## Exit Criteria
- 当前阶段的 agent 角色明确
- handoff 边界明确
- 不存在把完整聊天记录直接转交给下个 agent 的行为
## Failure Recovery
- 如果多个 agent 同时修改范围和目标，回到主控 agent 重发边界
- 如果实现 agent开始补规则，暂停并回到计划 agent
## Related Templates
- [`../templates/agent-handoff-template.md`](../templates/agent-handoff-template.md)
- [`../templates/analysis-template.md`](../templates/analysis-template.md)
## Agent Roles
| 角色 | 主要职责 | 默认模型 |
|---|---|---|
| 主控 agent | 推进阶段、分配角色、控制边界、决定 reset | `GPT-5.4 Pro xhigh` |
| 研究 agent | 读会议、读参考、读技能、读现状 | `Claude Opus 4.6` 或 `GPT-5.4 Pro xhigh` |
| 计划 agent | 输出 `ANALYSIS.md`、`TODO.yaml`、Spec、Plan | `GPT-5.4 Pro xhigh` |
| 实现 agent | 按计划改代码、补测试、执行任务 | `GPT-5.4 Pro xhigh` |
| 审查 agent | 做 Spec 审查、一致性检查、第二视角复核 | `Claude Opus 4.6` |
## Parallel Rules
- 可并行：独立参考主题调研、独立 Spec 草稿、独立模块 Gap 分析
- 不可并行：同一文件的最终定稿、同一范围的多个实现 agent 同时执行
- 并行结果必须先回计划 agent 压缩，再交给实现 agent
## Reset Rules
- `Research -> Spec`
- `Spec 审查完成 -> Code`
- 每轮 `fallback` 结束后
- 任何上下文已掺入过多废弃方案时
## Human Takeover Points
- 选择产品范围和成功标准
- 审核 `SPECS/*.md`
- 批准栈例外、模型例外和 ADR
- 最终 Acceptance

71
cc-switch-dev-workflow/references/knowledge-base/platform/framework-decision-matrix.md 普通文件
查看文件

@@ -0,0 +1,71 @@
# Platform Policy: Framework Decision Matrix
## Purpose
在 `Next.js 全栈` 与 `Hono + React SSR/TanStack` 两条允许轨道之间做可重复的选择，而不是让 agent 自行随机决定。
## When to Use
- 新项目初始化时
- 老项目需要明确迁移目标时
- 团队对 “Next.js 还是 Hono” 出现争议时
## Inputs
- 产品是否以前端页面为主
- API 边界是否需要长期清晰分层
- SSR/边缘部署要求
- 团队是否需要复用独立服务层
## Outputs
- 选定轨道
- 该轨道下保留或替代的技术组合
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- `spec-reviewing`
## Steps
1. 先看项目交付形态和团队协作方式。
2. 按矩阵选一条轨道，不接受双主栈并行。
3. 把选择结果写入 `CLAUDE.md` 和 Setup 阶段产物。
## Exit Criteria
- 轨道已经确定
- 相关被替代组件已经说明清楚
## Failure Recovery
- 如果出现两条轨道同时存在的设计，先回到单轨道
- 如果团队只是因为“看起来都不错”而摇摆，优先选择更有边界感的 `Hono + React SSR/TanStack`
## Related Templates
- [`../templates/claude-md-template.md`](../templates/claude-md-template.md)
## Decision Matrix
| 条件 | 选 `Hono + React SSR/TanStack` | 选 `Next.js 全栈` |
|---|---|---|
| 需要清晰前后端边界 | 是 | 否 |
| 需要独立服务层或未来拆服务 | 是 | 否 |
| 团队希望统一 `TanStack Router + Query` 心智 | 是 | 否 |
| 更看重单仓单应用的快速落地 | 否 | 是 |
| 页面和服务逻辑高度耦合 | 否 | 是 |
| 需要高度可控的 API 中间层 | 是 | 否 |
## Track A: Hono + React SSR/TanStack
- 默认场景：内部工具、业务系统、需要清晰服务边界的产品
- 固定组合：`Hono` + `React` + `TanStack Router` + `TanStack Query` + `Better Auth` + `shadcn/ui` + `Tailwind` + `Drizzle`
- 优点：边界清晰，迁移和拆分成本低，适合多 agent 任务切片
- 代价：初始装配稍多，需要更强的工程纪律
## Track B: Next.js Full Stack
- 默认场景：页面驱动、内容驱动、单体交付优先的应用
- 固定组合：`Next.js` + `React` + `Better Auth` + `shadcn/ui` + `Tailwind` + `Drizzle`
- 替代说明：本轨道中 `Next.js App Router` 替代 `TanStack Router`；服务层由 `route handlers / server actions` 替代 `Hono`
- 优点：统一框架、上手快、页面与服务同仓同形态
- 代价：边界容易模糊，后续抽服务时需要更多治理
## Tie-Break Rule
- 如果没有明确理由支持 `Next.js 全栈`，默认回到 `Hono + React SSR/TanStack`

69
cc-switch-dev-workflow/references/knowledge-base/platform/model-routing-policy.md 普通文件
查看文件

@@ -0,0 +1,69 @@
# Platform Policy: Model Routing
## Purpose
为 `CC Switch` 提供默认模型路由，明确 `GPT-5.4 Pro xhigh`、`Claude Opus 4.6` 与 fallback 模型的职责分工。
## When to Use
- 为新项目配置多 agent 工作模式时
- 当前任务需要模型切换时
- 遇到模型长文处理、复杂推演或受限场景时
## Inputs
- 当前阶段
- 任务类型
- 文档长度
- 是否需要第二视角复核
## Outputs
- 默认主模型
- 默认辅模型
- 受控 fallback 路径
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- 无强制 skill；受 `CC Switch` 编排规则约束
## Steps
1. 按任务类型选择主模型。
2. 需要长文消化或二次复核时并行交给 `Claude Opus 4.6`。
3. 遇到主模型受限或厂商覆盖不足时，仅在合规范围内启用 fallback。
4. fallback 输出必须被压缩回标准 handoff，再回主线程继续。
## Exit Criteria
- 当前任务已有清晰主辅模型
- fallback 只在受限范围使用，且结果已标准化
## Failure Recovery
- 如果模型切换导致上下文漂移，回到 handoff 模板重新压缩
- 如果团队开始按个人偏好随意换模型，回到本页固定路由
## Related Templates
- [`../templates/agent-handoff-template.md`](../templates/agent-handoff-template.md)
- [`../templates/analysis-template.md`](../templates/analysis-template.md)
## Default Routing
| 任务类型 | 主模型 | 辅模型 |
|---|---|---|
| 研究规划、任务拆分、复杂推演 | `GPT-5.4 Pro xhigh` | `Claude Opus 4.6` |
| 长会议纪要、长参考文档消化 | `Claude Opus 4.6` | `GPT-5.4 Pro xhigh` |
| Spec 编写和结构化文档定稿 | `GPT-5.4 Pro xhigh` | `Claude Opus 4.6` |
| Spec 审查、第二视角复核 | `Claude Opus 4.6` | `GPT-5.4 Pro xhigh` |
| TDD 实施、Gap 收敛、重构执行 | `GPT-5.4 Pro xhigh` | `Claude Opus 4.6` |
## Fallback Policy
- 可用模型：`GLM`、`Minimax`、`Kimi`
- 仅限场景：主模型在合规范围内无法继续分析、厂商覆盖不足、特定问题需要补充视角
- 不是默认路线：fallback 不能直接成为项目主链路
- 输出要求：必须回写为标准 handoff，包含 `Goal / Scope / Source of Truth / Constraints / Deliverable / Validation`
## Reset Rule
- 阶段切换时 reset
- 大型研究转规范时 reset
- 覆盖长文档后进入实施前 reset
- 发生 fallback 后，必须 reset 并只带 handoff 摘要继续

82
cc-switch-dev-workflow/references/knowledge-base/platform/stack-policy.md 普通文件
查看文件

@@ -0,0 +1,82 @@
# Platform Policy: Stack Whitelist
## Purpose
定义 v1 默认技术栈白名单、禁用项和例外审批接口，避免让 agent 在项目主链路上随机选型。
## When to Use
- 新项目立项时
- 老项目需要补一套统一技术栈约束时
- agent 要新增框架、语言或关键基础设施时
## Inputs
- 项目类型
- 产品形态
- 现有遗留约束
- 性能与交付要求
## Outputs
- 允许的主链路技术栈
- 禁用项
- 例外审批流程
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- `ralphy-initializing`
- `spec-reviewing`
## Steps
1. 先判断项目是 `Next.js 全栈` 还是 `Hono + React SSR/TanStack`。
2. 在允许的轨道内固定 UI、数据层、鉴权、样式和 ORM 方案。
3. 把选型写进 `CLAUDE.md`、Spec 和脚手架说明。
4. 如需偏离白名单，先走 ADR 和审批，再更新模板与执行说明。
## Exit Criteria
- 项目主链路的语言、框架、数据访问、鉴权和样式方案均已固定
- 例外项已被 ADR 化，并同步到模板和执行说明
## Failure Recovery
- 如果 agent 引入未批准语言或框架，停止实现并回退到白名单决策
- 如果项目同时混用多套主路由/状态/ORM 方案，立即收敛为单一路线
## Related Templates
- [`../templates/claude-md-template.md`](../templates/claude-md-template.md)
- [`../templates/spec-template.md`](../templates/spec-template.md)
## Default Whitelist
- 语言：`TypeScript`
- UI：`React`
- 样式：`Tailwind CSS`
- 组件：`shadcn/ui`
- 鉴权：`Better Auth`
- 数据获取：`TanStack Query`
- 路由：`TanStack Router` 或 `Next.js App Router`，按轨道二选一
- 服务层：`Hono` 或 `Next.js route handlers / server actions`，按轨道二选一
- ORM：`Drizzle`
- 数据库：`PostgreSQL`
## Default Track Preference
- 默认优先：`Hono + React SSR/TanStack`
- 条件允许时可选：`Next.js 全栈`
## Hard Bans On The Application Main Path
- 禁止 `Python` 作为产品应用主链路语言
- 禁止 `PHP` 作为产品应用主链路语言
- 禁止无类型的 `JavaScript-only` 作为默认实现路线
- 禁止未经 ADR 批准的第二套路由、鉴权、ORM 或样式体系并存
## Allowed Exceptions
- 既有遗留系统必须兼容，且短期无法迁移
- 明确的第三方平台限制只支持某一特定方案
- 已被性能分析证明主链路栈无法满足约束
- 一次性离线工具、迁移脚本或数据清洗脚本
## Exception Interface
- 谁批准：项目 owner + 技术负责人
- 需要补什么：ADR、`CLAUDE.md` 更新、相关 Spec 更新
- 要同步哪里：playbook 说明、模板默认值、handoff 约束
- 何时失效：例外只对当前项目或当前子系统生效，不自动扩散为默认规则

87
cc-switch-dev-workflow/references/knowledge-base/playbooks/existing-project-spec-backfill-and-refactor.md 普通文件
查看文件

@@ -0,0 +1,87 @@
# Playbook: Existing Project Spec Backfill And Refactor
## Purpose
为已有代码库补齐 `SPECS/`、重新建立规则层，并把缺失的结构化重构纳入正式流程。
## When to Use
- 老项目没有完整 Spec
- 代码能跑，但规则、边界和设计意图不清
- 团队准备把维护项目迁入标准 AI Agent 流程
## Inputs
- 现有代码库
- 历史文档和会议纪要
- 测试现状
- 当前问题清单
## Outputs
- 补齐后的 `CLAUDE.md`
- `.research/*.md`
- `SPECS/*.md`
- 重构和补齐计划
## Primary Agent/Model
计划 agent + `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
审查 agent + `Claude Opus 4.6`
## Required Skills
- `spec-tasking`
- `spec-reviewing`
- `code-refactoring`
- `architecture-audit`
## Steps
1. 先做 `Setup`，补 `CLAUDE.md` 和技术轨道。
2. 从现有代码与历史文档反推 Research 结论。
3. 编写并审核 `SPECS/*.md`。
4. 对照 Spec 跑 `Alignment`，把现状和规则重新对齐。
5. 跑 `Refinement`，收掉结构债和命名债。
## Exit Criteria
- 老项目已经具备规范层、任务层和审查门禁
- 后续新需求可以按标准 7 阶段继续推进
## Failure Recovery
- 如果代码库过于混乱无法直接写 Spec，先用 Research 做领域切片
- 如果团队试图直接大改代码而不补 Spec，回到本 playbook 的 Spec 阶段
## Related Templates
- [`../templates/claude-md-template.md`](../templates/claude-md-template.md)
- [`../templates/spec-template.md`](../templates/spec-template.md)
- [`../templates/acceptance-checklist-template.md`](../templates/acceptance-checklist-template.md)
## Stable Knowledge Vs Runtime Context
- 稳定知识：规范结构、重构节奏、架构审计方式
- 运行时上下文：当前代码病灶、当前历史文档、当前遗留约束
## First-Round Prompt Kit
### Prompt 1: Baseline
```text
读取当前代码库和现有文档，识别主要模块、边界问题、技术债和缺失的项目执行说明。输出 Setup/Research 的基线评估，不做代码修改。
```
### Prompt 2: Spec Backfill
```text
基于代码现状、历史文档和基线评估，产出 ANALYSIS.md、TODO.yaml 和 SPECS/*.md。Spec 只定义系统契约，不复制实现细节；产出后执行 spec-reviewing，并列出人工审核项。
```
### Prompt 3: Refactor Roadmap
```text
基于已审核通过的 SPECS/*.md 和现有代码，生成 Alignment 与 Refinement 的任务序列。优先补齐缺口，再收敛结构问题，不做无依据的大改。
```
## Stage Deliverables
- Setup：补写 `CLAUDE.md`、确认轨道与边界
- Research：反向整理 `.research/*.md`
- Spec：形成 `SPECS/*.md` 并完成人工审核
- Alignment：对齐现有实现与 Spec
- Refinement：全局简化、重构、架构审计
## Acceptance Checklist
- 老项目已有清晰的 `CLAUDE.md`
- `SPECS/*.md` 不是代码镜像，而是系统契约
- Alignment 后没有高优先级缺口残留
- Refinement 后的结构与命名更清晰，不是更复杂

90
cc-switch-dev-workflow/references/knowledge-base/playbooks/new-project-from-scaffold.md 普通文件
查看文件

@@ -0,0 +1,90 @@
# Playbook: New Project From Scaffold
## Purpose
为全新项目提供一条从 `Setup -> Research -> Spec -> Code -> Alignment` 的标准启动路径，先固化规则，再进入实现。
## When to Use
- 绿地项目
- 现有目录几乎为空，需要从标准脚手架和规范开始
- 团队希望统一技术轨道、模型路由和阶段产物
## Inputs
- 项目目标
- 原始会议纪要
- 初始目录
- 目标交付范围
## Outputs
- `CLAUDE.md`
- `.ralphy/config.yaml`
- `.research/*.md`
- `SPECS/*.md`
- 第一轮实施计划与任务清单
## Primary Agent/Model
主控/计划 agent + `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
研究/审查 agent + `Claude Opus 4.6`
## Required Skills
- `ralphy-initializing`
- `spec-tasking`
- `spec-reviewing`
- `tdd-planning`
- `tdd-implementing`
## Steps
1. 跑 `Setup`，清洗会议、固定技术轨道、生成 `CLAUDE.md`。
2. 跑 `Research`，对照参考仓库生成主题化研究报告。
3. 跑 `Spec`，形成 `SPECS/*.md` 并完成人工审核。
4. 跑 `Code`，用 TDD 和检查点重构实施第一轮代码。
5. 跑 `Alignment`，补齐遗漏和偏离。
## Exit Criteria
- 项目已形成可复用的规范层和可执行实施层
- 新成员可从 `CLAUDE.md`、`SPECS/*.md` 和 `TODO.yaml` 直接接手
## Failure Recovery
- 如果参考仓库质量不足，先补 Research，不要提前写 Spec
- 如果 Spec 审核不过，禁止进入 Code
## Related Templates
- [`../templates/claude-md-template.md`](../templates/claude-md-template.md)
- [`../templates/analysis-template.md`](../templates/analysis-template.md)
- [`../templates/spec-template.md`](../templates/spec-template.md)
- [`../templates/todo-yaml-template.md`](../templates/todo-yaml-template.md)
## Stable Knowledge Vs Runtime Context
- 稳定知识：技术栈白名单、阶段流程、模板、handoff 契约
- 运行时上下文：当前项目目标、当前会议决策、当前参考仓库结论
## First-Round Prompt Kit
### Prompt 1: Setup
```text
基于当前项目会议纪要和目录，按知识库的 Setup 流程生成项目初始化产物。固定技术轨道，只保留一个主路径；输出清洗后的会议要点、CLAUDE.md 草案、.ralphy/config.yaml 草案，以及进入 Research 的 handoff。
```
### Prompt 2: Research
```text
基于 CLAUDE.md、已选技术轨道和 .references/ 参考仓库，生成 ANALYSIS.md 和 TODO.yaml，并按主题产出 .research/*.md。只保留与当前项目目标相关的方案比较、推荐做法和拒绝理由。
```
### Prompt 3: Spec
```text
基于 .research/*.md 和业务目标，生成 SPECS/*.md。先生成 ANALYSIS.md 与 TODO.yaml，再产出 Spec；完成后执行 spec-reviewing，并整理出等待人工审核的问题清单。
```
## Stage Deliverables
- Setup：`.meetings/`, `.ralphy/config.yaml`, `CLAUDE.md`
- Research：`ANALYSIS.md`, `TODO.yaml`, `.research/*.md`
- Spec：`SPECS/*.md`, 审查结论, 人工审核结论
- Code：`.plans/*.md`, 代码与测试
- Alignment：缺口分析、补齐实现、重构检查点结果
## Acceptance Checklist
- 技术轨道只有一个主路线
- `CLAUDE.md` 已固定规则与禁用项
- `SPECS/*.md` 已通过人工审核
- 第一轮代码实施与 Alignment 已经形成闭环

88
cc-switch-dev-workflow/references/knowledge-base/playbooks/spec-code-alignment-gap-closure.md 普通文件
查看文件

@@ -0,0 +1,88 @@
# Playbook: Spec-Code Alignment Gap Closure
## Purpose
当 `SPECS/*.md` 已经存在，但代码与规范发生漂移时，用最短路径恢复一致性。
## When to Use
- 已有 Spec
- 代码和 Spec 明显不一致
- 验收前发现遗漏、偏离或未测试条款
## Inputs
- `SPECS/*.md`
- 现有代码
- 当前测试结果
- 既有 `.plans/*.md`
## Outputs
- Gap `ANALYSIS.md`
- Alignment `TODO.yaml`
- 补齐计划与补齐实现
- 验收前复核结论
## Primary Agent/Model
计划/实现 agent + `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
审查 agent + `Claude Opus 4.6`
## Required Skills
- `spec-gap-analyzing`
- `spec-gap-tasking`
- `tdd-planning`
- `tdd-implementing`
- `code-simplifying`
- `code-refactoring`
## Steps
1. 先做 Gap 分析，分类为 `Missing / Partial / Divergent / Untested / Integration`。
2. 基于分析生成 Plan/Impl 对。
3. 按优先级补齐高风险缺口。
4. 每批缺口后做简化和重构。
5. 重新跑验收清单。
## Exit Criteria
- 已知高优先级缺口全部收敛
- Spec 与代码重新建立可验证的一致性
## Failure Recovery
- 如果发现问题源头是 Spec 错误，回到 Spec 阶段修订
- 如果缺口范围不断扩大，回到计划层重排优先级
## Related Templates
- [`../templates/tdd-plan-template.md`](../templates/tdd-plan-template.md)
- [`../templates/todo-yaml-template.md`](../templates/todo-yaml-template.md)
- [`../templates/acceptance-checklist-template.md`](../templates/acceptance-checklist-template.md)
## Stable Knowledge Vs Runtime Context
- 稳定知识：Gap 分类、Plan/Impl 对、检查点机制
- 运行时上下文：本轮缺口证据、本轮实现状态、本轮测试失败点
## First-Round Prompt Kit
### Prompt 1: Gap Analysis
```text
基于 SPECS/*.md 和当前代码，生成 Gap ANALYSIS.md。逐条指出 Missing、Partial、Divergent、Untested、Integration 五类问题，并按影响优先级排序。
```
### Prompt 2: Gap Tasking
```text
基于已审核的 Gap ANALYSIS.md 和 SPECS/*.md，生成 Alignment TODO.yaml。每个真实缺口都拆成 Plan/Impl 对，并按批次插入 Simplify/Refactor 检查点。
```
### Prompt 3: Closure
```text
按 TODO.yaml 补齐缺口。每个 Impl 任务后立即简化，批次后做重构；最后输出剩余风险、未覆盖项和再次验收建议。
```
## Stage Deliverables
- Gap 分析：`ANALYSIS.md`
- Gap 任务：`TODO.yaml`
- 实施计划：`.plans/*.md`
- 补齐后代码与测试
- 验收前复核说明
## Acceptance Checklist
- 五类缺口均已分类处理
- 没有用“更优雅实现”替代对 Spec 的遵守
- 关键流程已有测试托底

65
cc-switch-dev-workflow/references/knowledge-base/sources/2026-02-02-ralphy-task-list-flow.md 普通文件
查看文件

@@ -0,0 +1,65 @@
# Source Digest: 2026-02-02 Ralphy Task List Flow
## Purpose
提炼 `20260202-ralphy任务清单开发流程(3).md` 中关于设计先行、Ralphy 配置和任务标题质量的最小执行规则。
## When to Use
- 需要快速解释为什么先写设计文档再让 AI 执行循环时
- 需要生成 `tasks.md` 或 `TODO.yaml` 的命名与约束时
- 需要初始化 `.ralphy/config.yaml` 时
## Inputs
- `20260202-ralphy任务清单开发流程(3).md`
## Outputs
- Ralphy 最小可执行规则
- 配置基线
- 任务文案要求
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- `ralphy-initializing`
- `spec-tasking`
## Steps
1. 提取最小流程和配置要求。
2. 将 `tasks.md` 规则折叠进 `TODO.yaml` 模板。
3. 保留必要配置项，去掉一次性案例细节。
## Exit Criteria
- Ralphy 初始化与任务标题规则都已有固定模板
## Failure Recovery
- 如果项目已不使用 Ralphy CLI，本页仍保留任务标题的自包含规则，不依赖具体工具
## Related Templates
- [`../templates/todo-yaml-template.md`](../templates/todo-yaml-template.md)
- [`../templates/claude-md-template.md`](../templates/claude-md-template.md)
## Core Conclusions
- 先写设计哲学与规范，再让 AI 进入执行循环，杠杆最大。
- 用法文档和设计文档属于低成本试错层，必须在代码前反复打磨。
- Ralphy 的规则配置要写死到项目配置里，而不是靠口头提醒。
- 默认 `TypeScript strict mode`、`KISS`、`DRY`、`YAGNI`、最大化复用。
## Reusable Rules
- `.ralphy/config.yaml` 至少要固定 `test/lint/build` 命令和项目规则。
- AI 执行前先读 `.references/`，如果有参考至少对照两个。
- 任务列表要能独立被执行，不能依赖任务正文的隐含语境。
## Background Only
- “几十轮打磨用法文档”的经验性描述
- 示例里的具体组件库和项目名
## Conflict Notes
- 本文使用 `tasks.md` 作为示例文件名；知识库统一使用 `TODO.yaml`，以 `workflow.zip` 和 `skills.zip` 为准。
## Traceability Targets
- `workflows/stage-0-setup.md`
- `workflows/stage-3-code.md`
- `templates/todo-yaml-template.md`

75
cc-switch-dev-workflow/references/knowledge-base/sources/2026-03-04-ai-pipeline-reliability.md 普通文件
查看文件

@@ -0,0 +1,75 @@
# Source Digest: 2026-03-04 AI Pipeline Reliability
## Purpose
提炼 `20260304-AI自动化开发流水线与可靠性工程(1).md` 中关于可靠性工程、偏差放大、Gap 对齐、代码简化和阶段性重构的规则。
## When to Use
- 需要定义为什么不能让模型从需求直接写代码时
- 需要设计 `Alignment`、`Refinement` 和质量检查点时
- 需要解释 80% 单步可靠性为何会导致整体失控时
## Inputs
- `20260304-AI自动化开发流水线与可靠性工程(1).md`
## Outputs
- 可靠性收敛规则
- Gap 分类与质量机制
- 与其他来源的冲突说明
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- `spec-gap-tasking`
- `code-simplifying`
- `code-refactoring`
- `architecture-audit`
## Steps
1. 提炼可靠性数学和偏差来源。
2. 提炼“遗漏”和“过度添加”两类核心失真。
3. 映射到 Alignment、Refinement 和 Acceptance 页。
4. 把策略性选项与执行规则分开。
## Exit Criteria
- 可靠性收敛逻辑已经转化为阶段化执行规则
- 缺口分类、检查点、验收路径全部有落点
## Failure Recovery
- 若与更具体的技能规则冲突，以技能规则定义的任务结构和检查点为准
## Related Templates
- [`../templates/tdd-plan-template.md`](../templates/tdd-plan-template.md)
- [`../templates/acceptance-checklist-template.md`](../templates/acceptance-checklist-template.md)
## Core Conclusions
- 从需求到代码的每一层都会放大偏差，不能把“总体看起来差不多”当作可靠。
- 减少层级和提升单步质量，是提高整体可靠性的两个杠杆。
- AI 实施最主要的两类问题是 `遗漏` 和 `过度添加`，分别需要 `Gap 对齐` 和 `代码简化` 去收敛。
- 简化、重构、对齐不能作为末尾补丁，而要嵌入主流程。
- `Spec` 的质量决定最终收敛上限，低质量 Spec 只会让系统更快地收敛到低质量结果。
## Reusable Rules
- 用 `Alignment` 补齐 `Missing / Partial / Divergent / Untested / Integration` 五类缺口。
- 每 4 个类别插入一次质量检查点，防止技术债堆积。
- `Refinement` 不是一次“美化”，而是全库级的清晰度、结构和架构收敛。
- `Acceptance` 必须由人主导，不能被自动化审查替代。
## Background Only
- 各组用量对比
- 外部项目 OpenClaw 的星数与账号投入
- 市场竞争与六月产品上线时间点
## Conflict Notes
- 本文对 95% 单步可靠性给出目标值，但没有提供模板和目录组织；执行骨架依旧以 `workflow.zip` 和 `skills.zip` 为准。
- 文中部分质量检查点是理念层描述，正式任务对的生成方式以 `spec-gap-tasking` 为准。
## Traceability Targets
- `foundations/reliability-and-convergence.md`
- `foundations/refactoring-and-gap-closure.md`
- `workflows/stage-4-alignment.md`
- `workflows/stage-5-refinement.md`
- `workflows/stage-6-acceptance.md`

77
cc-switch-dev-workflow/references/knowledge-base/sources/2026-03-06-spec-driven-workflow.md 普通文件
查看文件

@@ -0,0 +1,77 @@
# Source Digest: 2026-03-06 Spec-Driven Workflow
## Purpose
提炼 `20260306-基于规范编程的开发模式与工作流.md` 中关于 Spec 驱动开发、技能体系、`CLAUDE.md`、调研与任务拆分的长期规则。
## When to Use
- 需要定义项目级设计哲学和 `CLAUDE.md` 时
- 需要解释为什么 Spec 是代码之前的单一真相源时
- 需要确定会议、调研、Spec、Code 的标准链路时
## Inputs
- `20260306-基于规范编程的开发模式与工作流.md`
## Outputs
- 可复用规则集
- 背景性信息分层
- 与其他来源的冲突说明
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- `spec-tasking`
- `spec-reviewing`
- `ralphy-initializing`
## Steps
1. 提取文档中的不变原则。
2. 区分“流程规则”和“历史背景”。
3. 将能执行的规则映射到 workflow、playbook 和模板。
4. 将策略性、可变化内容转移到 ADR。
## Exit Criteria
- 本文档中的规则已被至少一个正式页面复用
- 背景故事没有混入 SOP 主文
## Failure Recovery
- 如果某条说法与技能规则冲突，以技能规则为准并记录到 ADR
## Related Templates
- [`../templates/claude-md-template.md`](../templates/claude-md-template.md)
- [`../templates/spec-template.md`](../templates/spec-template.md)
- [`../templates/todo-yaml-template.md`](../templates/todo-yaml-template.md)
## Core Conclusions
- `Spec` 是代码之前的单一真相源，需求变化时先改 Spec，再改代码。
- `CLAUDE.md` 是项目执行说明的核心文件，必须承载设计哲学、技能索引、边界和质量标准。
- 会议纪要不能原样喂给模型，必须先清洗，只保留当前项目相关决策。
- 参考仓库要经过筛选，前端优先 `TypeScript` 实现，且要有近年更新与足够社区信号。
- 调研、Spec 审查和人工判断占大头，代码实施只占整体时间的一部分。
- 任务标题必须自包含，至少说明 `Action + Where + Reference`，否则 Ralphy 循环会偏航。
- 技能不是“提示词收藏夹”，而是团队最佳实践的标准化封装，能显著提升稳定性。
## Reusable Rules
- 新项目先建 `.meetings/`、`.references/`、`CLAUDE.md`、`SPECS/`，再谈实施。
- 每个项目都要有明确的设计哲学，不接受“让模型随机发挥”。
- 调研报告和 Spec 要模块化拆分，便于独立生成、独立审查、独立对齐。
- `SPECS/` 使用编号和分域组织，不按写作顺序组织。
- 每实现 4 个小任务做一次重构，结束后再做一次更大的收敛。
## Background Only
- 对大型团队培训 TDD/敏捷的背景讨论
- 对未来客户端形态、自我学习能力的愿景描述
- 对不同语言 skill 包数量的示例性说明
## Conflict Notes
- 本文强调 `CLAUDE.md` 和技能驱动，但没有提供统一的 7 阶段骨架；骨架以 `workflow.zip` 为准。
- 本文提到的某些 skill 名称与 `skills.zip` 中实际命名略有差异；正式文档统一以 `skills.zip` 为准。
## Traceability Targets
- `foundations/spec-driven-development.md`
- `foundations/human-agent-boundaries.md`
- `workflows/stage-0-setup.md`
- `playbooks/new-project-from-scaffold.md`

75
cc-switch-dev-workflow/references/knowledge-base/sources/README.md 普通文件
查看文件

@@ -0,0 +1,75 @@
# Sources Index And Traceability
## Purpose
建立知识库的来源索引、追溯矩阵和冲突处理规则，确保所有核心规则可回溯。
## When to Use
- 新增或修改知识库规则前
- 发现两份来源说法不一致时
- 需要证明某条 SOP 来自哪里时
## Inputs
- `20260306-基于规范编程的开发模式与工作流.md`
- `20260304-AI自动化开发流水线与可靠性工程(1).md`
- `20260202-ralphy任务清单开发流程(3).md`
- `workflow.zip`
- `skills.zip`
## Outputs
- 源资产摘要索引
- 规则追溯矩阵
- 冲突处理顺序
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- 无强制 skill；必要时参考 `spec-reviewing` 的一致性思路
## Steps
1. 先看每个源资产对应的 digest 页面。
2. 判断这条规则是阶段骨架、质量原则、技能约束还是执行经验。
3. 若多个来源重叠，按“更具体、更晚、更新、更可执行”的顺序裁决。
4. 若裁决影响主流程或白名单，写 ADR 后再更新知识库正文。
## Exit Criteria
- 每条核心规则都能指向至少一个源资产
- 冲突规则已记录取舍和去向
- 不需要回看原始大段会议文本即可找到规则入口
## Failure Recovery
- 如果某条规则找不到来源，先降级为“待确认”，不要写入正式 SOP
- 如果来源冲突无法消解，写 ADR 并保留冲突说明
## Related Templates
- [`../templates/analysis-template.md`](../templates/analysis-template.md)
- [`../templates/agent-handoff-template.md`](../templates/agent-handoff-template.md)
## Source Digest 列表
| 源资产 | Digest |
|---|---|
| `20260306-基于规范编程的开发模式与工作流.md` | [`2026-03-06-spec-driven-workflow.md`](./2026-03-06-spec-driven-workflow.md) |
| `20260304-AI自动化开发流水线与可靠性工程(1).md` | [`2026-03-04-ai-pipeline-reliability.md`](./2026-03-04-ai-pipeline-reliability.md) |
| `20260202-ralphy任务清单开发流程(3).md` | [`2026-02-02-ralphy-task-list-flow.md`](./2026-02-02-ralphy-task-list-flow.md) |
| `workflow.zip` | [`workflow-zip-digest.md`](./workflow-zip-digest.md) |
| `skills.zip` | [`skills-zip-digest.md`](./skills-zip-digest.md) |
## 追溯矩阵
| 主题 | 主要来源 | 落点 |
|---|---|---|
| Spec 驱动、`CLAUDE.md`、调研到实施的链路 | `20260306...md` | `foundations/spec-driven-development.md`, `workflows/stage-0-setup.md`, `playbooks/new-project-from-scaffold.md` |
| 可靠性数学、Gap、简化与重构收敛 | `20260304...md` | `foundations/reliability-and-convergence.md`, `foundations/refactoring-and-gap-closure.md`, `workflows/stage-4-alignment.md`, `workflows/stage-5-refinement.md` |
| Ralphy 自包含任务标题与配置规则 | `20260202...md`, `skills.zip` | `templates/todo-yaml-template.md`, `workflows/stage-3-code.md` |
| 7 阶段流程骨架 | `workflow.zip` | `workflows/README.md` 与全部阶段页 |
| 技能到阶段的映射 | `skills.zip` | `workflows/`, `templates/`, `orchestration/` |
## 冲突处理顺序
1. `skills.zip` 中技能规则优先于泛化的阶段口述，前提是它更具体。
2. 两份会议整理冲突时，优先更晚的文档。
3. `workflow.zip` 提供流程骨架，不覆盖后续更具体的技能行为约束。
4. 一切正式取舍写入 [`../decisions/ADR-2026-03-21-source-precedence-and-conflict-resolution.md`](../decisions/ADR-2026-03-21-source-precedence-and-conflict-resolution.md)。

78
cc-switch-dev-workflow/references/knowledge-base/sources/skills-zip-digest.md 普通文件
查看文件

@@ -0,0 +1,78 @@
# Source Digest: skills.zip
## Purpose
提炼 `skills.zip` 中与知识库直接相关的 skill 行为约束，尤其是任务结构、审查门禁、检查点和计划模板。
## When to Use
- 需要把阶段流程落到可执行技能时
- 需要定义 `TODO.yaml`、Plan/Impl 对、审查门禁和重构检查点时
- 需要确认“流程说法”和“技能行为”哪个更具体时
## Inputs
- `skills.zip`
## Outputs
- 技能级执行约束摘要
- 阶段到 skill 的映射
- 审查与计划模板约束
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- `spec-tasking`
- `spec-gap-tasking`
- `spec-reviewing`
- `ralphy-initializing`
- `tdd-planning`
- `tdd-implementing`
- `code-simplifying`
- `code-refactoring`
- `architecture-audit`
## Steps
1. 找出直接约束阶段流程的 skill。
2. 把技能规则转成知识库里的固定结构。
3. 将可变化的策略和命名差异转移到 ADR。
## Exit Criteria
- 阶段和模板里的行为约束与 skill 真实定义一致
## Failure Recovery
- 如果阶段文档与 skill 描述冲突，以 skill 描述定义的任务结构、检查点和门禁为准
## Related Templates
- [`../templates/tdd-plan-template.md`](../templates/tdd-plan-template.md)
- [`../templates/todo-yaml-template.md`](../templates/todo-yaml-template.md)
- [`../templates/spec-template.md`](../templates/spec-template.md)
## Core Conclusions
- `spec-tasking` 先审计 `ANALYSIS.md`，再生成 `TODO.yaml`，避免为已存在内容重复派工。
- `spec-gap-tasking` 必须先对照真实实现再生成 Plan/Impl 对，并按批次插入质量检查点。
- `spec-reviewing` 是 Spec 进入实施前的硬门禁，重点看结构、语义、可实施性和过度设计。
- `code-simplifying` 关注刚改过的代码，优先删除“伪代码化文档”和不必要抽象。
- `code-refactoring` 从最近变更出发，但会跨代码库追查重复、职责错位和依赖反转问题。
- `architecture-audit` 是系统级全库健康检查，不等同于最近修改的重构。
## Reusable Rules
- `TODO.yaml` 的标题必须是一行内可执行说明。
- 对 Gap 和实现类任务，默认是 `Plan -> Implement -> Simplify -> Checkpoint Refactor`。
- 审查和重构任务都要以现有代码和现有文档为前提，不允许忽略现状直接重写。
## Background Only
- skill 内部的示例路径、年份占位和具体范例文本
- 与当前知识库无关的语言特定参考文件细节
## Conflict Notes
- 部分 skill 的文案更偏代码项目；知识库已经把这些规则重写为 `CC Switch` 可执行版，但不会改变核心任务结构。
## Traceability Targets
- `workflows/stage-2-spec.md`
- `workflows/stage-3-code.md`
- `workflows/stage-4-alignment.md`
- `workflows/stage-5-refinement.md`
- `templates/todo-yaml-template.md`
- `templates/tdd-plan-template.md`

66
cc-switch-dev-workflow/references/knowledge-base/sources/workflow-zip-digest.md 普通文件
查看文件

@@ -0,0 +1,66 @@
# Source Digest: workflow.zip
## Purpose
提炼 `workflow.zip` 中的 7 阶段骨架、阶段输入输出和阶段间流转关系，作为知识库流程层的主骨架。
## When to Use
- 需要快速定位当前项目所在阶段时
- 需要把会议经验落到统一阶段模型时
- 需要知道每个阶段的标准产物时
## Inputs
- `workflow.zip`
## Outputs
- 7 阶段骨架
- 阶段产物清单
- 与技能和会议经验的拼接点
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- 阶段自身列出的全部 skill
## Steps
1. 读取 `README.md` 和 `QUICK-REFERENCE.md` 得到总骨架。
2. 逐个读取 `0-setup.md` 到 `6-acceptance.md`。
3. 将阶段骨架改写为 `CC Switch` 适配版。
4. 用技能规则和会议规则修补“谁来做、何时 reset、何时人工接管”。
## Exit Criteria
- 7 阶段均有明确输入、输出、主模型、辅模型、技能和退出条件
## Failure Recovery
- 如果 `workflow.zip` 的流程描述与技能模板不一致，保留其阶段骨架，但用技能规则修正阶段内部行为
## Related Templates
- [`../templates/analysis-template.md`](../templates/analysis-template.md)
- [`../templates/todo-yaml-template.md`](../templates/todo-yaml-template.md)
- [`../templates/acceptance-checklist-template.md`](../templates/acceptance-checklist-template.md)
## Core Conclusions
- 流程统一分为 `Setup / Research / Spec / Code / Alignment / Refinement / Acceptance` 七个阶段。
- 每个阶段都要有输入、输出、关键活动、工作流图和下一步衔接。
- `workflow.zip` 已经提供了适合新人理解的阶段职责划分，是知识库的流程骨架来源。
## Reusable Rules
- 阶段输出要标准化，尤其是 `ANALYSIS.md`、`TODO.yaml`、`SPECS/*.md`、`.plans/*.md`。
- `Acceptance` 明确是人工主导，不是自动化阶段。
- `Refinement` 默认包含全局简化和增量重构，可选再做模块化与结构重组。
## Background Only
- 示例项目中的具体组件、包名和年份占位
- 流程图里的示意性文件路径
## Conflict Notes
- `workflow.zip` 对多 agent 分工没有建模；该部分由 `orchestration/` 补齐。
- `workflow.zip` 某些技能名是抽象名，具体名称以 `skills.zip` 为准。
## Traceability Targets
- `workflows/README.md`
- `workflows/stage-0-setup.md` 到 `workflows/stage-6-acceptance.md`
- `playbooks/*.md`

53
cc-switch-dev-workflow/references/knowledge-base/templates/README.md 普通文件
查看文件

@@ -0,0 +1,53 @@
# Templates Index
## Purpose
提供知识库中的标准模板集合，统一输入输出格式，降低 agent 自由发挥空间。
## When to Use
- 新建 `CLAUDE.md`
- 新建 `ANALYSIS.md`
- 新建 `TODO.yaml`
- 新建 Spec、TDD 计划、handoff 和验收清单
## Inputs
- 当前阶段目标
- 当前范围边界
- 当前来源文档
## Outputs
- 标准化模板文件
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- 阶段相关 skill
## Steps
1. 从本页选择模板。
2. 按模板填入当前项目内容。
3. 保持字段结构不变，只替换内容。
## Exit Criteria
- 阶段产物都使用统一模板
## Failure Recovery
- 如果 agent 开始自定义模板字段，回到本页恢复标准结构
## Related Templates
- 全部模板均在本目录
## Template List
| 模板 | 用途 |
|---|---|
| [`claude-md-template.md`](./claude-md-template.md) | 项目执行说明 |
| [`analysis-template.md`](./analysis-template.md) | 阶段分析报告 |
| [`todo-yaml-template.md`](./todo-yaml-template.md) | 任务清单 |
| [`spec-template.md`](./spec-template.md) | 单份 Spec |
| [`tdd-plan-template.md`](./tdd-plan-template.md) | 复杂任务实施计划 |
| [`agent-handoff-template.md`](./agent-handoff-template.md) | agent 交接契约 |
| [`acceptance-checklist-template.md`](./acceptance-checklist-template.md) | 验收清单 |

70
cc-switch-dev-workflow/references/knowledge-base/templates/acceptance-checklist-template.md 普通文件
查看文件

@@ -0,0 +1,70 @@
# Template: Acceptance Checklist
## Purpose
把最终人工验收标准固定下来，避免发布前只靠口头确认。
## When to Use
- Acceptance 阶段
- 里程碑发布前
## Inputs
- 最终代码库
- `SPECS/*.md`
- 测试结果
## Outputs
- 验收结论
## Primary Agent/Model
人工主导
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- 无
## Steps
1. 按清单逐项确认。
2. 给每个问题定级。
3. 决定发布、回退或继续收敛。
## Exit Criteria
- 通过/不通过有明确结论
## Failure Recovery
- 若结论模糊，重新按清单走，不做主观拍板
## Related Templates
- [`agent-handoff-template.md`](./agent-handoff-template.md)
## Template
```markdown
# Acceptance Checklist
## Functional
- [ ] All SPEC clauses implemented
- [ ] Critical user flows work
- [ ] Edge cases handled
## Testing
- [ ] All tests pass
- [ ] Core coverage acceptable
- [ ] No known blocking race/security issue
## Documentation
- [ ] SPECS align with code
- [ ] Public APIs documented
- [ ] README/update notes complete
## Code Quality
- [ ] Lint/build pass
- [ ] No unresolved high-risk architecture issue
- [ ] Module boundaries remain clear
## Decision
- [ ] Release
- [ ] Return to Alignment
- [ ] Return to Code
- [ ] Record follow-up items
```

68
cc-switch-dev-workflow/references/knowledge-base/templates/agent-handoff-template.md 普通文件
查看文件

@@ -0,0 +1,68 @@
# Template: Agent Handoff
## Purpose
统一 agent 之间的交接格式，压缩上下文且保留必需边界。
## When to Use
- 线程切换
- 角色切换
- fallback 回主线程
## Inputs
- 上一角色高密度产物
- 当前边界
## Outputs
- handoff 摘要
## Primary Agent/Model
当前发起 handoff 的 agent
## Secondary Agent/Model
接收 handoff 的 agent
## Required Skills
- 无
## Steps
1. 填满所有字段。
2. 删除无关对话。
3. 确认接收方无需回看原线程。
## Exit Criteria
- 接收方能立即开始执行
## Failure Recovery
- 若 handoff 无法直接执行，说明摘要还不够密
## Related Templates
- [`analysis-template.md`](./analysis-template.md)
## Template
```markdown
# Handoff
## Goal
-
## Scope
-
## Non-Goals
-
## Source of Truth
-
## Constraints
-
## Deliverable
-
## Validation
-
## Escalation
- Stop and ask when:
```

78
cc-switch-dev-workflow/references/knowledge-base/templates/analysis-template.md 普通文件
查看文件

@@ -0,0 +1,78 @@
# Template: ANALYSIS.md
## Purpose
统一阶段分析报告结构，确保下一步 tasking 有稳定输入。
## When to Use
- Research
- Spec
- Code
- Alignment
## Inputs
- 当前阶段源材料
- 当前阶段目标
- 当前阶段边界
## Outputs
- `ANALYSIS.md`
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- 对应阶段 analyzing skill
## Steps
1. 先写范围和目标。
2. 再写优先级、结构拆分和风险。
3. 只保留下一步 tasking 真正需要的信息。
## Exit Criteria
- tasking agent 不需要回看原始长文就能生成任务
## Failure Recovery
- 如果分析报告无法直接生成任务，说明范围还没压缩好
## Related Templates
- [`todo-yaml-template.md`](./todo-yaml-template.md)
- [`agent-handoff-template.md`](./agent-handoff-template.md)
## Template
```markdown
# ANALYSIS
## Goal
-
## Scope
- Included:
- Excluded:
## Inputs
-
## Findings
-
## Priority
1.
2.
3.
## Structure
- Category A:
- Category B:
## Risks
-
## Decisions Needed
-
## Exit Criteria
-
```

93
cc-switch-dev-workflow/references/knowledge-base/templates/claude-md-template.md 普通文件
查看文件

@@ -0,0 +1,93 @@
# Template: CLAUDE.md
## Purpose
生成项目级执行说明，让 agent 始终在固定边界内工作。
## When to Use
- Setup 阶段
- 老项目补规范时
## Inputs
- 清洗后的会议纪要
- 技术轨道决策
- 项目目标与边界
## Outputs
- `CLAUDE.md`
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- `ralphy-initializing`
## Steps
1. 用下方模板生成草案。
2. 对照 `platform/` 和 `orchestration/` 页面补齐白名单和流程约束。
3. 审核后作为项目执行说明固化。
## Exit Criteria
- `CLAUDE.md` 足够让实现 agent 不再随机发挥
## Failure Recovery
- 若缺少禁用项、例外接口或验收标准，禁止进入后续阶段
## Related Templates
- [`analysis-template.md`](./analysis-template.md)
## Template
```markdown
# CLAUDE.md
## Project
- Name:
- Goal:
- Audience:
- In Scope:
- Out of Scope:
## Design Philosophy
- KISS:
- DRY:
- YAGNI:
- Type Safety First:
- Preferred Architectural Shape:
## Default Stack
- Track:
- Language:
- UI:
- Styling:
- Auth:
- Data Fetching:
- Router:
- Service Layer:
- ORM:
- Database:
## Hard Boundaries
- Do not introduce:
- Do not modify:
- Do not bypass:
- Exceptions require:
## Process Requirements
- Follow stages:
- Source of truth:
- Required review gates:
- Required testing posture:
- Required refactor rhythm:
## Skills And Templates
- Preferred skills:
- Required templates:
## Definition Of Done
- Spec approved:
- Tests pass:
- Alignment complete:
- Acceptance signed off:
```

70
cc-switch-dev-workflow/references/knowledge-base/templates/spec-template.md 普通文件
查看文件

@@ -0,0 +1,70 @@
# Template: SPEC
## Purpose
统一单份 Spec 的章节结构和内容边界。
## When to Use
- Spec 阶段
- 老项目补 Spec
## Inputs
- `.research/*.md`
- 业务目标
- 边界与术语
## Outputs
- `SPECS/*.md`
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- `spec-reviewing`
- 若已安装可选：`spec-writing`
## Steps
1. 用固定结构写 Spec。
2. 只保留系统契约，不写教程。
3. 审查通过后再进入实施。
## Exit Criteria
- Spec 可被违反、可被测试、可被引用
## Failure Recovery
- 若内容无法被违反，移出 Spec
- 若写成实现细节，回退到更高抽象层
## Related Templates
- [`analysis-template.md`](./analysis-template.md)
## Template
```markdown
# <SPEC Title>
## Overview
- Defines:
- Not Covered:
- Related SPECS:
## Terminology
-
## Domain Sections
### <Section Name>
- Rule:
- Acceptance:
> **Why**:
> **Rejected**:
## Forbidden
- Do not:
- Use instead:
- Reason:
## References
- Internal:
- External:
```

87
cc-switch-dev-workflow/references/knowledge-base/templates/tdd-plan-template.md 普通文件
查看文件

@@ -0,0 +1,87 @@
# Template: TDD Plan
## Purpose
为复杂实现任务提供统一的 `.plans/*.md` 结构，确保实施 agent 拿到的是高密度执行计划，而不是松散说明。
## When to Use
- Code 阶段的复杂任务
- Alignment 阶段的缺口补齐任务
## Inputs
- `SPECS/*.md`
- 现有代码现状
- 当前任务范围
## Outputs
- `.plans/YYYY-MM-DD-<slug>.md`
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- `tdd-planning`
## Steps
1. 明确约束和依赖。
2. 定义接口契约。
3. 分阶段列出测试与实现顺序。
## Exit Criteria
- 实现 agent 无需回看完整 Spec 就能开始做 TDD
## Failure Recovery
- 如果计划没有测试场景或验收标准，计划不合格
## Related Templates
- [`todo-yaml-template.md`](./todo-yaml-template.md)
## Template
```markdown
# TDD Plan: <Feature>
## Goal
-
## Scope
- Included:
- Excluded:
## Constraints
-
## Current State
-
## Architecture
- Modules touched:
- Dependency order:
## Interface Contract
- Public API:
- Input:
- Output:
- Errors:
## Test Plan
1. Failing test:
2. Minimal implementation:
3. Refactor:
## Phases
### Phase 1
-
### Phase 2
-
## Validation
- Unit tests:
- Integration tests:
- Lint/build:
## Acceptance Criteria
-
```

68
cc-switch-dev-workflow/references/knowledge-base/templates/todo-yaml-template.md 普通文件
查看文件

@@ -0,0 +1,68 @@
# Template: TODO.yaml
## Purpose
统一任务清单格式，保证任务标题自包含并适配循环执行。
## When to Use
- Spec tasking
- Code tasking
- Alignment tasking
## Inputs
- 已审核的 `ANALYSIS.md`
- 当前阶段的来源文件
## Outputs
- `TODO.yaml`
## Primary Agent/Model
`GPT-5.4 Pro xhigh`
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- `spec-tasking`
- `spec-gap-tasking`
- `spec-implementing-tasking`
## Steps
1. 每个任务标题都写清 `Action + Where + Reference`。
2. 复杂任务拆成 `Plan + Impl`。
3. 每批任务插入质量检查点。
## Exit Criteria
- 任务可以只看标题执行
## Failure Recovery
- 如果标题读不出范围和依据，重写任务，不补描述赌运气
## Related Templates
- [`analysis-template.md`](./analysis-template.md)
## Template
```yaml
tasks:
# Priority 1
- title: "Plan <feature> (<operation>) and use <planning-skill> to generate .plans/<date>-<slug>.md"
description: "Scope: <where>. Reference: <spec/research/source>."
completed: false
- title: "Implement <feature> in <where>, covering <reference>, and use <implementing-skill> to follow .plans/<date>-<slug>.md"
description: "Validation: <tests/checks>. Impact: <create/modify files>."
completed: false
- title: "Review <where> for simplification opportunities and use code-simplifying skill"
description: "Keep behavior unchanged."
completed: false
- title: "Review <where> for refactoring opportunities and use code-refactoring skill to generate .plans/<date>-<refactor-slug>.md"
description: "Focus: DRY/SRP/OCP/KISS."
completed: false
```
## Title Rules
- 必须是一行
- 必须点名模块或路径
- 必须点名依据文档或计划文件
- 不写“实现某功能”这种无上下文标题

63
cc-switch-dev-workflow/references/knowledge-base/workflows/README.md 普通文件
查看文件

@@ -0,0 +1,63 @@
# Workflows Overview
## Purpose
提供适配 `CC Switch` 的 7 阶段执行入口，让团队按统一节奏推进，而不是临时拼接多 agent。
## When to Use
- 刚接到一个新项目或新改造任务时
- 需要判断当前应该进哪个阶段时
- 要安排阶段切换和 reset 时
## Inputs
- 当前项目状态
- 已有文档和代码
- 已选 playbook
## Outputs
- 当前阶段判断
- 下一个阶段入口
- 阶段切换时的 reset 决策
## Primary Agent/Model
主控 agent + `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
审查 agent + `Claude Opus 4.6`
## Required Skills
- 阶段对应 skill
## Steps
1. 判断项目所处阶段。
2. 进入对应阶段页执行。
3. 阶段完成后只保留高密度产物，再切下个阶段。
## Exit Criteria
- 当前阶段已确定
- 对应阶段输入、输出和 reset 点都清楚
## Failure Recovery
- 如果一个任务横跨多个阶段同时推进，拆回阶段边界
## Related Templates
- [`../templates/analysis-template.md`](../templates/analysis-template.md)
- [`../templates/todo-yaml-template.md`](../templates/todo-yaml-template.md)
- [`../templates/agent-handoff-template.md`](../templates/agent-handoff-template.md)
## Stage Map
| 阶段 | 页面 |
|---|---|
| 0 Setup | [`stage-0-setup.md`](./stage-0-setup.md) |
| 1 Research | [`stage-1-research.md`](./stage-1-research.md) |
| 2 Spec | [`stage-2-spec.md`](./stage-2-spec.md) |
| 3 Code | [`stage-3-code.md`](./stage-3-code.md) |
| 4 Alignment | [`stage-4-alignment.md`](./stage-4-alignment.md) |
| 5 Refinement | [`stage-5-refinement.md`](./stage-5-refinement.md) |
| 6 Acceptance | [`stage-6-acceptance.md`](./stage-6-acceptance.md) |
## Reset Rule By Default
- 阶段产物完成后 reset
- 长文研究结束后 reset
- Spec 审核完成后 reset
- fallback 模型输出回主线前 reset

60
cc-switch-dev-workflow/references/knowledge-base/workflows/stage-0-setup.md 普通文件
查看文件

@@ -0,0 +1,60 @@
# Workflow: Stage 0 Setup
## Purpose
完成会议清洗、项目初始化、技术轨道选择和 `CLAUDE.md` 对齐，为后续阶段建立稳定边界。
## When to Use
- 新项目刚开始
- 老项目没有统一执行说明时
- 技术轨道和边界还没固定时
## Inputs
- 原始会议纪要
- 当前仓库结构
- 目标产品形态
- 选定 playbook
## Outputs
- 清洗后的 `.meetings/`
- `.ralphy/config.yaml`
- `CLAUDE.md`
- 已确认的技术轨道
## Primary Agent/Model
计划 agent + `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
研究/审查 agent + `Claude Opus 4.6`
## Required Skills
- `ralphy-initializing`
- 若已安装可选：`meeting-extracting`, `agent-md-writing`
## Steps
1. 清洗会议纪要，只保留项目相关决策。
2. 选择 `Next.js 全栈` 或 `Hono + React SSR/TanStack` 轨道。
3. 初始化 `.ralphy/config.yaml`。
4. 生成 `CLAUDE.md`，写明哲学、白名单、边界、测试与技能要求。
5. 产出 Setup handoff，供 Research 或 Spec 阶段读取。
## Exit Criteria
- `CLAUDE.md` 存在且可直接约束 agent
- 技术轨道已固定
- 原始会议纪要不再被直接拿去执行
## Failure Recovery
- 如果 `CLAUDE.md` 只写目标、不写边界，补齐约束后再继续
- 如果技术轨道仍摇摆，回到 `platform/` 决策页，不进入后续阶段
## Related Templates
- [`../templates/claude-md-template.md`](../templates/claude-md-template.md)
- [`../templates/agent-handoff-template.md`](../templates/agent-handoff-template.md)
## Stable Knowledge Vs Runtime Context
- 稳定知识：技术栈白名单、项目哲学、任务规则、技能映射
- 运行时上下文：本项目会议决策、初始目录现状、当前目标描述
## Common Failure Modes
- 直接把会议长文交给实现 agent
- `CLAUDE.md` 没有写明禁用项和例外接口
- 初始化时就允许多个技术轨道并存

59
cc-switch-dev-workflow/references/knowledge-base/workflows/stage-1-research.md 普通文件
查看文件

@@ -0,0 +1,59 @@
# Workflow: Stage 1 Research
## Purpose
将参考仓库和现有材料压缩为可复用的调研报告，而不是把一堆链接直接传入 Spec 阶段。
## When to Use
- 技术方案还没稳定
- 需要对比多个参考实现
- 老项目要补设计哲学和边界时
## Inputs
- `.references/`
- 目标能力说明
- `CLAUDE.md`
- 已清洗会议纪要
## Outputs
- `ANALYSIS.md`
- `TODO.yaml`
- `.research/*.md`
## Primary Agent/Model
计划 agent + `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
研究 agent + `Claude Opus 4.6`
## Required Skills
- 若已安装可选：`research-analyzing`, `research-tasking`, `research-writing`
- fallback：使用本知识库模板手工生成同等产物
## Steps
1. 研究 agent 并行阅读参考仓库，按主题切片。
2. 计划 agent 生成 `ANALYSIS.md`，定义调研主题、优先级和输出路径。
3. 生成 `TODO.yaml`，每个任务只对应一个调研主题。
4. 产出 `.research/*.md`，记录实现方式、优缺点、可采纳与不可采纳项。
5. 对研究产物做一次压缩 handoff，再进入 Spec。
## Exit Criteria
- `.research/*.md` 足够支持 Spec 编写
- 调研结论已按主题拆分，不再依赖原始参考仓库浏览记录
## Failure Recovery
- 如果研究报告开始夹带具体实现计划，拆回“事实”和“决策建议”
- 如果调研范围失控，删去与当前项目目标无关的主题
## Related Templates
- [`../templates/analysis-template.md`](../templates/analysis-template.md)
- [`../templates/todo-yaml-template.md`](../templates/todo-yaml-template.md)
- [`../templates/agent-handoff-template.md`](../templates/agent-handoff-template.md)
## Stable Knowledge Vs Runtime Context
- 稳定知识：参考筛选标准、调研报告结构、任务自包含规则
- 运行时上下文：这轮参考仓库、这轮目标能力、这轮发现的设计取舍
## Common Failure Modes
- 只收集链接，不形成 `.research/*.md`
- 研究 agent 直接替代 Spec 决策
- 一份报告塞太多主题，导致后续不可引用

62
cc-switch-dev-workflow/references/knowledge-base/workflows/stage-2-spec.md 普通文件
查看文件

@@ -0,0 +1,62 @@
# Workflow: Stage 2 Spec
## Purpose
把调研结论和业务需求固化为 `SPECS/*.md`，并通过自动审查和人工审核形成实施前门禁。
## When to Use
- 调研已经足够支持决策时
- 维护项目需要补规范时
- 实施前需要冻结系统契约时
## Inputs
- `.research/*.md`
- 业务需求
- `CLAUDE.md`
- 现有代码库
## Outputs
- `ANALYSIS.md`
- `TODO.yaml`
- `SPECS/*.md`
- 审查结论与人工确认
## Primary Agent/Model
计划 agent + `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
审查 agent + `Claude Opus 4.6`
## Required Skills
- `spec-tasking`
- `spec-reviewing`
- 若已安装可选：`spec-analyzing`, `spec-writing`
## Steps
1. 计划 agent 识别模块边界、接口契约和行为约束。
2. 使用 `spec-tasking` 或等价模板生成 Spec 任务。
3. 逐份产出 `SPECS/*.md`。
4. 用 `spec-reviewing` 做结构、语义、过度设计和跨 Spec 一致性审查。
5. 人工逐份审核，未通过不得进入 Code。
## Exit Criteria
- `SPECS/*.md` 已覆盖系统契约
- 自动审查通过
- 人工逐份确认通过
## Failure Recovery
- 如果 Spec 之间术语冲突，先做术语对齐，再继续扩写
- 如果人工审核提出范围错误，回到 Research 或 Setup，不做带病实施
## Related Templates
- [`../templates/spec-template.md`](../templates/spec-template.md)
- [`../templates/todo-yaml-template.md`](../templates/todo-yaml-template.md)
- [`../templates/acceptance-checklist-template.md`](../templates/acceptance-checklist-template.md)
## Stable Knowledge Vs Runtime Context
- 稳定知识：Spec 章节结构、内容边界、Forbidden 写法、SSOT 原则
- 运行时上下文：当前业务需求、当前模块划分、当前调研结论
## Common Failure Modes
- Spec 混入教程、背景或实现细节
- 没有人工审核就直接进入 Code
- 一份 Spec 负责多个不相关领域

65
cc-switch-dev-workflow/references/knowledge-base/workflows/stage-3-code.md 普通文件
查看文件

@@ -0,0 +1,65 @@
# Workflow: Stage 3 Code
## Purpose
按 Spec 实施代码和测试，用 `Plan -> Implement -> Simplify -> Refactor` 节奏控制代码质量和任务颗粒度。
## When to Use
- `SPECS/*.md` 已经通过人工审核
- 需要首次落地实现时
- 需要把大模块拆成可执行任务时
## Inputs
- `SPECS/*.md`
- `CLAUDE.md`
- 现有代码库
- `.research/*.md`
## Outputs
- `ANALYSIS.md`
- `TODO.yaml`
- `.plans/*.md`
- 代码与测试
## Primary Agent/Model
实现 agent + `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
审查 agent + `Claude Opus 4.6`
## Required Skills
- `spec-implementing-analyzing`
- `spec-implementing-tasking`
- `tdd-planning`
- `tdd-implementing`
- `code-simplifying`
- `code-refactoring`
- `architecture-audit`
## Steps
1. 生成实施分析，明确模块顺序和复杂度。
2. 生成 `TODO.yaml`，复杂任务走 `Plan + Impl`，简单任务直接执行。
3. 实现 agent 按 `.plans/*.md` 做 TDD 实施。
4. 每次实现后立即运行 `code-simplifying`。
5. 每完成一批任务做 `code-refactoring`，必要时做 `architecture-audit`。
## Exit Criteria
- 当前范围内的 Spec 条款已有实现和测试
- 刚新增代码已被简化
- 批次级重构已完成
## Failure Recovery
- 如果实现 agent不再引用 Spec，停止执行并重建 plan
- 如果任务标题不能独立执行，回到 tasking 重写 `TODO.yaml`
## Related Templates
- [`../templates/tdd-plan-template.md`](../templates/tdd-plan-template.md)
- [`../templates/todo-yaml-template.md`](../templates/todo-yaml-template.md)
## Stable Knowledge Vs Runtime Context
- 稳定知识：TDD 节奏、任务自包含规则、每 4 个类别检查点
- 运行时上下文：当前模块现状、当前差异、当前测试反馈
## Common Failure Modes
- 跳过 `tdd-planning` 直接改复杂模块
- 实施后不简化，技术债直接累积
- 实现 agent 顺手修改无关模块

64
cc-switch-dev-workflow/references/knowledge-base/workflows/stage-4-alignment.md 普通文件
查看文件

@@ -0,0 +1,64 @@
# Workflow: Stage 4 Alignment
## Purpose
识别并补齐 `SPECS/*.md` 与实现代码之间的缺口，解决遗漏、偏离、未测试和集成断层。
## When to Use
- Code 阶段完成后
- 人工或审查 agent 发现 Spec 与代码不一致时
- 验收前需要做缺口收敛时
## Inputs
- `SPECS/*.md`
- 现有代码库
- 既有 `.plans/*.md`
- 测试报告
## Outputs
- `ANALYSIS.md`
- `TODO.yaml`
- 新的 `.plans/*.md`
- 缺口补齐后的代码与测试
## Primary Agent/Model
计划/实现 agent + `GPT-5.4 Pro xhigh`
## Secondary Agent/Model
审查 agent + `Claude Opus 4.6`
## Required Skills
- `spec-gap-analyzing`
- `spec-gap-tasking`
- `tdd-planning`
- `tdd-implementing`
- `code-simplifying`
- `code-refactoring`
## Steps
1. 用 `spec-gap-analyzing` 对照 Spec 和代码，识别缺口类型。
2. 用 `spec-gap-tasking` 生成 Plan/Impl 对和质量检查点。
3. 实施 agent 补齐缺口，随后立即简化。
4. 每 4 个类别做一次重构检查点。
5. 产出新的 handoff，决定是否进入 Refinement 或回到 Code。
## Exit Criteria
- 已知缺口均有处理结果
- 缺口补齐不再依赖口头说明
- 新增实现已有测试和简化
## Failure Recovery
- 如果缺口分析发现 Spec 本身有问题，回到 Spec 阶段修正
- 如果 Alignment 开始演变成大规模新需求开发，拆回 Code 或 Spec
## Related Templates
- [`../templates/tdd-plan-template.md`](../templates/tdd-plan-template.md)
- [`../templates/todo-yaml-template.md`](../templates/todo-yaml-template.md)
## Stable Knowledge Vs Runtime Context
- 稳定知识：Gap 分类、Plan/Impl 对、检查点节奏
- 运行时上下文：当前缺口列表、当前差异证据、当前测试覆盖情况
## Common Failure Modes
- 直接根据感觉补代码，不先做缺口分析
- 把 Spec 错误当成代码错误硬补实现
- 补齐后不做简化和重构

62
cc-switch-dev-workflow/references/knowledge-base/workflows/stage-5-refinement.md 普通文件
查看文件

@@ -0,0 +1,62 @@
# Workflow: Stage 5 Refinement
## Purpose
对完整代码库做全局质量收敛，为验收和交付做准备。
## When to Use
- Code 和 Alignment 都完成后
- 准备发布、开源或长期维护前
- 技术债明显累积时
## Inputs
- 完整代码库
- `SPECS/*.md`
- 测试覆盖结果
## Outputs
- 简化后的代码
- 重构计划
- 可选的模块化和结构重组计划
- 架构审计结果
## Primary Agent/Model
审查 agent + `Claude Opus 4.6`
## Secondary Agent/Model
实现 agent + `GPT-5.4 Pro xhigh`
## Required Skills
- `code-simplifying`
- `code-refactoring`
- `code-modularizing`
- `code-restructuring`
- `architecture-audit`
## Steps
1. 先全局运行 `code-simplifying`。
2. 再运行 `code-refactoring`，把最近和全库的结构问题收敛。
3. 只有在需要时才做 `code-modularizing` 或 `code-restructuring`。
4. 对准备交付的项目做 `architecture-audit`。
5. 输出最终质量结论，供 Acceptance 使用。
## Exit Criteria
- 基础优化已完成
- 需要的结构类改进已经完成或明确延期
- 架构级高风险问题已收敛或有明确残留记录
## Failure Recovery
- 如果优化阶段开始新增功能，立即停回 Code 或 Alignment
- 如果模块化或重组没有真实收益，停在基础优化层级即可
## Related Templates
- [`../templates/acceptance-checklist-template.md`](../templates/acceptance-checklist-template.md)
- [`../templates/agent-handoff-template.md`](../templates/agent-handoff-template.md)
## Stable Knowledge Vs Runtime Context
- 稳定知识：优化层级、何时做模块化、何时做结构重组
- 运行时上下文：当前代码库病灶、当前指标、当前残留风险
## Common Failure Modes
- 把 `Refinement` 当成功能阶段继续扩 scope
- 在没有测试托底的情况下大规模重构
- 对所有项目默认做最重的结构重组

57
cc-switch-dev-workflow/references/knowledge-base/workflows/stage-6-acceptance.md 普通文件
查看文件

@@ -0,0 +1,57 @@
# Workflow: Stage 6 Acceptance
## Purpose
由人主导做最终质量确认，决定交付、回退还是继续收敛。
## When to Use
- Refinement 完成后
- 准备合并、发布、交付前
- 需要对残留风险做明确判断时
## Inputs
- 优化后的代码库
- `SPECS/*.md`
- 测试结果
- 重构与架构审计结论
## Outputs
- 验收结论
- 回退建议或发布建议
- 残留风险记录
## Primary Agent/Model
人工主导
## Secondary Agent/Model
`Claude Opus 4.6`
## Required Skills
- 无强制 skill；允许用模板辅助整理
## Steps
1. 人工按验收清单逐项检查功能、测试、文档和代码质量。
2. 对严重问题回退到 Alignment 或 Code。
3. 对中等问题当场修复或记录为发布前阻塞项。
4. 对轻微问题记录为后续 TODO。
5. 通过后再做发布和交付动作。
## Exit Criteria
- 人工明确签收
- 严重问题已清零
- 残留问题有明确等级和去向
## Failure Recovery
- 如果验收仍依赖“感觉差不多”，回到模板化检查表
- 如果发现核心流程未覆盖，回到 Alignment 而不是现场打补丁
## Related Templates
- [`../templates/acceptance-checklist-template.md`](../templates/acceptance-checklist-template.md)
## Stable Knowledge Vs Runtime Context
- 稳定知识：验收维度和问题分级方式
- 运行时上下文：本次发布范围、本次残留风险、本次测试结论
## Common Failure Modes
- 把 Acceptance 外包给自动化
- 严重问题被降级成“后续再说”
- 没有记录残留风险就直接发布

56
cc-switch-dev-workflow/references/local-cc-switch-runtime.md 普通文件
查看文件

@@ -0,0 +1,56 @@
# Local CC Switch Runtime Snapshot
## Snapshot Date
`2026-03-26`
## Purpose
记录当前机器上 `~/.cc-switch` 的安全摘要，作为这个 workflow skill 的默认运行时对齐参考。这个文件不是长期规范本身；高风险任务开始前，优先重新读取本机实时配置。
## Paths
- Root: `~/.cc-switch`
- App settings: `~/.cc-switch/settings.json`
- Database: `~/.cc-switch/cc-switch.db`
- Skills: `~/.cc-switch/skills`
## Current Safe Summary
- App language: `zh`
- Skill sync: `auto`
- Current Claude provider id: `54f3da6d-68f7-42bc-8f99-2d6ceda7facd`
- Current Codex provider id: `f616abe7-f145-4453-8f19-86662e48d811`
## Current Provider Alignment
- Codex provider: `H3`
- Codex model: `gpt-5.4-pro`
- Codex reasoning: `xhigh`
- Codex base host: `sub2.de5.net`
- Codex multi-agent: `not explicitly enabled`
- Claude provider: `Bobbing`
- Claude default opus: `claude-opus-4-6`
- Claude base host: `bobdong.cn`
- Fallback pool present: `GLM / Kimi / Minimax`
## Current Inventory
- Skills in database: `9`
- Skills on disk: `9`
- Enabled skill repos: `5`
- MCP servers: `1`
- Known MCP server: `playwright` enabled for Codex
## Operational Implication
- 当前本机在模型主路径上与知识库一致，但 `multi-agent` 标记没有显式打开，属于一个需要人工确认的偏差。
- 研究、计划、结构化文档和复杂推演可以默认走 `GPT-5.4 Pro xhigh`。
- 长文档消化、Spec 审读和第二视角复核可以默认走 `Claude Opus 4.6`。
- 遇到主模型受限场景，可以受控地切换到 `GLM / Kimi / Minimax`，但结果必须压缩回 handoff。
## Safety Note
- 这里故意不记录原始 API key、完整 provider `settings_config` 或数据库里的敏感字段。
- 如果你需要实时摘要，运行 `python3 scripts/inspect_cc_switch_runtime.py --format markdown`。
- 如果用户明确要求把内部 token 固化到私有仓库，先在提交说明里标明用途和作用域。

90
cc-switch-dev-workflow/scripts/bootstrap_workflow_workspace.py 可执行文件
查看文件

@@ -0,0 +1,90 @@
#!/usr/bin/env python3
"""Seed a target project with the workflow's standard files and directories."""
from __future__ import annotations
import argparse
import json
import shutil
from datetime import datetime, timezone
from pathlib import Path
PLAYBOOK_FILES = {
"new-project-from-scaffold": "new-project-from-scaffold.md",
"existing-project-spec-backfill-and-refactor": "existing-project-spec-backfill-and-refactor.md",
"spec-code-alignment-gap-closure": "spec-code-alignment-gap-closure.md",
}
def copy_file(source: Path, target: Path, force: bool) -> str:
if target.exists() and not force:
return f"skip {target}"
target.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(source, target)
return f"write {target}"
def main() -> int:
parser = argparse.ArgumentParser(description="Bootstrap a repo with the CC Switch workflow files.")
parser.add_argument("--target-dir", required=True, help="Absolute or relative project directory to seed.")
parser.add_argument("--playbook", required=True, choices=sorted(PLAYBOOK_FILES))
parser.add_argument("--force", action="store_true", help="Overwrite existing files.")
args = parser.parse_args()
skill_root = Path(__file__).resolve().parent.parent
knowledge_base = skill_root / "references" / "knowledge-base"
templates_root = knowledge_base / "templates"
playbooks_root = knowledge_base / "playbooks"
workflows_root = knowledge_base / "workflows"
target_dir = Path(args.target_dir).expanduser().resolve()
required_dirs = [
target_dir / ".meetings",
target_dir / ".research",
target_dir / ".plans",
target_dir / ".handoff",
target_dir / ".acceptance",
target_dir / ".workflow",
target_dir / ".decisions",
target_dir / "SPECS",
]
for directory in required_dirs:
directory.mkdir(parents=True, exist_ok=True)
writes = []
template_map = {
templates_root / "claude-md-template.md": target_dir / "CLAUDE.md",
templates_root / "analysis-template.md": target_dir / "ANALYSIS.md",
templates_root / "todo-yaml-template.md": target_dir / "TODO.yaml",
templates_root / "spec-template.md": target_dir / "SPECS" / "_template.md",
templates_root / "tdd-plan-template.md": target_dir / ".plans" / "_tdd-plan-template.md",
templates_root / "agent-handoff-template.md": target_dir / ".handoff" / "_agent-handoff-template.md",
templates_root / "acceptance-checklist-template.md": target_dir / ".acceptance" / "_acceptance-checklist.md",
playbooks_root / PLAYBOOK_FILES[args.playbook]: target_dir / ".workflow" / "selected-playbook.md",
workflows_root / "README.md": target_dir / ".workflow" / "stage-index.md",
knowledge_base / "README.md": target_dir / ".workflow" / "knowledge-base-overview.md",
}
for source, target in template_map.items():
writes.append(copy_file(source, target, args.force))
manifest = {
"skill": "cc-switch-dev-workflow",
"playbook": args.playbook,
"generated_at": datetime.now(timezone.utc).isoformat(),
"target_dir": str(target_dir),
}
manifest_path = target_dir / ".workflow" / "bootstrap-manifest.json"
if not manifest_path.exists() or args.force:
manifest_path.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
writes.append(f"write {manifest_path}")
else:
writes.append(f"skip {manifest_path}")
print("\n".join(writes))
return 0
if __name__ == "__main__":
raise SystemExit(main())

286
cc-switch-dev-workflow/scripts/inspect_cc_switch_runtime.py 可执行文件
查看文件

@@ -0,0 +1,286 @@
#!/usr/bin/env python3
"""Summarize the local CC Switch runtime without exposing raw secrets."""
from __future__ import annotations
import argparse
import json
import re
import sqlite3
from pathlib import Path
from typing import Any
from urllib.parse import urlparse
def safe_json_load(path: Path) -> dict[str, Any]:
if not path.exists():
return {}
try:
return json.loads(path.read_text(encoding="utf-8"))
except json.JSONDecodeError:
return {}
def safe_json_parse(raw: str | None) -> dict[str, Any]:
if not raw:
return {}
try:
parsed = json.loads(raw)
except json.JSONDecodeError:
return {}
return parsed if isinstance(parsed, dict) else {}
def extract_toml_string(config_text: str, key: str) -> str | None:
match = re.search(rf'{re.escape(key)}\s*=\s*"([^"]+)"', config_text)
return match.group(1) if match else None
def extract_toml_bool(config_text: str, key: str) -> bool | None:
match = re.search(rf"{re.escape(key)}\s*=\s*(true|false)", config_text)
if not match:
return None
return match.group(1) == "true"
def extract_host(raw_url: str | None) -> str | None:
if not raw_url:
return None
parsed = urlparse(raw_url)
return parsed.netloc or raw_url
def count_regex(config_text: str, pattern: str) -> int:
return len(re.findall(pattern, config_text))
def sqlite_rows(db_path: Path, sql: str) -> list[dict[str, Any]]:
if not db_path.exists():
return []
conn = sqlite3.connect(db_path)
conn.row_factory = sqlite3.Row
try:
rows = conn.execute(sql).fetchall()
return [dict(row) for row in rows]
finally:
conn.close()
def summarize_codex_provider(row: dict[str, Any], endpoint_rows: list[dict[str, Any]]) -> dict[str, Any]:
parsed = safe_json_parse(row.get("settings_config"))
config_text = parsed.get("config", "")
endpoint = next(
(
item["url"]
for item in endpoint_rows
if item["provider_id"] == row["id"] and item["app_type"] == row["app_type"]
),
None,
)
return {
"id": row["id"],
"name": row["name"],
"endpoint_host": extract_host(endpoint or extract_toml_string(config_text, "base_url")),
"model": extract_toml_string(config_text, "model"),
"reasoning_effort": extract_toml_string(config_text, "model_reasoning_effort"),
"model_provider": extract_toml_string(config_text, "model_provider"),
"personality": extract_toml_string(config_text, "personality"),
"multi_agent_enabled": extract_toml_bool(config_text, "multi_agent"),
"trusted_project_count": count_regex(config_text, r'\[projects\."[^"]+"\]'),
"embedded_mcp_server_count": count_regex(config_text, r"\[mcp_servers\.[^\]]+\]"),
"embedded_skill_config_count": count_regex(config_text, r"\[\[skills\.config\]\]"),
}
def summarize_claude_provider(row: dict[str, Any], endpoint_rows: list[dict[str, Any]]) -> dict[str, Any]:
parsed = safe_json_parse(row.get("settings_config"))
env = parsed.get("env", {})
permissions = parsed.get("permissions", {})
endpoint = next(
(
item["url"]
for item in endpoint_rows
if item["provider_id"] == row["id"] and item["app_type"] == row["app_type"]
),
None,
)
allow_list = permissions.get("allow", []) if isinstance(permissions, dict) else []
return {
"id": row["id"],
"name": row["name"],
"endpoint_host": extract_host(endpoint or env.get("ANTHROPIC_BASE_URL")),
"current_model": env.get("ANTHROPIC_MODEL"),
"default_opus_model": env.get("ANTHROPIC_DEFAULT_OPUS_MODEL"),
"default_sonnet_model": env.get("ANTHROPIC_DEFAULT_SONNET_MODEL"),
"default_haiku_model": env.get("ANTHROPIC_DEFAULT_HAIKU_MODEL"),
"reasoning_model": env.get("ANTHROPIC_REASONING_MODEL"),
"allow_count": len(allow_list),
}
def fallback_flags(rows: list[dict[str, Any]]) -> dict[str, bool]:
haystack = "\n".join(
f"{row.get('name', '')} {row.get('settings_config', '')}".lower() for row in rows
)
return {
"glm": "glm" in haystack,
"kimi": "kimi" in haystack,
"minimax": "minimax" in haystack,
}
def collect_summary(root: Path) -> dict[str, Any]:
settings_path = root / "settings.json"
db_path = root / "cc-switch.db"
skills_root = root / "skills"
app_settings = safe_json_load(settings_path)
provider_rows = sqlite_rows(
db_path,
"select id,app_type,name,settings_config,is_current,provider_type from providers order by app_type,name;",
)
endpoint_rows = sqlite_rows(
db_path,
"select provider_id,app_type,url from provider_endpoints order by app_type,provider_id,url;",
)
skill_rows = sqlite_rows(
db_path,
"select id,name,directory,repo_owner,repo_name,repo_branch,enabled_claude,enabled_codex,enabled_opencode from skills order by name;",
)
skill_repo_rows = sqlite_rows(
db_path,
"select owner,name,branch,enabled from skill_repos order by owner,name;",
)
mcp_rows = sqlite_rows(
db_path,
"select id,name,server_config,enabled_claude,enabled_codex from mcp_servers order by name;",
)
current_codex = next((row for row in provider_rows if row["app_type"] == "codex" and row["is_current"] == 1), None)
current_claude = next((row for row in provider_rows if row["app_type"] == "claude" and row["is_current"] == 1), None)
codex_summary = summarize_codex_provider(current_codex, endpoint_rows) if current_codex else None
claude_summary = summarize_claude_provider(current_claude, endpoint_rows) if current_claude else None
fallback = fallback_flags([row for row in provider_rows if row["app_type"] in {"claude", "opencode"}])
mcp_servers = []
for row in mcp_rows:
parsed = safe_json_parse(row.get("server_config"))
mcp_servers.append(
{
"id": row["id"],
"name": row["name"],
"type": parsed.get("type", "http" if parsed.get("url") else "unknown"),
"command": parsed.get("command"),
"endpoint_host": extract_host(parsed.get("url")),
"enabled_codex": bool(row.get("enabled_codex")),
"enabled_claude": bool(row.get("enabled_claude")),
}
)
local_skill_count = 0
if skills_root.exists():
local_skill_count = sum(1 for entry in skills_root.iterdir() if entry.is_dir())
return {
"root": str(root),
"exists": root.exists(),
"app_settings": {
"language": app_settings.get("language"),
"current_provider_claude": app_settings.get("currentProviderClaude"),
"current_provider_codex": app_settings.get("currentProviderCodex"),
"skill_sync_method": app_settings.get("skillSyncMethod"),
},
"current_providers": {
"codex": codex_summary,
"claude": claude_summary,
},
"skills": {
"database_count": len(skill_rows),
"local_directory_count": local_skill_count,
"codex_enabled_count": sum(bool(row["enabled_codex"]) for row in skill_rows),
"claude_enabled_count": sum(bool(row["enabled_claude"]) for row in skill_rows),
"opencode_enabled_count": sum(bool(row["enabled_opencode"]) for row in skill_rows),
"names": [row["name"] for row in skill_rows],
},
"skill_repos": [
{
"owner": row["owner"],
"name": row["name"],
"branch": row["branch"],
"enabled": bool(row["enabled"]),
}
for row in skill_repo_rows
],
"mcp_servers": mcp_servers,
"fallback_providers": fallback,
"alignment": {
"codex_primary": bool(
codex_summary
and codex_summary.get("model") == "gpt-5.4-pro"
and codex_summary.get("reasoning_effort") == "xhigh"
),
"claude_secondary": bool(
claude_summary and claude_summary.get("default_opus_model") == "claude-opus-4-6"
),
"multi_agent": bool(codex_summary and codex_summary.get("multi_agent_enabled") is True),
"fallback_pool": all(fallback.values()),
},
}
def to_markdown(summary: dict[str, Any]) -> str:
codex = summary["current_providers"]["codex"] or {}
claude = summary["current_providers"]["claude"] or {}
lines = [
"# CC Switch Runtime Summary",
"",
f"- Root: `{summary['root']}`",
f"- Language: `{summary['app_settings'].get('language')}`",
f"- Skill sync: `{summary['app_settings'].get('skill_sync_method')}`",
"",
"## Current Providers",
"",
f"- Codex provider: `{codex.get('name')}`",
f"- Codex model: `{codex.get('model')}`",
f"- Codex reasoning: `{codex.get('reasoning_effort')}`",
f"- Codex base host: `{codex.get('endpoint_host')}`",
f"- Codex multi-agent: `{codex.get('multi_agent_enabled')}`",
f"- Claude provider: `{claude.get('name')}`",
f"- Claude default opus: `{claude.get('default_opus_model')}`",
f"- Claude base host: `{claude.get('endpoint_host')}`",
"",
"## Alignment",
"",
f"- Codex primary aligned: `{summary['alignment']['codex_primary']}`",
f"- Claude secondary aligned: `{summary['alignment']['claude_secondary']}`",
f"- Multi-agent aligned: `{summary['alignment']['multi_agent']}`",
f"- Fallback pool aligned: `{summary['alignment']['fallback_pool']}`",
"",
"## Inventory",
"",
f"- Skills in DB: `{summary['skills']['database_count']}`",
f"- Skills on disk: `{summary['skills']['local_directory_count']}`",
f"- Skill repos: `{len(summary['skill_repos'])}`",
f"- MCP servers: `{len(summary['mcp_servers'])}`",
f"- Installed skills: {', '.join(summary['skills']['names']) or 'n/a'}",
]
return "\n".join(lines) + "\n"
def main() -> int:
parser = argparse.ArgumentParser(description="Inspect local CC Switch runtime without printing secrets.")
parser.add_argument("--root", default=str(Path.home() / ".cc-switch"))
parser.add_argument("--format", choices=("json", "markdown"), default="json")
args = parser.parse_args()
summary = collect_summary(Path(args.root).expanduser())
if args.format == "markdown":
print(to_markdown(summary), end="")
else:
print(json.dumps(summary, indent=2, ensure_ascii=False))
return 0
if __name__ == "__main__":
raise SystemExit(main())