Add cc-switch-dev-workflow skill

2026-03-26 00:27:17 -07:00
--- a/cc-switch-dev-workflow/references/knowledge-base/workflows/README.md
+++ b/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
--- a/cc-switch-dev-workflow/references/knowledge-base/workflows/stage-0-setup.md
+++ b/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` 没有写明禁用项和例外接口
+- 初始化时就允许多个技术轨道并存
--- a/cc-switch-dev-workflow/references/knowledge-base/workflows/stage-1-research.md
+++ b/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 决策
+- 一份报告塞太多主题，导致后续不可引用
--- a/cc-switch-dev-workflow/references/knowledge-base/workflows/stage-2-spec.md
+++ b/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 负责多个不相关领域
--- a/cc-switch-dev-workflow/references/knowledge-base/workflows/stage-3-code.md
+++ b/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 顺手修改无关模块
--- a/cc-switch-dev-workflow/references/knowledge-base/workflows/stage-4-alignment.md
+++ b/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 错误当成代码错误硬补实现
+- 补齐后不做简化和重构
--- a/cc-switch-dev-workflow/references/knowledge-base/workflows/stage-5-refinement.md
+++ b/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
+- 在没有测试托底的情况下大规模重构
+- 对所有项目默认做最重的结构重组
--- a/cc-switch-dev-workflow/references/knowledge-base/workflows/stage-6-acceptance.md
+++ b/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 外包给自动化
+- 严重问题被降级成“后续再说”
+- 没有记录残留风险就直接发布