autonomous-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Autonomous Workflow

自主工作流

Execute complete feature development cycles autonomously—from task intake through tested PR delivery—using isolated Git worktrees.

利用独立Git工作树，自主执行完整的功能开发周期——从任务接收到提交经过测试的PR。

⚠️ CRITICAL: Before Starting ANY Work

⚠️ 重要提示：开始任何工作前必须完成以下步骤

You MUST complete these steps IN ORDER before writing any code:

你必须按顺序完成这些步骤后才能编写任何代码：

Step 1: Detect Workflow Mode (MANDATORY)

步骤1：检测工作流模式（必填）

Analyze the task scope to determine the workflow mode:

Mode	Criteria	Artifacts Required
Full	4+ files OR complex/architectural	YES - MANDATORY
Lite	1-3 files AND simple/straightforward	No

When in doubt, choose Full Mode.

分析任务范围以确定工作流模式：

模式	判断标准	是否需要工件
完整模式	修改4个及以上文件或涉及复杂架构变更	是 - 必填
轻量模式	修改1-3个文件且需求简单直接	否

若不确定，默认选择完整模式。

Step 2: Create Artifact Files (Full Mode ONLY)

步骤2：创建工件文件（仅完整模式）

For Full Mode, you MUST create these files in

.gw/{branch-name}/

BEFORE Phase 1 Planning begins:

bash

undefined

对于完整模式，你必须在第1阶段规划开始前在

.gw/{branch-name}/

目录下创建以下文件：

bash

undefined

Create artifact directory

创建工件目录

mkdir -p .gw/{branch-name}

Create required files

创建所需文件

touch .gw/{branch-name}/task.md touch .gw/{branch-name}/plan.md


| File             | Purpose                                | When to Update            |
| ---------------- | -------------------------------------- | ------------------------- |
| `task.md`        | Dynamic checklist, decisions, blockers | Throughout implementation |
| `plan.md`        | Implementation strategy, file list     | After Phase 1 analysis    |
| `walkthrough.md` | Final summary for PR                   | Phase 6 only              |

**⛔ DO NOT proceed to implementation without these files for Full Mode tasks.**

touch .gw/{branch-name}/task.md touch .gw/{branch-name}/plan.md


| 文件             | 用途                                | 更新时机            |
| ---------------- | -------------------------------------- | ------------------------- |
| `task.md`        | 动态任务清单、决策记录、阻塞点跟踪 | 开发全程持续更新 |
| `plan.md`        | 实现策略、文件修改清单     | 第1阶段分析完成后    |
| `walkthrough.md` | PR用最终总结文档                   | 仅第6阶段创建              |

**⛔ 完整模式任务未创建这些文件前，不得进入开发环节。**

Step 3: Announce Mode Selection

步骤3：宣布模式选择

State your mode selection explicitly:

"This is a Full Mode task (affects 5+ files). Creating
.gw/{branch-name}/
artifacts now."

"This is a Lite Mode task (2 files, simple fix). Proceeding without artifacts."

明确告知你选择的模式：

"这是一个完整模式任务（涉及修改5个及以上文件）。正在创建
.gw/{branch-name}/
工件。"

或

"这是一个轻量模式任务（修改2个文件，简单修复）。将不创建工件直接推进。"

Prerequisites: gw CLI Installation

前置条件：gw CLI安装

Before Phase 2 (Worktree Setup), verify the

gw

CLI is installed:

bash

which gw

在进入第2阶段（工作树设置）前，需确认

gw

CLI已安装：

bash

which gw

If gw is NOT installed

若未安装gw

STOP and prompt the user to install gw. The workflow cannot proceed without it.

Installation options (present to user):

bash

undefined

立即停止操作并提示用户安装gw。 未安装该工具无法推进工作流。

安装选项（提供给用户）：

bash

undefined

Via npm (recommended)

通过npm安装（推荐）

npm install -g @gw-tools/gw

Via Homebrew (macOS)

通过Homebrew安装（macOS）

brew install mthines/gw-tools/gw

Via pnpm

通过pnpm安装

pnpm add -g @gw-tools/gw


**After installation, set up shell integration:**

```bash

pnpm add -g @gw-tools/gw


**安装完成后，设置Shell集成：**

```bash

For zsh (add to ~/.zshrc)

针对zsh（添加至~/.zshrc）

echo 'eval "$(gw install-shell)"' >> ~/.zshrc source ~/.zshrc

For bash (add to ~/.bashrc)

针对bash（添加至~/.bashrc）

echo 'eval "$(gw install-shell)"' >> ~/.bashrc source ~/.bashrc

For fish (add to ~/.config/fish/config.fish)

针对fish（添加至~/.config/fish/config.fish）

echo 'gw install-shell | source' >> ~/.config/fish/config.fish source ~/.config/fish/config.fish


**Verify installation:**

```bash
gw --version
gw --help

Then initialize gw in the repository (if not already done):

bash

undefined

echo 'gw install-shell | source' >> ~/.config/fish/config.fish source ~/.config/fish/config.fish


**验证安装：**

```bash
gw --version
gw --help

然后在仓库中初始化gw（若未初始化）：

bash

undefined

For existing repositories

针对已有仓库

gw init

With auto-copy files (recommended)

自动复制文件（推荐）

gw init --auto-copy-files .env,secrets/ --post-checkout "npm install"


Once `gw` is installed and configured, resume the workflow from Phase 2.

---

gw init --auto-copy-files .env,secrets/ --post-checkout "npm install"


`gw`安装并配置完成后，从第2阶段恢复工作流。

---

Rules

规则

Rule	Description
overview	HIGH - Workflow phases, when to use, expected outcomes
smart-worktree-detection	CRITICAL - Fuzzy match task to current worktree, prompt to continue or create new
phase-0-validation	CRITICAL - MANDATORY - Validate requirements before any work
phase-1-planning	HIGH - Deep codebase analysis and implementation planning
phase-2-worktree	CRITICAL - MANDATORY - Create isolated worktree with `gw add`
phase-3-implementation	HIGH - Incremental implementation with continuous validation
phase-4-testing	CRITICAL - Fast iteration loop until tests pass (Ralph Wiggum pattern)
phase-5-documentation	MEDIUM - Update README, CHANGELOG, API docs
phase-6-pr-creation	HIGH - Create draft PR, deliver results
phase-7-cleanup	LOW - Optional worktree removal after merge
decision-framework	HIGH - Branch naming, test strategy, iteration decisions
error-recovery	HIGH - Recovery procedures for common errors
safety-guardrails	CRITICAL - Validation checkpoints, resource limits, rollback
parallel-coordination	HIGH - Multi-agent coordination, handoff protocol
artifacts-overview	HIGH - Three-artifact pattern (Task, Plan, Walkthrough), file locations
task-tracking	HIGH - Dynamic task updates throughout workflow
walkthrough-generation	MEDIUM - Final summary generation at Phase 6

规则	描述
概述	高优先级 - 工作流阶段、适用场景、预期产出
智能工作树检测	关键 - 模糊匹配任务与当前工作树，提示用户继续或创建新工作树
第0阶段验证	关键 - 必填 - 开展任何工作前验证需求
第1阶段规划	高优先级 - 深度代码库分析与实现规划
第2阶段工作树设置	关键 - 必填 - 使用 `gw add` 创建独立工作树
第3阶段开发	高优先级 - 增量开发并持续验证
第4阶段测试	关键 - 快速迭代直至测试通过（Ralph Wiggum模式）
第5阶段文档编写	中优先级 - 更新README、CHANGELOG、API文档
第6阶段PR创建	高优先级 - 创建草稿PR、交付成果
第7阶段清理	低优先级 - 合并后可选移除工作树
决策框架	高优先级 - 分支命名、测试策略、迭代决策
错误恢复	高优先级 - 常见错误的恢复流程
安全防护	关键 - 验证检查点、资源限制、回滚机制
并行协作	高优先级 - 多Agent协作、交接协议
工件概述	高优先级 - 三工件模式（任务、规划、总结）、文件位置
任务跟踪	高优先级 - 开发全程动态更新任务
总结文档生成	中优先级 - 第6阶段生成最终总结

Templates

模板

Structured templates for consistent artifact generation:

Template	Purpose
task.template.md	Dynamic task checklist
plan.template.md	Implementation plan
walkthrough.template.md	Final summary

用于生成标准化工件的结构化模板：

模板	用途
task.template.md	动态任务清单
plan.template.md	实现计划
walkthrough.template.md	最终总结

Quick Reference

速查指南

Full Mode (4+ files, complex changes)

完整模式（修改4+文件，复杂变更）

Phase	Command/Action
0. Validation	Ask clarifying questions, get user confirmation
1. Planning	Analyze codebase, create `.gw/{branch}/task.md` and `plan.md`
2. Worktree	`gw add feat/feature-name`
3. Implementation	Code in worktree, update `task.md` on changes
4. Testing	`npm test` , iterate until all pass, log in `task.md`
5. Documentation	Update README, CHANGELOG
6. PR Creation	Generate `walkthrough.md` , `gh pr create --draft`
7. Cleanup	`gw remove feat/feature-name` (after merge)

阶段	命令/操作
0. 验证	提出澄清问题、获取用户确认
1. 规划	分析代码库，创建 `.gw/{branch}/task.md` 和 `plan.md`
2. 工作树设置	`gw add feat/feature-name`
3. 开发	在工作树中编码，变更时更新 `task.md`
4. 测试	`npm test` ，迭代直至全部通过，记录至 `task.md`
5. 文档编写	更新README、CHANGELOG
6. PR创建	生成 `walkthrough.md` ，执行 `gh pr create --draft`
7. 清理	`gw remove feat/feature-name` （合并后执行）

Lite Mode (1-3 files, simple changes)

轻量模式（修改1-3文件，简单变更）

Phase	Command/Action
0. Validation	Quick clarification if needed
1. Planning	Brief mental plan (no artifact files)
2. Worktree	`gw add fix/bug-name` (optional for trivial)
3. Implementation	Code directly, commit when done
4. Testing	`npm test` , fix any failures
5. PR Creation	`gh pr create --draft`

阶段	命令/操作
0. 验证	必要时快速确认需求
1. 规划	简要的心理规划（无需创建工件文件）
2. 工作树设置	`gw add fix/bug-name` （ trivial修复可省略）
3. 开发	直接编码，完成后提交
4. 测试	`npm test` ，修复所有失败用例
5. PR创建	`gh pr create --draft`

Workflow Modes

工作流模式

Mode	Files Changed	Artifacts	Use When
Lite	1-3 files	No	Simple fixes, small enhancements
Full	4+ files	Yes	Features, refactors, complex changes

Full Mode: Creates

.gw/{branch}/

artifacts for progress tracking and context recovery.

Lite Mode: Faster execution without artifact overhead. Still uses worktree isolation.

模式	修改文件数	是否需要工件	适用场景
轻量模式	1-3个	否	简单修复、小型功能增强
完整模式	4个及以上	是	新功能开发、重构、复杂变更

完整模式：创建

.gw/{branch}/

工件用于跟踪进度和恢复上下文。

轻量模式：无需工件开销，执行速度更快。仍会使用工作树隔离环境。

Key Principles

核心原则

Detect workflow mode FIRST: Determine Full vs Lite before any other action.
Create artifacts BEFORE planning (Full Mode):
```
.gw/{branch}/task.md
```
and
```
plan.md
```
are MANDATORY.
Always validate first (Phase 0): Never skip directly to implementation.
Always create worktree (Phase 2): Isolation is mandatory (can skip for trivial fixes).
Track progress with artifacts: Update
```
.gw/{branch}/task.md
```
as you work.
Smart worktree detection: Check if current worktree matches task before creating new.
Iterate until correct: No artificial iteration limits (Ralph Wiggum pattern).
Fast feedback loops: Run tests frequently, fix failures immediately.
Self-validate continuously: Check work at every step.
Stop and ask when blocked: Don't guess on ambiguity.

优先检测工作流模式：先确定完整模式或轻量模式，再执行其他操作。
完整模式需先创建工件：
```
.gw/{branch}/task.md
```
和
```
plan.md
```
为必填项。
始终先验证（第0阶段）：不得直接跳过验证进入开发。
始终创建工作树（第2阶段）：必须使用隔离环境（trivial修复可例外）。
用工件跟踪进度：开发过程中持续更新
```
.gw/{branch}/task.md
```
。
智能工作树检测：创建新工作树前检查当前工作树是否匹配任务。
迭代直至正确：无人工迭代限制（Ralph Wiggum模式）。
快速反馈循环：频繁运行测试，立即修复失败用例。
持续自我验证：每一步都检查工作成果。
遇阻塞及时询问：对模糊需求不得猜测。

Artifact System

工件系统

Inspired by Google Antigravity, this workflow produces three artifacts in

.gw/{branch-name}/

Artifact	File	Created	Purpose
Task	`task.md`	Phase 1	Dynamic checklist, decisions, discoveries
Plan	`plan.md`	Phase 1	Implementation strategy
Walkthrough	`walkthrough.md`	Phase 6	Final summary for PR

Files are gitignored and grouped by branch for easy browsing.

灵感来自Google Antigravity，本工作流在

.gw/{branch-name}/

目录下生成三类工件：

工件	文件	创建阶段	用途
任务清单	`task.md`	第1阶段	动态任务清单、决策记录、发现事项
实现计划	`plan.md`	第1阶段	开发策略
总结文档	`walkthrough.md`	第6阶段	PR用最终总结

这些文件会被Git忽略，并按分支分组以便浏览。

Workflow Flow

工作流流程

┌─────────────────────────────────────────────────────┐
│  MODE DETECTION ← MANDATORY FIRST STEP              │
│  Analyze task → Choose Full (4+ files) or Lite      │
│  Full Mode: Create .gw/{branch}/ artifacts NOW      │
└─────────────────────────────────────────────────────┘
    ↓
Phase 0: Validation ← MANDATORY
    ↓ (user confirms)
Phase 1: Planning (Full: write to plan.md, Lite: mental plan)
    ↓ (plan validated)
Phase 2: Worktree Setup ← MANDATORY (with smart detection)
    ↓ (worktree created)
Phase 3: Implementation (Full: update task.md, Lite: just code)
    ↓ (code complete)
Phase 4: Testing ← iterate until passing
    ↓ (all tests pass)
Phase 5: Documentation
    ↓ (docs complete)
Phase 6: PR Creation (Full: generate walkthrough.md)
    ↓ (draft PR delivered)
Phase 7: Cleanup (optional)

┌─────────────────────────────────────────────────────┐
│  模式检测 ← 必须首先执行              │
│  分析任务 → 选择完整模式（4+文件）或轻量模式      │
│  完整模式：立即创建.gw/{branch}/工件      │
└─────────────────────────────────────────────────────┘
    ↓
第0阶段：验证 ← 必填
    ↓（用户确认后）
第1阶段：规划（完整模式：写入plan.md；轻量模式：心理规划）
    ↓（计划验证通过后）
第2阶段：工作树设置 ← 必填（含智能检测）
    ↓（工作树创建完成）
第3阶段：开发（完整模式：更新task.md；轻量模式：直接编码）
    ↓（编码完成）
第4阶段：测试 ← 迭代直至通过
    ↓（所有测试通过）
第5阶段：文档编写
    ↓（文档完成）
第6阶段：PR创建（完整模式：生成walkthrough.md）
    ↓（草稿PR提交完成）
第7阶段：清理（可选）

Smart Worktree Detection

智能工作树检测

Before creating a new worktree, the workflow checks if the current context matches the task:

Scenario	Action
On main/master	Always create new worktree
Worktree name matches task keywords	Prompt user to continue or create new
No keyword match	Create new worktree

创建新工作树前，工作流会检查当前上下文是否匹配任务：

场景	操作
当前处于main/master分支	始终创建新工作树
工作树名称匹配任务关键词	提示用户继续当前工作树或创建新工作树
无关键词匹配	创建新工作树

Fast Iteration Loop (Phase 4)

快速迭代循环（第4阶段）

Based on the Ralph Wiggum pattern:

while not all_tests_pass:
    1. Run tests
    2. If pass: done
    3. If fail: analyze → fix → commit → continue
    4. Safety: warn at 10 iterations, stop at 20

基于Ralph Wiggum模式：

while not all_tests_pass:
    1. 运行测试
    2. 若通过：结束循环
    3. 若失败：分析问题 → 修复 → 提交 → 继续循环
    4. 安全限制：迭代10次时发出警告，20次时停止

Troubleshooting Quick Reference

故障排查速查

Issue	Check	Recovery
Wrong worktree	`gw list` , `pwd`	`gw cd <correct-branch>`
gw command not found	`which gw`	`npm install -g @gw-tools/gw`
Secrets missing	`cat .gw/config.json`	`gw sync <branch> .env`
Agent stuck in loop	`task.md` iteration history	Try alternative approach, ask user
Tests keep failing	`task.md` test results	Focus on ONE failure, escalate at 7+
Agent hallucinated cmd	Error message	See error-recovery

问题	检查项	恢复方案
工作树错误	`gw list` 、 `pwd`	`gw cd <correct-branch>`
gw命令未找到	`which gw`	`npm install -g @gw-tools/gw`
密钥缺失	`cat .gw/config.json`	`gw sync <branch> .env`
Agent陷入循环	`task.md` 迭代历史	尝试替代方案，询问用户
测试持续失败	`task.md` 测试结果	聚焦单个失败用例，迭代7次以上时升级问题
Agent生成错误命令	错误信息	参考错误恢复

Related Skills

References

参考资料

Detailed examples and scenarios (loaded on-demand):

Complete Workflow Example
Error Recovery Scenarios
Iterative Refinement Example

详细示例与场景（按需加载）：

完整工作流示例
错误恢复场景
迭代优化示例

Research Sources

研究来源

Google Antigravity Artifacts - Three-artifact pattern
Ralph Wiggum AI Coding Loops - Iteration pattern
Addy Osmani's LLM Workflow - Fast feedback loops
Claude Code Worktree Support - Best practices

Google Antigravity Artifacts - 三工件模式
Ralph Wiggum AI Coding Loops - 迭代模式
Addy Osmani's LLM Workflow - 快速反馈循环
Claude Code Worktree Support - 最佳实践

autonomous-workflow

Original

Translation

Autonomous Workflow

自主工作流

⚠️ CRITICAL: Before Starting ANY Work

⚠️ 重要提示：开始任何工作前必须完成以下步骤

Step 1: Detect Workflow Mode (MANDATORY)

步骤1：检测工作流模式（必填）

Step 2: Create Artifact Files (Full Mode ONLY)

步骤2：创建工件文件（仅完整模式）

Create artifact directory

创建工件目录

Create required files

创建所需文件

Step 3: Announce Mode Selection

步骤3：宣布模式选择

Prerequisites: gw CLI Installation

前置条件：gw CLI安装

If gw is NOT installed

若未安装gw

Via npm (recommended)

通过npm安装（推荐）

Via Homebrew (macOS)

通过Homebrew安装（macOS）

Via pnpm

通过pnpm安装

For zsh (add to ~/.zshrc)

针对zsh（添加至~/.zshrc）

For bash (add to ~/.bashrc)

针对bash（添加至~/.bashrc）

For fish (add to ~/.config/fish/config.fish)

针对fish（添加至~/.config/fish/config.fish）

For existing repositories

针对已有仓库

With auto-copy files (recommended)

自动复制文件（推荐）

Rules

规则

Templates

模板

Quick Reference

速查指南

Full Mode (4+ files, complex changes)

完整模式（修改4+文件，复杂变更）

Lite Mode (1-3 files, simple changes)

轻量模式（修改1-3文件，简单变更）

Workflow Modes

工作流模式

Key Principles

核心原则

Artifact System

工件系统

Workflow Flow

工作流流程

Smart Worktree Detection

智能工作树检测

Fast Iteration Loop (Phase 4)

快速迭代循环（第4阶段）

Troubleshooting Quick Reference

故障排查速查

Related Skills

相关技能

References

参考资料

Research Sources

研究来源