bb-mas

name	bb-mas
description	生成芯片功能模块微架构文档（MAS、FSM、数据通路、验证计划、DFT）。Generate microarchitecture specification for chiplet modules. Trigger: /bb-mas, 微架构文档, MAS, FSM, datapath, verification plan, DFT
user-invocable	true
self-adaptive	true
version	1.0.0
arguments	[{"name":"project_dir","description":"芯片项目目录路径（如 ./myChip），auto-detect by default","required":false},{"name":"module_type","description":"模块类型：compute|storage|interconnect|io|all","required":false,"default":"all"},{"name":"auto_approve","description":"跳过用户批准点，自动生成所有文档","required":false,"default":"false"},{"name":"finetune","description":"Enable finetune mode for detailed intermediate output","required":false},{"name":"update","description":"更新模式：auto（自动检测变更）| full（强制归档+全量重建）| patch（强制就地更新，不归档）","required":false,"default":"auto"}]
handoffs	[{"target":"bb-spec-review","condition":"MAS documents completed","session_note":"必须执行对抗性 spec-review 才能进入 RTL 实现"}]
evolution	{"enabled":true,"trigger":"on_failure","max_attempts":3,"protected_zones":["frontmatter.name","frontmatter.description","HARD-GATE section","Self-Adaptive 初始化 section"],"depth_policy":{"conservative":"auto","local":"auto","system":"confirm"},"data_sources":["execution_log","evolution_history","failed_paths"]}

output_dir: ./spec_mas language: zh-CN finetune: false auto_approve: false project_dir: auto-detect module_type: all update: auto

Self-Adaptive 初始化

初始化目录结构：.skills_local/bb-mas/，并收集项目上下文信息。

---

HARD-GATE 定义

<HARD-GATE>
在任何 MAS 生成操作前，必须完成以下步骤：

1. Self-Adaptive 初始化 + 项目上下文收集 + 路径解析（MANDATORY）
   ```bash
   SCRIPT_DIR=~/.claude/scripts
   python3 "$SCRIPT_DIR/adaptive/adaptive_init.py" \
     --skill "bb-mas" \
     --project-dir "{{ PROJECT_DIR }}"

2. 加载配置文件（MANDATORY）

   import json
   
   with open(".skills_local/bb-mas/project_context.json") as f:
       CONTEXT = json.load(f)
   
   PROJECT_DIR = CONTEXT["project"]["root"]
   INPUT_DIR = CONTEXT["resolved_paths"]["INPUT_DIR"]
   OUTPUT_DIR = CONTEXT["resolved_paths"]["OUTPUT_DIR"]
   MODULE_TYPE = CONTEXT["config"]["module_type"]
   

3. 创建执行日志目录

   mkdir -p "${LOG_DIR}"
   LOG_FILE="${LOG_DIR}/mas-$(date -u +%Y%m%dT%H%M%S).log"
   

禁止行为（在完成初始化前）：

• 加载 spec_arch 输入
• 启动模块树生成
• 输出 MAS 文档

---

## Pipeline Position

spec_arch/ ──→ [bb-mas] ──→ spec_mas/ ──→ bb-spec-review ──→ bb-rtl-coder OUTPUT_DIR

---

## 铁律（违反即停止）

> 以下规则不受 auto_approve 影响，任何模式下均不得绕过。

1. **Spec 先行铁律**：`spec_arch/` 中有效文档少于 2 份 → 拒绝执行，返回 bb-arch 阶段
2. **叶子优先铁律**：子模块未完成 → 禁止开始父模块；违反此顺序父模块内容必然不准确
3. **五文件完整铁律**：每个模块��须有 MAS.md + FSM.md + datapath.md + verification.md + DFT.md，缺一不可；"简单模块不需要 FSM" 是借口
4. **Frontmatter 状态铁律**：`status: pending` 的文件不计入完成统计，不触发后续流程
5. **并行上限铁律**：同时运行子 agent ≤ 6 个；超出会导致上下文污染和路径混乱

---

## 模块类型分类

| 类型 | 典型模块 | MAS 重点章节 |
|------|---------|-------------|
| **compute** | ALU、CPU Core、MAC、DSP | 数据通路、FSM、流水线 |
| **storage** | Cache、SRAM、DRAM Controller | 访存协议、替换策略、一致性 |
| **interconnect** | NoC、Bus、Crossbar、Router | 路由算法、仲裁、带宽 |
| **io** | GPIO、PCIe、DDR、SerDes | 协议适配、CDC、时序 |

---

## Global Paths

PROJECT_DIR = {{ project_dir 参数 或 auto-detect }} INPUT_DIR = {{ PROJECT_DIR }}/spec_arch OUTPUT_DIR = {{ PROJECT_DIR }}/spec_mas TEMPLATE_DIR = ~/.claude/skills/bb-mas/templates PROGRESS_DIR = {{ OUTPUT_DIR }}/.progress CHECKPOINT_DIR = {{ OUTPUT_DIR }}/.checkpoint SCRIPT_DIR = ~/.claude/scripts PROJECT_SCRIPTS = {{ PROJECT_DIR }}/scripts SKILL_FILE = ~/.claude/skills/bb-mas/SKILL.md

---

## 增量更新机制

每次成功完成后，将输入文件哈希写入 `<output_dir>/.archive/input_snapshot.json`。下次执行时在前置检查之前自动比对。

### 输入快照格式

```json
{
  "snapshot_time": "<ISO8601+08:00>",
  "skill": "bb-mas",
  "input_files": {
    "<relative-path>": "<sha256>"
  }
}

Phase -1: 变更检测（前置检查前强制执行）

IF update=full  → 跳过检测，走 MAJOR 路径
IF update=patch → 跳过检测，走 MINOR 路径
ELSE (auto):
  IF input_snapshot.json 不存在
    → FULL RUN（首次执行，不归档）
  ELSE
    sha256sum arch_spec/ 下所有 .md 文件
    与 snapshot 对比
    IF 哈希全部一致 → 输出 "输入未变更，跳过生成" 并退出
    IF 哈希有差异   → 按下表分类

变更分类

条件（满足任意一条）	分类
arch_spec/ 中文件数量变化（增删文件）	MAJOR
arch_doc.md 中模块数量变化	MAJOR
接口协议列表变更（增删/重命名）	MAJOR
时钟域数量或名称变更	MAJOR
arch_spec/ 总字符数变化 > 30%	MAJOR
其他所有变更（模块描述更新、预算调整、时序约束细化等）	MINOR

MAJOR 路径：归档 + 全量重建

TIMESTAMP=$(date -u +%Y%m%dT%H%M%S)
ARCHIVE="{{ OUTPUT_DIR }}/.archive/$TIMESTAMP"
mkdir -p "$ARCHIVE"
for item in "{{ OUTPUT_DIR }}"/*.md "{{ OUTPUT_DIR }}"/*.json \
            "{{ OUTPUT_DIR }}"/fsm "{{ OUTPUT_DIR }}"/datapath; do
  [ -e "$item" ] && mv "$item" "$ARCHIVE/"
done
echo "{\"reason\":\"MAJOR\",\"timestamp\":\"$TIMESTAMP\"}" > "$ARCHIVE/CHANGE_REASON.json"

归档完成后执行 FULL RUN（从前置检查正常继续）。

MINOR 路径：就地更新

仅重新生成哈希发生变化的模块文档，其余模块保持不变：

变更内容	处理
某模块 MAS.md 对应的 arch_spec 段变更	重新生成该模块 MAS.md + FSM/Datapath
全局计划（verif_plan_seed.md、dft_plan_seed.md）相关内容变更	重新生成全局计划文件
仅描述文字变更	仅更新受影响模块的描述段落

完成后更新 {{ OUTPUT_DIR }}/.archive/input_snapshot.json。

---

前置检查

1. 定位 spec_arch 目录：

   • 若用户提供路径，验证存在
   • 否则自动检测最新子目录

2. 验证必需文档（至少 2 份，来自 bb-arch 实际输出）：

   • chip_overview.md 或 block_overview.md — 芯片/模块概述
   • block_diagram.md — 系统/模块框图
   • clock_reset_spec.md — 时钟复位架构
   • memory_map.md — 存储架构与地址映射
   • power_spec.md — 电源架构
   • io_pinout.md — IO 与引脚定义
   • ip_blocks/*.md — IP 模块详细设计（scope=chip 时）

3. 创建输出目录：

   mkdir -p {{ OUTPUT_DIR }}
   mkdir -p {{ PROGRESS_DIR }}
   mkdir -p {{ CHECKPOINT_DIR }}
   

---

阶段 1：构建模块树

1.1 输入规模检测

# Sum all .md files in spec_arch/ as input size
TOTAL_SIZE=$(find "${INPUT_DIR}" -name "*.md" -exec wc -c {} + | tail -1 | awk '{print $1}')

if [ "$TOTAL_SIZE" -lt 100000 ];  then READ_MODE="full"
elif [ "$TOTAL_SIZE" -lt 300000 ]; then READ_MODE="section"
else                                    READ_MODE="subagent"
fi

1.2 构建嵌套模块树

拆分判据：模块职责覆盖 3+ 独立子功能 → 拆分

命名规则：

• L1：M01_模块名/（如 M01_ALU/）
• L2：M01a_子模块名/（如 M01a_IntegerALU/）
• L3：M01a1_原子模块/（如 M01a1_Adder/）

Chiplet 特定标注：

• @D2D — Die-to-Die 接口模块
• @CDC — 跨时钟域模块
• @PWR — 电源管理相关

1.3 输出模块树文档

写入 {{ OUTPUT_DIR }}/module_tree.md

1.4 创建目录结构

为每个模块创建子目录和 5 个文件：

{{ OUTPUT_DIR }}/
├── module_tree.md
├── plan.md（占位）
├── .progress/
├── .checkpoint/
└── M01_*/
    ├── MAS.md         # 微架构文档
    ├── FSM.md         # 状态机设计
    ├── datapath.md    # 数据通路图
    ├── verification.md # 验证计划
    ├── DFT.md         # 可测性设计
    └── tasks.md       # 实现任务

---

阶段 2：填充叶子模块文档（并行）

子 agent 指令模板

## 任务：填充模块 MAS 文档

**路径规范**：
- 输出文件：{{ OUTPUT_DIR }}/{{ MODULE_PATH }}/MAS.md
- 模板文件：{{ TEMPLATE_DIR }}/MAS-template.md
- 上下文：{{ INPUT_DIR }}/architecture_spec.md, functional_spec.md

**要求**：
1. 读取模板文件
2. 按模板章节结构填充内容

**芯片特定质量要求**：
- §2.1 接口定义：信号名、位宽、方向、协议（AXI/APB/自定义）
- §2.2 时序规格：Cycle 延迟、吞吐、带宽
- §3 数据通路：流水线级数、关键路径、Mermaid/WaveDrom 图
- §4 状态机：FSM 定义、状态编码、转移条件
- §5 验证策略：功能覆盖点、断言、仿真场景
- §6 DFT 方案：扫描链、BIST、JTAG 接口
- §10 需求追踪矩阵：REQ_ID 列表 + 验收标准

3. frontmatter 格式：
   ---
   module: {{ MODULE_ID }}
   type: MAS
   status: complete
   parent: {{ PARENT_ID }}
   module_type: compute|storage|interconnect|io
   generated: {{ NOW }}
   ---

REQ_ID 分配与标注

分配规则：

1. 从 arch_spec 中的 REQ-SYS/ARCH 分解到模块级 REQ-M##-F##
2. 使用 $PROJECT_SCRIPTS/allocate_req_id.py 自动分配编号（禁止手动编号）
3. 每个功能点对应一个 REQ_ID（P-4: 禁止复用；P-5: 禁止一对多）

标注规则：

1. MAS.md §10：生成需求追踪矩阵表
2. 章节标题下：添加 HTML 注释 <!-- REQ-M##-F01, REQ-M##-F02 -->
3. 表格中：在 REQ_ID 列直接标注

示例：

## 3. 流水线结构

<!-- REQ-M01-F01, REQ-M01-F02, REQ-M01-F03 -->

| 级  | 名称 | REQ_ID | 功能 | 延迟 |
|-----|------|--------|------|------|
| IF  | 取指 | F01 | AXI Burst 读 | 1–8 cycle |

## 10. 需求追踪矩阵

| REQ_ID | 需求描述 | 优先级 | 验收标准 | 边界条件 | RTL 组件 | 测试用例 |
|--------|---------|--------|---------|---------|---------|---------|
| REQ-M01-F01 | IF 取指 | P0 | IQ 填充延迟 ≤8 cycle | IQ 满时 back-pressure | M01_DataflowController | TC-M01-L1-001 |

---

阶段 3：填充 FSM/Datapath/Verification/DFT（并行）

每个叶子模块启动子 agent 依次填充 4 个文件。

FSM.md 质量要求

## FSM 定义

### 状态列表
| 状态 | 编码 | 描述 |
|------|------|------|

### 状态转移表
| 当前状态 | 转移条件 | 目标状态 | 输出 |
|----------|---------|----------|------|

### Mermaid 状态图
```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Active: start
    ...

### Datapath.md 质量要求

```markdown
## 数据通路

### 模块框图（Mermaid）
```mermaid
graph TB
    A[输入] --> B[处理]
    B --> C[输出]

流水线结构

级别	操作	延迟

关键路径分析

• 最大延迟路径
• 时钟约束

### Verification.md 质量要求

```markdown
## 验证计划

### 功能覆盖点
| 覆盖点 | 类型 | 描述 |
|--------|------|------|

### 断言列表
| 断言 | 条件 | 严重性 |
|------|------|------|

### 仿真场景
- 正常场景
- 边界场景
- 异常场景

DFT.md 质量要求

## 可测性设计

### 扫描链配置
- 链数
- 长度
- 接口

### BIST 方案
- 类型（MBIST/LBIST）
- 覆盖范围

### JTAG 接口
- TCK/TMS/TDI/TDO
- 支持指令

---

阶段 4：逐层上卷父模块

从最深的父模块开始，逐层向上填充。

父模块特殊内容：

• MAS.md：子模块编排表、数据流图、聚合接口
• FSM.md：顶层状态机协调
• datapath.md：模块间连接图
• verification.md：集成验证场景
• DFT.md：顶层测试访问

---

阶段 5：生成全局计划 + Traceability CSV

5.1 全局计划

汇总所有模块的 tasks，生成 {{ OUTPUT_DIR }}/plan.md：

• 模块依赖关系图（Mermaid）
• 实现阶段定义
• 并行实现矩阵
• 验证里程碑

5.2 Traceability CSV 生成

从所有模块 MAS.md §10 提取 REQ_ID，生成 traceability/requirements_matrix.arch.csv：

uv run $PROJECT_SCRIPTS/babel_traceability.py arch

5.3 唯一性验证

uv run $PROJECT_SCRIPTS/check_req_uniqueness.py --check-deleted

5.4 完成标准追加

• 每个 MAS.md §10 包含需求追踪矩阵（REQ_ID + 验收标准）
• traceability/requirements_matrix.arch.csv 生成成功
• check_req_uniqueness.py 通过

5.5 生成 MAS handoff 新鲜度哈希（CR-5）

bba-architect 没有 Bash 工具，无法运行 sha256sum。本 skill 提供 scripts/hash_outputs.py 供 architect（经 IC_ADAPTER）填充 mas.json 的 inputs[]（消费的 idea/arch 文件）与 outputs[]（产出的 PRD/arch_spec/MAS 文档），二者均为 mas.schema.json 必填项；下游 RTL 重算 outputs[] 哈希以检测 MAS 漂移。

# inputs[]：消费的上游文件
uv run python scripts/hash_outputs.py --base designs/<name> \
  designs/<name>/idea/parsed_idea.json designs/<name>/arch_spec/*.md
# outputs[]：本阶段产出的规格文档
uv run python scripts/hash_outputs.py --base designs/<name> \
  designs/<name>/PRD.md designs/<name>/arch_spec/*.md \
  designs/<name>/mas/mas.md designs/<name>/mas/fsm/* designs/<name>/mas/datapath/*

脚本输出按 path 排序的 [{path, sha256}] JSON；缺失文件 → 退出码 1 且不伪造哈希（fail-closed）。

---

Chiplet 特定章节

当模块涉及 D2D 接口时，MAS.md 必须包含：

D2D 接口规范

## D2D 接口

### 协议类型
- UCIe / BoW / AIB / 自定义

### 信号定义
| 信号 | 方向 | 位宽 | 协议 |
|------|------|------|------|

### 时序参数
- 延迟：`xx cycles`
- 吞吐：`xx Gbps`

### CDC 方案
- 同步器类型
- MTBF 估算

电源域

## 电源域

### 域划分
| 域 | 电压 | 模块 |
|------|------|------|

### 电源序列
1. 域 A 上电
2. 域 B 上电
...

---

Frontmatter 格式规范

---
module: M[0-9]{2}[a-z]?    # 如 M01, M01a, M01a1
type: MAS | FSM | datapath | verification | DFT | tasks
status: pending | complete
parent: [父模块编号]
module_type: compute | storage | interconnect | io
chiplet_features: [D2D, CDC, PWR]  # 可选
generated: [ISO 8601 时间戳]
---

---

输出模板

详见 templates/ 目录：

• MAS-template.md — 微架构文档模板
• FSM-template.md — 状态机模板
• datapath-template.md — 数据通路模板
• verification-template.md — 验证计划模板
• DFT-template.md — DFT 模板
• tasks-template.md — 任务模板

---

辅助脚本

详见 scripts/ 目录：

• progress_check.sh — 进度检查
• checkpoint_manager.sh — checkpoint 管理
• analyze_spec.sh — 文档质量分析
• hash_outputs.py — 计算文件 sha256 填充 mas.json inputs[]/outputs[]（供无 Bash 的 architect 使用，CR-5）

---

操作原则

• 路径绝对化：所有路径使用绝对路径
• 格式统一：frontmatter 仅使用 status: complete
• 进度可追踪：每个文件完成后更新进度文件
• 支持恢复：每个阶段完成时创建 checkpoint
• 底层优先：叶子模块先完成，再逐层上卷
• 并行加速：同层无依赖模块并行处理（最大 6 个）
• 阶段压缩：每完成一个阶段执行 /compact

---

常见借口（均无效）

Agent 的借口	为什么错
"���个模块很简单，FSM.md 可以留空"	无 FSM 文档意味着 RTL 工程师在无规范情况下写状态机，必然引入缺陷，review 时也无法检查
"DFT.md 是 DFT 工程师的事，MAS 阶段不需要"	DFT 需求影响模块端口（scan_en），MAS 阶段未定则 RTL 需要返工接口
"父模块可以先写，子模块并行填充"	父模块内容依赖子模块接口定义；子模块未完成则父模块内容必然不准确，后续级联错误
"verification.md 场景太多，列几个代表性的就行"	不完整的验证计划等于不完整的测试；漏掉的场景在 silicon 上暴露，成本以流片次数计
"先标 status: complete，内容后续完善"	错误的 complete 标记会让 bb-spec-review 跳过实际未完成模块，掩盖质量问题
"输入文档不够清晰，猜测一下先继续"	基于猜测的 MAS 文档等于技术债；在 RTL 实现阶段被发现时已无法低成本修复

---

降级策略

场景	降级方案
子 agent 超时	重试一次；再次失败则记录至 .progress/failed_modules.md 并继续其他模块
模板文件缺失（templates/）	使用各阶段"质量要求"小节中的内联最小化模板结构
输入规模超过单 agent 处理能力	切分为 300KB chunks，依次送入子 agent，结果合并
bb-spec-review 不可用	使用阶段 5 plan.md 内联质量检查清单代替，结果写入 .checkpoint/manual_check.md
spec_arch/ 缺少某类文档	从已有文档推断，标注 "⚠️ 基于推断，需人工确认：{缺失文档}"

---

最终验证实证（完成标准）

以下条件全部满足才可声明 bb-mas 完成，并触发 bb-spec-review handoff。缺一不可。

• module_tree.md 存在且所有叶子模块已列出
• 每个叶子模块目录包含 5 个文件（MAS/FSM/datapath/verification/DFT）
• 所有文件 frontmatter 中 status: complete（无 pending）
• 每个 MAS.md 中接口信号表完整（无空行、无 TBD 信号名）
• 每个 FSM.md 包含状态列表 + 转移表 + Mermaid 状态图
• plan.md 存在，包含模块依赖图和并行实现矩阵
• bb-spec-review 未报告 CRITICAL 级别问题（或已修复并记录）

禁止在上述条件未满足时触发 bb-rtl-coder handoff。

---

Evolution Trigger Point

When any Phase fails:

1. Detect failure: Read {{ OUTPUT_DIR }}/execution.log
2. Invoke framework:

   bash {{ EVOLUTION_FRAMEWORK }}/evolve.sh \
     --skill "{{ SKILL_FILE }}" \
     --output "{{ OUTPUT_DIR }}" \
     --failure-phase "{{ FAILED_PHASE }}"
   

3. Framework handles: Analyze, modify, validate, rollback
4. Retry or escalate