aaw-workflow

Files (57)

• SKILL.md
• WORKFLOW_GUIDE.md
• aaw.py · scripts/
• VERSION · scripts/cli/
• __init__.py · scripts/cli/
• bootstrap.py · scripts/cli/
• README.md · scripts/cli/definitions/
• ar-clarify.yaml · scripts/cli/definitions/
• ar-init.yaml · scripts/cli/definitions/
• ar-split.yaml · scripts/cli/definitions/
• dev-design-gate.yaml · scripts/cli/definitions/
• dev-design.yaml · scripts/cli/definitions/
• dev-init.yaml · scripts/cli/definitions/
• dev-task-dev.yaml · scripts/cli/definitions/
• dev-task-split.yaml · scripts/cli/definitions/
• dev-test-design.yaml · scripts/cli/definitions/
• flow.yaml · scripts/cli/definitions/
• module-asis-analysis.yaml · scripts/cli/definitions/
• module-boundary-design.yaml · scripts/cli/definitions/
• module-design-gate.yaml · scripts/cli/definitions/
• module-detail-design-split.yaml · scripts/cli/definitions/
• module-test-design.yaml · scripts/cli/definitions/
• module-tobe-design.yaml · scripts/cli/definitions/
• ar-split.md · scripts/cli/definitions/prompts/
• sr-design-gate.yaml · scripts/cli/definitions/
• sr-design.yaml · scripts/cli/definitions/
• sr-init.yaml · scripts/cli/definitions/
• task-dev.yaml · scripts/cli/definitions/
• task-split.yaml · scripts/cli/definitions/
• errors.py · scripts/cli/
• install_lock.py · scripts/cli/
• __init__.py · scripts/cli/legacy_layout_migration/
• constants.py · scripts/cli/legacy_layout_migration/
• detector.py · scripts/cli/legacy_layout_migration/
• executor.py · scripts/cli/legacy_layout_migration/
• planner.py · scripts/cli/legacy_layout_migration/
• validator.py · scripts/cli/legacy_layout_migration/
• main.py · scripts/cli/
• mcp_config.py · scripts/cli/
• models.py · scripts/cli/
• network.py · scripts/cli/
• runtime_logging.py · scripts/cli/
• task-state.schema.json · scripts/cli/schemas/
• task_dev.py · scripts/cli/
• telemetry.py · scripts/cli/
• telemetry_config.py · scripts/cli/
• telemetry_config.yaml · scripts/cli/
• update.py · scripts/cli/
• version.py · scripts/cli/
• workflow.py · scripts/cli/
• README.md · scripts/studio/
• app.js · scripts/studio/
• index.html · scripts/studio/
• server.py · scripts/studio/
• start-studio-lan.bat · scripts/studio/
• start-studio.bat · scripts/studio/
• styles.css · scripts/studio/

SKILL.md (first lines)

# AAW 工作流

本 skill 只负责驱动 CLI 工作单，不包含具体业务节点知识。节点、入口、后继关系、变量映射、prompt、子 skill 调用和数据 schema 均由 CLI 读取配置后返回。

CLI 统一通过 `uv run` 调用（uv 按机器自身配置自动解析 Python 与依赖）；环境中没有 `uv` 时可退回 `python <skill-dir>/scripts/aaw.py ...`，此时需自行保证已安装 `typer` 与 `pyyaml`。

## 版本更新

每次会话开始、执行任何其他命令之前，先显式更新 skills：

```bash
uv run <skill-dir>/scripts/aaw.py update --json
```

按返回的 `status` 处理：

- `up_to_date`：已是最新，继续后续流程。
- `updated`：skills 已被替换为新版本（包括本 SKILL 文件）。重新读取本 SKILL 文件，按新版内容继续。
- `failed`（退出码 1，常见于网络不可达）：向用户提示更新失败原因，继续以当前版本执行。
- `recovery_required`（退出码 2）：安装可能不一致，停止执行，向用户转述错误信息与恢复指引。

即使跳过了这一步，`status` 命令也会自动检查并应用更新作为兜底；但显式执行 `update` 是首选路径，能让用户明确看到版本变化。

## 入口意图判定

当用户通过本 skill 但没有给出明确指令（例如空输入、只说“使用 aaw-workflow”、只贴需求但没说明继续还是新建）时，不要因为仓库中存在进行中的 workflow 就自动继续执行。

先执行：

```bash
uv run <skill-dir>/scripts/aaw.py status --json
```

然后按以下规则处理：

1. 如果用户明确说“继续 / 恢复 / 查看进度 / 处理 SR-XXX”，进入恢复流程。
2. 如果用户明确说“新建 / 启动 / 从 SR 入口 / 从 AR 入口 / 从 dev 入口”，进入启动流程。
3. 如果用户明确说“回退 / 返工 / 重做 / 重新执行某个阶段”，先定位目标 SR 和 step，再执行不带 `--artifacts` 的 `rollback --json` 获取回退预览；向用户展示 CLI 返回的两种成果物策略，等待用户明确选择后执行所选 `command_argv`。预览阶段不得修改 workflow 或文件。
4. 如果用户意图不明确且已有 workflow，列出已有 SR，并询问用户是继续已有 workflow，还是新开 SR/AR/dev workflow；等待用户选择，不要执行 `next`。
5. 如果用户意图不明确且没有已有 workflow，询问用户选择三个入口之一，并收集各自的启动变量：
   - **SR 入口**（企业/严谨流程）：需原始需求文件；
   - **AR 入口**：需已有 `repo-init` 与 `.sdd/software_architecture.md`；
   - **dev 入口**（个人开发者/轻量，设计与开发同一人）：适合一人独立完成的小需求，流程较短；详见下方定位说明。
6. 如果用户要继续但没有指定 SR，且存在多个 workflow，列出候选 SR 并让用户选择。

启动新 workflow 前必须确认新的 `SR`；不要复用已有 `.sdd/<SR>/workflow.yaml`，除非用户明确表示要继续该 SR。

## 恢复上下文

当用户明确要继续某个 workflow，或已在入口意图判定中选择继续后，执行：

```bash
uv run <skill-dir>/scripts/aaw.py status --json
uv run <skill-dir>/scripts/aaw.py next --sr SR-XXX --json
```

`next --json` 返回的 `ready` 就是当前可执行工作单。不要依赖记忆判断下一步，始终以 CLI 返回为准。

### 旧成果物目录迁移（临时）

如果 `status` 或 `next` 提示当前工作流仍在引用旧成果物目录，不要绕过检查，也不要直接手工修改
`workflow.yaml`。先获取结构化迁移计划：

```bash
uv run <skill-dir>/scripts/aaw.py migrate-layout --sr SR-XXX --json
```

按以下顺序处理：

1. `plan.unresolved` 为空时，执行返回的 `apply_command_argv`。
2. 存在 `unresolved` 时，根据旧文件的路径、标题、内容以及 `llm_resolution.allowed_targets`
   判断其唯一新位置。不得合并、拆分或改写文档，也不得选择候选列表之外的位置。
3. 确定映射后追加 `--map '<旧路径>=<新路径>'`，重新生成计划；可以指定多个 `--map`。
4. 如果仍无法唯一判断，向用户展示具体文件和候选位置，请用户确认；不得自行猜测。
5. 只有计划不再包含 `unresolved` 时才能使用 `--apply`。迁移完成后重新执行 `status` 和 `next`。

该迁移能力仅用于本次目录升级，将在迁移窗口结束后整体删除，不属于长期工作流兼容协议。

## 启动流程

使用入口启动一条工作流：

```bash
uv run <skill-dir>/scripts/aaw.py start --entry sr --sr SR-XXX --requirement-file <需求文件> --json
uv run <skill-dir>/scripts/aaw.py start --entry ar --sr SR-XXX --ar AR-XXX --title "AR描述" --json
uv run <skill-dir>/scripts/aaw.py start --entry dev --sr SR-XXX --json
```

三个入口的定位：

| 入口 | 适用场景 | 必需变量 | 链路 |
|---|---|---|---|
| `sr` | 企业/严谨流程，需求需完整留痕 | `SR` + `--requirement-file` | 11 步，产出约 11 份文档 |
| `ar` | 已有架构基线，从某个 AR 直接切入 | `SR` `AR` `描述` | 从 `ar-clarify` 起 |
| `dev` | 个人开发者/轻量迭代，追求快速出代码 | `SR` | 6 步，产 `dev-design.md`、`test-design.md`、`tasks-overview.md` 及 `.context/` 下门禁报告 |

SR 入口必须提供 `--requirement-file`（原始需求文件），CLI 会将其原样保存为
`.sdd/{SR}/original-requirement.md`，作为 `sr-design` 和 `sr-design-gate` 的正式输入。
启动前按以下方式准备需求文件：

1. 提取用户明确作为原始需求提供的文本，保持原文，不总结、不改写、不做设计性加工；
   需求分布在多个段落时按原顺序完整保存。普通讨论、Agent 的解释和设计推导不得混入。
2. 将原文写入一个临时 Markdown 文件，用它调用 `start`。
3. 无法判断用户是否已提供原始需求时，先向用户收集需求，不得以空内容或臆造内容启动。
4. `start` 成功后，向用户回显已保存的 `original-requirement.md` 内容（较长时回显开头
   若干行并注明总行数），请用户确认与其提供的需求一致。用户指出不一致时，停止推进，
   不要执行 `next`；让用户提供或确认正确原文后，修正当前 workflow 的
   `.sdd/{SR}/original-requirement.md`，重新回显核对，再继续当前 workflow。不要重新执行
   `start`，因为该 SR 的 `workflow.yaml` 已经存在。

AR 入口要求当前仓库已经执行过 `repo-init`，并且存在 `.sdd/software_architecture.md`。如果该文件缺失，`next --json` 会在工作单的 `inputs` 中标记 blocked，且 `done` 会失败。

dev 入口把设计、开发当作**同一个人**的两段工作：一份贯穿全程的设计文档由同一人维护，由同一人对照实现，因此流程比 sr 短，也不要求先备好 `--requirement-file`。适用与否的判断标准是需求的规模——只有一个人能独立设计并实现、无需多角色交接与分阶段留痕的需求适合它；需要多人协作、复杂度高、或需要完整留痕的需求请走 sr 严谨流程。需求本身仍需想清楚并确认——`dev-init` 会引导你确认需求（提供了较长原文时可落盘为可选的 `.sdd/{SR}/requirement.md`），随后 `dev-design` 用单份 `.sdd/{SR}/dev-design.md` 承接功能设计、模块边界与详细设计（问人与问代码是同一个问题池循环的两个出口，代码论断内联 `file:line` 引用，不设现状附录），`dev-test-design` 基于该设计生成 `.sdd/{SR}/test-design.md`（最小充分用例集、覆盖矩阵与缺口清单），`dev-design-gate` 做 3 项轻量准入检查（决策已收敛、代码论断可回溯、契约与验收可执行），最后复用 `task-split` / `task-dev`（轻量模式）完成拆分与开发——task-split 会回填覆盖矩阵的「首次可验证阶段」列并为每个任务圈定用例 ID。

使用 dev 入口前值得了解一点：功能设计、详细设计等阶段在这里被合并成一份口径统一的文档。若你的流程要求这些阶段分开评审，这份文档需要由你按评审需要自行组织讲解——它面向贯穿设计到开发的同一人，而非按评审阶段预先分册的交付物。

也可以使用通用变量形式：

```bash

From pi-ixel/Awesome-Agent-Workflow, MIT.

More from pi-ixel/Awesome-Agent-Workflow