create-yss-spec 1.0.0

package/template/docs/agents/gitlab-workflow-skills.md

@@ -0,0 +1,160 @@
+# GitLab Workflow Skills
+
+> 本文沉淀本项目使用 GitLab 管理代码、MR、CI 和自动化 Git 工作流的技能配置。这里记录的是协作规范与本机/项目入口，不保存任何 token。
+
+## 1. 定位
+
+当项目主远端为 GitLab 时，默认使用 GitLab 作为代码托管、Merge Request、CI/CD 和工作流协作入口。
+
+PRD、Issue 和 triage 不在本文中写死到 GitLab；它们按 `docs/agents/issue-tracker.md` 在 GitLab / GitHub 间路由。
+
+已集成能力：
+
+| 能力 | 工具 / Skill | 用途 |
+|---|---|---|
+| GitLab API 与项目查询 | `gitlab-workflow` skill | 查询项目、clone 地址、创建 group / project、执行分支化 git workflow |
+| GitLab CLI | `glab` | 管理 MR、Issue、CI、Pipeline、Release、变量、Runner 等 |
+| 项目快捷入口 | `scripts/gitworks` | 在当前仓库内统一执行 status、workflow、MR、CI 命令 |
+| Git 推送认证 | macOS Keychain + HTTPS token | 让 `git push`、workflow push 能非交互执行 |
+
+## 2. 本机配置
+
+GitLab 基础配置文件：
+
+```text
+~/.config/codex/gitlab.json
+```
+
+结构：
+
+```json
+{
+  "url": "http://<gitlab-host>",
+  "token": "<GitLab Personal Access Token 或 Project Access Token>",
+  "default_clone_protocol": "http"
+}
+```
+
+要求：
+
+- 文件权限应为 `600`。
+- token 不得写入仓库文件。
+- token 不得出现在脚本、文档、Issue、MR 描述或提交信息中。
+- token 至少需要 `read_api`；若要推送代码，需要 `write_repository`；若要创建 MR、管理 CI 或项目资源，建议具备对应 API 权限。
+
+## 3. glab 配置
+
+`glab` 用于操作 GitLab MR / CI / Issue / Release。
+
+自托管 GitLab 配置示例：
+
+```bash
+glab auth login \
+  --hostname <gitlab-host> \
+  --api-host <gitlab-host> \
+  --api-protocol http \
+  --git-protocol http \
+  --stdin
+```
+
+验证：
+
+```bash
+glab auth status --hostname <gitlab-host>
+glab repo view --repo <group>/<project>
+```
+
+若 `glab` 由 Go 安装，默认位置为：
+
+```text
+~/go/bin/glab
+```
+
+建议确保 `~/go/bin` 在 `PATH` 中。
+
+## 4. 项目快捷入口
+
+项目脚本：
+
+```text
+scripts/gitworks
+```
+
+`scripts/gitworks` 默认从当前仓库 `origin` 远端推导 GitLab host 和 `<group>/<project>`；如需覆盖，可设置 `GITLAB_HOST`、`GITLAB_PROJECT_PATH` 或 `GIT_REMOTE`。
+
+常用命令：
+
+```bash
+scripts/gitworks status
+scripts/gitworks workflow main feature/demo "feat: demo"
+scripts/gitworks mr-list
+scripts/gitworks mr-create main "feat: demo"
+scripts/gitworks ci-list
+scripts/gitworks ci-run
+scripts/gitworks ci-status
+```
+
+命令语义：
+
+| 命令 | 作用 |
+|---|---|
+| `status` | 查看当前分支、工作区状态和 GitLab 登录状态 |
+| `workflow <base> <branch> <message>` | 执行 fetch、rebase、切分支、add、commit、push |
+| `mr-list` | 查询当前项目打开的 MR |
+| `mr-create <target> <title> [description]` | 从当前分支创建 MR 到目标分支 |
+| `ci-list` | 查询 Pipeline 列表 |
+| `ci-run [branch]` | 触发 Pipeline |
+| `ci-status` | 查看 CI 状态 |
+
+## 5. Agent 使用规则
+
+当用户提到 GitLab、MR、Pipeline、CI、远端仓库、自动提交、自动推送或 gitworks 时，优先使用以下顺序：
+
+1. 读取项目状态：`scripts/gitworks status`。
+2. 需要 GitLab API / clone / push workflow 时，使用 `gitlab-workflow` skill。
+3. 需要 MR / CI / Pipeline 时，使用 `glab` 或 `scripts/gitworks`；需要 Issue / PRD / triage 时，先按 `docs/agents/issue-tracker.md` 判断 GitLab 或 GitHub。
+4. 执行自动提交前，必须先检查工作区脏文件，避免把无关 `.agents/`、`.codex/`、本机配置或用户未确认文件混入提交。
+5. 不直接提交到受保护主分支；默认使用 `feature/*`、`fix/*`、`chore/*` 分支。
+6. 自动 workflow 只在用户明确授权提交/推送时执行。
+7. 每个阶段产物完成后，按 `AGENTS.md` 的 Git checkpoint 规则确认范围、提交和推送。
+
+## 6. 推荐工作流
+
+开发阶段：
+
+```text
+影响面评估
+  -> 实现 / 文档 / 测试
+  -> fresh verification
+  -> scripts/gitworks status
+  -> scripts/gitworks workflow <base> <branch> "<commit message>"
+  -> scripts/gitworks mr-create <target> "<title>"
+  -> scripts/gitworks ci-status
+```
+
+MR 阶段：
+
+```text
+创建 MR
+  -> 查看 Pipeline
+  -> 修复 CI / Review comments
+  -> fresh verification
+  -> 合并前确认发布说明和回滚点
+```
+
+## 7. 故障排查
+
+| 现象 | 检查项 |
+|---|---|
+| `glab: command not found` | 确认 `~/go/bin` 在 `PATH`，或设置 `GLAB=/path/to/glab` |
+| `git push` 要求输入密码 | 检查 Keychain 凭据；重新写入 GitLab token |
+| `glab auth status` 失败 | 检查 token 是否过期、权限是否足够、GitLab 地址是否可达 |
+| `ci-list` 没有结果 | 项目可能还没有 `.gitlab-ci.yml` 或历史 Pipeline |
+| SSH clone 失败 | 当前环境优先使用 HTTP；SSH 端口和 key 需要单独配置 |
+
+## 8. 安全要求
+
+- token 轮换后，需要同步更新 `~/.config/codex/gitlab.json`、Keychain 和 `glab` 登录态。
+- 用户在聊天中明文提供 token 后，建议完成配置后尽快在 GitLab 轮换。
+- 不在 `docs/`、`scripts/`、`.env`、`.git/config` 中保存明文 token。
+- 触碰权限、认证、CI 变量、Runner、生产部署凭据时，必须标记人工确认。

package/template/docs/agents/issue-tracker.md

@@ -0,0 +1,81 @@
+# Issue Tracker: GitLab / GitHub
+
+> 中文说明：本文规定项目的 PRD、垂直切片 Issue 和 triage 结果必须支持 GitLab Issues 与 GitHub Issues。Agent 不得把 issue tracker 写死为 GitHub 或 GitLab；应按用户明确选择、当前仓库主远端和可用凭据决定发布平台。
+
+## 平台选择规则
+
+按以下优先级选择 issue tracker：
+
+1. 用户明确指定平台时，使用用户指定的平台。
+2. 用户未指定时，优先使用当前仓库主远端 `origin` 对应的平台。
+3. 如果当前目录不是目标仓库，或远端同时存在 GitLab / GitHub 且无法判断主平台，先询问用户。
+4. 如果目标平台凭据不可用，先生成本地 markdown 草案，并说明需要配置的 CLI / token，不要自动改发到另一平台。
+
+## 规格流程状态同步
+
+规格、生命周期和交付任务状态必须同步到当前选定 issue tracker。同步平台仍按“平台选择规则”确定：用户定 GitLab 就同步 GitLab，用户定 GitHub 就同步 GitHub；用户未指定时，以主远端对应平台为准。
+
+必须同步的节点：
+
+- PRD / 需求冻结 / OpenAPI Freeze / Issue change 创建完成时，创建或更新对应 Issue，并记录本地资产路径。
+- 垂直切片进入实现前，必须在对应平台存在可追踪 Issue；Issue 需要包含切片范围、阻塞关系、验收标准、测试 seam 和人工审查点。
+- 每个切片或生命周期阶段完成时，必须更新对应 Issue 的评论、标签、状态或里程碑，说明完成范围、验证命令、fresh verification 结果、剩余风险和下一步。
+- 阶段性议程、里程碑或 sprint planning 已经存在时，应把相关 PRD / change / slice Issue 归入同一议程，避免只在本地文档里记录进度。
+- 触碰安全红线时，必须在 Issue 中标记 `ready-for-human` 或写明 `TODO-HUMAN-REVIEW`，并列出需要人工确认的范围。
+
+同步证据要求：
+
+1. 本地生命周期文档应记录目标平台、Issue 编号 / URL、发布时间或最近同步时间。
+2. Git checkpoint 报告应说明 Issue 同步状态：已同步、暂缓同步或平台不可用。
+3. 不得把“完成 / 可合并 / 可发布”只写在本地文件里；必须同步到目标平台，并附 fresh verification 证据或明确阻断项。
+4. 若同步平台不可用，本地草案必须标记“待发布平台”，恢复后优先补同步。
+
+## GitLab Issues
+
+当平台为 GitLab 时，优先使用 `glab` 或项目快捷入口 `scripts/gitworks`。
+
+常用命令：
+
+- Create an issue: `glab issue create --title "..." --description "..."`
+- Read an issue: `glab issue view <iid> --comments`
+- List issues: `glab issue list --state opened`
+- Comment on an issue: `glab issue note <iid> --message "..."`
+- Apply labels: `glab issue update <iid> --label "ready-for-agent"`
+- Close an issue: `glab issue close <iid>`
+
+GitLab 相关配置和 MR / CI 工作流见 `docs/agents/gitlab-workflow-skills.md`。
+
+## GitHub Issues
+
+当平台为 GitHub 时，使用 `gh` CLI。
+
+常用命令：
+
+- Create an issue: `gh issue create --title "..." --body "..."`
+- Read an issue: `gh issue view <number> --comments`
+- List issues: `gh issue list --state open --json number,title,body,labels,comments`
+- Comment on an issue: `gh issue comment <number> --body "..."`
+- Apply or remove labels: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- Close an issue: `gh issue close <number> --comment "..."`
+
+## Triage Surface
+
+Issue 是默认 triage surface。MR / PR 是否纳入 triage 取决于当前平台和用户请求：
+
+- GitLab 项目：可按需读取 GitLab Issues、Merge Requests 和 Pipeline 状态。
+- GitHub 项目：可按需读取 GitHub Issues、Pull Requests 和 Actions 状态。
+- 用户只要求 issue triage 时，不主动扩展到 MR / PR。
+
+## Publishing
+
+当 skill 说 “publish to the issue tracker” 时：
+
+1. 先按“平台选择规则”确定 GitLab 或 GitHub。
+2. 在目标平台创建或更新 Issue。
+3. 在本地对应文档中记录平台、URL / 编号和发布时间。
+4. 若目标平台不可用，生成 `docs/requirements/issues/` 下的本地草案，并标注“待发布平台”。
+
+当 skill 说 “fetch the relevant ticket” 时：
+
+- GitLab：使用 `glab issue view <iid> --comments`。
+- GitHub：使用 `gh issue view <number> --comments`。

package/template/docs/agents/skills-maintenance.md

@@ -0,0 +1,126 @@
+# Skills Maintenance
+
+> 中文说明：本文说明本仓库内置 Engineering Skills 的来源、安装位置、升级步骤和验证命令。它是维护文档，不是 skill 本体；真正可被 Agent 加载的 `SKILL.md` 位于各项目 Agent roots 的 `skills/` 目录。
+
+本仓库默认使用项目内置技能快照，而不是只依赖用户全局 Codex / Hermes 技能目录。`skills-lock.json` 是来源、版本和技能清单的权威记录；`scripts/verify-template` 是落地校验入口。
+
+## Sources
+
+| Source | Ref | Path | 用途 |
+|---|---|---|---|
+| `mattpocock/skills` | `272f99b22574f50e4266791c86b9302682970e23` | `skills/engineering` | Matt Pocock Engineering Skills 主流程 |
+| `anthropics/knowledge-work-plugins` | `main` | `sales/skills/competitive-intelligence` | 竞品 / 市场事实研究 |
+
+## Installed Skills
+
+当前项目 Agent roots 必须同时具备以下技能：
+
+```text
+ask-matt
+competitive-intelligence
+grill-with-docs
+to-prd
+to-issues
+implement
+tdd
+diagnosing-bugs
+code-review
+domain-modeling
+codebase-design
+improve-codebase-architecture
+triage
+prototype
+research
+setup-matt-pocock-skills
+resolving-merge-conflicts
+```
+
+`ask-matt` 保持 Matt Pocock 上游正文不改；本项目通过 `yss-product-lifecycle` 把它的 idea -> ship 主流映射到 YSS 阶段门禁、OpenAPI Draft / Freeze、YSS routing、Git checkpoint 和 fresh verification。
+
+## Project Agent Roots
+
+| Agent | Project root |
+|---|---|
+| Agent | `.agent/skills/<skill-name>/` |
+| Agents | `.agents/skills/<skill-name>/` |
+| Claude | `.claude/skills/<skill-name>/` |
+| Codex | `.codex/skills/<skill-name>/` |
+| Hermes | `.hermes/skills/<skill-name>/` |
+| Pi | `.pi/skills/<skill-name>/` |
+| Trae | `.trae/skills/<skill-name>/` |
+
+## Optional Local Workflow Tools
+
+除项目内置 Engineering Skills 外，维护者可按需使用本机级 GitLab 工作流工具；它们不是模板必须内置的技能目录。
+
+| Skill / Tool | Entry | 用途 |
+|---|---|---|
+| `gitlab-workflow` | `$CODEX_HOME/skills/gitlab-workflow/` | GitLab API、项目查询、clone、push、分支化 workflow |
+| `glab` | `glab` | GitLab MR、CI、Pipeline、Issue、Release 等 CLI 操作 |
+| `scripts/gitworks` | `scripts/gitworks` | 当前仓库的 GitLab workflow 快捷入口 |
+
+详细配置与使用规则见 `docs/agents/gitlab-workflow-skills.md`。
+
+## Project-Level Harness / YSS Skills
+
+本项目还维护以下项目级 Harness / YSS 集成技能：
+
+| Skill | Path | 用途 |
+|---|---|---|
+| `implementation-repo-onboarding` | `.codex/skills/implementation-repo-onboarding/` | 接入已有前端 / 后端实现仓库，生成登记、基线发现和验证命令 |
+| `cross-repo-implementation-routing` | `.codex/skills/cross-repo-implementation-routing/` | 路由跨仓库实现任务，绑定 MR / PR 和验证证据 |
+| `yss-frontend-scaffold-generator` | `.codex/skills/yss-frontend-scaffold-generator/` | 基于标准 YSS 前端模板定义 0-1 前端工程生成流程 |
+
+这些技能只定义流程、输入输出和安全边界；除非用户明确授权，不直接 clone 到 Harness 仓库、创建远端仓库、提交或推送代码。
+
+## Upgrade Checklist
+
+1. 读取 `skills-lock.json`，确认 Matt 快照 ref、`competitive-intelligence` 额外来源和技能清单。
+2. 拉取或下载对应来源到临时目录，不直接覆盖工作区。
+3. 将锁定技能同步到全部 7 个项目 Agent roots。
+4. 保留 `ask-matt` 上游正文不改；项目差异写入 `yss-product-lifecycle`、流程文档或维护说明。
+5. 检查每个技能目录都有合法 `SKILL.md` frontmatter，至少包含 `name` 和 `description`。
+6. 运行 `scripts/verify-template`。
+7. 重启需要重新加载技能的 Agent 客户端。
+
+## Verification Command
+
+```bash
+skills=(
+  ask-matt
+  competitive-intelligence
+  grill-with-docs
+  to-prd
+  to-issues
+  implement
+  tdd
+  diagnosing-bugs
+  code-review
+  domain-modeling
+  codebase-design
+  improve-codebase-architecture
+  triage
+  prototype
+  research
+  setup-matt-pocock-skills
+  resolving-merge-conflicts
+)
+
+roots=(
+  .agent/skills
+  .agents/skills
+  .claude/skills
+  .codex/skills
+  .hermes/skills
+  .pi/skills
+  .trae/skills
+)
+
+for root in "${roots[@]}"; do
+  for skill in "${skills[@]}"; do
+    test -f "$root/$skill/SKILL.md" || echo "missing $root/$skill/SKILL.md"
+  done
+done
+
+scripts/verify-template
+```

package/template/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+> 中文说明：本文定义 Agent 分诊时使用的标准五态标签。无论 skill 内部使用什么描述，落到 GitLab Issue 或 GitHub Issue 时都应映射为这里列出的标签。
+
+The engineering skills use five canonical triage roles. This file maps those roles to the label strings used in this repo's issue tracker.
+
+| Canonical role | Tracker label | Meaning |
+|---|---|---|
+| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue |
+| `needs-info` | `needs-info` | Waiting on reporter for more information |
+| `ready-for-agent` | `ready-for-agent` | Fully specified and ready for an AFK agent |
+| `ready-for-human` | `ready-for-human` | Requires human implementation, judgment, or privileged access |
+| `wontfix` | `wontfix` | Will not be actioned |
+
+When a skill mentions a role, use the corresponding tracker label from this table.

package/template/docs/api/templates/openapi-draft-review-checklist.md

@@ -0,0 +1,56 @@
+# OpenAPI Draft 契约评审清单
+
+> 用于 API 影响分析 / 契约草案 / OpenAPI Draft 进入 Engineering Baseline / YSS DDD Review 之前。
+> OpenAPI Draft 在 OpenAPI Freeze 前仅用于评审和架构反审，不得作为前后端实现或生成客户端的稳定契约。
+> 评审采用 fail-closed：阻断项未关闭前，不进入架构 / 系统 / 数据架构设计。
+
+## 输入资产
+
+| 资产 | 路径 | 状态 |
+|---|---|---|
+| API 影响记录 / 契约草案 | issue note / design note / `docs/api/specs/<feature>.yaml` |  |
+| OpenAPI Draft | `docs/api/specs/<feature>.yaml` |  |
+| PRD / 需求冻结 |  |  |
+| 产品总体设计 / 功能架构 |  |  |
+| 交互说明 / 页面清单 | `docs/design/<feature>-interaction-spec.md` |  |
+| 原型 / 线框图 |  |  |
+| 状态矩阵 | `docs/design/<feature>-state-matrix.md` |  |
+| 原型评审结论 | `docs/design/<feature>-prototype-review.md` |  |
+| YSS 工程基线 | `.codex/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md` |  |
+
+## P0 追踪矩阵
+
+| P0 需求 / 页面动作 | Endpoint / Non-goal | Request | Response | Error | Permission / actionKey | Concurrency / Idempotency | Contract Test | 结论 |
+|---|---|---|---|---|---|---|---|---|
+|  |  |  |  |  |  |  |  |  |
+
+## 门禁检查
+
+| Gate | Pass 条件 | 结论 | 备注 |
+|---|---|---|---|
+| Draft 成熟度 | 明确当前仅为 review-only；实现、生成 client、契约测试固化均等待 OpenAPI Freeze |  |  |
+| OpenAPI 语法 | YAML、`$ref`、path 参数、lint 通过 |  |  |
+| P0 覆盖 | 每个 P0 需求有 endpoint/schema/error/test 或明确非目标 |  |  |
+| 交互输入完整 | Draft 已同时依据 PRD、产品总体设计、交互说明、原型/线框、状态矩阵和 prototype-review；缺任一项需说明无 UI 影响或返回上游补齐 |  |  |
+| DDD 契约边界 | Endpoint/schema 归属的限界上下文清楚；术语与 `CONTEXT.md` 和功能架构一致；契约不直接暴露内部聚合、Repository 或持久化表结构 |  |  |
+| 页面动作覆盖 | 每个按钮 / 抽屉 / 弹窗动作有 endpoint/non-goal、`actionKey`、权限和错误码 |  |  |
+| 对象生命周期 | manage/maintain/configure/create/update/archive/retry/cancel/publish/export/create-draft 语义闭环 |  |  |
+| YSS 响应包装 | 单对象 `SingleResult<T>`；列表 `MultiResult<T>`；分页 `PageResult<T>` |  |  |
+| 权限 | 无权不泄露数据；禁用动作返回 disabledReason；越权调用 403 |  |  |
+| 错误结构 | 模型级、字段级、行级错误可定位；关键 422 有 examples |  |  |
+| 乐观锁 / 幂等 | 草稿写入有 draftVersion；关键命令有幂等键 |  |  |
+| 安全红线 | 认证授权、SQL/DDL 草案、下载 URL、审计日志、敏感字段有人工审查项 |  |  |
+| 契约测试 | 导入、覆盖率、检查、评审、发布、导出、权限、冲突场景可测 |  |  |
+
+## 结论
+
+| 结论 | 勾选 |
+|---|---|
+| Approved for Engineering Baseline / Architecture Design |  |
+| Blocked, return to contract draft / OpenAPI Draft |  |
+
+## 阻断项
+
+| ID | 问题 | 依据 | 修正要求 | Owner |
+|---|---|---|---|---|
+|  |  |  |  |  |

package/template/docs/api/templates/openapi-freeze-record-template.md

@@ -0,0 +1,60 @@
+---
+pipeline: <feature-id>
+stage: openapi-freeze
+status: draft
+owner: ai
+---
+
+# <功能名称>OpenAPI Freeze 记录
+
+> 适用场景：OpenAPI Draft 通过产品、前端、后端、架构和设计审查后，冻结为实现输入。
+> 本文记录冻结版本、评审证据和后续变更规则，不替代 OpenAPI YAML。
+
+## 1. 输入材料
+
+| 资产 | 路径 / 链接 | 状态 | 备注 |
+|------|-------------|------|------|
+| OpenAPI Draft |  |  |  |
+| OpenAPI Draft Review |  |  |  |
+| PRD / 需求冻结 |  |  |  |
+| 产品设计 / 状态矩阵 |  |  |  |
+| 工程基线 / 系统 / 数据架构 |  |  |  |
+| Design Review |  |  |  |
+
+## 2. 冻结范围
+
+| 方法 | 路径 | schema | 状态 | 备注 |
+|------|------|--------|------|------|
+|  |  |  | frozen / deferred |  |
+
+## 3. 契约检查
+
+| 检查项 | 结论 | 备注 |
+|--------|------|------|
+| 页面动作到端点映射完整 | 通过 / 阻断 / 不适用 |  |
+| 请求 / 响应 schema 明确 | 通过 / 阻断 |  |
+| 错误结构和错误码明确 | 通过 / 阻断 |  |
+| 分页 / 排序 / 过滤明确 | 通过 / 阻断 / 不适用 |  |
+| 权限 / 并发 / 幂等明确 | 通过 / 阻断 / 不适用 |  |
+| YSS 统一响应包装明确 | 通过 / 阻断 |  |
+| 契约测试 seam 明确 | 通过 / 阻断 |  |
+| 安全红线已处理 | 通过 / 阻断 / 不适用 |  |
+
+## 4. 冻结后变更规则
+
+- 冻结后如需改变路径、请求 / 响应 schema、错误结构、权限或分页规则，必须回到 OpenAPI Draft Review 和 Design Review。
+- 行为规格变化影响接口时，必须同步回写 `docs/api/specs/<feature>.yaml` 和 OpenAPI Draft 或 PRD 验收场景。
+- 前后端实现必须以本记录引用的冻结版本为准。
+
+## 5. 完成标准
+
+- [ ] OpenAPI Draft Review 无阻断项。
+- [ ] Design Review 无阻断项。
+- [ ] 前端、后端、API 契约测试均可消费冻结契约。
+- [ ] Issue change formalization 可引用本冻结记录。
+
+## 6. 下一步门禁
+
+- 结论：Approved / Blocked
+- 下一步：Issue change formalization
+- 阻断项：

package/template/docs/architecture/README.md

@@ -0,0 +1,108 @@
+# 架构设计 (Architecture) — 从需求到技术方案
+
+> **Phase: Design**
+
+---
+
+## 四类架构产物
+
+架构设计按生命周期逐步产出，不要求一次性完成所有细节。
+
+| 产物 | 产出阶段 | 重点问题 | 建议文件 |
+|------|----------|----------|----------|
+| 业务架构 | 机会探索 / Discovery / 产品定义 | 用户是谁、价值流是什么、产品在业务生态中的边界在哪里 | `<feature>-business-architecture.md` |
+| 产品总体设计 / 功能架构 | PRD 初稿之后、页面 / 原型 / 交互设计之前 | 用户主流程、业务对象、功能域、模块边界、页面/API/数据影响、优先级、依赖和 MVP 非目标范围是什么 | `<feature>-product-overview-design.md` 或 `<feature>-functional-architecture.md` |
+| 系统概要设计 / 系统总体架构 | 工程基线 / 系统 / 数据架构设计 | 服务/模块如何构建、部署、集成、运维、回滚和演进 | `<feature>-system-overview-design.md`、`<feature>-system-architecture.md` 或 `<feature>-architecture.md` |
+| 数据架构 | 详细设计 / 持久化开发前 | 概念/逻辑/物理模型、元模型、版本、血缘、查询、索引和存储策略是什么 | `<feature>-data-architecture.md` |
+
+对于数据模型、元数据管理、ER 设计、版本管理或血缘分析类产品，数据架构是核心产品能力，必须在 Repository / MyBatis / 持久化开发前完成；如果 OpenAPI schema 依赖元模型，也必须在 OpenAPI Freeze 前完成。
+
+推荐配套图：
+
+```text
+docs/architecture/diagrams/<feature>-business-capability.excalidraw
+docs/architecture/diagrams/<feature>-functional-modules.excalidraw
+docs/architecture/diagrams/<feature>-system-architecture.excalidraw
+docs/architecture/diagrams/<feature>-data-model.excalidraw
+```
+
+使用 `excalidraw-diagram-generator` 生成图时，图只作为审查辅助；发现的问题必须回写到 PRD、OpenAPI、ADR、系统 / 数据架构设计 或对应架构文档。
+
+推荐模板：
+
+- `docs/design/templates/product-overview-design-template.md`：PRD 初稿之后、页面 / 原型 / 交互设计之前的产品总体设计 / 功能架构评审稿。
+- `docs/architecture/templates/system-overview-design-template.md`：系统 / 数据架构与工程契约设计审查阶段的系统概要设计评审稿，承接 API 影响分析 / 契约草案 / OpenAPI Draft 与工程基线，并在 OpenAPI Freeze 前反向校验 Draft。
+
+---
+
+## AI 四种角色
+
+### 方案生成器
+```python
+delegate_task(
+    goal="为'[功能]'生成 3 种技术方案并做 trade-off 对比",
+    context="评估维度：复杂度/安全/性能/扩展性/契合度/开发成本"
+)
+```
+
+### 预审者 — 六维度审查
+```python
+delegate_task(
+    goal="从可扩展性、安全性、性能、可靠性、可维护性、成本六个维度预审此方案",
+    context="每个维度打分 1-5，评分<3 给出替代方案"
+)
+```
+
+### ADR 记录者
+```python
+delegate_task(
+    goal="根据技术讨论记录，自动生成 ADR",
+    context="使用 docs/adr/template.md 模板"
+)
+```
+
+### 图表生成者
+```python
+delegate_task(
+    goal="使用 excalidraw-diagram-generator 生成架构图",
+    context="根据阶段选择：业务能力图/功能模块图/系统架构图/ER 图/血缘图/数据流图"
+)
+```
+
+---
+
+## 六维度审查清单 (39项)
+
+详见 [templates/architecture-review-checklist.md](templates/architecture-review-checklist.md)
+
+| 维度 | 项数 | 关键检查 |
+|------|------|---------|
+| 可扩展性 | 6 | 独立部署、无状态、服务边界 |
+| 安全性 | 10 | 认证链路、密码存储、注入防护 |
+| 性能 | 8 | 索引、缓存、N+1、连接池 |
+| 可靠性 | 5 | 降级、重试、幂等、健康检查 |
+| 可维护性 | 6 | ADR、OpenAPI、日志、监控 |
+| 成本 | 4 | YAGNI、按需、冷数据归档 |
+
+---
+
+## Deep Module 治理
+
+当出现模块难改、测试 seam 不清晰、逻辑散落、Agent 难以理解代码路径时，优先使用 `improve-codebase-architecture` 和 `codebase-design`。
+
+落地产物：
+
+- [templates/architecture-deepening-template.md](templates/architecture-deepening-template.md)：记录 deepening candidate。
+- `CONTEXT.md`：沉淀领域术语。
+- `docs/adr/`：记录硬以回滚、非显而易见、存在真实取舍的架构决策。
+
+架构讨论必须使用统一术语：`module`、`interface`、`seam`、`adapter`、`depth`、`leverage`、`locality`。
+
+---
+
+## AI-Human Loop
+
+```
+需求 → AI 3方案对比 → 架构师选方向 → AI 详细方案
+→ AI 六维预审 → 架构师签字 → ADR 记录 → 进入实现
+```

package/template/docs/architecture/templates/architecture-deepening-template.md

@@ -0,0 +1,64 @@
+# 架构深化提案：<模块 / 概念>
+
+## 候选项
+
+| 字段 | 值 |
+|---|---|
+| 领域概念 | |
+| 当前模块 | |
+| 建议模块 | |
+| 推荐强度 | 强烈建议 / 值得探索 / 推测性建议 |
+
+## 当前摩擦点
+
+说明当前结构为什么偏浅，或为什么难以维护。
+
+使用 `codebase-design` 术语：
+
+- Module:
+- Interface:
+- Seam:
+- Adapter:
+- Depth:
+- Leverage:
+- Locality:
+
+## 调整前
+
+```mermaid
+flowchart LR
+    A[调用方] --> B[浅模块]
+    A --> C[分散逻辑]
+```
+
+## 调整后
+
+```mermaid
+flowchart LR
+    A[调用方] --> B[深模块接口]
+    B --> C[隐藏在 seam 后的实现]
+```
+
+## 建议接口
+
+说明调用方需要了解的最小接口，包括不变量、顺序约束、错误模式和性能预期。
+
+## 依赖策略
+
+- 进程内依赖：
+- 可本地替换依赖：
+- 远程但自有依赖：
+- 真正外部依赖：
+
+## 测试策略
+
+- 主要测试 seam：
+- 需要删除或替换的测试：
+- 需要新增的测试：
+
+## ADR / 上下文影响
+
+- [ ] 更新 `CONTEXT.md`
+- [ ] 创建 ADR
+- [ ] 重新打开或修订现有 ADR
+- [ ] 不需要持久化文档