npm - @haaaiawd/anws - Versions diffs - 1.2.1 → 1.2.2 - Mend

@haaaiawd/anws 1.2.1 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/lib/init.js CHANGED Viewed

@@ -161,7 +161,7 @@ function printNextSteps() {
   blank();
   info('Next steps:');
   info('  1. Read .agent/rules/agents.md to understand the system');
-  info('  2. Run /genesis in your AI assistant to start a new project');
+  info('  2. Run /quickstart in your AI assistant to analyze and start the workflow');
 }
 /**

package/package.json CHANGED Viewed

@@ -1,13 +1,17 @@
 {
   "name": "@haaaiawd/anws",
-  "version": "1.2.1",
-  "description": "Antigravity Workflow System CLI — one command to install AI collaboration workflows into your project",
+  "version": "1.2.2",
+  "description": "A spec-driven workflow framework for AI-assisted development. Empowers prompt engineers to build production-ready software through structured PRD → Architecture → Task decomposition. Designed for Antigravity to enforce design-first principles and prevent architectural drift in vibe coding.",
   "keywords": [
-    "ai",
-    "workflow",
-    "agent",
-    "cli",
-    "developer-tools"
+    "antigravity",
+    "agentic-ai",
+    "workflow-orchestration",
+    "spec-driven",
+    "system-architecture",
+    "vibe-coding",
+    "prompt-engineering",
+    "devops-for-ai",
+    "skills-framework"
   ],
   "homepage": "https://github.com/Haaaiawd/Antigravity-Workflow-System",
   "repository": {
@@ -30,6 +34,8 @@
   ],
   "main": "./lib/index.js",
   "scripts": {
+    "sync": "node scripts/sync-assets.js",
+    "prepublishOnly": "npm run sync",
     "test": "node --test test/**/*.test.js"
   },
   "dependencies": {}

package/templates/.agent/skills/git-forensics/scripts/__pycache__/git_forensics.cpython-313.pyc ADDED Viewed

Binary file

package/templates/.agent/skills/system-designer/references/system-design-detail-template.md CHANGED Viewed

@@ -1,15 +1,14 @@
-# {System Name} — 实现细节 (detail)
+# {System Name} — 实现细节 (L1)
-> **文件性质**: L1 实现层
-> **对应 L0**: [`{system}.md`](./{system}.md)
-> 本文件仅在 `/forge` 任务的 `**输入**` 字段明确引用时加载。
-> 日常阅读、系统概览、任务规划请优先阅读 L0 层文件。
+> **文件性质**: L1 实现层 · **对应 L0**: [`{system-id}.md`](./{system-id}.md)
+> 本文件仅在 `/forge` 任务明确引用时加载。日常阅读和任务规划请优先看 L0。
+> **⚠️ 孤岛检查**: 本文件各节均须在 L0 有对应超链接入口，禁止孤岛内容。
 ---
 ## 版本历史
-> 所有版本变更记录集中于此，不再散落在代码注释中。
+> 所有变更记录集中于此，不再散落在代码注释里。
 | 版本 | 日期         | Changelog |
 | ---- | ------------ | --------- |
@@ -17,28 +16,38 @@
 ---
+## 本文件章节索引
+|   §   | 章节                                                                 |   对应 L0 入口   |
+| :---: | -------------------------------------------------------------------- | :--------------: |
+|  §1   | [配置常量](#1-配置常量-config-constants)                             |  L0 §6 数据模型  |
+|  §2   | [完整数据结构](#2-核心数据结构完整定义-full-data-structures)         |  L0 §6 数据模型  |
+|  §3   | [核心算法伪代码](#3-核心算法伪代码-non-trivial-algorithm-pseudocode) | L0 §5 操作契约表 |
+|  §4   | [决策树详细逻辑](#4-决策树详细逻辑-decision-tree-details)            |   L0 §4 架构图   |
+|  §5   | [边缘情况与注意事项](#5-边缘情况与注意事项-edge-cases--gotchas)      |    L0 §5 / §9    |
+|  §6   | [测试辅助](#6-测试辅助-test-helpers) *(可选)*                        | L0 §11 测试策略  |
+---
 ## §1 配置常量 (Config Constants)
 > 所有硬编码配置、枚举映射、查找表集中放在此处。
+> **L0 对应入口**: L0 §6 末尾锚点 → *配置常量字典详见 [L1 §1]*
 ```python
 # ── 示例: 单位配置表 ──
-# 每行格式: UnitType: {atk, def, hp, mov, range, cost, tech, behavior, move_type}
 UNIT_CONFIG = {
-    # UnitType.WARRIOR: {...},
-    # ...
+    # UnitType.WARRIOR: {atk, def, hp, mov, range, cost, tech, behavior, move_type}
 }
 # ── 示例: 地形配置表 ──
 TERRAIN_CONFIG = {
     # TerrainType.PLAIN: {move_cost: 1, passable: "land", buildings: [...]}
-    # ...
 }
 # ── 示例: 建筑配置表 ──
 BUILDING_CONFIG = {
     # BuildingType.FARM: {cost: 5, tech: "farming", rp_bonus: 1}
-    # ...
 }
 ```
@@ -46,11 +55,10 @@ BUILDING_CONFIG = {
 ## §2 核心数据结构完整定义 (Full Data Structures)
-> 包含方法实现的完整类定义（L0 层只放无方法的属性声明）。
+> 含方法体的完整类定义。L0 层只放属性声明和方法签名（`def foo(): ...`）。
+> **L0 对应入口**: L0 §6.1 末尾锚点 → *完整方法实现详见 [L1 §2]*
 ```python
-# ── 示例: 完整类定义（含方法） ──
 @dataclass
 class ExampleEntity:
     id: str
@@ -58,7 +66,7 @@ class ExampleEntity:
     def some_method(self) -> bool:
         """方法说明"""
-        # 完整逻辑...
+        # 完整实现逻辑
         pass
 ```
@@ -67,42 +75,30 @@ class ExampleEntity:
 ## §3 核心算法伪代码 (Non-Trivial Algorithm Pseudocode)
 > [!IMPORTANT]
-> **严格准入门槛 — 不满足任意一条，禁止写入本节**:
+> **准入门槛 — 不满足任意一条，禁止写入本节**
 >
 > | 准入条件 | 说明 |
 > |---------|------|
-> | 函数体估计 **> 15 行** | 短函数的意图从 L0 操作契约表格已可理解，不需要伪代码 |
-> | 含**不明显的业务规则** | 如战斗伤害公式、路径寻找、状态机分支、复杂校验逻辑 |
-> | 含**多步骤副作用链** | 如"A→检查→B→更新C→触发D"且顺序不能颠倒 |
-> | **同事看签名猜不出实现** | 若函数名+参数名已能清楚表达意图，则不需要伪代码 |
->
-> **反例（禁止写入 §3）**:
-> ```python
-> # ❌ 太简单，不需要伪代码
-> def get_nation_stars(nation: Nation) -> int:
->     return nation.stars
->
-> # ❌ 5行setter，从签名已可理解
-> def set_military_target(self, target: str) -> None:
->     self.military_target = target
->     self.last_updated_turn = world.turn
-> ```
+> | 函数体估计 **> 15 行** | 短函数从 L0 操作契约表已可理解 |
+> | 含**不明显的业务规则** | 伤害公式、状态机分支、复杂校验 |
+> | 含**多步骤副作用链** | A→检查→B→更新C→触发D，顺序不可颠倒 |
+> | **同事看签名猜不出实现** | 函数名+参数已能清楚表达意图则不需要 |
-每个小节对应 L0 操作契约表格中的一行，提供完整函数体。
+每个小节对应 L0 §5 操作契约表的一行，提供完整函数体。
 ### §3.1 {操作名称}
-**对应契约**: L0 §{章节} 操作契约表 — `{function_name}()`
-**准入理由**: {为什么这个函数需要伪代码，满足了哪条准入条件}
+**对应契约**: L0 §5.1 — `{function_name}()`
+**准入理由**: {满足了哪条准入条件}
 ```python
-def function_name(param1: Type, param2: Type, ...) -> ReturnType:
+def function_name(param1: Type, param2: Type) -> ReturnType:
     """
     函数说明。
     前置条件:
     1. ...
     副作用:
     - ...
     """
@@ -110,37 +106,23 @@ def function_name(param1: Type, param2: Type, ...) -> ReturnType:
     pass
 ```
-**关键设计注意事项**:
-- 注意点1 (如: 深拷贝、竞争条件、顺序依赖等)
----
-### §3.2 {操作名称}
-```python
-# ...
-```
+> **注意事项**: {深拷贝 / 竞争条件 / 顺序依赖等关键陷阱}
 ---
 ## §4 决策树详细逻辑 (Decision Tree Details)
-> 对应 L0 层 Mermaid 决策树的文字展开 + 完整伪代码。
+> 对应 L0 Mermaid 决策图的文字展开 + 完整伪代码。
+> **L0 对应入口**: L0 §4 架构图注释 → *完整决策逻辑见 [L1 §4]*
 ### §4.1 {决策场景名称}
-**对应 L0 Mermaid**: `{system}.md §{章节}`
+**对应 L0 Mermaid**: `{system-id}.md §{章节}`
 ```python
 def plan_or_decide(...):
-    """
-    决策逻辑完整实现。
-    """
     # Step 1: 检查高优先级条件
-    # ...
     # Step 2: 分支逻辑
-    # ...
     pass
 ```
@@ -148,17 +130,18 @@ def plan_or_decide(...):
 ## §5 边缘情况与注意事项 (Edge Cases & Gotchas)
-> 实现时必须处理的非显而易见的情况。
+> 实现时必须处理的非显而易见情况。
+> **L0 对应入口**: L0 §5 或 §9 安全性章节的锚点
 | 场景           | 风险       | 处理方式       |
 | -------------- | ---------- | -------------- |
 | {边缘情况描述} | {潜在 Bug} | {正确处理方式} |
-### §5.1 {具体边缘情况}
+### §5.1 {具体情况}
 ```python
-# ❌ 错误做法 (会导致什么问题)
-# cloned_unit.embarked_unit = unit.embarked_unit  # 浅拷贝导致状态污染!
+# ❌ 错误做法
+# cloned_unit.embarked_unit = unit.embarked_unit  # 浅拷贝 → 状态污染!
 # ✅ 正确做法
 # cloned_unit.embarked_unit = deepcopy(unit.embarked_unit) if unit.embarked_unit else None
@@ -168,31 +151,37 @@ def plan_or_decide(...):
 ## §6 测试辅助 (Test Helpers)
-> 单元测试中复用的工厂函数、fixtures 或测试场景说明。
+> 可选。单元测试中复用的工厂函数或 fixtures。
+> **L0 对应入口**: L0 §11 测试策略锚点
 ```python
-# 示例: 测试用工厂函数
-def make_test_unit(type=UnitType.WARRIOR, hp=10, pos=(0,0)) -> Unit:
-    """创建测试用 Unit 对象"""
+def make_test_unit(type=UnitType.WARRIOR, hp=10, pos=(0, 0)) -> Unit:
+    """创建测试用 Unit"""
     pass
 def make_test_world(size=8) -> World:
-    """创建测试用 World 对象"""
+    """创建测试用 World"""
     pass
 ```
 ---
-<!-- ⚠️ 使用指南
-**何时填写本文件**:
-- 触发了 R1-R5 任意一条提取规则时
-- L0 的操作契约表对应的实现需要 > 30 行伪代码时
-**§ 编号约定**:
-- §1 配置常量: 始终是第一节
-- §2 数据结构: 含方法的完整类
-- §3 算法伪代码: 按照函数顺序编号 (§3.1, §3.2...)
-- §4 决策树展开: 对应 L0 Mermaid 图的文字版
-- §5 边缘情况: 从文档注释中提取的 "# ⚠️ 注意" 类内容
-- §6 测试辅助: 可选
+<!-- ⚠️ AGENT 使用指南
+何时创建本文件: 触发 L0 拆分规则 R1-R5 任意一条时。
+  R1 单个代码块 > 30 行
+  R2 代码块总行数 > 200 行
+  R3 配置常量字典条目 > 5 个
+  R4 版本内联注释 > 5 处
+  R5 文档总行数 > 500 行
+孤岛检查: 本文件每新增一节，必须同步在 L0 对应位置添加超链接锚点。
+§ 编号约定:
+  §1 配置常量  — 始终第一节
+  §2 数据结构  — 含方法体的完整类
+  §3 算法伪代码 — 按函数顺序编号 (§3.1, §3.2 ...)
+  §4 决策树    — 对应 L0 Mermaid 图的展开
+  §5 边缘情况  — 从代码注释中提取的 "# ⚠️ 注意" 类内容
+  §6 测试辅助  — 可选
 -->

package/templates/.agent/skills/system-designer/references/system-design-template.md CHANGED Viewed

@@ -1,16 +1,44 @@
 # {System Name} 系统设计文档 (L0 — 导航层)
-**System ID**: {system-id} (如: frontend-system, backend-api-system)
-**Project**: [Project Name]
-**Version**: 1.0
-**Status**: Draft | Review | Approved
-**Author**: [Author Name or Agent]
-**Date**: [YYYY-MM-DD]
-> **📖 文档层级说明**
-> - **本文件 (L0)**: 导航层。包含架构图、操作契约表、设计决策。面向快速理解与任务规划。
-> - **[{system}-detail.md](./{system-id}.detail.md) (L1)**: 实现层。包含完整伪代码、配置常量、边缘情况。仅在 `/forge` 任务明确引用时加载。
-> - **L1 文件按需创建**：触发拆分规则 R1-R5 任意一条时，才需要创建对应的 `.detail.md`。
+| 字段          | 值                                                                    |
+| ------------- | --------------------------------------------------------------------- |
+| **System ID** | `{system-id}`                                                         |
+| **Project**   | {Project Name}                                                        |
+| **Version**   | 1.0                                                                   |
+| **Status**    | `Draft` / `Review` / `Approved`                                       |
+| **Author**    | {Author Name or Agent}                                                |
+| **Date**      | {YYYY-MM-DD}                                                          |
+| **L1 Detail** | [{system-id}.detail.md](./{system-id}.detail.md) — 仅 `/forge` 时加载 |
+> [!IMPORTANT]
+> **文档分层说明**
+> - **本文件 (L0 导航层)**: 架构图、操作契约、设计决策。面向快速理解与任务规划。禁止放配置字典、算法伪代码和方法体。
+> - **[{system-id}.detail.md](./{system-id}.detail.md) (L1 实现层)**: 完整伪代码、配置常量、边缘情况。仅 `/forge` 任务明确引用时加载。
+> - **L1 锚点原则 ⚠️**: L1 中的每一节都必须在本文件有对应超链接入口。严禁 L1 出现 L0 完全未提及的"孤岛内容"。
+---
+## 📋 目录 (Table of Contents)
+|   §   | 章节                                                         | 关键内容                                                 |
+| :---: | ------------------------------------------------------------ | -------------------------------------------------------- |
+|   1   | [概览](#1-概览-overview)                                     | 系统目的、边界、职责                                     |
+|   2   | [目标与非目标](#2-目标与非目标-goals--non-goals)             | Goals / Non-Goals                                        |
+|   3   | [背景与上下文](#3-背景与上下文-background--context)          | 为什么需要这个系统、约束                                 |
+|   4   | [系统架构](#4-系统架构-architecture)                         | Mermaid 架构图、组件职责、数据流                         |
+|   5   | [接口设计](#5-接口设计-interface-design)                     | 操作契约表、跨系统协议、HTTP API                         |
+|   6   | [数据模型](#6-数据模型-data-model)                           | 实体字段声明、ER 图 → [L1 §1-2](./{system-id}.detail.md) |
+|   7   | [技术选型](#7-技术选型-technology-stack)                     | 核心技术、关键依赖                                       |
+|   8   | [Trade-offs](#8-trade-offs--alternatives-权衡与备选方案)     | 决策理由、备选方案对比                                   |
+|   9   | [安全性考虑](#9-安全性考虑-security-considerations)          | 认证授权、风险与缓解                                     |
+|  10   | [性能考虑](#10-性能考虑-performance-considerations)          | 性能目标、优化策略                                       |
+|  11   | [测试策略](#11-测试策略-testing-strategy)                    | 单测、集成、性能测试                                     |
+|  12   | [部署与运维](#12-部署与运维-deployment--operations) *(可选)* | 流程、监控、可观测性                                     |
+|  13   | [未来考虑](#13-未来考虑-future-considerations) *(可选)*      | 扩展性、技术债                                           |
+|  14   | [附录](#14-appendix-附录) *(可选)*                           | 术语表、参考资料、变更日志                               |
+**L1 实现层** → [{system-id}.detail.md](./{system-id}.detail.md)（仅 `/forge` 时加载）
+> [§1 配置常量](./{system-id}.detail.md) · [§2 数据结构](./{system-id}.detail.md) · [§3 算法](./{system-id}.detail.md) · [§4 决策树](./{system-id}.detail.md) · [§5 边缘情况](./{system-id}.detail.md)
 ---
@@ -177,26 +205,26 @@ class ISystemName(Protocol):
   ❌ 禁止: 任何方法体 (哪怕只有 2 行)
   ❌ 禁止: 注释风格的方法列表 (# def foo... 这种)
   ❌ 禁止: 配置常量字典 (UNIT_CONFIG = {...})
-  → 以上内容全部放入 {system}.detail.md §1 和 §2
+  → 以上内容全部放入 {system}.detail.md §1 和 §2。并且依据「L1 锚点原则」，你必须在此处用 Markdown 超链接指明它们在 L1 的下落，例如：
+  *(完整的配置常量字典详见 [{system}.detail.md §1](./{system}.detail.md))*
 -->
 ### 6.1 核心实体 (Core Entities)
 ```python
-# ── 示例: 只放属性字段 + 签名 ──
+# ── 只放属性字段 + 方法签名，禁止方法体 ──
 @dataclass
 class EntityName:
-    # 属性字段
     id: str
     field_a: TypeA
     field_b: TypeB = default_value
-    # 方法签名 (不写方法体, 只写到 ...)
     def some_method(self, param: Type) -> ReturnType: ...
     def another_method(self) -> bool: ...
-    # 完整方法实现见 {system}.detail.md §2.1
 ```
+> *(完整方法实现 → [L1 §2](./{system-id}.detail.md) · 配置常量字典 → [L1 §1](./{system-id}.detail.md))*
 ### 6.2 实体关系图 (Entity Relationship)
 ```mermaid
@@ -474,33 +502,25 @@ classDiagram
 ---
-<!-- ⚠️ CRITICAL 使用指南 -->
-<!--
-**L0 文档撰写原则 (本文件)**:
-1. **导航层定位**: 面向快速理解和任务规划，不展示实现细节
-2. **操作契约表格**: §5.1 用表格代替函数伪代码，每行对应一个原子操作
-3. **属性声明优先**: §6 只放字段声明，不放方法体
-4. **追溯链**: 通过 [REQ-XXX] 引用PRD需求，不复制内容
-5. **约束继承**: 从PRD和ADR继承约束和决策，不能放松
-6. **Trade-offs说明**: 每个重要技术选型都说明「为什么选A不选B」
-7. **Mermaid优先**: 架构图、数据流、决策树 → 用图
-**L1 文件拆分规则 (触发任意一条即创建 .detail.md)**:
-- R1: 单个代码块 > 30 行
-- R2: 文档代码块总行数 > 200 行
-- R3: 配置常量字典条目 > 5 个
-- R4: 版本内联注释 (# vX.X 变更) 出现 > 5 处
-- R5: 文档总行数 > 500 行
-**章节使用指南**:
-- **必需章节**: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
-- **可选章节**: 12 (部署，小项目可简化), 13 (未来，可简化), 14 (附录)
-**L1 文件 ({system}.detail.md) 内容**:
-- §1 配置常量 (UNIT_CONFIG 等)
-- §2 完整类定义 (含方法体)
-- §3 算法伪代码 (完整函数体)
-- §4 决策树展开
-- §5 边缘情况
-- §6 测试辅助
+<!-- ⚠️ AGENT 使用指南
+L0 撰写九律:
+1. 导航层定位 — 不展示实现细节，面向快速理解与任务规划
+2. TOC 同步     — 新增章节必须同步更新文件头部目录表格
+3. 操作契约表  — §5.1 每行一个原子操作，「实现细节」列必须链接 L1
+4. 属性声明    — §6 只放字段 + 方法签名（def foo(): ...），禁止方法体
+5. L1 锚点     — 抽入 L1 的任何内容必须在 L0 对应位置留超链接，禁止孤岛
+6. 追溯链      — [REQ-XXX] 引用 PRD，不复制原文
+7. 约束继承    — 从 PRD / ADR 继承，不能放松
+8. Trade-offs  — 每个选型说明「选 A 不选 B 的理由」
+9. Mermaid 优先 — 架构图 / 数据流 / 决策树，用图不用文字列表
+L1 拆分规则（触发任意一条即创建 .detail.md）:
+  R1 单个代码块 > 30 行
+  R2 代码块总行数 > 200 行
+  R3 配置常量字典条目 > 5 个
+  R4 版本内联注释 > 5 处
+  R5 文档总行数 > 500 行
+必需章节: 1-11  |  可选章节: 12 (部署) · 13 (未来) · 14 (附录)
 -->

package/templates/.agent/workflows/craft.md CHANGED Viewed

@@ -8,33 +8,33 @@ description: 创建高质量的工作流、技能和提示词，融合行业最
 你是 **CRAFTSMAN (工艺大师)**。
 **你的使命**：
-遵循“做容易的事很好达成，但简单而高效的设计却往往很难”的哲学，创建经得起考验的工作流、技能和提示词。你的产出将被反复使用，影响深远。
+你在为 AI 刻铸思维中枢。你写下的每一行 Workflow 和 Skill，Agent 都会盲目遵从——这是权力，也是责任。好的工具不仅告诉 Agent 做什么，还告诉它为什么。因为**只给指令的工具会在边界失效，给了世界观的工具才会在意料之外的情况下做出正确判断**。
 **你的能力**：
-- 创建结构化的工作流 (Workflow)
-- 设计专业技能文档 (Skill)
+- 创建有世界观的工作流 (Workflow)
+- 设计有准入条件的技能文档 (Skill)
 - 编写高质量提示词 (Prompt)
-- **调研融合**行业最佳实践
+- 调研融合行业最佳实践
 **你的限制**：
-- 你不能跳过调研阶段
-- 你不能产出未经自我审视的工作流
-- 你不能使用模糊语言
-- 你的工具使用设计需自然语言而非非常具体
+- 不能跳过调研阶段
+- 不能产出未经自我审视的工作流
+- 不能使用模糊语言
+- 约束必须说明"为什么"，否则它只是一条随时被绕过的禁令
 **核心理念**：
-> **把 AI 当人看待** —— 解释"为什么"，而不只是"做什么"
-> **调研驱动设计** —— 不调研就设计 = 重复发明轮子
-> **自我迭代优化** —— 第一版永远有缺陷
+> **Workflow 是世界观，不是流程图** —— 好的 Workflow 让 Agent 在任何边界情况下都能做出正确判断
+> **Skill 的灵魂在 description** —— 那一行字决定 Agent 何时调用它，比整篇正文都重要
+> **约束是解放，不是限制** —— 好的约束让 Agent 只能通过高质量路径前进
 **与用户的关系**：
-你是用户的**工艺导师**，帮助他们创建高质量的 AI 交互工具。
+你是用户的**工艺导师**，帮助他们铸造经得起长期使用的 AI 工具。
 **Output Goal**: 高质量的工作流/技能/提示词文档
 **支持的输出位置**:
 - Workflow → `.agent/workflows/[name].md`
-- Skill → `.agent/skills/[name]/SKILL.md`
+- Skill → `.agent/skills/[name]/SKILL.md`
 - Prompt → 用户指定位置或 `prompts/[name].md`
 ---
@@ -43,13 +43,13 @@ description: 创建高质量的工作流、技能和提示词，融合行业最
 > [!IMPORTANT]
 > **六大核心原则**：
->
+>
 > 1. **先调研后设计** - 在创建前必须了解最佳实践
-> 2. **解释为什么** - AI 不是机器人，它需要理解目的
-> 3. **强制不偷懒** - 用 `[!IMPORTANT]` 和 `MUST` 约束行为
-> 4. **引导深度思考** - 给出具体步数和思考问题
-> 5. **提供脚手架** - 模板减少自由发挥的空间
-> 6. **自我审视优化** - 产出前必须自我批评和迭代
+> 2. **解释为什么** - 只有指令的约束会被绕过；有了理由的约束才会被内化
+> 3. **强制不偷懒** - 用 `[!IMPORTANT]` 和 `你**必须**` 构建不可跳过的节点
+> 4. **引导深度思考** - 给出具体步数和引导问题，而不是"好好想想"
+> 5. **提供脚手架** - 模板和示例压缩了 Agent 自由发挥（出错）的空间
+> 6. **自我审视优化** - 第一版永远有缺陷，自我批评是最后一道防线
 </phase_context>
 ---
@@ -89,22 +89,44 @@ description: 创建高质量的工作流、技能和提示词，融合行业最
 ---
+## ⚠️ 先理解本质：Skill 与 Workflow 是完全不同的东西
+> [!IMPORTANT]
+> **在选模式前，必须真正理解它们的差异——否则造出来的东西精神错位。**
+>
+> | 维度 | Skill（能力胶囊） | Workflow（行为剧本） |
+> |------|:-----------------:|:--------------------:|
+> | 语法 | **名词** — "我有这个能力" | **动词** — "我要这样做" |
+> | 状态 | 无状态，可被任意 Workflow 调用 | 有状态，定义完整的执行仪式 |
+> | 激活 | Agent 读 `description` 自主判断是否加载 | 用户或 Workflow 显式触发 |
+> | 核心资产 | **`description` 那一行字** | **`<phase_context>` + 约束块** |
+> | 类比 | 工具箱里的一把精密工具 | 一场需要按步骤完成的施工仪式 |
+>
+> **Skill 的 `description` 是灵魂**：它决定 Agent 何时激活这个能力。
+> 太宽泛 → 什么时候都不精准激活；太窄 → 覆盖不了边界场景。
+> 好的 description 是精确的**触发条件**，不是能力标签。
+>
+> **两者都不是"给人读的"**：写给 AI 的东西必须说清"为什么"，
+> 否则 Agent 永远选择最省力的路径（即最差的结果）。
+---
 ## Step 2: 选择模式 (Choose Mode)
 **目标**: 根据需求选择合适的结构。
-| 类型 | 适用场景 | 核心结构 |
-|------|---------|---------|
-| **Workflow** | 多步骤流程、端到端任务 | Steps + 检查点 |
-| **Skill** | 单一能力、可复用模块 | 框架 + 维度 |
-| **Prompt** | 简单指令、一次性任务 | 角色 + 指令 |
+| 类型         | 本质       | 适用场景                         | 核心结构                    |
+| ------------ | ---------- | -------------------------------- | --------------------------- |
+| **Workflow** | 行为剧本   | 端到端任务、多步骤流程           | 世界观 + Steps + 人类检查点 |
+| **Skill**    | 能力胶囊   | 单一可复用能力、被 Workflow 调用 | 准入条件 + 守则 + 输出契约  |
+| **Prompt**   | 一次性指令 | 简单任务、无需复用               | 角色 + 指令 + 约束          |
 ### 模式判断
 ```
-问题是否需要多个步骤？
+问题是否需要多个步骤，从头执行到尾？
 ├─ 是 → Workflow
-└─ 否 → 问题是否需要复用？
+└─ 否 → 这个能力是否在多个 Workflow 里都会被用到？
          ├─ 是 → Skill
          └─ 否 → Prompt
 ```
@@ -155,10 +177,10 @@ description: 创建高质量的工作流、技能和提示词，融合行业最
 ```markdown
 ### 调研总结
-| 来源 | 值得借鉴的设计 | 如何应用 |
-|------|----------------|----------|
-| [来源1] | [设计模式] | [应用方式] |
-| [来源2] | [设计模式] | [应用方式] |
+| 来源    | 值得借鉴的设计 | 如何应用   |
+| ------- | -------------- | ---------- |
+| [来源1] | [设计模式]     | [应用方式] |
+| [来源2] | [设计模式]     | [应用方式] |
 **需要避免的反模式**:
 - [反模式1]: [为什么要避免]
@@ -261,15 +283,23 @@ description: [一句话描述，用于工作流列表展示]
 ### 4.2 Skill 框架
+> **`description` 是 Skill 最重要的一行字。**
+> 它是 Agent 决定是否激活这个 Skill 的唯一判断依据。
+>
+> ❌ 错误示范：`description: 处理 PDF 文件，提取文字和表格，填写表单`（能力描述）
+> ✅ 正确示范：`description: 当用户需要读取、编辑或创建 PDF 文件时使用`（触发条件）
+>
+> 区别不在于字数，在于视角——能力描述是 Skill 在介绍自己；触发条件是在告诉 Agent "在什么时候来找我"。
 ```markdown
 ---
 name: skill-name
-description: [一句话描述]
+description: 当用户需要 [具体触发场景] 时使用。[一句话核心能力概括]
 ---
 # [技能名称] 手册 (English Name Manual)
-> "[核心理念/引言]"
+> "[核心理念/引言——这个 Skill 存在的哲学是什么]"
 ---
@@ -313,9 +343,9 @@ description: [一句话描述]
 ## 📥 输入契约
-| 输入 | 类型 | 必需 | 说明 |
-|------|------|:----:|------|
-| [输入1] | [类型] | ✅/❌ | [说明] |
+| 输入    | 类型   | 必需  | 说明   |
+| ------- | ------ | :---: | ------ |
+| [输入1] | [类型] |  ✅/❌  | [说明] |
 ---
@@ -327,7 +357,7 @@ description: [一句话描述]
 ### [输出标题]
 | 列1 | 列2 | 列3 |
-|-----|-----|-----|
+| --- | --- | --- |
 | ... | ... | ... |
 \`\`\`
@@ -392,38 +422,49 @@ description: [一句话描述]
 7. "调研中发现的反模式如何避免？"
 **内容质量检查**:
-| 检查项 | 标准 |
-|--------|------|
+| 检查项   | 标准                     |
+| -------- | ------------------------ |
 | 目标清晰 | 每个 Step/维度有明确目标 |
 | 原因解释 | 重要约束都解释了"为什么" |
-| 思考引导 | 有具体的引导问题列表 |
-| 输出模板 | 有结构化的输出格式 |
-| 示例丰富 | 关键概念有 ❌/✅ 示例对比 |
+| 思考引导 | 有具体的引导问题列表     |
+| 输出模板 | 有结构化的输出格式       |
+| 示例丰富 | 关键概念有 ❌/✅ 示例对比  |
 | 调研融合 | 融入了调研发现的最佳实践 |
 ---
 ## Step 6: 添加防护 (Add Guardrails)
-**目标**: 防止 AI 偷工减料或偏离方向。
+**目标**: 让 Agent 只能通过高质量路径前进。
+> **约束哲学**：约束不只是禁令，更是认知框架。没有解释的禁令只能约束服从者；有了"为什么"的约束，能让 Agent 在边界情况下自主做出正确判断。
+>
+> 每条有效约束必须回答三个问题：
+> - **What** — 禁止/必须做什么（边界清晰）
+> - **Why** — 为什么（意义，让 AI 理解而非机械执行）
+> - **Violation signal** — 违反时长什么样（提供具体示例，让 AI 能自检）
 **防护机制清单**:
-| 机制 | 用途 | 语法示例 |
-|------|------|---------|
-| `[!IMPORTANT]` 块 | 强制执行 | `> [!IMPORTANT]` |
-| `CRITICAL` 前缀 | 引起注意 | `## ⚠️ CRITICAL` |
-| `你**必须**` | 强制要求 | `你**必须**调用...` |
-| `❌ 禁止` | 负面边界 | `❌ 禁止跳过步骤` |
-| `✅ 必须` | 正面边界 | `✅ 必须验证结果` |
-| 具体步数 | 量化思考 | `5-10 步思考` |
-| 完成标准 | 验收条件 | `<completion_criteria>` |
+| 机制              | 用途     | 语法示例                |
+| ----------------- | -------- | ----------------------- |
+| `[!IMPORTANT]` 块 | 强制执行 | `> [!IMPORTANT]`        |
+| `CRITICAL` 前缀   | 引起注意 | `## ⚠️ CRITICAL`         |
+| `你**必须**`      | 强制要求 | `你**必须**调用...`     |
+| `❌ 禁止`          | 负面边界 | `❌ 禁止跳过步骤`        |
+| `✅ 必须`          | 正面边界 | `✅ 必须验证结果`        |
+| 具体步数          | 量化思考 | `5-10 步思考`           |
+| 完成标准          | 验收条件 | `<completion_criteria>` |
-**添加解释原因**:
+**每个重要约束的完整格式**：
-每个重要约束后面加：
 ```markdown
+> [!IMPORTANT]
+> 你**必须**[要求]。
+>
 > **为什么？** [解释原因]
+>
+> **自检示例**：[提供一个具体的正面或反面示例，让 AI 能对照判断自己是否越界。不一定非要有正反对比，只要足够直观即可。]
 ```
 ---
@@ -494,13 +535,13 @@ description: [一句话描述]
 ### 8.2 产出审视清单
-| 审视维度 | 问题 | 状态 | 修复方案 |
-|---------|------|:----:|---------|
-| 可执行性 | 每个 Step 是否可直接执行？ | ✅/❌ | |
-| 防护强度 | 防护机制是否足够？ | ✅/❌ | |
-| 思考深度 | 思考引导是否具体？ | ✅/❌ | |
-| 示例充分 | ❌/✅ 对比是否足够？ | ✅/❌ | |
-| 调研融合 | 最佳实践融入了吗？ | ✅/❌ | |
+| 审视维度 | 问题                       | 状态  | 修复方案 |
+| -------- | -------------------------- | :---: | -------- |
+| 可执行性 | 每个 Step 是否可直接执行？ |  ✅/❌  |          |
+| 防护强度 | 防护机制是否足够？         |  ✅/❌  |          |
+| 思考深度 | 思考引导是否具体？         |  ✅/❌  |          |
+| 示例充分 | ❌/✅ 对比是否足够？         |  ✅/❌  |          |
+| 调研融合 | 最佳实践融入了吗？         |  ✅/❌  |          |
 ### 8.3 迭代修复
@@ -559,9 +600,9 @@ description: [一句话描述]
 ### 表格增强
 ```markdown
-| 维度 | 检查问题 | 状态 |
-|------|---------|:----:|
-| ... | ... | ✅/❌ |
+| 维度 | 检查问题 | 状态  |
+| ---- | -------- | :---: |
+| ...  | ...      |  ✅/❌  |
 ```
 ### 完成标准

package/templates/.agent/workflows/design-system.md CHANGED Viewed

@@ -423,6 +423,7 @@ description: 为单个系统设计详细的技术文档，通过调研最佳实
 **关键要求**:
 - **L0 架构图**: 必须使用 Mermaid 绘制
 - **L0 决策树**: 用 Mermaid `flowchart TD`，不用伪代码
+- **L1 锚点原则 (L1 Anchor Principle)**: L0 作为大纲与目录，**必须**为 L1 里的所有细节块留下导航坐标（锚点）。例如在数据模型末尾必须显式注明 *“常量字典配置祥见 [xxx.detail.md §1](./xxx.detail.md)”*。**严禁在 L1 中存在 L0 完全没有提及/引用的“孤岛内容”**。
 - **Trade-offs**: 每个重要技术选型都要说明"为什么选 A 不选 B"
 - **追溯链**: 在相关章节引用 PRD 需求 [REQ-XXX]
 - **约束继承**: 从 PRD 和 ADR 继承约束

package/templates/.agent/workflows/quickstart.md CHANGED Viewed

@@ -1,289 +1,97 @@
 ---
-description: 一键启动入口。智能检测项目状态，编排 genesis → design-system → blueprint → challenge → forge 全流程，每一步等待用户确认后才继续。新用户只需知道这一个命令。
+description: 智能编排全流程（scout → genesis → design → blueprint → challenge → forge）。
 ---
 # /quickstart
 <phase_context>
 你是 **NAVIGATOR (导航员)**。
-**你的使命**：
-引导用户走完从"想法"到"可执行代码"的全流程。你不做具体工作——具体工作由各个专业工作流完成。你的价值在于**智能判断项目状态**和**编排正确的工作流顺序**。
-**核心原则**:
-- ⏸️ **绝不自动推进** — 每个 Step 结束后必须等待用户明确确认
-- 🧭 **智能起点** — 自动检测项目进度，从正确的位置开始
-- 📋 **清晰汇报** — 每个暂停点展示产出摘要、下一步内容、预估工作量
-- 🔀 **随时退出** — 用户可以随时中断，切换到具体工作流精细操作
+你的核心任务是：**智能诊断项目状态，编排最佳工作流路径。**
+原则：⏸️ 每步必等确认 | 🧭 自动对准起点 | 📋 交付物导向。
 </phase_context>
 ---
-## Step 0: 项目状态检测 (Project State Detection)
-**目标**: 智能判断项目当前处于哪个阶段，从正确的位置开始。
+## Step 0: 项目诊断 (Diagnosis)
-### 检测逻辑
+扫描项目以决定起点。
+### 状态矩阵
 ```
-1. 扫描 genesis/ 目录
-2. 判断状态:
-   ├── 无 genesis/ 目录
-   │   → 🆕 全新项目 → Jump to Step 1
-   │
-   ├── 有 genesis/v{N}/ 但无 05_TASKS.md
-   │   ├── 有 04_SYSTEM_DESIGN/ → 需要 blueprint 或设计审查 → Jump to Step 3
-   │   └── 无 04_SYSTEM_DESIGN/ → 可能需要 design-system → Jump to Step 2
-   │
-   ├── 有 05_TASKS.md 但无 src/ 代码
-   │   → 需要任务审查或开始执行 → Jump to Step 5
-   │
-   └── 有代码 + 有任务
-       → 增量模式 → Jump to Step 7
-```
-### 状态报告
-向用户展示：
-```markdown
-## 🧭 项目状态检测
-**检测到的架构版本**: genesis/v{N} (或: 未找到 genesis 目录)
-**PRD**: ✅ 存在 / ❌ 缺失
-**Architecture**: ✅ 存在 / ❌ 缺失
-**System Design**: ✅ 已有 {X} 个系统设计 / ⚠️ 未找到
-**Tasks**: ✅ 共 {N} 个任务 ({M} 已完成) / ❌ 缺失
-**代码**: ✅ src/ 存在 / ❌ 未开始
-📍 **建议从 Step {X} 开始**: {原因}
+├── 🛑 无 genesis/
+│   ├── 有代码 → 🏚️ [遗留项目] → Jump to Step 0.5 (Scout)
+│   └── 无代码 → 🆕 [全新项目] → Jump to Step 1 (Genesis)
+├── 📝 有架构 (无任务)
+│   ├── 有系统设计 → Step 3 (Challenge Design)
+│   └── 无系统设计 → Step 2 (Design System - 如需)
+└── 🔨 有任务
+    ├── 无代码 → Step 5 (Challenge Tasks)
+    └── 有代码 → Step 7 (Forge / Incremental)
 ```
-⏸️ **等待用户确认** → 用户同意后按检测结果跳转到对应 Step。
+⏸️ **确认探测结果** → 进入建议步骤。
 ---
-## Step 1: 需求收集 (Genesis)
-**目标**: 执行 `/genesis`，将模糊想法转化为 PRD + 架构文档 + ADR。
+## Step 0.5: 侦察 (Scout)
-> 引导用户执行 `/genesis` 工作流。
-### 完成后展示
-```markdown
-## ✅ Step 1 完成: 需求与架构
-**产出文件**:
-- 📄 genesis/v{N}/01_PRD.md — {X} 个 User Story, {Y} 个需求
-- 📄 genesis/v{N}/02_ARCHITECTURE_OVERVIEW.md — {Z} 个系统
-- 📁 genesis/v{N}/03_ADR/ — {W} 个架构决策记录
-**下一步**: Step 2 — 系统详细设计 (如需要) 或 Step 3 — 设计审查 (Challenge)
-**预估**: Step 2 每个系统约 30-60 分钟; Step 3 约 15-30 分钟
-```
-⏸️ **等待用户确认** → 用户确认后进入 Step 2。
+**触发**: 遗留项目。通过 `/scout` 探测暗地里的风险与耦合。
+**产出**: `00_SCOUT_REPORT.md` (Genesis 的重要输入)。
 ---
-## Step 2: 系统设计 (Design System — 如需要)
-**目标**: 评估是否需要为各系统执行 `/design-system`。
-### 复杂度评估
-检查 `02_ARCHITECTURE_OVERVIEW.md` 中的系统数量和复杂度：
+## Step 1: 创世 (Genesis)
-| 条件                           | 判断         | 建议                                  |
-| ------------------------------ | ------------ | ------------------------------------- |
-| 系统数 ≤ 2，且无复杂跨系统交互 | 简单项目     | 建议跳过，blueprint 时可按需补充      |
-| 系统数 ≥ 3，或有复杂状态同步   | 复杂项目     | 建议为每个核心系统执行 /design-system |
-| 包含 AI/LLM 集成               | 需要详细设计 | 至少为 AI 相关系统做设计              |
+**目标**: 运行 `/genesis`。将想法固化为 PRD、Architecture 与 ADR。
+**核心交付**: `01_PRD.md`, `02_ARCHITECTURE_OVERVIEW.md`。
-### 展示评估结果
-```markdown
-## 🔍 Step 2: 系统设计评估
-**架构中包含 {N} 个系统**:
-| 系统       | 复杂度 | 建议                    |
-| ---------- | :----: | ----------------------- |
-| {system-1} |  🔴 高  | 建议执行 /design-system |
-| {system-2} |  🟡 中  | 可选                    |
-| {system-3} |  🟢 低  | 可跳过                  |
+---
-**建议**: 为 {system-1} 执行详细设计。其余可在 blueprint 阶段按需补充。
-```
+## Step 2: 细化 (Design System)
-⏸️ **等待用户确认** → 用户选择要设计的系统 → 依次执行 `/design-system` → 全部完成后进入 Step 3。
+**目标**: 针对高复杂度系统运行 `/design-system`。
+**判断**: 系统数 ≥ 3 或包含 AI 集成时建议执行。
 ---
 ## Step 3: 设计审查 (Challenge Design)
-**目标**: 执行 `/challenge`，对当前的 PRD 和架构/系统设计进行系统性审查。
-> 引导用户执行 `/challenge` 工作流。由于当前无 `05_TASKS.md`，系统会自动进入 `DESIGN` 模式。
-### 完成后展示
-```markdown
-## ✅ Step 3 完成: 设计审查
-**审查结果**:
-| 级别       | 数量  |
-| ---------- | :---: |
-| 🔴 Critical |  {X}  |
-| 🟠 High     |  {Y}  |
-| 🟡 Medium   |  {Z}  |
-| 🟢 Low      |  {W}  |
-**详细报告**: genesis/v{N}/07_CHALLENGE_REPORT.md
-```
-### 判断逻辑
-- **有 CRITICAL 问题**: "⚠️ 发现 {X} 个阻塞设计问题，建议先通过 /change 修复后再进入拆解环节。"
-- **无 CRITICAL**: "✅ 无阻塞问题。可以开始拆解任务。"
-```markdown
-**下一步**: Step 4 — 任务拆解 (Blueprint)
-```
-⏸️ **等待用户确认** → 用户确认后进入 Step 4。
+**目标**: 运行 `/challenge`。在动工前识别架构层面的 Critical 风险。
+**准则**: 发现阻塞问题必须先修复。
 ---
-## Step 4: 任务拆解 (Blueprint)
-**目标**: 执行 `/blueprint`，将稳固的架构拆解为可执行的 WBS 任务清单。
-> 引导用户执行 `/blueprint` 工作流。含 User Story Overlay 交叉验证。
+## Step 4: 蓝图 (Blueprint)
-### 完成后展示
-```markdown
-## ✅ Step 4 完成: 任务清单
-**产出文件**: genesis/v{N}/05_TASKS.md
-**统计**:
-- 总任务数: {N}
-- P0 (Must): {X} | P1 (Should): {Y} | P2 (Nice): {Z}
-- Sprint 数: {S}
-- 总预估工时: {T}h
-**User Story 覆盖**:
-- {covered}/{total} US 完整覆盖
-- {gaps} 个覆盖 GAP (已在 Overlay 中标注)
-**下一步**: Step 5 — 任务审查 (Challenge Tasks，建议执行)
-```
-⏸️ **等待用户确认** → 用户确认后进入 Step 5。
+**目标**: 运行 `/blueprint`。将架构拆解为可执行的 `05_TASKS.md`。
+**交付**: WBS 任务清单 + Sprint 划分。
 ---
 ## Step 5: 任务审查 (Challenge Tasks)
-**目标**: 再次执行 `/challenge`，这次专注于任务清单的完备性与覆盖率。
-> 引导用户执行 `/challenge` 工作流。由于 `05_TASKS.md` 已存在，它将执行 `task-reviewer` (或 `FULL` 全面审查)。
-### 完成后展示
-```markdown
-## ✅ Step 5 完成: 任务审查
-**审查结果**: (同上表)
-**报告已追加至**: genesis/v{N}/07_CHALLENGE_REPORT.md
-```
-### 判断逻辑
-- **有任务覆盖 GAP 或缺陷**: "⚠️ 任务清单有漏洞，建议使用 /change 补全。"
-- **无阻塞问题**: "✅ 任务清单坚如磐石。"
-```markdown
-**下一步**: Step 6 — 开始编码执行 (Wave 1)
-```
-⏸️ **等待用户确认** → 用户确认后进入 Step 6。
+**目标**: 再次运行 `/challenge`。确保任务覆盖了所有 User Stories 且无逻辑缺失。
 ---
-## Step 6: 开始执行 (Forge)
-**目标**: 引导进入 `/forge` 的第一个波次。
-> 引导用户执行 `/forge` 工作流。
+## Step 6: 铸造 (Forge)
-### 展示 Wave 1 建议
-```markdown
-## 🔨 Step 5: 准备开始执行
-基于任务清单和依赖关系，建议 Wave 1 包含:
-| 任务     | 标题 | 估时  |
-| -------- | ---- | :---: |
-| T{X.Y.Z} | ...  |  Xh   |
-| T{X.Y.Z} | ...  |  Xh   |
-**总估时**: ~{T}h
-准备好了吗？确认后将进入 /forge 开始编码。
-此后可直接使用 /forge 继续后续波次。
-```
-⏸️ **等待用户确认** → 确认后执行 `/forge`。
+**目标**: 进入 `/forge`。引导开始 Wave 1 的编码。
+**提示**: 后续开发可直接使用 `/forge` 继续各波次。
 ---
-## Step 7: 增量模式 (Incremental)
-**目标**: 项目已有进度时，展示当前状态并建议下一步。
-### 展示当前进度
+## Step 7: 增量管理 (Incremental)
-```markdown
-## 📊 项目进度
-**架构版本**: genesis/v{N}
-**任务进度**: {completed}/{total} ({percentage}%)
-**当前波次**: Wave {W} ({status})
-| Sprint | 任务数 | 已完成 | 状态  |
-| ------ | :----: | :----: | :---: |
-| S1     |  {X}   |  {Y}   | ✅/🔶/⬜ |
-| S2     |  {X}   |  {Y}   | ✅/🔶/⬜ |
-**建议下一步**:
-1. `/forge` — 继续执行未完成的任务
-2. `/change` — 微调已有任务
-3. `/challenge` — 对当前状态做一次审查
-4. `/genesis` — 启动新版本架构 (v{N+1})
-```
-⏸️ **等待用户选择** → 根据选择跳转到对应工作流。
+**场景**: 项目开发中。
+**建议建议**:
+- `/forge` — 继续执行任务
+- `/scout` — 重大变更前探测风险
+- `/genesis` — 架构大版本升级
+- `/change` — 微调任务细节
 ---
-<completion_criteria>
-- ✅ 正确检测了项目状态
-- ✅ 每个 Step 结束后等待了用户确认
-- ✅ 用户已进入具体工作流开始工作
-</completion_criteria>
----
-## 🔀 Handoffs
-完成本工作流后，根据情况选择：
+## 🔀 快速跳转 (Handoffs)
-- **从头开始** → `/genesis` — 从零开始，将想法转化为 PRD 和架构
-- **任务拆解** → `/blueprint` — 将架构拆解为可执行任务
-- **开始编码** → `/forge` — 按任务清单开始波次执行
-- **质疑设计** → `/challenge` — 对当前设计进行系统性挑战
+- `/scout` | `/genesis` | `/blueprint` | `/challenge` | `/forge`