Scan existing projects and normalize intent and planning files to the IDD standard. Fix what can be fixed automatically; mark what cannot be fixed with a status for TeamSwarm to pick up.
Design principles
- Format first — All files must first have frontmatter so the system can recognize them
- Fix when possible — Fix mechanical issues directly (frontmatter, directory structure, naming)
- Mark when unable to fix — Mark content issues with a status for TeamSwarm or a human to handle later
- Idempotent — Results are consistent across 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. 输出规范化报告 │
└───────────────────────────────────┘
Checks and fix strategy
Automatic fixes (mechanical, no judgment needed)
| Check | 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 format is wrong (not a blockquote) | Fix to > Anchor: ... format |
| records/ directory | No records/ under the 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 is missing the type field | Add type: one-shot(default) |
Pickup marking (requires content judgment)
| Check | Condition | Mark action |
|---|---|---|
| Missing Anchor | INTENT.md has no Anchor line | Add to frontmatter needs: [anchor] |
| Over budget | Line count > 500 | Add to frontmatter needs: [critique] |
| Budget warning | 300 < line count ≤ 500 | Add to frontmatter needs: [review] |
| No Assumes | Content references other intents but has no Assumes tag | Add to frontmatter needs: [assumes] |
| Unclear classification | Planning file type cannot be determined automatically | type: idea(safest default) |
needs field
needs is the pickup signal in frontmatter, indicating that the file needs further processing:
---
status: active
needs: [anchor, critique]
---
TeamSwarm scans needs field to automatically schedule follow-up skills:
needs: [anchor]→ schedule/intent-interviewsupplementneeds: [critique]→ schedule/intent-critiquestreamlineneeds: [review]→ schedule/intent-reviewneeds: [assumes]→ schedule manual supplement of dependency declarations
After processing is complete, the corresponding needs item is removed.needs When empty, the entire field can be deleted.
Planning type inference
Automatically infer from file content type:：
| Keyword/pattern | 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 value) |
Execution details
1. Scan scope
默认扫描当前项目根目录下的：
- intent/ → 所有 INTENT.md 文件（递归，跳过 _archive/ 和 _data/）
- planning/ → 所有 .md 文件
- **/intent/ → 模块级 intent 目录
2. Frontmatter injection
For files without frontmatter, insert at the beginning of the file:
Intent files:
---
status: active
---
If the file appears to already be implemented (there is a corresponding code directory and tests), infer as:
---
status: implemented
---
Planning files:
---
type: research
---
3. Heuristic rules for inferring status
| Signal | Inferred status |
|---|---|
| Has TASK.yaml and status: done | implemented |
| Has a corresponding src/ directory and the files have not been modified recently | implemented |
| The file content is very small (< 50 lines) or clearly incomplete | active（+ needs: [anchor]） |
| Default | active |
4. Idempotency guarantee
- Files that already have correct frontmatter are not modified
- Existing records/ are not rebuilt
needsFields are only added, not overwritten (merge with existing)- Each run produces the same result
Output
Normalization report
# 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 |
Usage
Basic usage
/intent-normalize
Scan and normalize the current project.
Specify a path
/intent-normalize intent/kernel/
Only normalize a specific directory.
Dry run
/intent-normalize --dry-run
Report only, make no modifications.
Work with other commands
/intent-normalize # 先规范化格式（本命令）
↓
TeamSwarm pickup # 自动调度 needs 中的后续 skill
↓
/intent-interview # 处理 needs: [anchor]
/intent-critique # 处理 needs: [critique]
/intent-review # 处理 needs: [review]
↓
/intent-check # 最终合规检查