design

name	design
description	Design an implementation plan and refine it through human annotation cycles. Use when user says '設計して', '計画を立てて', 'plan the implementation', 'how should I implement', or wants to plan before coding. Do NOT use for direct implementation, code review, or research without planning.
allowed-tools	Agent, AskUserQuestion, Bash, Read, Write, Glob, Grep
argument-hint	[task description] [--research 'research-file.md'] [--output 'filename']
disable-model-invocation	true
metadata	{"author":"ysk1031","version":"1.0.0"}

Implementation Design Skill

Generate a detailed implementation plan for a task, then iterate on it through human annotation cycles — the human edits the plan with inline notes, and the plan is regenerated incorporating that feedback. Repeat until approved, then finalize as a checklist for implementation.

Instructions

Phase 1: Context Gathering (use Agent with subagent)

Call the Agent tool with:

• subagent_type: "project-profiler"
• description: "gather planning context"
• prompt: Replace $ARGUMENTS in the agent's loaded prompt with the actual user arguments and execute.

---

Phase 2: Plan Generation (use Agent with subagent)

If Phase 1 returned "status": "NO_TASK", display the message field and stop.

If Phase 1 returned "research": "NOT_FOUND" (file specified but missing): Use AskUserQuestion:

• question: "指定された調査ファイル <path> が見つかりません。調査ファイルなしで計画を作成しますか？"
• header: "Plan"
• options:
  1. label: "調査なしで作成", description: "調査ファイルなしで計画を生成します"
  2. label: "パスを変更", description: "別のファイルを指定します（Otherで入力）"
  3. label: "キャンセル", description: "計画作成を終了します"

Call the Agent tool with:

• subagent_type: "plan-generator"
• description: "generate implementation plan"
• prompt: Use the Phase 1 output as context data, the TASK as the agent description, and if a research file exists, read and incorporate its findings.

---

Phase 3: Annotation Cycle (main agent)

This is the core loop. It repeats until the user approves the plan.

Step 1: Write Plan File

Determine filename:

• If Phase 1's output field is not "NONE": use that
• Otherwise: design-<sanitized-task>.md (sanitize the TASK: lowercase, replace spaces and special characters with hyphens, remove consecutive hyphens)

Convert the Phase 2 JSON output to Markdown. Read the output template from assets/output-template.md (relative to this skill's directory) with the Read tool. Map JSON fields to Markdown sections as described in the template, and write the plan file using the Write tool.

Step 2: User Review

Use AskUserQuestion:

• question: "計画を確認してください。エディタでインライン注釈を書き込んでから「注釈を反映」を選択すると、注釈を反映した計画を再生成します。"
• header: "Plan Review"
• options:
  1. label: "承認", description: "この計画を確定します"
  2. label: "注釈を反映", description: "ファイルに書き込んだ注釈を反映して再生成します"
  3. label: "キャンセル", description: "計画作成を終了します"

If "承認": Proceed to Phase 4.

If "注釈を反映":

1. Read the plan file with the Read tool
2. Call the Agent tool to regenerate the plan:
   • subagent_type: "plan-reviser"
   • description: "revise plan with annotations"
   • prompt: Use the annotated plan file content as the annotated plan and the original context from Phase 1 as context data.
3. Write the revised plan to the same file (overwrite)
4. Loop back to Step 2 (ask for review again)

If custom input (Other): Treat as a verbal annotation. Follow the same flow as "注釈を反映" above — call the plan-reviser agent with the current plan file content as the annotated plan, the original context from Phase 1 as context data, AND the user's text as additional verbal feedback. Write the revised plan to the same file, then loop back to Step 2.

If "キャンセル": Print "計画作成を終了しました。" and stop.

---

Phase 4: Finalization (main agent)

1. Read the approved plan file
2. Ensure the checklist section at the bottom is complete and matches all implementation steps
3. Update the plan file if the checklist needed corrections
4. Display completion message:

## 計画確定

`<filename>` が承認されました。

### チェックリスト
<display the checklist>

### 次のステップ
- 実装時にこの計画を参照し、各ステップ完了時にチェックリストを更新してください

---

Rules

• ALWAYS display messages in Japanese — the user is a Japanese speaker and needs to review and annotate plans in Japanese
• NEVER implement any code — this skill generates plans only — separating planning from implementation prevents code changes before human approval
• NEVER skip the annotation cycle (Phase 3) — proceeding to implementation without human approval risks unintended changes
• There is no limit on annotation cycle iterations — repeat as many times as the user needs — plan quality directly determines implementation quality, so iterate until the user is satisfied
• When regenerating with annotations, preserve parts of the plan the user did NOT annotate — changing unannotated sections would lose content the user already approved
• The plan must be specific enough to implement without ambiguity — include file paths, function names, and code structure — ambiguous plans lead to misinterpretation during AI implementation, causing rework
• If a research file is provided, the plan must reference and build upon its findings — plans that ignore research findings are prone to inconsistencies with existing patterns
• If CLAUDE.md exists, ensure the plan follows project conventions — plans violating project conventions will be rejected during lint/review at implementation time
• Keep each implementation step atomic — one logical change per step — large steps make mid-step validation and rollback difficult
• Include a testability consideration for each step where applicable — untestable changes cannot be quality-assured and increase future regression risk

---

Examples

Example 1: 新機能の設計

User says: "認証機能の設計をして" Actions:

1. project-profiler がプロジェクトコンテキストを収集
2. plan-generator が実装計画を生成
3. ユーザーがエディタで計画を確認・注釈
4. plan-reviser が注釈を反映して再生成（必要に応じて繰り返し）
5. 承認後 design-auth.md として確定 Result: 実装可能な詳細計画とチェックリストが生成される

---

Troubleshooting

"NO_TASK"

Cause: タスクの説明が指定されていない Solution: 具体的なタスク説明を引数として指定

注釈が反映されない

Cause: ファイルを保存せずに「注釈を反映」を選択した Solution: エディタでファイルを保存してから「注釈を反映」を選択