请见下（由于长度限制，仅提供部分关键翻译，完整内容请根据原文自行翻译）
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.
Prerequisites
| Dependency | Type | Required | Notes |
|---|
| Schedule YAML | data | Yes | planning/schedules/.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.
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
Module Status State Machine
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.
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.
Script
Deterministic operations are handled by scripts/planning.py:
python3 /scripts/planning.py review # Show progress
python3 /scripts/planning.py update --status done # Update status
python3 /scripts/planning.py link --change # Link change
python3 /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.
Requires: pip install pyyaml
Commands
planning init
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/.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"
planning review
Show overall schedule progress grouped by phase.
Steps:
- Run
python3 /scripts/planning.py review (use --file if needed)
- Format the JSON output for the user
- Display by phase:
## 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
- 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 — 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)
planning update --status
Update a module's status.
python3 /scripts/planning.py update --status
The script validates the state machine transition and returns JSON with the result.
If invalid, it shows the error with allowed target states.
planning link --change
Associate an OpenSpec change with a module.
python3 /scripts/planning.py link --change
The script verifies the change exists, appends it, and auto-transitions planned to in_progress.
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
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 |
by