Skip to content

Commit f9188eb

Browse files
author
catlog22
committed
Add Chinese documentation for CLI commands and workflows
1 parent 05ad811 commit f9188eb

23 files changed

Lines changed: 8877 additions & 26 deletions

File tree

‎.claude/skills/_shared/COMMAND-TO-SKILL-CONVERSION.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -291,6 +291,27 @@ allowed-tools: Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob,
291291
## Architecture Overview
292292
{ASCII 架构图}
293293

294+
## Key Design Principles
295+
{设计原则列表}
296+
297+
## Auto Mode
298+
{自动模式说明}
299+
300+
## Usage
301+
302+
```
303+
Skill(skill="{skill-name}", args="<task description>")
304+
Skill(skill="{skill-name}", args="[FLAGS] \"<task description>\"")
305+
306+
# Flags
307+
{flag 说明，每个 flag 一行}
308+
309+
# Examples
310+
Skill(skill="{skill-name}", args="\"Implement JWT authentication\"") # 说明
311+
Skill(skill="{skill-name}", args="--mode xxx \"Refactor payment module\"") # 说明
312+
Skill(skill="{skill-name}", args="-y \"Add user profile page\"") # 说明
313+
```
314+
294315
## Execution Flow
295316
{流程图 + Phase 引用表}
296317
@@ -313,6 +334,16 @@ allowed-tools: Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob,
313334
{错误处理策略}
314335
```
315336

337+
**Usage 格式要求**：
338+
339+
- **必须使用代码块** 包裹 Usage 内容
340+
- 使用 `Skill()` 调用格式，不使用 `/skill-name` 命令行格式
341+
- 包含两种调用格式：基本调用 + 带 Flags 的完整调用
342+
- Flags 说明每行一个 flag，格式：`flag-name 说明`
343+
- Examples 必须展示所有 flag 组合的典型调用场景
344+
- 字符串参数中的引号使用转义 `\"`
345+
- Examples 行尾可添加 `# 说明` 注释
346+
316347
### 5.3 执行流程示例
317348

318349
```markdown
@@ -641,12 +672,34 @@ skills/workflow-plan/
641672
| 原 plan.md 内容 | SKILL.md 对应位置 |
642673
|----------------|-------------------|
643674
| Frontmatter | Frontmatter (扩展) |
675+
| argument-hint | Usage (转换为 Skill 调用格式) |
644676
| 执行流程描述 | Execution Flow (可视化) |
645677
| 子命令调用 | Phase Reference Table |
646678
| 数据传递 | Data Flow (显式定义) |
679+
| (无) | Usage (新增 - Skill 调用格式) |
647680
| (无) | TodoWrite Pattern (新增) |
648681
| (无) | Error Handling (新增) |
649682

683+
**Usage 转换示例**：
684+
685+
原命令 `argument-hint`:
686+
```yaml
687+
argument-hint: "[-y|--yes] \"text description\"|file.md"
688+
```
689+
690+
转换为 SKILL.md Usage:
691+
```
692+
Skill(skill="workflow-plan", args="<task description>")
693+
Skill(skill="workflow-plan", args="[-y|--yes] \"<task description>\"")
694+
695+
# Flags
696+
-y, --yes Skip all confirmations (auto mode)
697+
698+
# Examples
699+
Skill(skill="workflow-plan", args="\"Implement authentication\"") # Interactive mode
700+
Skill(skill="workflow-plan", args="-y \"Implement authentication\"") # Auto mode
701+
```
702+
650703
### 9.3 Phase 文件与原子命令对比
651704

652705
| 原子命令内容 | Phase 文件对应 |
@@ -685,3 +738,4 @@ wc -l skills/{skill-name}/SKILL.md skills/{skill-name}/phases/*.md
685738
| v1.0 | 2025-02-05 | 基于 workflow-plan 转换实践创建 |
686739
| v1.1 | 2025-02-05 | 强化内容一致性要求；添加第7章一致性验证；添加应移除的命令特有内容说明 |
687740
| v2.0 | 2026-02-05 | 命令调用引用统一转换为文件路径引用；移除 `/workflow:XX` 命令语法；引用转换规则重构 |
741+
| v2.1 | 2026-02-05 | 添加 Usage 部分格式规范（Skill 调用格式）；更新 5.2 必需章节；添加 Usage 转换示例到 9.2 节 |

‎.claude/skills/workflow-lite-plan/SKILL.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
---
2+
name: workflow-lite-plan
3+
description: Unified lightweight planning skill with mode selection (Lite Plan, Multi-CLI Plan, Lite Fix). Supports exploration, diagnosis, multi-CLI collaboration, and shared execution via lite-execute.
4+
allowed-tools: Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep, Skill, mcp__ace-tool__search_context
5+
---
6+
7+
# Planning Workflow
8+
9+
Unified lightweight planning skill that consolidates multiple planning approaches into a single entry point with mode selection. Default mode: **Lite Plan**. All planning modes share a common execution phase (lite-execute).
10+
11+
## Architecture Overview
12+
13+
```
14+
┌──────────────────────────────────────────────────────────┐
15+
│ Planning Workflow Orchestrator (SKILL.md) │
16+
│ → Parse args → Mode selection → Load phase → Execute │
17+
└────────────┬─────────────────────────────────────────────┘
18+
│ Mode Selection (default: Lite Plan)
19+
┌────────┼────────┬──────────┐
20+
↓ ↓ ↓ ↓ (shared)
21+
┌────────┐ ┌────────┐ ┌────────┐ ┌────────────┐
22+
│Phase 1 │ │Phase 2 │ │Phase 3 │ │ Phase 4 │
23+
│ Lite │ │Multi- │ │ Lite │ │ Lite │
24+
│ Plan │ │CLI Plan│ │ Fix │ │ Execute │
25+
└────────┘ └────────┘ └────────┘ └────────────┘
26+
│ │ │ ↑
27+
└──────────┴──────────┴───────────┘
28+
(all hand off to Phase 4)
29+
```
30+
31+
## Key Design Principles
32+
33+
1. **Mode Selection First**: User chooses planning approach before any work begins
34+
2. **Shared Execution**: All planning modes produce `executionContext` consumed by Phase 4 (lite-execute)
35+
3. **Progressive Phase Loading**: Only load the selected planning phase + execution phase
36+
4. **Auto-Continue**: Planning phase completes → automatically loads execution phase
37+
5. **Default Lite Plan**: When no mode specified, use Lite Plan (most common)
38+
39+
## Auto Mode
40+
41+
When `--yes` or `-y`: Skip mode selection (use default or flag-specified mode), auto-approve plan, skip clarifications.
42+
43+
## Usage
44+
45+
```
46+
Skill(skill="workflow-lite-plan", args="<task description>")
47+
Skill(skill="workflow-lite-plan", args="[FLAGS] \"<task description>\"")
48+
49+
# Flags
50+
--mode lite-plan|multi-cli|lite-fix Planning mode selection (default: lite-plan)
51+
-y, --yes Skip all confirmations (auto mode)
52+
-e, --explore Force exploration (lite-plan only)
53+
--hotfix Fast hotfix mode (lite-fix only)
54+
55+
# Examples
56+
Skill(skill="workflow-lite-plan", args="\"Implement JWT authentication\"") # Default: lite-plan
57+
Skill(skill="workflow-lite-plan", args="--mode multi-cli \"Refactor payment module\"") # Multi-CLI planning
58+
Skill(skill="workflow-lite-plan", args="--mode lite-fix \"Login fails with 500 error\"") # Bug fix mode
59+
Skill(skill="workflow-lite-plan", args="-y \"Add user profile page\"") # Auto mode
60+
Skill(skill="workflow-lite-plan", args="--mode lite-fix --hotfix \"Production DB timeout\"") # Hotfix mode
61+
```
62+
63+
## Execution Flow
64+
65+
```
66+
Input Parsing:
67+
├─ Extract flags: --mode, --yes, --explore, --hotfix
68+
└─ Extract task description (string or file path)
69+
70+
Mode Selection:
71+
└─ Decision:
72+
├─ --mode lite-plan (or no --mode flag) → Read phases/01-lite-plan.md
73+
├─ --mode multi-cli → Read phases/02-multi-cli-plan.md
74+
├─ --mode lite-fix → Read phases/03-lite-fix.md
75+
└─ No flag + not --yes → AskUserQuestion (default: Lite Plan)
76+
77+
Planning Phase (one of):
78+
├─ Phase 1: Lite Plan
79+
│ └─ Ref: phases/01-lite-plan.md
80+
│ └─ Output: executionContext (plan.json + explorations + selections)
81+
│
82+
├─ Phase 2: Multi-CLI Plan
83+
│ └─ Ref: phases/02-multi-cli-plan.md
84+
│ └─ Output: executionContext (plan.json + synthesis rounds + selections)
85+
│
86+
└─ Phase 3: Lite Fix
87+
└─ Ref: phases/03-lite-fix.md
88+
└─ Output: executionContext (fix-plan.json + diagnoses + selections)
89+
90+
Execution Phase (always):
91+
└─ Phase 4: Lite Execute
92+
└─ Ref: phases/04-lite-execute.md
93+
└─ Input: executionContext from planning phase
94+
└─ Output: Executed tasks + optional code review
95+
```
96+
97+
**Phase Reference Documents** (read on-demand when phase executes):
98+
99+
| Phase | Document | Purpose |
100+
|-------|----------|---------|
101+
| 1 | [phases/01-lite-plan.md](phases/01-lite-plan.md) | Lightweight planning with exploration, clarification, and plan generation |
102+
| 2 | [phases/02-multi-cli-plan.md](phases/02-multi-cli-plan.md) | Multi-CLI collaborative planning with ACE context and cross-verification |
103+
| 3 | [phases/03-lite-fix.md](phases/03-lite-fix.md) | Bug diagnosis and fix planning with severity-based workflow |
104+
| 4 | [phases/04-lite-execute.md](phases/04-lite-execute.md) | Shared execution engine: task grouping, batch execution, code review |
105+
106+
## Mode Selection Logic
107+
108+
```javascript
109+
// Flag parsing
110+
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
111+
const modeFlag = extractFlag($ARGUMENTS, '--mode') // 'lite-plan' | 'multi-cli' | 'lite-fix' | null
112+
113+
// Mode determination
114+
let selectedMode
115+
116+
if (modeFlag) {
117+
// Explicit mode flag
118+
selectedMode = modeFlag
119+
} else if (autoYes) {
120+
// Auto mode: default to lite-plan
121+
selectedMode = 'lite-plan'
122+
} else {
123+
// Interactive: ask user
124+
const selection = AskUserQuestion({
125+
questions: [{
126+
question: "Select planning approach:",
127+
header: "Mode",
128+
multiSelect: false,
129+
options: [
130+
{ label: "Lite Plan (Recommended)", description: "Lightweight planning with exploration and clarification" },
131+
{ label: "Multi-CLI Plan", description: "Multi-model collaborative planning (Gemini + Codex + Claude)" },
132+
{ label: "Lite Fix", description: "Bug diagnosis and fix planning with severity assessment" }
133+
]
134+
}]
135+
})
136+
selectedMode = parseSelection(selection) // Map to 'lite-plan' | 'multi-cli' | 'lite-fix'
137+
}
138+
139+
// Load phase document
140+
const phaseDoc = {
141+
'lite-plan': 'phases/01-lite-plan.md',
142+
'multi-cli': 'phases/02-multi-cli-plan.md',
143+
'lite-fix': 'phases/03-lite-fix.md'
144+
}[selectedMode]
145+
146+
Read(phaseDoc) // Load selected planning phase
147+
// Execute planning phase...
148+
// After planning completes:
149+
Read('phases/04-lite-execute.md') // Load execution phase
150+
```
151+
152+
## Data Flow
153+
154+
```
155+
Planning Phase (01/02/03)
156+
│
157+
├─ Produces: executionContext = {
158+
│ planObject: plan.json or fix-plan.json,
159+
│ explorationsContext / diagnosisContext / synthesis rounds,
160+
│ clarificationContext,
161+
│ executionMethod: "Agent" | "Codex" | "Auto",
162+
│ codeReviewTool: "Skip" | "Gemini Review" | ...,
163+
│ originalUserInput: string,
164+
│ session: { id, folder, artifacts }
165+
│ }
166+
│
167+
↓
168+
Execution Phase (04)
169+
│
170+
├─ Consumes: executionContext
171+
├─ Task grouping → Batch creation → Parallel/sequential execution
172+
├─ Optional code review
173+
└─ Development index update
174+
```
175+
176+
## TodoWrite Pattern
177+
178+
**Initialization** (after mode selection):
179+
```json
180+
[
181+
{"content": "Mode: {selectedMode} - Planning", "status": "in_progress", "activeForm": "Planning ({selectedMode})"},
182+
{"content": "Execution (Phase 4)", "status": "pending", "activeForm": "Executing tasks"}
183+
]
184+
```
185+
186+
**After planning completes**:
187+
```json
188+
[
189+
{"content": "Mode: {selectedMode} - Planning", "status": "completed", "activeForm": "Planning ({selectedMode})"},
190+
{"content": "Execution (Phase 4)", "status": "in_progress", "activeForm": "Executing tasks"}
191+
]
192+
```
193+
194+
Phase-internal sub-tasks are managed by each phase document (attach/collapse pattern).
195+
196+
## Core Rules
197+
198+
1. **Planning phases NEVER execute code** - all execution delegated to Phase 4
199+
2. **Only ONE planning phase runs** per invocation (Phase 1, 2, or 3)
200+
3. **Phase 4 ALWAYS runs** after planning completes
201+
4. **executionContext is the contract** between planning and execution phases
202+
5. **Progressive loading**: Read phase doc ONLY when about to execute
203+
6. **No cross-phase loading**: Don't load Phase 2 if user selected Phase 1
204+
205+
## Error Handling
206+
207+
| Error | Resolution |
208+
|-------|------------|
209+
| Unknown --mode value | Default to lite-plan with warning |
210+
| Planning phase failure | Display error, offer retry or mode switch |
211+
| executionContext missing | Error: planning phase did not produce context |
212+
| Phase file not found | Error with file path for debugging |
213+
214+
## Related Skills
215+
216+
- Full planning workflow: [workflow-plan/SKILL.md](../workflow-plan/SKILL.md)
217+
- Brainstorming: [workflow-brainstorm-auto-parallel/SKILL.md](../workflow-brainstorm-auto-parallel/SKILL.md)

0 commit comments

Comments
 (0)