create-ai-project 1.24.1 → 1.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/.claude/agents-en/acceptance-test-generator.md +2 -1
  2. package/.claude/agents-en/code-reviewer.md +6 -3
  3. package/.claude/agents-en/codebase-analyzer.md +1 -1
  4. package/.claude/agents-en/design-sync.md +2 -1
  5. package/.claude/agents-en/document-reviewer.md +4 -2
  6. package/.claude/agents-en/integration-test-reviewer.md +7 -5
  7. package/.claude/agents-en/prd-creator.md +2 -1
  8. package/.claude/agents-en/scope-discoverer.md +2 -1
  9. package/.claude/agents-en/task-decomposer.md +21 -41
  10. package/.claude/agents-en/technical-designer-frontend.md +4 -2
  11. package/.claude/agents-en/technical-designer.md +4 -2
  12. package/.claude/agents-en/ui-spec-designer.md +1 -1
  13. package/.claude/agents-en/work-planner.md +5 -4
  14. package/.claude/agents-ja/acceptance-test-generator.md +2 -1
  15. package/.claude/agents-ja/code-reviewer.md +6 -3
  16. package/.claude/agents-ja/codebase-analyzer.md +1 -1
  17. package/.claude/agents-ja/design-sync.md +2 -1
  18. package/.claude/agents-ja/document-reviewer.md +4 -2
  19. package/.claude/agents-ja/integration-test-reviewer.md +7 -5
  20. package/.claude/agents-ja/prd-creator.md +2 -1
  21. package/.claude/agents-ja/scope-discoverer.md +2 -1
  22. package/.claude/agents-ja/task-decomposer.md +21 -41
  23. package/.claude/agents-ja/technical-designer-frontend.md +4 -2
  24. package/.claude/agents-ja/technical-designer.md +4 -2
  25. package/.claude/agents-ja/ui-spec-designer.md +1 -1
  26. package/.claude/agents-ja/work-planner.md +5 -4
  27. package/.claude/commands-en/add-integration-tests.md +2 -0
  28. package/.claude/commands-en/build.md +2 -0
  29. package/.claude/commands-en/design.md +2 -0
  30. package/.claude/commands-en/diagnose.md +2 -0
  31. package/.claude/commands-en/front-build.md +2 -0
  32. package/.claude/commands-en/front-design.md +2 -0
  33. package/.claude/commands-en/front-plan.md +2 -0
  34. package/.claude/commands-en/front-review.md +2 -0
  35. package/.claude/commands-en/implement.md +2 -0
  36. package/.claude/commands-en/plan.md +2 -0
  37. package/.claude/commands-en/prepare-implementation.md +2 -0
  38. package/.claude/commands-en/project-inject.md +2 -0
  39. package/.claude/commands-en/reverse-engineer.md +2 -0
  40. package/.claude/commands-en/review.md +2 -0
  41. package/.claude/commands-en/update-doc.md +2 -0
  42. package/.claude/commands-ja/add-integration-tests.md +2 -0
  43. package/.claude/commands-ja/build.md +2 -0
  44. package/.claude/commands-ja/design.md +2 -0
  45. package/.claude/commands-ja/diagnose.md +2 -0
  46. package/.claude/commands-ja/front-build.md +2 -0
  47. package/.claude/commands-ja/front-design.md +2 -0
  48. package/.claude/commands-ja/front-plan.md +2 -0
  49. package/.claude/commands-ja/front-review.md +2 -0
  50. package/.claude/commands-ja/implement.md +2 -0
  51. package/.claude/commands-ja/plan.md +2 -0
  52. package/.claude/commands-ja/prepare-implementation.md +2 -0
  53. package/.claude/commands-ja/project-inject.md +2 -0
  54. package/.claude/commands-ja/reverse-engineer.md +2 -0
  55. package/.claude/commands-ja/review.md +2 -0
  56. package/.claude/commands-ja/update-doc.md +2 -0
  57. package/.claude/skills-en/documentation-criteria/references/design-template.md +7 -5
  58. package/.claude/skills-en/documentation-criteria/references/plan-template.md +4 -3
  59. package/.claude/skills-en/documentation-criteria/references/task-template.md +19 -3
  60. package/.claude/skills-en/llm-friendly-context/SKILL.md +80 -0
  61. package/.claude/skills-en/task-analyzer/references/skills-index.yaml +15 -0
  62. package/.claude/skills-ja/documentation-criteria/references/design-template.md +7 -5
  63. package/.claude/skills-ja/documentation-criteria/references/plan-template.md +4 -3
  64. package/.claude/skills-ja/documentation-criteria/references/task-template.md +19 -3
  65. package/.claude/skills-ja/llm-friendly-context/SKILL.md +80 -0
  66. package/.claude/skills-ja/task-analyzer/references/skills-index.yaml +15 -0
  67. package/CHANGELOG.md +12 -0
  68. package/package.json +1 -1
@@ -42,6 +42,21 @@ Each row is a DD-derived observable contract the implementation in this task mus
42
42
  |---|---|---|---|
43
43
  | [Design Doc path (§ Section) copied from the matching work plan Reference Contract Values row] | [structure-order / derived-display / state-lifecycle-negative, copied from the work plan row] | [Required Observable Value copied verbatim from the work plan row] | [Y/N-answerable positive predicate that evaluates whether the planned/final implementation reproduces the value] |
44
44
 
45
+ ## Decisions and Unresolved Items
46
+ (Include this section when task decomposition resolved an alternative, optional behavior, or placeholder, or when a required decision is unresolved at decomposition time. Omit when the task carries no such items.)
47
+
48
+ Resolved decisions — each alternative, optional behavior, or placeholder the decomposition fixed to an explicit choice:
49
+
50
+ | Item | Decision | Source / Rule |
51
+ |---|---|---|
52
+ | [the alternative, optional behavior, or placeholder] | [the selected choice or the deterministic rule that selects it; for a placeholder, the exact temporary output, allowed dependencies, and verification expectation] | [work plan / Design Doc / UI Spec / ADR section, or the basis of the decision rule] |
53
+
54
+ Blocking unresolved items — decisions that cannot be made at decomposition time and block execution:
55
+
56
+ | Item | Required Input | Escalation Condition |
57
+ |---|---|---|
58
+ | [the unresolved decision] | [the input needed to resolve it] | [who or what to escalate to, and the point at which the executor must stop rather than guess] |
59
+
45
60
  ## Investigation Notes
46
61
  (Implementation observations are appended here before implementation begins. When Binding Decisions exist, record the planned implementation approach and each Compliance Check result here.)
47
62
 
@@ -74,10 +89,10 @@ Each row is a DD-derived observable contract the implementation in this task mus
74
89
  - **Verification level**: [L1: Functional operation as end-user feature / L2: New tests added and passing / L3: Code builds without errors]
75
90
 
76
91
  ## Proof Obligations
77
- (One entry per AC or claim this task implements. Derived from test skeleton annotations when present, otherwise from the AC's primary failure mode. Each test must prove its claim. Repeat the block below once per claim; the heading carries the AC ID or claim ID so downstream review can resolve coverage per claim.)
92
+ (One entry per AC, claim, or applicable Failure Mode Checklist category this task covers. Derived from test skeleton annotations when present, otherwise from the AC's primary failure mode or the mapped Failure Mode category. Each test must prove its claim. Repeat the block below once per claim; the heading carries the AC ID, claim ID, or `Failure Mode: <category>` so downstream review can resolve coverage per claim.)
78
93
 
79
- ### Obligation: [AC ID or claim ID]
80
- - **Claim**: [the behavior the AC promises]
94
+ ### Obligation: [AC ID, claim ID, or Failure Mode category — e.g., `Failure Mode: missing-sort-key ordering`]
95
+ - **Claim**: [the AC behavior, claim, or failure-mode condition this task must prove]
81
96
  - **Primary failure mode**: [the regression the test turns red on]
82
97
  - **Boundary to exercise**: [public/integration boundary the test traverses, or "in-process unit"]
83
98
  - **State assertion**: [observable state before → action → after for state-changing claims; "N/A" otherwise]
@@ -91,6 +106,7 @@ Each row is a DD-derived observable contract the implementation in this task mus
91
106
  - [ ] Deliverables created (for research/design tasks)
92
107
  - [ ] (When Binding Decisions exist) Every Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (file:line, test result, or command output)
93
108
  - [ ] (When Reference Contracts exist) Every Reference Contract Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes
109
+ - [ ] (When Decisions and Unresolved Items exist) Every resolved decision is applied as recorded, and no blocking unresolved item remains open — if one does, execution halts and is escalated per its Escalation Condition
94
110
 
95
111
  ## Notes
96
112
  - Impact scope: [Areas where changes may propagate]
@@ -0,0 +1,80 @@
1
+ ---
2
+ name: llm-friendly-context
3
+ description: Clarifies inputs, outputs, success criteria, decisions, and unresolved conditions so downstream agents can execute without guessing. Use when writing or revising LLM-facing prompts, handoffs, planning artifacts, reviews, reports, or generated instructions.
4
+ ---
5
+
6
+ # LLM-Friendly Context
7
+
8
+ The goal is stable downstream execution: the next agent should know what to read, what to do, what counts as success, and when to stop or escalate.
9
+
10
+ This skill governs the clarity of LLM-facing output — prompts, handoffs, and generated artifacts. It does not define which documents to create or their required structure; that is owned by documentation-criteria.
11
+
12
+ ## Core Rules
13
+
14
+ 1. **Use positive, executable instructions**
15
+ - State what the next agent should do.
16
+ - Convert quality policies into positive criteria.
17
+ - Example: "Preserve existing public API behavior across the documented compatibility cases."
18
+
19
+ 2. **Make vague instructions concrete**
20
+ - Replace subjective terms with observable conditions, paths, commands, schemas, examples, or decision rules.
21
+ - Terms that often need clarification when they leave a decision to the next agent: `appropriate`, `proper`, `related`, `existing behavior`, `optional`, `as needed`, `if needed`, `per convention`, unresolved alternatives, `TBD`, `placeholder`.
22
+
23
+ 3. **Specify output shape**
24
+ - Define required sections, fields, table columns, JSON keys, or checklist items.
25
+ - For handoffs, include paths to produced artifacts and the exact status fields the caller must inspect.
26
+
27
+ 4. **Provide necessary context**
28
+ - Include the purpose, source artifacts, hard constraints, accepted decisions, and unresolved conditions.
29
+ - Prefer concrete file paths and section hints over broad module names.
30
+
31
+ 5. **Decompose complex work into verifiable steps**
32
+ - Split work with 3+ objectives or sequential dependencies into ordered steps.
33
+ - Each step needs a checkpoint: what evidence proves it is complete.
34
+
35
+ 6. **Permit uncertainty explicitly**
36
+ - If the source material is missing, contradictory, or not verifiable, state the uncertainty and the required escalation.
37
+ - Record unknown business, product, security, or compatibility decisions as blocking unresolved items, each stating the required input to resolve it and the escalation condition.
38
+ - Write every blocking unresolved item in one consistent shape, regardless of artifact: `Unresolved: <decision needed> — required input: <what or who resolves it> — escalation: <the condition under which the next agent stops rather than guesses>`.
39
+
40
+ 7. **Keep constraints proportionate**
41
+ - Add only constraints that reduce ambiguity or preserve a real requirement.
42
+ - Keep simple downstream tasks lightweight when the target action, context, and success criteria are already clear.
43
+
44
+ ## Rewrite Patterns
45
+
46
+ Use these rewrites before treating a prompt, handoff, or artifact as complete.
47
+
48
+ | Ambiguous form | Rewrite as |
49
+ |---|---|
50
+ | `optional` used as an unresolved choice | Required, omitted, or required only under a named condition |
51
+ | Multiple alternatives that the next agent must choose between | The selected option, or a deterministic decision rule |
52
+ | `as needed` / `if needed` | The triggering condition and required action |
53
+ | `per convention` | The file, function, test, or documented convention to follow |
54
+ | `related files` | Specific paths, globs, or search hints |
55
+ | `existing behavior` | The observable behavior, source file, test, API response, or UI state to preserve |
56
+ | `placeholder` | Exact temporary value/behavior, allowed dependencies, and verification expectation |
57
+ | `TBD` used as a placeholder for required information | A blocking unresolved item stating the required input and escalation condition (and owner when known) |
58
+ | `appropriate` / `proper` | A measurable criterion or checklist |
59
+
60
+ ## Handoff Checklist
61
+
62
+ Before sending a prompt or artifact to another agent, verify:
63
+
64
+ - [ ] The target action is explicit.
65
+ - [ ] Required input paths and source artifacts are named.
66
+ - [ ] Accepted decisions and constraints are stated once, without alternate wording.
67
+ - [ ] Output format or expected status fields are specified.
68
+ - [ ] Success criteria are observable.
69
+ - [ ] Ambiguous expressions have been rewritten or marked as unresolved.
70
+ - [ ] The next agent can complete its scope with explicit choices, decision rules, or blocking unresolved items.
71
+
72
+ ## Generated Artifact Checklist
73
+
74
+ Before writing or finalizing a generated document:
75
+
76
+ - [ ] Each requirement, claim, task, test skeleton, or review finding has enough source context to trace why it exists.
77
+ - [ ] Every executable instruction names the target, action, and expected result.
78
+ - [ ] Verification steps say what to run or observe and what result proves success.
79
+ - [ ] If an artifact is derived from another artifact, copied decisions stay consistent in wording and meaning.
80
+ - [ ] If downstream work is blocked by missing information, the artifact records the missing input and escalation condition.
@@ -189,6 +189,21 @@ skills:
189
189
  - "9 Skill Editing Principles"
190
190
  - "References"
191
191
 
192
+ llm-friendly-context:
193
+ skill: "llm-friendly-context"
194
+ tags: [universal, cross-cutting, prompt, handoff, artifact, clarity, ambiguity-removal, downstream-execution, documentation]
195
+ typical-use: "Writing or revising LLM-facing prompts, handoffs, planning artifacts, reviews, reports, or generated instructions so downstream agents can execute without guessing"
196
+ size: small
197
+ key-references:
198
+ - "Positive, executable instructions over prohibitions"
199
+ - "Observable success criteria for agent handoffs"
200
+ - "Explicit unresolved items over silent ambiguity"
201
+ sections:
202
+ - "Core Rules"
203
+ - "Rewrite Patterns"
204
+ - "Handoff Checklist"
205
+ - "Generated Artifact Checklist"
206
+
192
207
  # Frontend-specific Skills
193
208
  frontend-typescript-rules:
194
209
  skill: "frontend-typescript-rules"
@@ -281,11 +281,13 @@ unknowns:
281
281
 
282
282
  ### クライアント状態設計(フロントエンド機能を含む場合)
283
283
 
284
- | 状態カテゴリ | 状態 | 管理方法 | 同期戦略 |
285
- |------------|------|---------|---------|
286
- | サーバー状態 | [取得データ] | [キャッシュライブラリ/カスタムフック] | [ポーリング/WebSocket/手動更新] |
287
- | UIローカル状態 | [モーダル開閉、タブ選択] | [useState/useReducer] | - |
288
- | 一時状態 | [フォーム入力、下書き] | [useState/フォームライブラリ] | [自動保存/手動保存] |
284
+ | 状態カテゴリ | 状態 | 管理方法 | 同期戦略 | リセット/クリア時の振る舞い |
285
+ |------------|------|---------|---------|--------------------------|
286
+ | サーバー状態 | [取得データ] | [キャッシュライブラリ/カスタムフック] | [ポーリング/WebSocket/手動更新] | [全クリアで消去/保持] |
287
+ | UIローカル状態 | [モーダル開閉、タブ選択] | [useState/useReducer] | - | [デフォルトにリセット/保持] |
288
+ | 一時状態 | [フォーム入力、下書き] | [useState/フォームライブラリ] | [自動保存/手動保存] | [リセットで消去/永続化] |
289
+
290
+ 機能にリセットまたは全クリア操作がある場合、リセット/クリア時の振る舞い列を埋める。リセット時に未使用/デフォルト値へ戻らなければならない状態は state-lifecycle negative 契約(観測可能な契約: リセット後も状態は未使用のまま。Contract Type `state-lifecycle-negative`)であり、想定で済ませず検証されるよう記録する。
289
291
 
290
292
  ### UIアクション - APIコントラクトマッピング(フロントエンド機能を含む場合)
291
293
 
@@ -26,8 +26,8 @@
26
26
  - **失敗時の対応**: [Design Docから抽出]
27
27
 
28
28
  ### 証明戦略
29
- - **証明義務の出所**: [スケルトンが存在する場合はテストスケルトンの注釈(主要な故障モード、証明義務)。存在しない場合は各ACの主要な故障モード]
30
- - **タスクごとの伝播**: 主張を実装する各タスクは Proof Obligations(task template参照)を記録し、下流のレビューがテストが主張を証明しているか(単に実行されるだけでないか)を判定できるようにする
29
+ - **証明義務の出所**: [スケルトンが存在する場合はテストスケルトンの注釈(主要な故障モード、証明義務)。存在しない場合は各ACの主要な故障モード。加えてタスクにマッピングされた該当する故障モードチェックリストのカテゴリ]
30
+ - **タスクごとの伝播**: 主張を実装する、または該当する故障モードチェックリストのカテゴリをカバーする各タスクは Proof Obligations(task template参照)を記録し、下流のレビューがテストが主張を証明しているか(単に実行されるだけでないか)を判定できるようにする
31
31
 
32
32
  ## 品質保証メカニズム(Design Docより)
33
33
 
@@ -61,7 +61,7 @@ Design Docが、実装が正確に再現すべき**拘束的観測値**を指定
61
61
 
62
62
  ## 故障モードチェックリスト
63
63
 
64
- この実装が防ぐべきドメイン非依存の故障カテゴリ。8カテゴリすべてを列挙し、各カテゴリの該当列に yes/no を記入し、該当する各カテゴリにカバーするタスクを挙げる。エントリにはプロジェクト固有の名称を含めない。
64
+ この実装が防ぐべきドメイン非依存の故障カテゴリ。9カテゴリすべてを列挙し、各カテゴリの該当列に yes/no を記入し、該当する各カテゴリにカバーするタスクを挙げる。エントリにはプロジェクト固有の名称を含めない。
65
65
 
66
66
  | カテゴリ | 該当? | カバーするタスク |
67
67
  |---|---|---|
@@ -73,6 +73,7 @@ Design Docが、実装が正確に再現すべき**拘束的観測値**を指定
73
73
  | unavailable boundary | yes/no | |
74
74
  | shared-state dependency | yes/no | |
75
75
  | rollback-only visibility | yes/no | |
76
+ | missing-sort-key ordering | yes/no | |
76
77
 
77
78
  ## UI Specコンポーネント → タスクマッピング
78
79
 
@@ -42,6 +42,21 @@ Metadata:
42
42
  |---|---|---|---|
43
43
  | [対応する作業計画書のReference Contract Values行からコピーしたDesign Docパス (§ セクション)] | [作業計画書の行からコピーしたContract Type: structure-order / derived-display / state-lifecycle-negative] | [作業計画書の行から逐語コピーしたRequired Observable Value] | [計画中/最終の実装が値を再現するかをY/Nで判定できる肯定述語] |
44
44
 
45
+ ## Decisions and Unresolved Items
46
+ (タスク分解時に代替案・optionalな挙動・placeholderを解決した場合、または分解時点で必須の決定が未解決の場合に本セクションを記載する。該当項目がない場合は省略する。)
47
+
48
+ 解決済みの決定 — 分解が明示的な選択に確定した、各代替案・optionalな挙動・placeholder:
49
+
50
+ | Item | Decision | Source / Rule |
51
+ |---|---|---|
52
+ | [代替案・optionalな挙動・placeholder] | [選択した選択肢、またはそれを選ぶ決定的な判断ルール。placeholderの場合は正確な暫定出力・許容される依存・検証の期待値] | [作業計画書 / Design Doc / UI Spec / ADR のセクション、または判断ルールの根拠] |
53
+
54
+ ブロッキングな未解決項目 — 分解時点では決定できず実行をブロックする決定:
55
+
56
+ | Item | Required Input | Escalation Condition |
57
+ |---|---|---|
58
+ | [未解決の決定] | [解決に必要な入力] | [誰/何にエスカレーションするか、および executor が推測せず停止すべき地点] |
59
+
45
60
  ## Investigation Notes
46
61
  (実装観察事項を実装開始前にここへ追記する。Binding Decisionsがある場合、計画した実装アプローチと各Compliance Check結果をここに記録する。)
47
62
 
@@ -74,10 +89,10 @@ Metadata:
74
89
  - **検証レベル**: [L1: エンドユーザー機能としての動作確認 / L2: 新規テスト追加・パス / L3: ビルドエラーなし]
75
90
 
76
91
  ## Proof Obligations
77
- (このタスクが実装するACまたは主張ごとに1エントリ。スケルトンの注釈がある場合はそこから、なければACの主要な故障モードから導出する。各テストは主張を証明すること。下記ブロックを主張ごとに繰り返し、見出しにAC IDまたは主張IDを記載して下流のレビューが主張ごとにカバレッジを解決できるようにする。)
92
+ (このタスクがカバーするAC・主張・該当する故障モードチェックリストのカテゴリごとに1エントリ。スケルトンの注釈がある場合はそこから、なければACの主要な故障モードまたはマッピングされた故障モードカテゴリから導出する。各テストは主張を証明すること。下記ブロックを主張ごとに繰り返し、見出しにAC ID・主張ID・`Failure Mode: <category>` のいずれかを記載して下流のレビューが主張ごとにカバレッジを解決できるようにする。)
78
93
 
79
- ### Obligation: [AC IDまたは主張ID]
80
- - **主張**: [ACが約束する振る舞い]
94
+ ### Obligation: [AC ID・主張ID・故障モードカテゴリのいずれか — 例: `Failure Mode: missing-sort-key ordering`]
95
+ - **主張**: [このタスクが証明すべき、ACの振る舞い・主張・故障モード条件]
81
96
  - **主要な故障モード**: [テストがレッドになるリグレッション]
82
97
  - **検証する境界**: [テストが通過する公開/統合境界、または "in-process unit"]
83
98
  - **状態アサーション**: [状態変更を伴う主張では 操作前 → 操作 → 操作後 の観察可能な状態。それ以外は "N/A"]
@@ -91,6 +106,7 @@ Metadata:
91
106
  - [ ] 成果物作成完了(調査・設計タスクの場合)
92
107
  - [ ] (Binding Decisionsがある場合)全てのCompliance Checkが最終実装に対して`Y`と評価され、根拠(file:line、テスト結果、またはコマンド出力)がInvestigation Notesに記録されている
93
108
  - [ ] (Reference Contractsがある場合)全てのReference Contract Compliance Checkが最終実装に対して`Y`と評価され、根拠がInvestigation Notesに記録されている
109
+ - [ ] (Decisions and Unresolved Itemsがある場合)解決済みの各決定が記録どおりに適用され、ブロッキングな未解決項目が未解決のまま残っていない — 残っている場合は実行を停止し、その Escalation Condition に従ってエスカレーションする
94
110
 
95
111
  ## Notes
96
112
  - 影響範囲: [変更が波及する可能性のある領域]
@@ -0,0 +1,80 @@
1
+ ---
2
+ name: llm-friendly-context
3
+ description: 入力・出力・成功基準・決定事項・未解決条件を明確化し、下流エージェントが推測せず実行できるようにする。LLM向けのプロンプト・ハンドオフ・計画成果物・レビュー・レポート・生成指示を記述または改訂する時に使用。
4
+ ---
5
+
6
+ # LLM-Friendly Context
7
+
8
+ 目標は、下流が安定して実行できるようにすることである。次のエージェントが、何を読み、何をし、何をもって成功とし、いつ停止・エスカレーションするかを把握できる状態を目指す。
9
+
10
+ 本スキルはLLM向け出力(プロンプト、ハンドオフ、生成物)の明確さを扱う。どのドキュメントを作成するか、その必須構造が何かは定義しない。それはdocumentation-criteriaの責務である。
11
+
12
+ ## 中核ルール
13
+
14
+ 1. **肯定形で実行可能な指示を使う**
15
+ - 次のエージェントが何をすべきかを述べる。
16
+ - 品質ポリシーは肯定的な基準に変換する。
17
+ - 例: 「文書化された互換ケース全体で、既存の公開API挙動を維持する」
18
+
19
+ 2. **曖昧な指示を具体化する**
20
+ - 主観的な語を、観察可能な条件・パス・コマンド・スキーマ・例・判断ルールに置き換える。
21
+ - 次のエージェントに判断を委ねてしまい、明確化が必要になりやすい語: `appropriate`、`proper`、`related`、`existing behavior`、`optional`、`as needed`、`if needed`、`per convention`、未解決の代替案、`TBD`、`placeholder`。
22
+
23
+ 3. **出力構造を指定する**
24
+ - 必須のセクション・フィールド・表のカラム・JSONキー・チェックリスト項目を定義する。
25
+ - ハンドオフでは、生成した成果物のパスと、呼び出し側が確認すべき正確なステータスフィールドを含める。
26
+
27
+ 4. **必要なコンテキストを与える**
28
+ - 目的・出典となる成果物・厳格な制約・合意済みの決定・未解決条件を含める。
29
+ - 大まかなモジュール名より、具体的なファイルパスとセクションヒントを優先する。
30
+
31
+ 5. **複雑な作業を検証可能なステップに分解する**
32
+ - 目的が3つ以上、または逐次的な依存がある作業は、順序付きのステップに分割する。
33
+ - 各ステップには、完了を証明する根拠を示すチェックポイントを設ける。
34
+
35
+ 6. **不確実性を明示的に許可する**
36
+ - 出典が欠落・矛盾・検証不能な場合は、その不確実性と必要なエスカレーションを述べる。
37
+ - ビジネス・プロダクト・セキュリティ・互換性に関する未知の決定は、解決に必要な入力とエスカレーション条件を付したブロッキングな未解決項目として記録する。
38
+ - ブロッキングな未解決項目は、成果物を問わず一貫した形式で書く: `Unresolved: <必要な決定> — required input: <解決に必要な入力(必要なら確認先も)> — escalation: <次のエージェントが推測せず停止すべき条件>`。
39
+
40
+ 7. **制約を比例的に保つ**
41
+ - 曖昧さを減らす、または実在の要件を保つ制約のみを追加する。
42
+ - 対象アクション・コンテキスト・成功基準が既に明確な単純な下流タスクは、軽量なまま保つ。
43
+
44
+ ## 書き換えパターン
45
+
46
+ プロンプト・ハンドオフ・成果物を完成とみなす前に、以下の書き換えを適用する。
47
+
48
+ | 曖昧な形 | 書き換え後 |
49
+ |---|---|
50
+ | 未解決の選択として使われる `optional` | 必須・省略・特定条件下でのみ必須、のいずれか |
51
+ | 次のエージェントが選ばねばならない複数の代替案 | 選択した選択肢、または決定的な判断ルール |
52
+ | `as needed` / `if needed` | 発動条件と必要なアクション |
53
+ | `per convention` | 従うべきファイル・関数・テスト・文書化された規約 |
54
+ | `related files` | 具体的なパス・glob・サーチヒント |
55
+ | `existing behavior` | 維持すべき観察可能な挙動・出典ファイル・テスト・APIレスポンス・UI状態 |
56
+ | `placeholder` | 正確な暫定値/挙動・許容される依存・検証の期待値 |
57
+ | 必須情報のプレースホルダとして使われる `TBD` | required inputとescalation conditionを付したブロッキングな未解決項目(判明していればownerも) |
58
+ | `appropriate` / `proper` | 測定可能な基準またはチェックリスト |
59
+
60
+ ## ハンドオフチェックリスト
61
+
62
+ プロンプトや成果物を別のエージェントに渡す前に確認する:
63
+
64
+ - [ ] 対象アクションが明示されている。
65
+ - [ ] 必須の入力パスと出典成果物が名指しされている。
66
+ - [ ] 合意済みの決定と制約が、言い換えなしに一度だけ記載されている。
67
+ - [ ] 出力形式または期待されるステータスフィールドが指定されている。
68
+ - [ ] 成功基準が観察可能である。
69
+ - [ ] 曖昧な表現が書き換え済み、または未解決として明示されている。
70
+ - [ ] 次のエージェントが、明示的な選択・判断ルール・ブロッキングな未解決項目によって自身のスコープを完了できる。
71
+
72
+ ## 生成物チェックリスト
73
+
74
+ 生成ドキュメントを記述・確定する前に確認する:
75
+
76
+ - [ ] 各要件・主張・タスク・テストスケルトン・レビュー所見が、なぜ存在するかを辿れるだけの出典コンテキストを持つ。
77
+ - [ ] 実行可能な各指示が、対象・アクション・期待結果を名指ししている。
78
+ - [ ] 検証ステップが、何を実行/観察するか、どの結果が成功を証明するかを述べている。
79
+ - [ ] ある成果物が別の成果物から導出される場合、コピーした決定が文言と意味の両面で一貫している。
80
+ - [ ] 下流作業が情報欠落でブロックされる場合、成果物が欠落している入力とエスカレーション条件を記録している。
@@ -180,6 +180,21 @@ skills:
180
180
  - "9つの編集原則"
181
181
  - "References"
182
182
 
183
+ llm-friendly-context:
184
+ skill: "llm-friendly-context"
185
+ tags: [universal, cross-cutting, prompt, handoff, artifact, clarity, ambiguity-removal, downstream-execution, documentation]
186
+ typical-use: "LLM向けのプロンプト・ハンドオフ・計画成果物・レビュー・レポート・生成指示を記述/改訂し、下流エージェントが推測せず実行できるようにする"
187
+ size: small
188
+ key-references:
189
+ - "禁止形より肯定形の実行可能な指示"
190
+ - "エージェント間ハンドオフの観察可能な成功基準"
191
+ - "暗黙の曖昧さより明示的な未解決項目"
192
+ sections:
193
+ - "中核ルール"
194
+ - "書き換えパターン"
195
+ - "ハンドオフチェックリスト"
196
+ - "生成物チェックリスト"
197
+
183
198
  # フロントエンド固有スキル
184
199
  frontend-typescript-rules:
185
200
  skill: "frontend-typescript-rules"
package/CHANGELOG.md CHANGED
@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [1.25.0] - 2026-06-25
9
+
10
+ ### Added
11
+
12
+ - **LLM-friendly context skill** (agents, skills, commands) — added the `llm-friendly-context` skill so prompts, handoffs, and generated artifacts state explicit inputs, output structure, success criteria, decisions, and blocking unresolved items, wired into the 11 artifact-producing agents and invoked by the 15 orchestrator commands before they construct Agent prompts, handoffs, or generated artifacts. `document-reviewer` gains an LLM-facing artifact clarity check (`clarity` category); `task-decomposer` gains self-checks for unresolved alternatives/optional behavior, placeholder output, commit-boundary viability, and decision preservation, and records resolved choices and blocking unresolved items in a new `Decisions and Unresolved Items` task-template section. The redundant task-decomposer recap section was trimmed losslessly. Applied across en/ja.
13
+
14
+ ## [1.24.2] - 2026-06-23
15
+
16
+ ### Added
17
+
18
+ - **Failure-mode and spec-completeness coverage** (agents, skills) — added a ninth domain-independent failure category (`missing-sort-key ordering`), a mode × branch AC-expansion step in technical design, and reset/clear state captured as a `state-lifecycle-negative` contract. Failure Mode Checklist categories now propagate from the work plan to task Proof Obligations and are verified in review (`code-reviewer`, `integration-test-reviewer`), with a deterministic fallback when task files are absent so AC-less obligations are not silently treated as verified. Applied across en/ja.
19
+
8
20
  ## [1.24.1] - 2026-06-21
9
21
 
10
22
  ### Changed
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-ai-project",
3
- "version": "1.24.1",
3
+ "version": "1.25.0",
4
4
  "packageManager": "npm@10.8.2",
5
5
  "description": "TypeScript boilerplate with skills and sub-agents for Claude Code. Prevents context exhaustion through role-based task splitting.",
6
6
  "keywords": [