agent-workflow

通用 AI 交付工作流 Skill + CLI：把需求材料变成可审阅 DSL、可执行 Plan、原子任务和可验证交付。它不绑定某个 IDE，支持 Claude Code、Codex、Copilot、Cursor、Windsurf、Cline、Continue、QoderWork / Qoder、TraeIDE、Lingma、OpenClaw、qclaw 及任意对话；Cursor Skill 只是可选入口。

在线手册：https://duntak1.github.io/agentworkflow/

为什么需要

AI 编码常见问题不是“不会写代码”，而是上下文和闸门不稳定：

• 需求没审清就直接改业务代码。
• Agent 猜测路径、架构、验收标准。
• Plan 不可执行，任务之间依赖不清。
• 改动范围扩大，夹带无关重构。
• 口头说完成，但没有跑项目真实验证命令。
• 换 IDE 或新会话后，要重复解释流程。

解决方案

agent-workflow 把交付拆成一条跨工具流水线：

启动 aw / @aw → 角色确认 → Project Scan → 阶段确认 → 同步中心决策 → 项目类型/构建目标确认 → 必要时同步中心就绪 → Reference/基线 → DSL 已审 → Plan 可执行 → confirm → AT-T 任务 → verify → compact / handoff

能力	解决的问题
启动 aw / @aw / aw start	不必完整输入 agentworkflow；首次启动先问角色：产品、前端、后端、全栈
reference/manifest.yaml	材料来源可追踪，避免编造路径
`aw project scan	gate`
aw dsl / aw dsl apply	先产出可审需求 DSL，再允许写代码
aw dsl suite	生成多文件 DSL 套件，覆盖需求、页面、交互、事件、联动边界、验收
aw dsl review	给工程师输出 DSL 审阅包，确认通过后再 approve
aw plan / aw plan apply	把方案拆成可执行 Plan + AT-T 原子任务
`aw rules init	review
aw confirm	人类确认后才生成工程执行索引
aw file-index / docs/FILE_INDEX.md	生成项目代码文件索引；AI 代写代码后供人类工程师快速定位需手改文件
`aw task brief	confirm`
`aw context plan	gate`
`aw task start	blocked
aw task complete --run-e2e	使用项目真实命令验证；通过完成，失败自动写 Bug 流水
`aw bug add	list`
`aw req new	change`
aw index	交付文件索引刷新；REQ / Bug / TP / DSL / Plan 写入命令会自动触发扫描刷新
aw file-index	项目代码文件索引刷新；覆盖 scripts、skill、templates、agent-workflow、docs、CI、配置入口
aw adapters --all	同一套规则接入多 IDE / 多 Agent
`aw paste session	task`
aw status --json / aw capabilities --json	给 dashboard、插件和自动化提供机器可读状态与能力摘要
aw dashboard	只读终端视图，集中显示当前状态、能力和机器可读入口
`aw memory add	search
aw compact --write --snapshot	Codex / 新会话前的一键工程化上下文压缩：更新 handoff、生成新会话粘贴块、可选写聊天 Memory
`aw gate pre-commit	task
`aw context plan	gate
aw context enrich / aw verify --affected	自动补全 Context Plan 的 symbol/影响范围，并按变更范围写入 affected analysis
`aw contract change	test
aw contract diff --write / aw vcs fill / aw watch index	自动记录契约 diff、生成 PR/MR/CR 草稿、刷新索引和 affected analysis
`aw vcs branch	fill
`aw pm start	init
`aw agents register	list
`aw agents claim	heartbeat
aw score record / aw recover ...	交付评分和恢复机制：审计、修复、交接、回滚有固定路径

Skill 首屏还内置编码原则：Think before coding、Simplicity first、Mature solutions first、Surgical changes、Goal-driven execution。

Token 省用原则

默认按“先摘要、后展开”执行：启动只看 aw start / aw status --json / aw project scan 摘要；研发任务只读 aw task brief 和 docs/context/tasks/CTX-<AT-T>.md 白名单；跨端同步只读 aw sync inbox 摘要、TASK_BOARD.md 和相关 event / contract。不要把 HTML 手册、ENGINEERING_INDEX.md、整个同步中心、整个 inbox 或整仓代码塞进 AI 上下文。

默认 AT-T 预算：6 个业务文件、12 个 symbol、3 次精准搜索。超过预算前，Agent 必须说明原因并等待工程师确认。

快速开始

对话里最短启动：

启动 aw

或：

@aw

首次启动后 Agent 必须先问角色：1=产品、2=前端、3=后端、4=全栈。选择 全栈 时，默认前后端代码在一个仓库下，构建目标为 3=前后端项目，同步中心不强制；只有分仓、不同电脑或 PM 三端协作时才强制同步中心。

cd your-app
/path/to/agentworkflow/scripts/aw install . --adapters
chmod +x scripts/aw scripts/*.sh
./scripts/aw start
./scripts/aw setup
./scripts/aw project scan
./scripts/aw config init --project-stage 1 # 1=全新项目，2=已有/存量项目；先看 docs/PROJECT_SCAN.md 再确认
./scripts/aw config init --sync-center 1 --sync-center-path ../project-harness # 1=建立/使用，2=不建立，3=稍后决定且阻断 Plan
./scripts/aw config init --project-kind 1 --repo-url https://github.com/<owner>/<repo>
# 代码托管平台：1=GitHub，2=本地 Git，3=GitLab，4=Bitbucket，5=Gitee，6=GitCode，7=Gitea，8=Forgejo，9=GitLab CE，10=Gerrit，11=云效 Codeup
./scripts/aw config init --build-target 1 # 1=前端，2=后端，3=前后端
./scripts/aw status
./scripts/aw dashboard
./scripts/aw memory inject
./scripts/aw status --json
./scripts/aw capabilities --json

如果从远程仓库安装 Cursor Skill，可直接传 GitHub URL：

/path/to/agentworkflow/scripts/install-cursor-skill.sh https://github.com/duntak1/agentworkflow.git

验证整条流程：

./scripts/aw demo

工程规范写入 docs/ENGINEERING_RULES.md，项目实际栈和命令写入 docs/PROJECT_CONFIG.md。AT-T 原子任务会标注领域：Frontend / Backend / Fullstack / QA / Docs / Ops / Data。前后端边界清楚时拆开，必须贯通 UI 与 API 的验收标 Fullstack，避免为了分类强拆任务。

也可以按人类指令定向拆任务，例如“DSL 已确认，生成前端研发计划”对应：

./scripts/aw approve dsl docs/dsl/DSL_xxx.md --plan --domain frontend

后端同理使用 --domain backend。

源码仓发布检查：

./scripts/e2e-smoke.sh
./scripts/build-skill-archive.sh

支持矩阵

Agent / IDE	入口文件	安装命令	状态
Claude Code	CLAUDE.md	aw adapters --claude	支持
OpenAI Codex	AGENTS.md	aw adapters --codex	支持
GitHub Copilot / VS Code	.github/copilot-instructions.md	aw adapters --copilot	支持
Cursor	.cursor/rules/agent-workflow.mdc + 可选 Skill	aw adapters --cursor / aw sync-skill	支持
Windsurf	.windsurfrules	aw adapters --windsurf	支持
Cline	.clinerules	aw adapters --cline	支持
Continue	.continue/rules/agent-workflow.md	aw adapters --continue	支持
QoderWork / Qoder	.qoderwork/rules/agent-workflow.md	aw adapters --qoderwork	支持
TraeIDE	.trae/rules/agent-workflow.md	aw adapters --trae	支持
Lingma / 通义灵码	.lingma/rules/agent-workflow.md	aw adapters --lingma	支持
OpenClaw	.openclaw/agent-workflow.md	aw adapters --openclaw	支持
qclaw	.qclaw/agent-workflow.md	aw adapters --qclaw	支持
任意 Chat	粘贴块	aw paste session	支持

可验证范围

• 7 类以上 Agent / IDE 适配入口。
• 20+ 个 aw 子命令覆盖安装、诊断、DSL、Plan、任务、验证、CI、升级、移除。
• e2e 路径覆盖：install → init → DSL → Plan → approve → confirm → task → TP → verify。
• 发布检查覆盖 Skill 源、Skill 包、命令文档同步与版本文件。

Cursor Skill（可选）

cd agentworkflow
./scripts/sync-skill.sh

也可从远程仓安装：

./scripts/install-cursor-skill.sh https://github.com/duntak1/agentworkflow.git

已安装用户更新本机 skill 和当前项目：

./scripts/aw upgrade --from-github --adapters
# 或：
./scripts/aw update --from-github --adapters

这会重新获取 https://github.com/duntak1/agentworkflow.git，删除本机旧的 agent-workflow / aw-delivery skill 安装，安装最新版 skill，并替换当前项目中的 agent-workflow/ 与 scripts/；业务 docs/、reference/ 和运行状态会保留。

详见 PUBLISH.md · skill/QUICKSTART.md。

Codex Plugin Metadata

本仓包含 .codex-plugin/plugin.json，用于 Codex 插件入口的基础元数据；.agents/plugins/marketplace.json 提供 repo-root local marketplace 条目，source.path 指向当前仓库根。核心流程仍以 agent-workflow/ 与 scripts/aw 为真源。

Handoff vs Memory

• docs/handoff/PROJECT_HANDOFF.md：当前目标、进度、阻塞、下一步。
• docs/memory/：稳定事实、决策、偏好、可复用流程、长期风险。
• 只有当 Handoff 里的结论会被未来任务复用时，才提炼成 aw memory add。
• aw compact "本轮目标" --write --snapshot：一键生成工程化压缩快照，写入 PROJECT_HANDOFF.md、LAST_AUTO_SNAPSHOT.md 和 PASTE_IN_NEW_CHAT.txt；带 --memory-summary 时同步写聊天摘要 Memory。

文档

路径	说明
skill/SKILL.md	Cursor Skill 真源
skill/reference.md	Skill 能力与 CLI 速查
agent-workflow/INVOCATION.md	调用真源（install 后）
agent-workflow/AICODING_WORKFLOW.md	AI 编码阶段 A-E
docs/handoff/AGENTWORKFLOW_ROADMAP.md	项目路线图

License

MIT