swe-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SWE Workflow

SWE 工作流

The idiomatic software-engineer workflow: clarify the idea → spec it → slice it → triage it → ship it. Five stages, each with a dedicated skill and a durable artifact that feeds the next.

标准的软件工程师工作流：明确想法 → 制定规格 → 拆分任务 → 分类处理 → 交付上线。共五个阶段，每个阶段都有专属技能，且会生成可复用的成果物供下一阶段使用。

The workflow

工作流

┌────────────────────── SPEC LAYER (mattpocock) ──────────────────────┐
│                                                                      │
│  0. How is this repo set up?                                         │
│     /setup-matt-pocock-skills ──► AGENTS.md, docs/agents/            │
│              (one-time: tracker, triage labels, doc layout —         │
│               wires this repo's conventions into the chain)          │
│                                                                      │
│  1. What do I want?                                                  │
│     /grill-with-docs ──► CONTEXT.md, ADRs                            │
│              (resolve domain language; capture decisions)            │
│                                                                      │
│  2. What features does this break into?                              │
│     /to-features ──► FEATURES.md                                     │
│              (read CONTEXT.md + ADRs → user-facing features;         │
│               strike through, don't delete, on ship)                 │
│                                                                      │
│  3. What does done look like?                                        │
│     /to-prd ──► PRD (auto-labeled `ready-for-agent`)                 │
│              (Problem / Solution / User Stories /                    │
│               Implementation Decisions / Testing Decisions / Scope)  │
│                                                                      │
│  4. What are the units of work?                                      │
│     /to-issues ──► N tracer-bullet issues                            │
│              (vertical slices, all auto-labeled `ready-for-agent`    │
│               — /triage NOT in the critical path)                    │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

                                  │
                  (Agent grabs ONE `ready-for-agent` issue)
                                  │
                                  ▼
┌────────── EXECUTION LAYER (worktree + planning-with-files) ──────────┐
│                                                                      │
│  5. How do I plan each unit?                                         │
│     Fetch issue (per tracker) ──► worktree + branch + seed files     │
│              (task_plan.md, findings.md, progress.md from AC)        │
│                                                                      │
│     /planning-with-files:plan ──► interview → refine the plan        │
│              (sharpens phases, key questions, decisions to make)     │
│                                                                      │
│  6. How do I ship each unit?                                         │
│     /planning-with-files:start ──► implement → commit                │
│              (outer loop: phases, decisions, errors, findings)       │
│              (apply karpathy-guidelines for code quality)            │
│                                                                      │
│     /tdd ──► red → green → refactor (per code-producing phase)       │
│              (inner loop: one failing test → one minimal fix)        │
│                                                                      │
│     progress.md highlights ──► PR body / closing comment             │
│              (the session log IS the PR narrative — don't rewrite)   │
│                                                                      │
│     Teardown ──► git worktree remove + branch -d if merged           │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

┌────────────────────── SPEC LAYER (mattpocock) ──────────────────────┐
│                                                                      │
│  0. How is this repo set up?                                         │
│     /setup-matt-pocock-skills ──► AGENTS.md, docs/agents/            │
│              (one-time: tracker, triage labels, doc layout —         │
│               wires this repo's conventions into the chain)          │
│                                                                      │
│  1. What do I want?                                                  │
│     /grill-with-docs ──► CONTEXT.md, ADRs                            │
│              (resolve domain language; capture decisions)            │
│                                                                      │
│  2. What features does this break into?                              │
│     /to-features ──► FEATURES.md                                     │
│              (read CONTEXT.md + ADRs → user-facing features;         │
│               strike through, don't delete, on ship)                 │
│                                                                      │
│  3. What does done look like?                                        │
│     /to-prd ──► PRD (auto-labeled `ready-for-agent`)                 │
│              (Problem / Solution / User Stories /                    │
│               Implementation Decisions / Testing Decisions / Scope)  │
│                                                                      │
│  4. What are the units of work?                                      │
│     /to-issues ──► N tracer-bullet issues                            │
│              (vertical slices, all auto-labeled `ready-for-agent`    │
│               — /triage NOT in the critical path)                    │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

                                  │
                  (Agent grabs ONE `ready-for-agent` issue)
                                  │
                                  ▼
┌────────── EXECUTION LAYER (worktree + planning-with-files) ──────────┐
│                                                                      │
│  5. How do I plan each unit?                                         │
│     Fetch issue (per tracker) ──► worktree + branch + seed files     │
│              (task_plan.md, findings.md, progress.md from AC)        │
│                                                                      │
│     /planning-with-files:plan ──► interview → refine the plan        │
│              (sharpens phases, key questions, decisions to make)     │
│                                                                      │
│  6. How do I ship each unit?                                         │
│     /planning-with-files:start ──► implement → commit                │
│              (outer loop: phases, decisions, errors, findings)       │
│              (apply karpathy-guidelines for code quality)            │
│                                                                      │
│     /tdd ──► red → green → refactor (per code-producing phase)       │
│              (inner loop: one failing test → one minimal fix)        │
│                                                                      │
│     progress.md highlights ──► PR body / closing comment             │
│              (the session log IS the PR narrative — don't rewrite)   │
│                                                                      │
│     Teardown ──► git worktree remove + branch -d if merged           │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

Parallel concern:

/triage

并行环节：

/triage

/triage

sits beside the chain, not inside it — a small state machine over the issue tracker (

needs-info

ready-for-agent

ready-for-human

wontfix

). Required for issues filed outside the chain (user bug reports, external contributions, ad-hoc feature requests); redundant for chain-created issues, since

/to-prd

and

/to-issues

auto-label

ready-for-agent

at creation.

See REFERENCE.md for the full state machine and per-state outputs.

/triage

是工作流的并行环节，而非核心流程的一部分——它是针对需求跟踪系统的小型状态机（包含

needs-info

ready-for-agent

ready-for-human

wontfix

状态）。适用于工作流外部提交的需求（用户bug报告、外部贡献、临时功能请求）；对于工作流内创建的需求则无需使用，因为

/to-prd

和

/to-issues

在创建时会自动标记

ready-for-agent

标签。

完整状态机及各状态输出可查看REFERENCE.md。

Design philosophy

设计理念

This is a chain of small skills, not a framework. Three principles guard against drifting into framework opacity:

Own the process. "Process" here means deciding what goes into context at each stage. Every skill in the chain is a markdown file you can read, edit, swap, or skip — there is no opaque orchestrator.
Every artifact is observable. PRDs, issues, AGENT-BRIEFs,
```
task_plan.md
```
,
```
findings.md
```
,
```
progress.md
```
— all human-readable markdown, all
```
cat
```
-able at any point.
Ephemeral state is intentional. Per-issue worktrees and planning files die when the PR ships. Deliberate defense against spec/plan drift accumulating into a "ball of mud" over time.

Operating maxim (Matt Pocock, after surveying ~2000 AI coding course participants on framework dissatisfaction): "a good framework hands a lot of control over to the user and is easy to observe." If a proposed addition reduces either, reject it — even if it's borrowed from a framework that looks useful.

Concrete commitments derived from these principles:

Instructions-only, no scripts. Deterministic operations are documented as instructions the agent runs, not wrapped in scripts. Every script reintroduced would move the chain toward the opacity Matt's surveyed users rejected.
Transparent markdown all the way down. Six chain stages plus
```
/triage
```
as a parallel concern — every link is a markdown skill you can read, edit, or replace without touching code. None of them opaque. The direct test of the operating maxim above.

Engineering-side, by design. The mattpocock toolchain assumes features come from product thinking (user needs, business goals) that lives outside this skill ecosystem. Stage 2 (

/to-features

) is the deliberate seam: features get enumerated here (read from

CONTEXT.md

+ ADRs), but discovered elsewhere — in user interviews, product strategy, sales conversations, whatever your team uses. This toolchain has no opinion on that.

See REFERENCE.md for the comparison with spec-kit / BMAD / GSD.

这是一个小型技能链，而非框架。以下三大原则可避免陷入框架的不透明性：

掌控流程：此处的“流程”指决定每个阶段需要纳入哪些上下文信息。链中的每个技能都是可阅读、编辑、替换或跳过的markdown文件——不存在不透明的编排器。
所有成果物可观测：PRD、需求、AGENT-BRIEFs、
```
task_plan.md
```
、
```
findings.md
```
、
```
progress.md
```
——所有文件均为人类可读的markdown格式，随时可通过
```
cat
```
命令查看。
临时状态是有意设计的：每个需求对应的worktree和规划文件会在PR合并后删除。这是为了防止规格/规划偏差随时间积累成“一团乱麻”。

操作准则（Matt Pocock在调查约2000名AI编码课程参与者对框架的不满点后提出）：*“优秀的框架会将大量控制权交给用户，且易于观测。”*如果某项新增功能会降低控制权或可观测性，即使它来自看似有用的框架，也要拒绝。

基于上述原则的具体承诺：

仅含指令，无脚本：确定性操作以Agent执行的指令形式记录，而非封装在脚本中。每引入一个脚本都会使技能链向Matt调查用户所排斥的不透明性靠拢。
全程使用透明markdown：六个核心阶段加并行环节
```
/triage
```
——每个环节都是markdown技能文件，无需修改代码即可阅读、编辑或替换。所有环节均透明可见，这是对上述操作准则的直接验证。

专为工程侧设计：mattpocock工具链假设功能源自外部的产品思考（用户需求、业务目标），而非本技能生态系统。第2阶段（

/to-features

）是刻意设置的衔接点：功能在此处被枚举（从

CONTEXT.md

+ADRs读取），但发现于外部——用户访谈、产品策略、销售对话，或团队使用的任何其他渠道。本工具链对此不做限制。

与spec-kit / BMAD / GSD的对比可查看REFERENCE.md。

Where to enter the chain

工作流入口选择

Don't always start at stage 1 — jump to where the chain actually breaks.

Entry signal	Start at
Fresh repo, no `## Agent skills` block or `docs/agents/` yet	0
Vocabulary fights, fuzzy terms, no glossary yet	1
Domain understood, features not yet enumerated	2
Feature picked, no PRD yet for this one	3
PRD exists but is one mega-issue	4
Picked a `ready-for-agent` issue, ready to plan	5
`task_plan.md` refined, ready to implement	6
External issue filed by a user, needs classification	(parallel: `/triage` )

无需总是从第1阶段开始——直接跳转到工作流的缺失环节即可。

触发信号	起始阶段
全新仓库，尚无 `## Agent skills` 区块或 `docs/agents/` 目录	0
存在术语歧义、模糊表述，尚无术语表	1
已理解业务领域，尚未枚举功能	2
已选定功能，尚未为此功能编写PRD	3
已有PRD，但仅对应一个大型需求	4
已选定 `ready-for-agent` 需求，准备规划	5
`task_plan.md` 已优化完成，准备实现	6
用户提交外部需求，需要分类处理	（并行环节： `/triage` ）

When is it done?

完成标准

The mirror image of "Where to enter the chain" — four levels of "done", four signals:

Level	Done when	Recorded in
Phase	TDD cycle green + logged	`task_plan.md` checkbox ticked
Issue	All phases ticked, PR merged	tracker status (closed/merged)
Feature	All issues from its PRD merged	`FEATURES.md` strike-through w/ shipped refs
Project	(no native concept — judgment call)	—

A feature's completion is mechanical: walk from the PRD to its child issues (via the parent reference

/to-issues

writes), confirm all closed, then strike through the

FEATURES.md

line:

- [x] ~~user-can-reset-password~~ — ~~A user can reset...~~ (shipped: #42, #43, #44)

Software projects rarely "complete" — features keep getting added. If you need a hard milestone, layer on your tracker's mechanism (

gh milestone

, Linear cycles, release tags) and define "project complete" as that milestone closing. See REFERENCE.md for per-tracker completion queries.

与“工作流入口选择”相对应——有四个层级的“完成”标准及对应信号：

层级	完成条件	记录位置
阶段	TDD循环执行成功并记录	`task_plan.md` 勾选框标记完成
需求	所有阶段均完成，PR已合并	跟踪系统状态（已关闭/已合并）
功能	其PRD对应的所有需求均已合并	`FEATURES.md` 中添加删除线并标注交付引用
项目	（无原生定义——需自行判断）	—

功能的完成状态是机械判定的：从PRD追溯到其子需求（通过

/to-issues

写入的父引用），确认所有需求均已关闭，然后在

FEATURES.md

中为对应行添加删除线：

- [x] ~~user-can-reset-password~~ — ~~A user can reset...~~ (shipped: #42, #43, #44)

软件项目很少真正“完成”——功能会持续新增。如果需要明确的里程碑，可借助跟踪系统的机制（

gh milestone

、Linear周期、发布标签），将“项目完成”定义为该里程碑关闭。各跟踪系统的完成查询方式可查看REFERENCE.md。

Stages 5-6: worktree + planning-with-files

第5-6阶段：worktree + planning-with-files

The skill is instructions-only — there are no scripts. The agent performs each step manually, adapting to the team's issue tracker.

该技能仅含指令——无脚本。Agent需手动执行每个步骤，以适配团队的需求跟踪系统。

Bootstrap

初始化

Pick the tracker. See Tracker selection below.
Fetch the issue per
```
trackers/<name>.md
```
— extract title, body, labels, AGENT-BRIEF.
Derive paths:
- slug = title → lowercase → non-alphanumerics replaced with
```
-
```
  → truncate to 40 chars
- branch =
```
issue-<id>-<slug>
```
  (Linear's
```
TEAM-123
```
  passes through literally)
- worktree =
```
../<repo>-issue-<id>/
```

Create the worktree:

git worktree add ../<repo>-issue-<id> -b issue-<id>-<slug>

cd
in and seed three planning files:

File	Contents
`task_plan.md`	Goal = title; Phases = AC checkboxes. Structured fields only (hook re-injection risk).
`findings.md`	Raw issue body + AGENT-BRIEF pasted verbatim. Safe sink for external content.
`progress.md`	Initial session log entry with bootstrap timestamp.

Invoke
/planning-with-files:plan
to refine seeds via interview (Stage 5). Sharpens phases, surfaces key questions, captures decisions to make.
Invoke
/planning-with-files:start
to execute (Stage 6) — outer loop runs phases;
```
/tdd
```
is the inner loop for code-producing phases. During implementation, refer to
```
/andrej-karpathy-skills:karpathy-guidelines
```
for code quality — surgical changes, simplicity first, no speculative abstractions, surfaced assumptions.

选择跟踪系统：详见下方跟踪系统选择。
获取需求：按照
```
trackers/<name>.md
```
中的说明操作——提取标题、内容、标签、AGENT-BRIEF。
生成路径:
- slug = 标题 → 转为小写 → 非字母数字字符替换为
```
-
```
  → 截断至40字符
- branch =
```
issue-<id>-<slug>
```
  （Linear的
```
TEAM-123
```
  格式直接保留）
- worktree =
```
../<repo>-issue-<id>/
```

创建worktree：

git worktree add ../<repo>-issue-<id> -b issue-<id>-<slug>

进入目录并生成三个规划文件:

文件	内容
`task_plan.md`	目标=标题；阶段=验收标准复选框。仅包含结构化字段（避免提示注入风险）。
`findings.md`	原需求内容+AGENT-BRIEF原文粘贴。作为外部内容的安全存储区。
`progress.md`	初始会话日志条目，包含初始化时间戳。

调用
/planning-with-files:plan
：通过访谈优化初始文件（第5阶段）。细化阶段、梳理关键问题、记录待做决策。
调用
/planning-with-files:start
：执行实现（第6阶段）——外层循环执行各阶段；
```
/tdd
```
是代码生成阶段的内层循环。实现过程中，参考
```
/andrej-karpathy-skills:karpathy-guidelines
```
保证代码质量——精准修改、优先简洁、避免过度抽象、明确假设。

Tracker selection

跟踪系统选择

Priority order:

$SWE_WORKFLOW_TRACKER
env var (explicit override)
tracker=<name>
line in
```
.swe-workflow.conf
```
at the repo root
Auto-detect from project signals:
- ```
.scratch/
```
  directory →
```
local-markdown
```
  (mattpocock's
```
.scratch/<feature>/
```
  convention)
- github remote +
```
gh
```
  installed →
```
github
```
- gitlab remote +
```
glab
```
  installed →
```
gitlab
```
- ```
.linear/
```
  directory →
```
linear
```
- ```
$MULTICA_WORKSPACE_ID
```
  set →
```
multica
```
  (no project-level signal — Multica config is user-level)
Still ambiguous → ask the user.

Per-tracker fetch commands and conventions:

trackers/<name>.md

. To add a new tracker, write a new doc following the same shape — nothing else changes.

优先级顺序:

**
```
$SWE_WORKFLOW_TRACKER
```
**环境变量（显式覆盖）
仓库根目录
.swe-workflow.conf
中的
tracker=<name>
行
根据项目信号自动检测:
- 存在
```
.scratch/
```
  目录 →
```
local-markdown
```
  （mattpocock的
```
.scratch/<feature>/
```
  约定）
- GitHub远程仓库且已安装
```
gh
```
  →
```
github
```
- GitLab远程仓库且已安装
```
glab
```
  →
```
gitlab
```
- 存在
```
.linear/
```
  目录 →
```
linear
```
- 已设置
```
$MULTICA_WORKSPACE_ID
```
  →
```
multica
```
  （无项目级信号——Multica配置为用户级）
仍无法确定 → 询问用户。

各跟踪系统的获取命令及约定：

trackers/<name>.md

。如需添加新跟踪系统，只需按照相同格式编写新文档——无需修改其他内容。

Inner loop:

/tdd

for code-producing phases

内层循环：代码生成阶段的

/tdd

/planning-with-files:start

is the outer loop (phases, state, errors);

/tdd

is the inner loop (one failing test → one minimal fix). For each phase in

task_plan.md

that produces testable code:

Mark phase in_progress  →  /tdd (red → green → refactor)  →  log to progress.md  →  Mark phase complete

Not every phase needs

/tdd

— exploration, config tweaks, and infra changes skip it. See REFERENCE.md for the full nuances (multiple cycles per phase, decision/error capture, when

/tdd

's own planning step duplicates vs. complements the issue-level plan).

/planning-with-files:start

是外层循环（阶段、状态、错误）；

/tdd

是内层循环（一个失败测试 → 一个最小修复）。对于

task_plan.md

中所有生成可测试代码的阶段：

标记阶段为in_progress  →  /tdd（红 → 绿 → 重构）  → 记录到progress.md  → 标记阶段为complete

并非所有阶段都需要

/tdd

——探索、配置调整、基础设施变更可跳过。完整细节（每个阶段多轮循环、决策/错误记录、

/tdd

自身规划步骤与需求级规划的重复或互补场景）可查看REFERENCE.md。

Teardown (after PR merges)

清理（PR合并后）

From the main checkout (NOT inside the worktree):

bash

undefined

从主仓库目录（NOT worktree内部）执行：

bash

undefined

Verify no uncommitted changes

验证无未提交变更

git -C ../<repo>-issue-<id> status --porcelain

Remove worktree

删除worktree

git worktree remove ../<repo>-issue-<id>

Delete branch only if merged into the default branch

仅当分支已合并到默认分支时删除

default_branch=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@') git branch --merged "$default_branch"
| grep -qE "^[[:space:]]**?[[:space:]]*issue-<id>-<slug>$"
&& git branch -d "issue-<id>-<slug>"

undefined

undefined

Critical handoff rules

关键交接规则

PRD uses the glossary from stage 1. If
```
to-prd
```
introduces terms that conflict with
```
CONTEXT.md
```
, loop back to
```
/grill-with-docs
```
.
Issues are tracer bullets, not horizontal layers. Each is a thin vertical slice (schema → API → UI → tests). "Backend issue" + "frontend issue" is a smell — re-slice.
Only
ready-for-agent
issues enter execution.
```
/to-issues
```
auto-applies the label on chain-created issues;
```
/triage
```
applies it to external issues (user reports, etc.). Either way, stage 5 reads from the label, not the source.
One issue = one worktree = one
task_plan.md
. Filesystem isolation for parallel AFK agents. No exceptions.
Strike through, don't delete. When a feature ships, strike it through in
```
FEATURES.md
```
with a shipped reference — never delete. Preserves institutional memory; prevents quiet scope drift.

PRD使用第1阶段的术语表。如果
```
to-prd
```
引入的术语与
```
CONTEXT.md
```
冲突，需回到
```
/grill-with-docs
```
环节。
需求是垂直切片，而非横向分层。每个需求都是薄的垂直切片（ schema → API → UI → 测试）。“后端需求”+“前端需求”是不良实践——需重新拆分。
仅
ready-for-agent
需求可进入执行阶段。
```
/to-issues
```
会为工作流内创建的需求自动添加该标签；
```
/triage
```
会为外部需求（用户报告等）添加该标签。无论哪种情况，第5阶段均读取该标签，而非需求来源。
一个需求 = 一个worktree = 一个
task_plan.md
。通过文件系统隔离实现多Agent并行工作。无例外。
添加删除线，而非删除内容。功能交付后，在
```
FEATURES.md
```
中为对应行添加删除线并标注交付引用——切勿删除。保留团队记忆；避免隐性范围偏差。

Don't double-track

避免重复跟踪

Lives in…	Don't also put in…
PRD (immutable arch decisions)	`task_plan.md` (would rot; the spec is authoritative)
AGENT-BRIEF (durable contract)	`task_plan.md` (copy only AC + key interfaces; raw brief goes in `findings.md` )
`task_plan.md` (execution-time decisions, errors hit)	The issue (don't litter the spec with build noise)
`progress.md` (session log)	A hand-written PR summary (the log IS the summary)

存储位置…	请勿同时存入…
PRD（不可变架构决策）	`task_plan.md` （会失效；规格文件具有权威性）
AGENT-BRIEF（持久化约定）	`task_plan.md` （仅复制验收标准+关键接口；原始约定存入 `findings.md` ）
`task_plan.md` （执行阶段决策、遇到的错误）	需求（勿在规格文件中混入构建噪音）
`progress.md` （会话日志）	手写PR摘要（日志即为摘要）

Security boundary

安全边界

planning-with-files

re-injects

task_plan.md

into context on every tool call. Any text in

task_plan.md

is an amplified prompt-injection target.

Raw issue bodies, fetched docs, web content →
```
findings.md
```
only.
```
task_plan.md
```
gets only structured fields the executor wrote (Goal, Phases from AC, Decisions, Errors).

The bootstrap procedure (Stages 5-6) enforces this split.

planning-with-files

会在每次工具调用时重新注入

task_plan.md

到上下文中。

task_plan.md

中的任何文本都是潜在的提示注入目标。

原始需求内容、获取的文档、网页内容 → 仅存入
```
findings.md
```
。
```
task_plan.md
```
仅包含执行者编写的结构化字段（目标、验收标准中的阶段、决策、错误）。

初始化流程（第5-6阶段）强制遵循此划分规则。

When to skip this skill

何时跳过该技能

Single-file edits (no spec, no plan needed)
Bug fixes where the AGENT-BRIEF is one paragraph — just do it, skip stage 5 bootstrap
Exploration / prototypes — use the
```
prototype
```
skill instead

单文件编辑（无需规格、无需规划）
AGENT-BRIEF仅为一段文字的bug修复——直接处理，跳过第5阶段初始化
探索/原型开发——使用
```
prototype
```
技能替代