intent-normalize

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Intent Normalize

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

Scan existing projects to normalize intent and planning files to the IDD standard. Automatically fix issues that can be resolved mechanically, and mark the status of issues that cannot be fixed for TeamSwarm to pickup.

设计原则

Design Principles

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

Format First — All files must have frontmatter first so that the system can identify them
Fix What Can Be Fixed — Directly fix mechanical issues (frontmatter, directory structure, naming)
Mark What Cannot Be Fixed — Mark content issues with statuses for subsequent handling by TeamSwarm or humans
Idempotent — Consistent results after multiple runs; already normalized files will not be modified

工作流程

Workflow

/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-normalize [path]
        ↓
┌───────────────────────────────────┐
│ 1. Scan intent/ and planning/     │
│    Discover all .md and .yaml files│
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│ 2. Analyze compliance status of each file │
│    - Has frontmatter?             │
│    - Has Anchor?                  │
│    - Is directory structure complete? │
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│ 3. Automatically fix mechanical issues │
│    - Add frontmatter              │
│    - Create records/ + INDEX.md   │
│    - Create _archive/, _data/     │
│    - Standardize file naming      │
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│ 4. Mark content issues            │
│    - Missing Anchor → status: draft │
│    - Over budget → mark needs_critique │
│    - Unclassifiable → status: draft │
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│ 5. Output normalization report    │
└───────────────────────────────────┘

检查项与修复策略

Check Items and Fix Strategies

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

Automatic Fixes (Mechanical, No Judgment Required)

检查项	条件	修复动作
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` （默认）

Check Item	Condition	Fix Action
Intent frontmatter	INTENT.md has no frontmatter	Add `status: active` (or infer from content)
Planning frontmatter	.md files under planning/ have no frontmatter	Add `type:` (infer from content: idea/research/feedback/analysis)
Anchor Format	Anchor exists but has incorrect format (not a blockquote)	Correct to `> Anchor: ...` format
records/ Directory	No records/ under intent directory	Create `records/` + empty `INDEX.md`
_archive/ Directory	No _archive/ under intent/	Create `intent/_archive/`
_data/ Directory	No _data/ under intent/	Create `intent/_data/`
TASK.yaml Format	TASK.yaml lacks type field	Add `type: one-shot` (default)

标记 pickup（需要内容判断）

Mark for Pickup (Requires Content Judgment)

检查项	条件	标记动作
缺少 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` （默认最安全）

Check Item	Condition	Marking Action
Missing Anchor	INTENT.md has no Anchor line	Add `needs: [anchor]` to frontmatter
Over Budget	Number of lines > 500	Add `needs: [critique]` to frontmatter
Budget Warning	300 < Number of lines ≤ 500	Add `needs: [review]` to frontmatter
No Assumes	References other intents in content but no Assumes tag	Add `needs: [assumes]` to frontmatter
Unclear Classification	Cannot automatically determine the type of planning file	`type: idea` (safest default)

needs

字段

needs

Field

needs

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

yaml

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

TeamSwarm 扫描

needs

字段来自动调度后续 skill：

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

处理完成后，对应的

needs

项被移除。

needs

为空时可以删掉整个字段。

needs

is a pickup signal in the frontmatter, indicating that the file requires subsequent processing:

yaml

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

TeamSwarm scans the

needs

field to automatically schedule subsequent skills:

```
needs: [anchor]
```
→ Schedule
```
/intent-interview
```
to supplement
```
needs: [critique]
```
→ Schedule
```
/intent-critique
```
to streamline
```
needs: [review]
```
→ Schedule
```
/intent-review
```
```
needs: [assumes]
```
→ Schedule manual supplement of dependency declarations

After processing, the corresponding

needs

items are removed. The entire

needs

field can be deleted when it is empty.

Planning 类型推断

Planning Type Inference

自动从文件内容推断

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` （最安全的默认值）

Automatically infer

type:

from file content:

Keywords/Patterns	Inferred 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`
Cannot determine	`idea` (safest default)

执行细节

Execution Details

1. 扫描范围

1. Scan Scope

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

Default scan of the following under the current project root directory:
- intent/           → All INTENT.md files (recursive, skip _archive/ and _data/)
- planning/         → All .md files
- **/intent/        → Module-level intent directories

2. Frontmatter 注入

2. Frontmatter Injection

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

Intent 文件：

yaml

---
status: active
---

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

yaml

---
status: implemented
---

Planning 文件：

yaml

---
type: research
---

For files without frontmatter, insert at the top of the file:

Intent Files:

yaml

---
status: active
---

If the file appears to be implemented (has corresponding code directories and tests), infer as:

yaml

---
status: implemented
---

Planning Files:

yaml

---
type: research
---

3. 推断 status 的启发式规则

3. Heuristic Rules for Inferring status

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

Signal	Inferred status
Has TASK.yaml with status: done	`implemented`
Has corresponding src/ directory and files have not been modified recently	`implemented`
File content is very short (< 50 lines) or obviously incomplete	`active` (plus `needs: [anchor]` )
Default	`active`

4. 幂等保证

4. Idempotence Guarantee

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

Files with correct frontmatter are not modified
Existing records/ directories are not recreated
The
```
needs
```
field is only added to, not overwritten (merge existing entries)
Consistent results with each run

输出

Output

规范化报告

Normalization Report

markdown

undefined

markdown

undefined

Intent Normalize Report

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

Project: my-project Scan Time: 2026-02-06

统计

Statistics

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

Type	Scanned	Normalized	Auto-Fixed	Needs Pickup
Intent Files	15	8	5	2
Planning Files	7	2	4	1
Directory Structure	—	—	3	—

自动修复（已完成）

Auto-Fixes (Completed)

✅

intent/kernel/proc/INTENT.md

— 添加 frontmatter

status: active

✅

intent/kernel/afs/INTENT.md

— 添加 frontmatter

status: implemented

✅
```
planning/v2-ideas.md
```
— 添加 frontmatter
```
type: idea
```

✅

planning/legacy-analysis.md

— 添加 frontmatter

type: analysis

✅
```
intent/kernel/proc/records/
```
— 创建目录 + INDEX.md
✅
```
intent/_archive/
```
— 创建目录
✅
```
intent/_data/
```
— 创建目录

✅

intent/kernel/proc/INTENT.md

— Added frontmatter

status: active

✅

intent/kernel/afs/INTENT.md

— Added frontmatter

status: implemented

✅
```
planning/v2-ideas.md
```
— Added frontmatter
```
type: idea
```

✅

planning/legacy-analysis.md

— Added frontmatter

type: analysis

✅
```
intent/kernel/proc/records/
```
— Created directory + INDEX.md
✅
```
intent/_archive/
```
— Created directory
✅
```
intent/_data/
```
— Created directory

需要 Pickup（已标记）

Needs Pickup (Marked)

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

undefined

File	needs	Suggestion
`intent/ash/INTENT.md`	`[anchor, critique]`	Missing Anchor, 612 lines exceed budget
`intent/surfaces/INTENT.md`	`[anchor]`	Missing Anchor
`planning/random-notes.md`	—	Cannot be classified, default type: idea

undefined

使用

Usage

基本用法

Basic Usage

/intent-normalize

扫描并规范化当前项目。

/intent-normalize

Scan and normalize the current project.

指定路径

Specify Path

/intent-normalize intent/kernel/

只规范化特定目录。

/intent-normalize intent/kernel/

Only normalize the specified directory.

Dry run

/intent-normalize --dry-run

只报告，不做任何修改。

/intent-normalize --dry-run

Only generate a report without making any modifications.

与其他命令配合

Integrating with Other Commands

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

/intent-normalize       # First normalize formats (this command)
    ↓
TeamSwarm pickup        # Automatically schedule subsequent skills in needs
    ↓
/intent-interview       # Handle needs: [anchor]
/intent-critique        # Handle needs: [critique]
/intent-review          # Handle needs: [review]
    ↓
/intent-check           # Final compliance check