Add cc-switch-dev-workflow skill

2026-03-26 00:27:17 -07:00
--- a/cc-switch-dev-workflow/references/knowledge-base/playbooks/existing-project-spec-backfill-and-refactor.md
+++ b/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 后的结构与命名更清晰，不是更复杂
--- a/cc-switch-dev-workflow/references/knowledge-base/playbooks/new-project-from-scaffold.md
+++ b/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 已经形成闭环
--- a/cc-switch-dev-workflow/references/knowledge-base/playbooks/spec-code-alignment-gap-closure.md
+++ b/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 的遵守
+- 关键流程已有测试托底