name: 工作流管理描述: | 管理基于规范驱动的开发工作流。当用户运行 /orbit、请求“定义功能”、“创建计划”、“实施”或需要工作流指导时使用此技能。它从工件中检测当前阶段并执行适当的操作。工具:

读取
写入
编辑
全局搜索
文本搜索
Bash
任务
询问用户问题

Orbit 工作流

用于规范驱动开发的单一技能。工件是唯一事实来源。

初始化

<上下文加载> 在任何工作流操作之前，使用单个 Bash 调用加载完整上下文：

node plugins/spec/skills/managing-workflow/scripts/context-loader.js

返回的 JSON 包含：

suggestion：建议的下一步操作
current：活动功能状态和工件
features.active：所有具有 frontmatter 状态的功能
features.in_progress：需要关注的功能
architecture_files：可用的架构文档

使用此上下文进行所有决策。避免为状态检测进行额外的读取调用。 </上下文加载>

阶段检测

阶段存储在 spec.md 的 frontmatter status 字段中：

状态	工件	下一步操作
`initialize`	无	创建 spec.md
`specification`	spec.md（无 [CLARIFY]）	创建 plan.md
`clarification`	spec.md 带有 [CLARIFY]	解决问题
`planning`	spec.md + plan.md	创建 tasks.md
`implementation`	tasks.md 有 `- [ ]`	执行任务
`complete`	所有任务 `- [x]`	归档或新功能

Frontmatter 模式

spec.md Frontmatter

---
id: 001-功能名称
title: 人类可读标题
status: specification  # initialize|specification|clarification|planning|implementation|complete
priority: P1           # P1|P2|P3
created: 2025-11-27
updated: 2025-11-27
progress:
  tasks_total: 0
  tasks_done: 0
owner: 团队名称
tags:
  - api
  - auth
---

更新 Frontmatter

在每个阶段转换时，使用技能的内置脚本：

# 更新状态和时间戳
node plugins/spec/skills/managing-workflow/scripts/update-status.js \
  ".spec/features/{feature}/spec.md" "planning"

# 使用 ISO 时间戳记录活动
node plugins/spec/skills/managing-workflow/scripts/log-activity.js \
  ".spec/features/{feature}/metrics.md" "计划已创建"

或者使用编辑工具 - 更新 frontmatter 中的状态行。

阶段门控（强制）

在 ANY 阶段转换之前，您 MUST 验证。这是 NOT 可选的。

# 每次阶段更改前 REQUIRED
RESULT=$(node plugins/spec/skills/managing-workflow/scripts/validate-phase.js \
  ".spec/features/{feature}" "{target-phase}")

# 检查结果 - 如果无效，DO NOT PROCEED
if [[ $(echo "$RESULT" | jq -r '.valid') != "true" ]]; then
  echo "BLOCKED: $(echo "$RESULT" | jq -r '.suggestion')"
  # 在继续之前创建缺失的工件
fi

阶段先决条件

目标阶段	必需工件	如果缺失
specification	无	-
clarification	spec.md	先创建 spec
planning	spec.md（无 [CLARIFY]）	解决澄清问题
implementation	spec.md, plan.md, tasks.md	创建缺失工件
complete	所有任务 `[x]`	完成剩余任务

执行规则

NEVER 直接跳到 implementation - plan.md 和 tasks.md MUST 存在
NEVER 在有未完成任务时标记 complete - 所有 [ ] 必须为 [x]
如果验证失败：创建缺失的工件，不要继续
对于简单功能：使用快速计划模板（见 plugins/spec/skills/managing-workflow/templates/quick-plan.md）

快速计划选项

对于简单功能（错误修复，< 3 个文件），使用简化模板：

plugins/spec/skills/managing-workflow/templates/quick-plan.md - 包含内联任务的组合计划
plugins/spec/skills/managing-workflow/templates/quick-tasks.md - 最小任务列表

这确保了工件的存在，同时减少了小变更的开销。

工作流操作

初始化新功能

向用户询问功能名称和描述
生成功能 ID：{NNN}-{kebab-name}
并行创建目录和文件：

mkdir -p .spec/features/{id}

同时创建这些文件：

带有 frontmatter 的 spec.md
带有跟踪模板的 metrics.md

设置会话：set_feature "{id}"

spec.md 模板

---
id: {id}
title: {title}
status: specification
priority: P2
created: {date}
updated: {date}
progress:
  tasks_total: 0
  tasks_done: 0
---

# 功能：{title}

## 概述

{description}

## 用户故事

### US1：{story title}

作为 {role}，我想要 {goal} 以便 {benefit}。

**验收标准：**
- [ ] AC1.1：{criterion}
- [ ] AC1.2：{criterion}

## 技术约束

- {constraint}

## 范围外

- {exclusion}

metrics.md 模板

# 指标：{title}

## 进度

| 阶段 | 状态 | 更新时间 |
|-------|--------|---------|
| 规范 | 待定 | |
| 澄清 | 待定 | |
| 计划 | 待定 | |
| 实施 | 0/0 | |

## 活动

| 时间戳 | 事件 |
|-----------|-------|

注意：所有时间戳使用 ISO 8601 格式：2025-11-27T10:30:00Z

定义规范

加载上下文以检查相关的归档功能
如果找到相关功能，询问：“找到类似功能 ‘{name}’。要引用它吗？”
向用户询问功能需求（使用 AskUserQuestion 获取范围/优先级）
生成带有验收标准的用户故事
用 [CLARIFY] 标记不明确的项目
请用户审查 spec.md
如果批准：
- 更新 frontmatter：status: specification（如果存在标签，则为 clarification）
- 更新 metrics.md

澄清

在 spec.md 中找到所有 [CLARIFY] 标签
分批处理，最多 4 个问题一组
使用 AskUserQuestion 解决每组问题
使用答案更新 spec.md，移除 [CLARIFY] 标签
请用户审查更改
当所有问题解决并批准后，更新 frontmatter：status: specification

创建计划

验证规范完整性（无 [CLARIFY] 标签）
读取 spec.md
生成技术计划，包括：
- 架构决策
- 组件及其用途
- 数据模型
- API 设计（如果适用）
- 集成点
写入 plan.md
请用户审查 plan.md
如果批准：
- 更新 frontmatter：status: planning
- 更新 metrics.md

plan.md 模板

# 技术计划：{title}

## 架构

{架构决策和理由}

## 组件

| 组件 | 用途 | 依赖项 |
|-----------|---------|--------------|
| {name} | {purpose} | {deps} |

## 数据模型

{模型定义}

## API 设计

{端点（如果适用）}

## 实施阶段

1. **阶段 1**：{description}
2. **阶段 2**：{description}

## 风险

| 风险 | 影响 | 缓解措施 |
|------|--------|------------|
| {risk} | {impact} | {mitigation} |

创建任务

读取 spec.md + plan.md
分解为具有并行组和依赖关系的任务：

## 并行组 A
- [ ] T001：{task} [P1]
- [ ] T002：{task} [P1]

## 并行组 B [depends:A]
- [ ] T003：{task} [P1] [depends:T001,T002]

标记关键变更：[critical:schema], [critical:api], [critical:types]
写入 tasks.md
请用户审查 tasks.md
如果批准：
- 更新 frontmatter：status: implementation
- 更新 frontmatter 中的进度：tasks_total: {count}
- 更新 metrics.md

tasks.md 模板

# 任务：{title}

## 并行组 A

- [ ] T001：{description} [P1]
- [ ] T002：{description} [P1]

## 并行组 B [depends:A]

- [ ] T003：{description} [P1] [depends:T001,T002]
- [ ] T004：{description} [P2] [depends:T001]

## 顺序

- [ ] T005：{description} [P1] [critical:api] [depends:T003,T004]

---

## 图例

- `[P1/P2/P3]` - 优先级级别
- `[depends:X,Y]` - 任务依赖关系
- `[critical:type]` - 需要额外审查（schema, api, types, auth）
- `[estimate:S/M/L]` - 规模估算

实施

需要门控检查 - 在实施之前，MUST 验证：

# MANDATORY：在任何实施之前运行此命令
RESULT=$(node plugins/spec/skills/managing-workflow/scripts/validate-phase.js \
  ".spec/features/{feature}" "implementation")

# 如果无效，STOP 并创建缺失的工件
if [[ $(echo "$RESULT" | jq -r '.valid') != "true" ]]; then
  MISSING=$(echo "$RESULT" | jq -r '.missing')
  echo "无法实施：缺失 $MISSING"
  # 返回并创建：plan.md 或 tasks.md
fi

仅在验证通过后，委托给 task-implementer 代理：

任务：task-implementer 代理

功能：{feature-path}
任务文件：.spec/features/{feature}/tasks.md

尽可能在并行组中执行任务。
更新任务复选框为已完成。
报告任何阻塞问题。

实施后：

更新 frontmatter 进度：tasks_done: {count}
如果全部完成，更新：status: complete

验证

委托给 artifact-validator 代理：

任务：artifact-validator 代理

功能：{feature-path}

验证：
1. 规范完整性（所有 AC 都有任务）
2. 计划覆盖（所有 US 都有实施）
3. 任务一致性（依赖关系有效）

归档功能

当功能完成时：

询问用户：“归档此功能？”
如果是： a. 检查已完成工作中的可重复模式 b. 如果检测到模式（2+ 个类似文件/任务），提供工具建议
运行 archive_feature

node plugins/spec/skills/managing-workflow/scripts/archive-feature.js "{feature-id}"

如果在功能期间创建了新技能/代理：
- 通知用户：“已创建新工具。重启 Claude 以使用它。”
- 建议：claude --continue 在重启后恢复
从上下文加载器建议下一步操作

归档时的工具检查

在归档之前，分析已完成的功能以寻找自动化机会：

模式检测（仅适用于可重复任务）：
- 创建了 3+ 个类似文件？→ 建议生成器技能
- 编写了 3+ 个测试文件？→ 建议测试代码技能
- 添加了 3+ 个 API 端点？→ 建议 api-testing 代理
- 重复了类似的任务结构？→ 建议工作流技能

如果以下情况，跳过工具建议：

功能是一次性的（迁移、独特集成）
模式计数 < 2
类似工具已存在

如果创建了工具：

## 已创建新工具

| 类型 | 名称 | 位置 |
|------|------|----------|
| 技能 | {name} | .claude/skills/{name}/ |
| 代理 | {name} | .claude/agents/{name}.md |

**需要重启**：运行 `claude --continue` 以使用新工具。

用户问题

策略性地使用 AskUserQuestion：

初始化时

questions:
  - header: "项目类型"
    question: "这是什么类型的项目？"
    options:
      - label: "绿地项目"
        description: "从头开始的新项目"
      - label: "棕地项目"
        description: "现有代码库"

功能选择时（多个功能）

questions:
  - header: "功能"
    question: "要处理哪个功能？"
    options:
      - label: "{feature-1}"
        description: "{status} - {progress}"
      - label: "{feature-2}"
        description: "{status}"
      - label: "新功能"
        description: "重新开始"

开始实施时

questions:
  - header: "执行"
    question: "如何执行任务？"
    options:
      - label: "引导式"
        description: "确认每个任务"
      - label: "自主式"
        description: "执行所有任务，最后报告"

错误处理

缺失工件 → 从该阶段开始
验证失败 → 显示差距，提供修复
任务阻塞 → 记录阻塞器，跳到下一个，最后报告
缺少 Frontmatter → 在下一次更新时添加

并行执行指南

独立时并行执行：

文件创建（spec.md + metrics.md）
多个验证
独立任务组

依赖时顺序执行：

规范 → 计划 → 任务
依赖任务组