Back to Details

state-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

State Management Skill

状态管理Skill

This skill provides techniques for managing workflow state through simplified, consolidated markdown files. The refactored structure uses just two file patterns: a single 
FLOW.md
at project level and one 
ITEM-XXX.md
per work item.
该Skill提供了通过简化、整合的Markdown文件管理工作流状态的技术。重构后的结构仅使用两种文件模式：项目级的单个
FLOW.md
文件和每个工作项对应的一个
ITEM-XXX.md
文件。

Core Principles

核心原则

  1. Minimal Footprint: Only two file patterns instead of 9+
  2. Single Source of Truth: FLOW.md contains backlog + project context, ITEM-XXX.md contains everything about one item
  3. Human Readable: All state in plain markdown, easy to edit
  4. Checkpoint Recovery: State enables resumption from any interruption
  5. Context Budget Awareness: Track and report context usage
  1. 最小化开销：仅使用2种文件模式，替代原来的9种以上
  2. 单一数据源：FLOW.md包含待办事项和项目上下文，ITEM-XXX.md包含单个工作项的所有信息
  3. 易读性：所有状态均采用纯Markdown格式，便于编辑
  4. 检查点恢复：状态支持从任何中断点恢复工作
  5. 上下文预算感知：跟踪并报告上下文使用情况

Directory Structure

目录结构

.flow/
├── FLOW.md           # Project state + backlog (single file)
└── items/
    ├── ITEM-001.md   # All state for work item 001
    ├── ITEM-002.md   # All state for work item 002
    └── ...
.flow/
├── FLOW.md           # 项目状态 + 待办事项（单个文件）
└── items/
    ├── ITEM-001.md   # 工作项001的所有状态
    ├── ITEM-002.md   # 工作项002的所有状态
    └── ...

State Files Overview

状态文件概述

FilePurposeContains
FLOW.md
Project-level stateVision, backlog, active item, capabilities cache
ITEM-XXX.md
Per-item statePhase, decisions, requirements, tasks, checkpoint
文件用途包含内容
FLOW.md
项目级状态愿景、待办事项、活跃工作项、功能缓存
ITEM-XXX.md
单个工作项状态阶段、决策、需求、任务、检查点

FLOW.md Structure

FLOW.md结构

The single project file contains:
单个项目文件包含以下部分：

Sections

章节

  1. Vision: High-level project vision
  2. Backlog: Table of all work items with status
  3. Active Item: Currently active item pointer
  4. Capabilities Cache: Discovered plugin mappings with timestamp
  1. 愿景：项目高层愿景
  2. 待办事项：所有工作项及其状态的表格
  3. 活跃工作项：当前活跃工作项的指针
  4. 功能缓存：已发现的插件映射及时间戳

Template

模板

See 
templates.md
for the full FLOW.md template.
完整的FLOW.md模板请参考
templates.md
。

ITEM-XXX.md Structure

ITEM-XXX.md结构

Each work item has a single consolidated file containing:
每个工作项都有一个整合的文件，包含以下部分：

Sections

章节

  1. Header: Item ID, title, timestamps
  2. Phase: Current phase and progress (DISCUSS/PLAN/EXECUTE/VERIFY)
  3. Decisions: Numbered decisions with rationale
  4. Requirements: Extracted functional/non-functional requirements
  5. Tasks: XML-structured atomic tasks (when in EXECUTE)
  6. Checkpoint: Current state snapshot for resume
  1. 头部：工作项ID、标题、时间戳
  2. 阶段：当前阶段及进度（DISCUSS/PLAN/EXECUTE/VERIFY）
  3. 决策：带理由的编号决策
  4. 需求：提取的功能/非功能需求
  5. 任务：XML结构的原子任务（处于EXECUTE阶段时）
  6. 检查点：用于恢复的当前状态快照

Template

模板

See 
templates.md
for the full ITEM-XXX.md template.
完整的ITEM-XXX.md模板请参考
templates.md
。

Work Item States

工作项状态

Items progress through these phases:
PhaseDescriptionNext Phase
BACKLOG
Defined but not startedDISCUSS
DISCUSS
Gathering requirementsPLAN
PLAN
Creating task planEXECUTE
EXECUTE
Implementing tasksVERIFY
VERIFY
Validating implementationDONE
DONE
Completed(terminal)
ON_HOLD
Paused intentionallyPrevious
BLOCKED
Waiting on dependencyPrevious
工作项会经历以下阶段：
阶段描述下一阶段
BACKLOG
已定义但未启动DISCUSS
DISCUSS
收集需求PLAN
PLAN
创建任务计划EXECUTE
EXECUTE
执行任务VERIFY
VERIFY
验证实现DONE
DONE
已完成（终端阶段）
ON_HOLD
主动暂停上一阶段
BLOCKED
等待依赖项上一阶段

State Operations

状态操作

Initialize Project

初始化项目

markdown
1. Create .flow/ directory if not exists
2. Create .flow/items/ directory
3. Scan for installed plugins
4. Detect project type from file patterns
5. Create FLOW.md with empty backlog + capabilities
markdown
1. 若不存在则创建.flow/目录
2. 创建.flow/items/目录
3. 扫描已安装的插件
4. 根据文件模式检测项目类型
5. 创建包含空待办事项和功能信息的FLOW.md

Create Work Item (
/flow-workflow:start
)

创建工作项（
/flow-workflow:start
）

markdown
1. Read FLOW.md to get next item number
2. Generate ITEM-XXX ID
3. Create .flow/items/ITEM-XXX.md with DISCUSS phase
4. Update FLOW.md backlog table
5. Set as active item in FLOW.md
markdown
1. 读取FLOW.md获取下一个工作项编号
2. 生成ITEM-XXX ID
3. 创建处于DISCUSS阶段的.flow/items/ITEM-XXX.md
4. 更新FLOW.md中的待办事项表格
5. 在FLOW.md中设置为活跃工作项

Switch Active Item

切换活跃工作项

markdown
1. Update checkpoint in current item's file
2. Update FLOW.md active item pointer
3. Load new item's context
markdown
1. 更新当前工作项文件中的检查点
2. 更新FLOW.md中的活跃工作项指针
3. 加载新工作项的上下文

Phase Transition

阶段转换

markdown
1. Verify completion criteria for current phase
2. Update phase in ITEM-XXX.md
3. Create checkpoint snapshot
4. Initialize next phase section
markdown
1. 验证当前阶段的完成条件
2. 更新ITEM-XXX.md中的阶段
3. 创建检查点快照
4. 初始化下一阶段的章节

Create Checkpoint

创建检查点

markdown
1. Record current phase and task progress
2. Capture context budget percentage
3. List next recommended action
4. Add timestamp
markdown
1. 记录当前阶段和任务进度
2. 捕获上下文预算百分比
3. 列出推荐的下一步操作
4. 添加时间戳

Resume from Checkpoint

从检查点恢复

markdown
1. Read FLOW.md to get active item
2. Read ITEM-XXX.md checkpoint section
3. Restore context from checkpoint
4. Identify next action
5. Continue workflow
markdown
1. 读取FLOW.md获取活跃工作项
2. 读取ITEM-XXX.md的检查点章节
3. 从检查点恢复上下文
4. 确定下一步操作
5. 继续工作流

Context Budget Tracking

上下文预算追踪

Track context usage in FLOW.md and report:
markdown
undefined
在FLOW.md中追踪上下文使用情况并报告：
markdown
undefined

Context Monitor

上下文监控

  • Current session: [X]% (limit: 50% before fresh agent)
  • Last auto-spawn: [TIMESTAMP]
  • Fresh agents this session: [N]
undefined
  • 当前会话：[X]%（限制：达到50%时启用新agent）
  • 上次自动生成：[TIMESTAMP]
  • 当前会话的新agent数量：[N]
undefined

State Validation

状态验证

Before any phase transition, validate:
  1. Completeness: Required sections filled
  2. Consistency: No contradictory decisions
  3. Recoverability: Checkpoint exists for current progress
在任何阶段转换前，需验证：
  1. 完整性：必填章节已填写
  2. 一致性：无矛盾的决策
  3. 可恢复性：当前进度存在检查点

Best Practices

最佳实践

Writing State Updates

编写状态更新

  • Use timestamps in ISO format
  • Include brief rationale for decisions
  • Mark status clearly (DONE, BLOCKED, etc.)
  • Keep checkpoint current
  • 使用ISO格式的时间戳
  • 包含决策的简要理由
  • 清晰标记状态（DONE、BLOCKED等）
  • 保持检查点为最新状态

Reading State for Context

读取状态获取上下文

  • Load FLOW.md first for active item
  • Load ITEM-XXX.md for current phase details
  • Check checkpoint before proceeding
  • 先加载FLOW.md获取活跃工作项
  • 加载ITEM-XXX.md获取当前阶段详情
  • 继续前检查检查点

Handling Phase Transitions

处理阶段转换

  • Always create checkpoint before transition
  • Update both FLOW.md backlog and ITEM-XXX.md
  • Announce transition to user
  • 转换前务必创建检查点
  • 同时更新FLOW.md待办事项和ITEM-XXX.md
  • 向用户通知转换情况

Migration from Old Format

从旧格式迁移

If legacy 
.flow/
structure detected (BACKLOG.md, ACTIVE.md, PROJECT.md, etc.):
  1. Read existing state files
  2. Consolidate into FLOW.md
  3. Consolidate per-item files into ITEM-XXX.md
  4. Backup old files to 
    .flow/legacy/
  5. Report migration complete
若检测到旧版
.flow/
结构（BACKLOG.md、ACTIVE.md、PROJECT.md等）：
  1. 读取现有状态文件
  2. 整合为FLOW.md
  3. 将单个工作项文件整合为ITEM-XXX.md
  4. 将旧文件备份到
    .flow/legacy/
  5. 报告迁移完成

Integration Points

集成点

State management integrates with:
  • Capability Discovery: Cache plugin mappings in FLOW.md
  • Workflow Orchestration: Phase transitions and checkpoints
  • Smart Continuation: Resume from checkpoint via 
    /flow-workflow:go
See 
templates.md
for full file templates.
状态管理与以下模块集成：
  • 功能发现：在FLOW.md中缓存插件映射
  • 工作流编排：阶段转换和检查点
  • 智能续办：通过
    /flow-workflow:go
    从检查点恢复
完整的文件模板请参考
templates.md
。