Intent Normalize

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

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. 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)

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)

Mark for Pickup (Requires Content Judgment)

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

Field

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 Type Inference

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. Scan Scope

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 Injection

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. Heuristic Rules for Inferring status

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. Idempotence Guarantee

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

# Intent Normalize Report

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

## Statistics

| 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)

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

## Needs Pickup (Marked)

| 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 |

Usage

Basic Usage

/intent-normalize

Scan and normalize the current project.

Specify Path

/intent-normalize intent/kernel/

Only normalize the specified directory.

Dry run

/intent-normalize --dry-run

Only generate a report without making any modifications.

Integrating with Other Commands

/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

intent-normalize

NPX Install

Tags

SKILL.md Content (Chinese)

Intent Normalize

Design Principles

Workflow

Check Items and Fix Strategies

Automatic Fixes (Mechanical, No Judgment Required)

Mark for Pickup (Requires Content Judgment)

`needs`
Field

Planning Type Inference

Execution Details

1. Scan Scope

2. Frontmatter Injection

3. Heuristic Rules for Inferring status

4. Idempotence Guarantee

Output

Normalization Report

Usage

Basic Usage

Specify Path

Dry run

Integrating with Other Commands