workspace-planning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Workspace Planning

工作空间规划

Workspace-level project schedule management. Operates on

planning/schedules/*.yaml

files that track modules, milestones, and delivery phases.

Each schedule YAML is organized around functional modules (not tasks or tickets), bridging the gap between Yunxiao work items and OpenSpec code changes.

工作空间级别的项目进度管理。对存储在

planning/schedules/*.yaml

文件中的模块、里程碑和交付阶段进行操作。

每个进度YAML都围绕功能模块（而非任务或工单）组织，打通了Yunxiao工作项和OpenSpec代码变更之间的关联。

Prerequisites

前置条件

Dependency	Type	Required	Notes
Schedule YAML	data	Yes	`planning/schedules/<project>.yaml` in workspace root
yunxiao skill	skill	For sync only	Must be installed before using `planning sync-yunxiao`

Do NOT verify prerequisites on skill load. If a command fails due to a missing dependency, guide the user through setup step by step.

依赖	类型	必填	说明
进度YAML	数据	是	工作空间根目录下的 `planning/schedules/<project>.yaml`
yunxiao skill	技能	仅同步功能需要	使用 `planning sync-yunxiao` 前必须先安装

请勿在技能加载时校验前置条件。如果命令因依赖缺失执行失败，请逐步引导用户完成配置。

When to Use

适用场景

User asks about project progress, timeline, or delivery status
User wants to check what's planned for a specific week
User mentions milestones, deadlines, or "how much is left"
User wants to update a module's status or mark something done
User wants to connect an OpenSpec change to a schedule module
User needs to create a new project schedule
User wants to push schedule data to Yunxiao

用户询问项目进度、时间线或交付状态
用户想要查看指定周的计划内容
用户提及里程碑、截止日期或“还剩多少工作量”
用户想要更新模块状态或将某项标记为完成
用户想要将OpenSpec变更关联到进度模块
用户需要创建新的项目进度计划
用户想要将进度数据推送到Yunxiao

Module Status State Machine

模块状态状态机

text

planned --> in_progress --> done (terminal)
   |
   +--> deferred --> planned / in_progress

Allowed:

planned -> in_progress

in_progress -> done

planned -> deferred

deferred -> planned

deferred -> in_progress

Forbidden: any transition out of

done

text

planned --> in_progress --> done (terminal)
   |
   +--> deferred --> planned / in_progress

允许的转换：

planned -> in_progress

、

in_progress -> done

、

planned -> deferred

、

deferred -> planned

、

deferred -> in_progress

。

禁止的转换：任何从

done

状态转出的操作。

Module Types

模块类型

Type	Description	Key fields
`feature`	Has UI frames, frontend/backend coordination	`frames` , `design` , `figma` , `backend` , `frontend` , `priority`
`infrastructure`	Backend-only, no UI	`description`

For the complete YAML schema and field reference, read

references/yaml-schema.md

类型	说明	关键字段
`feature`	包含UI框架、前后端协同的模块	`frames` , `design` , `figma` , `backend` , `frontend` , `priority`
`infrastructure`	仅后端、无UI的模块	`description`

完整的YAML schema和字段参考请查看

references/yaml-schema.md

。

Script

脚本

Deterministic operations are handled by

scripts/planning.py

bash

python3 <skill-dir>/scripts/planning.py review                      # Show progress
python3 <skill-dir>/scripts/planning.py update <id> --status done   # Update status
python3 <skill-dir>/scripts/planning.py link <id> --change <name>   # Link change
python3 <skill-dir>/scripts/planning.py week W3                     # Show week modules

All commands output JSON for the LLM to format. Use

--file

to specify a schedule YAML if multiple exist. Always point

--file

at the main schedule file (e.g.

sylsmart.yaml

), not the month files — the script resolves

module_files

references automatically.

Requires:

pip install pyyaml

确定性操作由

scripts/planning.py

处理：

bash

python3 <skill-dir>/scripts/planning.py review                      # 展示进度
python3 <skill-dir>/scripts/planning.py update <id> --status done   # 更新状态
python3 <skill-dir>/scripts/planning.py link <id> --change <name>   # 关联变更
python3 <skill-dir>/scripts/planning.py week W3                     # 展示当周模块

所有命令输出JSON供LLM格式化。如果存在多个进度YAML文件，请使用

--file

指定。请始终将

--file

指向主进度文件（例如

sylsmart.yaml

），而非月度文件——脚本会自动解析

module_files

引用。

依赖：

pip install pyyaml

Split vs Inline Modules

拆分与内联模块

Schedules support two layouts:

Inline:
```
modules:
```
list directly in the main YAML (simple projects)
Split:
```
module_files:
```
list of relative paths, each containing a
```
modules:
```
list (large projects)

When using split layout, all read commands (

review

week

) merge modules from all referenced files. Write commands (

update

link

) save back to the correct source file.

进度计划支持两种布局：

内联：
```
modules:
```
列表直接定义在主YAML中（适用于简单项目）
拆分：
```
module_files:
```
为相对路径列表，每个路径对应的文件中包含一个
```
modules:
```
列表（适用于大型项目）

使用拆分布局时，所有读命令（

review

、

week

）会合并所有引用文件中的模块。写命令（

update

、

link

）会将修改写回对应的源文件。

Commands

命令

planning init <project-name>

planning init <project-name>

Bootstrap a new schedule YAML for a project. This is interactive (handled by the LLM, not the script).

Steps:

Ask the user for basic project info:
- Project title (display name)
- Timeline start and end dates
- Team capacity (optional)
Ask about milestones (at least one required) — for each: id, title, date, type, deliverable
Ask about phases (optional) — or suggest a default monthly split based on timeline

Create

planning/schedules/<project-name>.yaml

with the provided structure and an empty

modules: []

Suggest next step: "Add modules manually or describe your feature list and I'll help structure them"

为项目初始化一个新的进度YAML。该操作是交互式的（由LLM处理，而非脚本）。

步骤：

向用户询问项目基础信息：
- 项目标题（展示名称）
- 时间线起止日期
- 团队容量（可选）
询问里程碑信息（至少需要一个）——每个里程碑包含：id、标题、日期、类型、交付物
询问阶段信息（可选）——或根据时间线建议默认的月度拆分方案

按照提供的结构创建

planning/schedules/<project-name>.yaml

，并包含空的

modules: []

建议下一步操作："可手动添加模块，或描述你的功能列表，我会帮你结构化梳理"

planning review

planning review

Show overall schedule progress grouped by phase.

Steps:

Run

python3 <skill-dir>/scripts/planning.py review

(use

--file

if needed)

Format the JSON output for the user
Display by phase:

text

undefined

展示按阶段分组的整体进度情况。

步骤：

执行

python3 <skill-dir>/scripts/planning.py review

（如果需要请添加

--file

参数）

将JSON输出格式化后展示给用户
按阶段展示：

text

undefined

sylsmart schedule (current: W3)

month-1: Framework (2/6 done, 33%)

V core-extraction infrastructure done V auth feature 14f done

project-list feature 12f in_progress o project-overview feature 10f planned o common-dialogs feature 18f planned o core-regression infrastructure planned


Legend: V done, * in_progress, o planned, - deferred

1. After the module list, add a brief **Risks & Bottlenecks** section (2-4 bullets):
   - Highlight modules with `design: partial` or `pending`
   - Flag weeks where backend capacity is overloaded (many ready_week targets in same week)
   - Note any milestone within 14 days with low completion rate
   - Call out frontend modules that depend on not-yet-ready backend APIs

**Flags:**

- `--week <W>` — Show modules relevant to that week. A module is "relevant" if ANY of these apply: (1) `weeks` contains that week, (2) `backend.ready_week` equals that week, (3) `frontend.mock_from` equals that week. Split output into Backend and Frontend sections with dependency status.
- `--milestones` — Show milestone progress with countdown warnings (highlight if <= 14 days away)

V core-extraction infrastructure done V auth feature 14f done

project-list feature 12f in_progress o project-overview feature 10f planned o common-dialogs feature 18f planned o core-regression infrastructure planned


图例：V 已完成，* 进行中，o 未开始，- 延期

1. 在模块列表后，添加一个简短的**风险与瓶颈**部分（2-4条）：
   - 高亮`design: partial`或`pending`的模块
   - 标记后端容量过载的周（同一周内有过多ready_week目标）
   - 提醒14天内到期且完成率较低的里程碑
   - 指出依赖尚未就绪的后端API的前端模块

**参数：**

- `--week <W>`——展示与该周相关的模块。满足以下任意条件的模块即为"相关"：(1) `weeks`包含该周，(2) `backend.ready_week`等于该周，(3) `frontend.mock_from`等于该周。将输出拆分为后端和前端两部分，并展示依赖状态。
- `--milestones`——展示里程碑进度和倒计时提醒（如果距离到期<=14天则高亮）

planning update <module-id> --status <status>

planning update <module-id> --status <status>

Update a module's status.

Step 1 — Validate with the script (does NOT write to files):

bash

python3 <skill-dir>/scripts/planning.py update <module-id> --status <status>

The script validates the state machine transition and returns JSON including

source_file

(the YAML file containing the module). If invalid, it exits with an error.

Step 2 — Apply with the Edit tool: use the

source_file

from the JSON output to locate the module and change its

status:

field. This preserves YAML comments and formatting.

更新模块状态。

步骤1——校验：使用脚本执行校验（不会写入文件）：

bash

python3 <skill-dir>/scripts/planning.py update <module-id> --status <status>

脚本会校验状态机转换是否合法，并返回包含

source_file

（模块所在的YAML文件）的JSON。如果校验不通过，会返回错误并退出。

步骤2——生效：使用编辑工具：根据JSON输出的

source_file

定位到对应模块，修改其

status:

字段。该操作会保留YAML注释和格式。

planning link <module-id> --change <change-name>

planning link <module-id> --change <change-name>

Associate an OpenSpec change with a module.

Step 1 — Validate with the script (does NOT write to files):

bash

python3 <skill-dir>/scripts/planning.py link <module-id> --change <change-name>

The script verifies the change exists and returns JSON with the updated

changes

list,

source_file

, and whether an auto-transition from

planned

in_progress

should apply.

Step 2 — Apply with the Edit tool: add the change name to the module's

changes:

list (or create the field). If

auto_transition

is true, also update

status: in_progress

将OpenSpec变更与模块关联。

步骤1——校验：使用脚本执行校验（不会写入文件）：

bash

python3 <skill-dir>/scripts/planning.py link <module-id> --change <change-name>

脚本会校验变更是否存在，并返回包含更新后的

changes

列表、

source_file

以及是否需要自动将状态从

planned

转为

in_progress

的JSON。

步骤2——生效：使用编辑工具：将变更名称添加到模块的

changes:

列表（如果字段不存在则创建）。如果

auto_transition

为true，同时将

status

更新为

in_progress

。

planning sync-yunxiao

planning sync-yunxiao

Push unlinked modules to Yunxiao as work items.

Prerequisite: yunxiao skill must be installed and configured.

Steps:

Read YAML, find modules where
```
yunxiao_id
```
is null or missing
List modules to be created, wait for user confirmation
Use yunxiao skill to create a work item for each module
Write returned work item IDs back to
```
yunxiao_id
```
field in YAML
Report results; modules with existing
```
yunxiao_id
```
are skipped

将未关联的模块作为工作项推送到Yunxiao。

前置条件：必须已安装并配置yunxiao skill。

步骤：

读取YAML，查找
```
yunxiao_id
```
为空或缺失的模块
列出待创建的模块，等待用户确认
使用yunxiao skill为每个模块创建一个工作项
将返回的工作项ID写回YAML的
```
yunxiao_id
```
字段
上报结果；已存在
```
yunxiao_id
```
的模块会被跳过

Common Mistakes

常见错误

Error	Cause	Fix
Module not found	Typo in module id	Run `planning review` to see all ids
Invalid status transition	State machine violation	Check allowed transitions above
Change not found	Name mismatch	Verify change exists in `openspec/changes/`
No schedule files	Missing YAML	Run `planning init` to create one
Yunxiao sync fails	yunxiao skill not installed	Install yunxiao skill first

错误	原因	解决方案
模块未找到	模块id输入错误	执行 `planning review` 查看所有id
无效的状态转换	违反状态机规则	查看上方允许的转换规则
变更未找到	名称不匹配	校验 `openspec/changes/` 目录下是否存在该变更
无进度文件	缺失YAML文件	执行 `planning init` 创建一个
Yunxiao同步失败	yunxiao skill未安装	先安装yunxiao skill

workspace-planning

Original

Translation

Workspace Planning

工作空间规划

Prerequisites

前置条件

When to Use

适用场景

Module Status State Machine

模块状态状态机

Module Types

模块类型

Script

脚本

Split vs Inline Modules

拆分与内联模块

Commands

命令

`planning init <project-name>`

`planning init <project-name>`

`planning review`

`planning review`

sylsmart schedule (current: W3)

sylsmart schedule (current: W3)

month-1: Framework (2/6 done, 33%)

month-1: Framework (2/6 done, 33%)

`planning update <module-id> --status <status>`

`planning update <module-id> --status <status>`

`planning link <module-id> --change <change-name>`

`planning link <module-id> --change <change-name>`

`planning sync-yunxiao`

`planning sync-yunxiao`

Common Mistakes

常见错误