npx skills add https://github.com/boshu2/agentops --skill plan快速参考: 将目标分解为可跟踪的、分阶段的问题。输出:
.agents/plans/*.md+ bd 问题。
你必须执行此工作流。不要仅仅描述它。
CLI 依赖项: bd(问题创建)。如果 bd 不可用,则将计划以 markdown 格式写入 .agents/plans/,并包含问题描述,然后使用 TaskList 进行跟踪。无论 bd 是否可用,计划文档始终会被创建。
| 标志 | 默认值 | 描述 |
|---|---|---|
--auto | 关闭 | 跳过人工批准门。由 /rpi --auto 用于完全自主的生命周期。 |
给定 /plan <goal> [--auto]:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
mkdir -p .agents/plans
查找关于此主题的现有研究:
ls -la .agents/research/ 2>/dev/null | head -10
使用 Grep 在 .agents/ 中搜索相关内容。如果存在研究,请在规划前使用 Read 工具阅读它以了解上下文。
在知识飞轮中搜索先前的规划模式:
if command -v ao &>/dev/null; then
ao search "<topic> plan decomposition patterns" 2>/dev/null | head -10
fi
如果 ao 返回相关的学习或模式,请将其纳入计划。如果 ao 不可用或未返回结果,则静默跳过。
在分解之前,当 .agents/findings/registry.jsonl 存在时读取它。这是 v1 中 /plan 的主要预防层面。
使用 docs/contracts/finding-registry.md 中跟踪的合约:
status=active 的活跃发现applicable_when 重叠、语言重叠、字面目标文本重叠和严重性进行排序在问题分解之前,将选定的发现用作硬性规划上下文。记录应用的发现 ID 以及它们如何改变了计划。这些成为书面计划的必需上下文,而不是可选的旁注。
如果研究文件存在,请阅读最新的一个,并在继续之前验证其包含实质性发现:
LATEST_RESEARCH=$(ls -t .agents/research/*.md 2>/dev/null | head -1)
if [ -n "$LATEST_RESEARCH" ]; then
# 验证研究具有实质性内容(不仅仅是 frontmatter)
if grep -qE '^## (Key Findings|Architecture|Executive Summary|Recommendations|Part [0-9])' "$LATEST_RESEARCH"; then
echo "Research validated: $LATEST_RESEARCH"
else
echo "WARNING: Research file exists but lacks standard sections (Key Findings, Architecture, Executive Summary, or Recommendations)."
echo "Consider running /research first for a thorough exploration."
fi
fi
在继续步骤 3 之前,使用 Read 工具阅读已验证的研究文件。不要仅基于文件存在性进行规划——理解研究内容对于准确分解至关重要。
使用 TASK 工具 来派遣一个探索代理。探索提示必须请求符号级别的详细信息:
Tool: Task
Parameters:
subagent_type: "Explore"
description: "Understand codebase for: <goal>"
prompt: |
Explore the codebase to understand what's needed for: <goal>
1. Find relevant files and modules
2. Understand current architecture
3. Identify what needs to change
For EACH file that needs modification, return:
- Exact function/method signatures that need changes
- Struct/type definitions that need new fields
- Key functions to reuse (with file:line references)
- Existing test file locations and naming conventions (e.g., TestFoo_Bar)
- Import paths and package relationships
Return: file inventory, per-file symbol details, reuse points with line numbers, test patterns
在分解为问题之前,运行定量基线审计,使计划基于已验证的数字。这对所有计划都是强制性的——不仅仅是清理/重构。任何做出定量声明(计数、大小、覆盖率)的计划都必须机械地验证它们。
运行 grep/wc/ls 命令来计算您要更改的当前状态:
ls/find/wc -l 计数grep -l/grep -L 计数grep -L 或 find 计算缺失项将验证命令及其结果一起记录下来。 这些成为事前证据和验收标准。
| 差 | 好 |
|---|---|
| "14 missing refs/" | "14 missing refs/ (verified: `ls -d skills/*/references/ |
| "clean up dead code" | "Delete 3,003 LOC across 3 packages (verified: `find src/old -name '*.go' |
| "update stale docs" | "Rewrite 4 specs (verified: `ls docs/specs/*.md |
| "add missing sections" | "Add Examples to 27 skills (verified: `grep -L '## Examples' skills/*/SKILL.md |
grep -rn 'func Test' <test-dir>/ | wc -l 计算任何要添加或修改的过滤器/门/钩子上游的测试夹具数量。更改门而不更新其测试夹具会导致 CI 假阳性。基于数字的客观事实可以防止范围蔓延,并使完成情况可验证。在 ol-571 中,审计发现需要删除 5,752 LOC——没有它,计划就会模糊不清。在 ag-dnu 中,错误的计数(11 对 14,0 对 7)导致了事前失败,而简单的 grep 审计本可以避免这种情况。
在探索代码库之后,为计划中的每个文件生成符号级别的实现细节。这是将可操作的规范与模糊描述区分开来的关键。阅读计划的工人应该确切地知道要写什么,而无需重新发现函数名、参数或代码位置。
从 ## Files to Modify 表开始,列出计划涉及到的每个文件:
## Files to Modify
| File | Change |
|------|--------|
| `src/auth/middleware.go` | Add rate limit check to `AuthMiddleware` |
| `src/config/config.go` | Add `RateLimit` section to `Config` struct |
| `src/auth/middleware_test.go` | **NEW** — rate limit middleware tests |
用 **NEW** 标记新文件。这个表格让实施者在 30 秒内了解完整的影响范围。
对于每个逻辑变更组,提供符号级别的细节:
确切的函数签名 — 命名函数、其参数以及更改内容:
classifyRunStatus 添加 worktreePath string 参数"WorktreeMode string 字段的新 RPIConfig 结构体"要重用的关键函数 — 包含来自探索步骤的 file:line 引用:
rpi_phased.go:1963 处的 readRunHeartbeat()"rpi_phased.go:1924 处现有的 parsePhasedState()"内联代码块 — 用于非显而易见的构造(结构体定义、CLI 标志、配置片段)。在将内联片段包含在问题描述中之前,使用 go build ./... 验证所有内联片段都能编译——工人会逐字复制它们:
type RPIConfig struct {
WorktreeMode string `yaml:"worktree_mode" json:"worktree_mode"`
}
带有标签的新结构体字段 — 确切的字段名和 JSON/YAML 标签
CLI 标志定义 — 确切的标志名称、类型、默认值和帮助文本
对于每个测试文件,列出具有单行描述的特定测试函数:
**`src/auth/middleware_test.go`** — add:
- `TestRateLimitMiddleware_UnderLimit`: Request within limit returns 200
- `TestRateLimitMiddleware_OverLimit`: Request exceeding limit returns 429
- `TestRateLimitMiddleware_ResetAfterWindow`: Counter resets after time window
添加一个 ## Verification 部分,包含可运行的 bash 序列,用于重现场景并确认修复:
## Verification
1. **Unit tests**: `go test ./src/auth/ -run "TestRateLimit" -v`
2. **Build check**: `go build ./...`
3. **Manual simulation**:
```bash
# Start server
go run ./cmd/server/ &
# Hit endpoint 11 times (limit is 10)
for i in $(seq 1 11); do curl -s -o /dev/null -w "%{http_code}\n" localhost:8080/api; done
# Last request should return 429
**为什么这很重要:** 黄金计划模式(文件表 + 符号级规范 + 验证程序)使得能够单次实现一个涉及 8 个文件、5 个区域的变更,且零歧义。类别级规范("修改 classifyRunStatus")迫使实施者重新发现符号,导致分歧和返工。
#### 数据转换映射表(过滤时强制)
当计划声明任何结构体级别的过滤、排除或允许列表逻辑时:
- 创建一个显式的映射表,显示**源字段 → 输出转换**
- 格式:源名称 → 受影响的字段 → 转换(归零、重命名、计算)
来自上下文编排的示例(na-0v2):
| Section Name | Fields Zeroed |
|---|---|
| `HISTORY` | `Sessions` |
| `INTEL` | `Learnings`, `Patterns` |
| `TASK` | `BeadID`, `Predecessor` |
**原因:** 没有显式的映射表,工人会误解数据转换。在 na-0v2 中,部分→字段映射的歧义性直到事前检查才被发现。一个显式的表格可以完全避免这个问题。
### 步骤 4:分解为问题
分析目标并将其分解为离散的、可实施的问题。为每个问题定义:
- **标题:** 清晰的动作动词(例如,"添加认证中间件")
- **描述:** 需要做什么
- **依赖项:** 哪些问题必须先完成(如果有的话)
- **验收标准:** 如何验证已完成
#### 重写的设计概要
对于任何说明"重写"、"重新设计"或"从头创建"的问题:
包含一个**设计概要**(3+ 句),涵盖:
1. **目的** — 此组件在新架构中做什么?
2. **关键工件** — 哪些文件/接口定义了成功?
3. **工作流** — 哪些序列必须工作?
没有设计概要,工人会发明设计决策。在 ol-571 中,一个没有设计概要的规范重写问题产生了偏离预期架构的输出。
#### 问题粒度
- **1-2 个独立文件** → 1 个问题
- **3+ 个独立文件且无代码依赖** → 拆分为子问题(每个文件一个)
- 示例:"重写 4 个规范" → 4 个子问题(4.1, 4.2, 4.3, 4.4)
- 启用 N 个并行工人,而不是 1 个串行工人
- **问题之间的共享文件** → 串行化或分配给同一个工人
#### 可操作化启发式方法
每个问题必须能够被群组工人立即执行,无需进一步研究:
- **文件所有权(`metadata.files`):** 列出问题涉及到的每个文件。工人使用此信息进行冲突检测。
- **验证命令(`metadata.validation`):** 包含可运行的检查(例如,`go test ./...`, `bash -n script.sh`)。工人在报告完成前运行这些命令。
- **同质阶段分组:** 在同一阶段内按工作类型(全部 Go、全部文档、全部 shell)对问题进行分组。混合类型的阶段会导致工具链上下文切换并增加冲突风险。
- **同文件串行化:** 如果两个问题涉及同一个文件,请标记它们进行串行化(移动到后面的阶段)或合并为一个问题。切勿将涉及同一文件的问题分配给并行工人。
#### 一致性检查
对于每个问题的验收标准,至少派生一个**机械可验证的**一致性检查,使用 validation-contract.md 类型。这些检查弥合了规范意图与实现验证之间的差距。
| 验收标准 | 一致性检查 |
|-----|------|
| "文件 X 存在" | `files_exist: ["X"]` |
| "函数 Y 已实现" | `content_check: {file: "src/foo.go", pattern: "func Y"}` |
| "测试通过" | `tests: "go test ./..."` |
| "端点返回 200" | `command: "curl -s -o /dev/null -w '%{http_code}' localhost:8080/api \| grep 200"` |
| "配置具有设置 Z" | `content_check: {file: "config.yaml", pattern: "setting_z:"}` |
**规则:**
- 每个问题必须至少有一个一致性检查
- 检查必须使用 validation-contract.md 类型:`files_exist`, `content_check`, `command`, `tests`, `lint`
- 优先使用 `content_check` 和 `files_exist`(快速、确定性)而不是 `command`(较慢、环境依赖)
- 如果验收标准无法机械验证,则将其标记为未充分指定
- 当向测试枚举的配置文件中添加条目时,搜索硬编码的计数断言:`grep -rn 'len.*!=\|len.*==\|expected.*count' <test-dir>/`
### 步骤 5:计算阶段
按依赖关系对问题进行分组以进行并行执行:
- **阶段 1:** 没有依赖项的问题(可以并行运行)
- **阶段 2:** 仅依赖于阶段 1 的问题
- **阶段 3:** 依赖于阶段 2 的问题
- 继续直到所有问题都已分配
#### 文件级依赖矩阵(强制)
在将问题分配到阶段之前,构建一个文件冲突矩阵。对于每个问题,列出它修改了哪些文件。如果任何文件出现在 2 个或更多同阶段问题中,则:
- **串行化** 它们(将一个移动到后面的阶段),或
- **合并** 它们为一个分配给一个工人的单一问题。
```markdown
## File-Conflict Matrix
| File | Issues |
|------|--------|
| `src/auth.go` | Issue 1, Issue 3 | ← CONFLICT: serialize or merge
| `src/config.go` | Issue 2 |
| `src/auth_test.go` | Issue 1 |
原因: 问题级依赖图会遗漏共享文件冲突。在 context-orchestration-leverage 中,两个轨道都修改了 rpi_phased_handoff.go,并需要计划外的阶段 2a/2b 拆分。文件冲突矩阵本可以在规划期间发现这一点。
计算阶段后,构建一个跨阶段共享文件注册表,列出在不同阶段的问题中出现的每个文件。这些文件是碰撞风险,因为后期阶段的工作树是从可能不包含早期阶段更改的基础 SHA 创建的。
## Cross-Wave Shared Files
| File | Wave 1 Issues | Wave 2+ Issues | Mitigation |
|------|---------------|----------------|------------|
| `src/auth_test.go` | Issue 1 | Issue 5 | Wave 2 worktree must branch from post-Wave-1 SHA |
| `src/config.go` | Issue 2 | Issue 6 | Serial: Issue 6 blocked by Issue 2 |
如果任何文件出现在多个阶段:
bd dep add / addBlockedBy)。## Cross-Wave Shared Files 部分标记该文件,以便 /crank 可以在阶段之间强制执行工作树基础刷新。原因: 在 na-vs9 中,阶段 2 代理从阶段 1 之前的 SHA 开始。一个阶段 2 的测试覆盖率问题覆盖了阶段 1 在 rpi_phased_test.go 中的 .md→.json 修复,因为工作树不包含阶段 1 的提交。跨阶段注册表使这些碰撞在规划期间可见。
对于每个声明的依赖项,验证:
虚假依赖会降低并行性。事前评审员也会标记这些。在 ol-571 中,独立规范重写之间不必要的串行化被事前检查发现。
写入: .agents/plans/YYYY-MM-DD-<goal-slug>.md
---
id: plan-YYYY-MM-DD-<goal-slug>
type: plan
date: YYYY-MM-DD
source: "[[.agents/research/YYYY-MM-DD-<research-slug>]]"
---
# Plan: <Goal>
## Context
<1-2 paragraphs explaining the problem, current state, and why this change is needed. Include `Applied findings: <id, id, ...>` from `.agents/findings/registry.jsonl` when present.>
Applied findings:
- `<finding-id>` — `<how it changed the plan>`
## Files to Modify
| File | Change |
|------|--------|
| `path/to/file.go` | Description of change |
| `path/to/new_file.go` | **NEW** — description |
## Boundaries
**Always:** <non-negotiable requirements — security, backward compat, testing, etc.>
**Ask First:** <decisions needing human input before proceeding — in auto mode, logged only>
**Never:** <explicit out-of-scope items preventing scope creep>
## Baseline Audit
| Metric | Command | Result |
|--------|---------|--------|
| <what was measured> | `<grep/wc/ls command used>` | <result> |
## Implementation
### 1. <Change Group Name>
In `path/to/file.go`:
- **Modify `functionName`**: Add `paramName Type` parameter. If `paramName != ""` and condition, return `"value"`.
- **Add `NewStruct`**:
```go
type NewStruct struct {
FieldName string `json:"field_name,omitempty"`
}
existingHelper() at path/to/file.go:123anotherFunc() at path/to/other.go:456<Same pattern — exact symbols, inline code, reuse references>
path/to/file_test.go — add:
TestFunctionName_ScenarioA: Input X produces output YTestFunctionName_ScenarioB: Edge case Z handled correctlypath/to/new_test.go — NEW :
TestNewFeature_HappyPath: Normal flow succeedsTestNewFeature_ErrorCase: Bad input returns error| Issue | Check Type | Check |
|---|---|---|
| Issue 1 | content_check | {file: "src/auth.go", pattern: "func Authenticate"} |
| Issue 1 | tests | go test ./src/auth/... |
| Issue 2 | files_exist | ["docs/api-v2.md"] |
Unit tests : go test ./path/to/ -run "TestFoo" -v
Full suite : go test ./... -short -timeout 120s
Manual simulation :
# Create test scenario
mkdir -p .test/data
echo '{"key": "value"}' > .test/data/input.json
# Run the tool
./bin/tool --flag value
# Verify expected output
cat .test/data/output.json # Should show "result"
Dependencies: None Acceptance: Description: <what to do — reference Implementation section for symbol-level detail>
Dependencies: Issue 1 Acceptance: Description:
Wave 1 (parallel): Issue 1, Issue 3 Wave 2 (after Wave 1): Issue 2, Issue 4 Wave 3 (after Wave 2): Issue 5
After bulk-merging wave results, audit for scaffold-era names:
handleThing, processItem) to domain-specific namesgrep -rn 'TODO\|FIXME\|HACK\|XXX' <modified-files> for deferred cleanup markersRun /pre-mortem to validate plan
Run /crank for autonomous execution
Or /implement <issue> for single issue
为每个问题使用 TaskCreate 工具:
Tool: TaskCreate Parameters: subject: "" description: | - What to do - Acceptance criteria - Dependencies: [list task IDs that must complete first] activeForm: "<-ing verb form of the task>"
**创建所有任务后,设置依赖关系:**
Tool: TaskUpdate Parameters: taskId: "" addBlockedBy: [""]
**重要:创建持久性问题以进行棘轮跟踪:**
如果 bd CLI 可用,创建 beads 问题以支持跨会话的进度跟踪:
```bash
# 首先创建史诗
bd create --title "<goal>" --type epic --label "planned"
# 创建子问题(注意返回的 ID)
bd create --title "<wave-1-task>" --body "<description>" --parent <epic-id> --label "planned"
# Returns: na-0001
bd create --title "<wave-2-task-depends-on-wave-1>" --body "<description>" --parent <epic-id> --label "planned"
# Returns: na-0002
# 添加阻塞依赖关系以形成阶段
bd dep add na-0001 na-0002
# Now na-0002 is blocked by na-0001 → Wave 2
在问题正文中包含一致性检查:
创建 beads 问题时,将计划中的一致性检查作为围栏式验证块嵌入问题描述中。这将通过 /crank 流入工人验证元数据:
bd create --title "<task>" --body "Description...
\`\`\`validation
{\"files_exist\": [\"src/auth.go\"], \"content_check\": {\"file\": \"src/auth.go\", \"pattern\": \"func Authenticate\"}}
\`\`\`
" --parent <epic-id>
在史诗描述中包含跨领域约束:
计划中的"始终"边界应作为 ## Cross-Cutting Constraints 部分添加到史诗的描述中。/crank 从史诗(而非每个问题)读取这些内容,并将其注入到每个工人任务的验证元数据中。
阶段由blocks依赖关系形成:
bd ready 中)bd ready 返回当前阶段 — 所有可以并行运行的无阻塞问题。
没有 bd 问题,棘轮验证器无法跟踪门进度。这对于 /crank 自主执行和 /post-mortem 验证是必需的。
创建所有 beads 问题后,验证每个问题正文是否包含围栏式验证块。缺少验证块会破坏计划到 crank 的流水线——/crank 无法从缺少验证块的问题中提取一致性检查。
if command -v bd &>/dev/null && [[ -n "$EPIC_ID" ]]; then
MISSING_VALIDATION=()
for ISSUE_ID in $ALL_CREATED_ISSUES; do
if ! bd show "$ISSUE_ID" 2>/dev/null | grep -q '```validation'; then
MISSING_VALIDATION+=("$ISSUE_ID")
fi
done
if [[ ${#MISSING_VALIDATION[@]} -gt 0 ]]; then
echo "WARNING: ${#MISSING_VALIDATION[@]} issue(s) missing validation blocks: ${MISSING_VALIDATION[*]}"
echo " /crank will fall back to default files_exist checks for these issues."
echo " Consider adding ```validation``` blocks with conformance checks."
else
echo "All ${#ALL_CREATED_ISSUES[@]} issues have validation blocks."
fi
fi
这是一个警告门,而不是阻塞器——计划可以在没有验证块的情况下继续进行,但 crank 执行将使用较弱的回退检查。
如果设置了--auto标志,则跳过此步骤。 在自动模式下,直接进入步骤 9。
使用 AskUserQuestion 工具:
Tool: AskUserQuestion
Parameters:
questions:
- question: "Plan complete with N tasks in M waves. Approve to proceed?"
header: "Gate 2"
options:
- label: "Approve"
description: "Proceed to /pre-mortem or /crank"
- label: "Revise"
description: "Modify the plan before proceeding"
- label: "Back to Research"
description: "Need more research before planning"
multiSelect: false
在报告完成之前等待批准。
ao ratchet record plan 2>/dev/null || true
告诉用户:
/pre-mortem 进行故障模拟,然后 /crank 执行.agents/plans/用户说: /plan "add user authentication"
会发生什么:
.agents/research/2026-02-13-authentication-system.md 阅读最近的研究ag-5k2,包含 2 个阶段中的 5 个子问题.agents/plans/2026-02-13-add-user-authentication.md结果: 具有依赖关系图、一致性检查和并行执行阶段结构的史诗。
用户说: /plan --auto "refactor payment module"
会发生什么:
结果: 完全自主的计划创建,包含 3 个阶段、8 个问题,准备就绪,可供 /crank 执行。
用户说: /plan "remove dead code"
会发生什么:
结果: 具有可衡量完成标准(例如,"从 pkg/legacy 删除 1,500 LOC")的范围明确的清理计划。
用户说: /plan "add stale run detection to RPI status" (external operator loop surface)
会发生什么:
rpi_status.go:850 找到 classifyRunStatus,在 rpi_phased.go:100 找到 phasedStateTestClassifyRunStatus_StaleWorktree、TestDetermineRunLiveness_MissingWorktree 及其描述结果: 实施者可以单次执行计划,而无需重新发现任何符号名称,将实施时间减少约 50%,并消除规范分歧返工。
| 问题 | 原因 | 解决方案 |
|---|---|---|
| bd create 失败 | 存储库中未初始化 Beads | 首先运行 bd init --prefix <prefix> |
| 依赖关系未创建 | 问题创建时没有显式的 bd dep add 调用 | 验证计划输出包含依赖命令。重新运行以重新生成 |
| 计划太大 | 研究范围太广,导致 >20 个问题 | 缩小目标或拆分为多个史诗 |
| 阶段结构不正确 | 声明了虚假依赖关系(逻辑顺序,而非文件冲突) | 审查依赖必要性:被阻塞的问题是否修改了阻塞者的文件? |
| 缺少一致性检查 | 验收标准无法机械验证 | 根据 validation-contract.md 添加 files_exist、content_check、tests 或 command 检查 |
| 史诗没有子项 | 计划已创建但 bd 命令静默失败 | 检查 bd list --type epic 输出;在 bd CLI 可用的情况下重新运行计划 |
每周安装数
227
仓库
GitHub 星标数
197
首次出现
2026年2月2日
安全审计
安装于
opencode223
codex221
gemini-cli221
github-copilot219
amp213
kimi-cli213
Quick Ref: Decompose goal into trackable issues with waves. Output:
.agents/plans/*.md+ bd issues.
YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.
CLI dependencies: bd (issue creation). If bd is unavailable, write the plan to .agents/plans/ as markdown with issue descriptions, and use TaskList for tracking instead. The plan document is always created regardless of bd availability.
| Flag | Default | Description |
|---|---|---|
--auto | off | Skip human approval gate. Used by /rpi --auto for fully autonomous lifecycle. |
Given /plan <goal> [--auto]:
mkdir -p .agents/plans
Look for existing research on this topic:
ls -la .agents/research/ 2>/dev/null | head -10
Use Grep to search .agents/ for related content. If research exists, read it with the Read tool to understand the context before planning.
Search knowledge flywheel for prior planning patterns:
if command -v ao &>/dev/null; then
ao search "<topic> plan decomposition patterns" 2>/dev/null | head -10
fi
If ao returns relevant learnings or patterns, incorporate them into the plan. Skip silently if ao is unavailable or returns no results.
Before decomposition, read .agents/findings/registry.jsonl when it exists. This is the primary prevention surface for /plan in v1.
Use the tracked contract in docs/contracts/finding-registry.md:
status=activeapplicable_when overlap, language overlap, literal goal-text overlap, and severityUse the selected findings as hard planning context before issue decomposition. Record the applied finding IDs and how they changed the plan. These become required context for the written plan, not optional side notes.
If research files exist, read the most recent one and verify it contains substantive findings before proceeding:
LATEST_RESEARCH=$(ls -t .agents/research/*.md 2>/dev/null | head -1)
if [ -n "$LATEST_RESEARCH" ]; then
# Verify research has substantive content (not just frontmatter)
if grep -qE '^## (Key Findings|Architecture|Executive Summary|Recommendations|Part [0-9])' "$LATEST_RESEARCH"; then
echo "Research validated: $LATEST_RESEARCH"
else
echo "WARNING: Research file exists but lacks standard sections (Key Findings, Architecture, Executive Summary, or Recommendations)."
echo "Consider running /research first for a thorough exploration."
fi
fi
Read the validated research file with the Read tool before proceeding to Step 3. Do not plan based solely on file existence — understanding the research content is essential for accurate decomposition.
USE THE TASK TOOL to dispatch an Explore agent. The explore prompt MUST request symbol-level detail:
Tool: Task
Parameters:
subagent_type: "Explore"
description: "Understand codebase for: <goal>"
prompt: |
Explore the codebase to understand what's needed for: <goal>
1. Find relevant files and modules
2. Understand current architecture
3. Identify what needs to change
For EACH file that needs modification, return:
- Exact function/method signatures that need changes
- Struct/type definitions that need new fields
- Key functions to reuse (with file:line references)
- Existing test file locations and naming conventions (e.g., TestFoo_Bar)
- Import paths and package relationships
Return: file inventory, per-file symbol details, reuse points with line numbers, test patterns
Before decomposing into issues , run a quantitative baseline audit to ground the plan in verified numbers. This is mandatory for ALL plans — not just cleanup/refactor. Any plan that makes quantitative claims (counts, sizes, coverage) must verify them mechanically.
Run grep/wc/ls commands to count the current state of what you're changing:
ls/find/wc -lgrep -l/grep -Lgrep -L or findRecord the verification commands alongside their results. These become pre-mortem evidence and acceptance criteria.
| Bad | Good |
|---|---|
| "14 missing refs/" | "14 missing refs/ (verified: `ls -d skills/*/references/ |
| "clean up dead code" | "Delete 3,003 LOC across 3 packages (verified: `find src/old -name '*.go' |
| "update stale docs" | "Rewrite 4 specs (verified: `ls docs/specs/*.md |
| "add missing sections" | "Add Examples to 27 skills (verified: `grep -L '## Examples' skills/*/SKILL.md |
grep -rn 'func Test' <test-dir>/ | wc -l. Changing a gate without updating its test fixtures causes false-green CI.Ground truth with numbers prevents scope creep and makes completion verifiable. In ol-571, the audit found 5,752 LOC to remove — without it, the plan would have been vague. In ag-dnu, wrong counts (11 vs 14, 0 vs 7) caused a pre-mortem FAIL that a simple grep audit would have prevented.
After exploring the codebase , generate symbol-level implementation detail for EVERY file in the plan. This is what separates actionable specs from vague descriptions. A worker reading the plan should know exactly what to write without rediscovering function names, parameters, or code locations.
Start with a ## Files to Modify table listing EVERY file the plan touches:
## Files to Modify
| File | Change |
|------|--------|
| `src/auth/middleware.go` | Add rate limit check to `AuthMiddleware` |
| `src/config/config.go` | Add `RateLimit` section to `Config` struct |
| `src/auth/middleware_test.go` | **NEW** — rate limit middleware tests |
Mark new files with **NEW**. This table gives the implementer the full blast radius in 30 seconds.
For each logical change group, provide symbol-level detail:
Exact function signatures — name the function, its parameters, and what changes:
worktreePath string parameter to classifyRunStatus"RPIConfig struct with WorktreeMode string field"Key functions to reuse — with file:line references from the explore step:
readRunHeartbeat() at rpi_phased.go:1963"parsePhasedState() at "For each test file, list specific test functions with one-line descriptions:
**`src/auth/middleware_test.go`** — add:
- `TestRateLimitMiddleware_UnderLimit`: Request within limit returns 200
- `TestRateLimitMiddleware_OverLimit`: Request exceeding limit returns 429
- `TestRateLimitMiddleware_ResetAfterWindow`: Counter resets after time window
Add a ## Verification section with runnable bash sequences that reproduce the scenario and confirm the fix:
## Verification
1. **Unit tests**: `go test ./src/auth/ -run "TestRateLimit" -v`
2. **Build check**: `go build ./...`
3. **Manual simulation**:
```bash
# Start server
go run ./cmd/server/ &
# Hit endpoint 11 times (limit is 10)
for i in $(seq 1 11); do curl -s -o /dev/null -w "%{http_code}\n" localhost:8080/api; done
# Last request should return 429
**Why this matters:** The golden plan pattern (file tables + symbol-level specs + verification procedures) enabled single-pass implementation of an 8-file, 5-area change with zero ambiguity. Category-level specs ("modify classifyRunStatus") force implementers to rediscover symbols, causing divergence and rework.
#### Data Transformation Mapping Tables (Mandatory for Filtering)
When a plan declares any struct-level filtering, exclusion, or allowlist logic:
- Create an explicit mapping table showing **source field → output transformation**
- Format: source name → fields affected → transformation (zeroed, renamed, computed)
Example from context orchestration (na-0v2):
| Section Name | Fields Zeroed |
|---|---|
| `HISTORY` | `Sessions` |
| `INTEL` | `Learnings`, `Patterns` |
| `TASK` | `BeadID`, `Predecessor` |
**Why:** Without explicit mapping tables, workers misinterpret data transformations. In na-0v2, section→field mapping ambiguity was caught only in pre-mortem. An explicit table prevents the concern entirely.
### Step 4: Decompose into Issues
Analyze the goal and break it into discrete, implementable issues. For each issue define:
- **Title**: Clear action verb (e.g., "Add authentication middleware")
- **Description**: What needs to be done
- **Dependencies**: Which issues must complete first (if any)
- **Acceptance criteria**: How to verify it's done
#### Design Briefs for Rewrites
For any issue that says "rewrite", "redesign", or "create from scratch":
Include a **design brief** (3+ sentences) covering:
1. **Purpose** — what does this component do in the new architecture?
2. **Key artifacts** — what files/interfaces define success?
3. **Workflows** — what sequences must work?
Without a design brief, workers invent design decisions. In ol-571, a spec rewrite issue without a design brief produced output that diverged from the intended architecture.
#### Issue Granularity
- **1-2 independent files** → 1 issue
- **3+ independent files with no code deps** → split into sub-issues (one per file)
- Example: "Rewrite 4 specs" → 4 sub-issues (4.1, 4.2, 4.3, 4.4)
- Enables N parallel workers instead of 1 serial worker
- **Shared files between issues** → serialize or assign to same worker
#### Operationalization Heuristics
Each issue must be immediately executable by a swarm worker without further research:
- **File ownership (`metadata.files`):** List every file the issue touches. Workers use this for conflict detection.
- **Validation commands (`metadata.validation`):** Include runnable checks (e.g., `go test ./...`, `bash -n script.sh`). Workers run these before reporting done.
- **Homogeneous wave grouping:** Group issues by work type (all Go, all docs, all shell) within the same wave. Mixed-type waves cause toolchain context-switching and increase conflict risk.
- **Same-file serialization:** If two issues touch the same file, flag them for serialization (different waves) or merge into one issue. Never assign same-file issues to parallel workers.
#### Conformance Checks
For each issue's acceptance criteria, derive at least one **mechanically verifiable** conformance check using validation-contract.md types. These checks bridge the gap between spec intent and implementation verification.
| Acceptance Criteria | Conformance Check |
|-----|------|
| "File X exists" | `files_exist: ["X"]` |
| "Function Y is implemented" | `content_check: {file: "src/foo.go", pattern: "func Y"}` |
| "Tests pass" | `tests: "go test ./..."` |
| "Endpoint returns 200" | `command: "curl -s -o /dev/null -w '%{http_code}' localhost:8080/api \| grep 200"` |
| "Config has setting Z" | `content_check: {file: "config.yaml", pattern: "setting_z:"}` |
**Rules:**
- Every issue MUST have at least one conformance check
- Checks MUST use validation-contract.md types: `files_exist`, `content_check`, `command`, `tests`, `lint`
- Prefer `content_check` and `files_exist` (fast, deterministic) over `command` (slower, environment-dependent)
- If acceptance criteria cannot be mechanically verified, flag it as underspecified
- When adding entries to config files enumerated by tests, search for hardcoded count assertions: `grep -rn 'len.*!=\|len.*==\|expected.*count' <test-dir>/`
### Step 5: Compute Waves
Group issues by dependencies for parallel execution:
- **Wave 1**: Issues with no dependencies (can run in parallel)
- **Wave 2**: Issues depending only on Wave 1
- **Wave 3**: Issues depending on Wave 2
- Continue until all issues assigned
#### File-Level Dependency Matrix (Mandatory)
Before assigning issues to waves, build a file-conflict matrix. For EACH issue, list which files it modifies. If any file appears in 2+ same-wave issues, either:
- **Serialize** them (move one to a later wave), or
- **Merge** them into a single issue assigned to one worker.
```markdown
## File-Conflict Matrix
| File | Issues |
|------|--------|
| `src/auth.go` | Issue 1, Issue 3 | ← CONFLICT: serialize or merge
| `src/config.go` | Issue 2 |
| `src/auth_test.go` | Issue 1 |
Why: Issue-level dependency graphs miss shared-file conflicts. In context-orchestration-leverage, two tracks both modified rpi_phased_handoff.go and required an unplanned Wave 2a/2b split. A file-conflict matrix would have caught this during planning.
After computing waves, build a cross-wave file registry listing every file that appears in issues across different waves. These files are collision risks because later-wave worktrees are created from a base SHA that may not include earlier-wave changes.
## Cross-Wave Shared Files
| File | Wave 1 Issues | Wave 2+ Issues | Mitigation |
|------|---------------|----------------|------------|
| `src/auth_test.go` | Issue 1 | Issue 5 | Wave 2 worktree must branch from post-Wave-1 SHA |
| `src/config.go` | Issue 2 | Issue 6 | Serial: Issue 6 blocked by Issue 2 |
If any file appears in multiple waves:
bd dep add / addBlockedBy is set).## Cross-Wave Shared Files section so /crank can enforce worktree base refresh between waves.Why: In na-vs9, Wave 2 agents started from pre-Wave-1 SHA. A Wave 2 test coverage issue overwrote Wave 1's .md→.json fix in rpi_phased_test.go because the worktree didn't include Wave 1's commit. The cross-wave registry makes these collisions visible during planning.
For EACH declared dependency, verify:
False dependencies reduce parallelism. Pre-mortem judges will also flag these. In ol-571, unnecessary serialization between independent spec rewrites was caught by pre-mortem.
Write to: .agents/plans/YYYY-MM-DD-<goal-slug>.md
---
id: plan-YYYY-MM-DD-<goal-slug>
type: plan
date: YYYY-MM-DD
source: "[[.agents/research/YYYY-MM-DD-<research-slug>]]"
---
# Plan: <Goal>
## Context
<1-2 paragraphs explaining the problem, current state, and why this change is needed. Include `Applied findings: <id, id, ...>` from `.agents/findings/registry.jsonl` when present.>
Applied findings:
- `<finding-id>` — `<how it changed the plan>`
## Files to Modify
| File | Change |
|------|--------|
| `path/to/file.go` | Description of change |
| `path/to/new_file.go` | **NEW** — description |
## Boundaries
**Always:** <non-negotiable requirements — security, backward compat, testing, etc.>
**Ask First:** <decisions needing human input before proceeding — in auto mode, logged only>
**Never:** <explicit out-of-scope items preventing scope creep>
## Baseline Audit
| Metric | Command | Result |
|--------|---------|--------|
| <what was measured> | `<grep/wc/ls command used>` | <result> |
## Implementation
### 1. <Change Group Name>
In `path/to/file.go`:
- **Modify `functionName`**: Add `paramName Type` parameter. If `paramName != ""` and condition, return `"value"`.
- **Add `NewStruct`**:
```go
type NewStruct struct {
FieldName string `json:"field_name,omitempty"`
}
existingHelper() at path/to/file.go:123anotherFunc() at path/to/other.go:456<Same pattern — exact symbols, inline code, reuse references>
path/to/file_test.go — add:
TestFunctionName_ScenarioA: Input X produces output YTestFunctionName_ScenarioB: Edge case Z handled correctlypath/to/new_test.go — NEW :
TestNewFeature_HappyPath: Normal flow succeedsTestNewFeature_ErrorCase: Bad input returns error| Issue | Check Type | Check |
|---|---|---|
| Issue 1 | content_check | {file: "src/auth.go", pattern: "func Authenticate"} |
| Issue 1 | tests | go test ./src/auth/... |
| Issue 2 | files_exist | ["docs/api-v2.md"] |
Unit tests : go test ./path/to/ -run "TestFoo" -v
Full suite : go test ./... -short -timeout 120s
Manual simulation :
# Create test scenario
mkdir -p .test/data
echo '{"key": "value"}' > .test/data/input.json
# Run the tool
./bin/tool --flag value
# Verify expected output
cat .test/data/output.json # Should show "result"
Dependencies: None Acceptance: Description: <what to do — reference Implementation section for symbol-level detail>
Dependencies: Issue 1 Acceptance: Description:
Wave 1 (parallel): Issue 1, Issue 3 Wave 2 (after Wave 1): Issue 2, Issue 4 Wave 3 (after Wave 2): Issue 5
After bulk-merging wave results, audit for scaffold-era names:
handleThing, processItem) to domain-specific namesgrep -rn 'TODO\|FIXME\|HACK\|XXX' <modified-files> for deferred cleanup markersRun /pre-mortem to validate plan
Run /crank for autonomous execution
Or /implement <issue> for single issue
Use TaskCreate tool for each issue:
Tool: TaskCreate Parameters: subject: "" description: | - What to do - Acceptance criteria - Dependencies: [list task IDs that must complete first] activeForm: "<-ing verb form of the task>"
**After creating all tasks, set up dependencies:**
Tool: TaskUpdate Parameters: taskId: "" addBlockedBy: [""]
**IMPORTANT: Create persistent issues for ratchet tracking:**
If bd CLI available, create beads issues to enable progress tracking across sessions:
```bash
# Create epic first
bd create --title "<goal>" --type epic --label "planned"
# Create child issues (note the IDs returned)
bd create --title "<wave-1-task>" --body "<description>" --parent <epic-id> --label "planned"
# Returns: na-0001
bd create --title "<wave-2-task-depends-on-wave-1>" --body "<description>" --parent <epic-id> --label "planned"
# Returns: na-0002
# Add blocking dependencies to form waves
bd dep add na-0001 na-0002
# Now na-0002 is blocked by na-0001 → Wave 2
Include conformance checks in issue bodies:
When creating beads issues, embed the conformance checks from the plan as a fenced validation block in the issue description. This flows to worker validation metadata via /crank:
bd create --title "<task>" --body "Description...
\`\`\`validation
{\"files_exist\": [\"src/auth.go\"], \"content_check\": {\"file\": \"src/auth.go\", \"pattern\": \"func Authenticate\"}}
\`\`\`
" --parent <epic-id>
Include cross-cutting constraints in epic description:
"Always" boundaries from the plan should be added to the epic's description as a ## Cross-Cutting Constraints section. /crank reads these from the epic (not per-issue) and injects them into every worker task's validation metadata.
Waves are formed byblocks dependencies:
bd ready immediately)bd ready returns the current wave - all unblocked issues that can run in parallel.
Without bd issues, the ratchet validator cannot track gate progress. This is required for /crank autonomous execution and /post-mortem validation.
After creating all beads issues, verify that every issue body contains a fenced validation block. Missing validation blocks break the plan-to-crank pipeline — /crank cannot extract conformance checks from issues that lack them.
if command -v bd &>/dev/null && [[ -n "$EPIC_ID" ]]; then
MISSING_VALIDATION=()
for ISSUE_ID in $ALL_CREATED_ISSUES; do
if ! bd show "$ISSUE_ID" 2>/dev/null | grep -q '```validation'; then
MISSING_VALIDATION+=("$ISSUE_ID")
fi
done
if [[ ${#MISSING_VALIDATION[@]} -gt 0 ]]; then
echo "WARNING: ${#MISSING_VALIDATION[@]} issue(s) missing validation blocks: ${MISSING_VALIDATION[*]}"
echo " /crank will fall back to default files_exist checks for these issues."
echo " Consider adding ```validation``` blocks with conformance checks."
else
echo "All ${#ALL_CREATED_ISSUES[@]} issues have validation blocks."
fi
fi
This is a warning gate, not a blocker — plans can proceed without validation blocks, but crank execution will use weaker fallback checks.
Skip this step if--auto flag is set. In auto mode, proceed directly to Step 9.
USE AskUserQuestion tool:
Tool: AskUserQuestion
Parameters:
questions:
- question: "Plan complete with N tasks in M waves. Approve to proceed?"
header: "Gate 2"
options:
- label: "Approve"
description: "Proceed to /pre-mortem or /crank"
- label: "Revise"
description: "Modify the plan before proceeding"
- label: "Back to Research"
description: "Need more research before planning"
multiSelect: false
Wait for approval before reporting completion.
ao ratchet record plan 2>/dev/null || true
Tell the user:
/pre-mortem for failure simulation, then /crank for execution.agents/plans/User says: /plan "add user authentication"
What happens:
.agents/research/2026-02-13-authentication-system.mdag-5k2 with 5 child issues in 2 waves.agents/plans/2026-02-13-add-user-authentication.mdResult: Epic with dependency graph, conformance checks, and wave structure for parallel execution.
User says: /plan --auto "refactor payment module"
What happens:
Result: Fully autonomous plan creation with 3 waves, 8 issues, ready for /crank.
User says: /plan "remove dead code"
What happens:
Result: Scoped cleanup plan with measurable completion criteria (e.g., "Delete 1,500 LOC from pkg/legacy").
User says: /plan "add stale run detection to RPI status" (external operator loop surface)
What happens:
classifyRunStatus at rpi_status.go:850, phasedState at rpi_phased.go:100TestClassifyRunStatus_StaleWorktree, TestDetermineRunLiveness_MissingWorktree with descriptionsResult: Implementer can execute the plan in a single pass without rediscovering any symbol names, reducing implementation time by ~50% and eliminating spec-divergence rework.
| Problem | Cause | Solution |
|---|---|---|
| bd create fails | Beads not initialized in repo | Run bd init --prefix <prefix> first |
| Dependencies not created | Issues created without explicit bd dep add calls | Verify plan output includes dependency commands. Re-run to regenerate |
| Plan too large | Research scope was too broad, resulting in >20 issues | Narrow the goal or split into multiple epics |
| Wave structure incorrect | False dependencies declared (logical ordering, not file conflicts) | Review dependency necessity: does blocked issue modify blocker's files? |
| Conformance checks missing | Acceptance criteria not mechanically verifiable | Add files_exist, content_check, , or checks per validation-contract.md |
Weekly Installs
227
Repository
GitHub Stars
197
First Seen
Feb 2, 2026
Security Audits
Gen Agent Trust HubPassSocketFailSnykPass
Installed on
opencode223
codex221
gemini-cli221
github-copilot219
amp213
kimi-cli213
AI Elements:基于shadcn/ui的AI原生应用组件库,快速构建对话界面
56,200 周安装
竞争对手研究指南:SEO、内容、反向链接与定价分析工具
231 周安装
Azure 工作负载自动升级评估工具 - 支持 Functions、App Service 计划与 SKU 迁移
231 周安装
Kaizen持续改进方法论:软件开发中的渐进式优化与防错设计实践指南
231 周安装
软件UI/UX设计指南:以用户为中心的设计原则、WCAG可访问性与平台规范
231 周安装
Apify 网络爬虫和自动化平台 - 无需编码抓取亚马逊、谷歌、领英等网站数据
231 周安装
llama.cpp 中文指南:纯 C/C++ LLM 推理,CPU/非 NVIDIA 硬件优化部署
231 周安装
rpi_phased.go:1924Inline code blocks — for non-obvious constructs (struct definitions, CLI flags, config snippets). Verify all inline snippets compile with go build ./... before including them in issue descriptions — workers copy them verbatim:
type RPIConfig struct {
WorktreeMode string `yaml:"worktree_mode" json:"worktree_mode"`
}
New struct fields with tags — exact field names and JSON/YAML tags
CLI flag definitions — exact flag names, types, defaults, and help text
testscommand| Epic has no children | Plan created but bd commands failed silently | Check bd list --type epic output; re-run plan with bd CLI available |