Add cc-switch-dev-workflow skill

2026-03-26 00:27:17 -07:00
--- a/cc-switch-dev-workflow/references/knowledge-base/foundations/context-engineering.md
+++ b/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。
--- a/cc-switch-dev-workflow/references/knowledge-base/foundations/human-agent-boundaries.md
+++ b/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 校验、重构建议和第二视角复核
--- a/cc-switch-dev-workflow/references/knowledge-base/foundations/refactoring-and-gap-closure.md
+++ b/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` 用来掩盖前面没有对齐好的问题
--- a/cc-switch-dev-workflow/references/knowledge-base/foundations/reliability-and-convergence.md
+++ b/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
+- 所有阶段都要留下高密度产物，便于下一阶段在更干净的上下文中执行。
+- 任何“先实现，后面再说”的做法，都会把偏差拖到更昂贵的阶段。
--- a/cc-switch-dev-workflow/references/knowledge-base/foundations/spec-driven-development.md
+++ b/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 的自由度发生在正确层级。
+- 高层只定义目标和边界，低层才决定具体实现细节。
+- 这样既防止模型随机发挥，也不把高层误判强行塞进代码。