From dcb2a10ad83d6ba845ba25b2893dea6af8221d4c Mon Sep 17 00:00:00 2001 From: X Date: Thu, 26 Mar 2026 00:27:17 -0700 Subject: [PATCH] Add cc-switch-dev-workflow skill --- README.md | 18 ++ cc-switch-dev-workflow/SKILL.md | 137 +++++++++ cc-switch-dev-workflow/agents/openai.yaml | 4 + .../references/knowledge-base/README.md | 103 +++++++ ...-2026-03-21-model-routing-and-fallbacks.md | 63 ++++ ...urce-precedence-and-conflict-resolution.md | 62 ++++ ...1-stack-whitelist-and-exception-process.md | 65 ++++ .../knowledge-base/decisions/README.md | 46 +++ .../foundations/context-engineering.md | 60 ++++ .../foundations/human-agent-boundaries.md | 60 ++++ .../refactoring-and-gap-closure.md | 68 +++++ .../reliability-and-convergence.md | 66 ++++ .../foundations/spec-driven-development.md | 78 +++++ .../orchestration/agent-handoff-contract.md | 52 ++++ .../cc-switch-operating-model.md | 77 +++++ .../platform/framework-decision-matrix.md | 71 +++++ .../platform/model-routing-policy.md | 69 +++++ .../knowledge-base/platform/stack-policy.md | 82 +++++ ...ting-project-spec-backfill-and-refactor.md | 87 ++++++ .../playbooks/new-project-from-scaffold.md | 90 ++++++ .../spec-code-alignment-gap-closure.md | 88 ++++++ .../2026-02-02-ralphy-task-list-flow.md | 65 ++++ .../2026-03-04-ai-pipeline-reliability.md | 75 +++++ .../2026-03-06-spec-driven-workflow.md | 77 +++++ .../knowledge-base/sources/README.md | 75 +++++ .../sources/skills-zip-digest.md | 78 +++++ .../sources/workflow-zip-digest.md | 66 ++++ .../knowledge-base/templates/README.md | 53 ++++ .../acceptance-checklist-template.md | 70 +++++ .../templates/agent-handoff-template.md | 68 +++++ .../templates/analysis-template.md | 78 +++++ .../templates/claude-md-template.md | 93 ++++++ .../knowledge-base/templates/spec-template.md | 70 +++++ .../templates/tdd-plan-template.md | 87 ++++++ .../templates/todo-yaml-template.md | 68 +++++ .../knowledge-base/workflows/README.md | 63 ++++ .../knowledge-base/workflows/stage-0-setup.md | 60 ++++ .../workflows/stage-1-research.md | 59 ++++ .../knowledge-base/workflows/stage-2-spec.md | 62 ++++ .../knowledge-base/workflows/stage-3-code.md | 65 ++++ .../workflows/stage-4-alignment.md | 64 ++++ .../workflows/stage-5-refinement.md | 62 ++++ .../workflows/stage-6-acceptance.md | 57 ++++ .../references/local-cc-switch-runtime.md | 56 ++++ .../scripts/bootstrap_workflow_workspace.py | 90 ++++++ .../scripts/inspect_cc_switch_runtime.py | 286 ++++++++++++++++++ 46 files changed, 3393 insertions(+) create mode 100644 cc-switch-dev-workflow/SKILL.md create mode 100644 cc-switch-dev-workflow/agents/openai.yaml create mode 100644 cc-switch-dev-workflow/references/knowledge-base/README.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/decisions/ADR-2026-03-21-model-routing-and-fallbacks.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/decisions/ADR-2026-03-21-source-precedence-and-conflict-resolution.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/decisions/ADR-2026-03-21-stack-whitelist-and-exception-process.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/decisions/README.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/foundations/context-engineering.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/foundations/human-agent-boundaries.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/foundations/refactoring-and-gap-closure.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/foundations/reliability-and-convergence.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/foundations/spec-driven-development.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/orchestration/agent-handoff-contract.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/orchestration/cc-switch-operating-model.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/platform/framework-decision-matrix.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/platform/model-routing-policy.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/platform/stack-policy.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/playbooks/existing-project-spec-backfill-and-refactor.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/playbooks/new-project-from-scaffold.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/playbooks/spec-code-alignment-gap-closure.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/sources/2026-02-02-ralphy-task-list-flow.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/sources/2026-03-04-ai-pipeline-reliability.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/sources/2026-03-06-spec-driven-workflow.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/sources/README.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/sources/skills-zip-digest.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/sources/workflow-zip-digest.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/templates/README.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/templates/acceptance-checklist-template.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/templates/agent-handoff-template.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/templates/analysis-template.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/templates/claude-md-template.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/templates/spec-template.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/templates/tdd-plan-template.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/templates/todo-yaml-template.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/workflows/README.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/workflows/stage-0-setup.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/workflows/stage-1-research.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/workflows/stage-2-spec.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/workflows/stage-3-code.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/workflows/stage-4-alignment.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/workflows/stage-5-refinement.md create mode 100644 cc-switch-dev-workflow/references/knowledge-base/workflows/stage-6-acceptance.md create mode 100644 cc-switch-dev-workflow/references/local-cc-switch-runtime.md create mode 100755 cc-switch-dev-workflow/scripts/bootstrap_workflow_workspace.py create mode 100755 cc-switch-dev-workflow/scripts/inspect_cc_switch_runtime.py diff --git a/README.md b/README.md index 7fd8681..2509cd6 100644 --- a/README.md +++ b/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` 字段和用途一致 diff --git a/cc-switch-dev-workflow/SKILL.md b/cc-switch-dev-workflow/SKILL.md new file mode 100644 index 0000000..025309c --- /dev/null +++ b/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 当作最后可有可无的装饰步骤。 diff --git a/cc-switch-dev-workflow/agents/openai.yaml b/cc-switch-dev-workflow/agents/openai.yaml new file mode 100644 index 0000000..07f3577 --- /dev/null +++ b/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." diff --git a/cc-switch-dev-workflow/references/knowledge-base/README.md b/cc-switch-dev-workflow/references/knowledge-base/README.md new file mode 100644 index 0000000..b6fdf7a --- /dev/null +++ b/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)。 diff --git a/cc-switch-dev-workflow/references/knowledge-base/decisions/ADR-2026-03-21-model-routing-and-fallbacks.md b/cc-switch-dev-workflow/references/knowledge-base/decisions/ADR-2026-03-21-model-routing-and-fallbacks.md new file mode 100644 index 0000000..6e4e4a1 --- /dev/null +++ b/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 +- 主模型能力或成本结构显著变化 +- 团队引入新的主编排系统 diff --git a/cc-switch-dev-workflow/references/knowledge-base/decisions/ADR-2026-03-21-source-precedence-and-conflict-resolution.md b/cc-switch-dev-workflow/references/knowledge-base/decisions/ADR-2026-03-21-source-precedence-and-conflict-resolution.md new file mode 100644 index 0000000..0c4ca87 --- /dev/null +++ b/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 +- 新一轮会议整理文档替代现有原则层 +- 新技能包改变了关键执行结构 diff --git a/cc-switch-dev-workflow/references/knowledge-base/decisions/ADR-2026-03-21-stack-whitelist-and-exception-process.md b/cc-switch-dev-workflow/references/knowledge-base/decisions/ADR-2026-03-21-stack-whitelist-and-exception-process.md new file mode 100644 index 0000000..02f647f --- /dev/null +++ b/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 +- 团队默认栈发生正式变更 +- 某个白名单组件长期无法满足主流项目需求 diff --git a/cc-switch-dev-workflow/references/knowledge-base/decisions/README.md b/cc-switch-dev-workflow/references/knowledge-base/decisions/README.md new file mode 100644 index 0000000..40840a8 --- /dev/null +++ b/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) diff --git a/cc-switch-dev-workflow/references/knowledge-base/foundations/context-engineering.md b/cc-switch-dev-workflow/references/knowledge-base/foundations/context-engineering.md new file mode 100644 index 0000000..ac7441a --- /dev/null +++ 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。 diff --git 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 new file mode 100644 index 0000000..42623b3 --- /dev/null +++ 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 校验、重构建议和第二视角复核 diff --git 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 new file mode 100644 index 0000000..b878293 --- /dev/null +++ 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` 用来掩盖前面没有对齐好的问题 diff --git 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 new file mode 100644 index 0000000..c5afdbc --- /dev/null +++ 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 +- 所有阶段都要留下高密度产物，便于下一阶段在更干净的上下文中执行。 +- 任何“先实现，后面再说”的做法，都会把偏差拖到更昂贵的阶段。 diff --git 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 new file mode 100644 index 0000000..53e3b32 --- /dev/null +++ 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 的自由度发生在正确层级。 +- 高层只定义目标和边界，低层才决定具体实现细节。 +- 这样既防止模型随机发挥，也不把高层误判强行塞进代码。 diff --git a/cc-switch-dev-workflow/references/knowledge-base/orchestration/agent-handoff-contract.md b/cc-switch-dev-workflow/references/knowledge-base/orchestration/agent-handoff-contract.md new file mode 100644 index 0000000..dc75db4 --- /dev/null +++ b/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` 必须说明什么情况停下来找人 diff --git a/cc-switch-dev-workflow/references/knowledge-base/orchestration/cc-switch-operating-model.md b/cc-switch-dev-workflow/references/knowledge-base/orchestration/cc-switch-operating-model.md new file mode 100644 index 0000000..1e368ce --- /dev/null +++ b/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 diff --git a/cc-switch-dev-workflow/references/knowledge-base/platform/framework-decision-matrix.md b/cc-switch-dev-workflow/references/knowledge-base/platform/framework-decision-matrix.md new file mode 100644 index 0000000..5e54f80 --- /dev/null +++ b/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` diff --git a/cc-switch-dev-workflow/references/knowledge-base/platform/model-routing-policy.md b/cc-switch-dev-workflow/references/knowledge-base/platform/model-routing-policy.md new file mode 100644 index 0000000..080b36f --- /dev/null +++ b/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 摘要继续 diff --git a/cc-switch-dev-workflow/references/knowledge-base/platform/stack-policy.md b/cc-switch-dev-workflow/references/knowledge-base/platform/stack-policy.md new file mode 100644 index 0000000..6773879 --- /dev/null +++ b/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 约束 +- 何时失效：例外只对当前项目或当前子系统生效，不自动扩散为默认规则 diff --git 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 new file mode 100644 index 0000000..686821c --- /dev/null +++ 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 后的结构与命名更清晰，不是更复杂 diff --git 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 new file mode 100644 index 0000000..fdb14f3 --- /dev/null +++ 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 已经形成闭环 diff --git 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 new file mode 100644 index 0000000..7c845bc --- /dev/null +++ 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 的遵守 +- 关键流程已有测试托底 diff --git a/cc-switch-dev-workflow/references/knowledge-base/sources/2026-02-02-ralphy-task-list-flow.md b/cc-switch-dev-workflow/references/knowledge-base/sources/2026-02-02-ralphy-task-list-flow.md new file mode 100644 index 0000000..b9ad679 --- /dev/null +++ b/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` diff --git a/cc-switch-dev-workflow/references/knowledge-base/sources/2026-03-04-ai-pipeline-reliability.md b/cc-switch-dev-workflow/references/knowledge-base/sources/2026-03-04-ai-pipeline-reliability.md new file mode 100644 index 0000000..d894411 --- /dev/null +++ b/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` diff --git a/cc-switch-dev-workflow/references/knowledge-base/sources/2026-03-06-spec-driven-workflow.md b/cc-switch-dev-workflow/references/knowledge-base/sources/2026-03-06-spec-driven-workflow.md new file mode 100644 index 0000000..3797d3c --- /dev/null +++ b/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` diff --git a/cc-switch-dev-workflow/references/knowledge-base/sources/README.md b/cc-switch-dev-workflow/references/knowledge-base/sources/README.md new file mode 100644 index 0000000..22386b8 --- /dev/null +++ b/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)。 diff --git a/cc-switch-dev-workflow/references/knowledge-base/sources/skills-zip-digest.md b/cc-switch-dev-workflow/references/knowledge-base/sources/skills-zip-digest.md new file mode 100644 index 0000000..128f055 --- /dev/null +++ b/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` diff --git a/cc-switch-dev-workflow/references/knowledge-base/sources/workflow-zip-digest.md b/cc-switch-dev-workflow/references/knowledge-base/sources/workflow-zip-digest.md new file mode 100644 index 0000000..e84734b --- /dev/null +++ b/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` diff --git a/cc-switch-dev-workflow/references/knowledge-base/templates/README.md b/cc-switch-dev-workflow/references/knowledge-base/templates/README.md new file mode 100644 index 0000000..141e7d2 --- /dev/null +++ b/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) | 验收清单 | diff --git a/cc-switch-dev-workflow/references/knowledge-base/templates/acceptance-checklist-template.md b/cc-switch-dev-workflow/references/knowledge-base/templates/acceptance-checklist-template.md new file mode 100644 index 0000000..f4c149e --- /dev/null +++ b/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 +``` diff --git a/cc-switch-dev-workflow/references/knowledge-base/templates/agent-handoff-template.md b/cc-switch-dev-workflow/references/knowledge-base/templates/agent-handoff-template.md new file mode 100644 index 0000000..dfd799e --- /dev/null +++ b/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: +``` diff --git a/cc-switch-dev-workflow/references/knowledge-base/templates/analysis-template.md b/cc-switch-dev-workflow/references/knowledge-base/templates/analysis-template.md new file mode 100644 index 0000000..70d52a2 --- /dev/null +++ b/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 +- +``` diff --git a/cc-switch-dev-workflow/references/knowledge-base/templates/claude-md-template.md b/cc-switch-dev-workflow/references/knowledge-base/templates/claude-md-template.md new file mode 100644 index 0000000..01351c0 --- /dev/null +++ b/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: +``` diff --git a/cc-switch-dev-workflow/references/knowledge-base/templates/spec-template.md b/cc-switch-dev-workflow/references/knowledge-base/templates/spec-template.md new file mode 100644 index 0000000..1ca0d18 --- /dev/null +++ b/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 +# + +## Overview +- Defines: +- Not Covered: +- Related SPECS: + +## Terminology +- + +## Domain Sections +###
+- Rule: +- Acceptance: +> **Why**: +> **Rejected**: + +## Forbidden +- Do not: +- Use instead: +- Reason: + +## References +- Internal: +- External: +``` diff --git a/cc-switch-dev-workflow/references/knowledge-base/templates/tdd-plan-template.md b/cc-switch-dev-workflow/references/knowledge-base/templates/tdd-plan-template.md new file mode 100644 index 0000000..6c4c4b2 --- /dev/null +++ b/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-.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: + +## 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 +- +``` diff --git a/cc-switch-dev-workflow/references/knowledge-base/templates/todo-yaml-template.md b/cc-switch-dev-workflow/references/knowledge-base/templates/todo-yaml-template.md new file mode 100644 index 0000000..d7fb6cc --- /dev/null +++ b/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 () and use to generate .plans/-.md" + description: "Scope: . Reference: ." + completed: false + + - title: "Implement in , covering , and use to follow .plans/-.md" + description: "Validation: . Impact: ." + completed: false + + - title: "Review for simplification opportunities and use code-simplifying skill" + description: "Keep behavior unchanged." + completed: false + + - title: "Review for refactoring opportunities and use code-refactoring skill to generate .plans/-.md" + description: "Focus: DRY/SRP/OCP/KISS." + completed: false +``` + +## Title Rules +- 必须是一行 +- 必须点名模块或路径 +- 必须点名依据文档或计划文件 +- 不写“实现某功能”这种无上下文标题 diff --git a/cc-switch-dev-workflow/references/knowledge-base/workflows/README.md b/cc-switch-dev-workflow/references/knowledge-base/workflows/README.md new file mode 100644 index 0000000..85cd292 --- /dev/null +++ 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 diff --git 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 new file mode 100644 index 0000000..f15d36c --- /dev/null +++ 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` 没有写明禁用项和例外接口 +- 初始化时就允许多个技术轨道并存 diff --git 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 new file mode 100644 index 0000000..47a0e67 --- /dev/null +++ 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 决策 +- 一份报告塞太多主题，导致后续不可引用 diff --git 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 new file mode 100644 index 0000000..5a82bd7 --- /dev/null +++ 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 负责多个不相关领域 diff --git 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 new file mode 100644 index 0000000..d7359f5 --- /dev/null +++ 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 顺手修改无关模块 diff --git 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 new file mode 100644 index 0000000..a5df1fa --- /dev/null +++ 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 错误当成代码错误硬补实现 +- 补齐后不做简化和重构 diff --git 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 new file mode 100644 index 0000000..ebb68c3 --- /dev/null +++ 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 +- 在没有测试托底的情况下大规模重构 +- 对所有项目默认做最重的结构重组 diff --git 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 new file mode 100644 index 0000000..b54d0d1 --- /dev/null +++ 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 外包给自动化 +- 严重问题被降级成“后续再说” +- 没有记录残留风险就直接发布 diff --git a/cc-switch-dev-workflow/references/local-cc-switch-runtime.md b/cc-switch-dev-workflow/references/local-cc-switch-runtime.md new file mode 100644 index 0000000..3cdb0a2 --- /dev/null +++ b/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 固化到私有仓库，先在提交说明里标明用途和作用域。 diff --git a/cc-switch-dev-workflow/scripts/bootstrap_workflow_workspace.py b/cc-switch-dev-workflow/scripts/bootstrap_workflow_workspace.py new file mode 100755 index 0000000..1c1c427 --- /dev/null +++ b/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()) diff --git a/cc-switch-dev-workflow/scripts/inspect_cc_switch_runtime.py b/cc-switch-dev-workflow/scripts/inspect_cc_switch_runtime.py new file mode 100755 index 0000000..476523e --- /dev/null +++ b/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())