spec-dev

Requirement design workflow - mandatory before any creative development (new features, components, behavior changes, API/DB design): triage, parallel exploration, one-question-at-a-time clarification, adversarial validation and 2-3 option comparison produce a spec, then hand off to writing-plans. Use exploring first while the idea is unsettled; not for pure Q&A, test runs, or no-design-space small fixes (use quick-fix). / 需求设计工作流——在任何创造性开发工作（新功能、新组件、行为变更、API/数据库设计）开始前必须使用。通过需求分诊、并行探索、逐题澄清、对抗验证与 2-3 方案对比，把想法打磨成完整设计，落盘 spec 并交接 writing-plans。当用户已明确要交付某功能或变更（功能开发、API/数据库设计、行为变更、技术选型落地）时触发；不适用于纯问答、跑测试、无设计空间的小 bug 修复/小调整（用 quick-fix）；想法尚未定型、还没决定要不要做时先用 exploring。

Real-time search engine supporting web search, vertical domain search, parallel batch search, and URL content extraction.

All-round acceptance workflow - multi-dimension acceptance over the dimension x execution-nature matrix: unit/integration/API regression, E2E, visual regression, accessibility, performance (web CWV/Lighthouse, k6 load, client), plus AI autonomous acceptance and failure diagnosis. For acceptance-flavored requests (accept a feature/page/endpoint, E2E, load test, visual regression) or executing-plans wrap-up; also diagnoses page interaction, rendering, performance, Shadow DOM/iframe issues. Not for TDD red-green cycles, routine test runs, static code review, or doc review. / 全能验收工作流——按「验收维度 × 执行性质」矩阵对交付物做多维验收：单元/集成/API 回归、 E2E 端到端、视觉回归、可访问性、性能验收（前端 CWV/Lighthouse、后端 k6 压测、客户端）， 外加 AI 自主验收与失败诊断。当用户要求"验收这个功能/页面/接口"、"E2E 测试"、 "acceptance test"、"性能测试/压测/能扛多少 QPS"、"视觉回归"、"界面/浏览器测试"， 或 executing-plans 收尾按验收矩阵触发时使用；也用于诊断页面交互、渲染、性能、 Shadow DOM/iframe 问题。不适用于开发中的 TDD 红绿循环（用 test-driven-development）、 无验收语义的日常"跑一下测试/修测试"、代码静态审查、需求文档评审。

Lightweight bug-fix workflow - for fixes already decided on with no design space (small bugs, minor adjustments, post-plan tweaks): locate root cause with spec back-lookup, confirm one question at a time, fix under TDD, optional acceptance. Splits on contract impact to avoid spec drift; escalates to requirement-analysis on contract-crossing / cross-module / new-dependency signals. Not for new features or anything with design space (use requirement-analysis), nor for undecided ideas (use exploring). / 轻量 bug 修复工作流——已决定要修、无设计空间的小修复（小 bug、小调整、计划执行后的小问题）时使用：定位根因（含 spec 反查）、逐题校对、TDD 修复、可选验收。按契约影响分流以规避 spec 漂移；根因涉及跨 spec 契约/跨模块/新依赖时建议升级 requirement-analysis。不适用于新功能或任何有设计空间的需求（用 requirement-analysis），也不适用于尚未决定要不要做的想法（用 exploring）。

Isolated workspace - before feature work that needs isolation from the current workspace or before executing a plan: detect existing isolation first, prefer native worktree tools (e.g. Claude Code EnterWorktree), fall back to manual git worktree; ensure dependencies installed and the test baseline is green. / 隔离工作区——开始需要与当前工作区隔离的功能开发、或执行实施计划之前使用。先检测已有隔离，优先平台原生 worktree 工具（如 Claude Code 的 EnterWorktree），无原生工具才降级手工 git worktree。确保隔离工作区就绪、依赖安装完成、测试基线干净。

Browser visual preview - during requirement design or brainstorming, show mockups, wireframes, layout comparisons and architecture diagrams in a local browser page and collect click-through choices. Use when a question is genuinely visual (clearer to see than to say); text-only requirement, tradeoff or concept questions stay in the terminal. / 浏览器可视化预览——在需求设计/头脑风暴过程中，用本地浏览器页面向用户展示 mockup、线框图、布局对比、架构图并收集点击选择。当一个问题"用看的比用说的更清楚"时使用（真实的布局/视觉/图示对比问题，而非仅话题涉及 UI）；纯文字的需求、取舍、概念选择问题不适用，应留在终端提问。

Write implementation plans - when a spec or clear requirement exists and multi-step work has not started: decompose the design into bite-sized tasks a zero-context engineer can execute (exact file paths, complete code, TDD steps, expected output), save under the feature directory plan/ subdir, hand off to executing-plans. Usually invoked by requirement-analysis after spec approval. / 编写实施计划——当已有 spec 或明确需求、准备开始多步骤开发任务、但尚未动代码时使用。把设计拆解为零上下文工程师也能执行的 bite-sized 任务（精确文件路径、完整代码、TDD 步骤、预期输出），落盘特性目录的 plan/ 子目录并交接 executing-plans 执行。通常由 requirement-analysis 在 spec 获批后调用；也可对既有 spec/需求单独触发。

Execute implementation plans - when a written plan from writing-plans exists (plan/*-plan.md under the feature directory in .spec-dev/): the main thread executes task-by-task in an isolated worktree (TDD + per-task commits + spec self-check), then orchestrates multi-dimension adversarial code review and matrix-driven acceptance. Not for improvised changes without a written plan. / 执行实施计划——当已有 writing-plans 产出的实施计划（`.spec-dev/` 特性目录下 plan/ 子目录的 *-plan.md）、准备动手实现时使用。主线程在隔离 worktree 中逐任务执行（TDD + 每任务提交 + spec 自检），全部完成后编排多维对抗代码审查（code-reviewer 子代理不写码、仅分析与复跑验证），并按验收矩阵触发 acceptance-qa 验收，最终合并总结。不适用于没有书面计划的即兴改动。

Exploration mode (thinking partner) - for ideas not yet committed to delivery: read-only code walks, option comparison, diagram-driven reasoning; no code changes, no implementation artifacts, no forced conclusions; hands off to requirement-analysis once the idea crystallizes. Not for committed deliverables or single-fact lookups; for already-decided small fixes with no design space use quick-fix. / 探索模式（思考伙伴）——想法尚未定型、还没决定要不要做时使用。当用户表达"我在想要不要…""帮我想想/聊聊这个思路""A 和 B 哪个合适""为什么这里这么慢/乱""这个想法可行吗""先搞懂这块代码再说"等未承诺交付的请求时触发。只读代码、比较方案、画图梳理，不写代码、不建实施档案、不强制结论；想法结晶后交接 requirement-analysis。已明确要交付某功能时不适用（直接用 requirement-analysis）；单点事实问答（如"这个函数在哪定义"）也不适用；已决定要修的无设计空间小 bug/小调整用 quick-fix。

TDD discipline - before implementing any feature or fixing any bug. Iron law: no production code without a failing test. Write the test, watch it fail, write minimal code to pass; red-green-refactor. Exceptions (throwaway prototypes, generated code, config files) require user consent. / 测试驱动开发纪律——实现任何功能或修复任何 bug、在写实现代码之前使用。铁律：没有失败测试就没有生产代码。先写测试、看它失败、再写最小实现让它通过；红-绿-重构循环。例外（一次性原型、生成代码、配置文件）需征得用户同意。