intent-normalize

name	intent-normalize
description	Scan and normalize existing intent/planning files to IDD standard. Auto-fixes mechanical issues (frontmatter, directory structure), tags content issues for pickup. Use /intent-normalize to scan current project, or /intent-normalize <path> for specific directory.

Intent Normalize

扫描现有项目，将 intent 和 planning 文件规范化到 IDD 标准。能自动修的直接修，不能修的打上状态让 TeamSwarm pickup。

设计原则

1. 格式先行 — 所有文件先有 frontmatter，让系统能识别
2. 能修则修 — 机械性问题直接修复（frontmatter、目录结构、命名）
3. 不能修则标记 — 内容问题打上状态，后续由 TeamSwarm 或人处理
4. 幂等 — 多次运行结果一致，已规范的文件不会被改动

工作流程

/intent-normalize [path]
        ↓
┌───────────────────────────────────┐
│  1. 扫描 intent/ 和 planning/     │
│     发现所有 .md 和 .yaml 文件     │
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│  2. 分析每个文件的合规状态         │
│     - 有无 frontmatter?           │
│     - 有无 Anchor?                │
│     - 目录结构是否完整?            │
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│  3. 自动修复机械问题               │
│     - 补 frontmatter              │
│     - 创建 records/ + INDEX.md    │
│     - 创建 _archive/, _data/      │
│     - 规范化文件命名               │
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│  4. 标记内容问题                   │
│     - 缺 Anchor → status: draft   │
│     - 超预算 → 标记 needs_critique │
│     - 无法分类 → status: draft     │
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│  5. 输出规范化报告                 │
└───────────────────────────────────┘

检查项与修复策略

自动修复（机械性，无需判断）

检查项	条件	修复动作
Intent frontmatter	INTENT.md 没有 frontmatter	添加 status: active（或根据内容推断）
Planning frontmatter	planning/ 下 .md 没有 frontmatter	添加 type: (从内容推断: idea/research/feedback/analysis)
Anchor 格式	Anchor 存在但格式不对（不是 blockquote）	修正为 > Anchor: ... 格式
records/ 目录	intent 目录下没有 records/	创建 records/ + 空 INDEX.md
_archive/ 目录	intent/ 下没有 _archive/	创建 intent/_archive/
_data/ 目录	intent/ 下没有 _data/	创建 intent/_data/
TASK.yaml 格式	TASK.yaml 缺少 type 字段	添加 type: one-shot（默认）

标记 pickup（需要内容判断）

检查项	条件	标记动作
缺少 Anchor	INTENT.md 没有 Anchor 行	frontmatter 加 needs: [anchor]
超预算	行数 > 500	frontmatter 加 needs: [critique]
预算警告	300 < 行数 ≤ 500	frontmatter 加 needs: [review]
无 Assumes	内容中引用了其他 intent 但没有 Assumes 标签	frontmatter 加 needs: [assumes]
分类不明	planning 文件无法自动判断类型	type: idea（默认最安全）

needs 字段

needs 是 frontmatter 中的 pickup 信号，表示该文件需要后续处理：

---
status: active
needs: [anchor, critique]
---

TeamSwarm 扫描 needs 字段来自动调度后续 skill：

• needs: [anchor] → 安排 /intent-interview 补充
• needs: [critique] → 安排 /intent-critique 精简
• needs: [review] → 安排 /intent-review
• needs: [assumes] → 安排人工补充依赖声明

处理完成后，对应的 needs 项被移除。needs 为空时可以删掉整个字段。

Planning 类型推断

自动从文件内容推断 type:：

关键词/模式	推断类型
idea, concept, proposal, brainstorm, what if	idea
research, analysis, comparison, benchmark, study	research
feedback, user, complaint, request, survey	feedback
code analysis, refactor, migration, legacy, improvement	analysis
无法判断	idea（最安全的默认值）

执行细节

1. 扫描范围

默认扫描当前项目根目录下的：
- intent/           → 所有 INTENT.md 文件（递归，跳过 _archive/ 和 _data/）
- planning/         → 所有 .md 文件
- **/intent/        → 模块级 intent 目录

2. Frontmatter 注入

对没有 frontmatter 的文件，在文件头部插入：

Intent 文件：

---
status: active
---

如果文件看起来已经实现（有对应的代码目录和测试），推断为：

---
status: implemented
---

Planning 文件：

---
type: research
---

3. 推断 status 的启发式规则

信号	推断 status
有 TASK.yaml 且 status: done	implemented
有对应的 src/ 目录且文件最近没修改	implemented
文件内容很少（< 50 行）或明显不完整	active（+ needs: [anchor]）
默认	active

4. 幂等保证

• 已有正确 frontmatter 的文件不修改
• 已有 records/ 的不重建
• needs 字段只添加不覆盖（合并已有的）
• 每次运行结果相同

输出

规范化报告

# Intent Normalize Report

> 项目: my-project
> 扫描时间: 2026-02-06

## 统计

| 类型 | 扫描 | 已规范 | 自动修复 | 需 pickup |
|------|------|--------|----------|-----------|
| Intent 文件 | 15 | 8 | 5 | 2 |
| Planning 文件 | 7 | 2 | 4 | 1 |
| 目录结构 | — | — | 3 | — |

## 自动修复（已完成）

1. ✅ `intent/kernel/proc/INTENT.md` — 添加 frontmatter `status: active`
2. ✅ `intent/kernel/afs/INTENT.md` — 添加 frontmatter `status: implemented`
3. ✅ `planning/v2-ideas.md` — 添加 frontmatter `type: idea`
4. ✅ `planning/legacy-analysis.md` — 添加 frontmatter `type: analysis`
5. ✅ `intent/kernel/proc/records/` — 创建目录 + INDEX.md
6. ✅ `intent/_archive/` — 创建目录
7. ✅ `intent/_data/` — 创建目录

## 需要 Pickup（已标记）

| 文件 | needs | 建议 |
|------|-------|------|
| `intent/ash/INTENT.md` | `[anchor, critique]` | 缺少 Anchor，612 行超预算 |
| `intent/surfaces/INTENT.md` | `[anchor]` | 缺少 Anchor |
| `planning/random-notes.md` | — | 无法分类，默认 type: idea |

使用

基本用法

/intent-normalize

扫描并规范化当前项目。

指定路径

/intent-normalize intent/kernel/

只规范化特定目录。

Dry run

/intent-normalize --dry-run

只报告，不做任何修改。

与其他命令配合

/intent-normalize       # 先规范化格式（本命令）
    ↓
TeamSwarm pickup        # 自动调度 needs 中的后续 skill
    ↓
/intent-interview       # 处理 needs: [anchor]
/intent-critique        # 处理 needs: [critique]
/intent-review          # 处理 needs: [review]
    ↓
/intent-check           # 最终合规检查