Decompose tasks using the Single Responsibility Principle and generate executable specifications for Phases 1–13. Phase 12 includes middle-school-level conceptual explanations. Anchors: • Clean Code / Applied: SRP / Purpose: Task decomposition criteria • Continuous Delivery / Applied: Phase gate / Purpose: Quality pipeline • DDD / Applied: Ubiquitous Language / Purpose: Terminology unification Trigger: Task specification creation, task decomposition, workflow design, Phase execution, IPC Bridge API unification, Preload API pattern, safeInvoke, safeOn
開発タスクを Phase 1〜13 の実行可能な仕様書へ落とし込む。SKILL.md は入口だけを持ち、詳細は references/ と LOGS.md に分離する。
| 原則 | 説明 |
| ------------------------- | ----------------------------------------------------------- |
| Script First | 決定論的処理は scripts/ で固定する |
| LLM for Judgment | 判断、設計、レビューだけを LLM が担う |
| Progressive Disclosure | 必要な reference だけを段階的に読む |
| 1 File = 1 Responsibility | 大きくなった guide は family file へ分離する |
| .claude Canonical | 正本は .claude/skills/...、.agents/skills/... は mirror |
要件草案や設計草案を扱うときは、機能列挙のレビューで止めず、次の3系統を必ず通す。
特に workflow / lane / UI統合 / runtime orchestration / verify 導入を含むタスクでは、次を明示してから Phase 1 へ進む。
what / how だけでなく why now / why this way を仮説として書く。Facade / Engine / Service / Bridge / Store / UI の状態所有権を混在させない。4条件 は原則として次で評価する。
要件レビュー出力では、上の5項目を一次結論として先に示し、その後に補足として因果ループ、KJ法クラスタ、戦略仮説を足す。
| モード | 用途 | 最初に読むもの |
| ------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------- |
| create | 新規 workflow を作る | references/create-workflow.md |
| execute | Phase 1〜13 を順番に実行する | references/execute-workflow.md |
| update | 既存仕様書を修正する | references/phase-templates.md |
| detect-unassigned | Phase 12 の残課題を formalize する | references/phase-12-documentation-guide.md |
node scripts/detect-mode.js --request "{{USER_REQUEST}}"
タスク仕様書作成を開始する前に、以下の P50 チェックを実施する。 upstream 実装済みタスクでは「差分確認 → 回帰確認」にシフトできるため、Phase 5 の実装フェーズが軽減される。
| 確認項目 | Yes → 対応 | No → 対応 | | ---------------------------------- | ---------------------------------------------- | ------------------------------ | | current branch に実装が存在する | 差分確認・回帰テストを Phase 5 とする | 通常の実装 Phase とする | | upstream（main等）にマージ済み | worktree に cherry-pick または再実装不要を明記 | 未マージとして扱う | | 前提タスク（依存タスク）が完了済み | 完了済みを記録し依存チェックを省略 | Phase 1 に依存解消タスクを追加 |
標準ルール: upstream マージ済みの場合は Phase 5 冒頭に「差分確認」セクションを設け、実装の代わりに回帰確認を行う。
P50チェック結果に基づき、タスク仕様書のメタ情報に implementation_mode を明記する。
| モード | 値 | 説明 |
| ---------- | ------------------- | --------------------------------------------------------------- |
| 通常実装 | "new" | RED/GREEN サイクルで新規実装を行う |
| 既実装確認 | "verify_existing" | Phase 4 = targeted test 設計、Phase 5 = diff check に切り替える |
implementation_mode: "verify_existing" を選択した場合、Phase 4 では既実装コードのカバレッジを確認する targeted test のみを設計し、Phase 5 では git diff によるdiff確認を主要作業とする。詳細は references/phase-template-core.md の P50チェックセクションを参照。
verify_existing タスクタイプの典型的アウトカム:
verify_existing は「コードの暗黙知を明文化する」タスクタイプである。コード変更は原則ゼロまたは最小限にとどまり、以下が主な成果物となる:
| アウトカム | 例 | | ---------- | -- | | コメント追加 | 既存関数・型に JSDoc / インラインコメントを付与 | | テスト追加 | 既実装コードの動作を保証する regression test を新設 | | ドキュメント更新 | 仕様書・README・インターフェース定義の現行コードへの同期 |
コード変更なしで Phase 12 まで完了するケースが標準パターンであり、verify-all-specs が PASS しても仕様書反映が不完全な場合がある（→ references/phase-template-phase12.md §verify-all-specs が PASS しても確認すべき項目 を参照）。
agents/decompose-task.md で責務を分解する。agents/identify-scope.md で前提、制約、受入条件を固定する。
[Feedback 1 対応] Phase 1（要件定義）でタスク分類（UI task / docs-only task）を明示的に記録し、artifacts.json の artifact 命名 canonical 一覧を task root 生成時に先に確定させること。後回しにすると artifact 命名ドリフトが発生する。agents/design-phases.md と agents/generate-task-specs.md で index.md と phase-*.md を作る。agents/output-phase-files.md と agents/update-dependencies.md で artifacts.json を整える。agents/verify-specs.md、scripts/validate-phase-output.js、scripts/verify-all-specs.js で gate を通す。| Phase | 名称 | 目的 |
| ----- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | 要件定義 | scope、受入条件、inventory を固定する。既存コードの命名規則（camelCase / kebab-case 等）を分析し記録する。[FB-UI-02-2] 全件 pnpm test が SIGKILL 終了するリスクがある場合は、targeted run ファイルリストを Phase 1 で事前列挙する（たとえば、メモリ制約が厳しい環境では vitest の対象ファイル指定が必須となる）。[carry-over確認] 前タスクの成果物（git log --oneline -5 で確認）を棚卸しし、今タスクの新規作業との差異を明確化すること |
| 2 | 設計 | topology、SubAgent lane、validation path を設計する。[FB-SDK-07-1] 「既存コンポーネント再利用可否」を必ず確認する。新規 UI 実装ゼロで品質・アクセシビリティ・HIG準拠を既存レベルで担保できる場合は再利用を優先する |
| 3 | 設計レビュー | Phase 4 へ進めるかを判定する |
| 4 | テスト作成 | command suite と expected result を作る。TDD Red 前に、テストパターンが Phase 1-3 で確認した命名規則と整合しているかを検証する。[Feedback P0-09-U1] private method のテストは (facade as unknown as FacadePrivate) キャストまたは public callback 経由を使う方針を Phase 4 仕様書に明記する。[FB-MSO-002] テスト実行前に依存関係整合（pnpm install + pnpm --filter @repo/shared build）を確認する。esbuild darwin バイナリ mismatch は worktree 直後に多発するため、Phase 4 開始前チェックを必須とする |
| 5 | 実装 | .claude 正本を更新し、mirror を同期する。[Feedback RT-03] 実装計画に「新規作成」「修正」ファイルパス一覧を必須記載する（見落とし防止）。[Feedback P0-09-U1] improve() フローで SDK callback が不適用な場合（llmAdapter.sendChat() 経由など）は「canUseTool 適用可能範囲と制約」を仕様書に明記する |
| 6 | テスト拡充 | fail path、回帰 guard、補助 command を追加する |
| 7 | カバレッジ確認 | concern と dependency edge の coverage を可視化する。[EMB-005-FB] NON_VISUAL + 単一クラス追加タスクでは Phase 6 に統合可能（coverage が Phase 6 テストで既に担保できる場合）。[EVALS-DOC-001] docs-only タスクでは totalTests=0 / avgCoverage=0 で EVALS.json taskMetrics を閉じ、カバレッジ確認は「対象コードなし（N/A）」として記録する |
| 8 | リファクタリング | duplicate と navigation drift を削る。[Feedback RT-03] 変更内容を 対象/Before/After/理由 テーブル形式で記録する |
| 9 | 品質保証 | line budget、link、mirror parity を一括判定する |
| 10 | 最終レビュー | acceptance criteria と blocker を判定する |
| 11 | 手動テスト | 3層評価（Semantic / Visual / AI UX）を実行し、フィードバックループで HIGH 問題を unassigned-task/ へ自動生成する。shared path alias 系は build config と test config の parity を同時確認する。[FB-MSO-003] 画面証跡取得スクリプトには try { ... } finally { browser.close(); server.close(); } パターンを標準化し、ポート解放を確実にする。[FB-LLM-MOD-05-001] screenshot ファイル名は phase spec / capture script / metadata / implementation-guide の 4 か所でセマンティック canonical 名（<component>-<state>.png）を一致させる（TC-XX 番号はメタデータ内 tc フィールドのみ）。詳細: references/phase-11-screenshot-guide.md |
| 12 | ドキュメント更新 | implementation guide、spec sync、未タスク、feedback を完了する |
| 13 | PR作成 | user の明示承認後のみ実施する |
| Task | 責務 | パターン | 入力 | 出力 | | ------------------------ | -------------------------- | -------- | ---------------- | --------------------- | | decompose-task | タスクを単一責務に分解 | seq | ユーザー要求 | タスク分解リスト | | identify-scope | スコープ・前提・制約を定義 | seq | タスク分解リスト | スコープ定義 | | design-phases | Phase構成を設計 | seq | スコープ定義 | フェーズ設計書 | | generate-task-specs | タスク仕様書を生成 | seq | フェーズ設計書 | タスク仕様書一覧 | | output-phase-files | 個別Markdownファイルを出力 | par | タスク仕様書一覧 | phase-*.md | | update-dependencies | Phase間の依存関係を設定 | par | タスク仕様書一覧 | 依存関係マップ | | verify-specs | 全13仕様書の品質検証 | seq | 検証レポート | PASS/FAIL判定 | | update-system-specs | システム仕様書を更新 | seq | 実装サマリー | 更新完了チェック | | generate-unassigned-task | 未完了タスク指示書を生成 | cond | レビュー課題 | unassigned-task/*.md |
凡例: seq=順次実行, par=並列実行, cond=条件分岐
| Task | 名称 | 必須 | 詳細参照 | | ---- | -------------------------------- | ---- | ------------------------------------------- | | 1 | 実装ガイド作成（2パート構成） | ✅ | 下記参照 | | 2 | システム仕様書更新（2ステップ） | ✅ | 下記参照 | | 3 | ドキュメント更新履歴作成 | ✅ | scripts/generate-documentation-changelog.js | | 4 | 未タスク検出レポート作成 | ✅ | 0件でも出力必須 | | 5 | スキルフィードバックレポート作成 | ✅ | 改善点なしでも出力必須 |
| パート | 対象読者 | 内容 | | ---------- | ------------------------ | ------------------------------------------ | | Part 1 | 初学者・中学生レベル | 概念説明（日常の例え話、専門用語なし） | | Part 2 | 開発者・技術者 | 技術的詳細（スキーマ・API・コード例） |
Part 1（中学生レベル）の必須要件:
Part 2（技術者レベル）の必須要件:
implementation-guide.md へ必ず明記する## 視覚証跡 セクションに UI/UX変更なしのため Phase 11 スクリーンショット不要 と明記し、screenshots/.gitkeep を削除する。代替証跡として phase-10/final-review-result.md と phase-11/manual-test-result.md（Preload API / 型定義テスト結果を記録）を参照する| Step | 必須 | 内容 |
| -------- | ---- | ------------------------------------------------------------------------------------------------------------- |
| Step 1-A | ✅ | タスク完了記録（「完了タスク」セクション追加 + 関連ドキュメントリンク + 変更履歴 + LOGS.md×2 + topic-map.md） |
| Step 1-B | ✅ | 実装状況テーブル更新（実装完了:「未実装」→「完了」 / 仕様書作成のみ: spec_created） |
| Step 1-C | ✅ | 関連タスクテーブル更新（仕様書内の「関連タスク」「未タスク候補」テーブルのステータス更新） |
| Step 1-D | ✅ | EVALS.json taskMetrics追記（関連スキルの qualityInsights.taskMetrics.{TASK_ID} に completedPhases / totalTests / avgCoverage / systemSpecsUpdated / unassignedTasksDetected を記録。docs-only タスクは totalTests=0 / avgCoverage=0 で固定） |
| Step 2 | 条件 | システム仕様更新（新規インターフェース追加時のみ） |
⚠️ Task 1（実装ガイド作成）との境界に注意
| 活動 | Task 1（実装ガイド） | Task 2（仕様更新） | | -------------------------------- | -------------------- | ------------------ | | Part 1/2 実装ガイド作成 | ✅ メイン責務 | ❌ 対象外 | | aiworkflow-requirements 仕様更新 | ❌ 対象外 | ✅ Step 2 | | タスク完了記録（仕様書内） | ❌ 対象外 | ✅ Step 1-A 必須 | | LOGS.md更新（2ファイル） | ❌ 対象外 | ✅ Step 1-A 必須 |
Step 2 更新が必要な場合:
Step 2 更新が不要な場合:
spec_created UI task の Phase 12 close-out ルールspec_created ステータスの UI task でも Phase 12 実行時は Step 1-A〜1-C を N/A にせず same-wave sync で閉じる。
| Step | spec_created での扱い |
| -------- | ------------------------------------------------------------------------- |
| Step 1-A | 完了タスク記録 + LOGS.md x2 + SKILL.md x2 + topic-map を same-wave で更新 |
| Step 1-B | 実装状況テーブルに spec_created を記録（completed ではない） |
| Step 1-C | 関連タスクテーブルのステータスを current facts へ更新 |
| Step 2 | 新規インターフェース追加がなければ N/A（ただし下記の再判定ルールを確認） |
当初 docs-only / spec_created だった task に後から code 変更が入った場合:
outputs/phase-12/*.md を同一ターンで current facts へ戻すN/A / NON_VISUAL だった Phase 11 evidence の reclassification を検討する| ソース | 確認項目 |
| ------------------------ | ------------------------------------------------------------------------------------------- |
| 元タスク仕様書 | 「スコープ外」として明示された項目 |
| Phase 3/10レビュー結果 | MINOR判定の指摘事項 |
| Phase 11手動テスト | スコープ外の発見事項・改善提案 |
| コードコメント | TODO/FIXME/HACK/XXX |
| describe.skip ブロック | 削除したtestid/要素名が旧参照として残存していないか（残存時はcleanupタスクをbacklogに登録） |
# 未タスク検出スクリプト
node scripts/detect-unassigned-tasks.js --scan packages/shared/src --output .tmp/unassigned-candidates.json
📖 references/phase-11-12-guide.md 📖 references/spec-update-workflow.md 📖 agents/generate-unassigned-task.md
Phase 1冒頭で仕様書に記載されたクラス名とcurrentコードベースのクラス名が一致するか確認する。 不一致の場合は命名方針をPhase 2設計より前に確定させること。
事例: LateChunkingService（仕様書記述）vs ChunkingLateChunkingAdapter（実装クラス名）のズレがPhase 1で早期検出できれば、後続フェーズの手戻りを防げた（TASK-EMB-LATE-CHUNKING-SERVICE-SEPARATION-001）。
Phase 11のNON_VISUALテンプレートでは証跡ファイル名を事前に宣言・固定すること。 後からファイル名が変わるとPhase 12のartifacts parity確認で矛盾が発生する。
事例: evidence-collection.md などのcanonical名を強制することで、manual-test-result.md 単独では不明瞭だった証跡範囲をdrift防止できる（TASK-EMB-LATE-CHUNKING-SERVICE-SEPARATION-001）。
Phase 12で「system-spec-update: 更新要」と判定した場合、 summaryファイル作成だけでなく正本仕様ファイルの実際の更新まで完了条件とする。
事例: Phase 12がsummaryファイル作成で完結せず、正本仕様の更新まで完了条件にする必要がある（TASK-EMB-LATE-CHUNKING-SERVICE-SEPARATION-001）。
新規クラスを設計する際は同一パッケージ内の既存クラス名と照合する。 衝突する場合はPrefix/Suffix（Adapter, Service, Handler等）で区別すること。
事例: token-levelのLateChunkingServiceと同名になりそうだったため、Phase 2でChunkingLateChunkingAdapterに改名した。早期検査が必要（TASK-EMB-LATE-CHUNKING-SERVICE-SEPARATION-001）。
| Version | Date | Changes | | ---------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->下载完整 Skill 目录，包含 SKILL.md 及所有相关文件
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer