intent-plan

Transform an approved Intent into a structured, executable development plan with strict TDD discipline.

Output is TaskSwarm-compatible: The generated plan.md can be directly executed by /swarm run.

Core Principles

1. Test First, Always: Every implementation step starts with writing tests
2. Phased Execution: Break work into phases with clear deliverables (0-indexed)
3. Verification Gates: Each phase ends with e2e validation
4. Automation Priority: Prefer CLI/script testing over manual/browser testing
5. Checkbox Tracking: All tests use - [ ] format for progress tracking

Plan Structure

## Phase 0: [Phase Name]
├── ### Description
├── ### Tests
│   ├── #### Happy Path
│   │   └── - [ ] test case 1
│   ├── #### Bad Path (详尽列举)
│   │   └── - [ ] error case 1
│   ├── #### Edge Cases
│   │   └── - [ ] boundary case 1
│   ├── #### Security
│   │   └── - [ ] vulnerability test 1
│   ├── #### Data Leak
│   │   └── - [ ] leak prevention test 1
│   └── #### Data Damage
│       └── - [ ] integrity test 1
├── ### E2E Gate
│   └── CLI/Script 验证命令
└── ### Acceptance Criteria
    └── - [ ] criterion 1

## Phase 1: [Phase Name]
└── ...

Test Categories (6 Required)

Every phase MUST include tests from ALL 6 categories:

| Category | Description | Examples | |----------|-------------|----------| | Happy Path | Normal expected usage | Valid inputs, correct sequences | | Bad Path | Invalid inputs, error conditions | Wrong types, missing required fields, invalid states | | Edge Cases | Boundary conditions | Empty inputs, max values, concurrent access | | Security | Vulnerability prevention | Injection attacks, auth bypass, privilege escalation | | Data Leak | Information exposure | Sensitive data in logs, error messages, API responses | | Data Damage | Data integrity protection | Partial writes, corruption, race conditions |

Bad cases must be detailed and comprehensive. A good test suite has more failure tests than success tests.

Test Writing Discipline

1. Tests First: Write ALL tests before any implementation
2. Red-Green-Refactor: Run tests expecting failure, implement, verify pass
3. No Skip: Every category must have at least one test case

Phase Gates: E2E Verification (Required)

Each phase MUST end with E2E verification. This is the gate that proves the phase is truly complete.

E2E Gate Requirements

1. Automatable: Must be runnable via CLI/script, no manual steps
2. Independent: Can run without human intervention
3. Reproducible: Same inputs produce same outputs
4. Fast Feedback: Fails quickly when something is wrong

Preferred: CLI/Script Testing

# Example: API verification
curl -X POST http://localhost:3000/api/resource \
  -H "Content-Type: application/json" \
  -d '{"field": "value"}' | jq .

# Example: Database state check
psql -c "SELECT * FROM table WHERE condition"

# Example: File system verification
diff expected_output.json actual_output.json

# Example: Unit test suite
pnpm test -- --coverage

For Web Projects: Automation-Friendly Design

DO:
- Provide health check endpoints
- Return machine-parseable responses (JSON)
- Include test mode / seed data endpoints
- Design idempotent operations

DON'T:
- Require browser interaction for verification
- Depend on visual inspection
- Need manual clicking through UI

When Browser Testing is Unavoidable

If browser/headless testing is truly necessary:

• Use Playwright/Puppeteer with script automation
• Create dedicated test endpoints
• Prefer API calls over UI interaction

Pre-Plan Gates (Mandatory)

Before generating any plan, ALL gates must pass. No exceptions.

/intent-plan
    ↓
┌─────────────────────────────────────┐
│ Gate 1: Interview Check             │
│   ✗ → "先跑 /intent-interview"       │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ Gate 2: Critique Check              │
│   ✗ → "先跑 /intent-critique"        │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ Gate 3: Dependency Check            │
│   ✗ → "前置任务未完成，无法 plan"    │
└─────────────────────────────────────┘
    ↓
✓ All gates passed → Generate plan.md

Gate 1: Interview Check

Verify the Intent has been properly interviewed:

| Check | How to Verify | If Failed | |-------|---------------|-----------| | INTENT.md exists | File exists in intent directory | Run /intent-interview | | Anchor exists | First blockquote after title starts with > | Add anchor statement | | Within budget | wc -l INTENT.md ≤ 500 (warning at 300) | Run /intent-critique to reduce if > 500 | | Structure complete | Has Responsibilities, Structure, API sections | Run /intent-interview | | Not a stub | Content is substantial, not placeholder text | Run /intent-interview |

Output if failed:

❌ Gate 1 Failed: Interview Incomplete

INTENT.md is missing or incomplete:
- [ ] Responsibilities section missing
- [ ] Structure diagram missing

Action required: Run /intent-interview first.

Gate 2: Critique Check

Verify the Intent has been critiqued for over-engineering:

| Check | How to Verify | If Failed | |-------|---------------|-----------| | Critique done | Look for critique markers or changelog | Run /intent-critique | | Post-modification | If INTENT.md modified after last critique | Run /intent-critique again | | AI assessment | Ask AI if another critique round is needed | Run /intent-critique if yes |

Critique markers to look for:

• <!-- critique: {date} --> comment in INTENT.md
• critique.md or CRITIQUE.md in same directory
• Changelog entry mentioning critique

Post-modification detection:

• Compare INTENT.md mtime with critique marker date
• If INTENT.md is newer AND has substantial changes → re-critique required

AI Assessment prompt:

"Based on this Intent, is there any sign of over-engineering, premature abstraction, or YAGNI violation that warrants another critique round?"

Output if failed:

❌ Gate 2 Failed: Critique Required

Intent has not been critiqued, or was modified after critique:
- Last critique: 2026-01-15
- INTENT.md modified: 2026-01-20 (substantial changes detected)

Action required: Run /intent-critique to review for over-engineering.

Gate 3: Dependency Check

Verify all prerequisites are satisfied:

| Check | How to Verify | If Failed | |-------|---------------|-----------| | Internal deps | Referenced intents have status: done in TASK.yaml | List blocking intents | | External deps | Required packages/services exist | List missing dependencies | | Environment | Required env vars, credentials, access | List missing setup |

How to find dependencies:

1. Parse ## Prerequisites or ## Dependencies in INTENT.md
2. Look for depends_on: in TASK.yaml (if exists)
3. Scan for references like intent/other-feature/ or @package/name

Dependency states:

intent/auth/         → TASK.yaml status: done     ✓ OK
intent/database/     → TASK.yaml status: review   ✗ Blocked (not done)
intent/api/          → No TASK.yaml               ? Assume not started
@aigne/afs           → Check packages/ or deps    ✓/✗

Output if failed:

❌ Gate 3 Failed: Dependencies Not Ready

This Intent cannot be planned because prerequisites are incomplete:

Blocking Intents:
- intent/auth-module/ → status: in_progress (need: done)
- intent/database-setup/ → status: ready (need: done)

Missing External Dependencies:
- @aigne/session-protocol → not found in packages/

Action required: Complete blocking tasks first, or remove dependencies from INTENT.md if not actually needed.

Gate Pass Output

When all gates pass:

✓ Gate 1: Interview complete
✓ Gate 2: Critique done (2026-01-20), no re-critique needed
✓ Gate 3: All 2 dependencies satisfied

Proceeding to generate plan...

Workflow

/intent-plan
    ↓
Gate 1: Interview Check ──→ ✗ → Stop, require /intent-interview
    ↓ ✓
Gate 2: Critique Check ───→ ✗ → Stop, require /intent-critique
    ↓ ✓
Gate 3: Dependency Check ─→ ✗ → Stop, list blockers
    ↓ ✓
Read Intent file
    ↓
Analyze scope and complexity
    ↓
Identify logical phases (0-indexed)
    ↓
For each phase, define:
    - Description
    - Tests (6 categories)
    - E2E Gate
    - Acceptance Criteria
    ↓
Present plan for approval
    ↓
User confirms or adjusts
    ↓
Save to plan.md (same directory as INTENT.md)
    ↓
Create TASK.yaml (status: ready)

Output Files

1. plan.md (Required)

# Execution Plan: {task_name}

## Overview

简要说明这个任务要做什么。

## Prerequisites

- 前置条件
- 依赖的其他任务
- 需要的权限或资源

## Phase 0: {Phase Name}

### Description

这个阶段要完成什么，交付什么。

### Tests

#### Happy Path
- [ ] 测试正常流程 1: {具体描述}
- [ ] 测试正常流程 2: {具体描述}

#### Bad Path
- [ ] 无效输入: {具体场景}
- [ ] 缺失必填字段: {具体场景}
- [ ] 错误状态: {具体场景}
- [ ] 类型错误: {具体场景}

#### Edge Cases
- [ ] 空输入处理
- [ ] 最大值边界
- [ ] 并发访问

#### Security
- [ ] 注入攻击防护: {具体场景}
- [ ] 权限绕过防护: {具体场景}
- [ ] 输入验证: {具体场景}

#### Data Leak
- [ ] 错误信息不泄露敏感数据
- [ ] 日志不包含敏感信息
- [ ] API 响应不过度暴露

#### Data Damage
- [ ] 部分写入恢复
- [ ] 竞态条件处理
- [ ] 事务完整性

### E2E Gate

```bash
# Phase 完成验证脚本
{CLI commands to verify phase completion}

Acceptance Criteria

• [ ] 所有 6 类测试通过
• [ ] E2E Gate 验证通过
• [ ] 代码已提交并 push

---

Phase 1: {Phase Name}

Description

下一阶段要完成什么。

Tests

Happy Path

• [ ] 测试正常流程

Bad Path

• [ ] 测试错误处理 1
• [ ] 测试错误处理 2

Edge Cases

• [ ] 边界条件处理

Security

• [ ] 安全测试

Data Leak

• [ ] 泄露防护测试

Data Damage

• [ ] 数据完整性测试

E2E Gate

# Phase 1 验证脚本

Acceptance Criteria

• [ ] 所有测试通过
• [ ] E2E Gate 验证通过

---

Final E2E Verification

# 全系统端到端验证脚本
# 验证所有 Phase 的功能协同工作

Risk Mitigation

| Risk | Mitigation | Contingency | |------|------------|-------------| | [风险 1] | [预防措施] | [发生时的应对] |

References

• 相关 Intent
• 详细规格 (如果存在)
• 设计文档 (如果存在)

### 2. TASK.yaml (Required)

```yaml
status: ready
owner: null
assignee: null
phase: 0/{total_phases}
updated: {UTC_ISO_TIMESTAMP}
heartbeat: null

Important: {total_phases} is the number of phases in plan.md (0-indexed counting).

Integration with IDD & TaskSwarm

IDD Flow:
/intent-interview     # Create Intent (Gate 1 requirement)
    ↓
/intent-critique      # Review for over-engineering (Gate 2 requirement)
    ↓
/intent-review        # Approve Intent (optional but recommended)
    ↓
/intent-plan          # Gate checks → Generate plan.md + TASK.yaml (THIS SKILL)
    ↓
TaskSwarm Flow:
/swarm run            # Execute plan (TDD cycles)
    ↓
/swarm approve        # Human review
    ↓
/intent-sync          # Write back confirmed details

Gate enforcement ensures quality:

• No plan without proper interview → avoids vague/incomplete specs
• No plan without critique → avoids over-engineered designs
• No plan with missing deps → avoids unexecutable plans

Tips for Good Plans

Format (TaskSwarm Compatible)

1. 0-indexed phases: Phase 0, Phase 1, Phase 2...
2. Checkbox format: All tests use - [ ] for progress tracking
3. E2E Gate per phase: Each phase must have runnable verification

Test Quality

4. All 6 categories required: Happy/Bad/Edge/Security/Data Leak/Data Damage
5. Bad Path > Happy Path: More failure tests than success tests
6. Specific test cases: "Test error handling" ✗ → "returns 404 when resource not found" ✓
7. Security by default: Include even if not explicitly requested

Phase Design

8. Right-size phases: Each phase completable in 1-3 days
9. Clear dependencies: Note when phases depend on previous phases
10. Automatable gates: E2E Gate must be runnable via CLI, no manual steps

Example: Complete Output

For an Intent at intent/session-protocol/INTENT.md:

Creates: intent/session-protocol/plan.md

# Execution Plan: session-protocol

## Overview

实现 Session Protocol 的 Frame 编解码功能。

## Prerequisites

- @aigne/afs 包已存在
- TypeScript 环境配置完成

## Phase 0: Frame Encoding

### Description

实现 Frame 的编码函数，将结构化数据转换为二进制格式。

### Tests

#### Happy Path
- [ ] encodes empty frame correctly
- [ ] encodes frame with JSON payload
- [ ] encodes frame with binary payload
- [ ] preserves ReqId across encode/decode

#### Bad Path
- [ ] throws on invalid frame type
- [ ] throws on payload exceeding max size
- [ ] throws on null payload when required
- [ ] throws on negative ReqId
- [ ] throws on non-integer frame type

#### Edge Cases
- [ ] handles empty string payload
- [ ] handles maximum allowed payload size (64KB)
- [ ] handles unicode in JSON payload
- [ ] handles zero-length binary payload

#### Security
- [ ] rejects frames with potential injection patterns
- [ ] validates frame type bounds (0-255)
- [ ] sanitizes string inputs before encoding

#### Data Leak
- [ ] error messages don't expose internal structure
- [ ] stack traces not included in thrown errors

#### Data Damage
- [ ] atomic write: partial encode doesn't corrupt buffer
- [ ] buffer overflow protection

### E2E Gate

```bash
# Verify encoding works end-to-end
pnpm test -- --grep "Frame Encoding"
pnpm test:e2e -- --grep "encode"

Acceptance Criteria

• [ ] 所有 6 类测试通过
• [ ] E2E Gate 验证通过
• [ ] 100% 分支覆盖率
• [ ] 代码已提交

---

Phase 1: Frame Decoding

Description

实现 Frame 的解码函数，将二进制数据解析为结构化对象。

Tests

Happy Path

• [ ] decodes valid frame correctly
• [ ] handles streaming decode
• [ ] decodes all frame types

Bad Path

• [ ] throws on truncated frame
• [ ] throws on corrupted header
• [ ] throws on invalid magic bytes
• [ ] throws on unsupported version

Edge Cases

• [ ] handles minimum valid frame
• [ ] handles maximum valid frame
• [ ] handles back-to-back frames in stream

Security

• [ ] validates frame length before allocation
• [ ] rejects oversized frames (DoS protection)

Data Leak

• [ ] doesn't expose raw bytes in error messages

Data Damage

• [ ] partial decode doesn't advance stream position
• [ ] corrupted frame doesn't affect subsequent frames

E2E Gate

# Verify full roundtrip
pnpm test -- --grep "Frame"
echo '{"test":1}' | node scripts/encode-decode-test.js

Acceptance Criteria

• [ ] 所有测试通过
• [ ] E2E roundtrip 验证通过
• [ ] 代码已提交

---

Final E2E Verification

# Full integration test
pnpm test
pnpm test:e2e

References

• Intent
• Spec

**Creates**: `intent/session-protocol/TASK.yaml`
```yaml
status: ready
owner: null
assignee: null
phase: 0/2
updated: 2026-01-27T10:00:00Z
heartbeat: null