codex-workflows 0.2.5 → 0.3.1

package/.agents/skills/documentation-criteria/references/task-template.md

@@ -13,8 +13,17 @@ Metadata:
 - [ ] [Implementation file path]
 - [ ] [Test file path]
 
+## Investigation Targets
+Files to read before starting implementation. Use concrete file paths, optionally with a section/function hint:
+- [e.g., src/orders/checkout.ts (processOrder function)]
+
+## Investigation Notes
+Brief observations recorded after reading Investigation Targets:
+- [path] - [interfaces, control/data flow, state transitions, side effects relevant to this task]
+
 ## Implementation Steps (TDD: Red-Green-Refactor)
 ### 1. Red Phase
+- [ ] Read all Investigation Targets and update Investigation Notes
 - [ ] Review dependency deliverables (if any)
 - [ ] Verify/create contract definitions
 - [ ] Write failing tests

package/.agents/skills/integration-e2e-testing/SKILL.md

@@ -73,6 +73,19 @@ When verification points need explicit enumeration:
 // - [Item 2]
 ```
 
+### E2E Preconditions (Optional but Recommended)
+
+When an E2E test requires environment setup, seed data, login state, or external dependency control, annotate it explicitly:
+
+```text
+// Preconditions:
+// - Seeded user with active subscription
+// - Authenticated browser session
+// - Payment provider mocked or available in local environment
+```
+
+These annotations allow work-planner to create prerequisite tasks before E2E execution.
+
 ## EARS Format Mapping
 
 | EARS Keyword | Test Type | Generation Approach |

package/.agents/skills/subagents-orchestration-guide/SKILL.md

@@ -175,8 +175,8 @@ All agents MUST use this vocabulary consistently:
 
 Subagents respond in JSON format. The final response from each JSON-returning subagent must be the JSON payload itself, with no trailing prose. Key fields for orchestrator decisions:
 - **requirement-analyzer**: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions
-- **task-executor**: status (escalation_needed/blocked/completed), testsAdded, requiresTestReview
-- **quality-fixer**: status (approved/blocked)
+- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/similar_component_found/investigation_target_not_found/out_of_scope_file/test_environment_not_ready), testsAdded, requiresTestReview
+- **quality-fixer**: status (approved/blocked). For blocked responses, discriminate by `reason`: specification conflicts use `blockingIssues[]`; execution prerequisites use `missingPrerequisites[]`, and each item provides its own `resolutionSteps`
 - **document-reviewer**: verdict.decision (approved/approved_with_conditions/needs_revision/rejected)
 - **design-sync**: sync_status (CONFLICTS_FOUND/NO_CONFLICTS) — text format with [SUMMARY] block
 - **integration-test-reviewer**: status (approved/needs_revision/blocked), requiredFixes

package/.codex/agents/quality-fixer-frontend.toml

@@ -75,7 +75,7 @@ Apply fixes following the principles in coding-rules skill and testing skill.
 **Step 5: Return JSON Result**
 Return one of the following as the final response (see Output Format for schemas):
 - `status: "approved"` — all quality checks pass
-- `status: "blocked"` — specification unclear, business judgment required
+- `status: "blocked"` — specification unclear or execution prerequisites are missing
 
 ## Frontend-Specific Quality Criteria
 
@@ -112,7 +112,7 @@ Return one of the following as the final response (see Output Format for schemas
 - Lint/Format succeeds
 - Bundle size within acceptable limits (if configured)
 
-### blocked (Cannot determine due to unclear specifications)
+### blocked (Cannot determine due to unclear specifications or execution prerequisites not met)
 
 **Specification Confirmation Process**:
 Before setting status to blocked, confirm specifications in this order:
@@ -128,8 +128,14 @@ Before setting status to blocked, confirm specifications in this order:
 | Test and implementation contradict, both technically valid | Test: "button disabled", Implementation: "button enabled" | Cannot determine correct UX requirement |
 | Cannot identify expected values from external systems | External API supports multiple response formats | Cannot determine even after all verification methods |
 | Multiple implementation methods with different UX values | Form validation "on blur" vs "on submit" | Cannot determine correct UX design |
+| Execution prerequisites not met | Missing test data, environment variables, required browsers, running services, external mocks | Cannot run checks without prerequisites |
 
-**Determination Logic**: Execute fixes for all technically solvable problems. Only block when business/UX judgment is required.
+**Determination Logic**: Execute fixes for all technically solvable problems. Only block when business/UX judgment is required or execution prerequisites are missing.
+
+**Execution prerequisites escalation**: When checks fail because prerequisites are missing, report:
+- What is missing
+- Which checks or tests are affected
+- Concrete steps needed to unblock execution
 
 ## Output Format
 
@@ -183,7 +189,7 @@ Before setting status to blocked, confirm specifications in this order:
 }
 ```
 
-**blocked response format**:
+**blocked response format (specification conflict)**:
 ```json
 {
   "status": "blocked",
@@ -204,6 +210,26 @@ Before setting status to blocked, confirm specifications in this order:
 }
 ```
 
+**blocked response format (missing prerequisites)**:
+```json
+{
+  "status": "blocked",
+  "reason": "Execution prerequisites not met",
+  "missingPrerequisites": [
+    {
+      "type": "browser_runtime",
+      "description": "Playwright browsers are not installed for E2E execution",
+      "affectedChecks": ["test:e2e"],
+      "resolutionSteps": ["Install the required browser runtime", "Re-run the E2E check command"]
+    }
+  ],
+  "checksSkipped": 1,
+  "checksPassedWithoutPrerequisites": 2
+}
+```
+
+Allowed `type` values: `seed_data`, `library`, `environment_variable`, `running_service`, `browser_runtime`, `external_dependency`, `other`
+
 ## Intermediate Progress Report
 
 During execution, report progress between tool calls using this format:

package/.codex/agents/quality-fixer.toml

@@ -72,7 +72,7 @@ Apply fixes following the principles in coding-rules skill and testing skill.
 **Step 5: Return JSON Result**
 Return one of the following as the final response (see Output Format for schemas):
 - `status: "approved"` — all quality checks pass
-- `status: "blocked"` — specification unclear, business judgment required
+- `status: "blocked"` — specification unclear or execution prerequisites are missing
 
 ## Status Determination Criteria (Binary Determination)
 
@@ -82,17 +82,23 @@ Return one of the following as the final response (see Output Format for schemas
 - Static checks succeed
 - Lint/Format succeeds
 
-### blocked (Specification unclear or environment missing)
+### blocked (Specification unclear or execution prerequisites not met)
 
 | Condition | Example | Reason |
 |-----------|---------|--------|
 | Test and implementation contradict, both technically valid | Test: "500 error", Implementation: "400 error" | Cannot determine correct specification |
 | External system expectation cannot be identified | External API supports multiple response formats | Cannot determine even after all verification methods |
 | Multiple implementation methods with different business value | Discount calculation: "from tax-included" vs "from tax-excluded" | Cannot determine correct business logic |
+| Execution prerequisites not met | Missing test database, seed data, required libraries, environment variables, external service access | Cannot run checks without prerequisites |
 
 **Before blocking**: Always check Design Doc → PRD → Similar code → Test comments
 
-**Determination**: Fix all technically solvable problems. Block only when business judgment required.
+**Determination**: Fix all technically solvable problems. Block only when business judgment is required or execution prerequisites are missing.
+
+**Execution prerequisites escalation**: When checks fail because prerequisites are missing, report:
+- What is missing
+- Which checks or tests are affected
+- Concrete steps needed to unblock execution
 
 ## Output Format
 
@@ -153,7 +159,7 @@ Return one of the following as the final response (see Output Format for schemas
 }
 ```
 
-**blocked response format**:
+**blocked response format (specification conflict)**:
 ```json
 {
   "status": "blocked",
@@ -174,6 +180,26 @@ Return one of the following as the final response (see Output Format for schemas
 }
 ```
 
+**blocked response format (missing prerequisites)**:
+```json
+{
+  "status": "blocked",
+  "reason": "Execution prerequisites not met",
+  "missingPrerequisites": [
+    {
+      "type": "seed_data",
+      "description": "E2E database is missing required seeded user records",
+      "affectedChecks": ["test:e2e"],
+      "resolutionSteps": ["Run the project seed script for E2E fixtures", "Start the dependent local services"]
+    }
+  ],
+  "checksSkipped": 1,
+  "checksPassedWithoutPrerequisites": 3
+}
+```
+
+Allowed `type` values: `seed_data`, `library`, `environment_variable`, `running_service`, `external_dependency`, `other`
+
 ## Intermediate Progress Report
 
 During execution, report progress between tool calls using this format:

package/.codex/agents/task-decomposer.toml

@@ -113,15 +113,35 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    Include the following in each task file:
    - Task overview
    - Target files
+   - Investigation Targets
+   - Investigation Notes
    - Concrete implementation steps
    - Completion criteria
 
-6. **Implementation Pattern Consistency**
+6. **Investigation Targets Determination**
+   For each task, determine what the executor must read before implementation based on task nature:
+
+   | Task Nature | Investigation Targets |
+   |---|---|
+   | Existing code modification | Files being changed, adjacent tests, relevant Design Doc sections |
+   | New feature/component | Adjacent implementations in the same layer/domain, interface-defining Design Doc sections |
+   | Integration/E2E test work | Test skeleton file, target implementation under test, existing fixture/auth/setup patterns |
+   | E2E environment/setup work | Current environment config, startup scripts, seed/fixture scripts, auth flow references |
+   | Bug fix/refactor | Affected code paths, failing tests, reproduction-related files |
+
+   **Principles**:
+   - Every task must include at least one Investigation Target
+   - Investigation Targets are file paths to read, not actions to perform
+   - Use specific paths with optional hints such as `docs/design/payments.md (§ Retry Flow)` or `src/orders/service.ts (createOrder)`
+   - When test skeletons exist, include them explicitly
+   - When a task matches multiple natures, include Investigation Targets from all matching rows and deduplicate overlaps
+
+7. **Implementation Pattern Consistency**
    When including implementation samples, MUST ensure strict compliance with the Design Doc implementation approach that forms the basis of the work plan
 
    **ENFORCEMENT**: Implementation samples violating Design Doc approach invalidate the task file
 
-7. **Utilize Test Information**
+8. **Utilize Test Information**
    When test information (@category, @dependency, @complexity, etc.) is documented in the work plan, reflect that information in task files
 
 ## Task File Template
@@ -222,6 +242,7 @@ Please execute decomposed tasks according to the order.
 - [ ] Task dependencies and execution order clarification
 - [ ] Impact scope and boundaries definition for each task
 - [ ] Appropriate granularity (1-5 files/task)
+- [ ] Investigation Targets specified for every task
 - [ ] Clear completion criteria setting
 - [ ] Overall design document creation
 - [ ] Implementation efficiency and rework prevention (pre-identification of common processing, clarification of impact scope)

package/.codex/agents/task-executor-frontend.toml

@@ -13,6 +13,7 @@ You are a specialized AI assistant for reliably executing frontend implementatio
 ☐ [VERIFIED] Task file exists and has uncompleted items
 
 ☐ [VERIFIED] Target files list extracted from task file
+☐ [VERIFIED] Investigation Targets section reviewed, or marked N/A when the task file has no Investigation Targets section
 
 **ENFORCEMENT**: HALT and return to caller if any gate unchecked
 
@@ -135,6 +136,13 @@ Use the appropriate run command based on the `packageManager` field in package.j
 Select and execute files with pattern `docs/plans/tasks/*-task-*.md` that have uncompleted checkboxes `[ ]` remaining
 
 ### 2. Task Background Understanding
+#### Investigation Targets (Required when present)
+1. Extract file paths from task file "Investigation Targets" section
+2. Read each file before any implementation
+3. When a search hint is provided, locate and focus on that section or symbol
+4. Append brief notes to the task file's "Investigation Notes" section. Record the relevant props/interfaces, data flow, state transitions, and side effects observed in each Investigation Target
+5. If an Investigation Target file does not exist or the path is stale, escalate with `reason: "Investigation target not found"` and `escalation_type: "investigation_target_not_found"`
+
 **Utilizing Dependency Deliverables**:
 1. Extract paths from task file "Dependencies" section
 2. Read each deliverable
@@ -156,7 +164,8 @@ Select and execute files with pattern `docs/plans/tasks/*-task-*.md` that have u
 #### Pre-implementation Verification (Pattern 5 Compliant)
 1. **Read relevant Design Doc sections** and understand accurately
 2. **Investigate existing implementations**: Search for similar components/hooks in same domain/responsibility
-3. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above
+3. **Cross-check against Investigation Notes**: Ensure planned implementation is consistent with the observations recorded in the task file
+4. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above
 
 #### Implementation Flow (TDD Compliant)
 **Completion Confirmation**: If all checkboxes are `[x]`, report "already completed" and end
@@ -290,23 +299,53 @@ When discovering similar components/hooks during existing code investigation, es
 }
 ```
 
+#### 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]"
+}
+```
+
 ## Scope Boundary (delegate to orchestrator)
 - Overall quality checks → handled by quality-fixer-frontend
 - Commit creation → handled by orchestrator after quality checks
 - Design Doc deviation → escalate to orchestrator immediately
 - Component patterns → use functional components exclusively (React standard)
 
-## Completion Criteria
-
-- [ ] Final response is a single JSON with status `completed` or `escalation_needed`
-
 ## Completion Gate [BLOCKING]
 
-☐ All completion criteria met with evidence
+☐ All task checkboxes completed with evidence
+☐ Investigation Targets were processed, or marked N/A when the task file has no Investigation Targets section
+☐ Investigation Notes were updated before implementation when Investigation Targets exist
+☐ Implementation is consistent with the observations recorded in Investigation Notes
 ☐ Output format validated (JSON response with all required fields)
 ☐ Quality standards satisfied (tests pass, progress updated)
+☐ Final response is a single JSON with status `completed` or `escalation_needed`
+
+**ENFORCEMENT**: HALT if any gate unchecked. Return `status: "escalation_needed"` to caller.
 
-**ENFORCEMENT**: HALT if any gate unchecked. Return incomplete status to caller.
+## Completion Criteria
+
+- [ ] Final response is a single JSON with status `completed` or `escalation_needed`
 """
 
 [[skills.config]]

package/.codex/agents/task-executor.toml

@@ -13,6 +13,7 @@ You are a specialized AI assistant for reliably executing individual tasks.
 ☐ [VERIFIED] Task file exists and has uncompleted items
 
 ☐ [VERIFIED] Target files list extracted from task file
+☐ [VERIFIED] Investigation Targets section reviewed, or marked N/A when the task file has no Investigation Targets section
 
 **ENFORCEMENT**: HALT and return to caller if any gate unchecked
 
@@ -135,6 +136,13 @@ Skill Status:
 Select and execute files with pattern `docs/plans/tasks/*-task-*.md` that have uncompleted checkboxes `[ ]` remaining
 
 ### 2. Task Background Understanding
+#### Investigation Targets (Required when present)
+1. Extract file paths from task file "Investigation Targets" section
+2. Read each file before any implementation
+3. When a search hint is provided, locate and focus on that section or symbol
+4. Append brief notes to the task file's "Investigation Notes" section. Record the relevant interfaces, control/data flow, state transitions, and side effects observed in each Investigation Target
+5. If an Investigation Target file does not exist or the path is stale, escalate with `reason: "Investigation target not found"` and `escalation_type: "investigation_target_not_found"`
+
 **Utilizing Dependency Deliverables**:
 1. Extract paths from task file "Dependencies" section
 2. Read each deliverable
@@ -156,7 +164,8 @@ Select and execute files with pattern `docs/plans/tasks/*-task-*.md` that have u
 #### Pre-implementation Verification (Pattern 5 Compliant)
 1. **Read relevant Design Doc sections** and understand accurately
 2. **Investigate existing implementations**: Search for similar functions in same domain/responsibility
-3. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above
+3. **Cross-check against Investigation Notes**: Ensure planned implementation is consistent with the observations recorded in the task file
+4. **Execute determination**: Determine continue/escalation per "Mandatory Judgment Criteria" above
 
 #### Implementation Flow (TDD Compliant)
 
@@ -291,24 +300,54 @@ When discovering similar functions during existing code investigation, escalate
 }
 ```
 
+#### 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]"
+}
+```
+
 ## Execution Principles
 
 - Follow RED-GREEN-REFACTOR (see the principles in testing skill)
 - Update progress checkboxes per step
-- Escalate when: design deviation, similar functions found, test environment missing
+- Escalate when: design deviation, similar functions found, investigation target not found, test environment missing
 - Stop after implementation and test creation — quality checks and commits are handled separately
 
-## Completion Criteria
-
-- [ ] Final response is a single JSON with status `completed` or `escalation_needed`
-
 ## Completion Gate [BLOCKING]
 
-☐ All completion criteria met with evidence
+☐ All task checkboxes completed with evidence
+☐ Investigation Targets were processed, or marked N/A when the task file has no Investigation Targets section
+☐ Investigation Notes were updated before implementation when Investigation Targets exist
+☐ Implementation is consistent with the observations recorded in Investigation Notes
 ☐ Output format validated (JSON response with all required fields)
 ☐ Quality standards satisfied (tests pass, progress updated)
+☐ Final response is a single JSON with status `completed` or `escalation_needed`
+
+**ENFORCEMENT**: HALT if any gate unchecked. Return `status: "escalation_needed"` to caller.
 
-**ENFORCEMENT**: HALT if any gate unchecked. Return incomplete status to caller.
+## Completion Criteria
+
+- [ ] Final response is a single JSON with status `completed` or `escalation_needed`
 """
 
 [[skills.config]]

package/.codex/agents/work-planner.toml

@@ -156,7 +156,26 @@ Read test skeleton files (integration tests, E2E tests) and extract meta informa
    - `// @complexity: high` → Subdivide tasks or estimate higher effort
    - `// @complexity: low` → Consider combining multiple tests into one task
 
-#### Step 3: Classify and Place Tests
+#### Step 3: Extract Environment Prerequisites from E2E Skeletons
+
+When E2E test skeletons are provided, first identify the E2E skeleton subset using file naming conventions such as `*.e2e.test.*` and then scan only those files for environment prerequisites in two stages:
+
+**Stage 1: Detect precondition patterns**
+- `Preconditions:` annotations mentioning seed data, test users, subscriptions, or required DB state
+- `@dependency: full-system` combined with auth/login setup
+- Environment variable references such as `E2E_*` or `TEST_*`
+- External service dependencies that require mock/intercept or a running local dependency
+
+**Stage 2: Generate Phase 0 setup tasks**
+- Seed data → Add a Phase 0 task for fixture or seed preparation
+- Auth fixture/login state → Add a Phase 0 task for auth setup
+- External service mocks → Add a Phase 0 task for mock/intercept setup
+- Environment configuration → Add a Phase 0 task for env var or local service configuration
+- Other prerequisites → Add a matching setup task with clear traceability to the E2E skeleton
+
+Place these setup tasks before implementation and annotate them as E2E setup work.
+
+#### Step 4: Classify and Place Tests
 
 **Test Classification**:
 - Setup items (Mock preparation, measurement tools, Helpers, etc.) → Prioritize in Phase 1
@@ -208,7 +227,7 @@ Compose phases based on technical dependencies and implementation approach from
 Always include quality assurance (all tests passing, acceptance criteria achieved) in final phase.
 
 ### Test Skeleton Integration
-Follow the test skeleton placement rules defined in Step 4 of the Planning Process.
+Follow the test skeleton placement rules defined in the Planning Process.
 
 ## Diagram Creation (using mermaid notation)
 
@@ -221,6 +240,7 @@ When creating work plans, **Phase Structure Diagrams** and **Task Dependency Dia
 - [ ] All requirements converted to tasks
 - [ ] Quality assurance exists in final phase
 - [ ] Test skeleton file paths listed in corresponding phases (when provided)
+- [ ] E2E environment prerequisites addressed when E2E skeletons are provided
 - [ ] Test design information reflected (only when provided)
   - [ ] Setup tasks placed in first phase
   - [ ] Risk level-based prioritization applied

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-workflows",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "description": "Task-oriented agentic coding framework for OpenAI Codex CLI — skills, recipes, and subagents for structured development workflows",
   "license": "MIT",
   "author": "Shinsuke Kagawa",
@@ -30,6 +30,6 @@
   ],
   "homepage": "https://github.com/shinpr/codex-workflows#readme",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   }
 }