create-ai-project 1.23.3 → 1.23.5

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 (77) hide show
  1. package/.claude/agents-en/acceptance-test-generator.md +8 -31
  2. package/.claude/agents-en/code-reviewer.md +15 -24
  3. package/.claude/agents-en/code-verifier.md +3 -32
  4. package/.claude/agents-en/codebase-analyzer.md +10 -78
  5. package/.claude/agents-en/document-reviewer.md +10 -57
  6. package/.claude/agents-en/integration-test-reviewer.md +6 -37
  7. package/.claude/agents-en/investigator.md +6 -59
  8. package/.claude/agents-en/quality-fixer-frontend.md +4 -8
  9. package/.claude/agents-en/quality-fixer.md +4 -8
  10. package/.claude/agents-en/requirement-analyzer.md +3 -14
  11. package/.claude/agents-en/rule-advisor.md +3 -16
  12. package/.claude/agents-en/scope-discoverer.md +5 -29
  13. package/.claude/agents-en/security-reviewer.md +2 -13
  14. package/.claude/agents-en/skill-creator.md +3 -6
  15. package/.claude/agents-en/skill-reviewer.md +7 -43
  16. package/.claude/agents-en/solver.md +9 -24
  17. package/.claude/agents-en/task-decomposer.md +19 -1
  18. package/.claude/agents-en/task-executor-frontend.md +15 -20
  19. package/.claude/agents-en/task-executor.md +15 -20
  20. package/.claude/agents-en/ui-analyzer.md +16 -115
  21. package/.claude/agents-en/verifier.md +9 -53
  22. package/.claude/agents-en/work-planner.md +2 -5
  23. package/.claude/agents-ja/acceptance-test-generator.md +8 -31
  24. package/.claude/agents-ja/code-reviewer.md +15 -24
  25. package/.claude/agents-ja/code-verifier.md +3 -32
  26. package/.claude/agents-ja/codebase-analyzer.md +10 -78
  27. package/.claude/agents-ja/document-reviewer.md +10 -57
  28. package/.claude/agents-ja/integration-test-reviewer.md +6 -37
  29. package/.claude/agents-ja/investigator.md +6 -59
  30. package/.claude/agents-ja/quality-fixer-frontend.md +4 -8
  31. package/.claude/agents-ja/quality-fixer.md +4 -8
  32. package/.claude/agents-ja/requirement-analyzer.md +3 -14
  33. package/.claude/agents-ja/rule-advisor.md +3 -16
  34. package/.claude/agents-ja/scope-discoverer.md +5 -29
  35. package/.claude/agents-ja/security-reviewer.md +2 -13
  36. package/.claude/agents-ja/skill-creator.md +3 -6
  37. package/.claude/agents-ja/skill-reviewer.md +7 -43
  38. package/.claude/agents-ja/solver.md +9 -24
  39. package/.claude/agents-ja/task-decomposer.md +19 -1
  40. package/.claude/agents-ja/task-executor-frontend.md +15 -20
  41. package/.claude/agents-ja/task-executor.md +15 -20
  42. package/.claude/agents-ja/ui-analyzer.md +16 -115
  43. package/.claude/agents-ja/verifier.md +9 -53
  44. package/.claude/agents-ja/work-planner.md +2 -5
  45. package/.claude/commands-en/build.md +6 -15
  46. package/.claude/commands-en/front-build.md +4 -13
  47. package/.claude/commands-en/implement.md +2 -15
  48. package/.claude/commands-en/plan.md +7 -2
  49. package/.claude/commands-en/prepare-implementation.md +7 -17
  50. package/.claude/commands-en/sync-skills.md +3 -3
  51. package/.claude/commands-ja/build.md +7 -16
  52. package/.claude/commands-ja/front-build.md +4 -13
  53. package/.claude/commands-ja/implement.md +2 -15
  54. package/.claude/commands-ja/plan.md +6 -1
  55. package/.claude/commands-ja/prepare-implementation.md +8 -18
  56. package/.claude/commands-ja/sync-skills.md +3 -3
  57. package/.claude/skills-en/documentation-criteria/references/plan-template.md +1 -3
  58. package/.claude/skills-en/documentation-criteria/references/task-template.md +8 -0
  59. package/.claude/skills-en/frontend-technical-spec/SKILL.md +4 -8
  60. package/.claude/skills-en/frontend-typescript-rules/SKILL.md +4 -2
  61. package/.claude/skills-en/frontend-typescript-testing/SKILL.md +5 -11
  62. package/.claude/skills-en/integration-e2e-testing/SKILL.md +2 -0
  63. package/.claude/skills-en/subagents-orchestration-guide/SKILL.md +2 -7
  64. package/.claude/skills-en/technical-spec/SKILL.md +4 -3
  65. package/.claude/skills-en/typescript-testing/SKILL.md +4 -4
  66. package/.claude/skills-ja/documentation-criteria/references/plan-template.md +1 -3
  67. package/.claude/skills-ja/documentation-criteria/references/task-template.md +8 -0
  68. package/.claude/skills-ja/frontend-technical-spec/SKILL.md +4 -8
  69. package/.claude/skills-ja/frontend-typescript-rules/SKILL.md +4 -2
  70. package/.claude/skills-ja/frontend-typescript-testing/SKILL.md +5 -11
  71. package/.claude/skills-ja/integration-e2e-testing/SKILL.md +2 -0
  72. package/.claude/skills-ja/subagents-orchestration-guide/SKILL.md +2 -7
  73. package/.claude/skills-ja/task-analyzer/references/skills-index.yaml +3 -3
  74. package/.claude/skills-ja/technical-spec/SKILL.md +4 -3
  75. package/.claude/skills-ja/typescript-testing/SKILL.md +4 -4
  76. package/CHANGELOG.md +16 -0
  77. package/package.json +1 -1
@@ -18,9 +18,9 @@ Work plan: $ARGUMENTS
18
18
 
19
19
  ## Pre-execution Prerequisites
20
20
 
21
- ### Implementation Readiness Check
21
+ ### Work Plan Resolution
22
22
 
23
- Before any task processing, locate the work plan to gate against.
23
+ Before any task processing, locate the work plan.
24
24
 
25
25
  **When `$ARGUMENTS` is provided**, it is the work plan path supplied by the user. Use it directly without auto-resolution. Extract `{plan-name}` from the filename by stripping the `.md` extension (and any trailing `-plan` suffix when present).
26
26
 
@@ -51,27 +51,18 @@ Before any task processing, locate the work plan to gate against.
51
51
  - Otherwise (no backend signal found, OR any frontend signal present, OR layer-neutral paths only) → stop and report: "Cannot positively verify the most-recent work plan at `[path]` is a backend plan (signals examined: [list of signals checked and their results]). Pass the intended backend plan path as `$ARGUMENTS`, or run task-decomposer first to populate `docs/plans/tasks/` with backend-named task files."
52
52
  7. When no plan exists at all in `docs/plans/`, stop and report: "No work plan found. Pass a work plan path as `$ARGUMENTS`, or complete the planning phase first."
53
53
 
54
- Read the work plan header and find the line `Implementation Readiness: <status>`. Apply this rule:
55
-
56
- | Status | Action |
57
- |--------|--------|
58
- | `ready` | Proceed to Consumed Task Set computation |
59
- | `escalated` | Read the work plan's Readiness Report section, surface remaining gaps to the user via AskUserQuestion: "Implementation Readiness is `escalated` with the following remaining gaps: [list]. Continue execution? (y/n)". On `y` proceed; on `n` stop |
60
- | `pending` | Present via AskUserQuestion: "Implementation Readiness is `pending`. Run the readiness preflight first to verify the work plan is implementable, then resume. Continue without preflight? (y/n)". On `y` proceed; on `n` stop |
61
- | absent (line missing) | Treat as `pending` — older work plans created before the readiness marker existed should be preflighted explicitly |
62
-
63
54
  ### Consumed Task Set
64
55
 
65
- Compute the **Consumed Task Set** for this run — the exact files this recipe owns, executes, and later deletes. Use the same consumable patterns as the Implementation Readiness Check:
56
+ Compute the **Consumed Task Set** for this run — the exact files this recipe owns, executes, and later deletes. Use the same consumable patterns as Work Plan Resolution:
66
57
 
67
- 1. List task files in `docs/plans/tasks/` matching `{plan-name}-task-*.md` OR `{plan-name}-backend-task-*.md` for the `{plan-name}` resolved by the readiness check. `{plan-name}-frontend-task-*.md` is excluded — it is owned by the frontend build recipe
58
+ 1. List task files in `docs/plans/tasks/` matching `{plan-name}-task-*.md` OR `{plan-name}-backend-task-*.md` for the `{plan-name}` resolved by Work Plan Resolution. `{plan-name}-frontend-task-*.md` is excluded — it is owned by the frontend build recipe
68
59
  2. Exclude every file matching: `*-task-prep-*.md`, `_overview-*.md`, `*-phase*-completion.md`, `review-fixes-*.md`, `integration-tests-*-task-*.md` (these originate from other workflow phases)
69
60
 
70
61
  Every subsequent reference to "task files" in this recipe — Task Generation Decision Flow, Task Execution Cycle iteration, and Final Cleanup — uses this set, not the unrestricted `docs/plans/tasks/*.md` glob.
71
62
 
72
63
  ### Task Generation Decision Flow
73
64
 
74
- Analyze the Consumed Task Set and determine the action required. Reaching this section implies the readiness check above resolved a work plan (Steps 1-6 succeeded); the "no plan" state is already terminated by readiness-check Step 7 and never reaches this table.
65
+ Analyze the Consumed Task Set and determine the action required. Reaching this section implies Work Plan Resolution above resolved a work plan (Steps 1-6 succeeded); the "no plan" state is already terminated by Work Plan Resolution Step 7 and never reaches this table.
75
66
 
76
67
  | State | Criteria | Next Action |
77
68
  |-------|----------|-------------|
@@ -79,7 +70,7 @@ Analyze the Consumed Task Set and determine the action required. Reaching this s
79
70
  | No tasks + plan supplied via `$ARGUMENTS` | `$ARGUMENTS` provided AND Consumed Task Set empty | Confirm with user → run task-decomposer |
80
71
  | No tasks + plan auto-resolved | Consumed Task Set empty AND plan came from auto-resolution AND Step 6 confirmed at least one backend signal with zero frontend signals | Confirm with user → run task-decomposer (the layer verification in Step 6 already excluded frontend and ambiguous plans, so this is safe) |
81
72
 
82
- To bootstrap from a Design Doc when no plan exists yet, run the planning recipe first to produce a work plan, then re-invoke this recipe — the readiness check above intentionally requires a resolved work plan rather than auto-creating one, to keep the layer decision explicit.
73
+ To bootstrap from a Design Doc when no plan exists yet, run the planning recipe first to produce a work plan, then re-invoke this recipe — Work Plan Resolution above intentionally requires a resolved work plan rather than auto-creating one, to keep the layer decision explicit.
83
74
 
84
75
  ## Task Decomposition Phase (Conditional)
85
76
 
@@ -18,9 +18,9 @@ Work plan: $ARGUMENTS
18
18
 
19
19
  ## Pre-execution Prerequisites
20
20
 
21
- ### Implementation Readiness Check
21
+ ### Work Plan Resolution
22
22
 
23
- Before any task processing, locate the work plan to gate against.
23
+ Before any task processing, locate the work plan.
24
24
 
25
25
  **When `$ARGUMENTS` is provided**, it is the work plan path supplied by the user. Use it directly without auto-resolution. Extract `{plan-name}` from the filename by stripping the `.md` extension (and any trailing `-plan` suffix when present).
26
26
 
@@ -33,27 +33,18 @@ Before any task processing, locate the work plan to gate against.
33
33
  4. When at least one task file matches, the work plan is `docs/plans/{plan-name}.md` for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last `{plan-name}`
34
34
  5. When no `*-frontend-task-*.md` is found AND a non-template work plan exists in `docs/plans/`, do not assume the most-recent plan applies — frontend tasks must be explicitly named. Stop and report: "No `*-frontend-task-*.md` found in `docs/plans/tasks/`. If you intended to run this recipe on a frontend plan, either re-run task-decomposer so it emits frontend-named task files, or pass the work plan path as `$ARGUMENTS`. If the plan is backend, use the backend build recipe instead."
35
35
 
36
- Read the work plan header and find the line `Implementation Readiness: <status>`. Apply this rule:
37
-
38
- | Status | Action |
39
- |--------|--------|
40
- | `ready` | Proceed to Consumed Task Set computation |
41
- | `escalated` | Read the work plan's Readiness Report section, surface remaining gaps to the user via AskUserQuestion: "Implementation Readiness is `escalated` with the following remaining gaps: [list]. Continue execution? (y/n)". On `y` proceed; on `n` stop |
42
- | `pending` | Present via AskUserQuestion: "Implementation Readiness is `pending`. Run the readiness preflight first to verify the work plan is implementable, then resume. Continue without preflight? (y/n)". On `y` proceed; on `n` stop |
43
- | absent (line missing) | Treat as `pending` — older work plans created before the readiness marker existed should be preflighted explicitly |
44
-
45
36
  ### Consumed Task Set
46
37
 
47
38
  Compute the **Consumed Task Set** for this run — the exact files this recipe owns, executes, and later deletes. Per the routing table, the only consumable pattern is:
48
39
 
49
- 1. List task files in `docs/plans/tasks/` matching `{plan-name}-frontend-task-*.md` for the `{plan-name}` resolved by the readiness check. `{plan-name}-task-*.md` and `{plan-name}-backend-task-*.md` are excluded — they route to `task-executor` and are owned by the backend build recipe
40
+ 1. List task files in `docs/plans/tasks/` matching `{plan-name}-frontend-task-*.md` for the `{plan-name}` resolved by Work Plan Resolution. `{plan-name}-task-*.md` and `{plan-name}-backend-task-*.md` are excluded — they route to `task-executor` and are owned by the backend build recipe
50
41
  2. Exclude every file matching: `*-task-prep-*.md`, `_overview-*.md`, `*-phase*-completion.md`, `review-fixes-*.md`, `integration-tests-*-task-*.md` (these originate from other workflow phases)
51
42
 
52
43
  Every subsequent reference to "task files" in this recipe — Task Generation Decision Flow, Task Execution Cycle iteration, and Final Cleanup — uses this set, not the unrestricted `docs/plans/tasks/*.md` glob.
53
44
 
54
45
  ### Task Generation Decision Flow
55
46
 
56
- Analyze the Consumed Task Set and determine the action required. Note: when `$ARGUMENTS` is empty AND no `*-frontend-task-*.md` exist, the readiness check above already stops execution — so the rows below that involve "no tasks" only fire when the user explicitly supplied `$ARGUMENTS`.
47
+ Analyze the Consumed Task Set and determine the action required. Note: when `$ARGUMENTS` is empty AND no `*-frontend-task-*.md` exist, Work Plan Resolution above already stops execution — so the rows below that involve "no tasks" only fire when the user explicitly supplied `$ARGUMENTS`.
57
48
 
58
49
  | State | Criteria | Next Action |
59
50
  |-------|----------|-------------|
@@ -45,7 +45,7 @@ After scale determination, **register all steps of the applicable subagents-orch
45
45
 
46
46
  **Check next pending task with TaskList**.
47
47
 
48
- ## 📋 subagents-orchestration-guide skill Compliance Execution
48
+ ## subagents-orchestration-guide skill Compliance Execution
49
49
 
50
50
  **Pre-execution Checklist (Required)**:
51
51
  - [ ] Confirmed relevant subagents-orchestration-guide skill flow
@@ -58,19 +58,6 @@ After scale determination, **register all steps of the applicable subagents-orch
58
58
 
59
59
  **Flow Adherence**: Follow "Autonomous Execution Task Management" in subagents-orchestration-guide skill, managing 4 steps with TaskCreate/TaskUpdate
60
60
 
61
- ## Implementation Readiness Check (between work-planner approval and task-decomposer)
62
-
63
- After work-planner completes and the user grants batch approval, before invoking task-decomposer, read the work plan header and find the line `Implementation Readiness: <status>`. Apply this rule:
64
-
65
- | Status | Action |
66
- |--------|--------|
67
- | `ready` | Proceed to task-decomposer |
68
- | `escalated` | Read the work plan's Readiness Report section, surface remaining gaps to the user via AskUserQuestion: "Implementation Readiness is `escalated` with the following remaining gaps: [list]. Continue execution? (y/n)". On `y` proceed; on `n` stop |
69
- | `pending` | Present via AskUserQuestion: "Implementation Readiness is `pending`. Run the readiness preflight first to verify the work plan is implementable, then resume. Continue without preflight? (y/n)". On `y` proceed; on `n` stop |
70
- | absent (line missing) | Treat as `pending` — older work plans created before the readiness marker existed should be preflighted explicitly |
71
-
72
- This check applies to all scales (Small / Medium / Large) because this recipe is the scale-agnostic orchestrator.
73
-
74
61
  ## Scope Boundary for Subagents
75
62
 
76
63
  Append the following block to every subagent prompt invoked from this recipe:
@@ -87,7 +74,7 @@ Additionally, include the following constraint at the end of every sub-agent pro
87
74
  [Constraint] rule-advisor can only be used by Main AI
88
75
  ```
89
76
 
90
- ## 🎯 Mandatory Orchestrator Responsibilities
77
+ ## Mandatory Orchestrator Responsibilities
91
78
 
92
79
  ### Task Execution Quality Cycle
93
80
  Following "Autonomous Execution Task Management" in subagents-orchestration-guide skill, manage these steps with TaskCreate/TaskUpdate:
@@ -76,11 +76,16 @@ Create a work plan from the selected design document, clarifying specific implem
76
76
  **Scope**: Up to work plan creation and obtaining approval for plan content.
77
77
 
78
78
  ## Response at Completion
79
- **REQUIRED**: End with the following standard response after plan content approval
79
+ **REQUIRED**: After plan content approval, output the following standard response
80
80
  ```
81
81
  Planning phase completed.
82
82
  - Work plan: docs/plans/[plan-name].md
83
83
  - Status: Approved
84
84
 
85
85
  Please provide separate instructions for implementation.
86
- ```
86
+ ```
87
+
88
+ When the approved plan includes any of the following — E2E test skeletons; a Verification Strategy referencing commands, files, functions, or endpoints not yet in the codebase; UI components without a fixture entry or dev route to render their states; or a local lane not yet confirmed to run end-to-end — append one more line as the final line of the response (omit it otherwise):
89
+ ```
90
+ Optional preflight: `/prepare-implementation docs/plans/[plan-name].md` verifies these are implementable before build (exits no-op when readiness criteria already pass).
91
+ ```
@@ -11,7 +11,7 @@ description: Verify implementation readiness and resolve gaps before the build p
11
11
  **Execution Protocol**:
12
12
  1. **Delegate all work through Agent tool** — invoke sub-agents (task-executor / task-executor-frontend / quality-fixer / quality-fixer-frontend), pass deliverable paths between them, and report results
13
13
  2. **Self-contained scope**: When gaps are found, this recipe BOTH generates resolution tasks AND executes them through the standard 4-step cycle described in subagents-orchestration-guide "Standard Flow I Manage". Recipe completes only when readiness criteria pass or remaining gaps are escalated.
14
- 3. **No-op exit**: When the readiness scan finds no failing criteria, generate no resolution tasks and exit immediately. The only file modifications in this branch are to the work plan itself — promoting the `Implementation Readiness:` header to `ready` and persisting the Readiness Report section. No code or test files are touched.
14
+ 3. **No-op exit**: When the readiness scan finds no failing criteria, generate no resolution tasks and exit immediately, presenting the Readiness Report to the user. No files are modified in this branch.
15
15
 
16
16
  Work plan: $ARGUMENTS
17
17
 
@@ -74,11 +74,9 @@ Build the Readiness Report (see Output Format) regardless of outcome.
74
74
  ### Step 3: No-op Check
75
75
 
76
76
  When every applicable criterion is `pass` (zero `fail`):
77
- - Append (or replace, if already present) a `## Implementation Readiness Report` section in the work plan immediately after the header block, using the same Readiness Report markdown defined in Output Format below
78
- - Update the work plan header `Implementation Readiness:` line to `ready` (insert it after `Related Issue/PR:` if absent)
79
- - Present the Readiness Report to the user
77
+ - Present the Readiness Report (see Output Format below) to the user
80
78
  - Exit with `outcome: ready, gaps_resolved: 0`
81
- - The work plan modifications above are the only file modifications in this branch
79
+ - No files are modified in this branch
82
80
 
83
81
  When one or more criteria are `fail` → proceed to Step 4.
84
82
 
@@ -115,20 +113,13 @@ For each resolution task, run the 4-step cycle `task-executor → escalation che
115
113
 
116
114
  Append the Scope Boundary block (below) to every subagent prompt.
117
115
 
118
- ### Step 6: Re-scan, Persist Readiness Report, Update Header, Cleanup, Exit
116
+ ### Step 6: Re-scan, Record Phase 0 Completion, Present Readiness Report, Cleanup, Exit
119
117
 
120
118
  1. **Re-scan**: Re-run the Step 2 readiness scan after all resolution tasks are committed.
121
119
 
122
- 2. **Persist Readiness Report into work plan body**: Append (or replace, if already present) a `## Implementation Readiness Report` section in the work plan immediately after the header block. Use the same Readiness Report markdown defined in Output Format below. Downstream build/implement recipes read this section when the header is `escalated` to surface remaining gaps to the user.
120
+ 2. **Record Phase 0 completion in the work plan**: For each Phase 0 resolution task that was committed, check off its checkbox (`[x]`) in the work plan's Phase 0 section and annotate it as committed (append ` committed`). This records the durable outcome in the plan so the downstream task-decomposer skips already-committed Phase 0 work instead of regenerating and re-executing it.
123
121
 
124
- 3. **Update work plan header**: Locate the line `Implementation Readiness: pending` in the work plan and rewrite it based on the re-scan outcome:
125
-
126
- | Re-scan result | New header value |
127
- |----------------|------------------|
128
- | All applicable criteria `pass` | `Implementation Readiness: ready` |
129
- | One or more `fail` remain | `Implementation Readiness: escalated` |
130
-
131
- If the line is absent (older work plan format), insert it after the `Related Issue/PR:` line.
122
+ 3. **Present Readiness Report**: Present the Readiness Report (see Output Format below) to the user. The report is shown in-session and is not written into the work plan the durable output of this recipe is the committed Phase 0 resolution tasks (recorded as completed in the plan per Step 6.2), not a persisted report.
132
123
 
133
124
  4. **Final Cleanup**: Delete every prep task file this recipe created for the current `{plan-name}` (`docs/plans/tasks/{plan-name}-backend-task-prep-*.md` and `docs/plans/tasks/{plan-name}-frontend-task-prep-*.md`) AND the phase-completion file generated for prep phases (`docs/plans/tasks/{plan-name}-phase0-completion.md` when present, since prep tasks live in Phase 0). Prep task files for other plans are out of scope — this recipe deletes only what it created for the current run. Their work is committed; `docs/plans/` is ephemeral working state and is not retained between recipe runs. The work plan itself is preserved for the downstream build/implement phase.
134
125
 
@@ -185,7 +176,6 @@ Gaps resolved: [N]
185
176
  - [ ] Readiness scan run with per-criterion result and evidence recorded
186
177
  - [ ] No-op exit when all `pass`, OR resolution tasks generated, approved, and executed via the 4-step cycle
187
178
  - [ ] Re-scan run after the last resolution task commits
188
- - [ ] `## Implementation Readiness Report` section persisted into the work plan body
189
- - [ ] Work plan header `Implementation Readiness:` line updated to `ready` or `escalated`
179
+ - [ ] Committed Phase 0 tasks checked off (`[x]`) in the work plan so downstream decomposition skips them
190
180
  - [ ] Prep task files (and Phase 0 phase-completion file when generated) deleted from `docs/plans/tasks/`
191
181
  - [ ] Final report presented to the user
@@ -43,9 +43,9 @@ Present proposals to user and apply after approval:
43
43
 
44
44
  ```
45
45
  [1/N] typescript-rules
46
- sections: synchronized
47
- 💡 tags proposed: +[functional-programming]
48
- 💡 typical-use: "old description" → "new description"
46
+ sections: synchronized
47
+ tags proposed: +[functional-programming]
48
+ typical-use: "old description" → "new description"
49
49
  ```
50
50
 
51
51
  ## Completion Criteria
@@ -18,9 +18,9 @@ description: 分解済みタスクを自律実行モードで実装
18
18
 
19
19
  ## 実行前提条件
20
20
 
21
- ### Implementation Readinessチェック
21
+ ### 作業計画書の解決
22
22
 
23
- タスク処理の前に、ゲート対象となる作業計画書を特定する。
23
+ タスク処理の前に、作業計画書を特定する。
24
24
 
25
25
  **`$ARGUMENTS`が指定されている場合**は、それがユーザーから渡された作業計画書のパスである。自動解決を行わずそのまま使用する。`{plan-name}`はファイル名から `.md` 拡張子(および末尾に `-plan` がある場合はそれも)を除いて抽出する。
26
26
 
@@ -51,35 +51,26 @@ description: 分解済みタスクを自律実行モードで実装
51
51
  - それ以外(backend 信号がない、または frontend 信号が1つでもある、または layer-neutral なパスのみ)→ 停止して報告する: 「最も新しい作業計画書 `[path]` が backend 計画であることを確証できません(確認した信号と結果: [リスト])。意図する backend 計画書のパスを `$ARGUMENTS` で指定するか、task-decomposer を先に実行して `docs/plans/tasks/` に backend 命名のタスクファイルを出力してください。」
52
52
  7. `docs/plans/`に計画書が一切存在しない場合は、停止して報告する: 「作業計画書が見つかりません。作業計画書のパスを `$ARGUMENTS` で指定するか、計画フェーズを先に完了してください。」
53
53
 
54
- 作業計画書のヘッダを読み、`Implementation Readiness: <status>`の行を見つける。以下のルールを適用する:
55
-
56
- | ステータス | アクション |
57
- |--------|--------|
58
- | `ready` | Consumed Task Set の計算へ進む |
59
- | `escalated` | 作業計画書のReadiness Reportセクションを読み、AskUserQuestionで残存ギャップをユーザーに提示する: 「Implementation Readinessが`escalated`で、以下の残存ギャップがあります: [リスト]。実行を継続しますか?(y/n)」。`y`なら進む、`n`なら停止 |
60
- | `pending` | AskUserQuestionで提示する: 「Implementation Readinessが`pending`です。事前にreadiness preflightを実行して作業計画書の実装可能性を検証してから再開してください。preflightなしで継続しますか?(y/n)」。`y`なら進む、`n`なら停止 |
61
- | 行が存在しない | `pending`として扱う — readinessマーカー導入前に作成された古い作業計画書は明示的にpreflightすべき |
62
-
63
54
  ### Consumed Task Set
64
55
 
65
- 本実行で消費する **Consumed Task Set** を計算する — 本レシピが所有・実行・後で削除する正確なファイル群。Implementation Readinessチェックと同じ消費可能パターンを使用する:
56
+ 本実行で消費する **Consumed Task Set** を計算する — 本レシピが所有・実行・後で削除する正確なファイル群。作業計画書の解決と同じ消費可能パターンを使用する:
66
57
 
67
- 1. Implementation Readinessチェックで解決した `{plan-name}` について、`docs/plans/tasks/`内で `{plan-name}-task-*.md` または `{plan-name}-backend-task-*.md` にマッチするタスクファイルを列挙する。`{plan-name}-frontend-task-*.md` は除外する — frontend build レシピが所有する
58
+ 1. 作業計画書の解決で確定した `{plan-name}` について、`docs/plans/tasks/`内で `{plan-name}-task-*.md` または `{plan-name}-backend-task-*.md` にマッチするタスクファイルを列挙する。`{plan-name}-frontend-task-*.md` は除外する — frontend build レシピが所有する
68
59
  2. 以下にマッチするファイルを除外する: `*-task-prep-*.md`、`_overview-*.md`、`*-phase*-completion.md`、`review-fixes-*.md`、`integration-tests-*-task-*.md`(これらは他のワークフローフェーズに由来する)
69
60
 
70
61
  本レシピ内で「タスクファイル」と参照する箇所すべて — タスク生成判定フロー、タスク実行サイクルの反復、最終クリーンアップ — はこのセットを使用する。`docs/plans/tasks/*.md` を制限なく glob しない。
71
62
 
72
63
  ### タスク生成判定フロー
73
64
 
74
- Consumed Task Set を確認し、適切な対応を決定する。注: 本セクションに到達するということは、上記の readiness check が作業計画書を解決済み(Steps 1-6 が成功)であることを意味する。「計画書なし」の状態は readiness check の Step 7 が既に終了させており、本表には到達しない。
65
+ Consumed Task Set を確認し、適切な対応を決定する。注: 本セクションに到達するということは、上記の作業計画書の解決(Steps 1-6 が成功)で作業計画書が確定済みであることを意味する。「計画書なし」の状態は作業計画書の解決の Step 7 が既に終了させており、本表には到達しない。
75
66
 
76
67
  | 状態 | 判定基準 | 次のアクション |
77
68
  |------|---------|--------------|
78
69
  | タスク存在 | Consumed Task Set が非空 | ユーザーの実行指示をバッチ承認として自律実行へ移行 |
79
70
  | タスクなし + `$ARGUMENTS`で計画書指定 | `$ARGUMENTS`が提供され Consumed Task Set が空 | ユーザーに確認 → task-decomposer実行 |
80
- | タスクなし + 計画書を自動解決 | Consumed Task Set が空かつ計画書が自動解決(readiness check の Step 6 経由)で得られ、backend 信号 ≥1 かつ frontend 信号 = 0 が確認済み | ユーザーに確認 → task-decomposer実行(Step 6 のレイヤー検証で frontend / 不確定な計画は既に除外されているため安全) |
71
+ | タスクなし + 計画書を自動解決 | Consumed Task Set が空かつ計画書が自動解決(作業計画書の解決の Step 6 経由)で得られ、backend 信号 ≥1 かつ frontend 信号 = 0 が確認済み | ユーザーに確認 → task-decomposer実行(Step 6 のレイヤー検証で frontend / 不確定な計画は既に除外されているため安全) |
81
72
 
82
- Design Doc から作業計画書がまだない状態で着手したい場合は、先に計画レシピを実行して計画書を生成してから本レシピを再起動する — 上記 readiness check は意図的に自動生成を行わず、レイヤー判断を明示的に保つ。
73
+ Design Doc から作業計画書がまだない状態で着手したい場合は、先に計画レシピを実行して計画書を生成してから本レシピを再起動する — 上記の作業計画書の解決は意図的に自動生成を行わず、レイヤー判断を明示的に保つ。
83
74
 
84
75
  ## タスク分解フェーズ(条件付き実行)
85
76
 
@@ -18,9 +18,9 @@ description: フロントエンド実装を自律実行モードで実行
18
18
 
19
19
  ## 実行前提条件
20
20
 
21
- ### Implementation Readinessチェック
21
+ ### 作業計画書の解決
22
22
 
23
- タスク処理の前に、ゲート対象となる作業計画書を特定する。
23
+ タスク処理の前に、作業計画書を特定する。
24
24
 
25
25
  **`$ARGUMENTS`が指定されている場合**は、それがユーザーから渡された作業計画書のパスである。自動解決を行わずそのまま使用する。`{plan-name}`はファイル名から `.md` 拡張子(および末尾に `-plan` がある場合はそれも)を除いて抽出する。
26
26
 
@@ -33,27 +33,18 @@ description: フロントエンド実装を自律実行モードで実行
33
33
  4. 少なくとも1つのタスクファイルがマッチした場合、最も新しい mtime を持つ `{plan-name}` の `docs/plans/{plan-name}.md` を作業計画書とする。タイは辞書順最大の `{plan-name}` で解決する
34
34
  5. `*-frontend-task-*.md` が見つからず、かつ `docs/plans/`に非テンプレートの作業計画書が存在する場合、最も新しい計画書を自動採用してはならない — frontend タスクは明示的に命名されている必要がある。停止して報告する: 「`docs/plans/tasks/`に `*-frontend-task-*.md` が見つかりませんでした。本レシピを frontend 計画に対して実行する意図であれば、task-decomposer を再実行して frontend 命名のタスクファイルを出力させるか、作業計画書のパスを `$ARGUMENTS` で指定してください。計画が backend ならば、backend build レシピを使用してください。」
35
35
 
36
- 作業計画書のヘッダを読み、`Implementation Readiness: <status>`の行を見つける。以下のルールを適用する:
37
-
38
- | ステータス | アクション |
39
- |--------|--------|
40
- | `ready` | Consumed Task Set の計算へ進む |
41
- | `escalated` | 作業計画書のReadiness Reportセクションを読み、AskUserQuestionで残存ギャップをユーザーに提示する: 「Implementation Readinessが`escalated`で、以下の残存ギャップがあります: [リスト]。実行を継続しますか?(y/n)」。`y`なら進む、`n`なら停止 |
42
- | `pending` | AskUserQuestionで提示する: 「Implementation Readinessが`pending`です。事前にreadiness preflightを実行して作業計画書の実装可能性を検証してから再開してください。preflightなしで継続しますか?(y/n)」。`y`なら進む、`n`なら停止 |
43
- | 行が存在しない | `pending`として扱う — readinessマーカー導入前に作成された古い作業計画書は明示的にpreflightすべき |
44
-
45
36
  ### Consumed Task Set
46
37
 
47
38
  本実行で消費する **Consumed Task Set** を計算する — 本レシピが所有・実行・後で削除する正確なファイル群。ルーティング表により、消費可能なパターンは1つだけ:
48
39
 
49
- 1. Implementation Readinessチェックで解決した `{plan-name}` について、`docs/plans/tasks/`内で `{plan-name}-frontend-task-*.md` にマッチするタスクファイルを列挙する。`{plan-name}-task-*.md` および `{plan-name}-backend-task-*.md` は除外する — `task-executor` にルーティングされ、backend build レシピが所有する
40
+ 1. 作業計画書の解決で確定した `{plan-name}` について、`docs/plans/tasks/`内で `{plan-name}-frontend-task-*.md` にマッチするタスクファイルを列挙する。`{plan-name}-task-*.md` および `{plan-name}-backend-task-*.md` は除外する — `task-executor` にルーティングされ、backend build レシピが所有する
50
41
  2. 以下にマッチするファイルを除外する: `*-task-prep-*.md`、`_overview-*.md`、`*-phase*-completion.md`、`review-fixes-*.md`、`integration-tests-*-task-*.md`(これらは他のワークフローフェーズに由来する)
51
42
 
52
43
  本レシピ内で「タスクファイル」と参照する箇所すべて — タスク生成判定フロー、タスク実行サイクルの反復、最終クリーンアップ — はこのセットを使用する。`docs/plans/tasks/*.md` を制限なく glob しない。
53
44
 
54
45
  ### タスク生成判定フロー
55
46
 
56
- Consumed Task Set を確認し、適切な対応を決定する。注: `$ARGUMENTS`が空かつ `*-frontend-task-*.md` が存在しない場合は、上記の readiness check が既に実行を停止している — 以下の表で「タスクなし」が関わる行は、ユーザーが明示的に `$ARGUMENTS` を指定した場合にのみ発火する。
47
+ Consumed Task Set を確認し、適切な対応を決定する。注: `$ARGUMENTS`が空かつ `*-frontend-task-*.md` が存在しない場合は、上記の作業計画書の解決が既に実行を停止している — 以下の表で「タスクなし」が関わる行は、ユーザーが明示的に `$ARGUMENTS` を指定した場合にのみ発火する。
57
48
 
58
49
  | 状態 | 基準 | 次のアクション |
59
50
  |------|------|--------------|
@@ -45,7 +45,7 @@ requirement-analyzerの`crossLayerScope`がレイヤー横断(backend + fronte
45
45
 
46
46
  **TaskListで次のpendingタスクを確認して実行**。
47
47
 
48
- ## 📋 subagents-orchestration-guideスキル準拠の実行
48
+ ## subagents-orchestration-guideスキル準拠の実行
49
49
 
50
50
  **実行前チェック(必須)**:
51
51
  - [ ] subagents-orchestration-guideスキルの該当フローを確認した
@@ -58,19 +58,6 @@ requirement-analyzerの`crossLayerScope`がレイヤー横断(backend + fronte
58
58
 
59
59
  **フロー厳守**: subagents-orchestration-guideスキルの「自律実行中のタスク管理」に従い、TaskCreate/TaskUpdateで4ステップを管理する
60
60
 
61
- ## Implementation Readinessチェック(work-planner承認とtask-decomposerの間)
62
-
63
- work-plannerが完了しユーザーから一括承認を得た後、task-decomposerを呼び出す前に作業計画書のヘッダを読み、`Implementation Readiness: <status>`の行を見つける。以下のルールを適用する:
64
-
65
- | ステータス | アクション |
66
- |--------|--------|
67
- | `ready` | task-decomposerに進む |
68
- | `escalated` | 作業計画書のReadiness Reportセクションを読み、AskUserQuestionで残存ギャップをユーザーに提示する: 「Implementation Readinessが`escalated`で、以下の残存ギャップがあります: [リスト]。実行を継続しますか?(y/n)」。`y`なら進む、`n`なら停止 |
69
- | `pending` | AskUserQuestionで提示する: 「Implementation Readinessが`pending`です。事前にreadiness preflightを実行して作業計画書の実装可能性を検証してから再開してください。preflightなしで継続しますか?(y/n)」。`y`なら進む、`n`なら停止 |
70
- | 行が存在しない | `pending`として扱う — readinessマーカー導入前に作成された古い作業計画書は明示的にpreflightすべき |
71
-
72
- このチェックは全規模(Small / Medium / Large)に適用される。本レシピは規模に依存しないオーケストレーターであるため。
73
-
74
61
  ## サブエージェントのスコープ境界
75
62
 
76
63
  本レシピから呼び出すサブエージェントプロンプトの末尾に以下のブロックを必ず付与する:
@@ -87,7 +74,7 @@ Escalate when the required fix or investigation falls outside that scope.
87
74
  [Constraint] rule-advisor can only be used by Main AI
88
75
  ```
89
76
 
90
- ## 🎯 オーケストレーターとしての必須責務
77
+ ## オーケストレーターとしての必須責務
91
78
 
92
79
  ### タスク実行品質サイクル
93
80
  subagents-orchestration-guideスキルの「自律実行中のタスク管理」に従い、TaskCreate/TaskUpdateで以下のステップを管理:
@@ -76,7 +76,7 @@ description: 設計書から作業計画書を作成し計画承認を取得
76
76
  **スコープ**: 作業計画書作成と計画内容の承認取得まで。
77
77
 
78
78
  ## 終了時の応答
79
- **必須**: 計画内容の承認後は以下の定型応答で終了
79
+ **必須**: 計画内容の承認後は以下の定型応答を出力
80
80
  ```
81
81
  計画フェーズが完了しました。
82
82
  - 作業計画書: docs/plans/[plan-name].md
@@ -84,3 +84,8 @@ description: 設計書から作業計画書を作成し計画承認を取得
84
84
 
85
85
  実装は別途ご指示ください。
86
86
  ```
87
+
88
+ 承認された計画が次のいずれかを含む場合 — E2Eテストスケルトン;コードベースにまだ存在しないコマンド・ファイル・関数・エンドポイントを参照する検証戦略;視覚状態を描画する fixture エントリや開発用ルートを持たない UI コンポーネント;エンドツーエンドでの動作が未確認のローカルレーン — 応答の最終行として次の1行を追加する(該当しなければ省略する):
89
+ ```
90
+ 任意の事前検証: `/prepare-implementation docs/plans/[plan-name].md` で、ビルド前にこれらが実装可能かを検証できる(readiness 基準がすべて満たされていれば no-op で終了)。
91
+ ```
@@ -11,14 +11,14 @@ description: 実装着手前に readiness を検証しギャップを解消す
11
11
  **実行プロトコル**:
12
12
  1. **全作業をAgentツールでサブエージェントに委譲** — サブエージェント(task-executor / task-executor-frontend / quality-fixer / quality-fixer-frontend)の呼び出し、成果物パスの受け渡し、結果の報告
13
13
  2. **自己完結スコープ**: ギャップが見つかった場合、本レシピは解消タスクの生成と、subagents-orchestration-guide「標準フロー」で説明される標準4ステップサイクルでの実行の**両方**を行う。readiness基準がパスするか残存ギャップがエスカレーションされた時点でレシピは完了する。
14
- 3. **No-op終了**: readinessスキャンで失敗基準がない場合、解消タスクは生成せず即座に終了する。本ブランチのファイル変更は作業計画書本体のみ `Implementation Readiness:`ヘッダを `ready` に昇格し、Readiness Reportセクションを永続化する。コードやテストファイルには触れない。
14
+ 3. **No-op終了**: readinessスキャンで失敗基準がない場合、解消タスクは生成せず、Readiness Report をユーザーに提示して即座に終了する。この no-op 経路ではファイルを変更しない。
15
15
 
16
16
  作業計画書: $ARGUMENTS
17
17
 
18
18
  ## 適用される条件
19
19
 
20
20
  build/implement フェーズの前に、以下のいずれかが該当する場合に実行する:
21
- - 作業計画書の検証戦略がコードベースにまだ存在しないコマンド・ファイル・関数・エンドポイントを参照する Design Doc から作成された
21
+ - コードベースにまだ存在しないコマンド・ファイル・関数・エンドポイントを参照する検証戦略を含む Design Doc から、作業計画書が作成された
22
22
  - 作業計画書にE2Eテストスケルトンが含まれる(seed data、auth fixture、環境変数、または外部モックが未対応の可能性あり)
23
23
  - 作業計画書がUIコンポーネントに触れるが、それらの視覚状態を描画するfixtureエントリや開発用ルートがない
24
24
  - ローカルレーンが本機能領域でエンドツーエンドに動作することをチームが事前に確認していない
@@ -74,11 +74,9 @@ R4とR5は、トリガー信号が作業計画書に現れた場合のみ評価
74
74
  ### Step 3: No-opチェック
75
75
 
76
76
  該当する全基準が `pass`(`fail`ゼロ)の場合:
77
- - 作業計画書のヘッダブロック直後に `## Implementation Readiness Report` セクションを追記(既存なら置換)する。出力フォーマットで定義したReadiness Reportのmarkdownを使用する
78
- - 作業計画書ヘッダの `Implementation Readiness:` 行を `ready` に更新する(行が無ければ `Related Issue/PR:` の後に挿入する)
79
- - Readiness Reportをユーザーに提示する
77
+ - Readiness Report(下記の出力フォーマット参照)をユーザーに提示する
80
78
  - `outcome: ready, gaps_resolved: 0` で終了する
81
- - 本ブランチのファイル変更は上記の作業計画書への変更のみ
79
+ - この no-op 経路ではファイルを変更しない
82
80
 
83
81
  `fail`が1件以上ある場合 → Step 4へ進む。
84
82
 
@@ -115,20 +113,13 @@ R4とR5は、トリガー信号が作業計画書に現れた場合のみ評価
115
113
 
116
114
  各サブエージェントプロンプトの末尾に下記の「サブエージェントのスコープ境界」ブロックを必ず付与する。
117
115
 
118
- ### Step 6: 再スキャン、Readiness Reportの永続化、ヘッダ更新、クリーンアップ、終了
116
+ ### Step 6: 再スキャン、Phase 0 完了の記録、Readiness Report の提示、クリーンアップ、終了
119
117
 
120
118
  1. **再スキャン**: 全解消タスクのコミット後、Step 2のreadinessスキャンを再実行する。
121
119
 
122
- 2. **Readiness Reportを作業計画書本体に永続化する**: 作業計画書のヘッダブロック直後に `## Implementation Readiness Report` セクションを追記(既存なら置換)する。出力フォーマットで定義したReadiness Reportのmarkdownを使用する。下流のbuild/implementレシピは、ヘッダが `escalated` の場合に本セクションを読み、残存ギャップをユーザーに提示する。
120
+ 2. **作業計画書に Phase 0 完了を記録する**: コミットした各 Phase 0 解消タスクについて、作業計画書の Phase 0 セクションのチェックボックスを `[x]` にし、コミット済みである旨を注記する(` — committed` を付す)。これにより完了結果が計画書に残り、下流の task-decomposer がコミット済みの Phase 0 を再生成・再実行せずスキップできる。
123
121
 
124
- 3. **作業計画書ヘッダの更新**: 作業計画書内の `Implementation Readiness: pending` 行を特定し、再スキャンの結果に応じて書き換える:
125
-
126
- | 再スキャン結果 | 新しいヘッダ値 |
127
- |--------------|--------------|
128
- | 該当する全基準が `pass` | `Implementation Readiness: ready` |
129
- | `fail` が1件以上残存 | `Implementation Readiness: escalated` |
130
-
131
- 行が存在しない場合(古い作業計画書フォーマット)、`Related Issue/PR:` 行の後に挿入する。
122
+ 3. **Readiness Report の提示**: Readiness Report(下記の出力フォーマット参照)をユーザーに提示する。レポートはセッション内で提示し、作業計画書には書き込まない — 本レシピの永続的な成果物は、コミット済みの Phase 0 解消タスク(Step 6.2 で計画書に完了として記録)であり、永続化されたレポートではない。
132
123
 
133
124
  4. **最終クリーンアップ**: 本実行で作成した、現在の `{plan-name}` に該当するprepタスクファイル(`docs/plans/tasks/{plan-name}-backend-task-prep-*.md` および `docs/plans/tasks/{plan-name}-frontend-task-prep-*.md`)と、prepフェーズ用に生成されたフェーズ完了ファイル(`docs/plans/tasks/{plan-name}-phase0-completion.md` が存在する場合。prepタスクはPhase 0に置かれるため)をすべて削除する。他の計画のprepタスクファイルはスコープ外 — 本レシピは現在の実行で作成したものだけを削除する。作業内容はコミット済みで、`docs/plans/`はレシピ実行間で保持しない一時的な作業状態である。作業計画書本体は下流のbuild/implementフェーズのために保持する。
134
125
 
@@ -185,7 +176,6 @@ Escalate when the required fix or investigation falls outside that scope.
185
176
  - [ ] readinessスキャンが実行され、各基準の結果と根拠が記録されている
186
177
  - [ ] 全`pass`の場合のno-op終了、または解消タスクの生成・承認・4ステップサイクル実行のいずれかが行われている
187
178
  - [ ] 最後の解消タスクのコミット後に再スキャンが実行されている
188
- - [ ] `## Implementation Readiness Report` セクションが作業計画書本体に永続化されている
189
- - [ ] 作業計画書ヘッダの `Implementation Readiness:` 行が `ready` または `escalated` に更新されている
179
+ - [ ] コミット済みの Phase 0 タスクが作業計画書で `[x]` 完了マークされ、下流の分解でスキップされる
190
180
  - [ ] prepタスクファイル(および生成された場合のPhase 0フェーズ完了ファイル)が `docs/plans/tasks/` から削除されている
191
181
  - [ ] 最終レポートがユーザーに提示されている
@@ -43,9 +43,9 @@ description: スキル修正後のメタデータ同期とrule-advisor精度最
43
43
 
44
44
  ```
45
45
  [1/N] typescript-rules
46
- sections: 同期完了
47
- 💡 tags提案: +[functional-programming]
48
- 💡 typical-use: "旧記述" → "新記述"
46
+ sections: 同期完了
47
+ tags提案: +[functional-programming]
48
+ typical-use: "旧記述" → "新記述"
49
49
  ```
50
50
 
51
51
  ## 完了条件
@@ -5,8 +5,6 @@ Type: feature|fix|refactor
5
5
  Estimated Impact: X files
6
6
  Related Issue/PR: #XXX (if any)
7
7
  Review Scope: [planned-files scope derived from Design Doc and task targets; for a revision plan over existing work, base branch + diff range]
8
- <!-- The line below is medium / large only — small scale uses task-template instead of this plan-template. Keep the value line free of trailing comments so downstream parsers can extract the bare status (pending | ready | escalated). -->
9
- Implementation Readiness: pending
10
8
 
11
9
  ## Related Documents
12
10
  - Design Doc(s):
@@ -214,7 +212,7 @@ This phase is required for ALL implementation approaches.
214
212
  - [ ] Security review: Verify security considerations from Design Doc are implemented
215
213
  - [ ] Quality checks (types, lint, format)
216
214
  - [ ] Execute all tests (including integration/E2E from test skeletons, when provided)
217
- - [ ] Coverage 70%+
215
+ - [ ] Coverage reviewed as a gap signal on critical paths (any enforced threshold per project CI config)
218
216
  - [ ] Document updates
219
217
 
220
218
  ### Quality Assurance
@@ -17,6 +17,13 @@ Metadata:
17
17
  Files to read before starting implementation (file path, with optional search hint):
18
18
  - [e.g., src/orders/checkout (processOrder function) — determined during task decomposition based on task nature]
19
19
 
20
+ ## Change Category
21
+ (Include this field only when the task is a bug fix, regression, state-change, or boundary-change — populated during task decomposition. Omit otherwise.)
22
+
23
+ `Change Category: <one or more of bug-fix, regression, state-change, boundary-change — comma-separated>`
24
+
25
+ When present, the implementation sweeps the cases sharing the same path, contract, persisted state, or external boundary for the same class of defect (see Implementation Steps Red Phase).
26
+
20
27
  ## Binding Decisions
21
28
  (Include this section when the work plan's ADR Bindings table covers this task. Omit otherwise.)
22
29
 
@@ -32,6 +39,7 @@ Each row is an ADR decision the implementation in this task must comply with.
32
39
  ## Implementation Steps (TDD: Red-Green-Refactor)
33
40
  ### 1. Red Phase
34
41
  - [ ] Read all Investigation Targets and record key observations
42
+ - [ ] (When Change Category is set) Sweep the adjacent cases sharing the same path/contract/state/boundary for the same class of defect; fold any found within scope into the failing tests
35
43
  - [ ] Review dependency deliverables (if any)
36
44
  - [ ] Verify/create contract definitions
37
45
  - [ ] Write failing tests
@@ -133,14 +133,10 @@ Quality checks are mandatory upon implementation completion:
133
133
  - `test:coverage:fresh` - Coverage measurement
134
134
  - `check:all` - Overall integrated check
135
135
 
136
- ### Coverage Requirements
137
- - **Mandatory**: Unit test coverage must be 60% or higher
138
- - **Component-specific targets**:
139
- - Atoms: 70% or higher
140
- - Molecules: 65% or higher
141
- - Organisms: 60% or higher
142
- - Custom Hooks: 65% or higher
143
- - Utils: 70% or higher
136
+ ### Coverage
137
+ - Treat coverage as a diagnostic signal for finding untested areas, not a target (a target gets gamed into trivial tests — Goodhart's Law)
138
+ - Concentrate test rigor on foundational, high-reuse units (shared components, custom hooks, utils) whose regression has the widest blast radius; higher-composition surfaces (organisms, pages) lean on integration/E2E coverage instead
139
+ - Any enforced numeric threshold is the project's CI/coverage config, not a goal in itself
144
140
 
145
141
  ### Non-functional Requirements
146
142
  - **Browser Compatibility**: Chrome/Firefox/Safari/Edge (latest 2 versions)
@@ -34,6 +34,7 @@ const user = raw // narrowed to User
34
34
  - **Custom hooks** are the unit of logic reuse and dependency injection (inject collaborators through the hook for testability).
35
35
  - **Function parameters:** 0-2 positional; for 3+ take a single options object.
36
36
  - **State shape:** type state explicitly; for multi-field state with discrete transitions, use `useReducer` with a discriminated-union action type rather than many `useState` calls.
37
+ - **Server/Client boundary** (RSC frameworks only — e.g. Next.js App Router): default to server components for data fetching/rendering and isolate interactivity behind a `"use client"` boundary at the smallest scope that needs it; keep browser-only APIs (`window`, `localStorage`, event handlers) inside client components, since calling them in a server component breaks the render. N/A for client-only SPAs (e.g. Vite) — skip when the project has no server-component runtime.
37
38
 
38
39
  ## Error Handling
39
40
  - Surface every error: log and handle, or propagate — never swallow.
@@ -41,6 +42,7 @@ const user = raw // narrowed to User
41
42
  - Represent expected failures as values with a `Result` type; reserve `throw` for unexpected/unrecoverable cases.
42
43
  - Use purpose-specific error classes extending a base `AppError` carrying a `code` (e.g. ValidationError, ApiError, NotFoundError).
43
44
  - **Layer responsibilities:** the API layer converts transport errors into domain errors; hooks propagate `AppError` upward; an Error Boundary catches render-time errors and shows fallback UI.
45
+ - **Effect race/cleanup:** guard `useEffect` data fetches against out-of-order responses and post-unmount state updates — abort or ignore stale results (`AbortController` or a mounted flag), or use a server-state library (React Query/SWR) that cancels and dedupes. `try-catch` alone does not cover this.
44
46
  - Never log secrets (password, token, apiKey, creditCard).
45
47
 
46
48
  ```typescript
@@ -63,8 +65,8 @@ class ErrorBoundary extends React.Component<{ children: React.ReactNode; fallbac
63
65
  ```
64
66
 
65
67
  ## Project Conventions
66
- - **Environment variables:** read through the build tool's env system (`process.env` is absent in the browser). Keep all secrets server-side — frontend code ships to the client.
67
- - **Bundle & performance:** monitor with the `build` script, keep under 500KB; memoize expensive components (`React.memo`); code-split with `React.lazy` + `Suspense`; structure state to minimize re-renders.
68
+ - **Environment variables:** read client-side env through the bundler's exposed accessor — only vars carrying its public prefix reach the browser; an unprefixed var is `undefined` there. Match the project's bundler: Vite `import.meta.env.VITE_*`, Next.js public `process.env.NEXT_PUBLIC_*`, CRA `process.env.REACT_APP_*`. Keep all secrets server-side — frontend code ships to the client.
69
+ - **Bundle & performance:** monitor bundle size with the `build` script against the project's budget; code-split with `React.lazy` + `Suspense`; structure state to minimize re-renders. Memoization: when React Compiler is enabled, rely on it; reach for manual `React.memo`/`useMemo`/`useCallback` only as a profiler- or identity-justified escape hatch (a measured bottleneck, or stable reference identity for third-party APIs / effect dependencies).
68
70
  - **Naming:** components/types `PascalCase`; variables/functions `camelCase`; hooks `use`-prefixed; constants `SCREAMING_SNAKE_CASE`.
69
71
  - **Imports:** absolute paths from `src/`; order: React → external libs → internal (absolute) → internal (relative) → type-only → styles/assets.
70
72
  - **Formatting:** follow Biome (semicolons and style come from project config).
@@ -24,21 +24,15 @@ description: Designs tests with React Testing Library, MSW, and Playwright E2E.
24
24
  ## Basic Testing Policy
25
25
 
26
26
  ### Quality Requirements
27
- - **Coverage**: Unit test coverage must be 60% or higher (Frontend standard 2025)
27
+ - **Coverage**: prioritize meaningful assertions on critical paths and high-reuse components; treat coverage as a signal for gaps, not a target (a target gets gamed into trivial tests — Goodhart's Law). Any numeric threshold is the project's CI config
28
28
  - **Independence**: Each test can run independently without depending on other tests
29
29
  - **Reproducibility**: Tests are environment-independent and always return the same results
30
30
  - **Readability**: Test code maintains the same quality as production code
31
31
 
32
- ### Coverage Requirements (ADR-0002 Compliant)
33
- **Mandatory**: Unit test coverage must be 60% or higher
34
- **Component-specific targets**:
35
- - Atoms (Button, Text, etc.): 70% or higher
36
- - Molecules (FormField, etc.): 65% or higher
37
- - Organisms (Header, Footer, etc.): 60% or higher
38
- - Custom Hooks: 65% or higher
39
- - Utils: 70% or higher
32
+ ### Where to concentrate test rigor
33
+ Test foundational, high-reuse units the hardest — shared components, custom hooks, and utils reused across many features carry the widest blast radius. Higher-composition surfaces (organisms, pages) lean on integration/E2E coverage instead. Any numeric threshold is the project's CI config.
40
34
 
41
- **Metrics**: Statements, Branches, Functions, Lines
35
+ **Metrics** (what coverage reports break down): Statements, Branches, Functions, Lines
42
36
 
43
37
  ### Test Types and Scope
44
38
  1. **Unit Tests (React Testing Library)**
@@ -74,7 +68,7 @@ src/
74
68
 
75
69
  **Rationale**:
76
70
  - React Testing Library best practice
77
- - ADR-0002 Co-location principle
71
+ - Co-location principle: tests live alongside the implementation they cover
78
72
  - Easy to find and maintain tests alongside implementation
79
73
 
80
74
  ### Naming Conventions