Back to Details

intent-plan

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Intent Plan

Intent 计划

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
.
将已获批的Intent转换为遵循严格TDD规范的结构化、可执行开发计划。
输出与TaskSwarm兼容：生成的plan.md可直接通过
/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
  1. 始终测试先行：每个实现步骤都从编写测试开始
  2. 分阶段执行：将工作拆分为具有明确交付物的阶段（从0开始编号）
  3. 验证关卡：每个阶段结束时进行端到端（e2e）验证
  4. 优先自动化：优先使用CLI/脚本测试，而非手动/浏览器测试
  5. 复选框跟踪：所有测试均使用
    - [ ]
    格式跟踪进度

Plan Structure

计划结构

undefined
undefined

Phase 0: [Phase Name]

Phase 0: [阶段名称]

├── ### 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
├── ### 描述 ├── ### 测试 │ ├── #### 正常路径 │ │ └── - [ ] 测试用例1 │ ├── #### 异常路径（详尽列举） │ │ └── - [ ] 错误场景1 │ ├── #### 边界场景 │ │ └── - [ ] 边界用例1 │ ├── #### 安全 │ │ └── - [ ] 漏洞测试1 │ ├── #### 数据泄露 │ │ └── - [ ] 防泄露测试1 │ └── #### 数据损坏 │ └── - [ ] 完整性测试1 ├── ### E2E 验证关卡 │ └── CLI/脚本验证命令 └── ### 验收标准 └── - [ ] 验收条件1

Phase 1: [Phase Name]

Phase 1: [阶段名称]

└── ...
undefined
└── ...
undefined

Test Categories (6 Required)

测试类别（6类必填）

Every phase MUST include tests from ALL 6 categories:
CategoryDescriptionExamples
Happy PathNormal expected usageValid inputs, correct sequences
Bad PathInvalid inputs, error conditionsWrong types, missing required fields, invalid states
Edge CasesBoundary conditionsEmpty inputs, max values, concurrent access
SecurityVulnerability preventionInjection attacks, auth bypass, privilege escalation
Data LeakInformation exposureSensitive data in logs, error messages, API responses
Data DamageData integrity protectionPartial writes, corruption, race conditions
Bad cases must be detailed and comprehensive. A good test suite has more failure tests than success tests.
每个阶段必须包含所有6类测试：
类别描述示例
正常路径（Happy Path）预期的正常使用场景有效输入、正确流程
异常路径（Bad Path）无效输入、错误条件错误类型、缺失必填字段、无效状态
边界场景（Edge Cases）边界条件空输入、最大值、并发访问
安全（Security）漏洞防护注入攻击、权限绕过、权限提升
数据泄露（Data Leak）信息暴露日志中的敏感数据、错误信息、API响应
数据损坏（Data Damage）数据完整性保护部分写入、数据损坏、竞态条件
异常场景必须详尽全面。优质的测试套件中，失败测试的数量应多于成功测试。

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
  1. 测试先行：在任何实现前编写所有测试
  2. 红-绿-重构：先运行测试预期失败，再实现功能，最后验证通过
  3. 无遗漏：每个类别至少包含一个测试用例

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

E2E验证关卡要求

  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
  1. 可自动化：必须可通过CLI/脚本运行，无手动步骤
  2. 独立执行：无需人工干预即可运行
  3. 可复现：相同输入产生相同输出
  4. 快速反馈：出现问题时可快速失败

Preferred: CLI/Script Testing

首选：CLI/脚本测试

bash
undefined
bash
undefined

Example: API verification

示例：API验证

curl -X POST http://localhost:3000/api/resource
-H "Content-Type: application/json"
-d '{"field": "value"}' | jq .
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"
psql -c "SELECT * FROM table WHERE condition"

Example: File system verification

示例：文件系统验证

diff expected_output.json actual_output.json
diff expected_output.json actual_output.json

Example: Unit test suite

示例：单元测试套件

pnpm test -- --coverage
undefined
pnpm test -- --coverage
undefined

For Web Projects: Automation-Friendly Design

Web项目：自动化友好设计

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
推荐做法：
- 提供健康检查端点
- 返回机器可解析的响应（JSON格式）
- 包含测试模式/种子数据端点
- 设计幂等操作

不推荐：
- 验证时需要浏览器交互
- 依赖视觉检查
- 需要手动点击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
如果确实需要浏览器/无头测试：
  • 使用Playwright/Puppeteer实现脚本自动化
  • 创建专用测试端点
  • 优先使用API调用而非UI交互

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
在生成任何计划前，所有关卡必须通过，无例外。
/intent-plan
    ↓
┌─────────────────────────────────────┐
│ 关卡1：访谈检查                     │
│   ✗ → "先运行 /intent-interview"    │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ 关卡2：评审检查                     │
│   ✗ → "先运行 /intent-critique"     │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ 关卡3：依赖检查                     │
│   ✗ → "前置任务未完成，无法制定计划"│
└─────────────────────────────────────┘
    ↓
✓ 所有关卡通过 → 生成plan.md

Gate 1: Interview Check

关卡1：访谈检查

Verify the Intent has been properly interviewed:
CheckHow to VerifyIf Failed
INTENT.md existsFile exists in intent directoryRun 
/intent-interview
Structure completeHas Responsibilities, Structure, API sectionsRun 
/intent-interview
Not a stubContent is substantial, not placeholder textRun 
/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.
验证Intent已完成完整访谈：
检查项验证方式失败时操作
INTENT.md存在检查intent目录下是否有该文件运行
/intent-interview
结构完整包含职责、架构、API章节运行
/intent-interview
非占位内容内容充实，非占位文本运行
/intent-interview
失败时输出：
❌ 关卡1失败：访谈不完整

INTENT.md缺失或不完整：
- [ ] 缺少职责章节
- [ ] 缺少架构图

需执行操作：先运行/intent-interview。

Gate 2: Critique Check

关卡2：评审检查

Verify the Intent has been critiqued for over-engineering:
CheckHow to VerifyIf Failed
Critique doneLook for critique markers or changelogRun 
/intent-critique
Post-modificationIf INTENT.md modified after last critiqueRun 
/intent-critique
again
AI assessmentAsk AI if another critique round is neededRun 
/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.
验证Intent已完成过度设计评审：
检查项验证方式失败时操作
已完成评审查找评审标记或变更日志运行
/intent-critique
评审后未修改若INTENT.md在最后一次评审后被修改重新运行
/intent-critique
AI评估询问AI是否需要再次评审若需要则运行
/intent-critique
需查找的评审标记：
  • INTENT.md中的
    <!-- critique: {date} -->
    注释
  • 同目录下的
    critique.md
    或
    CRITIQUE.md
  • 变更日志中提及评审的条目
评审后修改检测：
  • 比较INTENT.md的修改时间与评审标记日期
  • 若INTENT.md更新且有实质性变更 → 需要重新评审
AI评估提示词：
"基于此Intent，是否存在过度设计、过早抽象或违反YAGNI原则的迹象，需要再次评审？"
失败时输出：
❌ 关卡2失败：需要评审

Intent尚未评审，或评审后被修改：
- 最后一次评审：2026-01-15
- INTENT.md修改时间：2026-01-20（检测到实质性变更）

需执行操作：运行/intent-critique以评审过度设计问题。

Gate 3: Dependency Check

关卡3：依赖检查

Verify all prerequisites are satisfied:
CheckHow to VerifyIf Failed
Internal depsReferenced intents have 
status: done
in TASK.yaml		List blocking intents
External depsRequired packages/services existList missing dependencies
EnvironmentRequired env vars, credentials, accessList 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.
验证所有前置条件已满足：
检查项验证方式失败时操作
内部依赖引用的intent在TASK.yaml中
status: done
列出阻塞的intent
外部依赖所需的包/服务已存在列出缺失的依赖
环境配置所需的环境变量、凭证、访问权限已就绪列出缺失的配置
如何查找依赖：
  1. 解析INTENT.md中的
    ## 前置条件
    或
    ## 依赖
    章节
  2. 查找TASK.yaml中的
    depends_on:
    字段（若存在）
  3. 扫描类似
    intent/other-feature/
    或
    @package/name
    的引用
依赖状态示例：
intent/auth/         → TASK.yaml状态: done     ✓ 已就绪
intent/database/     → TASK.yaml状态: review   ✗ 阻塞（未完成）
intent/api/          → 无TASK.yaml               ? 假设未启动
@aigne/afs           → 检查packages/或依赖项     ✓/✗
失败时输出：
❌ 关卡3失败：依赖未就绪

无法为此Intent制定计划，因为前置条件未完成：

阻塞的Intent：
- intent/auth-module/ → 状态: in_progress（需要: done）
- intent/database-setup/ → 状态: ready（需要: done）

缺失的外部依赖：
- @aigne/session-protocol → 未在packages/中找到

需执行操作：先完成阻塞任务，或若实际不需要则从INTENT.md中移除依赖。

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...
当所有关卡通过：
✓ 关卡1：访谈已完成
✓ 关卡2：评审已完成（2026-01-20），无需再次评审
✓ 关卡3：所有2项依赖已满足

开始生成计划...

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)
/intent-plan
    ↓
关卡1：访谈检查 ──→ ✗ → 停止，要求运行/intent-interview
    ↓ ✓
关卡2：评审检查 ───→ ✗ → 停止，要求运行/intent-critique
    ↓ ✓
关卡3：依赖检查 ─→ ✗ → 停止，列出阻塞项
    ↓ ✓
读取Intent文件
    ↓
分析范围与复杂度
    ↓
确定逻辑阶段（从0开始编号）
    ↓
为每个阶段定义：
    - 描述
    - 测试（6类）
    - E2E验证关卡
    - 验收标准
    ↓
提交计划待批准
    ↓
用户确认或调整
    ↓
保存至plan.md（与INTENT.md同目录）
    ↓
创建TASK.yaml（状态: ready）

Output Files

输出文件

1. plan.md (Required)

1. plan.md（必填）

markdown
undefined
markdown
undefined

Execution Plan: {task_name}

执行计划: {任务名称}

Overview

概述

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

Prerequisites

前置条件

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

Phase 0: {Phase Name}

Phase 0: {阶段名称}

Description

描述

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

Tests

测试

Happy Path

正常路径

  • 测试正常流程 1: {具体描述}
  • 测试正常流程 2: {具体描述}
  • 测试正常流程 1: {具体描述}
  • 测试正常流程 2: {具体描述}

Bad Path

异常路径

  • 无效输入: {具体场景}
  • 缺失必填字段: {具体场景}
  • 错误状态: {具体场景}
  • 类型错误: {具体场景}
  • 无效输入: {具体场景}
  • 缺失必填字段: {具体场景}
  • 错误状态: {具体场景}
  • 类型错误: {具体场景}

Edge Cases

边界场景

  • 空输入处理
  • 最大值边界
  • 并发访问
  • 空输入处理
  • 最大值边界
  • 并发访问

Security

安全

  • 注入攻击防护: {具体场景}
  • 权限绕过防护: {具体场景}
  • 输入验证: {具体场景}
  • 注入攻击防护: {具体场景}
  • 权限绕过防护: {具体场景}
  • 输入验证: {具体场景}

Data Leak

数据泄露

  • 错误信息不泄露敏感数据
  • 日志不包含敏感信息
  • API 响应不过度暴露
  • 错误信息不泄露敏感数据
  • 日志不包含敏感信息
  • API响应不过度暴露

Data Damage

数据损坏

  • 部分写入恢复
  • 竞态条件处理
  • 事务完整性
  • 部分写入恢复
  • 竞态条件处理
  • 事务完整性

E2E Gate

E2E验证关卡

bash
undefined
bash
undefined

Phase 完成验证脚本

阶段完成验证脚本

{CLI commands to verify phase completion}
undefined
{验证阶段完成的CLI命令}
undefined

Acceptance Criteria

验收标准

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

Phase 1: {Phase Name}

Phase 1: {阶段名称}

Description

描述

下一阶段要完成什么。
下一阶段要完成什么。

Tests

测试

Happy Path

正常路径

  • 测试正常流程
  • 测试正常流程

Bad Path

异常路径

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

Edge Cases

边界场景

  • 边界条件处理
  • 边界条件处理

Security

安全

  • 安全测试
  • 安全测试

Data Leak

数据泄露

  • 泄露防护测试
  • 泄露防护测试

Data Damage

数据损坏

  • 数据完整性测试
  • 数据完整性测试

E2E Gate

E2E验证关卡

bash
undefined
bash
undefined

Phase 1 验证脚本

Phase 1验证脚本

undefined
undefined

Acceptance Criteria

验收标准

  • 所有测试通过
  • E2E Gate 验证通过
  • 所有测试通过
  • E2E验证关卡通过

Final E2E Verification

最终端到端验证

bash
undefined
bash
undefined

全系统端到端验证脚本

全系统端到端验证脚本

验证所有 Phase 的功能协同工作

验证所有阶段的功能协同工作

undefined
undefined

Risk Mitigation

风险缓解

RiskMitigationContingency
[风险 1][预防措施][发生时的应对]
风险缓解措施应急预案
[风险1][预防措施][发生时的应对]

References

参考资料

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

2. TASK.yaml (Required)

2. TASK.yaml（必填）

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).
yaml
status: ready
owner: null
assignee: null
phase: 0/{总阶段数}
updated: {UTC_ISO_TIMESTAMP}
heartbeat: null
注意：
{总阶段数}
是plan.md中的阶段数量（按从0开始的计数方式）。

Integration with IDD & TaskSwarm

与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
IDD流程：
/intent-interview     # 创建Intent（关卡1要求）
    ↓
/intent-critique      # 评审过度设计问题（关卡2要求）
    ↓
/intent-review        # 批准Intent（可选但推荐）
    ↓
/intent-plan          # 关卡检查 → 生成plan.md + TASK.yaml（本技能）
    ↓
TaskSwarm流程：
/swarm run            # 执行计划（TDD循环）
    ↓
/swarm approve        # 人工评审
    ↓
/intent-sync          # 写入已确认的细节
关卡强制保证质量：
  • 无完整访谈则不生成计划 → 避免模糊/不完整的需求
  • 无评审则不生成计划 → 避免过度设计的方案
  • 依赖未就绪则不生成计划 → 避免无法执行的计划

Tips for Good Plans

优质计划的技巧

Format (TaskSwarm Compatible)

格式（兼容TaskSwarm）

  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
  1. 阶段从0开始编号：Phase 0, Phase 1, Phase 2...
  2. 复选框格式：所有测试使用
    - [ ]
    跟踪进度
  3. 每个阶段设E2E验证关卡：每个阶段必须有可运行的验证步骤

Test Quality

测试质量

  1. All 6 categories required: Happy/Bad/Edge/Security/Data Leak/Data Damage
  2. Bad Path > Happy Path: More failure tests than success tests
  3. Specific test cases: "Test error handling" ✗ → "returns 404 when resource not found" ✓
  4. Security by default: Include even if not explicitly requested
  1. 必填所有6类测试：正常/异常/边界/安全/数据泄露/数据损坏
  2. 异常路径测试多于正常路径：失败测试数量多于成功测试
  3. 测试用例具体化："测试错误处理" ✗ → "资源不存在时返回404" ✓
  4. 默认包含安全测试：即使未明确要求也需包含

Phase Design

阶段设计

  1. Right-size phases: Each phase completable in 1-3 days
  2. Clear dependencies: Note when phases depend on previous phases
  3. Automatable gates: E2E Gate must be runnable via CLI, no manual steps
  1. 阶段大小合适：每个阶段可在1-3天内完成
  2. 明确依赖关系：注明阶段是否依赖前序阶段
  3. 验证关卡可自动化：E2E验证关卡必须可通过CLI运行，无手动步骤

Example: Complete Output

示例：完整输出

For an Intent at 
intent/session-protocol/INTENT.md
:
Creates: 
intent/session-protocol/plan.md
markdown
undefined
对于位于
intent/session-protocol/INTENT.md
的Intent：
生成文件：
intent/session-protocol/plan.md
markdown
undefined

Execution Plan: session-protocol

执行计划: session-protocol

Overview

概述

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

Prerequisites

前置条件

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

Phase 0: Frame Encoding

Phase 0: Frame编码

Description

描述

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

Tests

测试

Happy Path

正常路径

  • encodes empty frame correctly
  • encodes frame with JSON payload
  • encodes frame with binary payload
  • preserves ReqId across encode/decode
  • 正确编码空frame
  • 编码带JSON负载的frame
  • 编码带二进制负载的frame
  • 编解码过程中保留ReqId

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
  • 无效frame类型时抛出错误
  • 负载超过最大尺寸时抛出错误
  • 必填字段为null时抛出错误
  • ReqId为负数时抛出错误
  • frame类型为非整数时抛出错误

Edge Cases

边界场景

  • handles empty string payload
  • handles maximum allowed payload size (64KB)
  • handles unicode in JSON payload
  • handles zero-length binary payload
  • 处理空字符串负载
  • 处理最大允许负载尺寸（64KB）
  • 处理JSON负载中的Unicode字符
  • 处理零长度二进制负载

Security

安全

  • rejects frames with potential injection patterns
  • validates frame type bounds (0-255)
  • sanitizes string inputs before encoding
  • 拒绝包含潜在注入模式的frame
  • 验证frame类型范围（0-255）
  • 编码前清理字符串输入

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

E2E验证关卡

bash
undefined
bash
undefined

Verify encoding works end-to-end

端到端验证编码功能

pnpm test -- --grep "Frame Encoding" pnpm test:e2e -- --grep "encode"
undefined
pnpm test -- --grep "Frame Encoding" pnpm test:e2e -- --grep "encode"
undefined

Acceptance Criteria

验收标准

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

Phase 1: Frame Decoding

Phase 1: Frame解码

Description

描述

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

Tests

测试

Happy Path

正常路径

  • decodes valid frame correctly
  • handles streaming decode
  • decodes all frame types
  • 正确解码有效frame
  • 处理流式解码
  • 解码所有frame类型

Bad Path

异常路径

  • throws on truncated frame
  • throws on corrupted header
  • throws on invalid magic bytes
  • throws on unsupported version
  • frame被截断时抛出错误
  • 头部损坏时抛出错误
  • 魔术字节无效时抛出错误
  • 版本不支持时抛出错误

Edge Cases

边界场景

  • handles minimum valid frame
  • handles maximum valid frame
  • handles back-to-back frames in stream
  • 处理最小有效frame
  • 处理最大有效frame
  • 处理流中连续的frame

Security

安全

  • validates frame length before allocation
  • rejects oversized frames (DoS protection)
  • 分配内存前验证frame长度
  • 拒绝超大frame（防止DoS攻击）

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
  • 部分解码不推进流位置
  • 损坏的frame不影响后续frame

E2E Gate

E2E验证关卡

bash
undefined
bash
undefined

Verify full roundtrip

验证完整的编解码往返

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

Acceptance Criteria

验收标准

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

Final E2E Verification

最终端到端验证

bash
undefined
bash
undefined

Full integration test

全系统集成测试

pnpm test pnpm test:e2e
undefined
pnpm test pnpm test:e2e
undefined

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
  • Intent
  • 规格文档

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