diff --git a/.agents/skills/documentation-criteria/references/task-template.md b/.agents/skills/documentation-criteria/references/task-template.md index b8c9340..e967058 100644 --- a/.agents/skills/documentation-criteria/references/task-template.md +++ b/.agents/skills/documentation-criteria/references/task-template.md @@ -3,7 +3,7 @@ Metadata: - Dependencies: task-01 -> Deliverable: docs/plans/analysis/research-results.md - Provides: docs/plans/analysis/api-spec.md (for research/design tasks) -- Size: Small (1-2 files) +- Source Plan Tasks: [P1-T1, P1-T2] ## Implementation Content [What this task will achieve] diff --git a/.agents/skills/recipe-add-integration-tests/SKILL.md b/.agents/skills/recipe-add-integration-tests/SKILL.md index 9b69b84..9a829d2 100644 --- a/.agents/skills/recipe-add-integration-tests/SKILL.md +++ b/.agents/skills/recipe-add-integration-tests/SKILL.md @@ -142,7 +142,7 @@ Use the executor's `filesModified` as the task write set. Spawn integration-test-reviewer with `changedTestFiles: [integration/E2E test paths from filesModified]`, `diffBase`, `skeletonFiles: [layer-specific paths from Step 2]`, and `taskFile`. Keep `testsAdded` as reporting metadata only. -**Expected output**: `status` (approved/needs_revision/blocked), `reviewBasis`, `requiredFixes`. Escalate `blocked` or an unrecognized status. +**Expected output**: `status` (approved/needs_revision/blocked), `reviewBasis`, `requiredFixes`. Apply Orchestrator Escalation Resolution for `blocked` or an unrecognized status. ### Step 6: Apply Review Fixes @@ -163,7 +163,7 @@ Spawn quality-fixer routed by task filename pattern: On quality-fixer result: - `status: "stub_detected"` -> Return to Step 4 with `stubFindings` -- `status: "blocked"` -> Escalate to user +- `status: "blocked"` -> Apply Orchestrator Escalation Resolution - `status: "approved"` -> Commit test files - MUST commit test files with appropriate message ENFORCEMENT: Commits without quality-fixer approval are invalid. diff --git a/.agents/skills/recipe-build/SKILL.md b/.agents/skills/recipe-build/SKILL.md index 4d9183f..547724a 100644 --- a/.agents/skills/recipe-build/SKILL.md +++ b/.agents/skills/recipe-build/SKILL.md @@ -21,7 +21,7 @@ description: "Execute decomposed backend tasks in autonomous execution mode usin 1. **Spawn agents for all work** -- your role is to invoke sub-agents, pass data between them, and report results 2. **Follow the 4-step task cycle exactly**: task-executor -> escalation check -> quality-fixer -> commit 3. **Enter autonomous mode** when user provides execution instruction with existing task files -- this IS the batch approval -4. **Scope**: Complete when all tasks are committed or escalation occurs +4. **Scope**: Complete when all tasks are committed or user input is required **CRITICAL**: MUST run quality-fixer before every commit. ENFORCEMENT: Commits without quality-fixer approval are invalid and MUST be reverted. @@ -92,17 +92,17 @@ Generate tasks from the work plan? (y/n): ``` ### 3. Task Decomposition (if approved) -Spawn task-decomposer agent: "Read work plan at docs/plans/[plan-name].md and decompose into atomic tasks. Output: Individual task files in docs/plans/tasks/. Granularity: 1 task = 1 commit = independently executable." +Spawn task-decomposer agent: "Read the approved work plan at docs/plans/[plan-name].md and generate executable task files in docs/plans/tasks/." ### 4. Verify Generation -Recompute the Consumed Task Set and verify it is non-empty. +Check task-decomposer `Status`. Apply Orchestrator Escalation Resolution for `blocked` or an unrecognized status. Only after `completed`, recompute the Consumed Task Set and verify it is non-empty. ## Pre-execution Checklist - [ ] Confirmed task files exist in docs/plans/tasks/ - [ ] Identified task execution order (dependencies) - [ ] **Environment check**: Can I execute per-task commit cycle? - - If commit capability unavailable -> Escalate before autonomous mode + - If commit capability unavailable -> Apply Orchestrator Escalation Resolution before autonomous mode - Other environments (tests, quality tools) -> Subagents will escalate ## Task Execution Cycle (4-Step Cycle) @@ -115,16 +115,16 @@ For EACH task, YOU MUST: 1. **Capture diff base**: Record the current revision as `diffBase`. 2. **Spawn task-executor agent**: "Execute the task implementation for [task-file-path]" 3. **CHECK task-executor response**: - - `status: "escalation_needed"` or `"blocked"` -> STOP and escalate to user + - `status: "escalation_needed"` or `"blocked"` -> Apply Orchestrator Escalation Resolution - `requiresTestReview` is `true` -> Spawn integration-test-reviewer agent with `changedTestFiles: [integration/E2E paths from filesModified]`, `diffBase`, and `taskFile: [task-file-path]`; when matching integration/E2E skeleton paths are available from acceptance-test-generator output or task/work-plan references, pass only those paths as `skeletonFiles` - `needs_revision` -> Apply Review Revision Convergence (`author`: task-executor; `artifact`: changed test files); on `progression`, proceed to step 4 - `approved` -> Proceed to step 4 - - `blocked` or unrecognized status -> STOP and escalate to user + - `blocked` or unrecognized status -> Apply Orchestrator Escalation Resolution - `readyForQualityCheck: true` -> Proceed to step 4 4. **Spawn quality-fixer agent** with `task_file` and executor `filesModified`. 5. **CHECK quality-fixer response**: - `status: "stub_detected"` -> Return to step 2 with `stubFindings` - - `status: "blocked"` -> STOP and escalate to user + - `status: "blocked"` -> Apply Orchestrator Escalation Resolution - `status: "approved"` -> Proceed to step 6 6. **COMMIT on approval**: After `status: "approved"` from quality-fixer -> Execute git commit @@ -152,16 +152,16 @@ After all task cycles finish, collect all `filesModified` from every task-execut 3. Consolidate results: - code-verifier passes when `summary.status` is `consistent` or `mostly_consistent` - code-verifier fails when `summary.status` is `needs_review` or `inconsistent` - - code-verifier `blocked` or unrecognized status -> Escalate to user + - code-verifier `blocked` or unrecognized status -> Apply Orchestrator Escalation Resolution - security-reviewer passes when `status` is `approved` or `approved_with_notes` - security-reviewer fails when `status` is `needs_revision` - - security-reviewer `blocked` -> Escalate to user + - security-reviewer `blocked` -> Apply Orchestrator Escalation Resolution 4. If either verifier fails: - Create one ephemeral fix task per executor route covering verifier discrepancies and security requiredFixes - Pass each exact task path to task-executor and then quality-fixer - Re-run both code-verifier and security-reviewer after any fix - Delete the ephemeral task files only after both verifiers pass - - Maximum retry count is 1 verification fix cycle; if any failed verifier still fails after re-run, escalate to the user + - If any verifier still fails after re-run, apply Orchestrator Escalation Resolution 5. If both verifiers pass -> Proceed to completion report ## Final Cleanup @@ -186,7 +186,7 @@ If cleanup fails, report the failed path but do not invalidate completed impleme - [ ] All tasks executed through 4-step cycle (task-executor -> check -> quality-fixer -> commit) - [ ] System constraint suffix appended to all sub-agent prompts - [ ] All quality gates passed -- [ ] All tasks committed or escalation completed +- [ ] All tasks committed or user input requested ## Output Example Backend implementation phase completed. diff --git a/.agents/skills/recipe-front-build/SKILL.md b/.agents/skills/recipe-front-build/SKILL.md index ba508ed..faaa4b4 100644 --- a/.agents/skills/recipe-front-build/SKILL.md +++ b/.agents/skills/recipe-front-build/SKILL.md @@ -21,7 +21,7 @@ description: "Execute frontend tasks in autonomous execution mode using task-exe 1. **Spawn agents for all work** -- your role is to invoke sub-agents, pass data between them, and report results 2. **Follow the 4-step task cycle exactly**: task-executor-frontend -> escalation check -> quality-fixer-frontend -> commit 3. **Enter autonomous mode** when user provides execution instruction with existing task files -- this IS the batch approval -4. **Scope**: Complete when all tasks are committed or escalation occurs +4. **Scope**: Complete when all tasks are committed or user input is required **CRITICAL**: MUST run quality-fixer-frontend before every commit. ENFORCEMENT: Commits without quality-fixer-frontend approval are invalid and MUST be reverted. @@ -92,17 +92,17 @@ Generate tasks from the work plan? (y/n): ``` ### 3. Task Decomposition (if approved) -Spawn task-decomposer agent: "Read work plan at docs/plans/[plan-name].md and decompose into atomic tasks. Output: Individual task files in docs/plans/tasks/. Granularity: 1 task = 1 commit = independently executable" +Spawn task-decomposer agent: "Read the approved work plan at docs/plans/[plan-name].md and generate executable task files in docs/plans/tasks/." ### 4. Verify Generation -Recompute the Consumed Task Set and verify it is non-empty. +Check task-decomposer `Status`. Apply Orchestrator Escalation Resolution for `blocked` or an unrecognized status. Only after `completed`, recompute the Consumed Task Set and verify it is non-empty. ## Pre-execution Checklist - [ ] Confirmed task files exist in docs/plans/tasks/ - [ ] Identified task execution order (dependencies) - [ ] **Environment check**: Can I execute per-task commit cycle? - - If commit capability unavailable -> Escalate before autonomous mode + - If commit capability unavailable -> Apply Orchestrator Escalation Resolution before autonomous mode - Other environments (tests, quality tools) -> Subagents will escalate ## Task Execution Cycle (4-Step Cycle) - Frontend Specialized @@ -123,16 +123,16 @@ For EACH task, YOU MUST: 1. **Capture diff base**: Record the current revision as `diffBase`. 2. **Spawn task-executor-frontend agent**: "Task file: docs/plans/tasks/[filename].md Execute frontend implementation" 3. **CHECK task-executor-frontend response**: - - `status: "escalation_needed"` or `"blocked"` -> STOP and escalate to user + - `status: "escalation_needed"` or `"blocked"` -> Apply Orchestrator Escalation Resolution - `requiresTestReview` is `true` -> Spawn integration-test-reviewer with `changedTestFiles: [integration/E2E paths from filesModified]`, `diffBase`, and `taskFile`; when matching integration/E2E skeleton paths are available from acceptance-test-generator output or task/work-plan references, pass only those paths as `skeletonFiles` - `needs_revision` -> Apply Review Revision Convergence (`author`: task-executor-frontend; `artifact`: changed test files); on `progression`, proceed to step 4 - `approved` -> Proceed to step 4 - - `blocked` or unrecognized status -> STOP and escalate to user + - `blocked` or unrecognized status -> Apply Orchestrator Escalation Resolution - `readyForQualityCheck: true` -> Proceed to step 4 4. **Spawn quality-fixer-frontend agent** with `task_file` and executor `filesModified`. 5. **CHECK quality-fixer-frontend response**: - `status: "stub_detected"` -> Return to step 2 with `stubFindings` - - `status: "blocked"` -> STOP and escalate to user + - `status: "blocked"` -> Apply Orchestrator Escalation Resolution - `status: "approved"` -> Proceed to step 6 6. **COMMIT on approval**: After `status: "approved"` from quality-fixer-frontend -> Execute git commit. Use `changeSummary` for commit message. @@ -160,16 +160,16 @@ After all task cycles finish, collect all `filesModified` from every task-execut 3. Consolidate results: - code-verifier passes when `summary.status` is `consistent` or `mostly_consistent` - code-verifier fails when `summary.status` is `needs_review` or `inconsistent` - - code-verifier `blocked` or unrecognized status -> Escalate to user + - code-verifier `blocked` or unrecognized status -> Apply Orchestrator Escalation Resolution - security-reviewer passes when `status` is `approved` or `approved_with_notes` - security-reviewer fails when `status` is `needs_revision` - - security-reviewer `blocked` -> Escalate to user + - security-reviewer `blocked` -> Apply Orchestrator Escalation Resolution 4. If either verifier fails: - Create one ephemeral frontend fix task covering verifier discrepancies and security requiredFixes - Pass its exact path to task-executor-frontend and then quality-fixer-frontend - Re-run both code-verifier and security-reviewer after any fix - Delete the ephemeral task file only after both verifiers pass - - Maximum retry count is 1 verification fix cycle; if any failed verifier still fails after re-run, escalate to the user + - If any verifier still fails after re-run, apply Orchestrator Escalation Resolution 5. If both verifiers pass -> Proceed to completion report ## Final Cleanup @@ -194,7 +194,7 @@ If cleanup fails, report the failed path but do not invalidate completed impleme - [ ] All tasks executed through 4-step cycle (task-executor-frontend -> check -> quality-fixer-frontend -> commit) - [ ] System constraint suffix appended to all sub-agent prompts - [ ] All quality gates passed -- [ ] All tasks committed or escalation completed +- [ ] All tasks committed or user input requested ## Output Example Frontend implementation phase completed. diff --git a/.agents/skills/recipe-fullstack-build/SKILL.md b/.agents/skills/recipe-fullstack-build/SKILL.md index b00cc85..266abf2 100644 --- a/.agents/skills/recipe-fullstack-build/SKILL.md +++ b/.agents/skills/recipe-fullstack-build/SKILL.md @@ -31,7 +31,7 @@ ENFORCEMENT: Proceeding without reading monorepo-flow.md invalidates the entire - `*-frontend-task-*` -> task-executor-frontend + quality-fixer-frontend 3. **Follow the 4-step task cycle exactly**: executor -> escalation check -> quality-fixer -> commit 4. **Enter autonomous mode** when user provides execution instruction with existing task files -- this IS the batch approval -5. **Scope**: Complete when all tasks are committed or escalation occurs +5. **Scope**: Complete when all tasks are committed or user input is required **CRITICAL**: MUST run layer-appropriate quality-fixer before every commit. ENFORCEMENT: Commits without quality-fixer approval are invalid and MUST be reverted. @@ -102,17 +102,17 @@ Generate tasks from the work plan? (y/n): ``` ### 3. Task Decomposition (if approved) -Spawn task-decomposer agent: "Read work plan at docs/plans/[plan-name].md and decompose into atomic tasks. Output: Individual task files in docs/plans/tasks/. Granularity: 1 task = 1 commit = independently executable. Use layer-aware naming: {plan}-backend-task-{n}.md, {plan}-frontend-task-{n}.md based on target file paths." +Spawn task-decomposer agent: "Read the approved work plan at docs/plans/[plan-name].md and generate executable task files in docs/plans/tasks/. Use layer-aware naming: {plan}-backend-task-{n}.md, {plan}-frontend-task-{n}.md based on target file paths." ### 4. Verify Generation -Recompute the Consumed Task Set and verify it is non-empty. +Check task-decomposer `Status`. Apply Orchestrator Escalation Resolution for `blocked` or an unrecognized status. Only after `completed`, recompute the Consumed Task Set and verify it is non-empty. ## Pre-execution Checklist - [ ] Confirmed task files exist in docs/plans/tasks/ - [ ] Identified task execution order (dependencies) - [ ] **Environment check**: Can I execute per-task commit cycle? - - If commit capability unavailable -> Escalate before autonomous mode + - If commit capability unavailable -> Apply Orchestrator Escalation Resolution before autonomous mode - Other environments (tests, quality tools) -> Subagents will escalate ## Agent Routing Table @@ -133,16 +133,16 @@ For EACH task, YOU MUST: 1. **Capture diff base**: Record the current revision as `diffBase`. 2. **Spawn task-executor or task-executor-frontend agent** (per routing table): "Execute the task implementation for [task-file-path]" 3. **CHECK executor response**: - - `status: "escalation_needed"` or `"blocked"` -> STOP and escalate to user + - `status: "escalation_needed"` or `"blocked"` -> Apply Orchestrator Escalation Resolution - `requiresTestReview` is `true` -> Spawn integration-test-reviewer with `changedTestFiles: [integration/E2E paths from filesModified]`, `diffBase`, and `taskFile`; when matching integration/E2E skeleton paths are available from acceptance-test-generator output or task/work-plan references, pass only those paths as `skeletonFiles` - `needs_revision` -> Apply Review Revision Convergence (`author`: layer-appropriate executor; `artifact`: changed test files); on `progression`, proceed to step 4 - `approved` -> Proceed to step 4 - - `blocked` or unrecognized status -> STOP and escalate to user + - `blocked` or unrecognized status -> Apply Orchestrator Escalation Resolution - `readyForQualityCheck: true` -> Proceed to step 4 4. **Spawn quality-fixer agent** (layer-appropriate per routing table) with `task_file` and executor `filesModified`. 5. **CHECK quality-fixer response**: - `status: "stub_detected"` -> Return to step 2 with `stubFindings` - - `status: "blocked"` -> STOP and escalate to user + - `status: "blocked"` -> Apply Orchestrator Escalation Resolution - `status: "approved"` -> Proceed to step 6 6. **COMMIT on approval**: After `status: "approved"` from quality-fixer -> Execute git commit @@ -170,16 +170,16 @@ After all task cycles finish, collect all `filesModified` from every task-execut 3. Consolidate results: - each code-verifier run passes when `summary.status` is `consistent` or `mostly_consistent` - a code-verifier run fails when `summary.status` is `needs_review` or `inconsistent` - - code-verifier `blocked` or unrecognized status -> Escalate to user + - code-verifier `blocked` or unrecognized status -> Apply Orchestrator Escalation Resolution - security-reviewer passes when `status` is `approved` or `approved_with_notes` - security-reviewer fails when `status` is `needs_revision` - - security-reviewer `blocked` -> Escalate to user + - security-reviewer `blocked` -> Apply Orchestrator Escalation Resolution 4. If any verifier fails: - Create one ephemeral fix task per executor route covering verifier discrepancies and security requiredFixes - Pass each exact task path to the layer-appropriate task-executor and then quality-fixer - Re-run all code-verifier runs and security-reviewer after any fix - Delete the ephemeral task files only after all verifiers pass - - Maximum retry count is 1 verification fix cycle; if any failed verifier still fails after re-run, escalate to the user + - If any verifier still fails after re-run, apply Orchestrator Escalation Resolution 5. If all verifiers pass -> Proceed to completion report ## Final Cleanup @@ -206,7 +206,7 @@ If cleanup fails, report the failed path but do not invalidate completed impleme - [ ] All tasks executed through 4-step cycle (executor -> check -> quality-fixer -> commit) - [ ] System constraint suffix appended to all sub-agent prompts - [ ] All quality gates passed -- [ ] All tasks committed or escalation completed +- [ ] All tasks committed or user input requested ## Output Example Fullstack implementation phase completed. diff --git a/.agents/skills/recipe-fullstack-implement/SKILL.md b/.agents/skills/recipe-fullstack-implement/SKILL.md index 308a02c..f5886fe 100644 --- a/.agents/skills/recipe-fullstack-implement/SKILL.md +++ b/.agents/skills/recipe-fullstack-implement/SKILL.md @@ -102,7 +102,7 @@ When user responds to questions: - [ ] codebase-analyzer included before each Design Doc creation - [ ] code-verifier included before each Design Doc review - [ ] **Environment check**: Can I execute per-task commit cycle? - - If commit capability unavailable -> Escalate before autonomous mode + - If commit capability unavailable -> Apply Orchestrator Escalation Resolution before autonomous mode - Other environments (tests, quality tools) -> Subagents will escalate **Required Flow Compliance**: @@ -138,7 +138,7 @@ Before executing task files, execute the Implementation Readiness Preflight Proc **Rules**: 1. Execute ONE task completely before starting next; capture `diffBase` before its executor call 2. Check executor status before quality-fixer (escalation check) -3. When `requiresTestReview` is true, integration-test-reviewer receives changed integration/E2E paths from `filesModified`, `diffBase`, and `taskFile`; when matching integration/E2E skeleton paths are available from acceptance-test-generator output or task/work-plan references, pass only those paths as `skeletonFiles`; `blocked` or unrecognized status escalates to the user +3. When `requiresTestReview` is true, integration-test-reviewer receives changed integration/E2E paths from `filesModified`, `diffBase`, and `taskFile`; when matching integration/E2E skeleton paths are available from acceptance-test-generator output or task/work-plan references, pass only those paths as `skeletonFiles`; apply Orchestrator Escalation Resolution for `blocked` or an unrecognized status 4. Quality-fixer MUST run after each executor with `filesModified` and `task_file` 5. If quality-fixer returns `status: "stub_detected"`, route the task back to the same executor with `stubFindings` 6. Commit MUST execute only when quality-fixer returns `status: "approved"` (do not defer to end) @@ -151,16 +151,16 @@ After all task cycles finish, collect all `filesModified` from every task-execut 3. Consolidate results: - each code-verifier run passes when `summary.status` is `consistent` or `mostly_consistent` - a code-verifier run fails when `summary.status` is `needs_review` or `inconsistent` - - code-verifier `blocked` or unrecognized status -> Escalate to user + - code-verifier `blocked` or unrecognized status -> Apply Orchestrator Escalation Resolution - security-reviewer passes when `status` is `approved` or `approved_with_notes` - security-reviewer fails when `status` is `needs_revision` - - security-reviewer `blocked` -> Escalate to user + - security-reviewer `blocked` -> Apply Orchestrator Escalation Resolution 4. If any verifier fails: - Create one ephemeral fix task per executor route covering verifier discrepancies and security requiredFixes - Pass each exact task path through the layer-appropriate executor and quality-fixer - Re-run all code-verifier runs and security-reviewer after any fix - Delete ephemeral task files only after all verifiers pass - - Maximum retry count is 1 verification fix cycle; if any failed verifier still fails after re-run, escalate to the user + - If any verifier still fails after re-run, apply Orchestrator Escalation Resolution 5. If all verifiers pass -> Proceed to completion report ### Test Information Communication @@ -183,7 +183,7 @@ After acceptance-test-generator execution, when calling work-planner, communicat - [ ] All stop points respected with user approval - [ ] All tasks executed through layer-appropriate 4-step cycle - [ ] All quality gates passed -- [ ] All tasks committed or escalation completed +- [ ] All tasks committed or user input requested ## Execution Method diff --git a/.agents/skills/recipe-implement/SKILL.md b/.agents/skills/recipe-implement/SKILL.md index 679e937..d388902 100644 --- a/.agents/skills/recipe-implement/SKILL.md +++ b/.agents/skills/recipe-implement/SKILL.md @@ -112,16 +112,16 @@ Before the first task, call `update_plan` once with first "Map active rules to t 1. Record the current revision as `diffBase`, then spawn task-executor (or task-executor-frontend): "Implement task [task-file-path]" 2. Check task-executor response: - - `status: escalation_needed` or `blocked` -> Escalate to user + - `status: escalation_needed` or `blocked` -> Apply Orchestrator Escalation Resolution - `requiresTestReview` is `true` -> Spawn integration-test-reviewer with changed integration/E2E paths from `filesModified`, `diffBase`, and `taskFile`; when matching integration/E2E skeleton paths are available from acceptance-test-generator output or task/work-plan references, pass only those paths as `skeletonFiles` - `needs_revision` -> Apply Review Revision Convergence (`author`: layer-appropriate executor; `artifact`: changed test files); on `progression`, proceed to step 3 - `approved` -> Proceed to step 3 - - `blocked` or unrecognized status -> Escalate to user + - `blocked` or unrecognized status -> Apply Orchestrator Escalation Resolution - Otherwise -> Proceed to step 3 3. Spawn quality-fixer (or quality-fixer-frontend) with `task_file` and executor `filesModified`. 4. Check quality-fixer response: - `status: "stub_detected"` -> Return to step 1 with `stubFindings` - - `status: "blocked"` -> Escalate to user + - `status: "blocked"` -> Apply Orchestrator Escalation Resolution - `status: "approved"` -> Proceed to step 5 5. git commit -> Execute on `status: "approved"` @@ -133,16 +133,16 @@ After all task cycles finish, collect all `filesModified` from every executor re 3. Consolidate results: - code-verifier passes when `summary.status` is `consistent` or `mostly_consistent` - code-verifier fails when `summary.status` is `needs_review` or `inconsistent` - - code-verifier `blocked` or unrecognized status -> Escalate to user + - code-verifier `blocked` or unrecognized status -> Apply Orchestrator Escalation Resolution - security-reviewer passes when `status` is `approved` or `approved_with_notes` - security-reviewer fails when `status` is `needs_revision` - - security-reviewer `blocked` -> Escalate to user + - security-reviewer `blocked` -> Apply Orchestrator Escalation Resolution 4. If either verifier fails: - Create one ephemeral fix task per executor route covering verifier discrepancies and security requiredFixes - Pass each exact path through the layer-appropriate executor and quality-fixer - Re-run both verification agents after any fix - Delete ephemeral task files only after both pass - - Maximum retry count is 1 verification fix cycle; if any failed verifier still fails after re-run, escalate to the user + - If any verifier still fails after re-run, apply Orchestrator Escalation Resolution 5. If both verifiers pass -> Proceed to completion report ### Test Information Communication @@ -162,5 +162,5 @@ After acceptance-test-generator execution, when spawning work-planner, communica - [ ] code-verifier included before document-reviewer for Design Doc review - [ ] All stopping points honored with user confirmation obtained - [ ] Quality-fixer spawned before every commit -- [ ] All tasks committed or escalation completed +- [ ] All tasks committed or user input requested - [ ] System constraint suffix appended to all sub-agent prompts diff --git a/.agents/skills/subagents-orchestration-guide/SKILL.md b/.agents/skills/subagents-orchestration-guide/SKILL.md index f71d12d..808bca1 100644 --- a/.agents/skills/subagents-orchestration-guide/SKILL.md +++ b/.agents/skills/subagents-orchestration-guide/SKILL.md @@ -127,7 +127,7 @@ Autonomous execution MUST stop and wait for user input at these points. | Design | After design-sync completes consistency verification | Approve Design Doc | | Work Plan | After document-reviewer completes WorkPlan review for Medium/Large, or after simplified plan creation for Small | Batch approval for implementation phase | -**ENFORCEMENT**: After batch approval, autonomous execution proceeds without stops until completion or escalation. Skipping stop points is a CRITICAL VIOLATION. +**ENFORCEMENT**: After batch approval, autonomous execution proceeds without stops until completion or Orchestrator Escalation Resolution requires user input. Skipping stop points is a CRITICAL VIOLATION. ### Approval Status Vocabulary [MANDATORY] @@ -140,7 +140,7 @@ These values standardize review and approval decisions. Review and approval agen | `approved_with_notes` | security-reviewer | Only hardening/policy findings | Proceed — include notes in completion report (no resolution required) | | `needs_revision` | Review/approval agents | Significant issues found | Use Review Revision Convergence when the active workflow owns the repair author; otherwise use the workflow's specific routing | | `rejected` | Document agents | Fundamental problems | Halt workflow, escalate to user | -| `blocked` | security-reviewer | Committed secrets or high-confidence exploitable risk | Halt workflow immediately, escalate to user (requires human intervention) | +| `blocked` | security-reviewer | Committed secrets or high-confidence exploitable risk | Apply Orchestrator Escalation Resolution | | `skipped` | Review/approval agents whose schema permits skipping | Preconditions not met for this step | Report reason, proceed | Handling rules: @@ -163,6 +163,15 @@ Inputs are `author`, `artifact`, `reviewer`, and the complete `current_review` r `progression`, `escalation`, and `non_convergent` are procedure control states, separate from the review and approval decisions governed by the Approval Status Vocabulary. The procedure owns the author-review loop; callers route its returned state exactly once and continue from the named destination. Observable progress governs loop length. The default route for `escalation` and `non_convergent` halts the current phase and presents the returned artifact, unresolved findings, and attempted corrections to the user; a caller-defined route takes precedence. +### Orchestrator Escalation Resolution [MANDATORY] + +Apply this procedure when a workflow subagent returns `escalation_needed` or `blocked`, a required status is unrecognized, or autonomous execution would otherwise escalate. The response returns control to the orchestrator; it is not itself a human stop. + +1. Resolve the issue from approved requirements, governing artifacts, repository evidence, and prior agent outputs. Choose the smallest resolution that preserves approved intent. +2. Invoke the responsible author to update the task, governing artifact, or implementation, then retry the interrupted step with the resolution and updated artifact. +3. Continue while corrections make observable progress. On the first no-progress result, make one targeted correction from the governing sources and retry once. +4. Resume the workflow when the interrupted step succeeds. Escalate to the user only when resolution requires a new or changed requirement, a business decision, unavailable external authority, an unauthorized irreversible action, or the targeted retry makes no progress. Preserve completed work and unaffected tasks. + ### WorkPlan Review State [MANDATORY] Medium and Large work plans must contain a `WorkPlan Review` section. Small simplified plans are exempt because they have no Design Doc to trace against. The plan is reviewed only when that section records `Status: approved` and `Conditions: none`. @@ -278,7 +287,7 @@ Flow rules: - Quality check tools (quality-fixer will detect and escalate if missing) - Test runner (task-executor will detect and escalate if missing) -**If critical environment unavailable**: Escalate with specific missing component before entering autonomous mode +**If critical environment unavailable**: Apply Orchestrator Escalation Resolution with the specific missing component before entering autonomous mode ### Authority Grant @@ -294,15 +303,16 @@ After "batch approval for entire implementation phase" with work-planner, autono ``` Batch approval -> Start autonomous execution mode -> task-decomposer: Task decomposition + - blocked/unrecognized -> Orchestrator Escalation Resolution -> Task execution loop: -> Orchestrator: capture diffBase -> task-executor: Implementation -> Escalation judgment: - - escalation_needed/blocked -> Escalate to user + - escalation_needed/blocked -> Orchestrator Escalation Resolution - requiresTestReview: true -> integration-test-reviewer with changedTestFiles from filesModified, diffBase, taskFile, and matching skeletonFiles when available from acceptance-test-generator output or task/work-plan references - needs_revision -> Review Revision Convergence (`author`: task-executor/task-executor-frontend; `artifact`: changed test files); on `progression` -> quality-fixer - approved -> quality-fixer - - blocked/unrecognized -> Escalate to user + - blocked/unrecognized -> Orchestrator Escalation Resolution - No issues -> quality-fixer -> quality-fixer: Quality check and fixes with task_file and filesModified - stub_detected -> task-executor/task-executor-frontend: complete implementation -> re-run quality-fixer @@ -312,14 +322,14 @@ Batch approval -> Start autonomous execution mode - No -> code-verifier + security-reviewer: Post-implementation verification - all pass -> Completion report - any fail -> exact ephemeral task path -> layer-appropriate task-executor -> quality-fixer -> re-run all verifiers - - blocked -> Escalate to user + - blocked -> Orchestrator Escalation Resolution ``` ### Conditions for Stopping Autonomous Execution -Stop autonomous execution and escalate to user in the following cases: +Stop autonomous execution and request user input in the following cases: -1. **Escalation from subagent**: When receiving `status: "escalation_needed"` or `status: "blocked"` +1. **Orchestrator resolution requires user input**: Orchestrator Escalation Resolution reaches one of its user-escalation conditions 2. **Requirement change detected**: Any match in requirement change detection checklist 3. **Work-planner update restriction violated**: Requirement changes after task-decomposer starts require overall redesign 4. **User explicitly stops**: Direct stop instruction or interruption @@ -344,7 +354,7 @@ Use the task loop defined in the autonomous execution diagram above. The canonic | security-reviewer | `status` is `approved` or `approved_with_notes` | `status` is `needs_revision` | `status` is `blocked` | Consolidate failed verifier findings into one ephemeral task per required executor and pass each exact task path through its executor and quality-fixer. Re-run both code-verifier and security-reviewer after any verification fix because the fix can invalidate either result. Delete the ephemeral task files after both verifiers pass. -Maximum retry count is 1 verification fix cycle. If any failed verifier still fails after the re-run, escalate to the user. +If any verifier still fails after the re-run, apply Orchestrator Escalation Resolution. ## Main Orchestrator Roles @@ -373,7 +383,7 @@ Maximum retry count is 1 verification fix cycle. If any failed verifier still fa Handoff rules: - Verify generated integration, fixture-e2e, and service-integration-e2e file paths exist before passing them onward -- Escalate only when required outputs are missing without a valid absence reason +- Apply Orchestrator Escalation Resolution only when required outputs are missing without a valid absence reason - Require work-planner to map every carried-forward technical requirement to a covering task or a justified `gap` ## Important Constraints [MANDATORY] diff --git a/.codex/agents/task-decomposer.toml b/.codex/agents/task-decomposer.toml index f4ced1c..aedc638 100644 --- a/.codex/agents/task-decomposer.toml +++ b/.codex/agents/task-decomposer.toml @@ -74,15 +74,20 @@ Decompose tasks based on implementation strategy patterns determined in implemen - **Always include operation verification methods** - Define clear completion criteria (within executor's scope of responsibility) -## Task Size Criteria -- **Small (Recommended)**: 1-2 files -- **Medium (Acceptable)**: 3-5 files -- **Large (Must Split)**: 6+ files +## Task Granularity Criteria -### Judgment Criteria -- Cognitive load: Amount readable while maintaining context (1-2 files is appropriate) -- Reviewability: PR diff within 100 lines (ideal), within 200 lines (acceptable) -- Rollback: Granularity that can be reverted in 1 commit +Create the fewest tasks compatible with autonomous execution. + +Within a phase, merge related Work Plan implementation tasks unless a separate commit is required because: +- A prerequisite must exist before its consumer can execute +- The invoking workflow routes target files to different executor or quality-fixer agents +- An approved artifact requires separate approval, release, deployment, or rollback + +Each task must leave the repository GREEN and complete either an approved outcome or a concrete dependency used by a later task. When one outcome crosses a required boundary, derive the smallest compatible order from approved artifacts and repository patterns; prefer reversible additive transitions. + +When every feasible order would violate an approved decision or require unauthorized irreversible action, return the exact conflict and a recommended resolution to the orchestrator. Preserve generated tasks that do not depend on the conflict. Counts do not create task boundaries. + +Record every source Work Plan task ID on the generated task and propagate all rows mapped to those IDs. ## Workflow @@ -374,15 +379,19 @@ Task 3: [Content] ## Output Format -### Decomposition Completion Report +### Decomposition Result ```markdown -Task Decomposition Complete +Task Decomposition Result +Status: completed | blocked Plan Document: [Filename] Overall Design Document: _overview-[plan-name].md Number of Decomposed Tasks: [Number] +Conflict: [Required when blocked; omit when completed] +Recommendation: [Required when blocked; omit when completed] + Overall Optimization Results: - Common Processing: [Common processing content] - Impact Scope Management: [Boundary settings] @@ -397,7 +406,7 @@ Execution Order: [Recommended execution order considering dependencies] Next Steps: -Please execute decomposed tasks according to the order. +[When completed: execute generated tasks in order. When blocked: return the conflict and recommendation to the orchestrator.] ``` @@ -408,7 +417,8 @@ Please execute decomposed tasks according to the order. - [ ] Common processing identification and shared design - [ ] Task dependencies and execution order clarification - [ ] Impact scope and boundaries definition for each task -- [ ] Appropriate granularity (1-5 files/task) +- [ ] Task boundaries satisfy Task Granularity Criteria +- [ ] Every generated task records its source Work Plan task IDs - [ ] Investigation Targets specified for every task - [ ] Change Category set for bug-fix, regression, state-change, or boundary-change tasks, with adjacent path/boundary owners added to Investigation Targets - [ ] Quality Assurance Mechanisms propagated to relevant tasks when present in the plan header diff --git a/.codex/agents/task-executor-frontend.toml b/.codex/agents/task-executor-frontend.toml index 967b469..c7266f7 100644 --- a/.codex/agents/task-executor-frontend.toml +++ b/.codex/agents/task-executor-frontend.toml @@ -239,7 +239,7 @@ During implementation, apply coding-rules Reference Representativeness before ad 3. **Refine**: Improve readability, accessibility, type safety, and repository-local React conventions while preserving behavior. 4. **Progress Update [MANDATORY]**: Execute the following in sequence (cannot be omitted) 4-1. **Task file**: Change completed item from `[ ]` → `[x]` - 4-2. **Work plan**: Change same item from `[ ]` → `[x]` in corresponding plan in docs/plans/ + 4-2. **Work plan**: Change the corresponding item from `[ ]` → `[x]` in docs/plans/ 4-3. **Overall design document**: Update corresponding item in progress section if exists ※After each Edit execution, proceed to next step 5. **Test Execution**: Run only created tests and confirm they pass @@ -253,6 +253,7 @@ During implementation, apply coding-rules Reference Representativeness before ad ### 4. Completion Processing Task complete when all checkbox items completed and operation verification complete. +After this condition is met, mark every work plan item identified by `Source Plan Tasks` as `[x]`. For research tasks, includes creating deliverable files specified in metadata "Provides" section. ### 5. Return JSON Result @@ -294,35 +295,35 @@ For task/AC/UI Spec/reference core-mechanism sources, set `details.design_doc_ex For core-mechanism violations, put the substitute in `details.actual_situation`, the behavior change in `details.why_cannot_implement`, and the unblock condition in `recommendation`. ```json -{"status":"escalation_needed","reason":"Design Doc deviation","taskName":"[Task name being executed]","details":{"design_doc_expectation":"[Exact quote from relevant Design Doc section]","actual_situation":"[Details of situation actually encountered]","why_cannot_implement":"[Technical reason why cannot implement per Design Doc]","attempted_approaches":["List of solution methods considered for trial"]},"escalation_type":"design_compliance_violation","user_decision_required":true,"suggested_options":["Modify Design Doc to match reality","Implement missing components first","Reconsider requirements and change implementation approach"],"recommendation":"[Specific proposal for most appropriate solution direction]"} +{"status":"escalation_needed","reason":"Design Doc deviation","taskName":"[Task name being executed]","details":{"design_doc_expectation":"[Exact quote from relevant Design Doc section]","actual_situation":"[Details of situation actually encountered]","why_cannot_implement":"[Technical reason why cannot implement per Design Doc]","attempted_approaches":["List of solution methods considered for trial"]},"escalation_type":"design_compliance_violation","suggested_options":["Modify Design Doc to match reality","Implement missing components first","Reconsider requirements and change implementation approach"],"recommendation":"[Specific proposal for most appropriate solution direction]"} ``` #### 2-2. Similar Component Discovery Escalation When discovering similar components/hooks during existing code investigation, escalate in following JSON format: ```json -{"status":"escalation_needed","reason":"Similar component/hook discovered","taskName":"[Task name being executed]","similar_components":[{"file_path":"src/components/ExistingButton/ExistingButton.tsx","component_name":"ExistingButton","similarity_reason":"Same UI pattern, same Props structure","code_snippet":"[Excerpt of relevant component code]","technical_debt_assessment":"high/medium/low/unknown"}],"search_details":{"keywords_used":["component keywords","feature keywords"],"files_searched":15,"matches_found":3},"escalation_type":"similar_component_found","user_decision_required":true,"suggested_options":["Extend and use existing component","Refactor existing component then use","New implementation as technical debt (create ADR)","New implementation (clarify differentiation from existing)"],"recommendation":"[Recommended approach based on existing component analysis]"} +{"status":"escalation_needed","reason":"Similar component/hook discovered","taskName":"[Task name being executed]","similar_components":[{"file_path":"src/components/ExistingButton/ExistingButton.tsx","component_name":"ExistingButton","similarity_reason":"Same UI pattern, same Props structure","code_snippet":"[Excerpt of relevant component code]","technical_debt_assessment":"high/medium/low/unknown"}],"search_details":{"keywords_used":["component keywords","feature keywords"],"files_searched":15,"matches_found":3},"escalation_type":"similar_component_found","suggested_options":["Extend and use existing component","Refactor existing component then use","New implementation as technical debt (create ADR)","New implementation (clarify differentiation from existing)"],"recommendation":"[Recommended approach based on existing component analysis]"} ``` #### 2-3. Investigation Target Not Found Escalation When an Investigation Target file does not exist or the path is stale, escalate in following JSON format: ```json -{"status":"escalation_needed","reason":"Investigation target not found","taskName":"[Task name being executed]","escalation_type":"investigation_target_not_found","missingTargets":[{"path":"[path specified in task file]","searchHint":"[section/function hint if provided, or null]","searchAttempts":["Checked path directly","Searched nearby files with similar names","Reviewed task dependencies for renamed or moved files"]}],"user_decision_required":true,"suggested_options":["Provide the correct file path","Remove this Investigation Target and proceed","Update the task file with current paths"],"recommendation":"[Recommended next step based on what was found]"} +{"status":"escalation_needed","reason":"Investigation target not found","taskName":"[Task name being executed]","escalation_type":"investigation_target_not_found","missingTargets":[{"path":"[path specified in task file]","searchHint":"[section/function hint if provided, or null]","searchAttempts":["Checked path directly","Searched nearby files with similar names","Reviewed task dependencies for renamed or moved files"]}],"suggested_options":["Provide the correct file path","Remove this Investigation Target and proceed","Update the task file with current paths"],"recommendation":"[Recommended next step based on what was found]"} ``` #### 2-4. Dependency Version Uncertain Escalation When repository-wide verification is insufficient to determine the appropriate dependency version, escalate in following JSON format: ```json -{"status":"escalation_needed","reason":"Dependency version uncertain","taskName":"[Task name being executed]","escalation_type":"dependency_version_uncertain","dependency":{"name":"[dependency name]","versionsFound":["list of versions found in repository"],"filesChecked":["file paths where the dependency usage was found"],"ambiguityReason":"[why repository state alone is insufficient]"},"user_decision_required":true,"suggested_options":["Use the majority version already in the repository","Use a different version with explicit rationale","Research the latest stable version and decide after review"]} +{"status":"escalation_needed","reason":"Dependency version uncertain","taskName":"[Task name being executed]","escalation_type":"dependency_version_uncertain","dependency":{"name":"[dependency name]","versionsFound":["list of versions found in repository"],"filesChecked":["file paths where the dependency usage was found"],"ambiguityReason":"[why repository state alone is insufficient]"},"suggested_options":["Use the majority version already in the repository","Use a different version with explicit rationale","Research the latest stable version and decide after review"]} ``` #### 2-5. Binding Decision Violation Escalation When one or more Compliance Checks in the task's Binding Decisions section evaluate to `N` during pre-implementation, or to `N` or `Unknown` during completion, escalate in following JSON format: ```json -{"status":"escalation_needed","reason":"Binding decision violation","taskName":"[Task name being executed]","escalation_type":"binding_decision_violation","phase":"pre_implementation | completion_gate","implementationApproach":"[1-2 sentence summary of the planned or final implementation approach]","failures":[{"source":"[ADR file path with section hint, copied from Source column]","axis":"[Axis value copied from the Axis column]","decision":"[Decision text copied from Decision column]","complianceCheck":"[Compliance Check predicate copied from Compliance Check column]","evaluation":"N | Unknown","rationale":"[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"}],"user_decision_required":true,"suggested_options":["Adjust the implementation plan to satisfy the binding decision","Update the ADR, then update the work plan ADR Bindings and task Binding Decisions","Provide additional context that resolves the Unknown evaluation"]} +{"status":"escalation_needed","reason":"Binding decision violation","taskName":"[Task name being executed]","escalation_type":"binding_decision_violation","phase":"pre_implementation | completion_gate","implementationApproach":"[1-2 sentence summary of the planned or final implementation approach]","failures":[{"source":"[ADR file path with section hint, copied from Source column]","axis":"[Axis value copied from the Axis column]","decision":"[Decision text copied from Decision column]","complianceCheck":"[Compliance Check predicate copied from Compliance Check column]","evaluation":"N | Unknown","rationale":"[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"}],"suggested_options":["Adjust the implementation plan to satisfy the binding decision","Update the ADR, then update the work plan ADR Bindings and task Binding Decisions","Provide additional context that resolves the Unknown evaluation"]} ``` #### 2-6. Test Environment Not Ready Escalation @@ -330,7 +331,7 @@ When one or more Compliance Checks in the task's Binding Decisions section evalu Triggered when the Test Environment Check finds the project-configured test toolchain unavailable or unrunnable. ```json -{"status":"escalation_needed","reason":"Test environment not ready","taskName":"[Task name]","escalation_type":"test_environment_not_ready","missingComponent":"test runner | RTL setup | browser runtime | fixtures | mock server | setup file | other","description":"[why the missing component blocks tests]","user_decision_required":true,"suggested_options":["Install or configure the missing component, then re-run the task","Reassign the task once the environment is ready"]} +{"status":"escalation_needed","reason":"Test environment not ready","taskName":"[Task name]","escalation_type":"test_environment_not_ready","missingComponent":"test runner | RTL setup | browser runtime | fixtures | mock server | setup file | other","description":"[why the missing component blocks tests]","suggested_options":["Install or configure the missing component, then re-run the task","Reassign the task once the environment is ready"]} ``` ## Scope Boundary (delegate to orchestrator) diff --git a/.codex/agents/task-executor.toml b/.codex/agents/task-executor.toml index cafe0f1..a7d0ebc 100644 --- a/.codex/agents/task-executor.toml +++ b/.codex/agents/task-executor.toml @@ -238,7 +238,7 @@ During implementation, apply coding-rules Reference Representativeness before ad 1. **RED**: Write failing test FIRST 2. **GREEN**: Minimal implementation to pass 3. **REFACTOR**: Improve code quality -4. **Progress Update**: `[ ]` → `[x]` in task file, work plan, design doc +4. **Progress Update**: `[ ]` → `[x]` in the task file, corresponding work plan item, and design doc 5. **Verify**: Run created tests **Test types**: Unit tests use RED-GREEN-REFACTOR; integration and fixture-e2e tests are created/executed with implementation; service-integration-e2e tests execute in the final phase; legacy E2E without `@lane` defaults to service-integration-e2e unless the task file or skeleton states mocked backend / fixture-driven execution. @@ -252,6 +252,7 @@ During implementation, apply coding-rules Reference Representativeness before ad ### 4. Completion Processing Task complete when all checkbox items completed and operation verification complete. +After this condition is met, mark every work plan item identified by `Source Plan Tasks` as `[x]`. For research tasks, includes creating deliverable files specified in metadata "Provides" section. ### 5. Return JSON Result @@ -293,35 +294,35 @@ For task/AC/reference core-mechanism sources, set `details.design_doc_expectatio For core-mechanism violations, put the substitute in `details.actual_situation`, the behavior change in `details.why_cannot_implement`, and the unblock condition in `recommendation`. ```json -{"status":"escalation_needed","reason":"Design Doc deviation","taskName":"[Task name being executed]","details":{"design_doc_expectation":"[Exact quote from relevant Design Doc section]","actual_situation":"[Details of situation actually encountered]","why_cannot_implement":"[Technical reason why cannot implement per Design Doc]","attempted_approaches":["List of solution methods considered for trial"]},"escalation_type":"design_compliance_violation","user_decision_required":true,"suggested_options":["Modify Design Doc to match reality","Implement missing components first","Reconsider requirements and change implementation approach"],"recommendation":"[Specific proposal for most appropriate solution direction]"} +{"status":"escalation_needed","reason":"Design Doc deviation","taskName":"[Task name being executed]","details":{"design_doc_expectation":"[Exact quote from relevant Design Doc section]","actual_situation":"[Details of situation actually encountered]","why_cannot_implement":"[Technical reason why cannot implement per Design Doc]","attempted_approaches":["List of solution methods considered for trial"]},"escalation_type":"design_compliance_violation","suggested_options":["Modify Design Doc to match reality","Implement missing components first","Reconsider requirements and change implementation approach"],"recommendation":"[Specific proposal for most appropriate solution direction]"} ``` #### 2-2. Similar Function Discovery Escalation When discovering similar functions during existing code investigation, escalate in following JSON format: ```json -{"status":"escalation_needed","reason":"Similar function discovered","taskName":"[Task name being executed]","similar_functions":[{"file_path":"[path to existing implementation]","function_name":"existingFunction","similarity_reason":"Same domain, same responsibility","code_snippet":"[Excerpt of relevant code]","technical_debt_assessment":"high/medium/low/unknown"}],"search_details":{"keywords_used":["domain keywords","responsibility keywords"],"files_searched":15,"matches_found":3},"escalation_type":"similar_function_found","user_decision_required":true,"suggested_options":["Extend and use existing function","Refactor existing function then use","New implementation as technical debt (create ADR)","New implementation (clarify differentiation from existing)"],"recommendation":"[Recommended approach based on existing code analysis]"} +{"status":"escalation_needed","reason":"Similar function discovered","taskName":"[Task name being executed]","similar_functions":[{"file_path":"[path to existing implementation]","function_name":"existingFunction","similarity_reason":"Same domain, same responsibility","code_snippet":"[Excerpt of relevant code]","technical_debt_assessment":"high/medium/low/unknown"}],"search_details":{"keywords_used":["domain keywords","responsibility keywords"],"files_searched":15,"matches_found":3},"escalation_type":"similar_function_found","suggested_options":["Extend and use existing function","Refactor existing function then use","New implementation as technical debt (create ADR)","New implementation (clarify differentiation from existing)"],"recommendation":"[Recommended approach based on existing code analysis]"} ``` #### 2-3. Investigation Target Not Found Escalation When an Investigation Target file does not exist or the path is stale, escalate in following JSON format: ```json -{"status":"escalation_needed","reason":"Investigation target not found","taskName":"[Task name being executed]","escalation_type":"investigation_target_not_found","missingTargets":[{"path":"[path specified in task file]","searchHint":"[section/function hint if provided, or null]","searchAttempts":["Checked path directly","Searched nearby files with similar names","Reviewed task dependencies for renamed or moved files"]}],"user_decision_required":true,"suggested_options":["Provide the correct file path","Remove this Investigation Target and proceed","Update the task file with current paths"],"recommendation":"[Recommended next step based on what was found]"} +{"status":"escalation_needed","reason":"Investigation target not found","taskName":"[Task name being executed]","escalation_type":"investigation_target_not_found","missingTargets":[{"path":"[path specified in task file]","searchHint":"[section/function hint if provided, or null]","searchAttempts":["Checked path directly","Searched nearby files with similar names","Reviewed task dependencies for renamed or moved files"]}],"suggested_options":["Provide the correct file path","Remove this Investigation Target and proceed","Update the task file with current paths"],"recommendation":"[Recommended next step based on what was found]"} ``` #### 2-4. Dependency Version Uncertain Escalation When repository-wide verification is insufficient to determine the appropriate dependency version, escalate in following JSON format: ```json -{"status":"escalation_needed","reason":"Dependency version uncertain","taskName":"[Task name being executed]","escalation_type":"dependency_version_uncertain","dependency":{"name":"[dependency name]","versionsFound":["list of versions found in repository"],"filesChecked":["file paths where the dependency usage was found"],"ambiguityReason":"[why repository state alone is insufficient]"},"user_decision_required":true,"suggested_options":["Use the majority version already in the repository","Use a different version with explicit rationale","Research the latest stable version and decide after review"]} +{"status":"escalation_needed","reason":"Dependency version uncertain","taskName":"[Task name being executed]","escalation_type":"dependency_version_uncertain","dependency":{"name":"[dependency name]","versionsFound":["list of versions found in repository"],"filesChecked":["file paths where the dependency usage was found"],"ambiguityReason":"[why repository state alone is insufficient]"},"suggested_options":["Use the majority version already in the repository","Use a different version with explicit rationale","Research the latest stable version and decide after review"]} ``` #### 2-5. Binding Decision Violation Escalation When one or more Compliance Checks in the task's Binding Decisions section evaluate to `N` during pre-implementation, or to `N` or `Unknown` during completion, escalate in following JSON format: ```json -{"status":"escalation_needed","reason":"Binding decision violation","taskName":"[Task name being executed]","escalation_type":"binding_decision_violation","phase":"pre_implementation | completion_gate","implementationApproach":"[1-2 sentence summary of the planned or final implementation approach]","failures":[{"source":"[ADR file path with section hint, copied from Source column]","axis":"[Axis value copied from the Axis column]","decision":"[Decision text copied from Decision column]","complianceCheck":"[Compliance Check predicate copied from Compliance Check column]","evaluation":"N | Unknown","rationale":"[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"}],"user_decision_required":true,"suggested_options":["Adjust the implementation plan to satisfy the binding decision","Update the ADR, then update the work plan ADR Bindings and task Binding Decisions","Provide additional context that resolves the Unknown evaluation"]} +{"status":"escalation_needed","reason":"Binding decision violation","taskName":"[Task name being executed]","escalation_type":"binding_decision_violation","phase":"pre_implementation | completion_gate","implementationApproach":"[1-2 sentence summary of the planned or final implementation approach]","failures":[{"source":"[ADR file path with section hint, copied from Source column]","axis":"[Axis value copied from the Axis column]","decision":"[Decision text copied from Decision column]","complianceCheck":"[Compliance Check predicate copied from Compliance Check column]","evaluation":"N | Unknown","rationale":"[One line explaining why the implementation does not satisfy the check, or why it cannot be evaluated]"}],"suggested_options":["Adjust the implementation plan to satisfy the binding decision","Update the ADR, then update the work plan ADR Bindings and task Binding Decisions","Provide additional context that resolves the Unknown evaluation"]} ``` #### 2-6. Test Environment Not Ready Escalation @@ -329,7 +330,7 @@ When one or more Compliance Checks in the task's Binding Decisions section evalu Triggered when the Test Environment Check finds the project-configured test toolchain unavailable or unrunnable. ```json -{"status":"escalation_needed","reason":"Test environment not ready","taskName":"[Task name]","escalation_type":"test_environment_not_ready","missingComponent":"test runner | fixtures | mock server | setup file | other","description":"[why the missing component blocks tests]","user_decision_required":true,"suggested_options":["Install or configure the missing component, then re-run the task","Reassign the task once the environment is ready"]} +{"status":"escalation_needed","reason":"Test environment not ready","taskName":"[Task name]","escalation_type":"test_environment_not_ready","missingComponent":"test runner | fixtures | mock server | setup file | other","description":"[why the missing component blocks tests]","suggested_options":["Install or configure the missing component, then re-run the task","Reassign the task once the environment is ready"]} ``` ## Execution Principles diff --git a/.codex/agents/work-planner.toml b/.codex/agents/work-planner.toml index a6fb9a1..dee75db 100644 --- a/.codex/agents/work-planner.toml +++ b/.codex/agents/work-planner.toml @@ -252,11 +252,11 @@ Include completion conditions in task names (e.g., "Service implementation and u ### Strategy A: Test-Driven Development (when test design information provided) -#### Phase 0: Test Preparation (Unit Tests Only) -Create Red state tests based on unit test definitions provided from previous process. +#### Phase 0: Test Execution Prerequisites (When Required) +Use Phase 0 for independently GREEN test setup or harness artifacts that must exist before a consuming implementation task can execute. **Test Implementation Timing and Placement**: -- Unit tests: Phase 0 Red → Green during implementation +- Unit tests: Include the Red-Green-Refactor cycle in the implementation task that makes the test GREEN - Integration tests: Create and execute at completion of relevant feature implementation (include in phase tasks like "[Feature name] implementation with integration test creation") - fixture-e2e tests: Create and execute alongside the relevant UI feature implementation - service-integration-e2e tests: Execute only in final phase @@ -340,8 +340,8 @@ When an E2E lane generated file is `null` and its `e2eAbsenceReason` is missing: #### Step 4: Classify and Place Tests **Test Classification**: -- Setup items (Mock preparation, measurement tools, Helpers, etc.) → Prioritize in Phase 1 -- Unit tests (individual functions) → Start from Phase 0 with Red-Green-Refactor +- Setup that need not exist before its consumer executes → Include in the consuming implementation task +- Unit tests (individual functions) → Include Red-Green-Refactor in the relevant implementation task - Integration tests → Place as create/execute tasks when relevant feature implementation is complete - fixture-e2e tests → Place as create/execute tasks alongside relevant UI implementation - service-integration-e2e tests → Place as execute-only tasks in final phase when a skeleton exists @@ -350,7 +350,7 @@ When an E2E lane generated file is `null` and its `e2eAbsenceReason` is missing: - Risk levels ("high risk", "required", etc.) → Move to earlier phases **Task Generation Principles**: -- Always decompose 5+ test cases into subtasks (setup/high risk/normal/low risk) +- Within each phase, group implementation, tests, configuration, wiring, and documentation that become GREEN at the same verification point, regardless of count - Specify "X test implementations" in each task (quantify progress) - Specify traceability: Show correspondence with acceptance criteria in "AC1 support (3 items)" format diff --git a/package.json b/package.json index 4739d73..7776097 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "codex-workflows", - "version": "0.9.4", + "version": "0.9.5", "description": "Task-oriented agentic coding framework for OpenAI Codex CLI — skills, recipes, and subagents for structured development workflows", "license": "MIT", "author": "Shinsuke Kagawa",