agentic-flow-kit 2.0.0 → 2.1.0

package/templates/profiles/typescript/AGENTS.md

@@ -0,0 +1,52 @@
+# Repository Guidelines
+
+{{projectName}}。{{stackDescription}}。
+
+## 1. 运行时联通 (Runtime Connectivity)
+前端 dev {{webPort}} 连 API `http://localhost:{{apiPort}}`；API 须监听 {{apiPort}} 才联通。端口/工具缺陷/可执行文件解析机理等环境事实见 `.agents/notes/runtime-env.md` §6；各机绝对路径与版本自登记 `.agents/notes/runtime-env.local.md`。
+
+## 2. 本地 Clone 必做 (Local Setup)
+> 漏配则门禁静默失效，详见 `.agents/notes/runtime-env.md` §7。
+- `git config core.hooksPath .githooks` 挂仓库自带钩子。
+- `git config merge.ours.driver true` 启用声明为 `merge=ours` 的合并保护。
+- `git config merge.jsonl-union.driver "node .agents/scripts/git-merge-jsonl.mjs %O %A %B"` 启用 `.agents/*.jsonl` 并集合并策略。
+- **禁令**：commit / merge / push 三处一律禁 `--no-verify`。
+- **自检**：`node .agents/scripts/check-local-gates.mjs --fix`
+
+## 3. 全局红线 (Universal Laws)
+- **安全/隐私**：不提交密钥、令牌、`.env` 或真实用户数据；发现敏感信息立即停止扩散。
+- **不可逆操作**：默认不执行生产部署、远程推送、数据删除等操作 → 须用户明确要求且不得绕过门禁。
+- **最小改动**：优先做满足需求的最小改动，禁止顺手重构无关代码、修改格式或修复无关 Lint 警告。
+- **单源纪律**：路径 / 版本 / 缺陷等环境事实只登记于 `.agents/notes/runtime-env.md` §6，别处禁止复制原文。
+- **上下文纪律**：批量取数、长日志、大 diff、全仓盘点交子代理，主线只收结论摘要与 `file:line`；子代理回报写结论与证据路径，禁把原始输出整段搬回主线。
+- **提交规范**：Conventional Commits，类型限 `feat/fix/docs/style/refactor/perf/chore`。
+
+## 4. 阶段路由表 (Workflow Routing)
+按任务类型跳转对应指令文件：
+
+| 任务类型 | 指令文件 | 核心职责 |
+|---|---|---|
+| **L0 极简道** | `.agents/commands/new-task.md` | 全机器可判的极小改动，与 L1 同走快速道：改码 → `verify --face`/`--scope` → 单笔 commit |
+| **L1 快速道** | `.agents/commands/new-task.md` | 定级、实现、`verify --scope`、单笔关单（仅独立关单场景开技能）。不打开 `stages.md` |
+| **新需求 / 功能** | `.agents/commands/new-task.md` | L1 走快速道；L2/L3 才进 `stages.md` |
+| **L2/L3 阶段流** | `.agents/commands/stages.md` | 四章 Plan→Design→Build→Test：立 intent → 起 spec → 起 plan + 实现 → 静态门 → UI 实测 → 独立复核 → 关单 |
+| **修复 / 事故** | `.agents/commands/maintain.md` | L1 非事故只做 §1 立档后回快速道。线上事故与 L2/L3 读全文 |
+| **上线 / 发布** | `.agents/commands/deploy.md` | 静态门 → 回归检查（含 DB 验证）→ 授权 → PR 审查合并 |
+| **合入评审** | `.agents/commands/review.md` | P0/P1/P2 分级评审 → 结论定性 |
+| **自动化驱动** | `.agents/commands/pipeline-run.md` | 实验位保留待用：状态机尚未验证、零 run 记录，启用前须补状态机测试 |
+| **无人值守 / 过夜** | `.agents/skills/autonomous-run/SKILL.md` | 长跑合同：逐单元签收 + 停机条件；门禁与确认门不豁免 |
+| **性能 / 视觉对齐** | `.agents/skills/perf/SKILL.md` · `.agents/skills/visual-parity/SKILL.md` | 先基线后单变量；像素对齐只改样式 |
+
+> **纠偏短名**：任务中途报短名即可，索引 `.agents/config/principles.md`。
+
+> **引擎面豁免**：改 AI-Native 治理引擎自身，**豁免工作流三件套**——不生成 intents/specs/plans、不走确认门，Conventional Commits 直接变更。引擎面 = `.agents/` 全部、`.githooks/`、`azure-pipelines.yml`、workflow/ 模板与台账、根 `package.json`、宿主适配目录；其中本机私有宿主目录不入库。**wiki 豁免**：调整 `wiki/` 知识文档内容（含 INDEX 与看板）同享上述豁免。**边界**：git 钩子与静态门照常执行；删除 wiki 文件仍须用户单独指令；数据维护 SQL 的**执行**不豁免。
+
+## 5. 目录级规则 (Directory-level Rules)
+**禁止回填本文档**。具体实现细节请查阅对应目录的 `AGENTS.md`：
+- **后端**: `backend/AGENTS.md`
+- **前端**: `frontend/AGENTS.md`
+- **成对文档同步**：按 `wiki/INDEX.md` 登记的成对文档，修改任一份须同步另一份，并同步更新 `wiki/INDEX.md` 与 `wiki/知识沉淀总览.html`。
+
+## 6. 项目适配区 (Project Adaptations)
+- **构建/测试/类型检查**: 命令清单单源 `.agents/hooks/commit-check.config.json`。
+- **冒烟探活**: 脚本路径与端点判定事实见 `.agents/notes/runtime-env.md` §6.1。

package/templates/scaffold/workflow/INDEX.md

@@ -11,3 +11,19 @@
 ## 档案（只读，不增量）
 
 （历史终态件归档后由生成器列出。）
+
+<!-- GENERATED:BEGIN — gen-workflow-index.mjs 整段重写，手工说明写在本行之前 -->
+
+## 活跃（0）
+
+| 类型 | 级别 | 状态 | 日期 | 模块 | 标题 | 验收 |
+|---|---|---|---|---|---|---|
+
+## 档案计数（0，不进表）
+
+| 类型 | 模块 | 数量 |
+|---|---|---|
+
+终态构成：；查档案用 `node .agents/scripts/kb-search.mjs "<词>" --status all`。
+
+<!-- GENERATED:END -->

package/templates/scaffold/workflow/README.md

@@ -25,6 +25,8 @@
 
 **门禁判定月度分片**（2026-10-22 gate-metrics-shard）：`workflow/gate-metrics.d/<YYYY-MM>.jsonl` 每月一行（规则 × WARN/BLOCK），由 `node .agents/scripts/agg-judgments.mjs --emit-month` 生成、随提交入库；pre-push 月检自动补生成上月分片。退役判据（连续 N 月 = 0）读「本地 `.agents/judgments.jsonl` ∪ 分片」取 max——换机/换 worktree 不再归零，多机并集（`.gitattributes` 复用 `jsonl-union`）。
 
+**主张账**（按月追加）：`workflow/claims.d/<YYYY-MM>.jsonl` 记「未来会话可能当真的一句话」及其在仓库里的原文。追加用 `node .agents/scripts/claims.mjs add`；`recheck` 只报告原文还在不在，退出码恒 0，不是门，也不改账里的历史行。合并走 `jsonl-union`。
+
 ## 使用方式
 
 - **发起新任务**：执行 `.agents/commands/new-task.md`（定级 + L0 极简道 / L1 快速道总入口）；L2/L3 进 `.agents/commands/stages.md` 四章（Plan → Design → Build → Test，2026-11-08 档 2-F 四并一）

package/templates/scaffold/workflow/artifact-sources.md

@@ -0,0 +1,25 @@
+# 工件真相源（Source of Truth）
+
+> 背景（Anthropic AI-native SDLC）：每个工件必须指定**唯一**真相源，其他系统只存副本或链接。
+> 否则 Jira / Confluence / Figma / 变更单与仓库文档会互相漂移，agent 会读到两份“真相”。
+>
+> 用法：开工前查本表；新增工件类型必须先登记。没有登记的工件，默认以仓库 markdown 为准。
+
+| 工件 | 唯一真相源 | 其他系统怎么放 | 谁维护 | 过期信号 |
+|---|---|---|---|---|
+| intent（要什么） | `workflow/intents/` markdown | Jira/需求工具存链接 + 摘要；评审记录在链接里 | 产品 owner | 状态仍 draft 超过约定天数 |
+| spec（决定什么） | `workflow/specs/` markdown | Confluence 只放链接，不复制正文 | 产品 + 技术 lead | 与 intent 的验收判据不一致 |
+| plan（怎么做） | `workflow/plans/` markdown | PR 描述引用路径；不另写一份 | 实现者 | 合并 diff 与 plan 文件清单不一致 |
+| 代码与测试 | git 仓库 | 任何外部系统只读镜像 | 工程 | 镜像落后一个提交 |
+| 评审结论 | PR / `workflow/reviews.d/` | 评审工具存链接或事件 id | 复核者 | 意见无采纳/拒绝结论 |
+| 事故与复盘 | `workflow/incidents/` | 事故平台存链接 + 影响面摘要 | on-call + owner | 复盘三件套缺一 |
+| 领域知识 | `wiki/` markdown | `wiki/` HTML 只是展示快照 | wiki owner | HTML 与 md 不一致 |
+| 记忆主张 | `workflow/claims.d/` | 不复制；其他文档引用 claim id | 主智能体 | 引用的原文已消失（broken） |
+| 行为评测 | `.agents/evals/results.jsonl` | CI 报告存链接 | 平台/引擎 owner | 凭证过期或签名不匹配 |
+
+## 迁移到 AI-native 时
+
+1. 先逐项填本表，再动流程；没有“唯一源”的工件不要开始自动化。
+2. 旧系统（Jira/Figma/变更委员会）不能立刻下线时，**仓库为源、旧系统为链接**，并在旧系统字段里写清“以 commit/path 为准”。
+3. 反向选择（旧系统为源）只有在审计/监管强制时才用；此时仓库文档必须带 `source: <系统>#<id>`，且不复制正文。
+4. 任何“两份都像真的”状态都按缺陷处理，登记 papercut。

package/templates/scaffold/workflow/non-engineer-intent.md

@@ -0,0 +1,51 @@
+# 非工程角色：写一份 intent
+
+> 目标：产品 / 业务 / 运营不需要 git 或命令行，也能产出下一阶段能直接读的 `intent.md`。
+> 产出的文件仍以仓库为真相源；本文只负责“怎么进来”。
+
+## 最简路径（claude.ai / Cowork）
+
+1. 在会话里用自己的话描述：**谁遇到了什么问题、现在不能做什么、什么算变好、什么不在范围内**。不需要正式格式。
+2. 让 Claude 按下面模板写成 `intent.md`；它会补问范围、用户、约束、成功判据。
+3. 你逐条纠正它理解错的地方。**作者与时间**必须保留。
+4. 让 Claude 通过 GitHub 连接器把文件提交到仓库的 `workflow/intents/<英文-kebab>.md`。
+   不会 git 也没关系：连接器负责提交；你只需要确认文件名与内容。
+5. 产品 owner 在仓库里把状态从 `draft` 改为 `approved`（或打回）。
+
+## 模板
+
+```md
+# Intent: <一句话标题>
+Author: <姓名/角色>  Status: draft
+Date: <YYYY-MM-DD>
+
+## 问题
+<谁、在什么场景、现在不能做什么；有数字更好>
+
+## 期望结果
+<可观察的“变好”是什么>
+
+## 受影响的人与系统
+<用户/岗位/模块/接口>
+
+## 约束
+<不能新增 PII、必须复用现有认证、上线窗口……>
+
+## 非目标
+<明确不做什么，防止范围蔓延>
+
+## 开放问题
+<需要谁拍板；没有写“无”>
+```
+
+## 红线
+
+- 不写实现方案（那是 spec/plan 的事）；只写要什么、为什么、约束。
+- 不在 intent 里贴密钥、真实用户数据或内部链接凭据。
+- 状态只能由产品 owner 改；agent 不自行把 draft 改成 approved。
+- 一个 intent 只解决一个问题；拆得开就拆。
+
+## 技术侧配合
+
+- 仓库里跑 `node .agents/scripts/fill-intent.mjs` 可生成骨架（有引擎时）。
+- 进入 Design 前，产品 owner 必须回答 open questions 或明确“带问进入”。