codex-workflows 0.4.11 → 0.5.0

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

@@ -130,8 +130,12 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    |---|---|
    | 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 |
+   | Frontend component implementation | UI Spec component section cited by the work plan's UI Spec Component -> Task Mapping, interface-defining Design Doc sections, adjacent components |
+   | Frontend integration / fixture-e2e test work | UI Spec component section including state and interaction tables, test skeleton file, target implementation, fixture data, browser harness config |
+   | Integration test work | Test skeleton file, target implementation under test, existing fixture/auth/setup patterns |
+   | fixture-e2e environment/setup work | Existing fixture data, API mock layer, browser harness configuration |
+   | service-integration-e2e environment/setup work | Current environment config, startup scripts, seed scripts, auth flow references, external service stubs |
+   | Cross-boundary implementation | Connection Map rows touching the task target files, caller/producer module, callee/consumer module, expected signal, contract definition |
    | Bug fix/refactor | Affected code paths, failing tests, reproduction-related files |
    | Behavior replacement/rewrite | Existing implementation being replaced, observable outputs, Verification Strategy section in the Design Doc |
 
@@ -140,6 +144,8 @@ Decompose tasks based on implementation strategy patterns determined in implemen
    - 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 the work plan contains a UI Spec Component -> Task Mapping table, propagate matching component sections to every task listed in the row
+   - When the work plan contains a Connection Map, propagate boundary rows touching the task's target files to every task on either side of the boundary
    - When a task matches multiple natures, include Investigation Targets from all matching rows and deduplicate overlaps
 
 7. **Implementation Pattern Consistency**
@@ -185,6 +191,25 @@ When the work plan includes a `Design-to-Plan Traceability` section:
 5. **Verification integrity**: For `verification` rows, ensure the corresponding task file includes the required comparison or verification method in Operation Verification Methods.
 6. **Prerequisite integrity**: For `prerequisite` rows, place setup, migration, seed, auth, or environment work before dependent implementation tasks.
 
+## UI Spec Propagation
+
+When the work plan includes a `UI Spec Component -> Task Mapping` section:
+
+1. For each row, locate the task IDs listed in `Covered By Task(s)`.
+2. Add the component section heading to those task files' Investigation Targets.
+3. Include the states listed in `States to Cover` in Investigation Notes and Operation Verification Methods.
+4. Preserve `gap` rows as planning issues and surface them to the caller.
+5. If a task implements UI but no component mapping row covers it, add a warning in the decomposition report.
+
+## Connection Map Propagation
+
+When the work plan includes a `Connection Map` section:
+
+1. For each boundary row, locate all tasks listed in `Covered By Task(s)`.
+2. Add the caller/producer module, callee/consumer module, serialized contract, and expected signal to each listed task's Investigation Targets or Notes.
+3. For tasks on one side of a boundary, include an Operation Verification Method that observes the expected signal from the other side.
+4. Propagate only boundary rows explicitly mapped in the work plan.
+
 ## Task File Template
 
 See task template in documentation-criteria skill for details.

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

@@ -133,7 +133,9 @@ Use the appropriate run command based on the `packageManager` field in package.j
 
 ### 1. Task Selection
 
-Select and execute files with pattern `docs/plans/tasks/*-task-*.md` that have uncompleted checkboxes `[ ]` remaining
+If the orchestrator prompt provides a task file path, execute only that exact task file. Do not scan or select any other task file.
+
+When no task file path is provided, 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)
@@ -185,7 +187,7 @@ This is a repeated self-check during implementation, not a one-time pre-implemen
 
 **Implementation procedure for each checkbox item**:
 1. **Red**: Create React Testing Library test for that checkbox item (failing state)
-   ※For integration tests (multiple components), create and execute simultaneously with implementation; E2E tests are executed in final phase only
+   ※For integration tests and fixture-e2e tests, create and execute with the related UI implementation; service-integration-e2e tests are executed in final phase only. Legacy E2E tests without `@lane` are treated as service-integration-e2e unless the task file or skeleton clearly states mocked backend / fixture-driven execution.
 2. **Green**: Implement minimum code to pass test (React function component)
 3. **Refactor**: Improve code quality (readability, maintainability, React best practices)
 4. **Progress Update [MANDATORY]**: Execute the following in sequence (cannot be omitted)
@@ -211,16 +213,11 @@ Return one of the following as the final response (see Structured Response Speci
 - `status: "completed"` — task fully implemented
 - `status: "escalation_needed"` — design deviation or similar component discovered
 
-## Research Task Deliverables
-
-Research/analysis tasks create deliverable files specified in metadata "Provides".
-Examples: `docs/plans/analysis/component-research.md`, `docs/plans/analysis/api-integration.md`
-
 ## Structured Response Specification
 
 ### Field Specifications
 
-**requiresTestReview**: Set to `true` when the task added or updated integration tests or E2E tests. Set to `false` for unit-test-only tasks or tasks with no tests.
+**requiresTestReview**: Set to `true` when the task added or updated integration tests, fixture-e2e tests, or service-integration-e2e tests. Set to `false` for unit-test-only tasks or tasks with no tests.
 
 ### 1. Task Completion Response
 Report in the following JSON format upon task completion (**without executing quality checks or commits**, delegating to quality assurance process):
@@ -380,9 +377,6 @@ When repository-wide verification is insufficient to determine the appropriate d
 
 **ENFORCEMENT**: HALT if any gate unchecked. Return `status: "escalation_needed"` to caller.
 
-## Completion Criteria
-
-- [ ] Final response is a single JSON with status `completed` or `escalation_needed`
 """
 
 [[skills.config]]

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

@@ -133,7 +133,9 @@ Skill Status:
 
 ### 1. Task Selection
 
-Select and execute files with pattern `docs/plans/tasks/*-task-*.md` that have uncompleted checkboxes `[ ]` remaining
+If the orchestrator prompt provides a task file path, execute only that exact task file. Do not scan or select any other task file.
+
+When no task file path is provided, 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)
@@ -194,7 +196,9 @@ This is a repeated self-check during implementation, not a one-time pre-implemen
 **Test types**:
 - Unit tests: RED-GREEN-REFACTOR cycle
 - Integration tests: Create and execute with implementation
-- E2E tests: Execute only (in final phase)
+- fixture-e2e tests: Create and execute with the related UI/browser task when the task file specifies that lane
+- service-integration-e2e tests: Execute only in final phase when the task file specifies that lane
+- legacy E2E tests without `@lane`: Treat as service-integration-e2e unless the task file or skeleton clearly states mocked backend / fixture-driven execution
 
 #### Operation Verification
 - Execute "Operation Verification Methods" section in task
@@ -212,16 +216,11 @@ Return one of the following as the final response (see Structured Response Speci
 - `status: "completed"` — task fully implemented
 - `status: "escalation_needed"` — design deviation or similar function discovered
 
-## Research Task Deliverables
-
-Research/analysis tasks create deliverable files specified in metadata "Provides".
-Examples: `docs/plans/analysis/research-results.md`, `docs/plans/analysis/api-spec.md`
-
 ## Structured Response Specification
 
 ### Field Specifications
 
-**requiresTestReview**: Set to `true` when the task added or updated integration tests or E2E tests. Set to `false` for unit-test-only tasks or tasks with no tests.
+**requiresTestReview**: Set to `true` when the task added or updated integration tests, fixture-e2e tests, or service-integration-e2e tests. Set to `false` for unit-test-only tasks or tasks with no tests.
 
 ### 1. Task Completion Response
 Report in the following JSON format upon task completion (**without executing quality checks or commits**, delegating to quality assurance process):
@@ -364,11 +363,9 @@ When repository-wide verification is insufficient to determine the appropriate d
 ```
 
 ## Execution Principles
-
 - Follow RED-GREEN-REFACTOR (see the principles in testing skill)
 - Update progress checkboxes per step
-- Escalate when: design deviation, similar functions found, investigation target not found, test environment missing
-- Escalate when dependency version or representative pattern choice cannot be determined from repository evidence
+- Escalate when design deviation, similar functions, missing investigation targets/test environment, or uncertain dependency/pattern choice blocks repository-evidence-based implementation
 - Stop after implementation and test creation — quality checks and commits are handled separately
 
 ## Completion Gate [BLOCKING]
@@ -383,9 +380,6 @@ When repository-wide verification is insufficient to determine the appropriate d
 
 **ENFORCEMENT**: HALT if any gate unchecked. Return `status: "escalation_needed"` to caller.
 
-## Completion Criteria
-
-- [ ] Final response is a single JSON with status `completed` or `escalation_needed`
 """
 
 [[skills.config]]

package/.codex/agents/technical-designer-frontend.toml

@@ -119,7 +119,7 @@ Must be performed when creating Design Doc:
 1. **Approach Selection Criteria**
    - Execute Phase 1-4 of implementation-approach skill to select strategy
    - **Vertical Slice**: Complete by feature unit, minimal component dependencies, early value delivery
-   - **Horizontal Slice**: Implementation by component layer (Atoms→Molecules→Organisms), important common components, design consistency priority
+   - **Horizontal Slice**: Implementation by the project's component layering convention. Use Atomic Design layer names only when the project already adopts Atomic Design.
    - **Hybrid**: Composite, handles complex requirements
    - Document selection reason (record results of metacognitive strategy selection process)
 
@@ -267,7 +267,7 @@ Implementation sample creation checklist:
 **Design Doc**: Component hierarchy diagram and data flow diagram are mandatory. Add state transition diagram and sequence diagram for complex cases.
 
 **React Diagrams**:
-- Component hierarchy (Atoms → Molecules → Organisms → Templates → Pages)
+- Component hierarchy (use the project's existing component architecture; Atomic Design labels apply only when adopted)
 - Props flow diagram (parent → child data flow)
 - State management diagram (Context, custom hooks)
 - User interaction flow (click → state update → re-render)

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

@@ -43,7 +43,8 @@ Skill Status:
 5. Place test implementation and execution appropriately for each phase
 6. Concretize risks and countermeasures
 7. Create explicit Design-to-Plan Traceability so Design Doc technical requirements are covered without silent omission
-8. Document in progress-trackable format
+8. Propagate UI Spec component and runtime boundary context into the plan so task decomposition can pass it to executors
+9. Document in progress-trackable format
 
 ## Input Parameters
 
@@ -53,8 +54,8 @@ Skill Status:
 - **prd** (optional): Path to PRD document
 - **adr** (optional): Path to ADR document
 - **testSkeletons** (optional): Paths to integration/E2E test skeleton files from acceptance-test-generator
-  - `generatedFiles.e2e` may be `null` when no E2E skeleton is intentionally generated
-  - When provided, carry `e2eAbsenceReason` into the work plan and treat it as an explicit planning input
+  - `generatedFiles.fixtureE2e` and `generatedFiles.serviceE2e` may be `null` when a lane is intentionally not generated
+  - When provided, carry lane-specific `e2eAbsenceReason` into the work plan and treat it as an explicit planning input
 - **updateContext** (update mode only): Path to existing plan, reason for changes
 
 ## Workflow
@@ -86,7 +87,9 @@ Choose Strategy A (TDD) if test skeletons are provided, Strategy B (implementati
 - Place tasks with the lowest dependencies in earlier phases
 - Map normalized verification timing to phases as follows: `phase_1` -> earliest implementation phase, `per_phase` -> each relevant phase, `integration_phase` -> integration phase, `final_phase` -> final Quality Assurance phase
 - Include verification tasks in the phase corresponding to the Verification Strategy timing
-- When test skeletons are provided, place integration test implementation based on `@dependency` metadata from test skeletons (see Test Design Information Processing > Step 2) and place E2E test execution in the final phase
+- When test skeletons are provided, place integration test implementation based on `@dependency` metadata from test skeletons (see Test Design Information Processing > Step 2)
+- When fixture-e2e skeletons are provided, place creation/execution alongside the relevant UI implementation phase
+- When service-integration-e2e skeletons are provided, place execution-only tasks in the final phase
 - When test skeletons are not provided, include test implementation tasks based on Design Doc acceptance criteria
 - Final phase is always Quality Assurance
 
@@ -115,12 +118,37 @@ Traceability rules:
 - Any `gap` without justification is an error
 - Any justified `gap` must be flagged for user confirmation before plan approval
 
+### 5a. Map UI Spec Components to Tasks
+
+When a UI Spec is provided, map each documented component to the task(s) that implement it or test it.
+
+Rules:
+- Use the UI Spec component section heading exactly as written.
+- Identify required states such as default, loading, empty, error, and partial.
+- Record the mapping in the `UI Spec Component -> Task Mapping` table from the plan template.
+- Mark components with no covering task as `gap` with justification and user confirmation before approval.
+
+### 5b. Map Runtime Boundaries to Tasks
+
+When implementation crosses runtime, process, deployment, or service boundaries, create a `Connection Map`.
+
+A boundary qualifies only when all of the following hold:
+- The two sides run in separate processes, services, runtimes, or deployed artifacts.
+- A serialized contract crosses the boundary, such as HTTP, RPC, event payload, queue message, or webhook payload.
+- A failure on one side creates an observable signal on the other side, such as a status code, timeout, missing field, dropped message, or persisted row.
+
+Map only boundaries satisfying all three qualifications above: separate runtime, serialized contract, and observable cross-side signal.
+
+For each boundary, record the caller/producer, callee/consumer, expected signal, and covering tasks in the `Connection Map` table.
+
 ### 6. Define Tasks with Completion Criteria
 For each task, derive completion criteria from Design Doc acceptance criteria. Apply the 3-element completion definition (Implementation Complete, Quality Complete, Integration Complete).
 
 ### 7. Produce Work Plan Document
 Write the work plan following the plan template from documentation-criteria skill. Include Phase Structure Diagram and Task Dependency Diagram (mermaid).
 
+The plan header MUST include `Implementation Readiness: pending`. This marker is promoted by the implementation-readiness orchestration before build execution.
+
 ## Work Plan Output Format
 
 - Storage location and naming convention follow the principles in documentation-criteria skill
@@ -161,7 +189,8 @@ Create Red state tests based on unit test definitions provided from previous pro
 **Test Implementation Timing and Placement**:
 - Unit tests: Phase 0 Red → Green during implementation
 - Integration tests: Create and execute at completion of relevant feature implementation (include in phase tasks like "[Feature name] implementation with integration test creation")
-- E2E tests: Execute only in final phase (execution only, no separate implementation needed)
+- fixture-e2e tests: Create and execute alongside the relevant UI feature implementation
+- service-integration-e2e tests: Execute only in final phase
 
 #### Meta Information Utilization
 Analyze meta information (@category, @dependency, @complexity, etc.) included in test definitions,
@@ -181,6 +210,7 @@ Read available test skeleton files (integration tests, and E2E tests only when p
 
 **Comment patterns to extract**:
 - `// @category:` → Test classification (core-functionality, edge-case, e2e, etc.)
+- `// @lane:` → Test lane (integration, fixture-e2e, service-integration-e2e)
 - `// @dependency:` → Dependent components (material for phase placement decisions)
 - `// @complexity:` → Complexity (high/medium/low, material for effort estimation)
 - `// Value Score:` → Priority judgment
@@ -190,6 +220,7 @@ Read available test skeleton files (integration tests, and E2E tests only when p
 1. **Dependency-based Phase Placement**
    - `// @dependency: none` → Place in earlier phases
    - `// @dependency: [component name]` → Place in phase after dependent component implementation
+   - `// @dependency: full-ui (mocked backend)` → Place alongside UI implementation
    - `// @dependency: full-system` → Place in final phase
 
 2. **Complexity-based Effort Estimation**
@@ -198,32 +229,36 @@ Read available test skeleton files (integration tests, and E2E tests only when p
 
 #### 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:
+When E2E test skeletons are provided, first identify the E2E skeleton subset using file naming conventions such as `*.fixture.e2e.test.*`, `*.service.e2e.test.*`, or `*.e2e.test.*`, 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
+- `@lane: fixture-e2e` or `@dependency: full-ui (mocked backend)` combined with fixture loaders or API mock handlers
 - `@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
+- fixture-e2e fixture data → Add a Phase 0 task for fixture state files
+- fixture-e2e mocked backend → Add a Phase 0 task for the project's API mock layer
+- fixture-e2e browser harness → Add a Phase 0 task for Playwright or the project's browser harness
+- service-integration-e2e seed data → Add a Phase 0 task for seed preparation
+- service-integration-e2e auth fixture/login state → Add a Phase 0 task for auth setup
+- service-integration-e2e external service stubs → Add a Phase 0 task for stubs or intercepts
+- service-integration-e2e environment configuration → Add a Phase 0 task for env vars and local service startup
 - 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.
+Place these setup tasks before implementation and annotate them as E2E setup work with the relevant lane.
 
 #### Step 3a: E2E Absence Handling
 
-When `generatedFiles.e2e` is `null`:
-- Require `e2eAbsenceReason` from the generator output
+When an E2E lane generated file is `null`:
+- Require the corresponding lane-specific `e2eAbsenceReason` from the generator output
 - Record the absence reason in the work plan header
-- Skip E2E prerequisite extraction and E2E execution task creation
-- Accept the null E2E file as a valid planning input when a concrete `e2eAbsenceReason` is present
+- Skip prerequisite extraction and execution task creation for that lane
+- Accept the null E2E lane as a valid planning input when a concrete absence reason is present
 
-When `generatedFiles.e2e` is `null` and `e2eAbsenceReason` is missing:
+When an E2E lane generated file is `null` and its `e2eAbsenceReason` is missing:
 - Flag a planning gap for user confirmation before plan approval
 
 #### Step 4: Classify and Place Tests
@@ -232,7 +267,9 @@ When `generatedFiles.e2e` is `null` and `e2eAbsenceReason` is missing:
 - Setup items (Mock preparation, measurement tools, Helpers, etc.) → Prioritize in Phase 1
 - Unit tests (individual functions) → Start from Phase 0 with Red-Green-Refactor
 - Integration tests → Place as create/execute tasks when relevant feature implementation is complete
-- E2E tests → Place as execute-only tasks in final phase when an E2E skeleton exists
+- 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
+- legacy E2E tests without a lane → Treat as service-integration-e2e unless the skeleton clearly uses mocked backend fixtures
 - Non-functional requirement tests (performance, UX, etc.) → Place in quality assurance phase
 - Risk levels ("high risk", "required", etc.) → Move to earlier phases
 

package/README.md

@@ -27,8 +27,6 @@ $recipe-implement Add user authentication with JWT
 
 Small changes stay lightweight. Larger tasks get structure: requirements → design → task decomposition → TDD implementation → quality gates.
 
-codex-workflows is the Codex-native counterpart of [Claude Code Workflows](https://github.com/shinpr/claude-code-workflows): same document-driven development style, adapted for Codex CLI, subagents, and GPT models.
-
 ---
 
 ## Why codex-workflows?
@@ -159,6 +157,7 @@ Invoke recipes with `$recipe-name` in Codex. Type `$recipe-` and use tab complet
 | `$recipe-task` | Single task with rule selection | Bug fixes, small changes |
 | `$recipe-design` | Requirements → ADR/Design Doc | Architecture planning |
 | `$recipe-plan` | Design Doc → test skeletons → work plan | Planning phase, including nullable E2E skeleton handling |
+| `$recipe-prepare-implementation` | Verify work plan readiness and resolve prep gaps | Pre-build check that the plan is implementable |
 | `$recipe-build` | Execute backend tasks autonomously | Resume backend implementation |
 | `$recipe-review` | Design Doc compliance and security validation with auto-fixes | Post-implementation check |
 | `$recipe-diagnose` | Problem investigation → failure-point verification → solution | Bug investigation |
@@ -182,6 +181,16 @@ Invoke recipes with `$recipe-name` in Codex. Type `$recipe-` and use tab complet
 | `$recipe-fullstack-implement` | Full lifecycle with separate Design Docs per layer | Cross-layer features |
 | `$recipe-fullstack-build` | Execute tasks with layer-aware agent routing | Resume cross-layer implementation |
 
+### Working State
+
+Recipes use `docs/plans/` as ephemeral working state for work plans, decomposed task files, prep tasks, review-fix tasks, and intermediate analysis files. Add it to your project's `.gitignore` unless your team intentionally wants to review those transient files:
+
+```gitignore
+docs/plans/
+```
+
+PRDs, ADRs, UI Specs, and Design Docs are durable project documents and are intended to be committed.
+
 ### Examples
 
 **Full feature development:**
@@ -315,6 +324,7 @@ your-project/
 │   ├── recipe-design/
 │   ├── recipe-build/
 │   ├── recipe-plan/
+│   ├── recipe-prepare-implementation/
 │   ├── recipe-review/
 │   ├── recipe-diagnose/
 │   ├── recipe-task/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-workflows",
-  "version": "0.4.11",
+  "version": "0.5.0",
   "description": "Task-oriented agentic coding framework for OpenAI Codex CLI — skills, recipes, and subagents for structured development workflows",
   "license": "MIT",
   "author": "Shinsuke Kagawa",