sugar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phased Software Engineering Execution

分阶段软件工程执行流程

Task

任务

$ARGUMENTS

Reference

参考

Subagent execution follows the Ralph pattern. Each phase workspace is a self-contained Ralph environment:

CLAUDE.md

(agent instructions),

prd.json

(story state machine),

progress.txt

(learning persistence). Subagents are autonomous — they read their workspace instructions and execute independently.

The Sugar library (

src/lib/

) is the source of truth for all execution logic. Skills delegate to

sugar

CLI commands for workspace management, story state, consensus, and pattern propagation. Do not embed procedural bash scripts or Python one-liners — use Sugar CLI instead.

子代理（subagent）的执行遵循**Ralph**模式。每个阶段的工作区都是一个独立的Ralph环境：

CLAUDE.md

（代理指令）、

prd.json

（故事状态机）、

progress.txt

（学习持久化文件）。子代理具备自主性——它们读取工作区指令并独立执行。

Sugar库（

src/lib/

）是所有执行逻辑的唯一可信来源。技能需委托给

sugar

CLI命令进行工作区管理、故事状态维护、一致性校验和模式传播。请勿嵌入过程式bash脚本或Python单行代码——请使用Sugar CLI替代。

Prompt reinforcement

提示强化

Use prompt repetition at every decision boundary: state the task, provide context, give the instruction, restate context briefly, repeat the instruction. Apply at skill level (restate

$ARGUMENTS

before each phase), subagent level (each workspace CLAUDE.md repeats the task), and per-story (restate acceptance criteria before implementing).

在每个决策节点使用提示重复：陈述任务、提供上下文、给出指令、简要重述上下文、重复指令。在技能层面（每个阶段前重述

$ARGUMENTS

）、子代理层面（每个工作区的CLAUDE.md重复任务）以及每个故事层面（实现前重述验收标准）应用此规则。

Core behavior

核心行为

Execute in strict phases. Never move to the next phase without explicit user approval.

Before every phase, restate: "The original task is: $ARGUMENTS. This phase's goal is: [phase goal]."

按照严格的阶段执行。未获得用户明确批准，绝不进入下一阶段。

每个阶段开始前，重述："原始任务为：$ARGUMENTS。本阶段目标为：[阶段目标]。"

Phase 1 — Planning

阶段1 — 规划

Goal

目标

Analyze the task and produce a complete execution plan. Do not implement any code.

Restate: The original task is

$ARGUMENTS

. This phase produces

plan.md

and

todo.md

only.

分析任务并生成完整的执行计划。请勿实现任何代码。

重述：原始任务为

$ARGUMENTS

。本阶段仅生成

plan.md

和

todo.md

文件。

Actions

操作

Use the

/prd

skill approach: analyze the task, ask clarifying questions if ambiguous, then produce structured requirements.

Create

plan.md

at the repo root containing:

objective, scope, assumptions, constraints, risks
dependency map — which parts depend on other parts
architecture / refactor / testing strategy as relevant
execution phases with explicit dependency annotations
blockers

Create

todo.md

at the repo root containing:

small, actionable, idempotent tasks grouped by phase
checkbox progress tracking (
```
- [ ]
```
)
dependency annotations per task
completion criteria per phase

使用

/prd

技能方法：分析任务，若存在歧义则提出澄清问题，然后生成结构化需求。

在仓库根目录创建

plan.md

文件，包含：

目标、范围、假设、约束、风险
依赖关系图——各部分之间的依赖关系
相关的架构/重构/测试策略
带有明确依赖标注的执行阶段
阻塞点

在仓库根目录创建

todo.md

文件，包含：

按阶段分组的小型、可执行、幂等任务
复选框进度跟踪（
```
- [ ]
```
）
每个任务的依赖标注
每个阶段的完成标准

Rules

规则

Do not implement anything or create branches
Stop after Phase 1 and wait for user approval

请勿实现任何内容或创建分支
完成阶段1后停止，等待用户批准

Phase 2 — Workspace and branch setup

阶段2 — 工作区与分支设置

Goal

目标

Create an isolated Ralph workspace for each execution phase.

Restate: The original task is

$ARGUMENTS

. This phase creates one git worktree per phase, each pre-loaded with the Ralph agent structure.

为每个执行阶段创建独立的Ralph工作区。

重述：原始任务为

$ARGUMENTS

。本阶段为每个阶段创建一个git工作树，每个工作树预加载Ralph代理结构。

Preconditions

前置条件

Only start after explicit user approval.

仅在获得用户明确批准后启动。

Actions

操作

Use the Sugar CLI to create workspaces:

bash

undefined

使用Sugar CLI创建工作区：

bash

undefined

Create workspace for each phase

为每个阶段创建工作区

sugar workspace create <phase-name>

List created workspaces

列出已创建的工作区

sugar workspace list


Branch naming: `phase-a-<scope>`, `phase-b-<scope>`, etc.

sugar workspace list


分支命名规则：`phase-a-<scope>`、`phase-b-<scope>`等。

Rules

规则

One worktree per phase, one branch per phase
Do not start implementation unless user approves Phase 3
Document setup problems in
```
plan.md
```

每个阶段对应一个工作树和一个分支
除非用户批准阶段3，否则请勿开始实现
在
```
plan.md
```
中记录设置过程中出现的问题

Phase 3 — Dependency analysis, PRD generation, and parallel implementation

阶段3 — 依赖分析、PRD生成与并行实现

Preconditions

前置条件

Only start after explicit user approval.

Restate: The original task is

$ARGUMENTS

. This phase analyzes dependencies, generates Ralph workspaces with prd.json and CLAUDE.md per phase, then launches all independent phases as parallel subagents.

Sub-phases: 3a → 3b → 3c.

仅在获得用户明确批准后启动。

重述：原始任务为

$ARGUMENTS

。本阶段分析依赖关系，为每个阶段生成带有prd.json和CLAUDE.md的Ralph工作区，然后将所有独立阶段作为并行子代理启动。

子阶段：3a → 3b → 3c。

Phase 3a — Dependency analysis

阶段3a — 依赖分析

Read

plan.md

thoroughly. For each phase determine:

Produces: artifacts, files, APIs, types, state changes
Consumes: what it needs from other phases
Hard dependencies: must complete before this starts
Soft dependencies: helpful but not blocking
Independence: zero overlap with other phases

Build the dependency graph. Identify parallel groups, sequential chains, and the critical path.

仔细阅读

plan.md

。为每个阶段确定：

产出：工件、文件、API、类型、状态变更
消耗：需要从其他阶段获取的内容
强依赖：必须在本阶段开始前完成的任务
弱依赖：有帮助但不阻塞的任务
独立性：与其他阶段无重叠

构建依赖关系图。识别并行组、顺序链和关键路径。

Phase 3b — Generate execution.md, prd.json, and CLAUDE.md per workspace

阶段3b — 为每个工作区生成execution.md、prd.json和CLAUDE.md

The Sugar library generates all workspace files. Use the

Orchestrator

class or CLI commands:

bash

undefined

Sugar库负责生成所有工作区文件。使用

Orchestrator

类或CLI命令：

bash

undefined

Initialize config if not present

若配置不存在则初始化

sugar config init

The orchestrator generates: execution.md, prd.json, CLAUDE.md, VERIFY.md, ralph-loop.sh per workspace

编排器会生成：execution.md、prd.json、CLAUDE.md、VERIFY.md、ralph-loop.sh（每个工作区一份）


For each workspace, the library generates:
- **`prd.json`** — Ralph-format user stories with consensus state machine
- **`CLAUDE.md`** — Agent instructions with iron laws, quality protocol, red flags
- **`VERIFY.md`** — Verifier agent instructions with vote format
- **`ralph-loop.sh`** — Iteration engine that spawns fresh agents per story
- **`execution.md`** at repo root — dependency graph, parallel groups, model strategy

**Story rules:** completable in one pass, ordered by dependency (schema → backend → UI), verifiable criteria, always include "Typecheck passes".


对于每个工作区，库会生成：
- **`prd.json`** — 带有一致性状态机的Ralph格式用户故事
- **`CLAUDE.md`** — 包含铁律、质量协议、警示信号的代理指令
- **`VERIFY.md`** — 带有投票格式的验证器代理指令
- **`ralph-loop.sh`** — 为每个故事生成新代理实例的迭代引擎
- **`execution.md`**（仓库根目录）— 依赖关系图、并行组、模型策略

**故事规则**：单次迭代可完成，按依赖顺序排列（ schema → 后端 → UI），具备可验证标准，始终包含"类型检查通过"项。

Rules

规则

Every workspace must have:

prd.json

progress.txt

CLAUDE.md

ralph-loop.sh

VERIFY.md

Do not proceed to 3c until all workspaces are fully set up

Validate each

prd.json

sugar validate <workspace>/prd.json

每个工作区必须包含：

prd.json

、

progress.txt

、

CLAUDE.md

、

ralph-loop.sh

、

VERIFY.md

所有工作区完全设置完成后，才可进入3c阶段

验证每个

prd.json

：

sugar validate <workspace>/prd.json

Phase 3c — Parallel execution via ralph-loop.sh

阶段3c — 通过ralph-loop.sh进行并行执行

Goal

目标

Launch the Ralph iteration loop for each phase in parallel.

为每个阶段启动Ralph迭代循环并并行运行。

How iteration works

迭代工作原理

ralph-loop.sh (the loop — runs in bash)
  ├── Iteration 1: claude < CLAUDE.md → implements US-001 → exits
  ├── Iteration 2: claude < CLAUDE.md → implements US-002 → exits
  ├── Iteration 3: claude < CLAUDE.md → implements US-003 → outputs PHASE_COMPLETE
  └── Loop exits successfully

Each iteration is a fresh agent instance with clean context. Memory persists via:

prd.json

— which stories are done (

status: "passed"/"pending"/"rejected"

)

```
progress.txt
```
— learnings and codebase patterns
git history — all committed code

ralph-loop.sh（循环脚本——在bash中运行）
  ├── 迭代1：claude < CLAUDE.md → 实现US-001 → 退出
  ├── 迭代2：claude < CLAUDE.md → 实现US-002 → 退出
  ├── 迭代3：claude < CLAUDE.md → 实现US-003 → 输出PHASE_COMPLETE
  └── 循环成功退出

每次迭代都是一个全新的代理实例，上下文干净。记忆通过以下方式持久化：

prd.json

— 标记哪些故事已完成（

status: "passed"/"pending"/"rejected"

）

```
progress.txt
```
— 学习成果和代码库模式
git历史 — 所有已提交的代码

Execution

执行

execution.md

group ordering. Launch ralph loops per group:

bash

undefined

遵循

execution.md

中的组顺序。按组启动ralph循环：

bash

undefined

Launch all independent phases in parallel

并行启动所有独立阶段

/tmp/<repo>-phases/phase-a/ralph-loop.sh 20 sonnet & /tmp/<repo>-phases/phase-b/ralph-loop.sh 20 sonnet & wait

Propagate patterns between groups

在组之间传播模式

sugar propagate-patterns --base /tmp/<repo>-phases

Launch next group

启动下一组

/tmp/<repo>-phases/phase-c/ralph-loop.sh 20 sonnet & wait


The `ralph-loop.sh` uses Sugar CLI for state management:
- `sugar pick-story` — get next story
- `sugar story-update` — update story status in prd.json
- `sugar snapshot` — create git snapshot tag before each attempt

/tmp/<repo>-phases/phase-c/ralph-loop.sh 20 sonnet & wait


`ralph-loop.sh`使用Sugar CLI进行状态管理：
- `sugar pick-story` — 获取下一个故事
- `sugar story-update` — 更新prd.json中的故事状态
- `sugar snapshot` — 每次尝试前创建git快照标签

Model selection per phase

各阶段模型选择

Sonnet (default): Well-scoped implementation tasks
Haiku: Mechanical tasks — config changes, boilerplate
Opus: Complex architectural decisions, ambiguous requirements

Auto-escalates to Opus on 2+ consecutive failures.

Sonnet（默认）：范围明确的实现任务
Haiku：机械性任务——配置变更、模板代码
Opus：复杂架构决策、模糊需求

连续失败2次及以上时自动升级为Opus。

Completion tracking

完成跟踪

Phase complete when
```
ralph-loop.sh
```
exits 0
After each group:
```
sugar propagate-patterns
```
to extract and inject patterns
Monitor progress:
```
sugar status-all /tmp/<repo>-phases
```

当
```
ralph-loop.sh
```
以0状态退出时，阶段完成
每组完成后：使用
```
sugar propagate-patterns
```
提取并注入模式
监控进度：
```
sugar status-all /tmp/<repo>-phases
```

Rules

规则

Never launch a dependent phase before prerequisites are confirmed complete
Propagate codebase patterns between groups
One story per commit, all commits must pass quality checks

确认前置阶段完成前，绝不启动依赖阶段
在组之间传播代码库模式
每个故事对应一次提交，所有提交必须通过质量检查

Phase 4 — Merge

阶段4 — 合并

Goal

目标

Safely integrate all completed phase branches.

Restate: The original task is

$ARGUMENTS

. All phases complete. Merge in dependency order.

安全整合所有已完成阶段的分支。

重述：原始任务为

$ARGUMENTS

。所有阶段已完成。按依赖顺序合并。

Preconditions

前置条件

Only start after explicit user approval.

仅在获得用户明确批准后启动。

Actions

操作

bash

undefined

bash

undefined

View workspace status first

先查看工作区状态

sugar status-all /tmp/<repo>-phases


Create `merge_order.md` at repo root with:
- merge order aligned with dependency graph (foundations first)
- rationale for ordering
- expected conflict areas
- conflict resolution notes
- validation steps after each merge

**Automatic merge:**
- Merge in documented order
- Resolve conflicts using best engineering judgment
- Validate after each merge: run quality checks
- Update `merge_order.md` with actual conflict notes

sugar status-all /tmp/<repo>-phases


在仓库根目录创建`merge_order.md`文件，包含：
- 与依赖关系图一致的合并顺序（基础部分优先）
- 顺序合理性说明
- 预期冲突区域
- 冲突解决说明
- 每次合并后的验证步骤

**自动合并**：
- 按文档记录的顺序合并
- 使用最佳工程判断解决冲突
- 每次合并后验证：运行质量检查
- 在`merge_order.md`中更新实际冲突记录

Post-merge validation

合并后验证

Phase 4 is not complete until the final merged result passes all checks.

只有当最终合并结果通过所有检查后，阶段4才完成。

Cleanup

清理

bash

sugar workspace cleanup

bash

sugar workspace cleanup

Iron Laws

铁律

Three inviolable rules enforced in every workspace:

ONE STORY per iteration — no "while I'm here" additions
NEVER COMMIT BROKEN code — every commit must pass all quality checks
READ PROGRESS.TXT FIRST — check codebase patterns before writing

每个工作区都必须遵守的三条不可违反规则：

每次迭代仅处理一个故事 — 禁止添加“顺手做的”内容
绝不提交损坏的代码 — 每次提交必须通过所有质量检查
先阅读PROGRESS.TXT — 编写代码前先查看代码库模式

Red Flags — If You Catch Yourself Thinking:

警示信号——如果你有以下想法：

Thought	Reality
"I'll just implement two quick stories in one iteration"	ONE story per iteration. The loop handles iteration. No exceptions.
"The tests mostly pass, I'll commit and fix later"	ALL commits must pass quality checks. Broken commits poison every future iteration.
"This dependency isn't really needed, I'll skip it"	The dependency graph exists for a reason. Never start dependent work before prerequisites complete.
"I know what changed, I don't need to read progress.txt"	Progress.txt IS your memory. You have NO context without it. Read it FIRST.
"This is a trivial change, I don't need to run checks"	Every commit gets checked. No exceptions. The one you skip is the one that breaks everything.
"I'll refactor this while I'm here"	Stay in scope. Implement the story. Nothing more.

想法	实际要求
"我要在一次迭代中快速实现两个故事"	每次迭代仅处理一个故事。循环会处理迭代流程。无例外。
"测试大部分通过，我先提交之后再修复"	所有提交必须通过质量检查。损坏的提交会影响后续所有迭代。
"这个依赖其实不需要，我跳过它"	依赖关系图存在是有原因的。前置任务完成前，绝不启动依赖工作。
"我知道哪些内容变更了，不需要读progress.txt"	Progress.txt是你的记忆来源。没有它你就没有上下文。必须先阅读。
"这是个小改动，不需要运行检查"	每次提交都要检查。无例外。你跳过的那次检查往往就是导致崩溃的原因。
"我顺便重构一下这里"	保持在范围内。只实现故事内容。不做额外操作。

How to interpret user requests

如何解读用户请求

User says	Start from
Planning only / no qualifier	Phase 1
Planning is approved	Phase 2
Setup is done	Phase 3 (3a → 3b → 3c)
PRDs exist, ready to implement	Phase 3c
All branches done, wants merge	Phase 4
Testing only	Phase 1 (testing strategy), then normal flow

用户表述	起始阶段
仅规划 / 无其他限定	阶段1
规划已批准	阶段2
已完成设置	阶段3（3a → 3b → 3c）
PRD已存在，准备实现	阶段3c
所有分支已完成，需要合并	阶段4
仅测试	阶段1（制定测试策略），然后按正常流程执行

Execution rules

执行规则

Source of truth

可信来源

Before Phase 3c:
```
todo.md
```
During Phase 3c: each workspace's
```
prd.json
```
After each phase completes: sync back to
```
todo.md
```

阶段3c之前：
```
todo.md
```
阶段3c期间：每个工作区的
```
prd.json
```
每个阶段完成后：同步更新至
```
todo.md
```

Commits

提交规范

One per story:
```
feat: [Story ID] - [Story Title]
```
Must pass quality checks
Never bundle unrelated changes

每个故事对应一次提交：
```
feat: [故事ID] - [故事标题]
```
必须通过质量检查
绝不捆绑无关变更

General

通用规则

Never skip phases or continue without approval
Keep all tracking files current
Document assumptions and blockers explicitly
Propagate codebase patterns between groups

绝不跳过阶段或未获批准就继续执行
保持所有跟踪文件更新
明确记录假设和阻塞点
在组之间传播代码库模式

Managed files

管理文件

File	Location	Created in
`plan.md`	repo root	Phase 1
`todo.md`	repo root	Phase 1
`execution.md`	repo root	Phase 3b
`prd.json`	each worktree	Phase 3b
`progress.txt`	each worktree	Phase 2
`CLAUDE.md`	each worktree	Phase 3b
`ralph-loop.sh`	each worktree	Phase 3b
`VERIFY.md`	each worktree	Phase 3b
`patterns.json`	repo root	Phase 3c (between groups)
`merge_order.md`	repo root	Phase 4

The first deliverable is always Phase 1 planning only, unless the user explicitly states that a later phase is already approved.

Restate: Given the task

$ARGUMENTS

— start with Phase 1. Produce

plan.md

and

todo.md

. Stop and wait for approval.

文件	位置	创建阶段
`plan.md`	仓库根目录	阶段1
`todo.md`	仓库根目录	阶段1
`execution.md`	仓库根目录	阶段3b
`prd.json`	每个工作树	阶段3b
`progress.txt`	每个工作树	阶段2
`CLAUDE.md`	每个工作树	阶段3b
`ralph-loop.sh`	每个工作树	阶段3b
`VERIFY.md`	每个工作树	阶段3b
`patterns.json`	仓库根目录	阶段3c（组之间）
`merge_order.md`	仓库根目录	阶段4

除非用户明确说明已批准后续阶段，否则首个交付成果始终仅为阶段1的规划内容。

重述：给定任务

$ARGUMENTS

— 从阶段1开始。生成

plan.md

和

todo.md

。停止并等待批准。