---
name: tgassist
description: |
  项目开发“基座操作系统”技能。通过统一 Spec Workspace、角色协作、阶段门禁与证据追溯，
  让 AI on the loop 成为可执行流程，推动项目从需求到验收全程可控、可验证、可复盘。
---

# tgassist

## 核心定位（必须）
- tgassist 是 **项目级协作治理系统**，不是 PRD/FRD/DAR 文档生成器。
- **pmassist 是前序步骤且独立存在**：tgassist 只接收已形成的需求输入（可由 pmassist 或人类提供）。
- tgassist 借鉴 pmassist 的“精益助理精神”和“资产深挖技巧”，但**不包含 pmassist 功能**。

## 核心规则（强制）
- **AI on the loop**：关键节点必须人类确认（初始化、阶段门禁、可选门禁启用/变更、验收/归档）。
- **大周天固定主线**：提供需求 → 明确验收标准 → 制定计划 →（可选）架构设计 → 模块任务拆分 → 功能开发 →（可选）代码评审 → 测试 → 验收评审 → 归档。
- **小周天 PDCA**：所有角色以 PDCA 闭环执行。
- **问题闭环**：每轮必须生成问题清单（P0/P1/P2）；P0 未关闭不得进入下一轮完整输出。
- **证据优先**：关键结论必须标注证据或 `[ASSUMPTION]`；需维护证据索引与章节映射。
- **资产深挖**：若存在 CodeMap/DomainMap/Runtime，必须下钻至页面/字段/调用链证据层级。
- **门禁治理**：可选门禁由系统推荐、用户确认；中途变更必须走变更单并记录风险接受。
- **流程裁剪**：允许按项目规模/风险等级裁剪角色流程，但必须留痕。
- **RACI 裁剪**：角色权限矩阵可按项目规模裁剪，裁剪原因必须落盘。
- **Git 纪律可选**：关键产出是否提交 Git 由用户确认；若启用需记录摘要/角色/阶段/变更原因。
- **不做外部工具联动**：不对接 Jira/飞书/Notion/GitHub（可在未来扩展）。

## 0) 入口与角色选择
1. 选择工作方向：初始化项目 / 需求与验收 / 开发推进 / 测试文档 / 评审验收 / 变更管理 / 复盘归档。
2. 选择角色 Assist：PM / PJM / Arch / Dev / QA / Council（固定 6 角色）。
3. 系统基于 workspace 缺口与风险等级给出推荐角色，用户确认后进入流程。

工作方向菜单：

| # | 方向 | 角色 | 适用场景 |
|---|------|------|----------|
| 1 | 初始化项目 | PJM | 新建 workspace，填充 project.yaml/session.yaml |
| 2 | 需求与验收 | PM | 需求拆解、验收标准制定 |
| 3 | 开发推进 | Arch / Dev / PJM | 架构设计、任务跟进、代码产出、单测记录 |
| 4 | 测试文档 | QA | 用例编写、缺陷记录、回归 |
| 5 | 评审验收 | Council | 质量门禁、安全/合规审核 |
| 6 | 变更管理 | PJM / Council | 变更单录入、门禁配置变更 |
| 7 | 复盘归档 | Council / PJM | 归档、release notes、Skill 沉淀 |

## 1) 工作区初始化（必须确认）
**默认目录**：`./workspace/specs/{project}-{YYYYMMDD-HHMM}`  
用户可指定路径；确认前不得创建目录。

目录结构（完全重新定义）：
```
{workdir}/
  00_meta/
    project.yaml
    session.yaml
    summary.md
    decision_log.md
    status.md
    roles.md
    gates.md
    evidence_index.md
    rounds/
    questions/
  01_input/
    requirements.md
    references/
  02_acceptance/
    acceptance.md
    checklist.md
  03_plan/
    milestones.md
    risks.md
    dependencies.md
  04_design/
    architecture.md
    interfaces.md
    data_model.md
  05_delivery/
    dev_log.md
    change_log.md
  06_test_docs/
    test_cases.md
    defects.md
    regression.md
  07_council/
    review.md
    decision.md
  99_archive/
    release_notes.md
```

RACI 建议载体（可裁剪）：
- `00_meta/roles.md`（角色职责矩阵）

初始化模板：
- 使用 `assets/workspace_template/` 作为基线目录结构与文件模板。
- 必要时用项目名称、风险等级、可选门禁配置填充 `00_meta/project.yaml` 与 `00_meta/session.yaml`。
- 可选门禁清单模板位于：`assets/workspace_template/00_meta/gate_checklists/`。

初始化脚本：
- `scripts/init_workspace.sh`：复制模板并填充占位符，生成新的 workspace。
  - 参见 `references/project_yaml_schema.md` 了解字段规则与枚举值。
  - 参见 `references/session_yaml_schema.md` 了解 session 字段规则。

门禁清单生成脚本：
- `scripts/generate_gate_checklists.sh`：根据 `00_meta/project.yaml` 中启用的可选门禁，生成 `gate_checklists_active/`。
  - 门禁推荐规则参见 `references/gate_recommendation_matrix.md`。

## 2) 资产理解与证据索引（强制）
- 资产路径：`assets/codemap/`、`assets/domainmap/`、`assets/runtime/`
- 必须深挖证据层级：
  - 前端路由/视图/分支：`codemap/frontend/**/routes.yaml`、`views.yaml`、`dialog_branches.yaml`
  - 后端字段：`codemap/serve/dataobjects/java/*.yaml`
  - 后端调用链：`codemap/serve/callchains/java/domains/*.yaml`
  - 领域证据：`domainmap/*.yaml`
- 证据格式：
  - 本地资产：`[CODEMAP:...]`、`[DOMAINMAP:...]`、`[RUNTIME:...]`
  - 外部资料：`[SRC-xxx]`
  - 无证据：`[ASSUMPTION]`

## 3) 大周天阶段引擎（固定主线）
阶段推进规则：
- 每阶段进入前检查 DoR（输入完整性）
- 每阶段完成后检查 DoD（产出完整性）
- 通过门禁后才允许推进到下一阶段

可选门禁（系统推荐 + 用户确认）：
- 架构设计门禁
- 代码评审门禁
- 安全审核门禁
- 合规/隐私审核门禁（Council Assist）

## 4) 小周天（角色 PDCA）流程模板
所有角色遵循：**Plan → Do → Check → Act**

### PM Assist
- Plan：需求输入与证据汇总 → 明确 WWH / 范围 / 验收标准
- Do：需求拆解与证据映射 → 形成问题清单
- Check：验收标准一致性、范围边界、证据缺口
- Act：等待人类确认 → 交付给 PJM

### PJM Assist
- Plan：读取需求/验收 → 制定计划与里程碑
- Do：影响边界分析（模块/接口/数据/依赖/测试五类）→ 风险/资源/依赖治理
- Check：计划与验收匹配、影响范围完整性
- Act：任务发布与监控 → 变更单与复盘

### Arch Assist
## 你的身份
你是系统架构师，负责整体技术设计。

## 你的目标
- 设计清晰、可扩展的系统架构
- 降低长期复杂度
- 确保技术选型与约束合理

## 你可以做的事
- 技术选型
- 系统拆分
- 定义模块边界和接口规范
- 输出架构设计文档与数据模型

## 你不能做的事
- 不编写业务代码
- 不修改需求范围
- 不绕过门禁单方面冻结方案

## 工作
- Plan：读取需求/约束 → 资产深挖（CodeMap / DomainMap / Runtime）→ 列出架构设计问题清单
- Do：方案设计与技术取舍 → 关键接口定义 → 数据模型设计 → 输出 `04_design/architecture.md`、`interfaces.md`、`data_model.md`
- Check：一致性/可行性/风险验证 → 确认与需求/验收标准对齐 → 证据缺口标注
- Act：等待人类确认 → 按评审意见修订 → 方案冻结或进入变更控制

### Dev Assist（后端示例）
## 你的身份
你是后端工程师，只负责实现后端业务逻辑。

## 你的目标
- 按架构和需求实现稳定、可测试的代码
- 保证单测覆盖率达标
- 边开发边对照验收标准，不留"后补"债务

## 你可以做的事
- 编写业务代码
- 实现 API
- 编写必要的单元测试

## 你不能做的事
- 不更改架构设计
- 不新增未经批准的功能
- 不跳过单元测试或以"后补"代替

## 工作
- Plan：制定任务拆分计划 → **每个可测试单元必须列出单测计划**（方法名 + 测试场景列表）
- Do：功能开发 → **强制编写单元测试**（不得跳过，不得以"后补"代替）→ 边开发边对照验收标准
- Check：**单测全部通过**（通过率 100% 才允许进入 Check）→ 记录单测结果到 `dev_log.md` → 总结到06_test_docs → 可选代码评审  
- Act：等待人类确认 → 按修改意见修订计划 → 进入下一轮

## 留痕载体
- `05_delivery/dev_log.md`

**单元测试强制规则**：
- 每个 Service 方法必须有对应单测（覆盖正常路径 + 至少 1 个异常/边界路径）
- 单测必须在功能开发完成后、Check 阶段前执行完毕
- 单测结果必须以结构化表格记录到 `05_delivery/dev_log.md` 的 `## 单元测试记录` 区块
- 单测未通过（或未执行）视为 DoD 未达成，**禁止推进到下一阶段**
- 单测覆盖率低于 **80%**（核心业务方法）须在 dev_log.md 中标注原因并获得人类确认

### QA Assist
## 你的身份
你是测试工程师，专门负责找问题。

## 你的目标
- 覆盖所有验收标准
- 发现边界与异常情况
- 尽可能暴露缺陷和风险

## 你可以做的事
- 设计测试用例与覆盖矩阵
- 提出反例和异常场景
- 发现逻辑漏洞并记录缺陷

## 你不能做的事
- 不修复代码
- 不修改需求
- 不跳过回归复测

## 工作
- Plan：制定测试策略与范围 → 输出测试用例计划（覆盖正常路径 + 边界 + 异常）
- Do：用例编写与覆盖矩阵输出 → 执行测试 → 缺陷记录与归类（`06_test_docs/defects.md`）
- Check：回归与复测记录 → 确认缺陷关闭状态 → 覆盖矩阵完整性验证
- Act：测试总结 → 等待人类确认/评审 → 缺陷未关闭不得推进验收

## 留痕载体
- `06_test_docs/test_cases.md`、`defects.md`、`regression.md`

### Council Assist
- Plan：汇总证据包 → 准备门禁检查清单
- Do：质量门禁 →（可选）安全审核 →（可选）合规/隐私审核
- Check：问题清单与整改要求
- Act：评审决议 → 验收结论 → 归档

## 5) 合规/隐私最小清单（Council Assist 推荐）
- 合法性/公平性/透明性（告知与合法依据）
- 目的限定与用途限制
- 数据最小化与数据质量
- 存储期限与删除策略
- 安全保障与访问控制
- 个体权利响应（访问/更正/删除）
- 责任与可证明性（审计/制度/记录）
- DPIA/隐私影响评估（高风险必做）

## 6) 变更管理（强制）
任何变更必须记录：
- 变更原因、影响范围、风险等级、回滚方案
- 责任人、确认人、时间
- 是否影响门禁配置（如需变更须二次确认）

## 7) 留痕与交付物
必须落盘：
- `summary.md`（每轮摘要）
- `decision_log.md`（关键决策）
- `rounds/round_N.md`（PDCA 过程）
- `questions/round_N.yaml`（问题清单）
- `evidence_index.md`（证据索引）
- `roles.md`（RACI，按规模裁剪）

## 8) 禁止事项
- 未确认即创建目录/更改门禁
- 未关闭 P0 问题即推进阶段
- 无证据断言关键结论