Agent skill

intent-normalize

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.

View SKILL.md on GitHub Repository
Stars 11
Forks 4

Install this agent skill to your Project

npx add-skill https://github.com/ArcBlock/idd/tree/main/skills/intent-normalize

SKILL.md

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 信号，表示该文件需要后续处理：

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 为空时可以删掉整个字段。

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 文件：

yaml
---
status: active
---

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

yaml
---
status: implemented
---

Planning 文件：

yaml
---
type: research
---

3. 推断 status 的启发式规则

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

4. 幂等保证

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

输出

规范化报告

markdown
# 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           # 最终合规检查

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

ArcBlock/idd

intent-build-now

Start implementation from Intent. Validates Intent completeness, then either delegates to TaskSwarm (if available) or executes TDD phases directly. Use when you have an Intent ready and want to start building.

11 4
Explore
ArcBlock/idd

intent-story

Share your IDD adoption story. Through structured interviewing, create blog posts about Intent-Driven Development experiences, lessons learned, and best practices. Supports multiple languages and formats.

11 4
Explore
ArcBlock/idd

intent-critique

Critical review of Intent design quality. Checks for over-engineering, YAGNI violations, premature abstraction, and simplification opportunities. Uses interactive discussion to refine design decisions.

11 4
Explore
ArcBlock/idd

intent-changes

Manage structured change proposals for design documents with PR-like review experience. Use /intent-changes start <file> to begin, /intent-changes propose to suggest changes, /intent-changes accept/reject to decide, /intent-changes finalize to apply.

11 4
Explore
ArcBlock/idd

intent-assess

Assess if IDD fits your project and learn about Intent-Driven Development. Use /intent-assess to evaluate project suitability or /intent-assess --learn for IDD education.

11 4
Explore
ArcBlock/idd

intent-interview

11 4
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results