Agent skill

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.

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

SKILL.md

Intent Changes

设计文档的结构化变更提案与协作 Review 工具。

核心概念

Change Proposal

每个变更是一个独立提案：

字段 说明
ID 唯一标识 (C001, C002...)
Type ADD / MODIFY / REPLACE / DELETE
Status PENDING / ACCEPTED / REJECTED
Target 变更位置
Before/After 变更内容
Decision 决策记录 (reviewer, timestamp, comment)

状态流

PENDING ──accept──> ACCEPTED ──finalize──> Applied
    │
    └──reject──> REJECTED

命令

命令 说明
/intent-changes start <file> 启动或恢复 review
/intent-changes propose 提出变更建议
/intent-changes accept <id> 接受变更
/intent-changes reject <id> 拒绝变更
/intent-changes status 查看当前状态
/intent-changes finalize 交互式 apply

工作流程

/intent-changes start <file>
        ↓
┌───────────────────┐
│  检查 .reviews/   │
│  有则恢复         │
│  无则创建         │
└─────────┬─────────┘
          ↓
/intent-changes propose
        ↓
┌───────────────────────────────────────┐
│  读取源文档                            │
│  与用户讨论变更内容                     │
│  生成 Change Proposal (C001, C002...)  │
│  写入 .reviews/{name}.review.md        │
└─────────┬─────────────────────────────┘
          ↓
/intent-changes accept/reject
        ↓
┌───────────────────┐
│  更新 status      │
│  记录 reviewer    │
│  记录 timestamp   │
└─────────┬─────────┘
          ↓
/intent-changes finalize
        ↓
┌───────────────────────────────────────┐
│  逐个显示 ACCEPTED 变更               │
│  交互确认: Apply? [Y/n/view]          │
│  Apply 到源文档                        │
│  生成变更摘要                          │
└───────────────────────────────────────┘

执行步骤

命令: start

输入: 文件路径

步骤:

  1. 验证源文件存在
  2. 确定 review 文件路径: .reviews/{basename}.review.md
  3. 如果 review 文件存在:
    • 读取并解析
    • 显示当前状态概览
  4. 如果不存在:
    • 创建 .reviews/ 目录（如不存在）
    • 创建 review 文件，写入 frontmatter
  5. 设置当前 session 的 source 和 review 路径

输出:

Review session started.

Source: intent/specs/kind-system-spec.md
Review: .reviews/kind-system-spec.review.md

Status: 3 PENDING, 2 ACCEPTED, 1 REJECTED

Commands:
  /intent-changes propose  - 提出新变更
  /intent-changes status   - 查看详情
  /intent-changes finalize - 应用变更

命令: propose

前置条件: 已执行 start

步骤:

  1. 读取源文档内容
  2. 读取当前 review 文件，获取已有提案
  3. 计算下一个 ID (如已有 C001-C005，下一个是 C006)
  4. 与用户讨论：
    • 展示源文档结构
    • 使用 AskUserQuestion 询问变更类型和位置
    • 收集变更内容
  5. 生成 Change Proposal 块
  6. 追加到 review 文件

交互流程:

使用 AskUserQuestion:
- question: "你想对哪个部分提出变更？"
- header: "变更位置"
- options:
  - "## Kind 定义" - 第一个 section
  - "## Actions" - 第二个 section
  - "## 示例" - 第三个 section
  - "其他位置" - 手动指定

使用 AskUserQuestion:
- question: "变更类型是什么？"
- header: "变更类型"
- options:
  - "ADD" - 新增内容
  - "MODIFY" - 修改现有内容
  - "REPLACE" - 替换整个 section
  - "DELETE" - 删除内容

然后收集具体内容，生成提案。

命令: accept / reject

输入: 提案 ID，可选 comment/reason

语法:

/intent-changes accept C001
/intent-changes accept C001 --comment "LGTM"
/intent-changes reject C002 --reason "不同意这个改法"

步骤:

  1. 读取 review 文件
  2. 找到对应 ID 的提案
  3. 验证当前状态是 PENDING
  4. 更新状态为 ACCEPTED 或 REJECTED
  5. 添加 Decision 记录:
    • reviewer: 从 git config user.name 或 $USER 获取
    • timestamp: 当前日期
    • comment: 用户提供的评论
  6. 写回 review 文件

Decision 格式:

markdown
**Decision:**
- ✓ @robmao (2026-01-21): "LGTM"

或拒绝时:

markdown
**Decision:**
- ✗ @robmao (2026-01-21): "不同意这个改法"

命令: status

输出详情:

Review: kind-system-spec.md
Source: intent/specs/kind-system-spec.md
Reviewers: @robmao, @claude

─────────────────────────────────

PENDING (2):
  C002 [MODIFY] 修改 Kind 定义的措辞
  C004 [ADD] 新增性能章节

ACCEPTED (3):
  C001 [ADD] 新增 Action 分类说明
       ✓ @robmao (2026-01-21)
  C003 [MODIFY] 调整示例代码
       ✓ @claude (2026-01-21)
  C005 [DELETE] 删除过时章节
       ✓ @robmao (2026-01-21)

REJECTED (1):
  C006 [REPLACE] 重写整个文档
       ✗ @robmao (2026-01-21): "改动太大"

─────────────────────────────────

Next: /intent-changes finalize (3 changes ready)

命令: finalize

前置条件: 至少有一个 ACCEPTED 的提案

步骤:

  1. 读取 review 文件，筛选 ACCEPTED 提案
  2. 按 Target 位置排序（从文档末尾往前，避免位置偏移）
  3. 对每个提案交互确认:
[1/3] C001 [ADD]: 新增 Action 分类说明

Target: After "## Actions"

Content to add:
┌────────────────────────────────────────┐
│ Actions 分为三类：                      │
│ - Inline: 同步执行，决定 commit 成功与否 │
│ - Deferred: 异步执行，失败不影响 commit  │
│ - Observational: 只读，可以慢           │
└────────────────────────────────────────┘

Apply this change? [Y/n/view/quit]

用户选项:

  • Y (默认): Apply 并继续
  • n: Skip 此变更（保持 ACCEPTED 状态但不 apply）
  • view: 显示完整的 before/after diff
  • quit: 中止 finalize
  1. Apply 变更到源文档
  2. 更新 review 文件:
    • 已 apply 的标记为 [APPLIED]
    • 更新 frontmatter status 为 finalized（如果全部处理完）
  3. 输出摘要

Apply 摘要:

Finalize complete.

Applied: 2
  C001 - 新增 Action 分类说明
  C003 - 调整示例代码

Skipped: 1
  C005 - 删除过时章节 (user chose to skip)

Source updated: intent/specs/kind-system-spec.md
Review archived: .reviews/kind-system-spec.review.md

Review 文件格式

Frontmatter

yaml
---
source: intent/specs/kind-system-spec.md
created: 2026-01-21
reviewers:
  - robmao
  - claude
status: active
---

status 值:

  • active: 进行中
  • finalized: 已完成 apply
  • abandoned: 已放弃

Change Proposal 块

markdown
---

## C001 [ADD] [PENDING]

> 简短描述

**Target:** After "## Actions"

**After:**
```markdown
新增的内容...

C002 [MODIFY] [ACCEPTED]

简短描述

Target: Section "## Kind 定义"

Before:

markdown
原内容...

After:

markdown
新内容...

Reason: 变更理由

Decision:

  • ✓ @robmao (2026-01-21): "LGTM"

## 获取 Reviewer 名称

按优先级:
1. 命令参数 `--reviewer`
2. `git config user.name`
3. 环境变量 `$USER`

```bash
# 获取方式
git config user.name || echo $USER

边界

做什么

  • ✓ 结构化管理变更提案
  • ✓ 追踪决策过程
  • ✓ 支持多 reviewer 署名
  • ✓ 交互式 apply

不做什么

  • ✗ 格式校验 → intent-validate
  • ✗ Section 审批 → intent-review
  • ✗ 设计质量判断 → intent-critique
  • ✗ 实现一致性 → intent-sync

与其他工具配合

intent-interview → 创建 Intent
        ↓
intent-critique → 质疑设计
        ↓
/intent-changes → 管理变更提案  ← 本 Skill
        ↓
intent-review → 锁定 sections
        ↓
intent-plan → 开始实现

示例

独立 Review

bash
# 开始
/intent-changes start intent/specs/tools-spec.md

# 提出建议
/intent-changes propose

# 决策
/intent-changes accept C001
/intent-changes reject C002 --reason "不需要"

# 应用
/intent-changes finalize

协作 Review

bash
# A 启动并提建议
/intent-changes start spec.md
/intent-changes propose  # C001-C003

# B 来 review
/intent-changes accept C001 --comment "Good"
/intent-changes reject C002 --reason "换个方式"

# A 提新方案
/intent-changes propose  # C004 替代 C002

# B 接受
/intent-changes accept C004

# 最终 apply
/intent-changes finalize

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-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
ArcBlock/idd

intent-sync

After implementation is complete and tests pass, sync confirmed details back to Intent. Captures finalized interfaces, data structures, naming conventions, and architecture decisions. Use after development is done and user confirms the implementation.

11 4
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results