Skip to content
Skills Library
Programming · Planning

plan

/plan

從 Spec 文件、OpenSpec 變更或自由文字需求生成 plan.json。 Use when: 把規格轉換成可供 /orchestrate 執行的任務計畫。 Not for: 執行產出的計畫——請用 /orchestrate;判斷這個想法值不值得做——請用 /brainstorm。 Keywords: plan, spec, task plan, plan.json, DAG, 計畫, 規格, 任務, 任務計畫.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

從 Spec 文件、OpenSpec 變更或自由文字需求生成 plan.json。 Use when: 把規格轉換成可供 /orchestrate 執行的任務計畫。 Not for: 執行產出的計畫——請用 /orchestrate;判斷這個想法值不值得做——請用 /brainstorm。 Keywords: plan, spec, task plan, plan.json, DAG, 計畫, 規格, 任務, 任務計畫.

Arguments

/plan [spec-file.md | openspec-dir/ | \"requirement text\" | (interactive)]
Original author description

從 Spec 文件、OpenSpec 變更或自由文字需求生成 plan.json。 Use when: 把規格轉換成可供 /orchestrate 執行的任務計畫。 Not for: 執行產出的計畫——請用 /orchestrate;判斷這個想法值不值得做——請用 /brainstorm。 Keywords: plan, spec, task plan, plan.json, DAG, 計畫, 規格, 任務, 任務計畫.

How it works

  1. 用法
  2. 執行流程
  3. 版本歷程
Original SKILL.md headings · 227 lines, 720 words
SKILL.md preview
---
name: plan
source: ../../../../skills/plan/SKILL.md
source_version: 2.0.0
translation_version: 2.1.0
last_synced: 2026-08-17
source_hash: 6fbb1a1b8040
scope: universal
description: |
  從 Spec 文件、OpenSpec 變更或自由文字需求生成 plan.json。
  Use when: 把規格轉換成可供 /orchestrate 執行的任務計畫。
  Not for: 執行產出的計畫——請用 /orchestrate;判斷這個想法值不值得做——請用 /brainstorm。
  Keywords: plan, spec, task plan, plan.json, DAG, 計畫, 規格, 任務, 任務計畫.
argument-hint: "[spec-file.md | openspec-dir/ | \"requirement text\" | (interactive)]"
---

# /plan — 從 Spec 自動生成 plan.json

> **語言**: [English](../../../../skills/plan/SKILL.md) | 繁體中文

## 用法

```
/plan <spec-file.md>              # Spec 模式(自有格式 / SpecKit)
/plan <openspec-change-dir/>      # OpenSpec 模式
/plan "需求描述文字"               # 需求模式
/plan                             # 互動模式(自動偵測)
```

---

## 執行流程

### Step 1:輸入辨識與格式偵測

根據引數類型判斷使用模式:

**引數是 .md 檔案:**
1. 讀取檔案內容
2. 偵測格式:
   - 含 `## Requirements` **且** `## Technical Design` → **自有格式**(SPEC-NNN-*.md)
   - 含 `## Summary` **且** `## Detailed Design` → **SpecKit 格式**
   - 其他 .md → 嘗試解析為通用 Spec(按自有格式處理,缺少的欄位由 AI 補充)

**引數是目錄:**
1. 檢查是否含 `proposal.md` + `tasks.md` → **OpenSpec 格式**
2. 否則報錯:「此目錄不符合 OpenSpec 結構」

**引數是字串描述(非檔案路徑):**
→ **需求模式**

**無引數:**
→ **互動模式**
1. 偵測 `openspec/` 目錄存在? → 列出 changes 讓使用者選擇
2. 偵測 `specs/*.md` 存在? → 列出可用 Spec 讓使用者選擇
3. 都沒有 → 進入需求模式問答

---

### Step 2:專案 Context 收集

讀取目標專案的關鍵資訊:

1. **CLAUDE.md / AGENTS.md** — 語言、框架、測試工具、開發規範
2. **package.json / pyproject.toml** — 可用 scripts(build, test, lint)

從 Context 推斷:
- 主要語言(TypeScript / Python / 其他)
- 預設 verify_command(如 `pnpm build && pnpm test`、`pytest -x`)
- 預設 lint_command(如 `pnpm lint`、`ruff check .`)

---

### Step 3:Spec 解析

依偵測到的格式,解析 Spec 內容:

#### 自有格式(SPEC-NNN-*.md)

提取以下區段:
- **Summary / Motivation** → 理解背景與需求動機
- **Requirements (REQ-NNN)** → 功能需求列表
- **Acceptance Criteria (AC-N)** → Given/When/Then 驗收條件
- **Technical Design** → Phase 分層、每個 Phase 的實作項目
- **Test Plan** → 測試清單
- **Risks** → 風險評估

#### OpenSpec(change 目錄)

讀取以下檔案:
- `proposal.md` → Why(動機)、What Changes(變更項目)、Impact
- `tasks.md` → `- [ ]` checklist 項目
- `design.md`(若存在)→ 技術決策
- `specs/*/spec.md`(若存在)→ Requirements(SHALL / MUST 語句)、Scenarios

#### SpecKit(SPEC-ID.md)

提取以下區段:
- **Summary / Motivation** → 背景
- **Detailed Design** → 技術實作步驟
- **Acceptance Criteria** → checkbox 驗收條件
- **Dependencies** → 外部依賴
- **Risks** → 風險

---

### Step 4:Task 切分

依格式套用不同映射規則:

#### 自有格式映射規則

| Spec 區段 | plan.json 欄位 | 映射規則 |
|-----------|---------------|----------|
| Technical Design > Phase | 一組 tasks | 每個 Phase 的每個實作項目 = 1 個 task |
| Phase 實作項目描述 | `task.spec` | 合併:項目描述 + 相關 REQ + 技術細節 |
| Acceptance Criteria (AC-N) | `task.acceptance_criteria` | 分配到最相關的 task |
| Summary / Motivation | `task.user_intent` | 萃取與 task 最相關的意圖 |
| Test Plan | `task.verify_command` | 推斷測試指令 |

#### OpenSpec 映射規則

| OpenSpec 檔案 | plan.json 欄位 | 映射規則 |
|--------------|---------------|----------|
| `tasks.md` 的 checklist 項目 | tasks | 每個 `- [ ]` 項目 = 1 個 task |
| `proposal.md` > Why | `task.user_intent` | 所有 tasks 共用 |
| `proposal.md` > What Changes | 融入 `task.spec` | 提供變更脈絡 |
| `design.md` 技術細節 | 融入 `task.spec` | 補充實作指引 |
| `specs/*/spec.md` > Scenarios | `task.acceptance_criteria` | 每個 Scenario 映射為一條 criteria |
| `specs/*/spec.md` > Requirements | 融入 `task.spec` | SHALL / MUST 語句轉為具體實作指引 |

---

### Step 5:依賴推斷

為 tasks 建立 `depends_on` 關係:

1. **Phase / Stage 順序**:後面的 Phase 的第一個 task depends_on 前面 Phase 的最後一個 task
2. **同 Phase 內順序**:型別定義 → 實作 → 整合 → 測試
3. **檔案依賴**:A 建立的檔案被 B import → B depends_on A
4. **無依賴的 tasks**:`depends_on: []`(可並行)

---

### Step 6:verify_command 推斷

依以下優先順序推斷:

1. **Test Plan / Scenarios 有明確測試項** → 對應測試指令
2. **TypeScript 專案** → `pnpm build && pnpm test`
3. **Python 專案** → `pytest -x`
4. **其他** → 使用 Step 2 收集的專案 scripts
5. **無法推斷** → 不設(後續品質警告會提醒)

---

### Step 7:品質設定

- 預設 `quality: "standard"`
- 使用者可在互動確認時調整

---

### Step 8:組裝 plan.json

```json
{
  "project": "<專案名稱>",
  "quality": "standard",
  "defaults": {
    "max_turns": 30,
    "max_budget_usd": 2.0,
    "verify_command": "<推斷的預設驗證指令>"
  },
  "tasks": [
    {
      "id": "T-001",
      "title": "<task 標題>",
      "spec": "<詳細的 task 規格說明>",
      "depends_on": [],
      "verify_command": "<task 層級驗證指令(可選)>",
      "acceptance_criteria": ["<驗收條件 1>"],
      "user_intent": "<使用者意圖>"
    }
  ]
}
```

**注意事項:**
- Task ID 格式:`T-NNN`(如 T-001, T-002)
- `spec` 欄位應詳盡——它是 agent 執行任務的唯一規格輸入
- `acceptance_criteria` 每條都必須是可觀察、可驗證的

---

### Step 9:驗證(Claude-native)

Claude 對 plan.json 執行以下驗證(無需外部引擎):

1. **結構驗證**:`tasks` 陣列存在且非空、每個 task 含必填欄位(id, title, spec)
2. **DAG 合法性**:`depends_on` 中的所有 ID 均存在、無循環依賴
3. **安全掃描**:task.spec 不含危險指令(`rm -rf /`、`DROP DATABASE`、`git push --force`)
4. **品質警告**:task 缺少 verify_command、spec 過短(< 20 字)等

若發現問題,在呈現前先自動修正(若可修正)或標示警告。

---

### Step 10:呈現與確認

向使用者呈現生成結果:

1. **摘要表格**:
   ```
   | Task ID | 標題 | 依賴 | 驗證指令 |
   |---------|------|------|----------|
   | T-001   | ...  | -    | ...      |
   | T-002   | ...  | T-001| ...      |
   ```

2. **DAG 拓撲**:
   ```
   Layer 0: T-001, T-002(並行)
   Layer 1: T-003(依賴 T-001)
   Layer 2: T-004(依賴 T-002, T-003)
   ```

3. **品質設定**:`quality: standard`

4. **品質警告**(若有)

5. **詢問使用者**:確認或修改?確認後寫入檔案(預設路徑:`plans/<spec-name>.plan.json`)

---

## 版本歷程

| 版本 | 日期 | 變更 |
|------|------|------|
| 2.0.0 | 2026-04-28 | 升格為 UDS 正式 Skill;移除 [DEVAP] 標記;Step 9 改為 Claude-native 驗證(XSPEC-097 Phase 3) |
| 1.0.0 | 2026-04-09 | 初始發布(從上游遷移) |

Versions

RepositoryScoreLicence
This page · AsiaOstrich/universal-dev-standards100MIT
mlophez/polix-ai100Apache-2.0
jeremylongshore/tons-of-skills-marketplace100MIT
duronext/jig100MIT
rjmurillo/ai-agents100MIT
rjmurillo/ai-agents100MIT
rjmurillo/ai-agents100MIT
xoai/sage100MIT
JoDi-27/JoDi-SDD100MIT

Identical content appears in 2 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 8ac1c3a40e98 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100orchestrate
    以 Claude 原生 Agent tool 编排多任务执行计划(以 DAG 为基础,不需外部引擎)。 Use when: 执行带有并行/顺序任务依赖关系的 plan.json 文件。 Not for: 一开始生成计划——请用 /plan;彼此之间没有依赖关系的单一任务。 Keywords: orchestrate, plan, execute, DAG, task plan, 编排, 执行计划, 并行, 任务依赖.
  • 100orchestrate
    Orchestrate multi-task execution plans using Claude's native Agent tool (DAG-based, no external engine). Use when: executing a plan.json file with parallel/sequential task dependencies. Not for: producing the plan in the first place — use /plan; single tasks with no dependencies…
  • 100spec-design
    Write OpenSpec design.md and tasks.md artifacts. TRIGGER when: producing a technical design or task checklist for a spec-driven feature. SKIP: writing proposal.md (use spec-research); executing tasks.md (use spec-develop).
  • 100openspec
    OpenSpec is a command-line tool plus a set of slash commands that make an AI coding agent write a reviewable plan — proposal, requirements with scenarios, design and task list — before it changes any code. Use when a user asks to set up spec-driven development, run openspec…
  • 100writing-plans
    Use when you have a spec or requirements for a multi-step task, before touching code. Produces a task-by-task implementation plan another engineer or agent can execute without asking you anything.
  • 100openspec-plus-spec
    MANDATORY skill that activates whenever the OpenSpec specification phase begins. Triggers: /opsx-new or /opsx-continue runs; openspec-new-change, openspec-continue-change, or openspec-explore is active; `openspec instructions spec` or `openspec instructions specs` is invoked; or…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.