flow-next

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Flow-Next Task Management

Flow-Next 任务管理

Quick task operations in

.flow/

. For planning features use

/flow-next:plan

, for executing use

/flow-next:work

在

.flow/

中快速执行任务操作。如需规划功能，请使用

/flow-next:plan

；如需执行任务，请使用

/flow-next:work

。

Setup

安装配置

CRITICAL: flowctl is BUNDLED — NOT installed globally.

which flowctl

will fail (expected). Always use:

bash

FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"

Then run commands with

$FLOWCTL <command>

Discover all commands/options:

bash

$FLOWCTL --help
$FLOWCTL <command> --help   # e.g., $FLOWCTL task --help

**重要提示：flowctl 是捆绑式的——并非全局安装。**执行

which flowctl

会失败（此为预期情况）。请始终使用以下方式调用：

bash

FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"

随后使用

$FLOWCTL <command>

运行命令。

查看所有命令/选项：

bash

$FLOWCTL --help
$FLOWCTL <command> --help   # 例如：$FLOWCTL task --help

Quick Reference

快速参考

bash

undefined

bash

undefined

Check if .flow exists

检查 .flow 是否存在

$FLOWCTL detect --json

Initialize (if needed)

初始化（如需要）

$FLOWCTL init --json

List everything (epics + tasks grouped)

列出所有内容（Epic + 分组的任务）

$FLOWCTL list --json

List all epics

列出所有Epic

$FLOWCTL epics --json

List all tasks (or filter by epic/status)

列出所有任务（或按Epic/状态筛选）

$FLOWCTL tasks --json $FLOWCTL tasks --epic fn-1-add-oauth --json $FLOWCTL tasks --status todo --json

View epic with all tasks

查看包含所有任务的Epic

$FLOWCTL show fn-1-add-oauth --json $FLOWCTL cat fn-1-add-oauth # Spec markdown

$FLOWCTL show fn-1-add-oauth --json $FLOWCTL cat fn-1-add-oauth # 查看Markdown格式的规格说明

View single task

查看单个任务

$FLOWCTL show fn-1-add-oauth.2 --json $FLOWCTL cat fn-1-add-oauth.2 # Task spec

$FLOWCTL show fn-1-add-oauth.2 --json $FLOWCTL cat fn-1-add-oauth.2 # 查看任务规格说明

What's ready to work on?

哪些任务可开始处理？

$FLOWCTL ready --epic fn-1-add-oauth --json

Create task under existing epic

在现有Epic下创建任务

$FLOWCTL task create --epic fn-1-add-oauth --title "Fix bug X" --json

$FLOWCTL task create --epic fn-1-add-oauth --title "修复Bug X" --json

Set task description and acceptance (combined, fewer writes)

设置任务描述与验收标准（合并操作，减少写入次数）

$FLOWCTL task set-spec fn-1-add-oauth.2 --description /tmp/desc.md --acceptance /tmp/accept.md --json

Or use stdin with heredoc (no temp file):

或使用 heredoc 从标准输入读取（无需临时文件）：

$FLOWCTL task set-description fn-1-add-oauth.2 --file - --json <<'EOF' Description here EOF

$FLOWCTL task set-description fn-1-add-oauth.2 --file - --json <<'EOF' 描述内容 EOF

Start working on task

开始处理任务

$FLOWCTL start fn-1-add-oauth.2 --json

Mark task done

标记任务完成

echo "What was done" > /tmp/summary.md echo '{"commits":["abc123"],"tests":["npm test"],"prs":[]}' > /tmp/evidence.json $FLOWCTL done fn-1-add-oauth.2 --summary-file /tmp/summary.md --evidence-json /tmp/evidence.json --json

echo "已完成的工作内容" > /tmp/summary.md echo '{"commits":["abc123"],"tests":["npm test"],"prs":[]}' > /tmp/evidence.json $FLOWCTL done fn-1-add-oauth.2 --summary-file /tmp/summary.md --evidence-json /tmp/evidence.json --json

Validate structure

验证结构

$FLOWCTL validate --epic fn-1-add-oauth --json $FLOWCTL validate --all --json

undefined

$FLOWCTL validate --epic fn-1-add-oauth --json $FLOWCTL validate --all --json

undefined

Common Patterns

常见使用场景

"Add a task for X"

"为X添加任务"

Find relevant epic:

bash

# List all epics
$FLOWCTL epics --json

# Or show a specific epic to check its scope
$FLOWCTL show fn-1 --json

Create task:

bash

$FLOWCTL task create --epic fn-N --title "Short title" --json

Add description + acceptance (combined):

bash

cat > /tmp/desc.md << 'EOF'
**Bug/Feature:** Brief description

**Details:**
- Point 1
- Point 2
EOF
cat > /tmp/accept.md << 'EOF'
- [ ] Criterion 1
- [ ] Criterion 2
EOF
$FLOWCTL task set-spec fn-N.M --description /tmp/desc.md --acceptance /tmp/accept.md --json

找到相关的Epic：

bash

# 列出所有Epic
$FLOWCTL epics --json

# 或查看特定Epic以确认其范围
$FLOWCTL show fn-1 --json

创建任务：

bash

$FLOWCTL task create --epic fn-N --title "简短标题" --json

添加描述与验收标准（合并操作）：

bash

cat > /tmp/desc.md << 'EOF'
**Bug/功能：** 简要描述

**详细信息：**
- 要点1
- 要点2
EOF
cat > /tmp/accept.md << 'EOF'
- [ ] 验收标准1
- [ ] 验收标准2
EOF
$FLOWCTL task set-spec fn-N.M --description /tmp/desc.md --acceptance /tmp/accept.md --json

"What tasks are there?"

"有哪些任务？"

bash

undefined

bash

undefined

All epics

所有Epic

$FLOWCTL epics --json

All tasks

所有任务

$FLOWCTL tasks --json

Tasks for specific epic

特定Epic下的任务

$FLOWCTL tasks --epic fn-1-add-oauth --json

Ready tasks for an epic

特定Epic下可开始处理的任务

$FLOWCTL ready --epic fn-1-add-oauth --json

undefined

$FLOWCTL ready --epic fn-1-add-oauth --json

undefined

"Show me task X"

"显示任务X"

bash

$FLOWCTL show fn-1-add-oauth.2 --json   # Metadata
$FLOWCTL cat fn-1-add-oauth.2           # Full spec

(Legacy

fn-1.2

fn-1-xxx.2

still works.)

bash

$FLOWCTL show fn-1-add-oauth.2 --json   # 元数据
$FLOWCTL cat fn-1-add-oauth.2           # 完整规格说明

（旧格式

fn-1.2

fn-N-xxx

（随机3字符后缀）仍受支持。）

Create new epic (rare - usually via /flow-next:plan)

创建新的Epic（较少使用——通常通过 /flow-next:plan 创建）

bash

$FLOWCTL epic create --title "Epic title" --json

bash

$FLOWCTL epic create --title "Epic标题" --json

Returns: {"success": true, "id": "fn-N-epic-title", ...}

返回结果：{"success": true, "id": "fn-N-epic-title", ...}

undefined

undefined

ID Format

ID格式

Epic:
```
fn-N-slug
```
where slug is derived from title (e.g.,
```
fn-1-add-oauth
```
,
```
fn-2-fix-login-bug
```
)

Task:

fn-N-slug.M

(e.g.,

fn-1-add-oauth.1

fn-2-fix-login-bug.2

)

Legacy formats

fn-N

and

fn-N-xxx

(random 3-char suffix) are still supported.

Epic：
```
fn-N-slug
```
，其中slug由标题派生（例如
```
fn-1-add-oauth
```
、
```
fn-2-fix-login-bug
```
）

任务：

fn-N-slug.M

（例如

fn-1-add-oauth.1

、

fn-2-fix-login-bug.2

）

旧格式

fn-N

和

fn-N-xxx

（随机3字符后缀）仍受支持。

Notes

注意事项

Run
```
$FLOWCTL --help
```
to discover all commands and options
All writes go through flowctl (don't edit JSON/MD files directly)
```
--json
```
flag gives machine-readable output
For complex planning/execution, use
```
/flow-next:plan
```
and
```
/flow-next:work
```

运行
```
$FLOWCTL --help
```
以查看所有命令和选项
所有写入操作请通过flowctl执行（请勿直接编辑JSON/MD文件）
```
--json
```
参数会返回机器可读的输出
如需复杂的规划/执行操作，请使用
```
/flow-next:plan
```
和
```
/flow-next:work
```